@liminis/editor 0.6.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.
@@ -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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liminis/editor",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "//publishing": "Publishing is deliberate, never incidental. `private: true` was this package's guard until verveguy/liminis-editor#39 took the publish decision; it is gone because that decision was taken, not because it was tidied away. The guard is now `prepublishOnly` -> scripts/guard-publish.mjs, which refuses unless LIMINIS_ALLOW_PUBLISH=1 is set explicitly. That variable is set at step scope in .github/workflows/publish.yml and nowhere else, so a release is the only path that publishes. Note that `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), which is why the guard is a script rather than a flag.",
5
5
  "license": "MIT",
6
6
  "description": "Lexical-based markdown WYSIWYG editor with mdast round-trip and a host-injection seam",
@@ -81,88 +81,89 @@
81
81
  "build:examples": "node scripts/build-examples.mjs",
82
82
  "build:site": "node scripts/build-site.mjs"
83
83
  },
84
- "//peerDependencies": "Ranges are the compatibility contract, not the tested matrix. CI resolves one point version per range (currently react 19.2.x latest and lexical 0.49.x latest), so every caret range here has an untested lower half — narrowing `react` to the devDependency's `^19.2.5` would not change that, it would only reject working consumers. The react floor is not a claim, it is enforced: `tests/package-manifest-contract.test.ts` (\"imports no React API newer than the declared 19.2.0 peer floor\") scans every source file for post-19.0 named imports — `useEffectEvent`, `Activity`, `cacheSignal`, `ViewTransition`, `captureOwnerStack` — and fails if one appears. Reaching for a newer API therefore breaks CI until you raise the floor here too, which is the pairing this note would otherwise only assert. Raise a floor when the code actually starts needing a later API, not to mirror whatever CI happened to install. This reasoning does not extend to the Lexical ranges below — see `//lexicalPeerPolicy`.",
84
+ "//peerDependencies": "Ranges are the compatibility contract, not the tested matrix. CI resolves one point version per range (currently react 19.3.x latest and lexical 0.53.x latest), so every caret range here has an untested lower half — narrowing `react` to the devDependency's `^19.3.0` would not change that, it would only reject working consumers. The react floor is not a claim, it is enforced: `tests/package-manifest-contract.test.ts` (\"imports no React API newer than the declared 19.2.0 peer floor\") scans every source file for post-19.0 named imports — `useEffectEvent`, `Activity`, `cacheSignal`, `ViewTransition`, `captureOwnerStack` — and fails if one appears. Reaching for a newer API therefore breaks CI until you raise the floor here too, which is the pairing this note would otherwise only assert. Raise a floor when the code actually starts needing a later API, not to mirror whatever CI happened to install. This reasoning does not extend to the Lexical ranges below — see `//lexicalPeerPolicy`.",
85
85
  "//lexicalPeerPolicy": "The twelve Lexical ranges are a single-caret bump per Lexical minor actually adopted and tested here, not a wide multi-version band. `react`'s untested lower half (above) is safe because a break there would be a bug in a stable major; Lexical is `0.x`, where every minor is permitted to break, so a wide band would claim compatibility with untested, potentially-breaking releases. Widening a range later is patch-safe; narrowing one is breaking — so this stays narrow by default and moves forward only when the code is actually run against the new minor. See docs/decisions/adr-92-lexical-peer-range-policy.md.",
86
86
  "peerDependencies": {
87
- "@lexical/code": "^0.49.0",
88
- "@lexical/code-prism": "^0.49.0",
89
- "@lexical/link": "^0.49.0",
90
- "@lexical/list": "^0.49.0",
91
- "@lexical/mark": "^0.49.0",
92
- "@lexical/markdown": "^0.49.0",
93
- "@lexical/react": "^0.49.0",
94
- "@lexical/rich-text": "^0.49.0",
95
- "@lexical/selection": "^0.49.0",
96
- "@lexical/table": "^0.49.0",
97
- "@lexical/utils": "^0.49.0",
98
- "lexical": "^0.49.0",
87
+ "@lexical/code": "^0.53.0",
88
+ "@lexical/code-prism": "^0.53.0",
89
+ "@lexical/link": "^0.53.0",
90
+ "@lexical/list": "^0.53.0",
91
+ "@lexical/mark": "^0.53.0",
92
+ "@lexical/markdown": "^0.53.0",
93
+ "@lexical/react": "^0.53.0",
94
+ "@lexical/rich-text": "^0.53.0",
95
+ "@lexical/selection": "^0.53.0",
96
+ "@lexical/table": "^0.53.0",
97
+ "@lexical/utils": "^0.53.0",
98
+ "lexical": "^0.53.0",
99
99
  "react": "^19.2.0",
100
100
  "react-dom": "^19.2.0"
101
101
  },
102
+ "//mdast-util-to-markdown": "Pinned exactly, not a caret, and deliberately so. From 2.1.3 it leaves `_` unescaped when both neighbours are neither whitespace nor punctuation (`a_b`), and two places hand it a stand-in character instead of the real neighbour. (1) stringify.ts serialises a force-escaped character (#17) through a placeholder; that was private-use U+E004, which classifies as a word character, so an underscore typed next to a preserved escape went out bare and `a \\\\_b c_\\\\ d` re-parsed as emphasis. FIXED: the placeholder is now U+2BFF, a symbol, as the backslash it stands for is punctuation; the tests 'underscores beside force-escaped characters' in src/markdown/__tests__/stringify.test.ts cover it. (2) STILL OPEN: annotate mode splices sentinel tokens (U+E000-E003, annotate-sentinels.ts) into text, and those classify as word characters too, so a `_` at a mark boundary goes out bare where the plain export escapes it. That breaks the #970 invariant that annotate output differs from a plain export only by its tokens; fixtures 17-typed-underscore-after-inline-node and 17-escaped-backslash-then-underscore fail annotated-serialize-corpus.test.ts on 2.1.3+. Unlike the placeholder, a sentinel stands in for no character, so no fixed codepoint class is right. Move past 2.1.2 only once annotate mode keeps its tokens out of the library's view of neighbours and that suite passes.",
102
103
  "dependencies": {
103
- "@liminis/diagrams": "^0.1.5",
104
+ "@liminis/diagrams": "^0.2.2",
104
105
  "@mathjax/src": "^4.1.1",
105
- "lucide-react": "^1.11.0",
106
- "mdast-util-definition-list": "^2.0.0",
107
- "mdast-util-from-markdown": "^2.0.3",
106
+ "lucide-react": "^1.70.0",
107
+ "mdast-util-definition-list": "^2.0.1",
108
+ "mdast-util-from-markdown": "^2.1.0",
108
109
  "mdast-util-frontmatter": "^2.0.1",
109
110
  "mdast-util-gfm": "^3.1.0",
110
111
  "mdast-util-gfm-footnote": "^2.1.0",
111
112
  "mdast-util-math": "^3.0.0",
112
- "mdast-util-to-markdown": "^2.1.2",
113
- "mermaid": "^11.14.0",
114
- "micromark-extension-definition-list": "^2.0.1",
113
+ "mdast-util-to-markdown": "2.1.2",
114
+ "mermaid": "^12.3.0",
115
+ "micromark-extension-definition-list": "^2.0.2",
115
116
  "micromark-extension-frontmatter": "^2.0.0",
116
117
  "micromark-extension-gfm": "^3.0.0",
117
118
  "micromark-extension-gfm-footnote": "^2.1.0",
118
119
  "micromark-extension-math": "^3.1.0",
119
120
  "micromark-extension-wiki-link": "^0.0.4",
120
121
  "prismjs": "^1.30.0",
121
- "yaml": "^2.8.3",
122
- "zod": "^4.3.6",
123
- "zustand": "^5.0.12"
122
+ "yaml": "^2.9.1",
123
+ "zod": "^4.6.7",
124
+ "zustand": "^5.1.0"
124
125
  },
125
126
  "devDependencies": {
126
127
  "@eslint/js": "^10.0.1",
127
- "@lexical/code": "^0.49.0",
128
- "@lexical/code-prism": "^0.49.0",
129
- "@lexical/link": "^0.49.0",
130
- "@lexical/list": "^0.49.0",
131
- "@lexical/mark": "^0.49.0",
132
- "@lexical/markdown": "^0.49.0",
133
- "@lexical/react": "^0.49.0",
134
- "@lexical/rich-text": "^0.49.0",
135
- "@lexical/selection": "^0.49.0",
136
- "@lexical/table": "^0.49.0",
137
- "@lexical/utils": "^0.49.0",
138
- "@testing-library/react": "^16.3.2",
128
+ "@lexical/code": "^0.53.0",
129
+ "@lexical/code-prism": "^0.53.0",
130
+ "@lexical/link": "^0.53.0",
131
+ "@lexical/list": "^0.53.0",
132
+ "@lexical/mark": "^0.53.0",
133
+ "@lexical/markdown": "^0.53.0",
134
+ "@lexical/react": "^0.53.0",
135
+ "@lexical/rich-text": "^0.53.0",
136
+ "@lexical/selection": "^0.53.0",
137
+ "@lexical/table": "^0.53.0",
138
+ "@lexical/utils": "^0.53.0",
139
+ "@testing-library/react": "^16.3.3",
139
140
  "@types/mdast": "^4.0.4",
140
- "@types/node": "^25.6.0",
141
- "@types/react": "^19.2.14",
142
- "@types/react-dom": "^19.2.3",
143
- "@vitejs/plugin-react": "^6.0.1",
144
- "@vitest/coverage-v8": "^4.1.5",
141
+ "@types/node": "^24.19.2",
142
+ "@types/react": "^19.3.0",
143
+ "@types/react-dom": "^19.3.0",
144
+ "@vitejs/plugin-react": "^6.3.0",
145
+ "@vitest/coverage-v8": "^5.1.0",
145
146
  "diff": "^9.0.0",
146
- "eslint": "^10.2.1",
147
+ "eslint": "^10.14.0",
147
148
  "eslint-plugin-react-hooks": "^7.1.1",
148
- "eslint-plugin-react-refresh": "^0.5.2",
149
- "globals": "^17.5.0",
150
- "happy-dom": "^20.9.0",
151
- "lexical": "^0.49.0",
152
- "react": "^19.2.5",
153
- "react-dom": "^19.2.5",
154
- "semver": "^7.8.5",
155
- "tsc-alias": "^1.9.1",
149
+ "eslint-plugin-react-refresh": "^0.5.7",
150
+ "globals": "^17.14.0",
151
+ "happy-dom": "^21.0.4",
152
+ "lexical": "^0.53.0",
153
+ "react": "^19.3.1",
154
+ "react-dom": "^19.3.1",
155
+ "semver": "^7.8.6",
156
+ "tsc-alias": "^1.9.10",
156
157
  "typescript": "^6.0.3",
157
- "typescript-eslint": "^8.59.0",
158
- "vitest": "^4.1.5"
158
+ "typescript-eslint": "^8.72.2",
159
+ "vitest": "^5.1.0"
159
160
  },
160
161
  "repository": {
161
162
  "type": "git",
162
- "url": "git+https://github.com/verveguy/liminis-editor.git"
163
+ "url": "git+https://github.com/liminisapp/liminis-editor.git"
163
164
  },
164
165
  "bugs": {
165
- "url": "https://github.com/verveguy/liminis-editor/issues"
166
+ "url": "https://github.com/liminisapp/liminis-editor/issues"
166
167
  },
167
- "homepage": "https://github.com/verveguy/liminis-editor#readme"
168
+ "homepage": "https://github.com/liminisapp/liminis-editor#readme"
168
169
  }