@liminis/editor 0.1.0-rc.1

package/docs/decisions/adr-082.md

@@ -0,0 +1,123 @@
+# ADR-082: `examples/demo` Is the Public Pages Site, and Its Documentation Is Generated from `README.md`
+
+**Date:** 2026-08-15
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #3 (verveguy/liminis-editor)
+
+## Context
+
+This package's `README.md` is adequate for someone who has already decided to
+adopt it; it does nothing for someone deciding *whether* to. Because
+`@liminis/editor`'s distinguishing claim — that what you type round-trips
+byte-for-byte to markdown on disk — cannot be shown in prose, this issue adds
+a public GitHub Pages site built around a live editor.
+
+verveguy/liminis-editor#2 had already grown `examples/demo` into exactly that
+shape: a fixture picker over the shared round-trip corpus, live-editing with
+`onChange` markdown state, importing only the package's public entry points.
+Two questions followed from reusing it:
+
+1. Does the Pages site wrap `examples/demo` as a new top-level app (e.g.
+   `site/`), or does `examples/demo` become the deployed artifact directly?
+2. FR-005–FR-009 require the site to document the seven subpath exports,
+   fourteen peer dependencies, the `sideEffects` landmine (ADR-075 §4), the
+   `0.x` versioning policy, and the annotation mechanism (ADR-077) — where
+   does that content live, given `README.md` already states five of those six
+   points accurately in prose?
+
+## Decision
+
+### 1. `examples/demo` *is* the Pages site, not a wrapper around it
+
+`scripts/build-site.mjs` builds `examples/demo` and only `examples/demo` —
+the same directory `pnpm demo` and `scripts/build-examples.mjs` already
+build — and its output (`examples/demo/dist`) is uploaded directly as the
+Pages artifact by `.github/workflows/pages.yml`.
+
+A new `site/` app importing the demo shell as a component was considered and
+rejected: it would either duplicate the fixture-picker UI or add an
+indirection layer for no functional gain, and it would turn FR-004's "one
+shared artifact, not a duplicated implementation" into something to police
+by discipline rather than something structurally true. With this decision, a
+contributor editing "the demo" is, by construction, also editing the public
+site — there is no second file tree that can silently drift from it.
+
+Two additions were made directly to `examples/demo` to carry the site's own
+requirements: a version badge (`App.jsx`, sourced from
+`VITE_LIMINIS_EDITOR_VERSION`, set by the Pages workflow from the triggering
+release's `tag_name` rather than `package.json`'s checked-in, pre-publish
+version) and a Demo/Documentation view toggle.
+
+### 2. The Documentation view renders `README.md`, generated, not re-authored
+
+`scripts/generate-demo-docs.mjs` reads the root `README.md` at build time and
+writes a gitignored `examples/demo/src/docs-content.generated.js`, which
+`examples/demo/src/Docs.jsx` renders with `react-markdown` + `remark-gfm`.
+This mirrors the pattern `scripts/generate-demo-fixtures.mjs` established for
+the fixture corpus (ADR-081): a build-time codegen step, not a runtime import
+reaching outside `examples/demo`, and a gitignored output regenerated by
+`pnpm demo`, `pnpm build:examples`, and `pnpm build:site` alike so no code
+path can consume a stale copy.
+
+A hand-written `site/docs/*.md` was considered and rejected. Five of the six
+required documentation points (exports, peer dependencies, annotations) were
+already accurate prose in `README.md`; re-deriving them by hand in a second
+location would have been exactly the duplication ADR-081 avoided for
+fixtures, with the same drift risk. The two genuine content gaps — a
+Lexical-free column on the exports table, and the `sideEffects` landmine and
+versioning-policy sections — were instead written into `README.md` itself,
+so the published npm tarball's own shipped documentation improves along with
+the site, rather than the site accumulating content the tarball doesn't
+carry.
+
+`tests/adr-citations.test.ts`'s scan of `README.md` + `docs/**` (excluding
+`docs/decisions/`) is not extended to also cover
+`docs-content.generated.js`. Because the generated file is a verbatim copy of
+`README.md`, a dangling `ADR-NNN` citation is caught at the source before it
+ever reaches the generated copy; scanning the copy too would just be a second
+check of the same string.
+
+## Consequences
+
+**Good:**
+
+- FR-004/SC-004 ("one shared artifact") holds by construction: there is one
+  `App.jsx`, one `package.json`, one build output, used by `pnpm demo`,
+  `pnpm build:examples`, and the Pages deploy alike.
+- FR-005–FR-009's six documentation points have exactly one copy each, in
+  `README.md`, already covered by the existing ADR-citation guard.
+- Editing `README.md` to keep it accurate for npm/GitHub browsing
+  automatically keeps the Pages site's Documentation tab accurate too, with
+  no second edit to remember.
+
+**Bad / accepted:**
+
+- `examples/demo`'s `README.md` and source now serve two audiences (a local
+  package-demo reader and a public site visitor) rather than one; a change
+  made for one has to be considered against the other, though in practice
+  the two have stayed aligned so far.
+- Rendering all of `README.md` on the Documentation tab means any section
+  that assumes an npm/GitHub reading context (for example, the "This package
+  is not published" install-warning language, current as of this decision)
+  reads on the public site exactly as written — no site-specific editing
+  layer exists to soften it. This self-corrects whenever `README.md` itself
+  is updated for the eventual publish flip; it is not something this
+  decision defers solving, since no site-only content divergence was wanted
+  in the first place.
+- `docs-content.generated.js`, like `fixtures.generated.js`, is gitignored,
+  so a reviewer checking "does the Documentation tab still render correctly"
+  after a `README.md` edit has to run the generator locally rather than
+  reading it in the PR diff.
+
+## References
+
+- Issue #3 (this decision), verveguy/liminis-editor#2 (the web shell this
+  decision reuses as the site)
+- `docs/decisions/adr-081.md` (the codegen pattern this decision applies a
+  second time, to `README.md` instead of the fixture corpus)
+- `docs/decisions/adr-075.md` §4 (the `sideEffects` landmine now documented
+  in `README.md` and, by extension, on the site)
+- `docs/decisions/adr-077.md` (the annotation mechanism now documented in
+  `README.md` and, by extension, on the site)

package/docs/decisions/adr-083.md

@@ -0,0 +1,204 @@
+# ADR-083: Backslash-Escape Provenance Is Captured at Parse Time and Carried Through as a Per-Character Style Hint
+
+**Date:** 2026-08-16
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #17 (verveguy/liminis-editor)
+
+## Context
+
+A backslash-escaped underscore lost its escape on a no-edit round trip
+(`A backslash\_underscore` → `A backslash_underscore`), while a backslash-escaped
+asterisk on the same line did not. This is not cosmetic: the escape exists to stop
+`_` from being read as an emphasis delimiter, and dropping it silently, on a save
+where the user changed nothing, is the same failure class as #973 (markdown
+serializer non-idempotence).
+
+The root cause is structural, not a stray regex bug. `fromMarkdown` (standard
+CommonMark parsing) discards escape provenance at parse time: `\_underscore` and
+`_underscore` both decode to the identical mdast `text` value
+(`"_underscore"`) — there is no flag anywhere in mdast or Lexical recording "this
+character had a backslash in front of it in the original file." Two existing
+`stringify.ts` post-processes (intraword-underscore-unescape, added for #901;
+bracket-preservation, added for #921) strip mdast-util-to-markdown's own
+conservative default escaping of `_`/`[`/`]` back off, because CommonMark doesn't
+always require escaping those characters and the library over-escapes them by
+default. Both post-processes operate purely on the shape of the final string, so
+they cannot distinguish "the library added this escape and it's unneeded" from
+"the user wrote this escape and meant it" — the two cases are byte-identical once
+parsed. `\*` never had this problem only because CommonMark's own rule requires
+escaping `*` unconditionally in the position it appears, so mdast-util-to-markdown
+re-escapes it regardless, and no Liminis post-process ever touches it.
+
+Two designs were available for recovering the lost provenance:
+
+1. Embed an invisible Private-Use-Area marker character directly in Lexical's
+   live text content at parse/import time, stripped back off at stringify time —
+   mirroring `annotate-sentinels.ts`'s existing PUA-sentinel mechanism.
+2. Capture provenance at parse time, before anything else touches the tree, and
+   carry it through Lexical as metadata attached to the `TextNode` rather than
+   embedded in its text content — restoring the real backslash only inside a
+   single, transient `stringifyMarkdown` call.
+
+## Decision
+
+### 1. Capture at parse time; never re-derive downstream
+
+`splitTextNodeEscapes` (called by `splitEscapedPunctuation`, the last step of
+`parseMarkdown`, after `annotateEmphasisMarkers`) replay-decodes each `text`
+node's raw source span character-by-character — consuming a backslash plus one
+of CommonMark's escapable ASCII punctuation characters as a single decoded
+character, exactly as `fromMarkdown` itself does — and compares the result
+against `node.value`. Whenever they don't match exactly (an HTML entity or other
+untracked transform sharing the span), the node is left untouched rather than
+split at a possibly-wrong offset: a missed protection reproduces today's
+pre-existing defect, but a wrong split would corrupt text. This mirrors
+`recordOffsetSpan`'s own width-mismatch bail-out in `mdastToLexical.ts`, an
+existing precedent for the same "decline rather than guess" trade-off.
+
+Otherwise, the node is split into siblings at every backslash-escaped instance
+of the seven characters this issue scopes (`* _ \` [ ] # \`, per the issue's own
+named set): untouched runs stay ordinary `text` nodes, and each protected
+character becomes its own single-character `text` node carrying
+`data._forceEscape = true`. This is deliberately uniform across all seven
+characters, not special-cased to the two or three Research suspected were
+actually broken — a character the library already escapes correctly (`*`,
+backtick, line-start `#`, a lone `\`) simply flows through the same mechanism
+with no behavior change, since it only ever *preserves* an escape the user
+actually wrote and never invents one. That by-construction property is what
+satisfies the "must not over-escape" requirement, rather than a per-character
+heuristic that could be wrong for an untested case.
+
+### 2. Carry as a per-character `TextNode` style hint, not a live-text sentinel
+
+Design (1) above — a PUA marker spliced into editable Lexical text — was
+rejected. Unlike `annotate-sentinels.ts`'s existing use, which is scoped to a
+single, transient export call, this marker would persist in the actual
+*editable* document for the whole session whenever the user opens and edits the
+file, not just a one-shot round trip: risk of a stray PUA character surviving
+into cursor placement, selection, copy/paste, spellcheck, or a newly-typed
+document abutting it.
+
+Instead, `setForceEscape` (`mdastToLexical.ts`'s `convertText`) sets a
+`--md-force-escape:1` style hint on the `TextNode`, mirroring the established
+`--md-emphasis-marker`/`--md-strong-marker` precedent that already carries the
+source's original `_`/`*` marker character through the same round trip. This has
+zero footprint on editable content. Both `convertTextNode` (the single-node
+export path) and `convertFormattedRun` (the merged-run path taken when a node
+sits inside emphasis/strong, or when a live annotation mark forces adjacent
+same-format siblings to merge) read the hint in `lexicalToMdast.ts` — an escaped
+character inside emphasis/strong (e.g. `*text \_x\_*`) always takes the
+merged-run path even on a pure no-edit round trip, so reading the hint in only
+one of the two would leave that adjacency case, called out explicitly in the
+issue's edge cases, unfixed.
+
+### 3. Restore via a transient placeholder and a dedicated node type, not by editing the existing regexes
+
+Making the two existing blind-strip post-processes provenance-aware — teaching
+them to recognize a real backslash as "leave alone" — was considered and
+rejected. Their patterns have no per-node knowledge; they operate on the final
+concatenated string. Testing confirmed that simply restoring the real backslash
+before those regexes run still lets the bracket-preservation regex (which has no
+adjacency/flanking guard, unlike the underscore one) misfire and strip a
+genuinely user-escaped `\[...\]` pair — stacking two independent escape
+decisions that can disagree.
+
+Instead, `convertForceEscapeTextNodes` (a `stringify.ts` pre-process) converts
+every `{type: 'text', data: {_forceEscape: true}}` node into a dedicated
+`escapedChar` node, whose custom `toMarkdown` handler emits a transient,
+backslash-free placeholder (`\u{E004}<char>\u{E004}`, distinct from
+`annotate-sentinels.ts`'s `E000`-`E003` range, module-local to `stringify.ts`
+and never exported) instead of running the character through the normal
+text-escaping path. Being backslash-free, the placeholder is provably invisible
+to both existing post-processes during their pass, so **neither one needed to
+change**. Only after every other post-process has already run does a final step
+replace each placeholder-wrapped character with a real `\<char>`, unconditionally
+restoring the backslash regardless of whatever the default handler emitted
+underneath. The placeholder never touches Lexical or live document state — like
+`annotate-sentinels.ts`'s own tokens, it exists only inside a single
+`stringifyMarkdown` call, on a mdast tree reconstructed fresh from Lexical at
+export time and discarded immediately after.
+
+Two adjacent force-escaped characters in the source (e.g. `\*\*`) can reach this
+pre-process already fused into one multi-character node, because Lexical's own
+reconciliation merges adjacent `TextNode`s sharing identical format and style,
+and two independent single-character force-escape nodes share the same
+`--md-force-escape:1` style. Since only single-character force-escaped nodes are
+ever produced upstream, every character of a fused node was independently
+force-escaped, so the pre-process expands such a node back into one `escapedChar`
+node per character rather than assuming length 1.
+
+An annotate-serialize sentinel token (see `annotate-sentinels.ts`, ADR-077's
+underlying mechanism) can also land inside a force-escaped node's text, if that
+exact `TextNode` instance happens to be a live annotation mark's boundary leaf.
+The pre-process uses a new `splitOnSentinelTokens` helper (added to
+`annotate-sentinels.ts`, alongside its existing `stripAnnotateSentinels`) to
+split those parts out first and leave them as plain, unescaped text — otherwise
+the token's own id characters would themselves come back out individually
+backslash-escaped, breaking annotate mode's "differs from a plain export only by
+its sentinel tokens" invariant (#970) for any fixture containing a force-escaped
+character.
+
+## Consequences
+
+**Good:**
+
+- `\*`, `\_`, `` \` ``, `\[`, `\]`, `\#`, and `\\` all round-trip byte-identically
+  in a meaningful context, and the fix is a fixed point on a second pass (ADR-076)
+  — see the `17-*` fixture group in
+  `src/app/mapper/__tests__/fixtures/roundtrip/README.md`.
+- The fix is provably non-over-escaping by construction: it only ever restores a
+  backslash the source actually had, never adds one, so `898-underscore-link.md`
+  (`mac_onboarding.sh`) and the bracket-related `known-defects/` fixtures needed
+  no changes.
+- Neither existing blind-strip post-process was modified, eliminating the risk
+  (flagged during planning) of two independent escape-decision mechanisms
+  disagreeing on the same character.
+- `recordOffsetSpan`'s width-mismatch bail-out in `mdastToLexical.ts` needed no
+  code change — splitting a text node at escape boundaries is exactly the kind
+  of source-width/decoded-length mismatch it was already designed to decline
+  gracefully on, one sub-span at a time instead of one whole node at a time. This
+  is a net improvement to `offset-spans.test.ts`'s existing coverage: a plain
+  run of text beside an escape now gets a valid, usable span where previously the
+  entire containing node was dropped.
+
+**Bad / accepted:**
+
+- The escaped-backslash-then-bare-underscore edge case (`\\_`) is not
+  byte-identical on the first pass: the restored literal backslash is not
+  alphanumeric, so the pipeline's own pre-existing, pre-#17 conservative default
+  (intraword-underscore-unescape only fires when *both* flanking characters are
+  alphanumeric) leaves the following bare underscore escaped too. This is not a
+  new over-escape introduced by this fix — `898-underscore-link.md` already
+  accepts the same conservative policy for other non-alphanumeric-flanked cases
+  — so `17-escaped-backslash-then-underscore.md` carries an `.expected.md`
+  sidecar rather than asserting byte-identity, per ADR-076's normalization
+  allowance. The second pass is still a fixed point.
+- A character reference (e.g. `&amp;`) anywhere in the same `fromMarkdown`-merged
+  text run as an escaped target character suppresses protection for the whole
+  run, not just the entity reference's own span, because `fromMarkdown` merges
+  entity references and surrounding literal text into one `text` node before
+  `splitTextNodeEscapes` ever sees it. This is a narrow, defect-shaped
+  limitation — not a regression, since no protection existed there before this
+  fix either — and is documented at the bail-out site in `parse.ts` and covered
+  by a dedicated test in `parse.test.ts`.
+- `convertTextNode` and `convertFormattedRun` in `lexicalToMdast.ts` now
+  duplicate a third piece of marker-reading logic (alongside the existing
+  `--md-strong-marker`/`--md-emphasis-marker` reads), increasing the surface
+  area that could drift out of sync in a future change to one but not the other.
+  Accepted because it follows an established, already-reviewed pattern in this
+  codebase rather than inventing a new one.
+
+## References
+
+- Issue #17 (this decision)
+- `docs/decisions/adr-076.md` (the fixed-point round-trip guarantee this fix
+  upholds, and the `.expected.md`/normalization allowance used for the `\\_`
+  edge case)
+- `docs/decisions/adr-077.md` (the annotation mechanism whose sentinel tokens
+  this fix's placeholder must stay distinguishable from)
+- `src/app/mapper/__tests__/fixtures/roundtrip/README.md`, `## The 973-* fixture
+  set` section (the `--md-emphasis-marker`/`--md-strong-marker` style-hint
+  precedent this fix's `--md-force-escape` hint mirrors) and `## The 17-*
+  fixture set` section (this fix's own as-built documentation)

package/docs/decisions/adr-084.md

@@ -0,0 +1,179 @@
+# ADR-084: Ordered Task-Item Checkboxes Are Rendered by `CustomListItemNode` Itself, Never by Lexical's `listType === 'check'` Gate
+
+**Date:** 2026-08-16
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #12 (verveguy/liminis-editor)
+
+## Context
+
+An ordered task item (`1. [ ] Task one`) used to render its checkbox marker
+as literal `[ ] `/`[x] ` text prepended to the item's first paragraph by
+`convertListItem` (`src/app/mapper/mdastToLexical.ts`), because
+`@lexical/list`'s checklist rendering — DOM attributes/classes, click
+handling (`@lexical/react`'s `CheckListPlugin`), and keyboard handling — is
+entirely gated on the *parent list's* `listType` being `'check'`, and
+Lexical has no `'check'`-typed list that is also numbered. The per-item
+checked state was already stored correctly and independently on
+`CustomListItemNode.__taskChecked` (added for #905/#914's mixed-list
+problem); only the *rendering* declined to use it.
+
+Reading the pinned `@lexical/list@0.44.0`/`@lexical/react@0.44.0` source
+directly (rather than trusting its public API surface) confirmed every
+mechanism a checkbox needs is private and individually keyed off
+`listType === 'check'`:
+
+- `ListItemNode.updateListItemDOM`/`updateListItemChecked`/
+  `$setListItemThemeClassNames` (DOM `role`/`aria-checked`/theme classes) —
+  all unexported.
+- `registerCheckList`'s `handleCheckItemEvent`/`handleClick`/
+  `getActiveCheckListItem` (click and keyboard handling) — gated on the DOM
+  list element's `__lexicalListType === 'check'` property, unexported.
+- `ListNode`'s own `$config().$transform` (`updateChildrenListItemValue`)
+  actively **resets** any list item's raw `__checked` back to `undefined`
+  whenever the parent list isn't `'check'`-typed — a live transform, not a
+  one-time check.
+
+## Decision
+
+### 1. `CustomListItemNode` renders its own ordered-task checkbox, from `__taskChecked`
+
+`CustomListItemNode.createDOM`/`updateDOM` call `super.createDOM`/
+`super.updateDOM` first (stock behavior already strips `role`/`tabIndex`/
+`aria-checked` for a non-`'check'` parent), then layer on a checkbox
+affordance — `role="checkbox"`, `aria-checked`, and new
+`editor-listitem-ordered-checked`/`-unchecked` CSS classes (applied
+directly via `classList`, not wired through Lexical's `editorTheme` object
+the way stock's own `listitemChecked`/`listitemUnchecked` are) — driven
+directly by `this.__taskChecked`, gated on the parent list's `listType`
+being `'number'` and the item being a leaf (mirroring stock's own
+`!$isListNode(getFirstChild())` guard). This reuses the "dedicated
+node-owned mechanism over a pattern hack" precedent already established by
+ADR-070, applied here to a private-library gate rather than a markdown
+pattern.
+
+The alternative — finding some way to make Lexical's own `'check'`-typed
+rendering also apply to a `'number'`-typed list — was not pursued: every
+mechanism above is private, unexported, and would need forking, not
+extending, and `ListNode`'s reset transform would still need to be defeated
+regardless (see below).
+
+New CSS classes (`editor-listitem-ordered-checked`/`-unchecked` in
+`styles.css`) were required rather than reusing the existing
+`editor-listitem-checked`/`-unchecked`: those set `list-style-type: none`
+and pull the marker box back with a negative `margin-left`, which would
+suppress `<ol>`'s native decimal numbering. The new classes instead claim
+space via the item's own `padding-left`, leaving the native marker
+undisturbed in the `<ol>`'s own padding area.
+
+### 2. Toggling an ordered item's checkbox must call `setTaskChecked()` exclusively, never `setChecked()`/`toggleChecked()`
+
+`OrderedTaskListPlugin` (`src/app/editor/OrderedTaskListPlugin.tsx`) — a new
+root-element click listener, since `CheckListPlugin`'s own listener never
+fires for a `'number'`-typed list — replicates `@lexical/list`'s own
+`handleCheckItemEvent` hit-box geometry (`clientX` vs. the rendered
+`::before` pseudo-element's width, via `calculateZoomLevel` from
+`@lexical/utils`) so clicking anywhere across the visible checkbox toggles
+it, matching the feel of the unordered checklist. On a hit, it calls
+`node.setTaskChecked(!node.getTaskChecked())` inside `editor.update()`.
+
+This is a hard rule, not a style preference. `ListNode`'s own transform
+(`updateChildrenListItemValue`) resets any list item's *raw* `__checked`
+field back to `undefined` on every reconciliation pass, for any list whose
+`listType !== 'check'` — which every ordered list is. `CustomListItemNode`
+overrides `setChecked()` to sync `__taskChecked` from the same argument (to
+support the #905/#914 live-promotion case, where clicking an *unordered*
+checklist's checkbox on a previously-plain item must promote it to a real
+task). If an ordered item's toggle handler called `setChecked()` or
+`toggleChecked()`, it would look correct on the triggering render and then
+be silently reset — `__checked` back to `undefined`, cascading through the
+override into `__taskChecked` too — on the very next reconciliation. The
+importer (`convertListItem`) already avoided this by never writing raw
+`__checked` for ordered items (`useChecked` stays `undefined`); the click
+handler must preserve that invariant symmetrically. Because `__checked`
+stays permanently `undefined` for ordered items under this rule, the reset
+transform's own guard (`__checked != null`) never fires — no other code
+path needed to change to avoid it.
+
+### 3. `stringify.ts`'s `addCheckboxTextToOrderedLists` is left in place, unmodified, despite being redundant
+
+The export side (`src/app/mapper/lexicalToMdast.ts`) already read
+`getTaskChecked()` rather than the gated `getChecked()`, so once the
+importer stopped prefixing marker text, `checkedForOutput` simply became
+the item's real per-item state with no export-side code change needed.
+
+Separately, `src/markdown/stringify.ts` contains its own workaround,
+`addCheckboxTextToOrderedLists`, which manually rewrites an ordered list's
+mdast tree to prepend literal `[ ]`/`[x] ` text before `toMarkdown()` runs,
+on the documented premise that "GFM only outputs checkboxes for unordered
+lists." That premise does not hold for this repo's pinned
+`mdast-util-gfm-task-list-item@2.0.0` — its `listItemWithTaskListItem`
+handler already matches `(?:[*+-]|\d+\.)` and emits a marker after either
+kind of list marker natively. The function is therefore redundant, but not
+incorrect: tracing a concrete example through the full pipeline confirmed
+it still fires exactly once per checked/unchecked item and still produces
+byte-identical output to the pre-fix behavior. Removing it was considered
+and rejected for this issue — it has no required benefit within this
+issue's scope (a rendering defect, not a serialization one) and would add
+verification surface against a part of the pipeline this issue's spec
+explicitly states does not need to change. It is left as a documented,
+deliberate trap: a future contributor who finds it and "cleans it up"
+without reading this ADR should not be surprised that doing so is safe on
+its own (the GFM dependency already covers it) but was out of scope here.
+
+## Consequences
+
+**Good:**
+
+- FR-001–FR-003 hold: an ordered task item renders a real checkbox with no
+  editable marker text, sourced from its own stored state, independent of
+  the parent list's rendering mode.
+- FR-004/FR-005 hold: toggling works via a dedicated plugin and round-trips
+  to exactly one marker in the exported Markdown, with FR-006's fixed-point
+  guarantee unaffected — the state model and markdown layers needed no
+  changes.
+- FR-007/FR-008 hold structurally, not by extra guarding: a plain item in a
+  mixed ordered list has `__taskChecked === null`, so
+  `CustomListItemNode`'s own gate already excludes it from checkbox
+  rendering, and unordered checklists are entirely untouched by any of this
+  (different classes, different plugin, same `CheckListPlugin` as before).
+- The reset-transform trap is now a one-time, well-understood constraint
+  documented in one place (this ADR, plus inline comments at both
+  `CustomListItemNode.setChecked()` and `OrderedTaskListPlugin`) rather than
+  a bug waiting to be rediscovered by a future toggle-handling change.
+
+**Bad / accepted:**
+
+- Two independent checkbox rendering/interaction code paths now exist —
+  Lexical's own for unordered lists, this package's own for ordered lists —
+  rather than one. This is inherent to the constraint (Lexical's mechanisms
+  are private and gate-locked to `'check'`), not a choice that could be
+  designed away within this issue's scope.
+- `OrderedTaskListPlugin`'s hit-box geometry duplicates `@lexical/list`'s
+  private `handleCheckItemEvent` formula by copying it, not importing it
+  (it isn't exported). A future `@lexical/list` upgrade that changes that
+  formula would need this plugin updated in step, silently, with no type
+  error to catch the drift.
+- `addCheckboxTextToOrderedLists` remains dead-but-correct code with a
+  now-inaccurate docstring premise ("GFM only outputs checkboxes for
+  unordered lists"), left in place deliberately rather than fixed, which
+  future readers of that file alone (not this ADR) may find confusing.
+
+## References
+
+- Issue #12 (this decision)
+- `docs/decisions/adr-070.md` ("Dedicated Lexical Node Types vs.
+  Paragraph-Pattern Detection") — the general precedent this decision
+  applies to a private-library rendering gate rather than a markdown
+  pattern.
+- `docs/decisions/adr-076.md` ("Markdown Serialization Is a Fixed Point") —
+  the fixed-point guarantee FR-006 restates for this issue; no new
+  infrastructure was needed to satisfy it.
+- `src/app/editor/nodes/CustomListItemNode.tsx` — `__taskChecked`, the
+  `createDOM`/`updateDOM` override, and the `setChecked()` override this
+  decision requires ordered-item toggling to route around.
+- `src/app/editor/OrderedTaskListPlugin.tsx` — the click-to-toggle
+  implementation.
+- `src/markdown/stringify.ts` — `addCheckboxTextToOrderedLists`, left
+  unmodified per this decision.

package/docs/editor-api.md

@@ -0,0 +1,106 @@
+# `<Editor>` and the host seam
+
+## `<Editor>`
+
+```tsx
+import { Editor } from '@liminis/editor'
+```
+
+The editor takes markdown in and hands markdown back. Lexical state is an
+implementation detail you never have to touch.
+
+### Content
+
+| Prop | Type | Notes |
+|---|---|---|
+| `initialContent` | `string` | Markdown text. **Required.** |
+| `onChange` | `(markdown: string) => void` | Fires on edit with the serialized markdown. **Required.** |
+| `contentVersion` | `number` | Bump to force a re-import of `initialContent`. Without it, changing `initialContent` alone does not reload the document — that is deliberate, so a controlled `onChange` loop does not fight the user's cursor. |
+| `editable` | `boolean` | Default `true`. `false` renders read-only. A `toolbar`-surfaced annotation create affordance (see the Annotations section of the package README) remains reachable via selection either way; formatting controls do not render when read-only. |
+| `filePath` | `string` | The path of the file being edited. Drives file-type-specific UI (e.g. `.mdc`). |
+
+### Cursor and selection
+
+| Prop | Type | Notes |
+|---|---|---|
+| `cursorToRestoreRef` | `RefObject<CursorState \| null>` | A ref, not a value — it is read inside effects, not during render, so restoring a cursor never triggers a render pass. |
+| `onCursorChange` | `(cursor: CursorState) => void` | Fires as the caret moves. Pair with `cursorToRestoreRef` to persist cursor position across document switches. |
+| `onSelectionContextMenu` | `(event: SelectionContextMenuEvent) => void` | Fires on context menu over a selection. Your app renders the menu. |
+
+### Assets and links
+
+| Prop | Type | Notes |
+|---|---|---|
+| `assetBaseUri` | `string` | Base URI images resolve against. |
+| `documentDirUri` | `string` | URI of the directory containing the document, for relative-path resolution. |
+| `imagePathResolution` | `ImagePathResolution` | How relative image paths are interpreted. |
+| `resolveLocalAsset` | `(relativePath: string) => Promise<string \| null>` | Resolve a workspace-relative path to a data URL. Return `null` for "not found" — the editor renders a broken-image placeholder rather than throwing. |
+
+### Corrections
+
+| Prop | Type | Notes |
+|---|---|---|
+| `onSubstitutionDetected` | `(oldTerm: string, newTerm: string) => void` | Fires after a debounce when a single-word substitution is detected. |
+| `sweepRef` | `MutableRefObject<SweepFn \| null>` | Populated with a sweep function while the ambient-correction plugin is active. |
+
+### Annotations
+
+All optional; supplying `annotationKinds` is what turns the mechanism on. See
+[`annotations.md`](./annotations.md).
+
+| Prop | Type | Notes |
+|---|---|---|
+| `annotationKinds` | `AnnotationKindConfigs` | Per-kind configuration. Omit it and no annotation module is loaded. |
+| `annotations` | `Annotation[]` | Host-supplied annotations to render markers for, already resolved. |
+| `activeAnnotationId` | `string \| null` | Which annotation is active, for marker styling. |
+| `scrollToAnnotation` | `{ id: string; nonce: number } \| null` | Host-driven scroll signal. Bump `nonce` to re-scroll to the same id. |
+| `onCreateAnnotation` | `(event: AnnotationCreateEvent) => void` | Fires when a user creates one via a kind's create affordance. |
+| `onActivateAnnotation` | `(id: string) => void` | Fires when a marker is activated. Your app opens its own panel. |
+| `annotationEditorHandleRef` | `MutableRefObject<AnnotationEditorHandle \| null>` | Imperative handle for the mounted editor's live marks. |
+| `annotationLogger` | `{ warn(message, ...args): void }` | Injected, so the package never imports a host logger. |
+
+## The host seam
+
+The package boundary is drawn at **persistence**: text ranges, marks, rendering
+and in-document UX are the package's; storage, lifecycle, identity and
+higher-level panels are yours. Everything the package needs from you crosses
+that seam through `EditorHostServices`.
+
+Every member is optional and has a safe default, so `<Editor>` works with no
+provider at all. Wrap it when you want to supply real services:
+
+```tsx
+import { EditorHostProvider, Editor } from '@liminis/editor'
+
+<EditorHostProvider services={{ logger, bridge, resolveWikiLinks, notifyError }}>
+  <Editor initialContent={md} onChange={setMd} />
+</EditorHostProvider>
+```
+
+### `EditorHostServices`
+
+| Member | Type | Purpose |
+|---|---|---|
+| `bridge` | `EditorHostBridge` | The channel to your environment. Two methods only: `postMessage(message)` and `addMessageHandler(handler)` returning an unsubscribe. Every higher-level helper (`requestInit`, `applyTextEdits`, `writeAsset`, `openLink`) is built on `postMessage` inside the package, so every host adapter emits byte-identical payloads. Defaults to a no-op bridge. |
+| `logger` | `(namespace: string) => EditorLogger` | Namespaced logger factory. `EditorLogger` is `{ debug, info, warn, error }`, structurally compatible with most app loggers. |
+| `resolveWikiLinks` | `(targets: string[]) => Promise<Record<string, string \| null>>` | Map wiki-link targets to existing paths; `null` for unresolved. Drives the "this page does not exist yet" styling. |
+| `onScrollToAnchor` | `(cb: (anchor: string) => void) => () => void` | Subscribe to host-driven scroll requests. Returns an unsubscribe. |
+| `notifyError` | `(message: string, description?: string) => void` | Surface a user-visible error. Defaults to a console warning. |
+| `corrections` | `CorrectionHostServices` | Persistence and knowledge-graph services backing the correction feature: `readCorrections`, `writeCorrections`, `suggestEntities`, `suggestPassages`, `applyCorrections`. The in-editor correction UI is package-side; the file and the graph are yours. |
+
+Read the resolved set inside your own components with `useEditorHost()`.
+`resolveHostServices()` applies the defaults if you need them directly.
+
+### The message contract
+
+`@liminis/editor/contract` exports the `HostToUIMessage` / `UIToHostMessage`
+shapes and nothing else. It exists so a boundary that must not pull renderer
+code into its bundle — an Electron preload script is the canonical case — can
+name the message types.
+
+```ts
+import type { HostToUIMessage, UIToHostMessage } from '@liminis/editor/contract'
+```
+
+Use `import type`. A value import from this entry pulls in `zod`, which is
+exactly what the entry exists to avoid.