@liminis/editor 0.2.0 → 0.2.2

package/README.md

@@ -199,7 +199,24 @@ Neither is a package defect, but only one of them tells you what is wrong.
 The editor's colors, borders and a few layout metrics are all CSS custom
 properties under a single package-owned vocabulary, `--liminis-editor-*`.
 Every one of them resolves with no host configuration at all — the table
-below exists so you can *override* a palette, not so you can complete one.
+below exists so you can *override* a palette, and also so you can *consume*
+one: every property this package declares with a value anywhere in
+`styles.css` — 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).
 
 **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
@@ -218,8 +235,13 @@ This table is generated from `src/` by `node scripts/generate-theming-docs.mjs`
 and checked for staleness in CI (`tests/theming-contract.test.ts`) — a `var(--x)`
 added to the source without regenerating this block fails the build. Do not
 hand-edit the rows between the markers below. See ADR-085 for how the
-generation and drift guard work, and ADR-087 for the rename and its
-compatibility design.
+generation and drift guard work, ADR-087 for the rename and its compatibility
+design, 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.
 
 <!-- theming-tokens:start -->
 | Custom property | Previous name | Controls | Kind | Has a default |

package/dist/app/App.d.ts

@@ -3,6 +3,7 @@ import type { SelectionContextMenuEvent } from './editor/SelectionContextMenuPlu
 import type { SweepFn } from './editor/AmbientCorrectionPlugin.js';
 import type { AnnotationCreateEvent } from './editor/AnnotationPlugin.js';
 import type { Annotation, AnnotationEditorHandle, AnnotationKindConfigs } from '../annotations/types.js';
+import type { DocumentOutlineHandle } from './editor/documentOutlineHandle.js';
 import type { WikiLinkPromotionMode } from './mapper/lexicalToMdast.js';
 export interface CursorState {
     offset: number;
@@ -57,8 +58,15 @@ interface AppProps {
     annotationLogger?: {
         warn: (message: string, ...args: unknown[]) => void;
     };
+    /**
+     * Connects the inner `<Editor>` to a `<DocumentOutline handle={…}>` rendered
+     * anywhere the host chooses (issue #69/#80). Create with
+     * `createDocumentOutlineHandle()` and pass the same object to both — an
+     * unsupplied handle mounts no outline plugin at all.
+     */
+    documentOutlineHandle?: DocumentOutlineHandle;
     /** Override className on the root div (default: "editor-app-root"). */
     className?: string;
 }
-export declare function App({ editable, autoFocus, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, className }: AppProps): import("react").JSX.Element;
+export declare function App({ editable, autoFocus, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, documentOutlineHandle, className }: AppProps): import("react").JSX.Element;
 export {};

package/dist/app/App.js

@@ -29,7 +29,7 @@ function computeMinimalEdits(oldText, newText) {
             newText: newTextContent,
         }];
 }
-export function App({ editable = true, autoFocus = false, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, className = 'editor-app-root' }) {
+export function App({ editable = true, autoFocus = false, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, documentOutlineHandle, className = 'editor-app-root' }) {
     const { bridge, logger } = useEditorHost();
     const log = useMemo(() => logger('slashmd/App'), [logger]);
     const { requestInit, applyTextEdits } = useHostMessages();
@@ -176,5 +176,5 @@ export function App({ editable = true, autoFocus = false, content: propContent,
     if (content === null) {
         return (_jsxs("div", { className: "editor-loading", children: [_jsx("div", { className: "loading-spinner" }), _jsx("span", { children: "Loading document..." })] }));
     }
-    return (_jsxs("div", { className: className, children: [error && (_jsx("div", { className: "editor-error-banner", role: "alert", children: error })), _jsx(Editor, { initialContent: content, autoFocus: autoFocus, contentVersion: contentVersion, cursorToRestoreRef: cursorStateRef, onChange: handleChange, onCursorChange: handleCursorChange, assetBaseUri: assetBaseUri, documentDirUri: documentDirUri, imagePathResolution: settings?.imagePathResolution ?? 'document', wikiLinkPromotion: wikiLinkPromotion, resolveLocalAsset: resolveLocalAsset, editable: editable, filePath: filePath, onSelectionContextMenu: onSelectionContextMenu, onSubstitutionDetected: onSubstitutionDetected, sweepRef: sweepRef, annotationKinds: annotationKinds, annotations: annotations, activeAnnotationId: activeAnnotationId, scrollToAnnotation: scrollToAnnotation, onCreateAnnotation: onCreateAnnotation, onActivateAnnotation: onActivateAnnotation, annotationEditorHandleRef: annotationEditorHandleRef, annotationLogger: annotationLogger })] }));
+    return (_jsxs("div", { className: className, children: [error && (_jsx("div", { className: "editor-error-banner", role: "alert", children: error })), _jsx(Editor, { initialContent: content, autoFocus: autoFocus, contentVersion: contentVersion, cursorToRestoreRef: cursorStateRef, onChange: handleChange, onCursorChange: handleCursorChange, assetBaseUri: assetBaseUri, documentDirUri: documentDirUri, imagePathResolution: settings?.imagePathResolution ?? 'document', wikiLinkPromotion: wikiLinkPromotion, resolveLocalAsset: resolveLocalAsset, editable: editable, filePath: filePath, onSelectionContextMenu: onSelectionContextMenu, onSubstitutionDetected: onSubstitutionDetected, sweepRef: sweepRef, annotationKinds: annotationKinds, annotations: annotations, activeAnnotationId: activeAnnotationId, scrollToAnnotation: scrollToAnnotation, onCreateAnnotation: onCreateAnnotation, onActivateAnnotation: onActivateAnnotation, annotationEditorHandleRef: annotationEditorHandleRef, annotationLogger: annotationLogger, documentOutlineHandle: documentOutlineHandle })] }));
 }

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

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

package/dist/app/editor/DocumentOutline.js

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

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

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

package/dist/app/editor/documentOutlineHandle.js

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

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

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

package/dist/app/editor/documentOutlineMarkdown.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/docs/decisions/adr-090.md

@@ -0,0 +1,141 @@
+# ADR-090: A Text-Based Contract Test Guards `App`'s Forwarding of `EditorProps`, Checked Against JSX-Attribute Reachability
+
+**Date:** 2026-08-19
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #80 (verveguy/liminis-editor)
+
+## Context
+
+Most consumers of `@liminis/editor` embed the package via `<App>`, not
+`<Editor>` directly — Zusammen, the primary downstream consumer, mounts
+`App`. `App` wraps `<Editor>` and forwards a curated, hand-maintained subset
+of `EditorProps` as `AppProps`, passing each one straight through in its
+render body's `<Editor .../>` call.
+
+Issue #69 added `documentOutlineHandle` to `EditorProps`. It did not add the
+same prop to `AppProps`, so `<App>` consumers had no way to reach the
+document outline — a capability exported from the package yet structurally
+unreachable through the component most consumers actually use. Nothing in
+the code made this omission visible; it was discovered the way this class of
+bug always is, one prop at a time, by a consumer hitting the gap.
+
+Because `App`'s forwarding list is maintained by hand with no mechanical
+link back to `EditorProps`, the same gap can recur for any future member
+added to `EditorProps`. This decision is about what closes that class of
+bug, not just the one prop: what the guard actually checks, and how it is
+implemented.
+
+Two questions needed a considered answer:
+
+1. **What does "forwarded" mean for the guard to check?** `AppProps`
+   declaring a member with a matching name is necessary but not sufficient —
+   a member could be added to the `AppProps` interface and never wired into
+   the `<Editor .../>` JSX call in `App`'s render body, leaving it exactly as
+   unreachable as `documentOutlineHandle` was, while satisfying a check that
+   only inspects the type declaration.
+2. **How should the guard extract that information?** The repo already has
+   an established contract-test convention (`tests/theming-contract.test.ts`,
+   `tests/package-manifest-contract.test.ts`), both of which parse source
+   files as text with targeted regexes rather than using a compiler API.
+   `typescript` is a devDependency (`^6.0.3`) but is not used
+   programmatically anywhere in the repo.
+
+## Decision
+
+**The guard checks JSX-attribute presence on the `<Editor .../>` element
+inside `App.tsx`, not `AppProps`-interface-member presence.**
+`scripts/lib/editor-app-prop-forwarding.mjs` extracts every top-level member
+name from `EditorProps` (`src/app/editor/Editor.tsx`) and every
+`attr={expr}` attribute name on the `<Editor .../>` JSX element in `App`'s
+render body (`src/app/App.tsx`). `tests/editor-app-forwarding-contract.test.ts`
+asserts every `EditorProps` member is one of those attribute names, or is
+listed in `EDITOR_INTERNAL_PROPS` (in the same lib module) with a stated
+reason. This directly encodes "forwarded" as "actually reaches the Editor
+element," which is strictly stronger than, and implies, "declared on
+`AppProps`."
+
+**Some `EditorProps` members are legitimately App-internal and belong in the
+allowlist, not the forwarding list.** `App` has two operating modes —
+IPC-driven (the default, used by the Electron host) and inline
+(`content`/`onChange` props, no IPC) — and several members are sourced from
+`App`'s own IPC or bookkeeping state in both modes rather than being a value
+a caller supplies: `contentVersion`, `cursorToRestoreRef`, `onCursorChange`,
+`assetBaseUri`, `documentDirUri`, `imagePathResolution`. A seventh,
+`initialContent`, is not internal in the same sense — it is reachable via
+`AppProps.content`, which is then multiplexed with IPC-sourced state before
+reaching `<Editor>` as `initialContent` — but it fails a same-name match, so
+it is recorded in the same allowlist with a reason distinguishing "renamed
+pass-through" from "genuinely internal." The guard's job is presence and
+classification, not semantic tracking of renames, so both cases are handled
+by the one allowlist mechanism rather than by building rename-detection
+logic for a single instance.
+
+**The guard is a text/regex-based contract test, matching the two existing
+precedents, not a TypeScript-compiler-API-based one.** Both `EditorProps`
+and `AppProps` are simple flat property lists today — every member is
+declared on a single line, even where its type contains nested braces or
+generics (`annotationEditorHandleRef?: MutableRefObject<AnnotationEditorHandle
+| null>`, `scrollToAnnotation?: { id: string; nonce: number } | null`). A
+brace-depth-tracking line scanner only needs to establish "am I at interface
+top level," not parse the nested type, which is sufficient for both files as
+they stand. Introducing `typescript`'s AST/type-checker API programmatically
+for the first time in this repo would be more robust against future
+syntactic variation (a multi-line declaration, a spread in the JSX call) but
+disproportionate to interfaces this simple, and would set a new pattern
+inconsistent with `theming-contract.test.ts` and
+`package-manifest-contract.test.ts`.
+
+## Consequences
+
+**Good:**
+
+- Adding a new `EditorProps` member without forwarding it on `<Editor .../>`
+  in `App.tsx`, and without an `EDITOR_INTERNAL_PROPS` entry, now fails CI
+  with a message naming the unclassified member — the exact recurrence this
+  issue exists to prevent.
+- Checking JSX-attribute reachability rather than interface-member
+  declaration closes the specific loophole a weaker guard would leave open:
+  a prop added to the `AppProps` type but never wired into the render body.
+- No new tooling dependency: the guard follows the same regex/text-parsing
+  shape as the two existing contract tests, so a maintainer who already
+  understands `theming-contract.test.ts` can read this one the same way.
+- `EDITOR_INTERNAL_PROPS`'s reasons are colocated with the guard itself
+  (`scripts/lib/editor-app-prop-forwarding.mjs`), discoverable by reading the
+  guard rather than requiring a separate document.
+
+**Bad / accepted:**
+
+- The extractor assumes every interface member and every JSX attribute is
+  declared on a single line, and that the `<Editor .../>` call uses
+  `attr={expr}` syntax throughout (no `{...props}` spread). Both hold for
+  every current member and for `App.tsx`'s current render body; a future
+  multi-line declaration or a spread refactor would need the extractor
+  updated, and would silently under- or over-count until then. Accepted as
+  the same tradeoff `theming-contract.test.ts` already accepts for CSS custom
+  properties.
+- `EDITOR_INTERNAL_PROPS` is a plain allowlist a contributor must remember to
+  update — the guard fails loudly if they forget, but nothing prevents an
+  entry from being added for the wrong reason (a prop that could have been
+  forwarded, allowlisted instead to make CI pass). The guard checks presence
+  and classification, not whether the classification is *correct* — that
+  remains a code-review concern, matching the spec's own stated edge case
+  that behavioral/type equivalence is out of the guard's scope.
+
+**Neutral:**
+
+- If `EditorProps` or `AppProps` later grow member declarations complex
+  enough that the single-line assumption breaks down, that is a signal to
+  revisit the AST-based approach this decision declined — not a reason to
+  build it preemptively now.
+
+## References
+
+- Issue #80 (this decision)
+- `scripts/lib/editor-app-prop-forwarding.mjs` — the extraction logic and `EDITOR_INTERNAL_PROPS` allowlist
+- `tests/editor-app-forwarding-contract.test.ts` — the contract test itself
+- `src/app/App.tsx` — `AppProps`, and the `<Editor .../>` render-body call the guard reads
+- `src/app/editor/Editor.tsx` — `EditorProps`, including `documentOutlineHandle` (added by #69, the prop this issue forwards)
+- `tests/theming-contract.test.ts`, `tests/package-manifest-contract.test.ts` — the existing regex/text-based contract-test precedent this guard follows
+- `docs/decisions/adr-088.md` — issue #69's own decision record, the origin of `documentOutlineHandle`

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")

package/docs/editor-api.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liminis/editor",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "//publishing": "Publishing is deliberate, never incidental. `private: true` was this package's guard until verveguy/liminis-editor#39 took the publish decision; it is gone because that decision was taken, not because it was tidied away. The guard is now `prepublishOnly` -> scripts/guard-publish.mjs, which refuses unless LIMINIS_ALLOW_PUBLISH=1 is set explicitly. That variable is set at step scope in .github/workflows/publish.yml and nowhere else, so a release is the only path that publishes. Note that `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), which is why the guard is a script rather than a flag.",
   "license": "MIT",
   "description": "Lexical-based markdown WYSIWYG editor with mdast round-trip and a host-injection seam",
@@ -75,6 +75,7 @@
     "test:coverage": "vitest run --coverage",
     "verify:package": "node scripts/verify-package.mjs",
     "docs:theming": "node scripts/generate-theming-docs.mjs",
+    "docs:theming-baseline": "node scripts/update-theming-baseline.mjs",
     "demo": "node scripts/run-demo.mjs",
     "build:examples": "node scripts/build-examples.mjs",
     "build:site": "node scripts/build-site.mjs"