@liminis/editor 0.1.0-rc.1

package/docs/decisions/adr-079.md

@@ -0,0 +1,167 @@
+# ADR-079: A Seventh Export Subpath, `./nodes`, for the Headless Mapper
+
+**Date:** 2026-08-07
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** ADR-075 (adds a seventh export subpath to the surface ADR-077 had already widened to six)
+**Issue:** #954
+
+## Context
+
+`@liminis/editor` already exported the markdown↔Lexical mapper functions
+(`importMarkdownToLexical`, `exportLexicalToMdast`) from the root barrel, but
+not the Lexical node classes — or the aggregate array of them — the production
+editor configures its `LexicalComposer` with. The mapper instantiates those
+node classes directly (`$createHeadingNode`, `$createCalloutNode`, …) and
+Lexical throws at runtime if a `createEditor` isn't registered with every node
+type an update tries to create. Without the array, a consumer could not build
+a working headless editor and therefore could not exercise the mapper at all
+without mounting the full `<Editor>` component — pulling in MathJax, Mermaid
+and Prism for a test that needs none of them.
+
+The array itself already existed, as an unexported `const editorNodes` local
+to `Editor.tsx`. The package's own test suite had worked around the gap by
+hand-maintaining a second copy in `roundtrip-test-utils.ts`, with a comment
+noting it had to be kept "matching Editor.tsx" — a live instance of the exact
+drift risk this ADR closes, silently depended on by roughly fifteen other
+internal test files.
+
+The issue's own text suggested `./contract` or `./markdown` as candidate
+homes. Both are ruled out by their own documented and tested isolation
+contracts: `./markdown`'s file header states "do not add anything to this
+entry whose import graph reaches Lexical, React, MathJax, or the C4
+subsystem," and `./contract`'s entire purpose is the zod host-message shapes
+alone, consumed via `import type` specifically to avoid pulling in Lexical.
+`./headless`'s own docstring is equally explicit that nothing there "may
+transitively import Lexical," and `./annotations` (ADR-077) is contractually
+Lexical-free, enforced by its own static-graph test. None of the six subpaths
+declared as of ADR-077 is a legitimate home for a Lexical node array.
+
+## Decision
+
+**Extract the shared node array, and add a seventh declared subpath,
+`./nodes`, carrying both it and the mapper functions.**
+
+### The array moves to its own module
+
+`editorNodes` is extracted from `Editor.tsx` into
+`packages/editor/src/app/editor/editorNodes.ts`. `Editor.tsx`'s
+`LexicalComposer` and the new public export both import this one array —
+neither holds its own copy. `roundtrip-test-utils.ts`'s hand-maintained
+duplicate is deleted and replaced with an import of the same module, closing
+the internal drift risk the array's own comment already flagged. Wherever the
+production editor's node set changes, both consumers see the change with no
+second list to edit — this is what makes the export "derived from the
+editor's own configuration" rather than a snapshot of it.
+
+### A seventh, considered subpath: `./nodes`
+
+ADR-075 fixed the surface at five subpaths and permitted adding a *considered*
+export when no existing one fits; ADR-077 exercised that rule once already for
+`./annotations`. This is the same rule, exercised again.
+
+`./nodes` re-exports `editorNodes` from the shared module, plus
+`importMarkdownToLexical`/`exportLexicalToMdast` from the mapper. Both live on
+the same subpath because they cannot be usefully separated: the mapper
+directly imports the node classes' `$create*`/`$is*` helpers, so an entry
+point exporting the functions without the matching node array would still
+leave a consumer unable to build a working `createEditor` for them, and vice
+versa. Putting both in one place also means Acceptance Scenario 1/2's
+"importing only from `@liminis/editor`'s declared entry points" is satisfied
+by a single import.
+
+### The MathJax-lite exception is inherited, not re-litigated
+
+`EquationNode.tsx` imports `mathjax-config.ts` at module scope, which
+statically imports MathJax's lite *and* browser adaptors — around 90
+side-effectful TeX-configuration imports evaluate whenever the node set loads,
+with no DOM, no rendering, and no MathJax document instantiation. `./headless`
+already carries and documents this identical exception (see ADR-075 §1).
+`./nodes` inherits it rather than attempting to fix `EquationNode.tsx`'s
+import laziness, which is a separate refactor out of scope for a purely
+additive change (FR-008).
+
+Verified directly (not assumed) that `./nodes`'s import graph is otherwise
+narrow: `Mermaid`'s and `C4`'s render components are `lazy(() =>
+import(...))`-loaded from their node class files, so a non-rendering headless
+editor never evaluates `mermaid`, `@dagrejs/dagre`, or Prism — none of those
+packages, nor `zustand` or `lucide-react`, appear anywhere in the static
+graph. This is pinned by `nodes-subpath.test.ts`, modeled on
+`annotations-subpath.test.ts`'s static-graph-walker pattern but adapted in two
+ways: comments are stripped before scanning for `from '...'` specifiers
+(`c4/types.ts` has a doc comment containing `from "Name"`, which the naive
+regex would otherwise misread as a bare package import), and dynamic
+`import('./Component')` targets are not followed as graph edges, since
+treating a lazy boundary as an eager one would defeat the point of measuring
+it.
+
+### The round-trip test asserts on mdast, not stringified markdown
+
+`nodes-subpath-roundtrip.test.ts` (FR-006/SC-005) proves the export is
+sufficient on its own: it imports only from `./nodes` and `./markdown`,
+builds a `createEditor` from `editorNodes`, and drives a markdown → Lexical →
+mdast round trip covering headings, links, lists, tables, code, images and a
+callout. It asserts against the resulting mdast tree's shape rather than
+re-stringified markdown, because `./markdown` does not export
+`stringifyMarkdown` — reaching for the root barrel to get it would reintroduce
+the `<App>`/`<Editor>`/Prism weight this subpath exists to avoid. This is a
+scope decision for what this one test checks, not a lowering of FR-005's
+fidelity bar, which the package's existing internal round-trip suite still
+enforces at full strength.
+
+One calling-convention detail worth recording because it is easy to get
+wrong: `importMarkdownToLexical` schedules its own `editor.update()`, which by
+default reconciles on a microtask. Calling `exportLexicalToMdast` immediately
+afterward races that reconciliation and reads a stale (often empty) tree. The
+fix — wrapping the call in an outer `editor.update(fn, { discrete: true })` —
+is the same convention the package's own internal `roundtrip-test-utils.ts`
+already relies on; it is now also shown in `docs/markdown-pipeline.md`'s
+headless-editor example, so external consumers don't have to discover it by
+reading the mapper's implementation.
+
+## Consequences
+
+**Good:**
+
+- A consumer (Zusammen's own round-trip harness is the motivating case) can
+  build a headless editor and exercise the real mapper without a fork, without
+  mounting `<Editor>`, and without pulling in MathJax's browser adaptor,
+  Mermaid, or Prism.
+- The internal drift risk `roundtrip-test-utils.ts`'s comment already named is
+  closed: one array, two consumers, both inside and outside the package.
+- Adding a node type to the production editor's configuration requires editing
+  exactly one file; both `Editor.tsx` and `./nodes` see it automatically.
+
+**Bad / accepted:**
+
+- `./nodes`'s isolation contract is strictly weaker than
+  `./markdown`/`./contract`/`./annotations`: it requires Lexical and React,
+  and carries the same MathJax-lite exception as `./headless`. This is stated
+  explicitly here and in the subpath's own docstring so it isn't later
+  mistaken for an oversight.
+- The surface ADR-075 fixed at five subpaths is now seven. Each widening is
+  small and individually justified, but the "closed set" is closed only in the
+  sense that widening it requires this documented process, not that it never
+  grows.
+
+**Neutral:**
+
+- `verify-package.mjs`'s `EXPECTED_SUBPATHS` and
+  `examples/external-consumer/src/subpaths.ts`'s per-subpath import block are
+  both hand-maintained lists; both were extended in the same change so the new
+  subpath's publishability is actually verified against a packed tarball,
+  rather than silently going unchecked the way ADR-078 built that script to
+  prevent.
+
+## References
+
+- Issue #954 (this phase)
+- ADR-075 (the `@liminis/editor` package boundary; §1's closed-subpath rule
+  this ADR exercises again)
+- ADR-077 (comments and corrections as one annotation mechanism; the prior
+  exercise of the same "considered export" rule, for `./annotations`)
+- ADR-078 (non-bundling `tsc` emit + `publishConfig` delivery; the mechanism a
+  new subpath plugs into)
+- `verveguy/zusammen#102` (the private adoption this export unblocks),
+  `verveguy/zusammen#62` and `#50`, `#943` (the mapper fidelity bugs the
+  resulting headless round-trip guard is meant to catch)

package/docs/decisions/adr-080.md

@@ -0,0 +1,325 @@
+# ADR-080: Comments Are Folded State in a Workspace Dotfile, Owned by the Main Process
+
+**Date:** 2026-08-08
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** ADR-077 (supplies the Liminis consumer it anticipated; corrects two statements it made about the app's wiring)
+**Issue:** #964
+
+## Context
+
+ADR-077 established comments and corrections as two *configurations* of one
+annotation mechanism inside `@liminis/editor`, and put storage, lifecycle and
+presentation deliberately on the **host** side of the ADR-075 persistence seam.
+It then noted that Liminis had none of that host side: it configured the
+`correction` kind, supplied no `onCreateAnnotation`, and never called
+`captureAnchor` or `resolveAnchors` at all.
+
+This ADR records the decisions that fill that gap — where comment data lives,
+what shape it takes, and who owns it.
+
+Two properties of the Liminis environment drove the answers, and both differ
+from Zusammen, whose implementation of this feature is the nearest prior art:
+
+- **A Liminis Notebook is a plain, human-browsable folder of markdown that is
+  also a git repository.** `workspace-init` runs `git init`, and the workspace
+  `.gitignore` template excludes only `.liminis/context-graph.pid` and
+  `.liminis/mcp-oauth.json` — so anything else written under `.liminis/` is
+  tracked, diffable, and swept into `createCheckpoint`'s `git add -A` for free.
+- **Liminis is single-user and single-machine.** Concurrency is several windows
+  of one app instance plus in-process agent activity — not concurrent reviewers
+  on branches, which is the problem Zusammen's storage design exists to solve.
+
+## Decision
+
+### 1. Comments live in `.liminis/comments.json`, as folded state
+
+One JSON index for the whole workspace, keyed by workspace-relative POSIX path,
+written atomically (temp file + rename) by the main process.
+
+**Not embedded in the markdown.** That would defeat the "transparent on export"
+property the mark renderer was built for and make every comment a document
+edit — the thing FR-007 forbids outright.
+
+**Not a sidecar beside each document.** It travels with the file, but it
+litters a notebook that is meant to read as a plain folder of notes, and
+Liminis already has a dotfile precedent in
+`.liminis/knowledge-corrections.yaml`.
+
+**Not a dedicated git ref (Zusammen ADR-003's WAL).** That model is correct for
+Zusammen's concurrent-reviewer, branch-per-review workflow, but it needs the
+scratch-index/CAS plumbing Liminis does not have, and buys conflict-freedom
+Liminis does not need. A notebook is already a git repo, so the working tree
+gives versioning, diffability and checkpoint participation without a second
+write path.
+
+**Folded state, not an event log.** Zusammen's append-only `CommentEvent` log
+with a pure `reconstructComments` fold buys conflict-free merge and a complete
+audit trail. Liminis needs neither. The two properties it *does* need from that
+model are one field (`editedAt`, for FR-023's "marked as edited") and one store
+invariant (never auto-delete, FR-018) — neither of which justifies replay
+machinery. The notebook's git history is the audit trail.
+
+**One index, not one file per document.** `rollbackToCommit` is
+`git reset --hard`, which is workspace-wide, so per-document granularity buys
+nothing for checkpoint alignment. A single index makes a rename remap a key
+change rather than a file move, and sidesteps path→filename escaping entirely.
+
+**JSON, not YAML** — unlike the corrections precedent. Anchors carry exact
+whitespace in `targetText`, `prefixContext` and `suffixContext`, which YAML
+block scalars round-trip badly, and the package's `ANCHOR_SCHEMA` is already
+zod.
+
+**Deletion is a hard delete.** FR-018 forbids only *automatic* deletion. A user
+delete removes the record; git history preserves it; and FR-023 requires the
+thread to actually leave the comment list, which a tombstone would complicate
+for no gain.
+
+**Accepted consequence:** comments are commit-worthy working-tree changes. They
+appear in `git status`, in checkpoint diffs, and move with a rollback. That is
+the intended behaviour — a rollback that restores a document should restore the
+comments that were on it — and it is the single most surprising thing a user
+who inspects their notebook will find.
+
+### 2. `docVersion` is a content hash
+
+`AnchorFields` carries no `docVersion` and `ANCHOR_SCHEMA` requires a non-empty
+one, so the host must stamp it. Liminis resolves anchors against *working-tree*
+text — the file as it is now, which may never have been committed and may have
+been edited outside the app — so Zusammen's git-HEAD-SHA answer does not
+transfer.
+
+`sha256(documentText).slice(0, 16)`, computed in the main process. It is audit
+metadata the resolver never reads; what matters is that capture, re-capture and
+resolution all compute it the same way, which one main-process implementation
+guarantees.
+
+### 3. The store is main-process-owned, behind IPC, and broadcasts
+
+Per ADR-032 the main process owns all state; per ADR-007 renderer traffic goes
+through `ipcMain.handle` + `contextBridge`; per ADR-025 window events are not a
+state channel. The comment store is therefore a main-process module with a
+`comments:*` IPC surface, and every change is pushed to every window over
+`comments:changed`.
+
+The renderer store holds nothing of its own beyond presentation state. Writes
+are serialized inside main by a per-workspace promise chain — the corrections
+precedent does unlocked read-modify-write, which is fine at its write rate and
+would not be at a comment editor's.
+
+**SC-005 is forward-looking.** Only one window hosts an editor today, so
+"a comment created in one window appears in another" is evidenced by a unit
+test on the broadcast fan-out rather than end-to-end. The fan-out is
+architecturally required regardless, and costs nothing.
+
+### 4. Resolution runs off the document-open path, and never auto-deletes
+
+`resolveAnchor` performs one full `parseBlocks` — an mdast parse of the entire
+document — *per anchor*, and `resolveAnchors`' `Promise.all` does not make that
+concurrent because the work is synchronous CPU. A hundred comments is a hundred
+parses on the main process's only thread.
+
+The host cannot hoist that parse (FR-033 bars touching the package), so
+`comments:open` answers immediately from the store with each comment's *last
+persisted* outcome and schedules the re-resolution pass, which yields to the
+event loop every five anchors and broadcasts when it lands. This is Zusammen's
+best-effort pattern. Hoisting `parseBlocks` out of the per-anchor loop is a
+separate upstream issue against `packages/editor`.
+
+The graded outcomes map to graded persistence, and to graded UI:
+
+| Outcome | Persisted | Marker | Presented as |
+| --- | --- | --- | --- |
+| `unchanged` | nothing (FR-015) | yes | Open |
+| `re-attached` | outcome + new anchor (FR-014) | yes | Open |
+| `flagged` | outcome only | no | Location uncertain, with the original quote |
+| `orphaned` | outcome only | no | Detached, with the original quote |
+
+No comment is ever deleted as a consequence of an outcome (FR-018), and no
+semantic-relocation strategy is supplied (FR-021) — filling
+`proposeSemanticRelocation` needs a model call on the document-open path, with
+the cost, latency and failure modes that implies, and is a follow-up.
+
+Two idempotence guards keep merely *opening* a document from dirtying the
+working tree: a `re-attached` anchor identical to the stored one is not
+rewritten, and an `unchanged` outcome clears a previous verdict only when that
+verdict was actually suppressing a marker.
+
+### 5. A degraded store refuses writes rather than overwriting
+
+A store file that exists but will not parse puts that workspace into a
+**degraded** state: reads answer empty so documents still open, every write is
+refused with a distinct error, the renderer shows a persistent banner, and the
+file is never touched.
+
+This deliberately departs from the corrections precedent, which logs malformed
+YAML and treats it as absent — and whose writer would then happily overwrite
+it. FR-010 forbids exactly that for comments, because the file being
+overwritten is the user's own data.
+
+Two corollaries, both found in review and both load-bearing:
+
+**Degradation is re-checked, not remembered.** A degraded entry is re-read on
+every access rather than cached. The banner tells the user their comment file is
+unreadable and the obvious response is to go and repair it; caching the verdict
+would keep refusing writes until the app restarted, with nothing explaining why
+the repair had no effect. A healthy store is still cached on first load.
+
+**The store validates on the way out as well as in.** Every field reaching a
+mutator arrives over IPC, where the types are a compile-time promise only.
+Validating only on read meant an unstorable record — an empty `id`, an author
+with an empty `name` — wrote successfully and failed on the *next* load, at
+which point the whole workspace flipped degraded: every comment invisible, every
+write refused. The store could corrupt itself into the state this decision
+exists to prevent. `writeToDisk` now parses the file it is about to write and
+refuses on failure, keeping the failure local to the bad record.
+
+### 6. The correction path now runs the package's capture cycle
+
+`AnnotationPlugin` registers a single command handler for *every* configured
+kind, gated only on the kind having a `createAffordance`. `correction` has one.
+So once Liminis supplies `onCreateAnnotation` — which FR-003 requires —
+clicking "Correction…" runs the package's wrap → export → `readAnchorFields` →
+unwrap cycle in addition to opening the legacy correction panel, and the host
+handler discards the result.
+
+This is precisely the cost ADR-077 declined to pay. It is accepted here because
+both alternatives are barred: removing the correction affordance would be a
+correction behaviour change (FR-034), and suppressing the capture would need a
+package change (FR-033). User-visible behaviour is unchanged —
+`markerStyle: 'none'` plus `livemarkPolicy: () => false` plus
+`retainMarkOnCreate: false` keep the correction path paint-free — and all three
+are guarded in `editor-package-wiring.test.ts`.
+
+### 7. Commenting is enabled on `EditorColumn` only
+
+Since #961 all five `<App>` mount sites configure annotation kinds. Adding
+`comment` to the value they *shared* would have given the canvas card bodies,
+`ActionViewer` and `MarkdownEditorPanel` a "Comment…" entry with no composer
+behind it. Those four are pinned to `CORRECTION_ONLY_ANNOTATION_KINDS` —
+byte-identical to what they had — and `ANNOTATION_KINDS` (comment + correction)
+is passed by `EditorColumn` alone (FR-032).
+
+### 8. Anchoring inside a code fence or frontmatter is refused up front
+
+The spec's structured-content edge case permits "work or be refused up front".
+Refusing is the safer half: a mark inside a code fence or a frontmatter block
+is the least-exercised region of the package's mark-transparency corpus, and a
+silent round-trip corruption there would damage the user's document — the one
+thing FR-007 exists to prevent. On refusal the transient mark is retracted, a
+toast explains, and nothing is persisted.
+
+## Consequences
+
+**Good**
+
+- Comments version, diff and roll back with the notebook, with no second git
+  write path and no new plumbing.
+- The difference between the comment feature and the correction feature stays
+  expressible as two `AnnotationKindConfig` values plus host code; nothing
+  inside `@liminis/editor` changed (SC-007).
+- Agent authorship is representable and renderable from day one, so the later
+  agent-authoring path needs no schema migration (FR-027). The anchor resolver
+  already exercises it — its automatic resolutions are attributed to
+  `{ name: 'Liminis Anchor Resolver', kind: 'agent' }`.
+- A corrupt store degrades commenting without endangering either the document
+  or the existing comment data.
+
+**Bad, or at least surprising**
+
+- `git status` in a notebook now shows `.liminis/comments.json` changing as the
+  user comments. This is intended, and is documented in the release notes.
+- The single index grows unbounded across a large notebook. Acceptable at
+  Liminis's scale — comments are small and the write is atomic — and the
+  migration to per-document files is mechanical if it ever stops being.
+- Correction authoring pays for a capture cycle whose result is thrown away.
+- The right rail now has three mutually-exclusive occupants (history >
+  comments > TOC) and a correspondingly fiddlier `paddingRight`.
+
+## Amendments to ADR-077
+
+Two statements in ADR-077 are true no longer, and this ADR supersedes them:
+
+1. *"the resolver currently has no Liminis consumer … stated here so it isn't
+   later mistaken for dead code"* — `src/main/comments/comment-anchoring.ts` is
+   that consumer.
+2. *"`liminis-app` supplies `annotationKinds` but **not** `onCreateAnnotation`"*
+   — `EditorColumn` supplies both. See §6 for what that changed on the
+   correction path.
+
+## Known limitations at first release
+
+> **Historical — both were fixed by #970 (PR #971) on 2026-08-13.** The rest of
+> this section is written in the present tense of the first release and is kept
+> as the record of what shipped and why. For what is true now, read the
+> resolution note at the end of the section: neither limitation survives, and
+> neither mitigation described below still exists in the codebase.
+
+Two `@liminis/editor` mark-placement gaps were measured while reviewing this
+issue and filed as #970. FR-033 forbids patching either from the host, so they
+ship as follows — the two were deliberately *not* treated the same way, because
+one degrades an experience and the other damages data.
+
+**Overlapping passages place only one mark.** `placeMarksForAnchors` works
+back-to-front because a placed mark splits its TextNode and invalidates
+`offsetSpans` for everything after it — sound for disjoint ranges, but for
+overlapping ones the later placement invalidates the span the earlier entry
+still needs. Strict nesting fails the same way. Accepted as a first-release
+limitation: both comments persist, both are listed, and the unmarked one is
+reachable from the comment list, which flags the threads affected
+(`findOverlappingThreadIds`). The release notes say so plainly. The set that
+actually places is pinned by an assertion in
+`comment-markdown-integrity.test.tsx` so the behaviour cannot drift unnoticed.
+
+**A mark spanning an inline link reports a truncated span**, and that one
+*writes*. An anchor stored as `it [rests](https://example.com)` comes back from
+`collectLiveAnchorSnapshots` as `it [rests`; the FR-019 refresh sees a
+difference no user caused and would persist an anchor ending mid-syntax,
+silently and cumulatively. That is data damage rather than a limitation, so it
+is guarded host-side: `canRefreshAnchorText` refuses to replace a stored
+`targetText` with text *contained within* it. The rule is deliberately blunt —
+sharpening it would mean re-implementing the mapper's knowledge of markdown in
+the host, which is #970's job. Its accepted cost is that a user who genuinely
+deletes the tail of an anchored passage gets no re-capture; a stale-but-valid
+anchor still re-resolves through the fuzzy resolver, whereas a truncated one is
+corrupt and does not.
+
+**When #970 lands**, the guard and the pinning assertion come out together —
+they are two halves of the same standing mitigation.
+
+> **Resolved 2026-08-13 (#970, PR #971).** Both limitations above are fixed
+> upstream and their mitigations are gone from this codebase.
+>
+> - Overlapping and nested marks now *all* place: placement resolves every
+>   entry against the pristine tree into absolute text offsets before applying
+>   any of them, so entries no longer invalidate each other. The
+>   `comment-markdown-integrity.test.tsx` assertion now pins all seven ids.
+> - A mark spanning an inline link recovers the whole construct, so
+>   `canRefreshAnchorText` and both its call sites are **deleted**. The refresh
+>   now skips only a genuinely unchanged span, which restores re-capture for the
+>   suffix deletions the guard used to decline.
+>
+> Still outstanding: the comment list's `findOverlappingThreadIds` notice
+> ("Shares a passage with another comment — only one of them shows a
+> highlight") is now untrue and should be removed. It is app-side presentation,
+> which #970's spec puts out of its own scope, so it did not travel with this
+> change.
+
+## Follow-ups
+
+Deliberately out of scope here, each worth its own issue:
+
+- Hoist `parseBlocks` out of `resolveAnchors`' per-anchor loop (upstream,
+  `packages/editor`).
+- Fill the `proposeSemanticRelocation` seam for orphaned anchors.
+- The agent-facing path for *creating* comments — an MCP tool or agent-SDK
+  surface, and anchoring from outside a mounted editor. This issue makes agent
+  authorship representable; it does not make it reachable.
+
+## References
+
+- ADR-075 — the `@liminis/editor` package boundary at persistence
+- ADR-077 — comments and corrections as two kinds of one mechanism
+- ADR-032 / ADR-025 / ADR-007 / ADR-024 — state ownership, renderer state, IPC, dialogs
+- ADR-057 — the `.liminis/` knowledge-corrections file-format precedent
+- Zusammen ADR-003, ADR-008, ADR-012 — the prior art this decision diverges from

package/docs/decisions/adr-081.md

@@ -0,0 +1,108 @@
+# ADR-081: The Web Shell Reads the Fixture Corpus Through Generated Data, Not a `src/` Import
+
+**Date:** 2026-08-15
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #2 (verveguy/liminis-editor)
+
+## Context
+
+verveguy/liminis-editor#1 landed a round-trip fixture corpus at
+`src/app/mapper/__tests__/fixtures/roundtrip/`, covering every Lexical node
+class `editorNodes.ts` declares (`node-class-completeness.test.ts` enforces
+this). This issue grows `examples/demo` from a single hand-written markdown
+string into a shell that renders every fixture-representable node class, and
+requires (FR-006/FR-007) that its content come from that same corpus rather
+than a second, hand-maintained set of sample documents.
+
+`examples/demo` is a structurally external consumer of `@liminis/editor` — its
+own `package.json`, no workspace linkage, and it installs the packed tarball
+the same way a real adopter would (`scripts/run-demo.mjs`). FR-008 makes that
+literal for imports: neither shell may import from `@liminis/editor/src/...`
+or any relative path reaching into the package's `src/`. The fixture corpus
+lives inside `src/`, so a direct `import.meta.glob('../../../src/app/mapper/
+__tests__/fixtures/roundtrip/**/*.md')` from the demo would be exactly the
+thing FR-008 prohibits — even though the fixtures are markdown data, not
+package code, the path itself crosses the boundary the rule polices.
+
+Two shapes were available to resolve this, both surfaced during Research:
+
+1. Move the corpus to a repository-root `fixtures/` directory, sibling to
+   `src/`, and update `roundtrip-test-utils.ts`'s `discoverFixtures` path and
+   `fixtures/roundtrip/README.md` accordingly.
+2. Leave the corpus where #1 put it, and add a build-time script that reads
+   it and emits a generated data module inside `examples/demo`, which the
+   demo then imports as an ordinary local file.
+
+#1's own Out of Scope section reserves "the content and structure of the
+shared fixture corpus itself" for that issue. Moving the corpus is not a
+content or structure change, but it touches already-merged, extensively
+documented test infrastructure (`fixtures/roundtrip/README.md`'s per-fixture
+provenance notes, `roundtrip-test-utils.ts`'s `discoverFixtures`) for a rule
+that belongs to a different issue. That is a bigger, riskier change than
+generating one file, for a boundary #1 drew around itself deliberately.
+
+## Decision
+
+**The corpus stays at `src/app/mapper/__tests__/fixtures/roundtrip/`.**
+`scripts/generate-demo-fixtures.mjs` reads it directly (a build-time Node
+script, not a runtime import, so it is not itself bound by FR-008 — nothing
+in the demo's own source or bundle reaches into `src/`) and emits
+`examples/demo/src/fixtures.generated.js`, a plain JS module listing each
+fixture's corpus-relative name, group, and markdown text.
+
+Fixtures with a `.error.txt` sidecar (expected to throw on import) are
+excluded, mirroring `node-class-completeness.test.ts`'s own skip logic —
+`discoverFixtures` and the exclusion rule are the only pieces of corpus
+knowledge this script needs, and both already exist in
+`roundtrip-test-utils.ts`'s shape.
+
+The generated file is gitignored. `pnpm demo` (`scripts/run-demo.mjs`) and
+the new `scripts/build-examples.mjs` (CI) both regenerate it before the demo
+is built or run, so there is no code path that consumes a stale copy, and the
+demo's own source tree never contains a checked-in duplicate of #1's corpus
+to drift out of sync with it.
+
+## Consequences
+
+**Good:**
+
+- `examples/demo` satisfies FR-006/FR-007 (fixture-driven content, same
+  corpus as #1) and FR-008 (no `src/` reach-in) simultaneously, without
+  touching a single file #1 already merged.
+- The corpus has exactly one location and one owner (#1's own scope), for
+  both the completeness test and the web shell — the generated file is a
+  derived artifact, not a second source of truth.
+- Adding a fixture to the corpus (or a class of fixture, as future issues
+  extend #1's coverage) makes it appear in the demo on the next regeneration,
+  with no change to the demo's own source.
+
+**Bad / accepted:**
+
+- A codegen step is now part of both `pnpm demo` and the CI build path for
+  `examples/demo` — one more script in the pack/install/build pipeline
+  Research already flagged as having duplicated orchestration logic across
+  `run-demo.mjs`, `verify-package.mjs`, and now `build-examples.mjs`. Left
+  unconsolidated; not required by this issue.
+- The generated file, being gitignored, does not appear in a diff when a
+  fixture changes — a reviewer checking "does the demo still render
+  correctly" has to run the generator locally rather than reading the PR.
+
+**Neutral:**
+
+- The repo-root-`fixtures/` alternative remains available if a future issue
+  needs the corpus to be reachable from outside `src/` for reasons beyond
+  this one shell (e.g. a second consumer). Nothing here forecloses it; it was
+  simply not the lowest-risk answer to *this* issue's requirement.
+
+## References
+
+- Issue #2 (this decision), verveguy/liminis-editor#1 (the corpus this
+  decision reads from, and whose Out of Scope section this decision respects)
+- `src/app/mapper/__tests__/fixtures/roundtrip/README.md` (the corpus's own
+  documentation, unchanged by this decision)
+- `docs/decisions/adr-078.md` (packed-tarball delivery; the reason
+  `examples/demo` cannot resolve `@liminis/editor/src/...` even in
+  development, which is the same structural constraint this decision applies
+  to the corpus)