@liminis/editor 0.2.1 → 0.3.0

package/docs/decisions/adr-92-lexical-peer-range-policy.md

@@ -0,0 +1,152 @@
+# ADR-92: The Lexical Peer Range Bumps Forward by a Narrow Single Caret, Never a Wide Band
+
+**Date:** 2026-08-20
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #92 (verveguy/liminis-editor)
+
+## Context
+
+Every published version of `@liminis/editor`, including `0.2.2`, declared its
+Lexical peer range as `^0.44.0` across all twelve Lexical family packages
+(`lexical` and eleven `@lexical/*` scoped packages). Lexical itself moved on
+to `0.49.0`. Because Lexical is a `0.x` package, `^0.44.0` resolves under
+semver to `>=0.44.0 <0.45.0` — it admits patch releases of 0.44 only, and
+excludes every 0.45+ release regardless of whether that particular release
+was actually breaking. The practical effect: this package pinned every host
+application to a Lexical line five minors behind, with no published version
+offering a path forward.
+
+This surfaced while refreshing `liminis-app`'s dependencies
+(verveguy/liminis#1026): the Lexical family was bumped 0.44.0 → 0.49.0 and
+tested in isolation there. It passed `liminis-app`'s own typecheck, lint,
+build, and 3275-test suite — and was still wrong, because `liminis-app` would
+have shipped in violation of this package's declared peer contract. That
+app's suite does not exercise the editor deeply enough for a green run to be
+evidence of Lexical compatibility; the only suite that can answer that
+question is this package's own.
+
+The peer-range shape was an open question, not a foregone conclusion: widen
+the range to admit 0.44 through 0.49 (matching the issue's own suggested
+example), or narrow it to `^0.49.0` and drop 0.44–0.48 support outright.
+
+## Decision
+
+**The twelve Lexical peer ranges move to `^0.49.0` — a narrow single-caret
+bump, not a wide multi-version band.** This is a deliberate, permanent
+policy choice about how this package treats Lexical peer ranges going
+forward, not a one-time bump: every future Lexical minor this package adopts
+gets the same treatment — the range moves forward by exactly one caret,
+paired with running the full suite against the new version, rather than
+widening to claim a span of untested minors as compatible.
+
+### Why narrow, not wide
+
+**Widening a peer range later is patch-safe; narrowing one is breaking.**
+Starting narrow keeps both options open — if a wide band is ever wanted, it
+can be added without breaking anyone. Starting wide commits the package to a
+claim it can only walk back by breaking whoever relied on the wide end.
+
+**This package's existing range philosophy for `react` does not transfer to
+Lexical.** The `//peerDependencies` manifest comment already documents that
+ranges are "the compatibility contract, not the tested matrix," and that
+narrowing `react`'s range to match its `devDependency` version "would only
+reject working consumers." That reasoning is sound for React specifically
+*because* React's untested span sits inside a **stable major** — a
+regression there is a bug in React, not a permitted outcome of its
+versioning scheme. Lexical is `0.x`, where semver explicitly permits every
+minor release to be breaking. A range like `>=0.44.0 <0.50.0` would assert
+compatibility with six minors, five of them never run against this
+package's own suite — a materially different, and unjustified, claim.
+
+**No known consumer wants Lexical 0.44.** Both known consumers of this
+package (`liminis-app` and the package's own test/build pipeline) are moving
+*toward* 0.49, not sitting on 0.44 and wanting to stay there. The wide
+band's benefit — "don't reject a working consumer on an old version" — is
+close to hypothetical here, while its cost — asserting untested compatibility
+across four intermediate minors known to contain breaking changes (see
+Consequences) — is real.
+
+A wide band remains available later, but only backed by CI matrix testing
+across the band's endpoints — that is separate work, out of scope for this
+decision.
+
+### What was verified before this decision was acted on
+
+The twelve packages were bumped to `0.49.0` in both `peerDependencies` and
+`devDependencies` (kept in lockstep, per this package's existing pairing
+between the tested version and the declared floor), and the full
+verification chain — `pnpm typecheck`, `pnpm lint`, `pnpm build`,
+`pnpm test` (1591 tests), and `pnpm verify:package` (the packed-tarball
+install-and-typecheck check against a fresh consumer) — ran clean with **no
+source changes required**, despite Lexical's own changelog listing several
+breaking changes in the 0.45–0.49 window (a `config()` protocol rework for
+node classes in 0.49.0; `insertNodes` linebreak-handling changes and a
+deprecated-export removal in 0.46.0; selection/backspace/reconcile changes
+in 0.45.0). This package's sixteen custom Lexical node classes all define
+explicit `getType`/`clone`/`importJSON` statics rather than relying on
+auto-synthesis, which structurally avoided the highest-risk part of the
+0.49.0 change; the rest of the changelog's items apparently do not intersect
+this package's actual usage patterns, since the suite exercises them and
+passed unmodified.
+
+## Consequences
+
+**Positive:**
+
+- Consumers can now install this package alongside the current Lexical
+  release; the multi-minor stall the issue described cannot recur until
+  Lexical ships another minor this package hasn't yet adopted.
+- The Lexical peer range's compatibility claim is now backed by an actual CI
+  run against the exact version it names — peer and devDependency are both
+  `0.49.0`, so no untested span exists in it. (React's own range still has
+  an intentionally untested lower half — peer `^19.2.0` vs. devDependency
+  `^19.2.5` — per the `//peerDependencies` note; that is unchanged by this
+  decision and follows the opposite, stable-major reasoning explained
+  above.)
+- The policy is written down (`//lexicalPeerPolicy` in `package.json`, this
+  ADR, and the README's install section), so the next Lexical minor is a
+  known, bounded task rather than a rediscovery of this issue's reasoning.
+
+**Negative:**
+
+- **This is a breaking change.** `^0.44.0` and `^0.49.0` are non-overlapping
+  ranges; any consumer still on Lexical 0.44.0–0.48.x will see an
+  unmet-peer-dependency warning on installing the next release and must
+  upgrade its Lexical family to 0.49.0 first. That is the intended effect of
+  narrowing, not a regression.
+- **The stall this issue describes will recur at every future Lexical
+  minor**, by design: this package's range never gets ahead of what it has
+  actually tested. The mitigation is that each recurrence is now a known,
+  bounded task (bump twelve versions, run the suite, adjust the range) with
+  a written rationale, rather than an accumulating five-minor gap discovered
+  incidentally by a downstream consumer's dependency refresh.
+
+**Neutral:**
+
+- `react`/`react-dom` peer ranges and all non-Lexical dependencies are
+  unaffected; this decision only concerns the Lexical family, and does not
+  reopen or alter the existing React range philosophy.
+- No Lexical-API-floor guard test (the kind `tests/package-manifest-contract.test.ts`
+  already has for React) was added. That guard exists for React because its
+  range makes an untested-lower-half claim that needs policing; the narrow
+  Lexical range makes no such claim, so there is nothing analogous to guard
+  against.
+
+## References
+
+- Issue #92 (this decision), verveguy/liminis#1026 (the originating
+  `liminis-app` dependency refresh that surfaced the stall)
+- `package.json` — the `//peerDependencies` and `//lexicalPeerPolicy`
+  manifest comments; the twelve `peerDependencies`/`devDependencies` entries
+- `README.md` — "Install" section, the Lexical `pnpm add` block and the
+  peer-range policy callout
+- `CHANGELOG.md` — the `## Unreleased` / `### Breaking changes` entry
+  recording this bump
+- `docs/decisions/adr-078.md`, `docs/decisions/adr-079.md` — prior ADRs on
+  consumer-facing package surface, cited as precedent for treating this as
+  ADR-worthy
+- Related: #78 (a required member made 0.2.0 type-level breaking), #79
+  (token definitions documented as public API) — prior instances of
+  consumer-facing surface needing explicit treatment

package/docs/decisions/adr-93-liminis-editor-defined-aliases.md

@@ -0,0 +1,288 @@
+# ADR-93: `--liminis-editor-*` Names Are Defined as Aliases of Their Legacy Names
+
+**Date:** 2026-08-20
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #93 (verveguy/liminis-editor)
+
+## Context
+
+ADR-087 (#51) renamed every *consumption* site to `--liminis-editor-*`,
+deliberately leaving every *definition* site (`:root`, `.dark`, the
+`@media print` block) declaring the old, pre-`0.2.0` names. ADR-092 (#79)
+built a checked-in baseline guarding those definitions, and explicitly
+deferred a third item: whether the package should ever *define*
+`--liminis-editor-*` names directly, with the legacy names kept as an
+alias layer underneath.
+
+That gap is not theoretical. Zusammen, a downstream host, reads this
+package's definitions directly — `var(--vscode-background)`,
+`var(--vscode-border)`, etc. — mapping its own design-system tokens onto
+them rather than overriding them
+([verveguy/zusammen#129](https://github.com/verveguy/zusammen/issues/129)).
+It wants to migrate those reads onto `--liminis-editor-*` instead, but
+before this change there was nothing to migrate to: every row in the
+README's token table read "Has a default: No (inline fallback only)."
+
+**The naive fix is the trap ADR-087 already reasoned through once, now on
+the definition side.** Adding `--liminis-editor-foreground: <default>;` to
+the package's own `:root` unconditionally would resolve every one of the
+250 consumption chains (`var(--liminis-editor-foreground, var(--vscode-foreground))`)
+at the new name before ever reaching the old one — silently disabling the
+ADR-087 fallback layer. A host like `liminis-app`, which supplies only
+`--color-primary`/`--color-muted-foreground` (its own Tailwind `@theme`
+tokens, coincidentally the fallback names `C4Component.tsx` already uses),
+would stop tracking its own overrides with no error and no failing test —
+exactly the failure mode ADR-092 exists to guard against.
+
+Two further, non-obvious problems surfaced during implementation, not
+anticipated by the plan:
+
+1. **A definition-side alias's own `var()` reference is textually
+   indistinguishable from a consumption site.** `scripts/lib/theming-tokens.mjs`'s
+   `consumptionSitesIn()` scans raw text for depth-0 `var(--x` occurrences
+   with no awareness of whether the enclosing statement is a custom-property
+   *declaration* (`--liminis-editor-foreground: var(--vscode-foreground);`)
+   or an ordinary property/JS-style value (`color: var(--liminis-editor-foreground, ...)`).
+   Adding the alias block as originally planned would have made every one
+   of the ~40 flat-aliased legacy names register as a newly "consumed"
+   token, growing the README table and `TOKEN_DESCRIPTIONS` maintenance
+   surface for tokens no host-facing code actually reads — a regression
+   against this issue's own explicit Out of Scope ("does not add or remove
+   rows" from the consumed/documented table).
+2. **A CSS block comment containing a literal `*/` substring inside its
+   text terminates early.** An early draft of the new `:root` block's
+   header comment read `--vscode-*/--slashmd-*/--checkbox-*` — the `*/`
+   embedded in `--vscode-*/--slashmd-*` closed the comment there, both for
+   real CSS parsers and for this repo's own `stripCssComments()`, leaving
+   the remainder of the intended comment as live (invalid) CSS text. This
+   would have shipped a real authoring bug, not just a test artifact.
+
+## Decision
+
+**Legacy names keep carrying the real defaults. Each `--liminis-editor-*`
+name becomes a new declaration that reads its legacy name via `var()`** —
+`--liminis-editor-foreground: var(--vscode-foreground);` — added in a new
+`:root`/`.dark` block placed immediately after the package's existing
+`:root`/`.dark` blocks in `src/styles.css`. This is the direction the
+spec's Background illustrated and Research confirmed by inspecting this
+file's cascade structure directly: a CSS custom property resolves against
+the *element's own* cascade at the point of use, not at declaration time,
+so a single `:root`-level alias re-resolves correctly through `.dark`'s and
+the `@media print` block's overrides of the *legacy* name it points to —
+no per-block alias duplication is needed, and neither `.dark` nor the print
+block needed to change for the ~40 tokens with a real existing declaration.
+
+**All 59 renamed tokens (`PREVIOUS_NAME`'s full set) get a real declaration
+in this pass, not only the two the originating issue named.** FR-001 says
+"every token it currently consumes"; inspection of every consumption site
+found 19 tokens with no existing `:root`/`.dark` legacy declaration to
+alias to, not 2, split into three groups:
+
+- **2 tokens** (`--vscode-input-bg`, `--vscode-foreground-muted`) resolve
+  today through an existing *nested* fallback at their own consumption
+  site. Their alias preserves that chain rather than flattening it:
+  `--liminis-editor-input-bg: var(--vscode-input-bg, var(--vscode-code-bg));`.
+- **13 tokens** have no CSS custom property backing anywhere — only a
+  literal inline fallback at each consumption site (e.g.
+  `var(--vscode-focus-border, #007acc)`). Their alias reproduces that
+  literal as the alias's own fallback:
+  `--liminis-editor-focus-border: var(--vscode-focus-border, #007acc);` —
+  a host supplying nothing sees the same literal as before (FR-002); a
+  host supplying the legacy name still wins (FR-003). 6 of these 13 vary by
+  theme via a JS `isDark`/`dark` ternary at their consumption sites
+  (`button-background`, all 5 `menu-*` tokens); those 6 get a matching
+  `.dark` override in the new block, mirroring the same light/dark split
+  their consumption sites already express in JS.
+- **4 tokens** (`--color-primary`, `--color-primary-100`,
+  `--color-muted-foreground`, `--color-muted-100`) are `liminis-app`'s own
+  Tailwind `@theme` brand tokens, for which the package only ever supplied
+  a literal final fallback, never asserted ownership. They are aliased
+  identically to the 13 above — the mechanism doesn't newly assert
+  ownership, it makes the existing fallback literal reachable under the new
+  name too.
+
+**Two of the 17 no-backing tokens have a real cross-site literal
+inconsistency, discovered by direct inspection (one — `--vscode-errorForeground`
+— was already flagged by Specify; the second — `--vscode-toolbar-hoverBackground`
+— was not):**
+
+| Token | Sites | Canonical value chosen |
+|---|---|---|
+| `--vscode-errorForeground` | `#f14c4c` (2 sites: `.editor-link-broken`, `:hover`) vs. `#f44336` (2 sites: `.block-delete-button:hover .block-delete-icon`, `.search-close-button:hover`) | `#f14c4c` — tie broken toward the more semantically central "broken link" indicator over two hover-only chrome details |
+| `--vscode-toolbar-hoverBackground` | `rgba(128, 128, 128, 0.15)` (2 sites) vs. `rgba(128, 128, 128, 0.1)` (1 site, `.drag-handle:hover .drag-handle-icon`) | `rgba(128, 128, 128, 0.15)` — majority (2 of 3) |
+
+Once a token has a single real definition, it necessarily wins over every
+site's own inline fallback (fallback only applies when the property is
+genuinely unset) — there is no mechanism that both defines the token
+(FR-001) and preserves two different resolved values at different sites.
+**This unifies 3 sites' rendered color to the canonical value, a small,
+real, intentional visual change**, called out here per this repository's
+convention of recording what a decision costs. The three affected call
+sites (`src/styles.css:1148`, `:1188`, `:1704`) each carry a one-line
+comment noting they are superseded by the new canonical default. The
+spec's Out of Scope section explicitly permits this as a side effect of
+choosing FR-001's value, not as a design goal in its own right.
+
+**Consumption sites are left untouched.** All 224 `styles.css` sites and 26
+`.tsx` sites keep their existing `var(--liminis-editor-x, var(--old-name-x, ...))`
+chains. Simplifying them to a single `var(--liminis-editor-x)` call was
+identified as optional cleanup (spec Assumptions) but would strip every
+renamed token's `immediateFallback`, breaking `resolvesToPreviousName()`
+(FR-011's existing drift guard) for all 59 tokens unless that guard were
+also redesigned to check the *definition* site's alias target instead —
+a materially larger, coordinated change deferred out of this issue's scope.
+The now-redundant nested legacy fallback at each site is provably dead code
+once its definition-side alias exists, left in place rather than removed.
+
+**`scripts/lib/theming-tokens.mjs`'s `consumptionSitesIn()` gains a
+declaration-value check.** A new helper,
+`isCustomPropertyDeclarationValue(text, varStartIndex)`, walks back from a
+depth-0 `var(` to the nearest statement boundary (`;`, `{`, or `}`) and
+tests whether everything between that boundary and the `var(` is exactly
+`--name:` — the shape only a custom-property declaration's value position
+can have (an ordinary CSS property name never starts with `--`). Each
+site now carries an `isDeclarationValue` flag; `consumedTokens()`'s Pass 1
+skips depth-0 sites where it is true. This keeps the "consumed" inventory —
+and therefore the README table's row set and the `TOKEN_DESCRIPTIONS`
+maintenance surface — exactly as it was before this issue, satisfying its
+Out of Scope constraint, while still letting `defaultedTokens()` (a
+separate, unchanged function that just scans for any `--name:` declaration)
+pick up all 59 new aliases as newly "defined."
+
+**No other change to `theming-tokens.mjs` or its `.d.mts`.**
+`isCustomPropertyDeclarationValue` is internal, not exported;
+`defaultedTokens()` needed no change to recognize the new aliases; the
+ADR-092 baseline guard, `resolvesWithoutHost()`, and `resolvesToPreviousName()`
+all continue to operate over the same "consumed"/"defined" definitions they
+already had, now simply seeing a larger defined set.
+
+## Consequences
+
+**Good:**
+
+- A host can now read `--liminis-editor-x` directly and get a real value in
+  every override state — the entire point of this issue and the
+  prerequisite for zusammen#129's read migration (FR-001, SC-001, SC-006).
+- A host supplying only a legacy name **at `:root`/`document.documentElement`**
+  is unaffected: the alias's `var()` re-resolves through that name's own
+  `.dark`/`@media print` overrides at the point of use, verified directly
+  against this file's actual cascade structure rather than assumed from the
+  general CSS-custom-property theory alone (FR-002, FR-003, User Story 2).
+  This is the standard integration point and the one this package's own
+  e2e coverage exercises. It does not extend to a legacy override scoped to
+  an arbitrary descendant element — see Bad/accepted below.
+- The ADR-092 baseline guard now protects all 59 new alias declarations the
+  same way it already protected the legacy ones — a future accidental
+  deletion of an alias fails `pnpm test`, naming the token (FR-005, US4).
+- The declaration-value fix to `consumptionSitesIn()` is general: it holds
+  for any future alias declaration of this shape without further
+  special-casing, not just the 59 added here.
+- The premature-comment-close bug was caught by the same regenerated test
+  suite that caught the consumption-site pollution, before either shipped —
+  the CI guards this issue extends are what surfaced both problems.
+
+**Bad / accepted:**
+
+- **The `:root`-only alias does not track a legacy-name override scoped to
+  a descendant element below `:root`** (e.g. a per-widget wrapper div a
+  host applies its own theme vars to, rather than `document.documentElement`
+  itself) — found during PR review (CodeRabbit), confirmed empirically in
+  a running Electron app, not merely reasoned about. A custom property
+  inherits its parent's already-*computed* value, not the `var()`
+  expression that produced it, so the alias's `var(--legacy-x)` is fixed
+  using `:root`'s own value of `--legacy-x` and does not re-evaluate for a
+  change made further down the tree. Two alternatives were tried and
+  rejected, each empirically, in a running app:
+  - **Re-declaring the alias on every element (`*`)** does fix the
+    descendant case, but then an element's own `*`-matched declaration
+    shadows whatever `--liminis-editor-x` value it would otherwise have
+    inherited from an ancestor — including a host's own direct
+    `--liminis-editor-x` override set on that ancestor. This broke User
+    Story 3 (a directly-set `--liminis-editor-*` name must win), which is
+    higher-confidence/already-tested behavior — confirmed by a real,
+    reproducible test failure, not a theoretical concern.
+  - **Scoping the redeclaration to the package's own root wrapper class**
+    (`.editor-app-root`) reduces but does not eliminate that same
+    shadowing (still breaks a `--liminis-editor-*` override set above
+    `.editor-app-root`), and is additionally unreliable on its own terms:
+    not every integration renders that wrapper — this repo's own
+    `examples/electron` shell mounts a lower-level component without it,
+    so the alias would go undeclared there, confirmed by inspecting the
+    actual DOM in a running instance.
+  - No mechanism was found that recomputes a legacy-name change made
+    anywhere below `:root` (User Story 2) while also respecting a
+    `--liminis-editor-*` override set on any ancestor of the read element
+    (User Story 3) — CSS custom-property inheritance passes down an
+    already-resolved value, not a live formula, so a property can prefer
+    "inherit if my ancestor set one" or "always recompute from a
+    dependency," but not both conditionally per-element without a
+    mechanism this package doesn't have (e.g. `@property` plus JS
+    reconciliation, well beyond this issue's scope). **The `:root`-only
+    design is kept, and this scope limitation is accepted and documented**
+    here and in `src/styles.css`'s alias-block comment, per this
+    repository's convention of recording what a decision costs rather than
+    silently narrowing FR-002/FR-003's stated guarantee. Extending it to
+    arbitrary DOM scope, if a specific host needs it, is deferred to a
+    follow-up issue — it is a materially larger design problem than this
+    ADR anticipated.
+- Three consumption sites (`--vscode-errorForeground` at 2 sites,
+  `--vscode-toolbar-hoverBackground` at 1 site) render a different,
+  intentionally-unified color than before this change. A host relying on
+  the specific pre-existing `#f44336`/`0.1`-alpha rendering at exactly
+  those sites will see a small visual shift. This is an unavoidable
+  consequence of giving these two tokens a single real definition (FR-001)
+  when their own consumption sites already disagreed with each other —
+  there is no mechanism that satisfies FR-001 without picking one value.
+- The checked-in baseline grows from 41 to 100 entries in one change. Per
+  ADR-092's own design the guard is one-directional (`missing` fails,
+  `added` never does), so this is a mechanical `pnpm docs:theming-baseline`
+  diff, not a CI risk — but it is a large diff for a human reviewer to
+  read line-by-line.
+- Every one of the 250 existing consumption sites keeps a nested legacy
+  fallback that is now provably redundant dead code (the definition-side
+  alias means the fallback branch can never be reached in practice). Removing
+  it was explicitly deferred (see Decision) rather than done here, so this
+  verbosity persists in `styles.css` and the five `.tsx` files until a
+  future change picks it up.
+- `consumptionSitesIn()`'s declaration-value detection is a text-boundary
+  heuristic (nearest `;`/`{`/`}` before the `var(`), not a real CSS parser.
+  It is correct for every declaration in this codebase today (all
+  single-line), but a future multi-line custom-property declaration split
+  across a statement boundary could evade it.
+
+**Neutral:**
+
+- The `@media print` block needed no changes: its `:root, .dark { ... }`
+  selector already overrides every legacy name it touches, and each new
+  alias's `var()` reference re-resolves through that override the same way
+  it re-resolves through `.dark`'s.
+- `liminis-app`'s own `--color-primary`/`--color-muted-foreground` overrides
+  are unaffected either way — the 4 brand-token aliases only make their
+  existing fallback literal reachable under the new name too, without
+  changing what either name resolves to when the host supplies its usual
+  overrides (SC-003).
+
+## References
+
+- Issue #93 (this decision); Issue #79 / ADR-092's "Not decided here" —
+  this decision's direct origin (Item 3)
+- `docs/decisions/adr-087.md` — the consumption-side rename and fallback
+  design this decision extends to the definition side, and the trap
+  ("that alternative is broken...") this decision's alias direction avoids
+  repeating on the definition side
+- `docs/decisions/adr-092.md` — the checked-in baseline guard this
+  decision's new declarations are added to
+- `src/styles.css` — the new `:root`/`.dark` alias block (after the
+  existing `.dark` block); the three superseded-literal comments at the
+  drag-handle-hover, block-delete-hover, and search-close-hover sites
+- `scripts/lib/theming-tokens.mjs` — `isCustomPropertyDeclarationValue()`,
+  `consumptionSitesIn()`'s new `isDeclarationValue` field, and
+  `consumedTokens()`'s Pass 1 filter
+- `scripts/lib/theming-defined-tokens-baseline.json` — regenerated via
+  `pnpm docs:theming-baseline`, 41 → 100 entries
+- `README.md`, "Theming: CSS custom properties" — regenerated table and
+  hand-rewritten prose describing the alias mechanism
+- [verveguy/zusammen#129](https://github.com/verveguy/zusammen/issues/129)
+  — the downstream migration this decision unblocks

package/docs/editor-api.md

@@ -95,6 +95,7 @@ function MyEditorWithOutline() {
 | `<Editor>`'s `documentOutlineHandle` | `DocumentOutlineHandle` | Connects this editor instance to a `<DocumentOutline>`. Omit it and no outline plugin mounts at all — an outline-less consumer pays nothing for it. |
 | `<DocumentOutline>`'s `handle` | `DocumentOutlineHandle` | The same object passed to `<Editor>`. |
 | `<DocumentOutline>`'s `className` | `string` | Additional class on the outer `<nav>`, for your own placement/layout. |
+| `<DocumentOutline>`'s `onEntrySelect` | `(entry: OutlineEntry) => void` | Optional. Fires with the clicked entry in addition to `handle.scrollToHeading`. Mainly useful on the markdown-derived path (below), where `scrollToHeading` no-ops. |
 
 `createDocumentOutlineHandle()` returns the shared controller: a React
 external store (`subscribe`/`getSnapshot`, so `<DocumentOutline>` re-renders
@@ -138,6 +139,76 @@ function MyAppWithOutline() {
 }
 ```
 
+### Raw-mode / markdown-derived entries (issue #84)
+
+The Lexical path above requires a mounted `<Editor>`. A host with a raw
+markdown mode — no `<Editor>`, no Lexical tree — can still drive the same
+`<DocumentOutline>` component by feeding the handle from markdown text
+directly, via `handle.publishFromMarkdown` and `handle.setActiveLine`:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { DocumentOutline, createDocumentOutlineHandle } from '@liminis/editor'
+
+function MyRawModeWithOutline({ markdown }: { markdown: string }) {
+  const [outlineHandle] = useState(() => createDocumentOutlineHandle())
+
+  // Re-derive entries whenever the raw markdown text changes.
+  useEffect(() => {
+    outlineHandle.publishFromMarkdown(markdown)
+  }, [outlineHandle, markdown])
+
+  return (
+    <div style={{ display: 'flex' }}>
+      <MyRawMarkdownEditor
+        markdown={markdown}
+        // Tell the outline which source line is at the top of your own
+        // (non-Lexical) editor's viewport as the reader scrolls, so it can
+        // resolve and highlight the active entry (FR-006).
+        onFirstVisibleLineChange={(line) => outlineHandle.setActiveLine(line)}
+      />
+      <aside>
+        <DocumentOutline
+          handle={outlineHandle}
+          // `handle.scrollToHeading` no-ops on this path (no Lexical editor
+          // to scroll) — use `entry.line` against your own editor instead.
+          onEntrySelect={(entry) => myRawEditorRef.current?.scrollToLine(entry.line)}
+        />
+      </aside>
+    </div>
+  )
+}
+```
+
+- `handle.publishFromMarkdown(markdown)` parses the markdown, derives H1–H5
+  entries using the same detection and text-extraction rules as the Lexical
+  path (order, nesting, inline formatting including inline code reduced to
+  plain text), and publishes them. Call it whenever your raw markdown text
+  changes.
+- Each markdown-derived entry additionally carries a 1-based `line` —
+  matching mdast's `position.start.line` — since a raw-mode host has no
+  Lexical tree to scroll instead. `<DocumentOutline>`'s own click handling
+  calls `handle.scrollToHeading(entry.index)`, which is a no-op on this path
+  since there's no Lexical editor to scroll; pass `onEntrySelect` to receive
+  the clicked entry and scroll your own editor via `entry.line`, as shown
+  above.
+- `handle.setActiveLine(line)` resolves which entry's heading line the
+  supplied line falls within or after (and before the next heading's line),
+  and publishes it as the active entry — the raw-mode equivalent of the
+  Lexical path's scroll-spy. Computing which line is "at the top" as the
+  reader scrolls is your responsibility, same as it is for a raw-mode host's
+  own scroll tracking; pass `null` before the first scroll for "no active
+  entry yet."
+- One handle is fed by exactly one path at a time — the Lexical path (via
+  `<Editor documentOutlineHandle>`/`OutlinePlugin`) and the markdown path
+  (via `publishFromMarkdown`/`setActiveLine`) are independent and not
+  reconciled. Don't mount `<Editor documentOutlineHandle={outlineHandle}>`
+  and call `publishFromMarkdown` on the same handle at once.
+- `deriveOutlineFromMarkdown(markdown)` and
+  `resolveActiveOutlineIndex(entries, line)` are also exported standalone,
+  for a host that wants the pure derivation without going through the
+  handle at all.
+
 ## The host seam
 
 The package boundary is drawn at **persistence**: text ranges, marks, rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liminis/editor",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "//publishing": "Publishing is deliberate, never incidental. `private: true` was this package's guard until verveguy/liminis-editor#39 took the publish decision; it is gone because that decision was taken, not because it was tidied away. The guard is now `prepublishOnly` -> scripts/guard-publish.mjs, which refuses unless LIMINIS_ALLOW_PUBLISH=1 is set explicitly. That variable is set at step scope in .github/workflows/publish.yml and nowhere else, so a release is the only path that publishes. Note that `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), which is why the guard is a script rather than a flag.",
   "license": "MIT",
   "description": "Lexical-based markdown WYSIWYG editor with mdast round-trip and a host-injection seam",
@@ -75,24 +75,26 @@
     "test:coverage": "vitest run --coverage",
     "verify:package": "node scripts/verify-package.mjs",
     "docs:theming": "node scripts/generate-theming-docs.mjs",
+    "docs:theming-baseline": "node scripts/update-theming-baseline.mjs",
     "demo": "node scripts/run-demo.mjs",
     "build:examples": "node scripts/build-examples.mjs",
     "build:site": "node scripts/build-site.mjs"
   },
-  "//peerDependencies": "Ranges are the compatibility contract, not the tested matrix. CI resolves one point version per range (currently react 19.2.x latest and lexical 0.44.x latest), so every caret range here has an untested lower half \u2014 narrowing `react` to the devDependency's `^19.2.5` would not change that, it would only reject working consumers. The react floor is not a claim, it is enforced: `tests/package-manifest-contract.test.ts` (\"imports no React API newer than the declared 19.2.0 peer floor\") scans every source file for post-19.0 named imports \u2014 `useEffectEvent`, `Activity`, `cacheSignal`, `ViewTransition`, `captureOwnerStack` \u2014 and fails if one appears. Reaching for a newer API therefore breaks CI until you raise the floor here too, which is the pairing this note would otherwise only assert. Raise a floor when the code actually starts needing a later API, not to mirror whatever CI happened to install.",
+  "//peerDependencies": "Ranges are the compatibility contract, not the tested matrix. CI resolves one point version per range (currently react 19.2.x latest and lexical 0.49.x latest), so every caret range here has an untested lower half \u2014 narrowing `react` to the devDependency's `^19.2.5` would not change that, it would only reject working consumers. The react floor is not a claim, it is enforced: `tests/package-manifest-contract.test.ts` (\"imports no React API newer than the declared 19.2.0 peer floor\") scans every source file for post-19.0 named imports \u2014 `useEffectEvent`, `Activity`, `cacheSignal`, `ViewTransition`, `captureOwnerStack` \u2014 and fails if one appears. Reaching for a newer API therefore breaks CI until you raise the floor here too, which is the pairing this note would otherwise only assert. Raise a floor when the code actually starts needing a later API, not to mirror whatever CI happened to install. This reasoning does not extend to the Lexical ranges below \u2014 see `//lexicalPeerPolicy`.",
+  "//lexicalPeerPolicy": "The twelve Lexical ranges are a single-caret bump per Lexical minor actually adopted and tested here, not a wide multi-version band. `react`'s untested lower half (above) is safe because a break there would be a bug in a stable major; Lexical is `0.x`, where every minor is permitted to break, so a wide band would claim compatibility with untested, potentially-breaking releases. Widening a range later is patch-safe; narrowing one is breaking \u2014 so this stays narrow by default and moves forward only when the code is actually run against the new minor. See docs/decisions/adr-92-lexical-peer-range-policy.md.",
   "peerDependencies": {
-    "@lexical/code": "^0.44.0",
-    "@lexical/code-prism": "^0.44.0",
-    "@lexical/link": "^0.44.0",
-    "@lexical/list": "^0.44.0",
-    "@lexical/mark": "^0.44.0",
-    "@lexical/markdown": "^0.44.0",
-    "@lexical/react": "^0.44.0",
-    "@lexical/rich-text": "^0.44.0",
-    "@lexical/selection": "^0.44.0",
-    "@lexical/table": "^0.44.0",
-    "@lexical/utils": "^0.44.0",
-    "lexical": "^0.44.0",
+    "@lexical/code": "^0.49.0",
+    "@lexical/code-prism": "^0.49.0",
+    "@lexical/link": "^0.49.0",
+    "@lexical/list": "^0.49.0",
+    "@lexical/mark": "^0.49.0",
+    "@lexical/markdown": "^0.49.0",
+    "@lexical/react": "^0.49.0",
+    "@lexical/rich-text": "^0.49.0",
+    "@lexical/selection": "^0.49.0",
+    "@lexical/table": "^0.49.0",
+    "@lexical/utils": "^0.49.0",
+    "lexical": "^0.49.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
@@ -121,17 +123,17 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@lexical/code": "^0.44.0",
-    "@lexical/code-prism": "^0.44.0",
-    "@lexical/link": "^0.44.0",
-    "@lexical/list": "^0.44.0",
-    "@lexical/mark": "^0.44.0",
-    "@lexical/markdown": "^0.44.0",
-    "@lexical/react": "^0.44.0",
-    "@lexical/rich-text": "^0.44.0",
-    "@lexical/selection": "^0.44.0",
-    "@lexical/table": "^0.44.0",
-    "@lexical/utils": "^0.44.0",
+    "@lexical/code": "^0.49.0",
+    "@lexical/code-prism": "^0.49.0",
+    "@lexical/link": "^0.49.0",
+    "@lexical/list": "^0.49.0",
+    "@lexical/mark": "^0.49.0",
+    "@lexical/markdown": "^0.49.0",
+    "@lexical/react": "^0.49.0",
+    "@lexical/rich-text": "^0.49.0",
+    "@lexical/selection": "^0.49.0",
+    "@lexical/table": "^0.49.0",
+    "@lexical/utils": "^0.49.0",
     "@testing-library/react": "^16.3.2",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.6.0",
@@ -145,7 +147,7 @@
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.5.0",
     "happy-dom": "^20.9.0",
-    "lexical": "^0.44.0",
+    "lexical": "^0.49.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "tsc-alias": "^1.9.1",