@liminis/editor 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,7 +5,7 @@ import { $isLinkNode } from '@lexical/link';
5
5
  import { $createHorizontalRuleNode, $createImageNode, $isImageNode, $createCalloutNode, $createToggleContainerNode, $createToggleTitleNode, $createToggleContentNode, $createEquationNode, $isEquationNode, $createFootnoteNode, $isFootnoteNode, $createBlockAnchorNode, $isBlockAnchorNode, $createHtmlNode, $isHtmlNode, $createMermaidNode, $createC4Node, $createFrontmatterNode, $createCustomLinkNode, $createCustomListNode, $createDefinitionListNode, $createDefinitionTermNode, $createDefinitionDescriptionNode, $createCustomListItemNode, $createListItemParagraphBreakNode, $createTransclusionNode, } from '../editor/nodes/index.js';
6
6
  import { parseFormattedAlias } from '../editor/MarkdownShortcutsPlugin.js';
7
7
  import { $createTableNode, $createTableRowNode, $createTableCellNode, TableCellHeaderStates } from '@lexical/table';
8
- import { getFileType } from '../../utils/file-types.js';
8
+ import { wikiTargetToUrl, wikiLinkTargetToUrl } from '../../utils/file-types.js';
9
9
  // Set only while a *WithOffsets import is running, so convertText/convertInlineCode
10
10
  // can record spans without threading a collector parameter through every one of
11
11
  // this file's many recursive conversion functions. Lexical updates run their
@@ -271,7 +271,7 @@ function convertBlockNode(node) {
271
271
  const wikiLink = node;
272
272
  const target = wikiLink.value || '';
273
273
  const rawDisplayText = wikiLink.data?.alias || target;
274
- const url = getFileType(target) !== 'unknown' ? target : `${target}.md`;
274
+ const url = wikiTargetToUrl(target);
275
275
  const paragraph = $createParagraphNode();
276
276
  const link = $createCustomLinkNode(url);
277
277
  link.setWikiLinkOrigin(true);
@@ -861,35 +861,9 @@ function convertInlineNode(node) {
861
861
  return [$createTextNode('[[]]')];
862
862
  }
863
863
  const displayText = wikiLink.data?.alias || target;
864
- // Convert to URL, preserving semantic intent
865
- // Directory links (trailing slash) are preserved - navigation layer resolves them
866
- // Example: [[entities/people/]] → stays as entities/people/ (resolved to index.md at navigation time)
867
- let url;
868
- if (target.startsWith('#')) {
869
- // Anchor-only: #anchor → #anchor
870
- url = target;
871
- }
872
- else if (target.endsWith('/')) {
873
- // Directory link: preserve trailing slash for semantic clarity
874
- // Navigation layer will resolve to index.md or README.md
875
- url = target;
876
- }
877
- else if (target.includes('#')) {
878
- // Path with anchor: page#anchor → page.md#anchor (or dir/#anchor preserved)
879
- const [path, anchor] = target.split('#', 2);
880
- if (path.endsWith('/')) {
881
- // Directory with anchor - preserve for navigation layer
882
- url = target;
883
- }
884
- else {
885
- const pathWithExt = getFileType(path) !== 'unknown' ? path : `${path}.md`;
886
- url = `${pathWithExt}#${anchor}`;
887
- }
888
- }
889
- else {
890
- // Simple path: page → page.md (unless it already has a recognized extension)
891
- url = getFileType(target) !== 'unknown' ? target : `${target}.md`;
892
- }
864
+ // Convert to URL, preserving semantic intent (anchor, directory and
865
+ // extension handling live in wikiLinkTargetToUrl)
866
+ const url = wikiLinkTargetToUrl(target);
893
867
  const link = $createCustomLinkNode(url);
894
868
  // Marks this link as genuine author-written wiki-link syntax, so export
895
869
  // (convertLinkNode) always emits it back as a wiki-link even when a host
package/dist/styles.css CHANGED
@@ -717,6 +717,30 @@ body {
717
717
  font-weight: 600;
718
718
  }
719
719
 
720
+ /* Source badge (#192): trailing "↗" that navigates to the transcluded block.
721
+ It reuses `.editor-link` so the `modifier-held` / `links-clickable` cursor
722
+ rules apply unchanged; the rules below only size it down and cancel the
723
+ shared link hover underline/opacity, which look wrong on a lone glyph. */
724
+ .editor-transclusion-wrap {
725
+ display: inline;
726
+ }
727
+
728
+ .editor-transclusion-source {
729
+ margin-inline-start: 0.25em;
730
+ font-size: 0.75em;
731
+ line-height: 1;
732
+ vertical-align: super;
733
+ user-select: none;
734
+ }
735
+
736
+ .editor-link.editor-transclusion-source,
737
+ .editor-link.editor-transclusion-source:hover,
738
+ .modifier-held .editor-link.editor-transclusion-source:hover,
739
+ .links-clickable .editor-link.editor-transclusion-source:hover {
740
+ text-decoration: none;
741
+ opacity: 1;
742
+ }
743
+
720
744
  /* Tables */
721
745
  .editor-table {
722
746
  width: 100%;
@@ -2653,6 +2677,11 @@ body {
2653
2677
  text-decoration: underline !important;
2654
2678
  }
2655
2679
 
2680
+ /* The source badge is a lone glyph; an underline reads as noise in print */
2681
+ .editor-link.editor-transclusion-source {
2682
+ text-decoration: none !important;
2683
+ }
2684
+
2656
2685
  /* Tables */
2657
2686
  .editor-table {
2658
2687
  page-break-inside: auto !important;
@@ -8,3 +8,19 @@ export type FileType = 'markdown' | 'image' | 'pdf' | 'mermaid' | 'code' | 'rema
8
8
  * @returns The detected file type
9
9
  */
10
10
  export declare function getFileType(path: string | null): FileType;
11
+ /**
12
+ * Normalise a wiki-link / transclusion target to the URL form carried on a
13
+ * link node: a target with a recognised extension is kept as-is, anything else
14
+ * gets `.md` appended (`[[page]]` -> `page.md`). Shared by the mapper and the
15
+ * transclusion renderer so `[[file#^id]]` and `![[file#^id]]` hand the host the
16
+ * same `url` shape.
17
+ */
18
+ export declare function wikiTargetToUrl(target: string): string;
19
+ /**
20
+ * Full wiki-link target -> URL derivation, covering the anchor and directory
21
+ * forms the bare {@link wikiTargetToUrl} does not: `#anchor` and `dir/` are
22
+ * kept, `page#anchor` becomes `page.md#anchor`. Shared by the mapper's inline
23
+ * wiki-link conversion and the transclusion renderer's nested links, so a link
24
+ * inside transcluded content navigates to the same URL as a top-level one.
25
+ */
26
+ export declare function wikiLinkTargetToUrl(target: string): string;
@@ -44,3 +44,34 @@ export function getFileType(path) {
44
44
  return 'code';
45
45
  return 'unknown';
46
46
  }
47
+ /**
48
+ * Normalise a wiki-link / transclusion target to the URL form carried on a
49
+ * link node: a target with a recognised extension is kept as-is, anything else
50
+ * gets `.md` appended (`[[page]]` -> `page.md`). Shared by the mapper and the
51
+ * transclusion renderer so `[[file#^id]]` and `![[file#^id]]` hand the host the
52
+ * same `url` shape.
53
+ */
54
+ export function wikiTargetToUrl(target) {
55
+ return getFileType(target) !== 'unknown' ? target : `${target}.md`;
56
+ }
57
+ /**
58
+ * Full wiki-link target -> URL derivation, covering the anchor and directory
59
+ * forms the bare {@link wikiTargetToUrl} does not: `#anchor` and `dir/` are
60
+ * kept, `page#anchor` becomes `page.md#anchor`. Shared by the mapper's inline
61
+ * wiki-link conversion and the transclusion renderer's nested links, so a link
62
+ * inside transcluded content navigates to the same URL as a top-level one.
63
+ */
64
+ export function wikiLinkTargetToUrl(target) {
65
+ // Anchor-only (#anchor) and directory links (trailing slash) are preserved;
66
+ // the navigation layer resolves directories to index.md / README.md.
67
+ if (target.startsWith('#') || target.endsWith('/'))
68
+ return target;
69
+ if (target.includes('#')) {
70
+ const [path, anchor] = target.split('#', 2);
71
+ // Directory with anchor: preserve for the navigation layer
72
+ if (path.endsWith('/'))
73
+ return target;
74
+ return `${wikiTargetToUrl(path)}#${anchor}`;
75
+ }
76
+ return wikiTargetToUrl(target);
77
+ }
@@ -157,6 +157,13 @@ block content" (FR-015 — any `^id`-carrying block is a valid target, not
157
157
  just checkboxes) without committing to full visual parity for every mdast
158
158
  construct.
159
159
 
160
+ > **Amended 2026-11-13 — the "inert link text" part of this clause no longer
161
+ > holds.** A `wikiLink` inside transcluded content now renders as a live
162
+ > anchor, and every transclusion carries a trailing "↗" source badge that
163
+ > navigates to its own source block. See ADR-192
164
+ > (`adr-192-transclusion-source-affordance.md`). The renderer is still partial
165
+ > and still render-only; only link navigation changed.
166
+
160
167
  ### 9. `openLink` gets an additive optional `blockId` parameter
161
168
 
162
169
  A host that has not implemented block-aware navigation still receives
@@ -0,0 +1,103 @@
1
+ # ADR-192: Transclusions Navigate to Their Source Through a Trailing Badge
2
+
3
+ **Date:** 2026-11-13
4
+ **Status:** Accepted
5
+ **Supersedes:** none
6
+ **Amends:** ADR-119 (§8, nested link navigation)
7
+ **Issue:** #192 (verveguy/liminis-editor)
8
+
9
+ ## Context
10
+
11
+ `![[file#^id]]` transclusion (ADR-119, #119) renders the referenced block
12
+ inline, but the rendered output was a dead end: only `<span>`s, no `<a>`, so
13
+ `LinkClickPlugin` — which reacts to `a[data-href]` — never saw anything to
14
+ follow. A `[[file#^id]]` link was navigable; the same block embedded was not.
15
+
16
+ The block-scoped `OPEN_LINK { url, blockId }` path already exists (ADR-119 §9),
17
+ so the only missing piece was a link-shaped element on the transclusion.
18
+
19
+ ## Decision
20
+
21
+ ### 1. A trailing "↗" badge, not a whole-container link
22
+
23
+ Every transclusion renders `<a class="editor-link editor-transclusion-source"
24
+ data-href data-block-id>↗</a>` after its state span, in all four states
25
+ (resolved, unresolved, circular, depth-exceeded). It is a *sibling* of the
26
+ content, never an ancestor of it, so:
27
+
28
+ - `target.closest('a')` in `LinkClickPlugin` always finds the innermost anchor:
29
+ a wiki link inside the transcluded content wins over the badge, with no
30
+ `stopPropagation` ordering to maintain;
31
+ - no `<a>`-in-`<a>`;
32
+ - caret placement and selection inside the transcluded text are untouched.
33
+
34
+ `LinkClickPlugin`, `TransclusionNode`, `exportDOM` and the mdast round-trip are
35
+ unchanged. The badge is presentation only.
36
+
37
+ ### 2. The badge carries `editor-link` but not `data-wiki-link`
38
+
39
+ `editor-link` makes the existing `modifier-held` / `links-clickable` cursor
40
+ rules apply with no new cursor CSS. `data-wiki-link` is deliberately absent:
41
+ `WikiLinkExistencePlugin` queries `a[data-wiki-link="true"]` and would resolve
42
+ the badge and could style it as a broken link.
43
+
44
+ ### 3. `data-href` is normalised exactly as a wiki link is
45
+
46
+ `wikiTargetToUrl(target)` (in `src/utils/file-types.ts`) appends `.md` to a
47
+ target without a recognised extension. The mapper's duplicated expressions now
48
+ call it too. A host that handles block-scoped links therefore receives the same
49
+ `url` shape from `![[x#^id]]` as from `[[x#^id]]`.
50
+
51
+ ### 4. Nested wiki links in transcluded content are now live
52
+
53
+ ADR-119 §8 left `wikiLink` inside transcluded content as inert text. That had to
54
+ change: with a badge present but nested links inert, the requirement that a
55
+ nested link navigate to *its own* target would pass vacuously. They render as
56
+ `<a class="editor-link" data-href data-block-id?>`, again without
57
+ `data-wiki-link` (the existence plugin only walks the editor's own DOM, and
58
+ resolver calls per nested link are not wanted).
59
+
60
+ ### 5. The badge renders from props, not from resolved state
61
+
62
+ `TransclusionComponent` passes `{ file, blockId }` from its props, so the badge
63
+ is present and stable across debounced re-resolves. It is absent only in the
64
+ loading state, which is not one of the four states in scope. A nested
65
+ `wikiEmbed` passes its own `{ file, blockId }`, so each level navigates to its
66
+ own source.
67
+
68
+ ### 6. `contenteditable="false"` and accessible name
69
+
70
+ The badge is `contenteditable="false"` so the caret does not land inside it. It
71
+ has `title` and `aria-label` "Open source block". It has no `href` or
72
+ `tabindex`, matching every other editor link, so keyboard activation is
73
+ whatever existing links support (nothing new).
74
+
75
+ ## Consequences — what this costs
76
+
77
+ - **An always-present "↗" glyph** in transclusions, including editable mode.
78
+ Existing transclusions grow by one small element; a host that screenshots or
79
+ styles transclusions will see it. It can be restyled or hidden via
80
+ `.editor-transclusion-source` without changing the emitted event.
81
+ - **A larger click target in read-only mode.** A plain click on the badge
82
+ navigates there, where previously nothing did. Nested wiki links in
83
+ transcluded content also now navigate on click, which they never did.
84
+ - **A small `contenteditable="false"` island** inside editable content, next to
85
+ an inline decorator. It was verified in jsdom (a plain click is not
86
+ default-prevented and does not navigate) but not in a real browser, where
87
+ caret behaviour around inline decorators is Lexical's and the browser's call.
88
+ - **Not keyboard-focusable.** Consistent with existing links, but it means the
89
+ affordance is pointer-only until links gain `tabindex`/`href` generally.
90
+ - **The whole transclusion is not a link target.** Clicking the transcluded text
91
+ still does nothing; only the badge navigates. That was a design choice, and a
92
+ whole-container target can be added later without changing the event.
93
+ - **Unresolved/circular/depth-exceeded states pass the block id along.** The
94
+ host may ignore it if the block no longer exists; the file still opens, which
95
+ is what a user repairing a broken reference needs.
96
+ - **Not done: making the transcluded checkbox writable** (#181) and host-side
97
+ scroll-to-block (shadoworg/liminis-notes#1318).
98
+
99
+ ## References
100
+
101
+ - ADR-119 — transclusion node and renderer (§8 amended, §9 reused)
102
+ - ADR-122 — block-anchor badge (visual vocabulary)
103
+ - Issue #192 (this ADR), #119 (transclusion), #181 (one logical item)
@@ -0,0 +1,101 @@
1
+ # ADR-194: C4 Manual Positions Are Merged at the Hand-Edit Commit, Not Cleared
2
+
3
+ **Date:** 2026-11-15
4
+ **Status:** Accepted
5
+ **Supersedes:** none
6
+ **Amends:** none
7
+ **Issue:** #194 (verveguy/liminis-editor)
8
+
9
+ ## Context
10
+
11
+ `@liminis/diagrams` 0.2.0 lets a user add elements and relationships on the
12
+ rendered C4 diagram. The renderer reports `onEdit(edit, { positions })`; the
13
+ host turns the edit into source with `applyC4Edit` and stores the reported
14
+ `positions`, which is the complete, already-merged map.
15
+
16
+ The C4 node could not adopt this. `C4Component` had an effect ("TASK 7") that
17
+ cleared the whole manual layout whenever the set of element ids differed from
18
+ the layout's keys. Adding one box from the diagram changes that set, so every
19
+ position the user had arranged would have been discarded the moment they added
20
+ something.
21
+
22
+ ## Decision
23
+
24
+ ### 1. A diagram edit replaces code and layout in one `editor.update`
25
+
26
+ `handleEdit` reads the source from the **node** (never from component state,
27
+ which lags by a render), calls `applyC4Edit`, and on success calls
28
+ `setCode(result.source)` and `setManualLayout({ positions: context.positions })`
29
+ in the same update. One update is one history entry, so a single undo restores
30
+ both. `context.positions` is stored as received: not filtered, not merged with
31
+ the old layout. On `{ ok: false }` nothing is mutated, so there is no history
32
+ entry; `code` and `message` are logged with `console.warn`.
33
+
34
+ ### 2. A hand edit merges at the commit, in the same update as `setCode`
35
+
36
+ The only point where a hand edit reaches the Lexical node is `onHide`
37
+ (`node.setCode(codeValue)`). The merge runs there: `mergeManualLayout` keeps the
38
+ positions of ids still present in the parsed source and any reserved `__` key
39
+ (such as `__legend__`), and drops the rest. It is a no-op (same object) when
40
+ nothing is dropped, and yields `undefined` when nothing is left. A source that
41
+ fails to parse, or parses with errors, never drops anything. An unchanged close
42
+ no longer dirties the node.
43
+
44
+ ### 3. The display renders from a `{ code, manualLayout }` snapshot
45
+
46
+ `C4DiagramDisplay` reads both from the node together, in its initial state and in
47
+ `registerUpdateListener`, instead of taking `code` from a prop that is synced in
48
+ an effect. A diagram edit or undo/redo therefore never renders new positions
49
+ against old code (the "visible jump" the diagrams recipe warns about).
50
+
51
+ ### Alternatives rejected
52
+
53
+ - **An effect that merges when ids change.** It can run with the new layout
54
+ (containing the just-placed id) before the new code reaches the display, see an
55
+ id absent from the parsed diagram, and drop the position it was meant to keep.
56
+ Undo and redo have the same ordering problem. Telling diagram-originated
57
+ changes from hand edits with a ref flag is order-dependent and fragile.
58
+
59
+ ## Consequences — what this costs
60
+
61
+ - **The layout is no longer cleared on an id-set change.** A hand-added element
62
+ is auto-placed beside existing pinned ones, and the result may not look as
63
+ tidy as a full re-layout did. "Reset to auto layout" remains the way to start
64
+ over.
65
+ - **A renamed id loses its position.** The old id is dropped and the new id has
66
+ none; the merge cannot tell a rename from a remove plus an add.
67
+ - **Clearing the source drops every position.** An empty source parses cleanly
68
+ with zero elements, so all positions go. Only a parse that fails, or reports
69
+ errors, is protected.
70
+ - **`setCode` callers other than the editor commit are not covered.** The merge
71
+ lives in `onHide`, not in `C4Node.setCode`. Anything else that later changes a
72
+ C4 node's code (a host, an import, collaboration) must merge the layout itself
73
+ or leave stale positions for removed ids. Stale keys are harmless to rendering
74
+ (the layout ignores unknown ids) but are written to the `@layout` fence meta
75
+ until the next hand edit prunes them. `C4Node` was deliberately not given this
76
+ logic: it must not import `@liminis/diagrams` statically (ADR-075, ADR-079).
77
+ - **Structural editing is only available in layout-edit mode.** The
78
+ interactive renderer is only mounted while the user is editing layout, and the
79
+ renderer shows its add affordances only in edit mode.
80
+ - **Hand-edit merging is validated against `parseC4` element ids**, which include
81
+ boundaries and nested elements (covered by tests). Whether the renderer keys
82
+ boundary positions identically was checked against the 0.2.0 type
83
+ declarations, not against a rendered diagram.
84
+
85
+ > **Amended 2026-11-16 — structural editing now shows one context menu.** The
86
+ > clause "Structural editing is only available in layout-edit mode" still holds,
87
+ > but trying the first version by hand showed that layout mode opened two
88
+ > overlapping menus: the renderer's own add-element menu and the editor's
89
+ > `DiagramContextMenu` (the renderer called `preventDefault()` but not
90
+ > `stopPropagation()`, so the event also reached the container's
91
+ > `onContextMenu`). `@liminis/diagrams` 0.2.1 added an `onContextMenu` hook that
92
+ > hands the host the diagram's items instead of drawing a menu. The C4 node now
93
+ > passes it and renders **one** `DiagramContextMenu`, with the diagram's items
94
+ > (elements, then boundaries) as their own groups above the editor's items; over
95
+ > a node the diagram offers none, so only the editor's items show. A long-press
96
+ > opens the same menu. Choosing an item calls the item's `select()`, so
97
+ > placement, the label prompt, `onEdit` and the single undo step are the
98
+ > diagram's own. The cost: the menu's look is now the editor's, not the
99
+ > renderer's, and the editor depends on `@liminis/diagrams` >= 0.2.1 (the hook
100
+ > is opt-in; without it the renderer's behaviour is unchanged). Guarded by
101
+ > `C4Component.contextmenu.test.tsx`, which uses the real renderer.
@@ -0,0 +1,188 @@
1
+ # ADR-203: The C4 Node Cancels the Release Shift by Measuring It, Not from `onFrameChange`
2
+
3
+ **Date:** 2026-11-15
4
+ **Status:** Accepted
5
+ **Supersedes:** none
6
+ **Amends:** none
7
+ **Issue:** #203 (verveguy/liminis-editor)
8
+
9
+ ## Context
10
+
11
+ `@liminis/diagrams` 0.2.0 (its ADR-100) grows the C4 diagram's SVG frame live while
12
+ a node is dragged past an edge. During the drag the renderer holds the diagram's
13
+ origin steady with an imperative `svg.style.transform`; on release it clears that
14
+ transform and the origin jumps to the natural origin of the larger frame. The
15
+ library leaves cancelling that jump to the host.
16
+
17
+ The editor's C4 node wraps the renderer in a flex-centred, `overflow-x: auto`
18
+ container. So on release the diagram jumps by the full growth for top/left growth,
19
+ and by half the growth for growth on any horizontal side (centring). The user sees
20
+ the node they just dropped move away from the pointer.
21
+
22
+ ## Decision
23
+
24
+ `C4DiagramDisplay` (`src/app/editor/nodes/C4Component.tsx`) measures the jump and
25
+ cancels it with a host-owned offset on the diagram's `<svg>`:
26
+
27
+ 1. `onPositionChange` is called by the renderer synchronously at release, before the
28
+ transform is cleared, and not at all for a cancelled drag. The handler records the
29
+ svg's `getBoundingClientRect()` and bumps a render tick, so the component
30
+ re-renders in the same batch as the renderer's release render.
31
+ 2. A no-dependency `useLayoutEffect` runs after the renderer's own (child) layout
32
+ effect. Once `style.transform` is empty it measures the svg again and adds
33
+ `before − after` to a per-instance offset.
34
+ 3. The offset is written as the CSS `translate` property (`svg.style.translate`),
35
+ which composes with the renderer's `transform` and which the renderer never
36
+ writes. The write happens in the layout phase, so no frame is painted with the
37
+ jump in it.
38
+ 4. The offset resets when layout mode exits. The container also gets
39
+ `overflow-anchor: none` so scroll anchoring cannot add a second adjustment.
40
+
41
+ Because the shift is measured rather than computed from the growth, one mechanism
42
+ covers left, top, right (the centring half-growth), corners, several sides in one
43
+ drag, net growth smaller than the peak, a container that was already scrolled, and
44
+ growth deferred to release by the renderer's 48px cap. A drag that does not grow
45
+ the frame measures zero and writes nothing.
46
+
47
+ ### Why `onFrameChange` is not used (the FR-005 reason)
48
+
49
+ `onFrameChange` reports `{ width, height }` in unscaled diagram units. It carries no
50
+ origin and no per-side growth, so it cannot tell a left-edge growth (which moves the
51
+ origin) from a right-edge one; it carries no drag or release signal; and it is silent
52
+ while the growth cap holds the frame, which is exactly when growth is deferred to
53
+ release. It could at most say that the width changed. The quantity that moves the
54
+ dropped node on screen is the origin's screen position, so that is what is measured.
55
+
56
+ ### The 48px growth cap
57
+
58
+ The cap applies only when the rendered scale differs from the drag-start scale
59
+ (zoom-to-fit) and the pointer is within 48px of the scroll container's edge. This
60
+ editor never passes `zoom`, so the cap cannot engage here today. If it ever does,
61
+ the deferred growth lands at release and goes through the same measure-and-cancel
62
+ path, which a unit test simulates. A test also asserts that `zoom` is not passed, so a
63
+ later zoom-to-fit change fails it and sends the next person back here.
64
+
65
+ ## Alternatives rejected
66
+
67
+ - **Adjust `scrollLeft`.** It only has range when the content overflows. A diagram
68
+ narrower than its container (the common case) cannot be corrected by scrolling, and
69
+ `scrollTop` cannot go negative for top growth.
70
+ - **A wrapper `<div>` with `transform`.** It would become the flex item, so
71
+ `.c4-renderer svg { max-width: 100% }` would resolve against an auto-width wrapper
72
+ and change diagram sizing on entering layout mode.
73
+ - **Drop the centring.** Users rely on it, and it would not cancel the top/left shift.
74
+ - **Use `getScreenCTM()` for the measurement.** The renderer's own code notes that
75
+ engines have been inconsistent about whether it includes CSS transforms. The bounding
76
+ rect always does.
77
+
78
+ ## Cost
79
+
80
+ - After a frame-growing drag the diagram stays off-centre by the cancelled shift until
81
+ layout mode is exited. That is deliberate: where the user dropped the node is what counts.
82
+ - Nothing is un-clipped. The offset reproduces the pre-release visual state, so
83
+ content pushed outside the container's scrollable area during the drag stays
84
+ clipped, as it was during the drag.
85
+ - The fix depends on library internals: the transform being cleared in a child layout
86
+ effect, `onPositionChange` firing synchronously at release and not on cancel, and
87
+ the renderer not writing `style.translate`. The unit tests lock the ordering with a
88
+ fake renderer that mirrors it. The Electron e2e (`examples/electron/e2e/c4-release-shift.spec.ts`)
89
+ measures real Chromium geometry to 1px and fails when the compensation is removed.
90
+ - `onFrameChange` stays unused.
91
+
92
+ > **Amended 2026-11-16 — the translate-only approach no longer holds for vertical
93
+ > growth (issue #206).** A translate is visual only, so the container's layout box
94
+ > does not grow with it. For top growth the cancelling translate moved the grown
95
+ > strip above the container's top edge, and the container clips there
96
+ > (`overflow-x: auto` makes its computed `overflow-y` clip too, and it has only `1rem`
97
+ > of padding). A node dropped partly above the top ended up mostly hidden, which is
98
+ > worse than the jump this ADR removed. What changed:
99
+ >
100
+ > - **Measurement is unchanged** (the svg's bounding rect before and after release).
101
+ > Only how the measured shift is applied changes.
102
+ > - **Vertical: no translate at all.** The container grows with the frame, and the
103
+ > shift is cancelled by scrolling the nearest vertically scrolling ancestor
104
+ > (`scrollContainerFor`, ADR-088, else the document) by the measured amount, with
105
+ > `behavior: 'instant'`. The browser clamps to the scroll range, so with no range (a
106
+ > short, non-scrolling document) or only a partial range the remainder is accepted as
107
+ > a visible shift. A visible jump is better than clipped content.
108
+ > - **Horizontal: scroll first, then a guarded translate.** If the container's content
109
+ > overflows, its `scrollLeft` absorbs the shift. Whatever remains (all of it when
110
+ > nothing overflows, the centred common case) is a translate, clamped so the svg
111
+ > stays inside the container's padding box. If the svg is wider than the box, or the
112
+ > translate would otherwise clip, the shift is accepted instead. The host offset is
113
+ > now x-only.
114
+ > - **`justify-content: safe center`** replaces `center` on the container. With plain
115
+ > centring an overflowing svg overflows equally both ways and the left half cannot be
116
+ > scrolled to, so left growth could not be recovered with `scrollLeft`.
117
+ > - `overflow-anchor: none` stays, so scroll anchoring adds no second adjustment.
118
+ >
119
+ > **The "Alternatives rejected" scroll option is revisited.** It was rejected because a
120
+ > narrow, centred diagram has no horizontal range and `scrollTop` cannot go negative.
121
+ > Neither holds for vertical growth once the container grows: the content is pushed
122
+ > down, so the *ancestor* has range to scroll down into. Horizontal scrolling is still
123
+ > only possible when the content overflows, which is why the translate remains there.
124
+ >
125
+ > **The "Cost" clause "Nothing is un-clipped" no longer holds.** The cost now is a
126
+ > visible shift wherever compensation cannot be done without clipping: a non-scrolling
127
+ > (or exhausted) vertical scroller, or a horizontal drop so close to the container edge
128
+ > that the grown frame cannot be translated back inside it. The e2e measured the
129
+ > latter: the svg frame carries about 40px of empty margin around the nodes, so a drop
130
+ > within that margin of the container's edge shifts a few pixels even though the node
131
+ > itself would still fit. The guard cannot tell frame from content, so it errs towards
132
+ > not clipping.
133
+ > The e2e now also asserts the dropped node's whole box lies inside the visible area
134
+ > (viewport and every clipping ancestor), and fails if the container clips it.
135
+
136
+ > **Amended 2026-11-17 — compensation is now live, through `@liminis/diagrams`
137
+ > 0.2.2 (issue #206, liminis-diagrams#110); the release-time translate is gone.**
138
+ > The 2026-11-16 amendment fixed the clipping at release, but hand testing in the
139
+ > demo with every frame of a drag recorded showed the four edges still differed
140
+ > *during* the drag. Down and right grow the box and nothing clips (past the right
141
+ > edge the svg shrinks to fit, `.c4-renderer svg { max-width: 100% }`). Up and left,
142
+ > the renderer held the origin with a CSS `transform` (liminis-diagrams ADR-100),
143
+ > which paints the grown strip outside the svg's layout box, so the container
144
+ > clipped it: the dragged node vanished above the top, and past the left edge the
145
+ > drawing spilled about 300px beyond the container. Correcting only at release
146
+ > cannot fix a frame that is already clipped. The release-time `translate` also left
147
+ > residual horizontal offsets (seen: -98px and +78px), so the diagram drifted off
148
+ > centre. What changed:
149
+ >
150
+ > - **`holdOrigin={false}`.** The host opts out of the hold transform, so the svg's
151
+ > layout box is always the whole drawing and all four edges behave alike. Bumps
152
+ > `@liminis/diagrams` to `^0.2.2`.
153
+ > - **Live, every frame, through `onOriginShift({ dx, dy })`.** The renderer reports
154
+ > the displacement since the previous commit from a layout effect (before paint,
155
+ > only during a drag, with the reverse shift on a cancel). The host scrolls the
156
+ > nearest vertical scroller (`scrollContainerFor`, else the document) by `dy`, and
157
+ > the container by `dx`. Top growth now opens upward the way bottom growth opens
158
+ > downward, and other nodes do not move on screen wherever the scroller has range.
159
+ > With no range the shift is accepted rather than clipped.
160
+ > - **Left and right need no compensation in practice.** The svg shrinks to fit, so
161
+ > the container has no horizontal range, the `dx` scroll is a no-op, and the diagram
162
+ > re-centres symmetrically.
163
+ > - **`unabsorbedShiftRef`.** Browsers snap a scroll position to whole pixels, and a
164
+ > range can clamp it. The unabsorbed part is carried into the next frame, so
165
+ > rounding cannot accumulate (the e2e measured a 2.5px drift of untouched nodes
166
+ > without it) and a reverse shift unwinds exactly what was scrolled. It is reset on
167
+ > release; whatever it holds then is the accepted shift.
168
+ > - **Removed:** the release snapshot, the layout effect, the host `translate` and its
169
+ > accumulated offset, and the clamp that guarded it. The svg now carries no
170
+ > `transform` or `translate` at any time, so an out-and-back drag leaves nothing
171
+ > behind. `justify-content: safe center` and `overflow-anchor: none` stay.
172
+ >
173
+ > **This supersedes the 2026-11-16 amendment's horizontal clauses** ("scroll first,
174
+ > then a guarded translate", the x-only host offset); its vertical clauses stand,
175
+ > with the scroll now applied live rather than at release. The measurement clause
176
+ > ("the compensation is measured from the svg's rect before and after release") also
177
+ > no longer holds: the renderer reports the shift, so nothing is measured. That
178
+ > removes the dependence on library internals listed under "Cost" (the transform
179
+ > cleared in a child layout effect, `onPositionChange` ordering): the contract is now
180
+ > the documented `onOriginShift` API.
181
+ >
182
+ > **Cost.** Where the vertical scroller has no range (a short, non-scrolling
183
+ > document) the diagram shifts as it grows at the top, instead of staying put; a
184
+ > jump beats clipped content. Dropping a layout-mode drag that is not covered by the
185
+ > renderer's own frame (`zoom` and the 48px growth cap, which this editor never
186
+ > engages) is unchanged. The e2e now checks every frame of a drag, at every edge and
187
+ > corner and out and back, that the dragged node lies inside the container's visible
188
+ > box, and it fails if the hold transform is switched back on.