Skip to content

feat: a third navigation target, for a diagram whose file nobody wrote - #38

Merged
endrix merged 1 commit into
feat/producer-declared-render-hooksfrom
feat/authored-source-navigation
Sep 4, 2026
Merged

endrix merged 1 commit into
feat/producer-declared-render-hooksfrom
feat/authored-source-navigation

Conversation

@endrix

@endrix endrix commented Sep 3, 2026

Copy link
Copy Markdown
Owner

Stacked on #37. Review that one first; this branch contains only the second commit.

cal:referencedUri answers two questions at once — drill into this element and show me its source — and that works for exactly as long as both have the same answer.

For a diagram generated from something else they come apart:

  • drilling has to stay inside the generated file, because that is where the definitions being drilled into live;
  • "show me the source" wants the file a person actually typed.

One slot means picking which of the two features to break. A consumer that hit this picked drill-down and lost source navigation entirely — every "Go to Source" landed in a machine-generated file, or, when pointed at the authored one instead, every element double-click became an attempt to open a source file as a diagram.

So a producer that knows both files can now say both: meta.authoredSource becomes its own pair of keys (cal:authoredUri, cal:authoredSourceRange) and its own context-menu item, Go to Authored Source. The existing two targets are untouched.

Neutrality

Nothing here names a language or a toolchain. Any product with a generation step between what someone wrote and what the diagram is built from has exactly this shape; the platform only learns that such a step can exist. 4/4 gates pass.

Two deliberate refusals

No fallback. The other two targets fall through to the diagram's own file, because there a missing range still means "somewhere in this document". Here an absent value means the producer made no such claim, and offering the generated file under a label that says authored misrepresents which file the reader is being sent to.

Both a file and a line are required. A half-populated locator navigates to the top of a file nobody asked for, which is worse than not offering the item at all.

Compatibility

Inert for every existing product: no authoredSource, no keys, no third menu item. The full platform suite passes unchanged.

Verification

  • 5 new tests in authored-source.test.ts, including one asserting that an authored file does not become the drill-down target — the property the whole change exists to preserve
  • Full platform suite, 4/4 neutrality gates, build

@endrix
endrix force-pushed the feat/authored-source-navigation branch from 6709ee8 to a623e54 Compare September 3, 2026 16:42
@endrix
endrix force-pushed the feat/producer-declared-render-hooks branch from b5b61b2 to 7e9d234 Compare September 3, 2026 18:50
`cal:referencedUri` answers two questions at once — drill into this element,
and show me its source — and that works only for as long as both have the same
answer. For a diagram generated from something else they come apart. Drilling
has to stay inside the generated file, because that is where the definitions
being drilled into live; "show me the source" wants the file a person actually
typed. One slot means picking which of the two features to break, and the
consumer that hit this picked drill-down and lost source navigation entirely.

So a producer that knows both files can now say both: `meta.authoredSource`
becomes its own pair of keys and its own context-menu item, and the existing two
targets are untouched.

Nothing here names a language or a toolchain. Any product with a compile step
between what someone wrote and what the diagram is built from has this shape;
the platform only learns that such a step can exist.

Two deliberate refusals in the implementation. The authored target does NOT
fall back to the diagram's own file the way the other two do — there, a missing
range still means "somewhere in this document", whereas an absent authored file
means the producer made no such claim, and offering the generated file under
that label would misrepresent which file the reader is being sent to. And both
a file and a line are required, because a half-populated locator navigates to
the top of a file nobody asked for, which is worse than not offering the item.

For every existing product this is inert: no `authoredSource`, no keys, no third
menu item, and 850 tests plus all four neutrality gates pass unchanged.
@endrix
endrix force-pushed the feat/authored-source-navigation branch from a623e54 to f8df462 Compare September 3, 2026 18:51
@endrix
endrix merged commit c9e6af3 into feat/producer-declared-render-hooks Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant