@liminis/editor 0.1.0-rc.1

package/docs/decisions/adr-077.md

@@ -0,0 +1,410 @@
+# ADR-077: Comments and Corrections Are Two Kinds of One Annotation Mechanism
+
+**Date:** 2026-08-04
+**Status:** Accepted (amended by ADR-080 — see the two notes marked *Amended by ADR-080* below)
+**Supersedes:** none
+**Amends:** ADR-075 (adds a sixth export subpath to the surface it fixed at five)
+**Amended by:** ADR-080 (#964 supplies the Liminis consumer this ADR said did not exist, and wires `onCreateAnnotation`)
+**Issue:** #939
+
+> Authored as ADR-076. Renumbered to 077 when this branch rebased onto `main`,
+> because #943 landed its own ADR-076 first. No numbering collision is left
+> behind — unlike ADR-024/024b, which the index still records as historical.
+
+## Context
+
+Two near-identical editor trees had been diverging. Zusammen accreted a review
+**commenting** feature — durable, text-anchored comments rendered as live
+`@lexical/mark` MarkNodes, transparent on export. Liminis accreted an AI
+**correction** feature — a context-menu entry, a suggestion panel, and a
+term-substitution scan.
+
+ADR-075 (#938) stopped the divergence for the *core* by making the editor one
+package with a curated public surface and a persistence-drawn seam. It
+deliberately left the two annotation-shaped features unreconciled. That left a
+live problem: the package shipped a correction-only code path, and Zusammen
+could not adopt the package without forking it back — the exact failure ADR-075
+set out to end.
+
+The two features are the same shape. Both are a range-anchored marker over
+document text, with data flowing in from a host and events flowing out to it.
+Only their storage, lifecycle and presentation differ, and all three of those
+are already on the host's side of ADR-075's seam.
+
+A complicating fact, found while implementing: **Liminis's correction feature
+has no marks, no anchors and no resolution.** The issue's premise — that
+corrections are host-injected annotations with inline accept/reject — described
+a feature that does not exist. A literal reading of "corrections must use the
+one marker renderer" and "no user-visible correction change" cannot both hold,
+because giving corrections in-document markers *is* a visible change.
+
+## Decision
+
+**One annotation mechanism, baked into the package, with comments and
+corrections as two configured usages of it.**
+
+An annotation is `{ id, kind, anchor, outcome?, presentation?, payload? }`. The
+package owns the mechanics: the durable anchor model, selection→anchor capture,
+the fuzzy anchor resolver, MarkNode marker rendering, mark-transparency on
+export, the live-mark placement policy, and the in-document affordances. A host
+owns everything else.
+
+### The kind configuration is the only difference
+
+`AnnotationKindConfig` — marker style, create affordance, live-mark policy, and
+whether capture retains its mark — is the sole thing distinguishing a comment
+from a correction. There is exactly one anchor model, one resolver, and one
+marker renderer, with no kind-specific variant of any of the three.
+
+### Corrections render no live mark
+
+The `correction` kind is configured `markerStyle: 'none'`, `livemarkPolicy:
+() => false`, `retainMarkOnCreate: false`. Correction authoring is *wired* to
+the same capture primitive comments use: `SelectionContextMenuPlugin`'s
+"Correction…" entry dispatches `OPEN_ANNOTATION_COMPOSER_COMMAND`, whose
+handler wraps the selection in a transient MarkNode, reads the anchor back
+from it, and — because `retainMarkOnCreate` is false — discards the mark
+again, so nothing ever paints. That handler is not mounted in Liminis today;
+see "What Liminis actually runs today" below, which is the authoritative
+statement and takes precedence over any looser reading of this paragraph.
+
+This is what resolves the contradiction above. Corrections are expressed
+through the mechanism — their authoring entry point dispatches its command,
+their behaviour is kind configuration — while rendering exactly what they
+rendered before: nothing.
+Parity is preserved, and the reviewer's test for "is this really unified?" —
+point at the kind-config objects as the only difference — holds.
+
+`markerStyle: 'none'` is enforced structurally rather than by convention:
+`deriveMarkerTargets` drops such annotations outright, ahead of and in
+precedence over `livemarkPolicy`. A marker target is not a styling hint — it
+is what causes a real `MarkNode`, and therefore a `<mark>` element, to be
+placed. The marker plugin skips decoration for `none`, so that element would
+carry no `annotation-mark-*` class, and the package's stylesheet neutralizes
+the UA's default yellow `<mark>` background only under those classes. Without
+the gate, a host that configured `none` and left `livemarkPolicy` at its
+default would get a persistent uncontrolled highlight — the opposite of what
+`none` promises. Liminis's explicit `livemarkPolicy: () => false` is now
+belt-and-braces rather than load-bearing.
+
+**What Liminis actually runs today.** The create handler lives in
+`AnnotationPlugin`, which the annotation surface mounts only when a host
+supplies `onCreateAnnotation`. `liminis-app` supplies `annotationKinds` but
+*not* `onCreateAnnotation` — it has nothing to do with a correction anchor,
+since corrections have no durable anchors (below). So in Liminis the
+"Correction…" dispatch currently finds no listener and is inert: the correction
+panel opens exactly as it always has, and no capture runs. This is deliberate
+— running a wrap/read/unwrap cycle purely to discard the result would be cost
+and FR-006 risk on a user-visible path for no product value — but it means the
+claim "corrections exercise the capture primitive" is true of the *wiring*, not
+of a running Liminis session.
+
+> **Amended by ADR-080 (#964).** No longer true. `EditorColumn` now supplies
+> `onCreateAnnotation` for the `comment` kind, and `AnnotationPlugin` registers
+> one handler for *every* configured kind — so the "Correction…" dispatch does
+> find a listener, and the wrap/read/unwrap cycle this paragraph declined to
+> pay for now runs on the correction path, with its result discarded by the
+> host handler. The cost was accepted rather than chosen: removing the
+> correction affordance would change correction behaviour, and suppressing the
+> capture would need a package change. User-visible behaviour is unchanged and
+> guarded. See ADR-080 §6. FR-001's substantive guarantee is unaffected: the
+package contains exactly one anchor model, one resolver and one marker
+renderer, and no correction-specific variant of any of them. A host that does
+want correction anchors turns them on by passing `onCreateAnnotation`, with no
+package change.
+
+**What that costs.** `annotationsEnabled` is true for any non-empty
+`annotationKinds`, so configuring the `correction` kind makes the editor load
+the lazy `AnnotationSurface` chunk (~49 KB) and its annotation modules at
+mount — machinery Liminis gains no behaviour from today. Measured live on a
+running app during Validate: the annotation code stays in its own chunk and
+never reaches windows that host no editor, so #938's bundle win survives
+(graph window +417 bytes against `main`). We accept the editor-window cost for
+this phase: registering the kind keeps the host-side wiring on the real path
+rather than dead, and dropping the config to reclaim the chunk would trade that
+away for a saving that only matters until the callback is supplied.
+
+Corrections do **not** exercise the resolver. They have no cross-session
+anchors; their lifetime and storage remain the app-side correction store. This
+is a refactor, not a data-model change for corrections.
+
+### A sixth export subpath: `./annotations`
+
+ADR-075 fixed the surface at five subpaths and permitted adding a *considered*
+export. This is one.
+
+The headless annotation surface — anchor model, resolver, block structure, span
+alignment, and the annotation types — must be callable outside a rendered
+editor (Zusammen resolves anchors in its main process). It therefore cannot
+live on the root barrel. It does not belong on `./headless` either, whose
+`mathjax-config` re-export drags ~1.9 MB of side-effectful imports; and
+`./markdown` is contractually pure-mdast, while the anchor schema needs `zod`.
+
+A dedicated subpath also gives the "annotations are off by default" requirement
+a crisp assertion target. Its import graph is tested to reach no Lexical, React,
+DOM, MathJax, Mermaid, C4 or Prism module, and nothing outside `src/annotations/`.
+
+### The mechanism is opt-in, behind a lazy boundary
+
+A consumer that configures no kinds gets nothing: no marker, no affordance, no
+registered command — and, more importantly, no annotation module in its import
+graph. `Editor.tsx` reaches the annotation surface only through
+`lazy(() => import('./AnnotationSurface'))`, and imports the annotation prop
+*types* only as `import type`, which the compiler erases.
+
+Two exceptions are deliberate and scoped:
+
+- **`MarkNode` registration** and **mapper mark-transparency** are
+  unconditional. The mapper is shared and cannot be kind-aware; making it so
+  would fork the round-trip path, which is the exact divergence #938 ended.
+  `MarkNode` is an inert node when nothing places one.
+- **`annotationCommands.ts`** stays statically importable. It declares one
+  Lexical command and imports nothing but `lexical`, carrying no anchor, mark or
+  resolver machinery. That is what lets the selection context menu enter the
+  mechanism without dragging any of it into the disabled graph. A test pins the
+  module to that single import.
+
+### Marker styling ships with the package
+
+`AnnotationMarkerPlugin` decorates a live mark's element with
+`annotation-mark-<markerStyle>` (`highlight` / `squiggle`), plus
+`annotation-mark-active` and `annotation-mark-pulse` for state. Default rules
+for all of them are in `packages/editor/src/styles.css`.
+
+They ship in the package rather than being left to the host because the
+mechanism is a baked-in feature, not an extension point (see the Context above):
+a host that enables the `comment` kind should get a visible, working marker
+without first having to discover and reimplement those exact class names. The
+failure mode is otherwise silent and invisible from inside Liminis — anchors
+place, activation fires, and nothing renders.
+
+Hosts that want a different look override the rules, or supply a per-annotation
+class through `presentation.className`, which the plugin applies alongside the
+kind's own style. A test asserts every `AnnotationMarkerStyle` other than `none`
+has a rule, cross-checked against the union declaration so a new style cannot be
+added without one.
+
+**Shipping the rules is not the same as delivering them.** Nothing in the
+package injects the stylesheet: neither the root barrel nor `<Editor>` imports
+`styles.css`, deliberately — a component that imports CSS forces it on every
+consumer, including the markdown-only ones that take `./markdown` precisely to
+stay clear of the React surface. So a host that enables a marker-visible kind
+**must** import the stylesheet itself:
+
+```ts
+import '@liminis/editor/styles.css'
+```
+
+Miss it and the failure is the silent one described above, one step earlier:
+anchors place, activation fires, and nothing renders. `liminis-app` does this in
+`src/renderer/App.tsx`, and `editor-package-wiring.test.ts` pins all three
+halves of the contract — the subpath is declared, the app performs the import,
+and the package still does not perform it on the host's behalf.
+
+### The seam stays at persistence
+
+The package contains no persistence, actor/identity, or annotation-lifecycle
+logic. Comment storage, correction storage, resolve/reopen, accept/reject, and
+the semantic-relocation strategy stay in the consuming apps, reached only via
+injected services or callbacks. `resolveAnchors` is async precisely because the
+relocation seam may be host-supplied and slow; with no strategy supplied, an
+unmatchable anchor yields `orphaned` rather than erroring.
+
+Two of Zusammen's helpers are deliberately **not** ported:
+`deriveMarkerTargets` and `anchorOutcomeOf` take Zusammen's `Comment`/`Thread`
+types, which are app-domain. The package accepts already-derived annotations
+instead and re-expresses `deriveMarkerTargets` over them.
+
+## Consequences
+
+**Good:**
+
+- Zusammen can adopt the package without forking it. Every editor-domain
+  capability it has today maps to a package export (see
+  `docs/project_notes/zusammen-editor-capability-map.md`).
+- One anchor model, one resolver, one marker renderer. A third annotation-shaped
+  feature is a configuration entry, not a new code path.
+- Zusammen's anchor test suites carry over and pass unmodified, so the
+  classification outcomes and thresholds are preserved case-for-case rather
+  than reimplemented and hoped-for.
+- Mark transparency is now asserted across the whole round-trip fixture corpus,
+  not just hand-built cases.
+
+**Bad / accepted:**
+
+- The resolver has **no Liminis consumer**. It exists for Zusammen and for the
+  ported tests. This is deliberate, and stated here so it isn't later mistaken
+  for dead code and deleted.
+  > **Amended by ADR-080 (#964).** It has one now:
+  > `liminis-app/src/main/comments/comment-anchoring.ts` calls `resolveAnchors`
+  > on every document open.
+- Liminis now configures an annotation kind, which turns the mechanism on and
+  switches its import path to the offset-collecting variant. Invisible to users,
+  but it is no longer true that Liminis takes the annotations-disabled path.
+- The sixth subpath is a small widening of a surface ADR-075 deliberately kept
+  narrow.
+
+**Neutral:**
+
+- The correction term-substitution scan remains separate from the resolver.
+  They answer different questions: the scan is exact word-boundary *candidate
+  discovery*; the resolver re-locates an anchor captured against an older
+  document version. "Fuzzy matching in exactly one module" constrains the
+  resolver, not the scan.
+
+## Implementation Notes
+
+Two constraints worth recording, both found by tests rather than by reading:
+
+**A Lexical command handler runs inside an active update.** The nested update
+that places a mark is queued, not applied, so reading the anchor back inline
+always yields null. The anchor read is deferred to a microtask, which runs after
+the outer update flushes. Zusammen reaches the same split by reading the anchor
+at composer-submit time.
+
+**`convertLinkNode`'s child loop silently drops unrecognized node types.** An
+unflattened MarkNode over link text therefore deleted that text from the export
+entirely (`[note](#x)` → `[](#x)`). Fourteen corpus fixtures caught this; it had
+no equivalent in Zusammen's copy.
+
+**Mid-resolution staleness needs no new guard.** `placeMarkForAnchor` already
+re-verifies the anchor's target text against the current offset spans and
+refuses to place on a mismatch, so a stale anchor no-ops and retries when the
+next parse produces fresh spans. This is now a tested property rather than an
+assumption.
+
+### Overlapping annotations (#970)
+
+**Placement resolves against the pristine tree, in absolute text offsets.**
+`OffsetSpan[]` describes the parse that produced it, and placing a mark splits
+the `TextNode` it lands in — Lexical's `splitText` keeps the original key on the
+first segment, so after one placement the table can name offsets past the end of
+what that key now holds. An earlier fix ordered a batch back to front, which
+keeps *disjoint* entries valid but silently declined any entry whose range
+overlapped, nested inside, or coincided with another's. `placeMarksForAnchors`
+now runs two phases inside one `editor.update()`: resolve every entry against the
+untouched tree into a character offset across all text nodes, then apply each
+against the live tree. Marking changes no text, so those offsets are invariant
+under every placement — the same invariant `$withPreservedSelection` relies on to
+restore the caret. Placement order therefore no longer affects the outcome.
+
+**Overlap is represented as id-unioned sibling marks, not nested ones.**
+`$wrapSelectionInMarkNode` creates a nested `MarkNode` when a selection lands
+inside an existing mark and never merges ids; its own source defers un-nesting to
+`registerNestedElementResolver<MarkNode>`. Nothing registered one, so the shared
+region of two overlapping annotations carried only the inner id and a click there
+fired twice as it bubbled — while `AnnotationMarkerPlugin` was already written
+for the opposite shape. `mark-overlap-resolver.ts` registers that resolver, so an
+overlap becomes a run of siblings whose shared part carries both ids. It is a
+node transform, so it runs inside the update that created the nesting and the
+single-reconciliation guarantee is unaffected.
+
+**A range over a whole inline construct recovers the whole construct.** The
+guarantee is deliberately scoped that way — a boundary never *splits* a run of
+inline syntax, whatever the mark covers, but only whole coverage moves it
+outside the construct (see the paragraph after next). The annotated-serialize
+sentinel used to be spliced into a mark's first/last *text leaf*, and that walk
+recursed into inline element children — so a mark over
+`it [rests](https://example.com)` recovered as `it [rests`. `lexicalToMdast.ts`
+now hoists a boundary token outside every inline construct whose whole rendered
+content the mark covers, emitting it as its own mdast text node beside the
+construct; nested constructs resolve to the outermost.
+
+The rule is *whole* coverage, not any coverage. A mark covering only part of a
+construct's text keeps today's splice, because widening it would change what the
+annotation means: `big` inside `**big world**` would recover as `**big world**`
+and re-place onto `big world`. Whole coverage has no such problem — re-placing
+`[project docs](…)` snaps back inside the syntax and highlights `project docs`
+again. This is a deliberate deviation from #970's FR-014, whose second clause
+would widen partial coverage too; the first clause (no boundary strictly inside a
+delimiter run) holds either way, since boundaries always sit at text-leaf edges.
+
+**Annotate mode must not be visible to any *decision* the export makes.** The
+whole range calculation is offset arithmetic against a plain export of the same
+state, so the annotated form has to differ by its tokens and nothing else. Two
+pre-existing violations surfaced when that property was given a corpus-wide test
+(`annotated-serialize-corpus.test.ts`): the list-item explicit-task-marker check
+and stringify's paragraph-ends-with-colon join rule both matched raw text values
+that a token had been spliced into. Both now read the sentinel-free form via
+`markdown/annotate-sentinels.ts`. Any new decision made from a text value has the
+same obligation.
+
+**Host-side mitigations in `liminis-app` became dead on merge, and were
+removed.** *(Written before either PR merged, and kept as the reasoning behind
+the checklist — see the authoritative status note below for what actually
+happened.)* Both defects were live long enough for #964 (PR #967) to ship around
+them, and neither mitigation was visible from this worktree at the time — PR #967
+was open against the same `main` this branch forked from, so the files named
+below did not exist here and could not be edited as part of this change.
+Whichever of the two PRs merged **second** had to carry the removals; if that
+were #967, this list was the checklist.
+
+**Tracked as issue #972**, because an ADR paragraph is not a reminder — if the
+second PR had merged without the removals, the write guard would have kept
+declining legitimate suffix deletions and the release notes would have stayed
+wrong.
+
+> **Status, 2026-08-13.** PR #967 (issue #964) merged first, so PR #971 is the
+> second and carries the removals. Done here: the `comment-markdown-integrity`
+> pins now assert all seven ids and the full `it [rests](https://example.com)`
+> span; `canRefreshAnchorText`, both call sites and its tests are deleted, with
+> the two call sites reduced to a plain "nothing moved" equality check so a
+> genuine edit — including a suffix deletion — refreshes again.
+>
+> **Not done, and deliberately:** `findOverlappingThreadIds` and its comment-list
+> notice. The notice is untrue now, but it is app-side presentation, which
+> #970's spec places out of its own scope, and removing it means unpicking a
+> prop threaded through `EditorColumn` into `CommentList` plus ~90 lines of
+> tests. #972 must not be closed as fully absorbed until that and the
+> `RELEASE_NOTES.md` / ADR-080 known-limitations wording are dealt with.
+
+Part 1 (overlapping marks) shipped as a documented limitation rather than a
+guard, so only descriptions go:
+
+- `renderer/components/comments/useDocumentComments.ts` — `findOverlappingThreadIds`
+  and the comment-list notice *"Shares a passage with another comment — only one
+  of them shows a highlight."* The notice is now untrue; drop the helper and its
+  tests.
+- `renderer/components/__tests__/comment-markdown-integrity.test.tsx` — pins
+  5 of 7 annotations placing, and the exact spans they cover. It is written to
+  fail when this lands. Update it to the full set and to
+  `covered['over-link'] === 'it [rests](https://example.com)'` — that failure is
+  the signal, not a regression.
+- The corresponding *Known limitations at first release* entries in
+  `RELEASE_NOTES.md` and ADR-080.
+
+Part 2 (truncated span over an inline link) shipped a real write guard, because
+FR-019's refresh would otherwise have persisted an anchor ending mid-syntax.
+That guard is `canRefreshAnchorText` in `shared/comment-types.ts` — *refuse to
+replace a stored `targetText` with text contained within it* — applied in
+`main/ipc/comments-handlers.ts` (`comments:refreshAnchors`, the authoritative
+check) and pre-filtered in `useDocumentComments.ts`. It is deliberately blunt
+and has a standing cost: a user who genuinely deletes the tail of an anchored
+passage gets no re-capture either, because the host cannot tell that apart from
+the truncation without re-implementing the mapper's knowledge of inline syntax —
+which is what now lives here instead. Delete the helper, both call sites, and
+the tests that pin it:
+
+- `shared/__tests__/comment-types.test.ts` → `describe('canRefreshAnchorText — the FR-019 write guard (#970)')`
+- `main/ipc/__tests__/comments-handlers.test.ts` → *"refuses to truncate a stored
+  anchor that spans an inline link"* and *"declines to shrink a stored anchor,
+  which is the guard's accepted cost"*
+- `renderer/components/comments/__tests__/useDocumentComments.test.ts` → *"sends
+  nothing when a mark over an inline link reports a truncated span"*
+
+Leaving the guard in after the fix keeps declining legitimate suffix deletions
+for no reason. What makes the removal safe is
+`annotation-inline-construct-ranges.test.ts`: for an unedited document the
+recovered slice now equals the captured `targetText` across every inline
+construct the editor round-trips, so the refresh has no spurious difference left
+to act on.
+
+## References
+
+- Issue #939 (this phase), #938 (Phase 1 — package carve-out), #940 (Phase 3 — OSS hardening)
+- ADR-075 (the `@liminis/editor` package boundary), ADR-057 (knowledge
+  corrections pipeline), ADR-070 (dedicated Lexical node types), ADR-042 (MCP
+  stdio serialization)
+- Zusammen ADR-008 (comment anchor resolution), ADR-012 and its #47 amendment
+  (comment anchor as live mark) — the design sources for the ported machinery
+- `docs/project_notes/zusammen-editor-capability-map.md`

package/docs/decisions/adr-078.md

@@ -0,0 +1,243 @@
+# ADR-078: `@liminis/editor` Is Delivered by a Non-Bundling `tsc` Emit Behind `publishConfig`
+
+**Date:** 2026-08-05
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** ADR-075 (closes three of its deferrals; re-points the other two)
+**Issue:** #940
+
+## Context
+
+ADR-075 carved `@liminis/editor` out of `liminis-app` and fixed its public
+surface; ADR-077 added the unified annotation mechanism and a sixth export
+subpath. Both left the package consumed **in-workspace as raw TypeScript**:
+`main`/`types` point at `src/index.ts`, there is no build, `react`/`react-dom`/
+`lexical` are plain dependencies, and wiki-link behaviour depends on a pnpm
+`patchedDependencies` entry that exists only in this repository.
+
+That is enough for `liminis-app` and not enough for anyone else. #940's job was
+to make the package genuinely installable outside the monorepo — for Zusammen
+first, and for open-sourcing generally — without changing what it contains.
+
+Four things had to be decided, and each has a failure mode that is silent rather
+than loud.
+
+## Decision
+
+### 1. The build is a structure-preserving `tsc` emit. No bundler.
+
+`tsc -p tsconfig.build.json` emits ESM plus `.d.ts` module-for-module into
+`dist/`, followed by `tsc-alias --resolve-full-paths` to turn `tsc`'s
+extensionless relative specifiers into Node-ESM-resolvable `./x.js` ones. A
+small `scripts/copy-assets.mjs` places `styles.css` and the vendored module's
+license, which `tsc` does not copy.
+
+**Why not a bundler.** ADR-075 §4's `ReferenceError: Prism is not defined`
+reproduction — 138 e2e failures, blank renderer — was a *rolldown whole-graph
+chunking* artifact. Introducing a second rolldown here (via `tsdown`, or `vite
+build` in library mode) would recreate exactly that risk surface, and would make
+the six subpaths' isolation depend on chunking configuration whose failure mode
+is a silently heavier bundle rather than an error.
+
+With a non-bundling emit the isolation holds **by construction**:
+
+- `./markdown` cannot acquire `./headless`'s ~1.9 MB MathJax configuration
+  graph, because no chunker exists to hoist it there.
+- `./contract` cannot acquire *renderer* code, because the module boundary is
+  preserved verbatim. Note it does **not** make the entry zod-free: `contract.js`
+  re-exports `./types.js`, which does `import { z } from 'zod'`, so a *value*
+  import of `./contract` pulls zod in. What keeps zod out of the preload
+  boundary is `import type` erasure, not the subpath — as ADR-075 §1 says
+  plainly, and as `editor-package-wiring.test.ts` is the only thing pinning.
+  Emitting module-for-module preserves that property exactly as it was; it does
+  not strengthen it.
+- `lazy(() => import('./AnnotationSurface'))` survives as a real dynamic import
+  to a real file, so the annotation boundary is still a boundary.
+
+It also adds no bundler dependency: `typescript` was already a devDependency,
+and `tsc-alias` is a small, mature post-pass.
+
+Rejected alternatives: `tsdown` (0.x, and it pulls in the exact rolldown hazard);
+`vite build` lib mode (chunking config that fails silently on the
+`./markdown` ↔ `./headless` boundary).
+
+### 2. `publishConfig` swaps the manifest at pack time. `liminis-app` keeps consuming source.
+
+The checked-in `package.json` still has `main`/`types`/`exports` pointing at
+`src/`. A `publishConfig` block carries the `dist/` versions, and pnpm applies it
+at `pnpm pack` / `pnpm publish` — verified, including for a `private: true`
+package, so no `prepack` manifest-swap fallback was needed.
+
+**Why this rather than switching the app to built output.** `liminis-app`
+carries two pieces of configuration that exist *solely* because the package is
+raw TypeScript, both asserted by `editor-package-wiring.test.ts`:
+
+- `electron.vite.config.ts` — `externalizeDepsPlugin({ exclude: ['@liminis/editor'] })`
+  on `main` and `preload`.
+- `renderer/styles/main.css` — `@source "../../../../packages/editor/src"`,
+  because Tailwind v4's automatic source detection skips `node_modules`.
+
+Switching the app to built output invalidates **both at the same moment**, and
+they must then change in lockstep with the tests asserting them. The Tailwind
+half is the dangerous one: its failure mode is unstyled output, not an error, and
+the existing guard ("the `@source` path exists") would still pass against a path
+that exists but contains no class-bearing source.
+
+`publishConfig` makes that whole class of problem not arise. The cost is that
+the built path is exercised only in CI — which is what SC-005 mandates anyway.
+
+`private: true` is kept: publishing is out of scope for #940, and `private`
+blocks `publish` without blocking `pack`.
+
+### 3. `mdast-util-wiki-link` is vendored, not merely un-patched.
+
+The upstream package is vendored under
+`src/markdown/vendor/mdast-util-wiki-link/` (MIT, Mark Hudnall, attribution and
+license preserved and shipped in `dist/`), with the trailing-backslash fix from
+[#347](https://github.com/verveguy/liminis/issues/347) applied inline.
+
+**Why vendor rather than drop the patch.** Three reasons, in increasing order of
+how easy they are to miss:
+
+1. The strip must happen **before** `pageResolver` runs, so `data.permalink` and
+   `data.exists` derive from the cleaned target. `parse.ts`'s existing
+   `stripEscapedPipeFromWikiLinks` post-pass fixes only `node.value` and cannot
+   reproduce that. (It is kept, as defense-in-depth.)
+2. `liminis-app/src/main/canonical-chunker.ts` is a **second, independent
+   consumer** with no post-pass at all. It feeds the knowledge graph, and a
+   wiki-link parse change there is invisible to the editor suite *and* to e2e —
+   it surfaces only as subtly different indexed chunk text. It now imports
+   `wikiLinkFromMarkdown`/`wikiLinkToMarkdown` from `@liminis/editor/markdown`,
+   so the two consumers cannot drift onto *different wiki-link extensions*.
+
+   That is narrower than "the two parses cannot diverge", and the difference
+   matters. Sharing the extension closes the vendoring gap only. It does not
+   close a **pre-existing** divergence that predates this ADR: `parseMarkdown`
+   escapes the alias divider before parsing and carries an `_emptyAlias`
+   sentinel, while the chunker calls the extension directly. Without the escape,
+   GFM's table parser reaches the `|` in `[[target|alias]]` first and splits the
+   row — measured at 5 cells / 0 wiki-links where `parseMarkdown` gives 4 / 1.
+   So an aliased wiki-link inside a table is still chunked differently from how
+   the editor parses it. Closing that changes the text fed to the knowledge
+   graph, so it is deliberately left for a follow-up rather than folded into
+   #940's delivery work. `canonical-chunker.ts` carries the same caveat at the
+   import site.
+3. Upstream's `to-markdown` deep-imports `mdast-util-to-markdown/lib/util/safe`
+   from **v0.6.5** — a v0 duplicate of the v2 the editor already uses, plus
+   `@babel/runtime`, both pulled in to serve one function. The vendored copy uses
+   v2's `state.safe()` and drops both.
+
+The root `patchedDependencies` entry, the patch file, and the dependency are
+gone. `liminis-app/pnpm-workspace.yaml` carried a second, vestigial
+`patchedDependencies` block that pnpm never read; it is removed and the file now
+says plainly that nothing in it takes effect.
+
+### 4. The whole Lexical surface is peered, not just bare `lexical`.
+
+`react`, `react-dom`, `lexical` and all eleven `@lexical/*` packages move to
+`peerDependencies`, mirrored into `devDependencies` so the workspace install is
+unchanged.
+
+Peering bare `lexical` while shipping `@lexical/react` as a hard dependency still
+permits two Lexical registries in a consumer's tree — the precise failure peering
+exists to prevent. React is the same story with `Invalid hook call`. pnpm v8+ and
+npm v7+ auto-install peers, so the consumer burden is small.
+
+### 5. `sideEffects` stays undeclared. The question is closed, not deferred.
+
+ADR-075 §4 prohibits the field and deferred a re-decision to #940, on the theory
+that an external consumer of *built* output would have a different module graph
+and might legitimately need it.
+
+That theory does not survive decision 1. Because the build performs no chunking
+of its own, an external consumer's bundler sees the **same module graph**
+`liminis-app`'s bundler sees today. The prismjs hazard is therefore identical,
+not different, and the narrowing FR-011 would have permitted is not available.
+
+The measurement the field was wanted for does not need it either: FR-006 points
+at the `React.lazy()` boundary on `AnnotationSurface`, which is structural.
+
+ADR-075 §4's prohibition stands unchanged, and its guard in
+`editor-package-wiring.test.ts` stays. It is now closed rather than open.
+
+## Consequences
+
+- **`pnpm build:editor` and `pnpm verify:package`** exist at the repository root.
+  `verify:package` builds, packs, installs the tarball into
+  `examples/external-consumer` with `--ignore-workspace`, type-checks it under
+  both `moduleResolution: "bundler"` and `"nodenext"`, builds three measurement
+  arms, and asserts the entry-graph boundaries. A new `package-build` CI job runs
+  `verify:package` — and only that, since it builds the package itself as its
+  first step. `build:editor` is the standalone convenience alias for a local
+  build without the whole verification cycle.
+
+  `--ignore-workspace` is load-bearing: without it pnpm links the package by
+  symlink and the tarball — the thing under test — is never resolved.
+
+- **The measurements read a per-chunk `modules.json`, not the emitted
+  JavaScript.** Grepping bundled output for identifier substrings does not work:
+  minification loses the names, and a chunk *containing* the string `annotation`
+  says nothing about whether that chunk is ever loaded. What is asserted is the
+  **eager closure** — the entry chunk plus static imports, excluding dynamic
+  ones, because a `React.lazy()` chunk being separate is the mechanism under
+  test.
+
+  As measured when this landed: the `./markdown`-only arm is 91 modules with no
+  MathJax, no Lexical and no `react-dom`. The annotations-disabled arm loads no
+  annotation module eagerly across 655; `AnnotationSurface` appears only as an
+  async chunk. The enabled arm's identical probe finds four — the control that
+  keeps the first result from being a probe pointed in the wrong place.
+
+  Per ADR-077 the scope is `AnnotationSurface` and `annotations/` specifically,
+  *not* "the string `annotation` does not appear": unconditional `MarkNode`
+  registration and a statically-importable `annotationCommands.ts` are deliberate
+  exceptions and are expected in both arms.
+
+- **Two manifests now exist for one package**, and they can drift. The wiring
+  test asserts that every subpath in `exports` is mirrored into
+  `publishConfig.exports` pointing at `dist/`; without that, adding a seventh
+  subpath would leave external consumers silently unable to import it while every
+  in-repo check stayed green.
+
+- **`examples/` is outside the `packages/*` workspace glob** on purpose. A
+  fixture placed under `packages/` becomes a workspace member — pnpm links the
+  editor by symlink, and `pnpm -r typecheck`/`lint` pick it up — at which point
+  "external consumer" stops being true. `examples/demo/` and
+  `examples/external-consumer/` install the packed tarball instead.
+
+- **The package ships a LICENSE (MIT) and consumer documentation** —
+  `README.md` plus `docs/{editor-api,markdown-pipeline,annotations}.md`, inside
+  the tarball. The MIT declaration is scoped to `packages/editor` alone; the rest
+  of the repository remains unlicensed and `liminis-app` remains `UNLICENSED`.
+
+  Two silent failure modes are documented explicitly because nothing in the
+  package can catch them: not importing `@liminis/editor/styles.css` (unstyled
+  editor, invisible annotation markers), and Tailwind v4 skipping `node_modules`
+  in source detection (the editor's utility classes simply absent). An external
+  consumer has no `@source` directive handed to them the way `liminis-app` does,
+  so the README tells them what to write.
+
+- **An emitted-declaration global-leak probe** runs in `verify:package`.
+  `src/ambient/jsx.d.ts` performs a `declare global { namespace JSX }`
+  augmentation; had anything of that class reached `dist/`, every consumer would
+  inherit it. ADR-075 records the same class of defect caught once before, when
+  an `acquireVsCodeApi` global leaked through `.` and `./contract`.
+
+- **Two of ADR-075's #940 deferrals are not addressed here** and are re-pointed
+  at a follow-up: a DOM-free tsconfig project enforcing `./headless`'s contract,
+  and splitting `mathjax-config.ts` into lite and browser halves. Neither appears
+  in #940's requirements, and both are independent of delivery. Leaving ADR-075's
+  text claiming #940 covers them would be wrong, so it no longer does.
+
+- **Not done: publishing.** #940 proves publishability. The registry, versioning
+  and release-automation decisions are separate, and `private: true` remains as
+  the guard against doing it by accident.
+
+## References
+
+- ADR-075 — the package boundary, the six-subpath inventory, the `sideEffects`
+  landmine and its reproduction
+- ADR-077 — the annotation mechanism and its lazy boundary; the
+  host-must-import-`styles.css` contract
+- Issue #940 (this ADR), #938 (carve the package), #939 (annotation mechanism),
+  #347 (wiki links inside markdown tables — the origin of the vendored fix)