@liminis/editor 0.2.1 → 0.3.0

package/README.md

@@ -43,12 +43,20 @@ produce a broken editor context — peering is what prevents both.
 
 ```bash
 pnpm add react@^19 react-dom@^19 \
-  lexical@^0.44 @lexical/react@^0.44 @lexical/code@^0.44 \
-  @lexical/code-prism@^0.44 @lexical/link@^0.44 @lexical/list@^0.44 \
-  @lexical/mark@^0.44 @lexical/markdown@^0.44 @lexical/rich-text@^0.44 \
-  @lexical/selection@^0.44 @lexical/table@^0.44 @lexical/utils@^0.44
+  lexical@^0.49 @lexical/react@^0.49 @lexical/code@^0.49 \
+  @lexical/code-prism@^0.49 @lexical/link@^0.49 @lexical/list@^0.49 \
+  @lexical/mark@^0.49 @lexical/markdown@^0.49 @lexical/rich-text@^0.49 \
+  @lexical/selection@^0.49 @lexical/table@^0.49 @lexical/utils@^0.49
 ```
 
+> **The Lexical peer ranges are single-caret, not a wide band.** Lexical is
+> also `0.x`, where every minor is permitted to break — unlike React's range
+> above, which spans an untested-but-stable range, the Lexical range names
+> exactly the one minor this package is built and tested against. Expect it
+> to move forward (e.g. to `^0.50`) only after this package has adopted and
+> tested that release, not automatically at every upstream release. See
+> `docs/decisions/adr-92-lexical-peer-range-policy.md`.
+
 pnpm v8+ and npm v7+ install peers automatically, so in practice the first
 command is usually enough.
 
@@ -199,7 +207,25 @@ Neither is a package defect, but only one of them tells you what is wrong.
 The editor's colors, borders and a few layout metrics are all CSS custom
 properties under a single package-owned vocabulary, `--liminis-editor-*`.
 Every one of them resolves with no host configuration at all — the table
-below exists so you can *override* a palette, not so you can complete one.
+below exists so you can *override* a palette, and also so you can *consume*
+one: every property this package declares with a value anywhere in
+`styles.css` is part of this package's public API, readable directly by a
+host, not only overridable. That now includes every `--liminis-editor-*` name
+itself (see "Has a default" below) as well as the pre-`0.2.0` names that still
+carry the real defaults (`--vscode-*`, `--slashmd-*`, `--checkbox-*`, and a
+couple of standalone legacy names) — each `--liminis-editor-*` declaration is
+an alias of its previous name (`--liminis-editor-x: var(--previous-name-x);`),
+so both names resolve to the same value and either can be read directly
+(ADR-93). (Legacy names like `--color-*` that appear only as an inner link in
+a fallback chain, with no `:root`/`.dark` declaration of their own, are not
+part of the defined set this paragraph describes — only the property that
+*carries* the value is.) Some hosts read these definitions directly — mapping
+their own design tokens onto them with `var(--x)` — rather than overriding
+them. Renaming or removing a definition is therefore a breaking change, the
+same as any other change to a supported API surface described under
+"Versioning policy" above, and is distinct from renaming a *consumption* site
+(covered separately in "Migrating from the old names" below) — this package's
+CI guards against a definition disappearing unintentionally (ADR-092).
 
 **Previous name** is the pre-`0.2.0` name this property replaced — the exact
 name to look for if you're migrating a host that still overrides the old
@@ -207,82 +233,92 @@ vocabulary (`—` for a property that was never renamed). **Controls** is a
 short description of what the token actually affects. **Kind** distinguishes
 tokens that only affect appearance (`Cosmetic`) from the handful that also
 affect layout (`Structural` — heading indents and the base font). **Has a
-default** marks tokens with a `--liminis-editor-*` `:root`/`.dark`
-declaration in `styles.css` directly; every row below reads "No (inline
-fallback only)" because each token instead resolves through a fallback chain
-— `--liminis-editor-x` first, then its previous name (which still carries the
-real `:root`/`.dark` default), so a host supplying only the old name keeps
-theming unchanged. See "Migrating from the old names" below.
+default** marks tokens declared with a value in `styles.css` directly; every
+row below now reads "Yes" — each `--liminis-editor-*` name carries its own
+`:root`/`.dark` declaration, an alias that reads its previous name via `var()`
+(ADR-93), so a host reading `--liminis-editor-x` gets a real value with no
+configuration, and a host overriding only the previous name at
+`:root`/`document.documentElement` still wins, because the alias re-resolves
+through that name's own `.dark`/`@media print` overrides at the point of use
+(ADR-93 documents a scope limitation for an override applied to a descendant
+element instead). See "Migrating from the old names" below.
 
 This table is generated from `src/` by `node scripts/generate-theming-docs.mjs`
 and checked for staleness in CI (`tests/theming-contract.test.ts`) — a `var(--x)`
 added to the source without regenerating this block fails the build. Do not
 hand-edit the rows between the markers below. See ADR-085 for how the
-generation and drift guard work, and ADR-087 for the rename and its
-compatibility design.
+generation and drift guard work, ADR-087 for the rename and its compatibility
+design, ADR-092 for the separate guard that protects the full *defined* set —
+every token declared with a value in `styles.css`, per the checked-in baseline
+(`scripts/lib/theming-defined-tokens-baseline.json`) — against an
+unintentional rename or removal (run `pnpm docs:theming-baseline` after a
+deliberate one), and ADR-93 for the `--liminis-editor-*` alias declarations
+that make the defined set (baseline) a superset of this table's rows —
+every consumed `--liminis-editor-*` name is now also a defined one — rather
+than the disjoint sets they were before.
 
 <!-- theming-tokens:start -->
 | Custom property | Previous name | Controls | Kind | Has a default |
 | --- | --- | --- | --- | --- |
-| `--liminis-editor-background` | `--vscode-background` | Base background color of the editor surface and its popovers/menus. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-bold-color` | `--slashmd-bold-color` | Text color of bold (`**text**`) markdown spans. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-border` | `--vscode-border` | Default border color used throughout the editor chrome. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-button-background` | `--vscode-button-background` | Background of primary action buttons (e.g. the correction panel's "Apply" button). | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-button-foreground` | `--vscode-button-foreground` | Text color of primary action buttons. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-caution-bg` | `--slashmd-callout-caution-bg` | Background of "caution" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-caution-border` | `--slashmd-callout-caution-border` | Left border accent of "caution" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-important-bg` | `--slashmd-callout-important-bg` | Background of "important" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-important-border` | `--slashmd-callout-important-border` | Left border accent of "important" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-note-bg` | `--slashmd-callout-note-bg` | Background of "note" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-note-border` | `--slashmd-callout-note-border` | Left border accent of "note" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-tip-bg` | `--slashmd-callout-tip-bg` | Background of "tip" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-tip-border` | `--slashmd-callout-tip-border` | Left border accent of "tip" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-warning-bg` | `--slashmd-callout-warning-bg` | Background of "warning" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-callout-warning-border` | `--slashmd-callout-warning-border` | Left border accent of "warning" callout blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-checkbox-border` | `--checkbox-border` | Border color of unchecked task-list checkboxes. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-code-bg` | `--vscode-code-bg` | Background of inline code spans and fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-errorForeground` | `--vscode-errorForeground` | Text color for error and validation messages. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-external-link` | `--vscode-external-link` | Text color of links that point outside the document. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-focus-border` | `--vscode-focus-border` | Border color of the toolbar link-input field when focused. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-focusBorder` | `--vscode-focusBorder` | Color of the drag-and-drop position indicator while reordering blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-font-family` | `--vscode-font-family` | Base font family for the editor content. | Structural | No (inline fallback only) |
-| `--liminis-editor-font-size` | `--vscode-font-size` | Base font size for the editor content. | Structural | No (inline fallback only) |
-| `--liminis-editor-foreground` | `--vscode-foreground` | Default text color throughout the editor. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-foreground-muted` | `--vscode-foreground-muted` | Hover border color for the frontmatter tray's raw-view toggle. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h1-color` | `--slashmd-h1-color` | Text color of level-1 (`#`) headings. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h1-indent` | `--slashmd-h1-indent` | Left margin of level-1 (`#`) headings. | Structural | No (inline fallback only) |
-| `--liminis-editor-h2-color` | `--slashmd-h2-color` | Text color of level-2 (`##`) headings. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h2-indent` | `--slashmd-h2-indent` | Left margin of level-2 (`##`) headings. | Structural | No (inline fallback only) |
-| `--liminis-editor-h3-color` | `--slashmd-h3-color` | Text color of level-3 (`###`) headings. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h3-indent` | `--slashmd-h3-indent` | Left margin of level-3 (`###`) headings. | Structural | No (inline fallback only) |
-| `--liminis-editor-h4-color` | `--slashmd-h4-color` | Text color of level-4 (`####`) headings. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h4-indent` | `--slashmd-h4-indent` | Left margin of level-4 (`####`) headings. | Structural | No (inline fallback only) |
-| `--liminis-editor-h5-color` | `--slashmd-h5-color` | Text color of level-5 (`#####`) headings. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-h5-indent` | `--slashmd-h5-indent` | Left margin of level-5 (`#####`) headings. | Structural | No (inline fallback only) |
-| `--liminis-editor-input-bg` | `--vscode-input-bg` | Background of the toolbar link-input field. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-inputValidation-errorBackground` | `--vscode-inputValidation-errorBackground` | Background of inline validation-error messages. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-italic-color` | `--slashmd-italic-color` | Text color of italic (`*text*`) markdown spans. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-link` | `--vscode-link` | Text color of in-document links. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-menu-background` | `--vscode-menu-background` | Background of context menus (block, selection and correction menus). | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-menu-border` | `--vscode-menu-border` | Border color of context menus. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-menu-foreground` | `--vscode-menu-foreground` | Text color of context menu items. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-menu-selectionBackground` | `--vscode-menu-selectionBackground` | Background of a hovered/selected context menu item. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-menu-separatorBackground` | `--vscode-menu-separatorBackground` | Color of separator lines inside context menus. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-muted-100` | `--color-muted-100` | Background of the C4 diagram layout-toggle buttons when inactive. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-muted-foreground` | `--color-muted-foreground` | Icon/text color of the C4 diagram layout-toggle buttons when inactive. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-notificationsInfoIcon-foreground` | `--vscode-notificationsInfoIcon-foreground` | Color of informational icons in inline notifications. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-primary` | `--color-primary` | Icon/text color of the C4 diagram layout-toggle buttons when active. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-primary-100` | `--color-primary-100` | Background of the C4 diagram layout-toggle buttons when active. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-selection` | `--vscode-selection` | Background color of selected/highlighted text. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-comment` | `--slashmd-token-comment` | Syntax-highlight color for comments in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-function` | `--slashmd-token-function` | Syntax-highlight color for function names in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-keyword` | `--slashmd-token-keyword` | Syntax-highlight color for keywords in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-operator` | `--slashmd-token-operator` | Syntax-highlight color for operators in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-property` | `--slashmd-token-property` | Syntax-highlight color for object properties in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-punctuation` | `--slashmd-token-punctuation` | Syntax-highlight color for punctuation in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-selector` | `--slashmd-token-selector` | Syntax-highlight color for CSS selectors in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-token-variable` | `--slashmd-token-variable` | Syntax-highlight color for variables in fenced code blocks. | Cosmetic | No (inline fallback only) |
-| `--liminis-editor-toolbar-hoverBackground` | `--vscode-toolbar-hoverBackground` | Background of a toolbar button on hover. | Cosmetic | No (inline fallback only) |
+| `--liminis-editor-background` | `--vscode-background` | Base background color of the editor surface and its popovers/menus. | Cosmetic | Yes |
+| `--liminis-editor-bold-color` | `--slashmd-bold-color` | Text color of bold (`**text**`) markdown spans. | Cosmetic | Yes |
+| `--liminis-editor-border` | `--vscode-border` | Default border color used throughout the editor chrome. | Cosmetic | Yes |
+| `--liminis-editor-button-background` | `--vscode-button-background` | Background of primary action buttons (e.g. the correction panel's "Apply" button). | Cosmetic | Yes |
+| `--liminis-editor-button-foreground` | `--vscode-button-foreground` | Text color of primary action buttons. | Cosmetic | Yes |
+| `--liminis-editor-callout-caution-bg` | `--slashmd-callout-caution-bg` | Background of "caution" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-caution-border` | `--slashmd-callout-caution-border` | Left border accent of "caution" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-important-bg` | `--slashmd-callout-important-bg` | Background of "important" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-important-border` | `--slashmd-callout-important-border` | Left border accent of "important" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-note-bg` | `--slashmd-callout-note-bg` | Background of "note" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-note-border` | `--slashmd-callout-note-border` | Left border accent of "note" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-tip-bg` | `--slashmd-callout-tip-bg` | Background of "tip" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-tip-border` | `--slashmd-callout-tip-border` | Left border accent of "tip" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-warning-bg` | `--slashmd-callout-warning-bg` | Background of "warning" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-callout-warning-border` | `--slashmd-callout-warning-border` | Left border accent of "warning" callout blocks. | Cosmetic | Yes |
+| `--liminis-editor-checkbox-border` | `--checkbox-border` | Border color of unchecked task-list checkboxes. | Cosmetic | Yes |
+| `--liminis-editor-code-bg` | `--vscode-code-bg` | Background of inline code spans and fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-errorForeground` | `--vscode-errorForeground` | Text color for error and validation messages. | Cosmetic | Yes |
+| `--liminis-editor-external-link` | `--vscode-external-link` | Text color of links that point outside the document. | Cosmetic | Yes |
+| `--liminis-editor-focus-border` | `--vscode-focus-border` | Border color of the toolbar link-input field when focused. | Cosmetic | Yes |
+| `--liminis-editor-focusBorder` | `--vscode-focusBorder` | Color of the drag-and-drop position indicator while reordering blocks. | Cosmetic | Yes |
+| `--liminis-editor-font-family` | `--vscode-font-family` | Base font family for the editor content. | Structural | Yes |
+| `--liminis-editor-font-size` | `--vscode-font-size` | Base font size for the editor content. | Structural | Yes |
+| `--liminis-editor-foreground` | `--vscode-foreground` | Default text color throughout the editor. | Cosmetic | Yes |
+| `--liminis-editor-foreground-muted` | `--vscode-foreground-muted` | Hover border color for the frontmatter tray's raw-view toggle. | Cosmetic | Yes |
+| `--liminis-editor-h1-color` | `--slashmd-h1-color` | Text color of level-1 (`#`) headings. | Cosmetic | Yes |
+| `--liminis-editor-h1-indent` | `--slashmd-h1-indent` | Left margin of level-1 (`#`) headings. | Structural | Yes |
+| `--liminis-editor-h2-color` | `--slashmd-h2-color` | Text color of level-2 (`##`) headings. | Cosmetic | Yes |
+| `--liminis-editor-h2-indent` | `--slashmd-h2-indent` | Left margin of level-2 (`##`) headings. | Structural | Yes |
+| `--liminis-editor-h3-color` | `--slashmd-h3-color` | Text color of level-3 (`###`) headings. | Cosmetic | Yes |
+| `--liminis-editor-h3-indent` | `--slashmd-h3-indent` | Left margin of level-3 (`###`) headings. | Structural | Yes |
+| `--liminis-editor-h4-color` | `--slashmd-h4-color` | Text color of level-4 (`####`) headings. | Cosmetic | Yes |
+| `--liminis-editor-h4-indent` | `--slashmd-h4-indent` | Left margin of level-4 (`####`) headings. | Structural | Yes |
+| `--liminis-editor-h5-color` | `--slashmd-h5-color` | Text color of level-5 (`#####`) headings. | Cosmetic | Yes |
+| `--liminis-editor-h5-indent` | `--slashmd-h5-indent` | Left margin of level-5 (`#####`) headings. | Structural | Yes |
+| `--liminis-editor-input-bg` | `--vscode-input-bg` | Background of the toolbar link-input field. | Cosmetic | Yes |
+| `--liminis-editor-inputValidation-errorBackground` | `--vscode-inputValidation-errorBackground` | Background of inline validation-error messages. | Cosmetic | Yes |
+| `--liminis-editor-italic-color` | `--slashmd-italic-color` | Text color of italic (`*text*`) markdown spans. | Cosmetic | Yes |
+| `--liminis-editor-link` | `--vscode-link` | Text color of in-document links. | Cosmetic | Yes |
+| `--liminis-editor-menu-background` | `--vscode-menu-background` | Background of context menus (block, selection and correction menus). | Cosmetic | Yes |
+| `--liminis-editor-menu-border` | `--vscode-menu-border` | Border color of context menus. | Cosmetic | Yes |
+| `--liminis-editor-menu-foreground` | `--vscode-menu-foreground` | Text color of context menu items. | Cosmetic | Yes |
+| `--liminis-editor-menu-selectionBackground` | `--vscode-menu-selectionBackground` | Background of a hovered/selected context menu item. | Cosmetic | Yes |
+| `--liminis-editor-menu-separatorBackground` | `--vscode-menu-separatorBackground` | Color of separator lines inside context menus. | Cosmetic | Yes |
+| `--liminis-editor-muted-100` | `--color-muted-100` | Background of the C4 diagram layout-toggle buttons when inactive. | Cosmetic | Yes |
+| `--liminis-editor-muted-foreground` | `--color-muted-foreground` | Icon/text color of the C4 diagram layout-toggle buttons when inactive. | Cosmetic | Yes |
+| `--liminis-editor-notificationsInfoIcon-foreground` | `--vscode-notificationsInfoIcon-foreground` | Color of informational icons in inline notifications. | Cosmetic | Yes |
+| `--liminis-editor-primary` | `--color-primary` | Icon/text color of the C4 diagram layout-toggle buttons when active. | Cosmetic | Yes |
+| `--liminis-editor-primary-100` | `--color-primary-100` | Background of the C4 diagram layout-toggle buttons when active. | Cosmetic | Yes |
+| `--liminis-editor-selection` | `--vscode-selection` | Background color of selected/highlighted text. | Cosmetic | Yes |
+| `--liminis-editor-token-comment` | `--slashmd-token-comment` | Syntax-highlight color for comments in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-function` | `--slashmd-token-function` | Syntax-highlight color for function names in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-keyword` | `--slashmd-token-keyword` | Syntax-highlight color for keywords in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-operator` | `--slashmd-token-operator` | Syntax-highlight color for operators in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-property` | `--slashmd-token-property` | Syntax-highlight color for object properties in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-punctuation` | `--slashmd-token-punctuation` | Syntax-highlight color for punctuation in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-selector` | `--slashmd-token-selector` | Syntax-highlight color for CSS selectors in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-token-variable` | `--slashmd-token-variable` | Syntax-highlight color for variables in fenced code blocks. | Cosmetic | Yes |
+| `--liminis-editor-toolbar-hoverBackground` | `--vscode-toolbar-hoverBackground` | Background of a toolbar button on hover. | Cosmetic | Yes |
 <!-- theming-tokens:end -->
 
 **A worked example.** To match a host's own palette, override a subset of
@@ -326,6 +362,25 @@ prefix swap (`--checkbox-border` became `--liminis-editor-checkbox-border`,
 not `--liminis-editor-border`, to avoid colliding with `--vscode-border`'s
 new name), so look it up rather than deriving it.
 
+Reading, not just overriding, is also migratable: a host that currently reads
+a legacy name directly (e.g. mapping its own design tokens onto
+`--vscode-foreground`) can switch that read to the corresponding
+`--liminis-editor-*` name and get an identical value, **as long as it isn't
+also setting the `--liminis-editor-*` name itself** — a directly-set
+`--liminis-editor-*` value always wins over the previous name's own value,
+by ordinary cascade precedence (see "Has a default" below), so the two reads
+are identical only while the host relies solely on the previous name. Until
+ADR-93, `--liminis-editor-*` names were only ever *consumed*, never
+themselves declared with a value — there was nothing for such a host to
+migrate its reads to. Every `--liminis-editor-*` name now carries its own
+`:root`/`.dark` alias declaration that resolves to the previous name's own
+value in that legacy-only case, so the read migration is a like-for-like
+swap with no observable difference (see verveguy/zusammen#129, the migration
+this addresses). This guarantee holds for a previous-name override applied
+at `:root`/`document.documentElement`, the standard integration point; see
+ADR-93 for a documented limitation when a host scopes its override to a
+descendant element instead.
+
 ## Annotations
 
 An annotation is a range-anchored marker over document text whose anchor

package/dist/app/editor/DocumentOutline.d.ts

@@ -1,9 +1,18 @@
-import type { DocumentOutlineHandle } from './documentOutlineHandle.js';
+import type { DocumentOutlineHandle, OutlineEntry } from './documentOutlineHandle.js';
 export interface DocumentOutlineProps {
     /** The controller created by `createDocumentOutlineHandle()` and also passed to `<Editor documentOutlineHandle={…}>`. */
     handle: DocumentOutlineHandle;
     /** Additional class name on the outer `<nav>`, for host placement/layout (FR-008). */
     className?: string;
+    /**
+     * Fires with the clicked entry in addition to `handle.scrollToHeading`.
+     * `handle.scrollToHeading` no-ops when no Lexical editor is connected
+     * (the markdown-derived/raw-mode path, issue #84) — a raw-mode host has no
+     * other way to react to a click, since it doesn't render the entry list
+     * itself, so this is how it navigates its own (non-Lexical) editor via
+     * `entry.line`.
+     */
+    onEntrySelect?: (entry: OutlineEntry) => void;
 }
 /**
  * Renders a navigable "on this page" heading outline for one editor
@@ -14,4 +23,4 @@ export interface DocumentOutlineProps {
  * placement, width-gating, and collapse/persistence are the host's concern
  * (FR-008) — this component only renders the list and reacts to the handle.
  */
-export declare function DocumentOutline({ handle, className }: DocumentOutlineProps): import("react").JSX.Element | null;
+export declare function DocumentOutline({ handle, className, onEntrySelect }: DocumentOutlineProps): import("react").JSX.Element | null;

package/dist/app/editor/DocumentOutline.js

@@ -9,7 +9,7 @@ import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
  * placement, width-gating, and collapse/persistence are the host's concern
  * (FR-008) — this component only renders the list and reacts to the handle.
  */
-export function DocumentOutline({ handle, className }) {
+export function DocumentOutline({ handle, className, onEntrySelect }) {
     // Wrapped rather than passed directly: `handle.subscribe`/`handle.getSnapshot`
     // are unbound method references off a plain interface value.
     const subscribe = useCallback((onStoreChange) => handle.subscribe(onStoreChange), [handle]);
@@ -27,6 +27,9 @@ export function DocumentOutline({ handle, className }) {
         return null;
     return (_jsx("nav", { className: className ? `editor-outline ${className}` : 'editor-outline', "aria-label": "Document outline", children: _jsx("ul", { className: "editor-outline-list", ref: listRef, children: snapshot.entries.map((entry) => {
                 const isActive = entry.index === snapshot.activeIndex;
-                return (_jsx("li", { "data-outline-index": entry.index, "data-outline-level": entry.level, className: isActive ? 'editor-outline-item editor-outline-item-active' : 'editor-outline-item', children: _jsxs("button", { type: "button", className: "editor-outline-item-button", "aria-current": isActive ? 'location' : undefined, onClick: () => handle.scrollToHeading(entry.index), children: [_jsx("span", { className: "editor-outline-indicator", "aria-hidden": "true" }), _jsx("span", { className: "editor-outline-item-text", children: entry.text })] }) }, entry.index));
+                return (_jsx("li", { "data-outline-index": entry.index, "data-outline-level": entry.level, className: isActive ? 'editor-outline-item editor-outline-item-active' : 'editor-outline-item', children: _jsxs("button", { type: "button", className: "editor-outline-item-button", "aria-current": isActive ? 'location' : undefined, onClick: () => {
+                            handle.scrollToHeading(entry.index);
+                            onEntrySelect?.(entry);
+                        }, children: [_jsx("span", { className: "editor-outline-indicator", "aria-hidden": "true" }), _jsx("span", { className: "editor-outline-item-text", children: entry.text })] }) }, entry.index));
             }) }) }));
 }

package/dist/app/editor/Editor.js

@@ -240,6 +240,20 @@ function CursorRestorePlugin({ contentVersion, cursorToRestoreRef, }) {
         const cursorToRestore = cursorToRestoreRef.current;
         if (!cursorToRestore)
             return;
+        // Only restore the caret if the user was actually in the editor when the
+        // reload arrived. A content reload is not always the user's doing: an
+        // agent writing the open file reaches here too, and re-focusing then pulls
+        // the caret out of whatever the user is typing in — a chat prompt beside
+        // the editor, say — mid-sentence. Restoring a caret nobody is looking at
+        // buys nothing, so an unfocused editor is left entirely alone (no
+        // selection write either, so reconciliation cannot move focus as a side
+        // effect). Same rule as `AutoFocusPlugin`: never take focus unasked.
+        // Read synchronously, before the update below can perturb focus.
+        const rootElement = editor.getRootElement();
+        const hadFocus = rootElement !== null &&
+            (rootElement === document.activeElement || rootElement.contains(document.activeElement));
+        if (!hadFocus)
+            return;
         console.log('[CursorRestorePlugin] Restoring cursor', {
             contentVersion,
             offset: cursorToRestore.offset,
@@ -262,11 +276,9 @@ function CursorRestorePlugin({ contentVersion, cursorToRestoreRef, }) {
                     console.log('[CursorRestorePlugin] Selection restored at offset', newOffset);
                 }
             });
-            // Re-focus the editor
-            const rootElement = editor.getRootElement();
-            if (rootElement) {
-                rootElement.focus({ preventScroll: true });
-            }
+            // Re-focus the editor. Reached only when it already had focus above, so
+            // this restores focus the reload disturbed rather than taking it.
+            rootElement.focus({ preventScroll: true });
         });
     }, [editor, contentVersion, cursorToRestoreRef]);
     return null;

package/dist/app/editor/documentOutlineHandle.d.ts

@@ -23,6 +23,13 @@ export interface OutlineEntry {
     level: 1 | 2 | 3 | 4 | 5;
     /** Heading text with inline content (including inline code) reduced to plain text. */
     text: string;
+    /**
+     * 1-based source line of the heading, matching mdast's
+     * `position.start.line`. Only populated on markdown-derived entries (see
+     * `documentOutlineMarkdown.ts`) — the live-Lexical path has no source-line
+     * mapping to supply, so it leaves this unset.
+     */
+    line?: number;
 }
 export interface DocumentOutlineSnapshot {
     entries: OutlineEntry[];
@@ -53,6 +60,21 @@ export interface DocumentOutlineHandle {
     getSnapshot(): DocumentOutlineSnapshot;
     /** Scroll the editor to the heading at `index`. No-ops if no editor is currently connected, or `index` is out of range. */
     scrollToHeading(index: number): void;
+    /**
+     * Derive entries from `markdown` (see `deriveOutlineFromMarkdown` in
+     * `documentOutlineMarkdown.ts`) and publish them — the raw-mode
+     * counterpart to `OutlinePlugin` feeding entries from live Lexical state.
+     * Call this on every content change in a host with no mounted Lexical
+     * editor (issue #84).
+     */
+    publishFromMarkdown(markdown: string): void;
+    /**
+     * Resolve `line` against the entries from the most recent
+     * `publishFromMarkdown` call and publish the corresponding active index —
+     * the raw-mode counterpart to `OutlinePlugin`'s scroll-spy. Pass `null`
+     * for "no active heading yet" (e.g. before first scroll).
+     */
+    setActiveLine(line: number | null): void;
 }
 /**
  * The concrete object `createDocumentOutlineHandle()` returns. Consumers only
@@ -66,9 +88,15 @@ export declare class OutlineHandleImpl implements DocumentOutlineHandle {
     private snapshot;
     private readonly listeners;
     private scrollImpl;
+    /** Entries from the most recent `publishFromMarkdown` call, so `setActiveLine` can resolve against them independently. */
+    private markdownEntries;
+    /** Last line passed to `setActiveLine`, kept so a subsequent `publishFromMarkdown` re-resolves against it. */
+    private lastActiveLine;
     subscribe: (onStoreChange: () => void) => (() => void);
     getSnapshot: () => DocumentOutlineSnapshot;
     scrollToHeading: (index: number) => void;
+    publishFromMarkdown: (markdown: string) => void;
+    setActiveLine: (line: number | null) => void;
     /** Called by `OutlinePlugin` while its editor is mounted. */
     connect(scrollImpl: (index: number) => void): void;
     /** Called by `OutlinePlugin` on unmount, so a stale handle no-ops rather than scrolling a torn-down editor. */

package/dist/app/editor/documentOutlineHandle.js

@@ -11,6 +11,7 @@
  * instance — it is naturally scoped to that instance, so mounting more than
  * one editor at once never aggregates headings across them.
  */
+import { deriveOutlineFromMarkdown, resolveActiveOutlineIndex } from './documentOutlineMarkdown.js';
 /**
  * Not exported, so nothing outside this module can reference it. Its only
  * purpose is to make `DocumentOutlineHandle` nominal instead of structural:
@@ -30,7 +31,7 @@ function snapshotsEqual(a, b) {
     for (let i = 0; i < a.entries.length; i++) {
         const x = a.entries[i];
         const y = b.entries[i];
-        if (x.index !== y.index || x.level !== y.level || x.text !== y.text)
+        if (x.index !== y.index || x.level !== y.level || x.text !== y.text || x.line !== y.line)
             return false;
     }
     return true;
@@ -47,6 +48,10 @@ export class OutlineHandleImpl {
     snapshot = EMPTY_SNAPSHOT;
     listeners = new Set();
     scrollImpl = null;
+    /** Entries from the most recent `publishFromMarkdown` call, so `setActiveLine` can resolve against them independently. */
+    markdownEntries = [];
+    /** Last line passed to `setActiveLine`, kept so a subsequent `publishFromMarkdown` re-resolves against it. */
+    lastActiveLine = null;
     subscribe = (onStoreChange) => {
         this.listeners.add(onStoreChange);
         return () => {
@@ -57,6 +62,16 @@ export class OutlineHandleImpl {
     scrollToHeading = (index) => {
         this.scrollImpl?.(index);
     };
+    publishFromMarkdown = (markdown) => {
+        this.markdownEntries = deriveOutlineFromMarkdown(markdown);
+        const activeIndex = resolveActiveOutlineIndex(this.markdownEntries, this.lastActiveLine);
+        this.publish({ entries: this.markdownEntries, activeIndex });
+    };
+    setActiveLine = (line) => {
+        this.lastActiveLine = line;
+        const activeIndex = resolveActiveOutlineIndex(this.markdownEntries, line);
+        this.publish({ entries: this.markdownEntries, activeIndex });
+    };
     /** Called by `OutlinePlugin` while its editor is mounted. */
     connect(scrollImpl) {
         this.scrollImpl = scrollImpl;

package/dist/app/editor/documentOutlineMarkdown.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Derives `OutlineEntry` entries directly from markdown text, independent of
+ * any Lexical editor state — the raw-mode counterpart to `OutlinePlugin`'s
+ * live-tree derivation (issue #84). A host with no mounted Lexical editor
+ * (liminis#1022's raw markdown mode) has no heading DOM/tree to walk, but it
+ * does have the markdown text and, per this issue's spec, is expected to know
+ * which source line is currently in view — this module turns both into the
+ * same `OutlineEntry` shape `OutlinePlugin` produces, plus a source line
+ * neither Lexical nor the DOM can supply.
+ */
+import type { OutlineEntry } from './documentOutlineHandle.js';
+/**
+ * Derive `OutlineEntry[]` from a markdown string alone — no Lexical editor,
+ * no DOM. Mirrors `OutlinePlugin.readHeadingEntries()`: only top-level nodes
+ * are inspected (headings nested inside blockquotes/lists are not walked
+ * into, matching `$getRoot().getChildren()`), levels are restricted to
+ * H1–H5 (mdast allows depth 6; excluded exactly like the Lexical path
+ * excludes H6), and identity is positional (`index`), not by `text`.
+ *
+ * Unlike the Lexical path, an empty-title heading is still included — see
+ * ADR for why this issue does not replicate the pre-extraction app's
+ * `if (!title) continue`.
+ */
+export declare function deriveOutlineFromMarkdown(markdown: string): OutlineEntry[];
+/**
+ * Resolve which entry is "active" for a supplied source `line` — the
+ * raw-mode counterpart to `OutlinePlugin`'s viewport-based scroll-spy. An
+ * entry is active from its own line up to (but not including) the next
+ * entry's line, matching the spec's literal FR-006 semantics (no tolerance/
+ * fudge factor — that is host-side scroll-spy tuning, per the plan).
+ *
+ * Returns `null` when `line` is `null` (no active heading yet, e.g. before
+ * first scroll) or falls before the first heading.
+ */
+export declare function resolveActiveOutlineIndex(entries: OutlineEntry[], line: number | null): number | null;

package/dist/app/editor/documentOutlineMarkdown.js

@@ -0,0 +1,82 @@
+/**
+ * Derives `OutlineEntry` entries directly from markdown text, independent of
+ * any Lexical editor state — the raw-mode counterpart to `OutlinePlugin`'s
+ * live-tree derivation (issue #84). A host with no mounted Lexical editor
+ * (liminis#1022's raw markdown mode) has no heading DOM/tree to walk, but it
+ * does have the markdown text and, per this issue's spec, is expected to know
+ * which source line is currently in view — this module turns both into the
+ * same `OutlineEntry` shape `OutlinePlugin` produces, plus a source line
+ * neither Lexical nor the DOM can supply.
+ */
+import { parseMarkdown, isHeading, isText, isInlineCode } from '../../markdown/parse.js';
+/**
+ * Recursively reduces inline content to plain text, matching Lexical's
+ * `getTextContent()` semantics: every inline node's text is concatenated in
+ * order with no separator, bottoming out at `text`/`inlineCode` leaves. This
+ * mirrors `OutlinePlugin.test.tsx`'s inline-code fixture (`'See ' + 'inline
+ * code'` → `'See inline code'`) rather than enumerating every mdast inline
+ * type by name.
+ */
+function extractText(node) {
+    if (isText(node) || isInlineCode(node))
+        return node.value;
+    if ('children' in node && Array.isArray(node.children)) {
+        return node.children.map((child) => extractText(child)).join('');
+    }
+    return '';
+}
+/**
+ * Derive `OutlineEntry[]` from a markdown string alone — no Lexical editor,
+ * no DOM. Mirrors `OutlinePlugin.readHeadingEntries()`: only top-level nodes
+ * are inspected (headings nested inside blockquotes/lists are not walked
+ * into, matching `$getRoot().getChildren()`), levels are restricted to
+ * H1–H5 (mdast allows depth 6; excluded exactly like the Lexical path
+ * excludes H6), and identity is positional (`index`), not by `text`.
+ *
+ * Unlike the Lexical path, an empty-title heading is still included — see
+ * ADR for why this issue does not replicate the pre-extraction app's
+ * `if (!title) continue`.
+ */
+export function deriveOutlineFromMarkdown(markdown) {
+    const { root } = parseMarkdown(markdown);
+    const entries = [];
+    let index = 0;
+    for (const node of root.children) {
+        if (!isHeading(node))
+            continue;
+        if (node.depth < 1 || node.depth > 5)
+            continue;
+        const text = node.children.map((child) => extractText(child)).join('');
+        entries.push({
+            index: index++,
+            level: node.depth,
+            text,
+            line: node.position?.start?.line,
+        });
+    }
+    return entries;
+}
+/**
+ * Resolve which entry is "active" for a supplied source `line` — the
+ * raw-mode counterpart to `OutlinePlugin`'s viewport-based scroll-spy. An
+ * entry is active from its own line up to (but not including) the next
+ * entry's line, matching the spec's literal FR-006 semantics (no tolerance/
+ * fudge factor — that is host-side scroll-spy tuning, per the plan).
+ *
+ * Returns `null` when `line` is `null` (no active heading yet, e.g. before
+ * first scroll) or falls before the first heading.
+ */
+export function resolveActiveOutlineIndex(entries, line) {
+    if (line === null)
+        return null;
+    let active = null;
+    for (const entry of entries) {
+        if (entry.line === undefined)
+            continue;
+        if (entry.line <= line)
+            active = entry.index;
+        else
+            break;
+    }
+    return active;
+}

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { DocumentOutline } from './app/editor/DocumentOutline.js';
 export type { DocumentOutlineProps } from './app/editor/DocumentOutline.js';
 export { createDocumentOutlineHandle } from './app/editor/documentOutlineHandle.js';
 export type { DocumentOutlineHandle, DocumentOutlineSnapshot, OutlineEntry, } from './app/editor/documentOutlineHandle.js';
+export { deriveOutlineFromMarkdown, resolveActiveOutlineIndex } from './app/editor/documentOutlineMarkdown.js';
 export { OPEN_ANNOTATION_COMPOSER_COMMAND } from './app/editor/annotationCommands.js';
 export type { AnnotationCreateEvent } from './app/editor/AnnotationPlugin.js';
 export type { Annotation, AnnotationKind, AnnotationKindConfig, AnnotationKindConfigs, AnnotationCreateAffordance, AnnotationMarkerStyle, AnnotationPresentation, AnnotationEditorHandle, MarkerTarget, } from './annotations/types.js';

package/dist/index.js

@@ -15,12 +15,18 @@ export { createHostMessageApi, useHostMessages } from './host/messages.js';
 // --- Components ------------------------------------------------------------
 export { App } from './app/App.js';
 export { Editor } from './app/editor/index.js';
-// --- Document outline (issue #69) -------------------------------------------
+// --- Document outline (issue #69, markdown-derived path issue #84) --------
 // `createDocumentOutlineHandle()` makes the controller shared between one
 // `<Editor documentOutlineHandle={…}>` and one `<DocumentOutline handle={…}>`
 // — create it once per editor instance and pass the same object to both.
+// A host with no mounted Lexical editor (e.g. a raw markdown mode) can feed
+// the same handle from markdown text alone via `handle.publishFromMarkdown`/
+// `handle.setActiveLine`; `deriveOutlineFromMarkdown`/
+// `resolveActiveOutlineIndex` are exported standalone for a host that wants
+// the pure derivation without going through the handle.
 export { DocumentOutline } from './app/editor/DocumentOutline.js';
 export { createDocumentOutlineHandle } from './app/editor/documentOutlineHandle.js';
+export { deriveOutlineFromMarkdown, resolveActiveOutlineIndex } from './app/editor/documentOutlineMarkdown.js';
 // --- Annotations, React surface (ADR-077) ---------------------------------
 // The kind-configuration types a host needs to turn the mechanism on, plus the
 // create-event shape. The DOM-free anchor model, resolver and marker-target