@liminis/editor 0.1.0 → 0.2.0

package/README.md

@@ -194,25 +194,137 @@ Note the contrast with the failure above: forgetting the *import* fails
 silently, while adding it without a declaration fails loudly at compile time.
 Neither is a package defect, but only one of them tells you what is wrong.
 
-### If you use Tailwind
+### Theming: CSS custom properties
+
+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.
+
+**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
+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.
+
+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.
+
+<!-- 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) |
+<!-- theming-tokens:end -->
+
+**A worked example.** To match a host's own palette, override a subset of
+tokens after importing `styles.css` — no rebuild of the editor required:
 
-Some of the editor's markup also uses Tailwind utility classes. Tailwind v4
-generates utilities by scanning your source, and **its automatic source
-detection skips `node_modules`** — so without telling it where to look, those
-classes are simply absent. Again: silent, not an error.
+```css
+@import '@liminis/editor/styles.css';
 
-Add an explicit `@source` for the package's built output in the CSS file where
-you import Tailwind:
+:root {
+  --liminis-editor-foreground: #1a1a2e;
+  --liminis-editor-border: #d0d0e0;
+  --liminis-editor-link: #4b3fce;
+  --liminis-editor-code-bg: #f4f4fb;
+}
 
-```css
-@import "tailwindcss";
-@source "../node_modules/@liminis/editor/dist";
+.dark {
+  --liminis-editor-foreground: #eaeaf5;
+  --liminis-editor-border: #3a3a55;
+  --liminis-editor-link: #9d90ff;
+  --liminis-editor-code-bg: #1e1e2e;
+}
 ```
 
-Adjust the relative path to point at your installed copy. In a pnpm workspace
-the real path may be under `node_modules/.pnpm/` — pointing `@source` at the
-symlinked path works, but verify a distinctive utility class actually appears in
-your generated CSS rather than assuming it.
+Only the tokens you override need to change — everything else keeps the
+package default. `--liminis-editor-foreground` and `--liminis-editor-border`
+are the two most widely referenced tokens, so they're usually the
+highest-value place to start.
+
+#### Migrating from the old names
+
+Before `0.2.0`, these tokens were split across four inconsistent prefixes:
+`--vscode-*`, `--slashmd-*`, `--color-*` and `--checkbox-*`. `0.2.0` renames
+all 59 of them to `--liminis-editor-*`, but **a host that still only supplies
+the old names keeps working unchanged** — every renamed token resolves
+`--liminis-editor-x` first, then falls back to its specific previous name,
+so nothing breaks silently on upgrade. The old prefixes are deprecated as of
+`0.2.0` and will be removed in a future major release; migrate at your own
+pace using the table above's **Previous name** column, which lists each
+renamed property's exact old name — the mapping isn't always a mechanical
+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.
 
 ## Annotations
 

package/dist/annotations/types.d.ts

@@ -156,4 +156,20 @@ export interface AnnotationEditorHandle {
     removeMarksForAnnotation: (annotationId: string) => void;
     /** The current live range of every marked passage, keyed by annotation id. */
     collectLiveAnchorSnapshots: (markdownText: string) => Map<string, AnchorRange>;
+    /**
+     * Current on-screen geometry for existing, currently-rendered annotation
+     * marks (#73), keyed by annotation id — one `DOMRect` per constituent
+     * `MarkNode` (a multi-block annotation spans several sibling nodes), in
+     * document order. Computed fresh at call time from `getBoundingClientRect()`
+     * (viewport-relative, not scroll-container-relative); never cached.
+     *
+     * `annotationIds` omitted returns geometry for every annotation with at
+     * least one currently live mark. An id with no live mark (unknown, removed,
+     * or not yet rendered) is simply absent from the result — this never throws.
+     *
+     * Two annotation ids can legitimately report the same rect(s): overlapping
+     * annotations may share one `MarkNode`, and its rect is reported under each
+     * id it carries.
+     */
+    getMarkRects: (annotationIds?: readonly string[]) => Map<string, DOMRect[]>;
 }

package/dist/app/App.d.ts

@@ -57,7 +57,7 @@ interface AppProps {
     annotationLogger?: {
         warn: (message: string, ...args: unknown[]) => void;
     };
-    /** Override className on the root div (default: "min-h-screen p-0"). */
+    /** 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;

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 = 'min-h-screen p-0' }) {
+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' }) {
     const { bridge, logger } = useEditorHost();
     const log = useMemo(() => logger('slashmd/App'), [logger]);
     const { requestInit, applyTextEdits } = useHostMessages();
@@ -174,7 +174,7 @@ export function App({ editable = true, autoFocus = false, content: propContent,
         cursorStateRef.current = cursor;
     }, []);
     if (content === null) {
-        return (_jsxs("div", { className: "flex items-center justify-center gap-3 min-h-screen text-[var(--vscode-foreground)] opacity-70", children: [_jsx("div", { className: "loading-spinner" }), _jsx("span", { children: "Loading document..." })] }));
+        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: "fixed top-0 left-0 right-0 px-4 py-2 bg-red-500 text-white text-center z-[1000]", 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 })] }));
 }

package/dist/app/editor/AnchorScrollPlugin.js

@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
 import { useEditorHost } from '../../host/context.js';
+import { scrollElementIntoView } from './scrollContainer.js';
 /**
  * Reduce text to a GitHub-style anchor slug so a link fragment matches a heading
  * regardless of punctuation the anchor drops. GitHub lowercases, removes
@@ -20,26 +21,6 @@ function normalizeForMatch(text) {
         .replace(/[\s-]+/g, '-') // spaces and dash runs → single hyphen
         .replace(/^-+|-+$/g, ''); // trim stray hyphens
 }
-/**
- * Find the scrollable container for a heading: the known editor scroll ids first,
- * then the nearest ancestor that actually scrolls (robust to host markup).
- */
-function scrollContainerFor(heading) {
-    // Assumes the two known ids are never nested inside one another; neither
-    // known host does. If that ever changes, the closer one should win instead.
-    const byId = heading.closest('#editor-scroll-container') ||
-        heading.closest('#editor-panel-scroll-container');
-    if (byId)
-        return byId;
-    let el = heading.parentElement;
-    while (el) {
-        const overflowY = getComputedStyle(el).overflowY;
-        if (/(auto|scroll)/.test(overflowY) && el.scrollHeight > el.clientHeight)
-            return el;
-        el = el.parentElement;
-    }
-    return null;
-}
 /**
  * Scroll the editor to the heading whose normalized text matches `anchor`.
  * Returns true if a matching heading was found and scrolled — false if not (yet)
@@ -63,20 +44,7 @@ function scrollToHeading(editor, anchor) {
     const heading = headings.find((h) => normalizeForMatch(h.textContent || '') === normalizedAnchor);
     if (!heading)
         return false;
-    const container = scrollContainerFor(heading);
-    if (container) {
-        // rect-based offset is robust regardless of the heading's offsetParent;
-        // leave a small margin so the heading sits near the top, not flush against it.
-        const MARGIN = 16;
-        const top = Math.max(0, heading.getBoundingClientRect().top -
-            container.getBoundingClientRect().top +
-            container.scrollTop -
-            MARGIN);
-        container.scrollTo({ top, behavior: 'smooth' });
-    }
-    else {
-        heading.scrollIntoView({ behavior: 'smooth', block: 'start' });
-    }
+    scrollElementIntoView(heading);
     return true;
 }
 /**

package/dist/app/editor/AnnotationSurface.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useMemo, useRef } from 'react';
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
 import { deriveMarkerTargets, } from '../../annotations/types.js';
-import { collectLiveAnchorSnapshots, placeMarksForAnchors, removeMarksForAnnotation, removeMarksForAnnotations, } from './annotation-marks.js';
+import { collectLiveAnchorSnapshots, getMarkRects, placeMarksForAnchors, removeMarksForAnnotation, removeMarksForAnnotations, } from './annotation-marks.js';
 import { AnnotationPlugin } from './AnnotationPlugin.js';
 import { AnnotationMarkerPlugin } from './AnnotationMarkerPlugin.js';
 import { registerMarkOverlapResolver } from './mark-overlap-resolver.js';
@@ -84,6 +84,7 @@ function AnnotationEditorHandlePlugin({ handleRef, wikiLinkPromotion, }) {
         handleRef.current = {
             removeMarksForAnnotation: (id) => removeMarksForAnnotation(editor, id),
             collectLiveAnchorSnapshots: (markdownText) => collectLiveAnchorSnapshots(editor, markdownText, { wikiLinkPromotion }),
+            getMarkRects: (annotationIds) => getMarkRects(editor, annotationIds),
         };
         return () => {
             handleRef.current = null;

package/dist/app/editor/CorrectionPanelPlugin.js

@@ -29,10 +29,10 @@ const panelStyle = () => {
         padding: '12px',
         minWidth: '280px',
         maxWidth: '360px',
-        background: `var(--vscode-menu-background, ${dark ? '#252526' : '#ffffff'})`,
-        border: `1px solid var(--vscode-menu-border, ${dark ? '#454545' : '#d4d4d4'})`,
+        background: `var(--liminis-editor-menu-background, var(--vscode-menu-background, ${dark ? '#252526' : '#ffffff'}))`,
+        border: `1px solid var(--liminis-editor-menu-border, var(--vscode-menu-border, ${dark ? '#454545' : '#d4d4d4'}))`,
         boxShadow: dark ? '0 4px 16px rgba(0,0,0,0.4)' : '0 4px 16px rgba(0,0,0,0.15)',
-        color: `var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'})`,
+        color: `var(--liminis-editor-menu-foreground, var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'}))`,
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: '13px',
     };
@@ -260,8 +260,8 @@ export function CorrectionPanelPlugin() {
     if (!isOpen)
         return null;
     const dark = isDark();
-    const borderColor = `var(--vscode-menu-border, ${dark ? '#454545' : '#d4d4d4'})`;
-    const hoverBg = `var(--vscode-menu-selectionBackground, ${dark ? '#094771' : '#e8e8e8'})`;
+    const borderColor = `var(--liminis-editor-menu-border, var(--vscode-menu-border, ${dark ? '#454545' : '#d4d4d4'}))`;
+    const hoverBg = `var(--liminis-editor-menu-selectionBackground, var(--vscode-menu-selectionBackground, ${dark ? '#094771' : '#e8e8e8'}))`;
     const mutedColor = dark ? '#888888' : '#999999';
     const inputBg = dark ? '#1e1e1e' : '#f5f5f5';
     const warningBg = dark ? '#4a3500' : '#fff8e1';
@@ -273,12 +273,12 @@ export function CorrectionPanelPlugin() {
         cursor: 'pointer',
         border: `1px solid ${borderColor}`,
         background: 'transparent',
-        color: `var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'})`,
+        color: `var(--liminis-editor-menu-foreground, var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'}))`,
     };
     const btnPrimary = {
         ...btnBase,
-        background: `var(--vscode-button-background, ${dark ? '#0e639c' : '#007acc'})`,
-        color: `var(--vscode-button-foreground, #ffffff)`,
+        background: `var(--liminis-editor-button-background, var(--vscode-button-background, ${dark ? '#0e639c' : '#007acc'}))`,
+        color: `var(--liminis-editor-button-foreground, var(--vscode-button-foreground, #ffffff))`,
         border: 'none',
         opacity: isSubmitting ? 0.6 : 1,
     };
@@ -297,7 +297,7 @@ export function CorrectionPanelPlugin() {
                             borderRadius: '4px',
                             border: `1px solid ${borderColor}`,
                             background: inputBg,
-                            color: `var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'})`,
+                            color: `var(--liminis-editor-menu-foreground, var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'}))`,
                             fontSize: '13px',
                             boxSizing: 'border-box',
                         }, onKeyDown: (e) => {
@@ -324,7 +324,7 @@ function SuggestionItem({ name, hoverBg, onClick, }) {
             cursor: 'pointer',
             fontSize: '13px',
             borderRadius: '3px',
-            color: `var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'})`,
+            color: `var(--liminis-editor-menu-foreground, var(--vscode-menu-foreground, ${dark ? '#cccccc' : '#333333'}))`,
         }, onMouseEnter: (e) => {
             e.currentTarget.style.background = hoverBg;
         }, onMouseLeave: (e) => {

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

@@ -0,0 +1,17 @@
+import type { DocumentOutlineHandle } 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;
+}
+/**
+ * Renders a navigable "on this page" heading outline for one editor
+ * instance, driven by the `DocumentOutlineHandle` shared with that editor's
+ * `<Editor documentOutlineHandle={…}>` (issue #69).
+ *
+ * Renders nothing when the document has no headings (FR-007). Visibility,
+ * 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;

package/dist/app/editor/DocumentOutline.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
+/**
+ * Renders a navigable "on this page" heading outline for one editor
+ * instance, driven by the `DocumentOutlineHandle` shared with that editor's
+ * `<Editor documentOutlineHandle={…}>` (issue #69).
+ *
+ * Renders nothing when the document has no headings (FR-007). Visibility,
+ * 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 }) {
+    // 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]);
+    const getSnapshot = useCallback(() => handle.getSnapshot(), [handle]);
+    const snapshot = useSyncExternalStore(subscribe, getSnapshot);
+    const listRef = useRef(null);
+    // Keep the active entry visible within the outline itself (US2-AC2).
+    useEffect(() => {
+        if (snapshot.activeIndex === null)
+            return;
+        const item = listRef.current?.querySelector(`[data-outline-index="${snapshot.activeIndex}"]`);
+        item?.scrollIntoView({ block: 'nearest' });
+    }, [snapshot.activeIndex]);
+    if (snapshot.entries.length === 0)
+        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));
+            }) }) }));
+}

package/dist/app/editor/DragHandlePlugin.js

@@ -293,7 +293,7 @@ export function DragHandlePlugin() {
                     left: 0,
                     right: 0,
                     height: 2,
-                    background: 'var(--vscode-focusBorder, #007acc)',
+                    background: 'var(--liminis-editor-focusBorder, var(--vscode-focusBorder, #007acc))',
                     pointerEvents: 'none',
                     zIndex: 100,
                 } }))] }));

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

@@ -1,4 +1,5 @@
 import { type MutableRefObject } from 'react';
+import type { DocumentOutlineHandle } from './documentOutlineHandle.js';
 import type { SelectionContextMenuEvent } from './SelectionContextMenuPlugin.js';
 import { type SweepFn } from './AmbientCorrectionPlugin.js';
 import type { Annotation, AnnotationEditorHandle, AnnotationKindConfigs } from '../../annotations/types.js';
@@ -79,6 +80,14 @@ interface EditorProps {
     annotationLogger?: {
         warn: (message: string, ...args: unknown[]) => void;
     };
+    /**
+     * Connects this editor to a `<DocumentOutline handle={…}>` rendered
+     * anywhere the host chooses (issue #69). Create with
+     * `createDocumentOutlineHandle()` and pass the same object to both — an
+     * unsupplied handle mounts no outline plugin at all, so an outline-less
+     * consumer pays nothing for it.
+     */
+    documentOutlineHandle?: DocumentOutlineHandle;
 }
-export declare function Editor({ initialContent, autoFocus, contentVersion, cursorToRestoreRef, onChange, onCursorChange, onSelectionContextMenu, assetBaseUri, documentDirUri, imagePathResolution, wikiLinkPromotion, resolveLocalAsset, editable, filePath, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, }: EditorProps): import("react").JSX.Element;
+export declare function Editor({ initialContent, autoFocus, contentVersion, cursorToRestoreRef, onChange, onCursorChange, onSelectionContextMenu, assetBaseUri, documentDirUri, imagePathResolution, wikiLinkPromotion, resolveLocalAsset, editable, filePath, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, documentOutlineHandle, }: EditorProps): import("react").JSX.Element;
 export {};

package/dist/app/editor/Editor.js

@@ -32,6 +32,7 @@ import { FrontmatterPlugin } from './FrontmatterPlugin.js';
 import { WikiLinkExistencePlugin } from './WikiLinkExistencePlugin.js';
 import { WikiLinkFormatPlugin } from './WikiLinkFormatPlugin.js';
 import { AnchorScrollPlugin } from './AnchorScrollPlugin.js';
+import { OutlinePlugin } from './OutlinePlugin.js';
 import { SelectionContextMenuPlugin } from './SelectionContextMenuPlugin.js';
 import { CorrectionPanelPlugin } from './CorrectionPanelPlugin.js';
 import { AmbientCorrectionPlugin } from './AmbientCorrectionPlugin.js';
@@ -401,7 +402,7 @@ const DEBOUNCE_DELAY = 100;
 // Window after an external content load (file open/reload) or editor-initiated change
 // during which we suppress onChange/reload to avoid feedback loops and normalization noise.
 const POST_LOAD_SUPPRESS_MS = 500;
-export function Editor({ initialContent, autoFocus = false, contentVersion = 0, cursorToRestoreRef, onChange, onCursorChange, onSelectionContextMenu, assetBaseUri, documentDirUri, imagePathResolution, wikiLinkPromotion, resolveLocalAsset, editable = true, filePath, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId = null, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, }) {
+export function Editor({ initialContent, autoFocus = false, contentVersion = 0, cursorToRestoreRef, onChange, onCursorChange, onSelectionContextMenu, assetBaseUri, documentDirUri, imagePathResolution, wikiLinkPromotion, resolveLocalAsset, editable = true, filePath, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId = null, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, documentOutlineHandle, }) {
     // Annotations are on only when the host configured at least one kind
     // (FR-004). Everything annotation-specific hangs off this flag, including
     // the dynamic import below — with no kinds, none of those modules is ever
@@ -530,7 +531,7 @@ export function Editor({ initialContent, autoFocus = false, contentVersion = 0,
         onError: editorOnError,
         editable,
     };
-    return (_jsx(AssetContext.Provider, { value: assetContextValue, children: _jsx(LexicalComposer, { initialConfig: initialConfig, children: _jsx("div", { className: "relative max-w-[800px] ml-5 mr-1 pl-6 pr-6", children: _jsxs("div", { className: "editor-inner relative", children: [_jsx(RichTextPlugin, { contentEditable: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Markdown editor" }), placeholder: _jsx("div", { className: "editor-placeholder", children: "Type '/' for commands..." }), ErrorBoundary: LexicalErrorBoundary }), _jsx(HistoryPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(OrderedTaskListPlugin, {}), _jsx(TabIndentationPlugin, {}), _jsx(LinkPlugin, {}), _jsx(TablePlugin, {}), _jsx(CodeHighlightPlugin, {}), _jsx(OnChangePlugin, { onChange: handleChange, ignoreSelectionChange: true }), _jsx(InitializePlugin, { content: initialContent, onOffsets: handleOffsets }), _jsx(EditablePlugin, { editable: editable }), autoFocus && _jsx(AutoFocusPlugin, {}), _jsx(CursorTrackingPlugin, { onCursorChange: onCursorChange }), _jsx(CursorRestorePlugin, { contentVersion: contentVersion, cursorToRestoreRef: effectiveCursorRef }), _jsx(ExternalUpdatePlugin, { content: initialContent, lastExternalLoadRef: lastExternalLoadRef, currentContentRef: currentContentRef, lastEditorChangeRef: lastEditorChangeRef, onOffsets: handleOffsets }), _jsx(SlashMenuPlugin, {}), _jsx(DragHandlePlugin, {}), _jsx(MarkdownShortcutsPlugin, {}), _jsx(TableActionsPlugin, {}), _jsx(CodeBlockPlugin, {}), _jsx(TogglePlugin, {}), _jsx(ImagePlugin, {}), _jsx(BlockClickPlugin, {}), _jsx(LinkClickPlugin, { editable: editable }), _jsx(Toolbar, { annotationAffordances: toolbarAnnotationAffordances }), _jsx(SearchPlugin, {}), _jsx(FrontmatterPlugin, { filePath: filePath }), _jsx(WikiLinkExistencePlugin, {}), _jsx(WikiLinkFormatPlugin, {}), _jsx(AnchorScrollPlugin, {}), _jsx(SelectionContextMenuPlugin, { onSelectionContextMenu: onSelectionContextMenu, 
+    return (_jsx(AssetContext.Provider, { value: assetContextValue, children: _jsx(LexicalComposer, { initialConfig: initialConfig, children: _jsx("div", { className: "editor-container", children: _jsxs("div", { className: "editor-inner", children: [_jsx(RichTextPlugin, { contentEditable: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Markdown editor" }), placeholder: _jsx("div", { className: "editor-placeholder", children: "Type '/' for commands..." }), ErrorBoundary: LexicalErrorBoundary }), _jsx(HistoryPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(OrderedTaskListPlugin, {}), _jsx(TabIndentationPlugin, {}), _jsx(LinkPlugin, {}), _jsx(TablePlugin, {}), _jsx(CodeHighlightPlugin, {}), _jsx(OnChangePlugin, { onChange: handleChange, ignoreSelectionChange: true }), _jsx(InitializePlugin, { content: initialContent, onOffsets: handleOffsets }), _jsx(EditablePlugin, { editable: editable }), autoFocus && _jsx(AutoFocusPlugin, {}), _jsx(CursorTrackingPlugin, { onCursorChange: onCursorChange }), _jsx(CursorRestorePlugin, { contentVersion: contentVersion, cursorToRestoreRef: effectiveCursorRef }), _jsx(ExternalUpdatePlugin, { content: initialContent, lastExternalLoadRef: lastExternalLoadRef, currentContentRef: currentContentRef, lastEditorChangeRef: lastEditorChangeRef, onOffsets: handleOffsets }), _jsx(SlashMenuPlugin, {}), _jsx(DragHandlePlugin, {}), _jsx(MarkdownShortcutsPlugin, {}), _jsx(TableActionsPlugin, {}), _jsx(CodeBlockPlugin, {}), _jsx(TogglePlugin, {}), _jsx(ImagePlugin, {}), _jsx(BlockClickPlugin, {}), _jsx(LinkClickPlugin, { editable: editable }), _jsx(Toolbar, { annotationAffordances: toolbarAnnotationAffordances }), _jsx(SearchPlugin, {}), _jsx(FrontmatterPlugin, { filePath: filePath }), _jsx(WikiLinkExistencePlugin, {}), _jsx(WikiLinkFormatPlugin, {}), _jsx(AnchorScrollPlugin, {}), documentOutlineHandle && _jsx(OutlinePlugin, { handle: documentOutlineHandle }), _jsx(SelectionContextMenuPlugin, { onSelectionContextMenu: onSelectionContextMenu, 
                             // Only kinds that actually ask for a context-menu affordance:
                             // with none configured, or one on another surface, AnnotationPlugin
                             // would decline the command anyway, and dispatching from here would

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

@@ -0,0 +1,14 @@
+import { type DocumentOutlineHandle } from './documentOutlineHandle.js';
+/**
+ * OutlinePlugin - Feeds a `DocumentOutlineHandle` from inside the Lexical
+ * tree: the current H1-H5 heading list (FR-002/FR-005), which heading is at
+ * the top of the viewport (FR-004, rAF-throttled for rapid-scroll/large-doc
+ * performance), and the imperative scroll-to-heading action (FR-003) the
+ * handle's `scrollToHeading` forwards to.
+ *
+ * Mounted only when a host supplies `documentOutlineHandle` to `<Editor>` —
+ * an outline-less consumer pays nothing for this plugin.
+ */
+export declare function OutlinePlugin({ handle }: {
+    handle: DocumentOutlineHandle;
+}): null;

package/dist/app/editor/OutlinePlugin.js

@@ -0,0 +1,133 @@
+import { useEffect } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { $getRoot } from 'lexical';
+import { $isHeadingNode } from '@lexical/rich-text';
+import { scrollContainerFor, scrollElementIntoView } from './scrollContainer.js';
+const HEADING_SELECTOR = [
+    '.editor-heading-h1',
+    '.editor-heading-h2',
+    '.editor-heading-h3',
+    '.editor-heading-h4',
+    '.editor-heading-h5',
+].join(',');
+function readHeadingEntries() {
+    const entries = [];
+    let index = 0;
+    for (const child of $getRoot().getChildren()) {
+        if (!$isHeadingNode(child))
+            continue;
+        // H6 has no theme class (`Editor.tsx`'s `editorTheme.heading` maps only
+        // h1-h5), so it never appears in `HEADING_SELECTOR` either — excluding it
+        // here keeps `entries` and the rendered heading DOM in the same order.
+        const level = Number(child.getTag().slice(1));
+        if (level < 1 || level > 5)
+            continue;
+        entries.push({ index: index++, level: level, text: child.getTextContent() });
+    }
+    return entries;
+}
+/**
+ * OutlinePlugin - Feeds a `DocumentOutlineHandle` from inside the Lexical
+ * tree: the current H1-H5 heading list (FR-002/FR-005), which heading is at
+ * the top of the viewport (FR-004, rAF-throttled for rapid-scroll/large-doc
+ * performance), and the imperative scroll-to-heading action (FR-003) the
+ * handle's `scrollToHeading` forwards to.
+ *
+ * Mounted only when a host supplies `documentOutlineHandle` to `<Editor>` —
+ * an outline-less consumer pays nothing for this plugin.
+ */
+export function OutlinePlugin({ handle }) {
+    const [editor] = useLexicalComposerContext();
+    // Safe: `DocumentOutlineHandle`'s private brand (see documentOutlineHandle.ts)
+    // makes it nominal, so only an `OutlineHandleImpl` from
+    // `createDocumentOutlineHandle()` can type-check as one here.
+    const impl = handle;
+    useEffect(() => {
+        let entries = [];
+        let activeIndex = null;
+        // No listener is attached until `reattachScrollListener` resolves a
+        // first target — `null`, not `window`, so that a document whose scroll
+        // container falls back to `window` still gets a listener attached (a
+        // pre-resolved `window` initial value would equal that same fallback and
+        // the early-return below would skip attaching one at all).
+        let scrollTarget = null;
+        const publish = () => {
+            impl.publish({ entries, activeIndex });
+        };
+        let scheduledFrame = 0;
+        const updateActive = () => {
+            scheduledFrame = 0;
+            const rootElement = editor.getRootElement();
+            if (!rootElement)
+                return;
+            const headings = Array.from(rootElement.querySelectorAll(HEADING_SELECTOR));
+            let next = null;
+            if (headings.length > 0) {
+                const container = scrollContainerFor(headings[0]);
+                const referenceTop = container ? container.getBoundingClientRect().top : 0;
+                next = 0;
+                for (let i = 0; i < headings.length; i++) {
+                    if (headings[i].getBoundingClientRect().top - referenceTop <= 0)
+                        next = i;
+                    else
+                        break;
+                }
+                // Guards against a heading-DOM/entries mismatch rather than assuming
+                // they always agree in length.
+                if (next >= entries.length)
+                    next = entries.length > 0 ? entries.length - 1 : null;
+            }
+            if (next !== activeIndex) {
+                activeIndex = next;
+                publish();
+            }
+        };
+        const scheduleUpdateActive = () => {
+            if (scheduledFrame)
+                return;
+            scheduledFrame = requestAnimationFrame(updateActive);
+        };
+        /**
+         * Re-resolve the scroll container from the current DOM and move the
+         * listener there if it changed. Called on every entries update — not
+         * just once at mount — because the container is normally only
+         * discoverable once at least one heading has actually rendered.
+         */
+        const reattachScrollListener = () => {
+            const rootElement = editor.getRootElement();
+            const firstHeading = rootElement?.querySelector(HEADING_SELECTOR) ?? null;
+            const nextTarget = firstHeading ? scrollContainerFor(firstHeading) ?? window : window;
+            if (nextTarget === scrollTarget)
+                return;
+            scrollTarget?.removeEventListener('scroll', scheduleUpdateActive);
+            nextTarget.addEventListener('scroll', scheduleUpdateActive, { passive: true });
+            scrollTarget = nextTarget;
+        };
+        const updateEntries = () => {
+            editor.getEditorState().read(() => {
+                entries = readHeadingEntries();
+            });
+            if (activeIndex !== null && activeIndex >= entries.length) {
+                activeIndex = entries.length > 0 ? entries.length - 1 : null;
+            }
+            reattachScrollListener();
+            scheduleUpdateActive();
+            publish();
+        };
+        updateEntries();
+        const unregisterUpdateListener = editor.registerUpdateListener(updateEntries);
+        impl.connect((index) => {
+            const target = editor.getRootElement()?.querySelectorAll(HEADING_SELECTOR)[index];
+            if (target)
+                scrollElementIntoView(target);
+        });
+        return () => {
+            unregisterUpdateListener();
+            scrollTarget?.removeEventListener('scroll', scheduleUpdateActive);
+            if (scheduledFrame)
+                cancelAnimationFrame(scheduledFrame);
+            impl.disconnect();
+        };
+    }, [editor, impl]);
+    return null;
+}