@liminis/editor 0.2.2 → 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.
 
@@ -201,22 +209,23 @@ 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, and also so you can *consume*
 one: every property this package declares with a value anywhere in
-`styles.css` — the pre-`0.2.0` names still carrying the real defaults
-(`--vscode-*`, `--slashmd-*`, `--checkbox-*`, and a couple of standalone
-legacy names) that the `--liminis-editor-*` names below fall back to — is
-part of this package's public API, readable directly by a host, not only
-overridable. (The `--liminis-editor-*` names themselves are never declared
-with a value directly — see "Has a default" below — nor are legacy names
-like `--color-*` that appear only as an inner link in a fallback chain
-rather than a `:root`/`.dark` declaration; neither is part of the defined
-set this paragraph describes.) Some hosts do exactly that — mapping their
-own design tokens onto these definitions 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).
+`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
@@ -224,87 +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, ADR-087 for the rename and its compatibility
-design, and 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`), a different
-and non-overlapping set of names from this table's rows — against an
-unintentional rename or removal — run `pnpm docs:theming-baseline` after a
-deliberate one.
+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
@@ -348,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/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/styles.css

@@ -107,6 +107,135 @@
   --slashmd-callout-caution-border: oklch(0.63 0.24 27);
 }
 
+/* ========================================
+   PUBLIC ALIASES — --liminis-editor-* names (ADR-93)
+
+   The package's own :root/.dark declarations above keep carrying the real
+   defaults, under the legacy names, exactly as before. Every alias below
+   only reads a legacy name via var() — it never declares an independent
+   value — so a host overriding only the legacy name still wins: the alias
+   re-resolves through .dark and the @media print block's overrides of that
+   legacy name, since a var() reference resolves per-element at the point of
+   use, not at the point this declaration is parsed. This lets a host read
+   --liminis-editor-* directly (verveguy/zusammen#129) without disabling the
+   ADR-087 fallback layer that a host supplying only the legacy name relies
+   on.
+
+   Scope of the "legacy name still wins" guarantee: this re-resolution is
+   correct for a legacy override applied at (or that plainly inherits down
+   to) :root/document.documentElement — the standard integration point, and
+   the only one covered by this package's own e2e coverage. It does NOT
+   extend to a legacy override scoped to an arbitrary DESCENDANT element
+   between :root and the editor's own DOM (e.g. a per-widget wrapper div a
+   host might apply its own theme vars to): a custom property inherits its
+   parent's already-*computed* value, not the var() expression, so this
+   :root-declared alias is fixed at parse time using :root's own value and
+   won't pick up a change made lower in the tree. Re-declaring the alias on
+   every element (`*`) was tried and rejected: it fixes the descendant case
+   but then shadows a --liminis-editor-* override a host sets on an
+   ancestor of the element being read, breaking the higher-priority
+   guarantee (User Story 3) that a directly-set --liminis-editor-* name
+   always wins — confirmed by test, not assumed. Scoping the redeclaration
+   to a known package wrapper class (e.g. .editor-app-root) was also tried
+   and rejected: not every integration renders that wrapper (this repo's
+   own examples/electron shell doesn't), so the alias would go undefined
+   there. See ADR-93 for the full trade-off and verveguy/liminis-editor#93's
+   PR review thread for the CSS-inheritance mechanics that rule out a
+   `:root`-only or `*`-only fix satisfying both scenarios at once.
+   ======================================== */
+:root {
+  /* Aliases for tokens with an existing --vscode-, --slashmd- or --checkbox- default */
+  --liminis-editor-background: var(--vscode-background);
+  --liminis-editor-bold-color: var(--slashmd-bold-color);
+  --liminis-editor-border: var(--vscode-border);
+  --liminis-editor-callout-caution-bg: var(--slashmd-callout-caution-bg);
+  --liminis-editor-callout-caution-border: var(--slashmd-callout-caution-border);
+  --liminis-editor-callout-important-bg: var(--slashmd-callout-important-bg);
+  --liminis-editor-callout-important-border: var(--slashmd-callout-important-border);
+  --liminis-editor-callout-note-bg: var(--slashmd-callout-note-bg);
+  --liminis-editor-callout-note-border: var(--slashmd-callout-note-border);
+  --liminis-editor-callout-tip-bg: var(--slashmd-callout-tip-bg);
+  --liminis-editor-callout-tip-border: var(--slashmd-callout-tip-border);
+  --liminis-editor-callout-warning-bg: var(--slashmd-callout-warning-bg);
+  --liminis-editor-callout-warning-border: var(--slashmd-callout-warning-border);
+  --liminis-editor-checkbox-border: var(--checkbox-border);
+  --liminis-editor-code-bg: var(--vscode-code-bg);
+  --liminis-editor-external-link: var(--vscode-external-link);
+  --liminis-editor-font-family: var(--vscode-font-family);
+  --liminis-editor-font-size: var(--vscode-font-size);
+  --liminis-editor-foreground: var(--vscode-foreground);
+  --liminis-editor-h1-color: var(--slashmd-h1-color);
+  --liminis-editor-h1-indent: var(--slashmd-h1-indent);
+  --liminis-editor-h2-color: var(--slashmd-h2-color);
+  --liminis-editor-h2-indent: var(--slashmd-h2-indent);
+  --liminis-editor-h3-color: var(--slashmd-h3-color);
+  --liminis-editor-h3-indent: var(--slashmd-h3-indent);
+  --liminis-editor-h4-color: var(--slashmd-h4-color);
+  --liminis-editor-h4-indent: var(--slashmd-h4-indent);
+  --liminis-editor-h5-color: var(--slashmd-h5-color);
+  --liminis-editor-h5-indent: var(--slashmd-h5-indent);
+  --liminis-editor-italic-color: var(--slashmd-italic-color);
+  --liminis-editor-link: var(--vscode-link);
+  --liminis-editor-selection: var(--vscode-selection);
+  --liminis-editor-token-comment: var(--slashmd-token-comment);
+  --liminis-editor-token-function: var(--slashmd-token-function);
+  --liminis-editor-token-keyword: var(--slashmd-token-keyword);
+  --liminis-editor-token-operator: var(--slashmd-token-operator);
+  --liminis-editor-token-property: var(--slashmd-token-property);
+  --liminis-editor-token-punctuation: var(--slashmd-token-punctuation);
+  --liminis-editor-token-selector: var(--slashmd-token-selector);
+  --liminis-editor-token-variable: var(--slashmd-token-variable);
+
+  /* Aliases preserving an existing nested consumption-site fallback chain —
+     these two legacy names have no --vscode-* declaration of their own, only
+     an existing fallback to a second legacy name at their consumption site. */
+  --liminis-editor-input-bg: var(--vscode-input-bg, var(--vscode-code-bg));
+  --liminis-editor-foreground-muted: var(--vscode-foreground-muted, var(--vscode-border));
+
+  /* Aliases for tokens with no CSS custom property backing anywhere — only an
+     inline literal fallback at their consumption site(s). The literal below
+     reproduces that existing light-mode fallback so a host supplying nothing
+     sees no change (FR-002); a host setting the legacy name still wins
+     (FR-003). Where the same token's literal differs by site (errorForeground,
+     toolbar-hoverBackground), a single canonical value is chosen here — see
+     ADR-93 for the two accepted visual deltas this causes at three sites. */
+  --liminis-editor-button-background: var(--vscode-button-background, #007acc);
+  --liminis-editor-button-foreground: var(--vscode-button-foreground, #ffffff);
+  --liminis-editor-menu-background: var(--vscode-menu-background, #ffffff);
+  --liminis-editor-menu-border: var(--vscode-menu-border, #d4d4d4);
+  --liminis-editor-menu-foreground: var(--vscode-menu-foreground, #333333);
+  --liminis-editor-menu-selectionBackground: var(--vscode-menu-selectionBackground, #e8e8e8);
+  --liminis-editor-menu-separatorBackground: var(--vscode-menu-separatorBackground, #d4d4d4);
+  --liminis-editor-toolbar-hoverBackground: var(--vscode-toolbar-hoverBackground, rgba(128, 128, 128, 0.15));
+  --liminis-editor-notificationsInfoIcon-foreground: var(--vscode-notificationsInfoIcon-foreground, #3794ff);
+  --liminis-editor-inputValidation-errorBackground: var(--vscode-inputValidation-errorBackground, rgba(255, 0, 0, 0.15));
+  --liminis-editor-errorForeground: var(--vscode-errorForeground, #f14c4c);
+  --liminis-editor-focus-border: var(--vscode-focus-border, #007acc);
+  --liminis-editor-focusBorder: var(--vscode-focusBorder, #007acc);
+
+  /* Aliases for liminis-app's own Tailwind @theme brand tokens — the package
+     only ever supplied a literal final fallback for these, never asserted
+     ownership; this alias makes that existing fallback reachable under the
+     new name too, without changing what it resolves to. */
+  --liminis-editor-primary: var(--color-primary, #3b82f6);
+  --liminis-editor-primary-100: var(--color-primary-100, rgba(59, 130, 246, 0.1));
+  --liminis-editor-muted-foreground: var(--color-muted-foreground, #6b7280);
+  --liminis-editor-muted-100: var(--color-muted-100, rgba(128, 128, 128, 0.1));
+}
+
+.dark {
+  /* Dark-mode literal overrides for the subset of the no-CSS-backing group
+     above whose consumption sites select a different literal in dark mode
+     (via a JS `isDark`/`dark` check reading the same .dark class this
+     selector keys off) rather than a single literal used in both themes. */
+  --liminis-editor-button-background: var(--vscode-button-background, #0e639c);
+  --liminis-editor-menu-background: var(--vscode-menu-background, #252526);
+  --liminis-editor-menu-border: var(--vscode-menu-border, #454545);
+  --liminis-editor-menu-foreground: var(--vscode-menu-foreground, #cccccc);
+  --liminis-editor-menu-selectionBackground: var(--vscode-menu-selectionBackground, #094771);
+  --liminis-editor-menu-separatorBackground: var(--vscode-menu-separatorBackground, #454545);
+}
+
 * {
   box-sizing: border-box;
 }
@@ -1038,6 +1167,7 @@ body {
 }
 
 .drag-handle:hover .drag-handle-icon {
+  /* Superseded by --liminis-editor-toolbar-hoverBackground's canonical 0.15-alpha default (ADR-93) */
   background: var(--liminis-editor-toolbar-hoverBackground, var(--vscode-toolbar-hoverBackground, rgba(128, 128, 128, 0.1)));
 }
 
@@ -1077,6 +1207,7 @@ body {
 
 .block-delete-button:hover .block-delete-icon {
   background: var(--liminis-editor-inputValidation-errorBackground, var(--vscode-inputValidation-errorBackground, rgba(255, 0, 0, 0.15)));
+  /* Superseded by --liminis-editor-errorForeground's canonical #f14c4c default (ADR-93) */
   color: var(--liminis-editor-errorForeground, var(--vscode-errorForeground, #f44336));
 }
 
@@ -1592,6 +1723,7 @@ body {
 }
 
 .search-close-button:hover {
+  /* Superseded by --liminis-editor-errorForeground's canonical #f14c4c default (ADR-93) */
   color: var(--liminis-editor-errorForeground, var(--vscode-errorForeground, #f44336));
 }
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liminis/editor",
-  "version": "0.2.2",
+  "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",
@@ -80,20 +80,21 @@
     "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"
   },
@@ -122,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",
@@ -146,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",