@liminis/editor 0.2.0 → 0.2.1

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/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/editor-api.md

@@ -111,6 +111,33 @@ 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>
+  )
+}
+```
+
 ## 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.1",
   "//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",