@liminis/editor 0.2.1 → 0.3.0

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-091.md

@@ -0,0 +1,159 @@
+# ADR-091: `DocumentOutlineHandle` Gets Two Independent, Non-Reconciled Entry Sources
+
+**Date:** 2026-08-19
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #84 (verveguy/liminis-editor)
+
+## Context
+
+Issue #69 extracted `DocumentOutline` from liminis-app's `TableOfContents.tsx`
+and deliberately rebuilt it on **live Lexical state**: `OutlinePlugin` walks
+`HeadingNode`s on every editor update and feeds the shared
+`DocumentOutlineHandle`. That decision avoided a second markdown parse and got
+#69's "the outline updates as headings change" requirement for free — but it
+also meant an outline is only possible where a Lexical `<Editor>` is mounted.
+
+The pre-extraction `TableOfContents.tsx` had no such limitation: it derived
+entries from **markdown**, using this package's own `parseMarkdown`/
+`isHeading`/`isText`/`isInlineCode`, and carried each heading's mdast
+`position.start.line` — a 1-based source line its raw-mode variant used to
+scroll a non-Lexical editor directly. That capability did not survive
+extraction, which is what stalled liminis-app's raw markdown mode
+(verveguy/liminis#1022) from adopting `DocumentOutline` at all.
+
+Three questions needed a considered answer:
+
+1. **Does markdown replace the Lexical derivation, or sit alongside it?**
+   Unifying on markdown for both paths would give up #69's "no second parse"
+   property for the live-Lexical/WYSIWYG path, and risked introducing subtle
+   Lexical-state/markdown divergence bugs in a path that already works.
+2. **How does markdown reach the handle?** `OutlineHandleImpl`'s `publish`/
+   `connect`/`disconnect` are reachable today only via a brand-gated cast
+   (`handle as OutlineHandleImpl`) that only `OutlinePlugin` — always
+   constructed from `createDocumentOutlineHandle()` — can perform. A raw-mode
+   host holds a plain `DocumentOutlineHandle` and cannot replicate that cast.
+3. **Should the two paths be reconciled when both are somehow available on
+   one handle at once?** (E.g., a host that mounts both a Lexical editor and
+   also calls the markdown methods on the same handle.)
+
+## Decision
+
+**`DocumentOutlineHandle` gains two new public methods —
+`publishFromMarkdown(markdown)` and `setActiveLine(line)` — that are a second,
+independent entry source feeding the same `publish`/`subscribe`/`getSnapshot`
+machinery `OutlinePlugin` already uses.** `DocumentOutline.tsx` renders
+correctly regardless of which path produced its snapshot, with no branching
+on the source — its only change is an optional `onEntrySelect` prop, fired
+alongside the existing `scrollToHeading` call, since that call is a no-op on
+the markdown path (no Lexical editor to scroll) and a raw-mode host needs
+some way to react to a click without re-implementing the entry list itself
+(see "Bad / accepted" below). `OutlinePlugin.tsx` needs zero changes: the
+Lexical path keeps working exactly as it did in 0.2.1.
+
+**The two paths are parallel and deliberately not reconciled.** A handle is
+fed by one path or the other — `<Editor documentOutlineHandle>`/
+`OutlinePlugin`, or `publishFromMarkdown`/`setActiveLine` — matching how the
+pre-extraction app never ran both on the same instance either. Mounting both
+on one handle at once is unsupported and produces whichever `publish()` call
+happened most recently, the same "last write wins" behavior `publish()`
+already has for any two callers.
+
+**`publishFromMarkdown` and `setActiveLine` are split into two methods, not
+one combined call**, because content changes and scroll events fire
+independently and at different rates in a raw-mode host, which owns its own
+scroll tracking (there is no package-side equivalent of `OutlinePlugin`'s
+rAF-throttled viewport observer, since the package does not own a raw-mode
+host's editor or its scroll container). `OutlineHandleImpl` stores the
+last-derived markdown entries and last active line internally so either
+method can be called alone.
+
+**The pure derivation functions (`deriveOutlineFromMarkdown`,
+`resolveActiveOutlineIndex`) live in a sibling file
+(`documentOutlineMarkdown.ts`), not inlined into `documentOutlineHandle.ts`,
+and are exported standalone from the package root** alongside the handle
+methods that compose them — independently unit-testable with no handle/
+publish machinery involved, and usable by a host that wants the derivation
+without the handle's mutable-state class at all.
+
+**`OutlineEntry` gains an optional `line?: number`**, populated only on
+markdown-derived entries; the Lexical path leaves it unset since live Lexical
+state has no source-line mapping to supply. `snapshotsEqual` compares it, so
+a line-only change (same text/level, new line) still notifies subscribers.
+
+## Consequences
+
+**Good:**
+
+- A raw-mode host with zero Lexical editors mounted can produce a populated,
+  navigable outline by calling two methods on a handle it already holds, and
+  render it with the shared `<DocumentOutline>` component — including
+  click-to-navigate via `onEntrySelect`, since `scrollToHeading` alone
+  no-ops on this path — satisfying #84's FR-008/SC-004 ("adopt without
+  reimplementing... logic") without liminis#1022 forking outline/
+  heading-derivation *or* list-rendering code.
+- The existing Lexical/WYSIWYG path is untouched at the source level:
+  `OutlinePlugin.tsx` has no diff, and #69's existing test suites pass
+  unmodified, directly verifying FR-005/US3 ("WYSIWYG behavior is
+  unaffected").
+- `DocumentOutline.tsx` has no branching on which path produced its
+  snapshot — the two entry sources are invisible to it — and its one
+  addition (`onEntrySelect`) is additive and optional, so existing WYSIWYG
+  consumers that don't pass it see no behavior change.
+- The standalone-exported pure functions give a host an escape hatch if it
+  ever wants derivation without the handle/publish machinery (e.g. a
+  server-side outline preview), without that being the primary API shape.
+
+**Bad / accepted:**
+
+- **Text extraction is now implemented twice**: Lexical's built-in
+  `getTextContent()` on the WYSIWYG path, and a hand-written recursive mdast
+  walk (`extractText` in `documentOutlineMarkdown.ts`) on the markdown path.
+  A future inline mdast node type could silently produce different text on
+  the two paths with nothing to catch it beyond the shared fixture the two
+  paths' test suites both happen to exercise (`OutlinePlugin.test.tsx`'s and
+  `documentOutlineMarkdown.test.ts`'s equivalent inline-code case). No shared
+  test harness enforces parity mechanically; considered out of scope for this
+  issue.
+- **The two paths are never reconciled**, so a host that (incorrectly) drives
+  both at once on the same handle gets undefined-in-practice "whichever
+  `publish()` ran last" behavior rather than an explicit error. Accepted
+  because detecting and rejecting that misuse would add complexity for a
+  configuration nothing in the spec calls for and the pre-extraction app
+  never did either.
+- **Empty-title headings are included on the markdown path**, diverging from
+  the pre-extraction `TableOfContents.tsx`'s `if (!title) continue`. This
+  matches FR-002's literal requirement ("same rules as the existing Lexical
+  path", which does not skip them) over parity with the old app behavior —
+  liminis#1022 needs to be aware of this when it adopts the markdown path.
+
+**Neutral:**
+
+- No new export subpath was added; `deriveOutlineFromMarkdown`/
+  `resolveActiveOutlineIndex` are exported from the same root `.` entry as
+  the rest of the outline surface, not from `./markdown`'s Lexical-free
+  barrel. ADR-075 draws that barrel's isolation boundary around avoiding
+  Lexical/MathJax/Mermaid/C4 for a consumer that only parses markdown; this
+  issue's FR-008 requires only that liminis#1022 can adopt the capability
+  without forking logic, not that it be reachable without the root barrel's
+  full import graph. Revisit only if that assumption proves wrong during
+  #1022's own implementation.
+
+## References
+
+- Issue #84 (this decision)
+- `src/app/editor/documentOutlineHandle.ts` — `OutlineEntry.line`,
+  `publishFromMarkdown`, `setActiveLine`, updated `snapshotsEqual`
+- `src/app/editor/documentOutlineMarkdown.ts` — `deriveOutlineFromMarkdown`,
+  `resolveActiveOutlineIndex`
+- `src/app/editor/OutlinePlugin.tsx` — the unchanged Lexical/WYSIWYG path
+- `src/app/editor/DocumentOutline.tsx` — the `onEntrySelect` prop, its one
+  change, added so a raw-mode host can react to clicks
+- `docs/editor-api.md` — "Raw-mode / markdown-derived entries" section
+- `docs/decisions/adr-075.md` — the package-boundary/export-subpath decision
+  this ADR's "Neutral" section revisits
+- `specs/69-extract-the-table-of/spec.md`, `docs/decisions/adr-088.md` —
+  issue #69's own decision to derive from live Lexical state, whose
+  WYSIWYG-only assumption this issue lifts without replacing it
+- verveguy/liminis#1022 (external repo) — the consumer this decision unblocks

package/docs/decisions/adr-092.md

@@ -0,0 +1,202 @@
+# ADR-092: A Checked-In Baseline Guards `styles.css`'s Defined Tokens Against Silent Rename or Removal
+
+**Date:** 2026-08-20
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #79 (verveguy/liminis-editor)
+
+## Context
+
+`tests/theming-contract.test.ts` (ADR-085) already guards the *consumed*
+token set — every `var(--x)` reference under `src/` must be documented in
+the README's generated table, resolve without a host, carry a description,
+and (per ADR-087) preserve a fallback to its pre-`0.2.0` name where renamed.
+None of those four checks say anything about a token that is *defined*
+(declared with a value in `styles.css`) but never itself consumed by
+`src/` — the `--vscode-*`, `--slashmd-*`, `--color-*` and `--checkbox-*`
+fallback targets `0.2.0` (#51) left in place specifically so a host still
+supplying only the old name keeps working.
+
+Zusammen, a downstream host, reads several of those definitions directly —
+`var(--vscode-background)`, `var(--vscode-border)`, etc. — mapping its own
+design-system tokens onto them, not overriding them. Nothing about that is
+visible from inside this package: `src/` never references those names via
+`var()`, so the existing consumed-token guard has nothing to check. `0.2.0`
+happened to leave every defined token's name untouched (0 removed, 0 added,
+comparing the published `0.1.1` and `0.2.0` packages) — but that was a
+property of what `0.2.0` chose to do, not a guarantee enforced anywhere. A
+future rename that touched definition sites as well as consumption sites
+would drop Zusammen's palette silently: an unresolved CSS custom property
+does not error, the declaration is just gone.
+
+This is a genuinely different axis from every existing guard in this repo.
+Two questions needed a considered answer:
+
+1. **What should CI compare the live defined set against?** Every existing
+   contract test (`theming-contract`, `adr-citations`,
+   `package-manifest-contract`) computes both sides of its comparison
+   dynamically from current source — there is no prior example in this repo
+   of a checked-in snapshot a maintainer edits by hand as a deliberate,
+   reviewable act. A dynamic self-comparison can't work here: the whole
+   point is to catch names *disappearing* between one state and the next,
+   which requires a reference point independent of "whatever `styles.css`
+   currently says."
+2. **Should an addition to the defined set ever fail CI?** The issue's
+   FR-006 and SC-002 are explicit that it must not — only a *disappearance*
+   of a previously-baselined name is a failure. (Acceptance Scenario 4's
+   prose reads, in isolation, as if new tokens need the baseline updated
+   before CI passes at all; FR-006/SC-002 are the more explicit,
+   cross-referencing pair on this exact point, so this decision follows
+   them: the guard is one-directional.)
+
+## Decision
+
+**A new checked-in baseline, `scripts/lib/theming-defined-tokens-baseline.json`,
+records the flat, sorted array of every token name `defaultedTokens()`
+(already existing, unchanged) finds declared in `src/styles.css`.**
+`diffDefinedTokenBaseline(current, baseline)`, added to
+`scripts/lib/theming-tokens.mjs` alongside the other pure extraction/compare
+functions, returns `{ missing, added }` — both sorted, both computed by
+name, never by count. `tests/theming-contract.test.ts` fails only when
+`missing` is non-empty, and names the specific token(s) in the failure
+message.
+
+**The comparison is one-directional: `missing` fails CI, `added` never
+does.** A token added to `styles.css` without a baseline update is not
+itself an error — it's simply not yet protected by this guard until someone
+runs the updater. This is deliberate (FR-006), not an oversight: the
+baseline's job is to catch *disappearance*, not to force every addition
+through an extra step before it can ship.
+
+**A same-count rename still fails.** Because the diff is by name, a
+declaration renamed in the same change (old name deleted, new name added,
+total count unchanged) produces one entry in `missing` and one in `added` —
+never a silent no-op. This reproduces, and would have caught, the exact
+scenario the issue's Background describes: `0.2.0` was 42 defined tokens
+before and 42 after, which a count-only check would have called clean.
+
+**`scripts/update-theming-baseline.mjs`, a new script mirroring
+`generate-theming-docs.mjs`'s shape, is the update mechanism**, exposed as
+`pnpm docs:theming-baseline`. It reads `defaultedTokens('src/styles.css')`
+and writes the sorted JSON array. A maintainer making a deliberate rename or
+removal runs it in the same change that edits `styles.css`; that diff is
+then a normal part of PR review, distinguishing "I meant to do this" from
+"this disappeared by accident." This matches the repo's existing
+`docs:theming` precedent rather than asking for a bare hand-edit of JSON.
+
+**The guard evaluates `src/styles.css`, not a built `dist/`.** `pnpm test`
+alone (no prior build) is what a local run and this guard's own CI job
+invoke; `dist/` is gitignored and does not exist without a build step
+first. `scripts/copy-assets.mjs` makes `dist/styles.css` a byte-for-byte
+copy of `src/styles.css` with no transform, so evaluating the guard against
+`src/` is representative of what ships (FR-008) without requiring a build
+at test time — the same choice the pre-existing consumed-token guard
+already made.
+
+**The baseline lives in `scripts/lib/`, not a fixtures directory.** This
+repo has no checked-in test-fixtures directory; the existing mutation tests
+build throwaway fixtures under `os.tmpdir()`. The baseline is not test
+scaffolding — it's permanent project data describing the current package
+surface, the same category as `PREVIOUS_NAME` and `TOKEN_DESCRIPTIONS` in
+the same module, so it's colocated with them.
+
+## Consequences
+
+**Good:**
+
+- Removing or renaming a defined token without updating the baseline now
+  fails CI, naming the specific token(s) — the exact defence the issue's
+  Background describes as missing, closing the gap that let `0.2.0`'s
+  rename through by coincidence rather than by guarantee.
+- The name-vs-count distinction is exercised directly by a mutation test
+  (`flags a same-count rename, not masked by an unchanged total`), so the
+  guard's core guarantee is demonstrated, not merely asserted.
+- Adding a new token is a one-line, low-friction baseline update via
+  `pnpm docs:theming-baseline` — never a blocker on its own, per FR-006.
+- The README now states, in the paragraph a first-time reader reaches
+  before the token table, that defined tokens (including pre-`0.2.0`
+  fallback names) are public API a host may read directly, and that
+  renaming or removing one is a breaking change under the existing
+  `0.x` versioning policy — answering SC-004 without requiring this ADR or
+  the issue as prerequisite reading.
+
+**Bad / accepted:**
+
+- The baseline is a plain hand-maintained (script-updated) JSON array with
+  no schema enforcement beyond `diffDefinedTokenBaseline`'s runtime
+  comparison — a malformed or hand-edited-incorrectly baseline would only
+  surface as an unexpected `missing`/`added` result at test time, not a
+  separate validation error. Accepted: the array is trivial enough (one
+  string per line) that this class of mistake is unlikely and, if it
+  happens, self-corrects on the next `pnpm docs:theming-baseline` run.
+- Because the guard is one-directional by design, a token added to
+  `styles.css` and never baselined is not protected — if it is later
+  removed, that removal also goes uncaught (it was never in `missing`'s
+  input set to begin with). This is an accepted consequence of FR-006's
+  explicit choice, not a bug to "fix" by making the guard bidirectional;
+  a maintainer who wants a newly-added token protected needs to run the
+  updater, same as documenting it in the README table already requires a
+  separate `pnpm docs:theming` run today.
+- `theming-tokens.d.mts` is hand-maintained with no automated sync check
+  against `theming-tokens.mjs`'s actual exports; forgetting to add
+  `diffDefinedTokenBaseline`'s declaration there would only surface as a
+  `pnpm typecheck` failure. Accepted as the same pre-existing tradeoff
+  ADR-085 already lives with for every other exported function in this
+  module.
+
+**Neutral:**
+
+- This ADR does not change which tokens are currently defined, consumed,
+  or documented, and does not decide whether `--liminis-editor-*` names
+  should eventually be defined natively with the legacy prefixes as an
+  alias layer (issue #79's Item 3) — that remains a follow-up candidate
+  issue, independent of this guard. See "Not decided here" below.
+
+## Not decided here
+
+Issue #79 named three things to do and ranked "Item 2 is the substance."
+This decision delivers Item 1 (the README states the contract) and Item 2
+(this baseline guard). **Item 3 — whether the package should eventually
+*define* `--liminis-editor-*` names directly, with `--vscode-*`/
+`--slashmd-*`/`--color-*`/`--checkbox-*` kept as an alias layer — is left
+open.** It is a design decision (how an alias layer would interact with the
+existing fallback chain from ADR-087), not a guard, and resolving it well is
+independent of stating today's contract and protecting it against
+shrinkage.
+
+This gap is not just theoretical follow-up work: **a downstream consumer is
+already blocked on it.** Zusammen currently reads this package's legacy
+definitions directly (`var(--vscode-background)`, `var(--vscode-border)`,
+etc., per this issue's Background) and wants to migrate those reads onto the
+`--liminis-editor-*` vocabulary instead — but there is nothing to migrate
+to, because this package defines zero `--liminis-editor-*` names today (see
+"Has a default: No" for every row in the README's token table). That
+migration is tracked at
+[verveguy/zusammen#129](https://github.com/verveguy/zusammen/issues/129) and
+cannot proceed until Item 3 is decided. Whoever picks up Item 3 should treat
+that issue as a concrete acceptance case, not just this ADR's own
+description of the gap.
+
+## References
+
+- Issue #79 (this decision)
+- `scripts/lib/theming-tokens.mjs` — `defaultedTokens()` (unchanged, already
+  computed the "defined" set) and the new `diffDefinedTokenBaseline()`
+- `scripts/lib/theming-defined-tokens-baseline.json` — the checked-in
+  baseline
+- `scripts/update-theming-baseline.mjs` — the update mechanism
+  (`pnpm docs:theming-baseline`)
+- `tests/theming-contract.test.ts` — the new "defined tokens are a public
+  API surface" `describe` block and its mutation tests
+- `scripts/copy-assets.mjs` — establishes `dist/styles.css` as a
+  byte-for-byte copy of `src/styles.css`, the basis for FR-008
+- `docs/decisions/adr-085.md` — the consumed/documented guard and the
+  shared-module, mutation-testing conventions this decision follows
+- `docs/decisions/adr-087.md` — the `--liminis-editor-*` rename this
+  decision's guard would have caught had it also touched definition sites
+- Issue #52 — the prior silent-drop incident that motivated the
+  resolves-without-host guard this new guard sits alongside
+- [verveguy/zusammen#129](https://github.com/verveguy/zusammen/issues/129) —
+  the downstream migration blocked on issue #79's Item 3, deferred by this
+  decision (see "Not decided here")