@liminis/editor 0.1.0 → 0.2.0

package/docs/decisions/adr-088.md

@@ -0,0 +1,136 @@
+# ADR-088: The Document Outline Widget Stays Host-Seam-Free and Is Wired Through a Shared Controller Object, Not a Ref
+
+**Date:** 2026-08-18
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #69 (verveguy/liminis-editor)
+
+## Context
+
+`liminis-app`'s table-of-contents widget — heading list, click-to-scroll,
+scroll-spy — lived entirely in the app, duplicated its click-to-scroll logic
+across two call sites, and hardcoded two different scroll-container ids
+between them (`editor-panel-scroll-container` in one, `editor-scroll-container`
+in the other). Extracting it into `@liminis/editor` as a considered export
+(FR-001) raised two design questions the issue's own research flagged as
+needing a deliberate answer rather than an implicit one:
+
+1. **FR-006** requires the widget not hardcode a host DOM id or assume a
+   specific scroll container, and says the scroll container/element
+   positions "MUST reach it through the editor-host seam (or be owned by the
+   package)". `AnchorScrollPlugin` — an existing plugin that scrolls the
+   editor to an anchor-linked heading — already solves exactly this problem
+   package-locally: it tries the two known host ids, then walks DOM
+   ancestors for the nearest actually-scrolling one, with no
+   `EditorHostServices` involvement at all. Whether the outline widget should
+   reuse that precedent or instead earn `EditorHostServices` a new
+   scroll-container/element-rect member was open.
+
+2. `<Editor>` renders a fixed internal plugin list with no slot a consumer
+   can render into, and FR-008 requires the widget's placement to be entirely
+   the consumer's decision — so the rendered list cannot simply be "a child
+   of `<Editor>`" the way `AnchorScrollPlugin` is. It has to be a separate,
+   freely-placed component, while the data it renders and the scroll-to
+   action it triggers live inside the Lexical tree `<Editor>` owns. How those
+   two pieces communicate — a component mounted inside `LexicalComposer`
+   feeding data out, and a component mounted anywhere reading it back in —
+   was undecided. The package's one existing precedent for "read the live
+   editor from outside `<Editor>`", `annotationEditorHandleRef`, is a
+   `MutableRefObject` populated after mount and read imperatively later. That
+   doesn't fit here: the outline component has to *reactively* re-render on
+   every scroll and edit, and mutating a ref's `.current` does not notify a
+   sibling component holding the same ref.
+
+## Decision
+
+**No new `EditorHostServices` member.** The outline widget's scroll-spy and
+scroll-to-heading logic reuse `AnchorScrollPlugin`'s container-discovery
+logic directly — extracted, as a pure refactor, into a shared
+`src/app/editor/scrollContainer.ts` (`scrollContainerFor()`,
+`scrollElementIntoView()`) rather than duplicated. FR-006's own text permits
+this explicitly ("... or be owned by the package"), and the only named
+beneficiary of a shared host-seam capability for scroll-container/element-rect
+data — Zusammen issue #126, margin comments aligned to text — is not yet
+planned. Building a generalized host-seam primitive now, for a consumer that
+doesn't exist yet, would be speculative and untested; `scrollContainer.ts` is
+deliberately factored out so that whenever #126 does start, it has a single,
+already-proven extraction point to build from instead of a second
+copy-pasted implementation.
+
+**A shared controller object connects `<Editor>` to the outline component,
+not a ref.** `createDocumentOutlineHandle()` returns a `DocumentOutlineHandle`
+— a React external store (`subscribe`/`getSnapshot`, consumed with
+`useSyncExternalStore`) plus an imperative `scrollToHeading(index)`. The
+consumer creates one per editor instance and passes the *same* object to both
+`<Editor documentOutlineHandle={handle}>` and
+`<DocumentOutline handle={handle}>`. Internally, an `OutlinePlugin` — mounted
+inside `<Editor>`'s `LexicalComposer` tree only when `documentOutlineHandle`
+is supplied, so an outline-less consumer pays nothing for it — walks
+`HeadingNode`s on every `registerUpdateListener` firing to populate entries,
+runs an rAF-throttled scroll-spy scoped to `editor.getRootElement()`'s
+`.editor-heading-hN` elements, and implements `scrollToHeading` by reusing
+`scrollElementIntoView`. `<DocumentOutline>` never talks to Lexical directly;
+it only reads the handle.
+
+Because the handle is created per call site rather than shared globally, an
+outline for one editor instance can never aggregate headings from a second,
+simultaneously-mounted editor — the correctness gap `EditorColumn`'s current
+`document.querySelectorAll`-based implementation has today, closed as a
+side effect of this shape rather than as a separate fix.
+
+Entries are derived from **live Lexical state**
+(`HeadingNode.getTextContent()`), not by re-parsing the markdown string:
+`getTextContent()` already reduces inline content — including inline code —
+to plain text, matching FR-002 without a second parse pass, and the same
+update listener that populates entries already satisfies FR-005 (the
+outline stays current) with no extra staleness tracking.
+
+## Consequences
+
+**Good:**
+
+- FR-006 is satisfied with zero new, untested API surface. `AnchorScrollPlugin`
+  already demonstrated the DOM-ancestor-walk approach works and is exercised
+  by `host-plugins.test.tsx`; the outline widget inherits that coverage
+  rather than duplicating the risk with a second implementation.
+- `scrollContainer.ts` is a real extraction, not a footnote: both
+  `AnchorScrollPlugin` and `OutlinePlugin` call the same functions, so a fix
+  to the container-discovery heuristic fixes both at once, and Zusammen #126
+  has a concrete starting point instead of a green-field design.
+- The handle-sharing pattern gives `<DocumentOutline>` true placement freedom
+  (FR-008) — it can render anywhere, including outside `<Editor>`'s own
+  subtree — while still reacting live to scroll and edits, which a
+  `MutableRefObject` cannot do for a sibling reader.
+- Multi-editor correctness (no cross-instance heading aggregation) falls out
+  of the design for free, rather than requiring a scoping fix bolted on
+  afterward.
+
+**Bad / accepted:**
+
+- The DOM-ancestor-walk heuristic — "nearest ancestor with `overflow-y:
+  auto|scroll` and real overflow" — is inherited, not newly assessed; an
+  unusual host layout could still pick the wrong container. This was already
+  an accepted risk for `AnchorScrollPlugin` before this issue.
+- The handle-sharing shape (`documentOutlineHandle` prop shared between
+  `<Editor>` and a sibling component) is new API surface with no prior
+  precedent in this package — annotations use a ref instead — so it is the
+  first place a consumer has to learn this particular pattern.
+
+**Neutral:**
+
+- Extending `EditorHostServices` for scroll-container/element-rect data was
+  considered and explicitly deferred, not rejected outright — see Zusammen
+  #126. If and when that issue lands, `scrollContainer.ts`'s functions are
+  the natural seed for whatever host-seam capability it needs, rather than a
+  redesign from scratch.
+
+## References
+
+- Issue #69 (this decision)
+- `src/app/editor/AnchorScrollPlugin.tsx` / `src/app/editor/scrollContainer.ts` — the extracted, shared container-discovery logic
+- `src/app/editor/documentOutlineHandle.ts` — the `DocumentOutlineHandle` external-store shape
+- `src/app/editor/OutlinePlugin.tsx` — the internal plugin that feeds the handle
+- `src/app/editor/DocumentOutline.tsx` — the exported, freely-placed component that reads it
+- `docs/decisions/adr-075.md` — the persistence-boundary seam and "safe default for every host-service member" rule this decision stays consistent with by adding no new member
+- Zusammen issue #126 — the not-yet-planned margin-comment-positioning capability that would want the same scroll-container/element-rect primitive, named as the deferred beneficiary above

package/docs/decisions/adr-089.md

@@ -0,0 +1,121 @@
+# ADR-089: Existing-Mark Geometry (`getMarkRects`) Lives on `AnnotationEditorHandle`, Is Viewport-Relative, and Is Pull-Only
+
+**Date:** 2026-08-19
+**Status:** Accepted
+**Supersedes:** none
+**Amends:** none
+**Issue:** #73 (verveguy/liminis-editor)
+
+## Context
+
+ADR-088 (issue #69, the Document Outline widget) considered and declined to
+add a new `EditorHostServices` member for scroll-container/element-rect data,
+naming Zusammen [#126](https://github.com/verveguy/zusammen/issues/126) —
+"margin comments aligned to text" — as the not-yet-planned consumer that
+would want the same positional primitive, and deliberately deferred the
+question until #126 "does start." That is now: #126 needs a host to look up
+where an *existing* annotation's mark currently renders, so it can position a
+margin note against the annotated text. Today `AnnotationEditorHandle`
+exposes `removeMarksForAnnotation` and `collectLiveAnchorSnapshots`
+(document-offset ranges, not screen geometry) for live marks, and
+`AnnotationCreateEvent.rect` delivers a one-shot `DOMRect` only at the moment
+an annotation is created — nothing lets a host ask "where is annotation X
+*right now*."
+
+Three questions were explicitly left open by the issue's spec for this
+decision:
+
+1. **Surface placement** — extend `AnnotationEditorHandle` (mechanics-side,
+   matching its two existing members) or add a new `EditorHostServices`
+   member (host-seam-side, the option ADR-088 deferred)?
+2. **Coordinate space** — raw viewport-relative `getBoundingClientRect()`, or
+   rects adjusted relative to the editor's scroll container?
+3. **Staleness model** — a pull-based snapshot the host re-requests, or a
+   subscription/observer the package pushes updates through?
+
+## Decision
+
+**`getMarkRects(annotationIds?)` is added to `AnnotationEditorHandle`, not to
+`EditorHostServices`.** It keeps every live-mark operation — remove, snapshot,
+and now geometry — on the one seam a host already holds a reference to for
+annotations, rather than splitting positional queries onto a second surface
+for no functional reason. This does not reopen ADR-088: that decision was
+about the *outline widget's* scroll-container discovery (`AnchorScrollPlugin`
+/ `scrollContainer.ts`), which stays exactly as it is. `getMarkRects` needs
+none of that machinery — it resolves annotation ids to `MarkNode` elements
+(already solved, and already tested, by `markElementsByAnnotationId`) and
+reads each element's own `getBoundingClientRect()`.
+
+**Rects are raw, viewport-relative `getBoundingClientRect()` output — no
+scroll-container adjustment.** This matches the only existing precedent for
+rect delivery in this package, `AnnotationCreateEvent.rect`
+(`AnnotationPlugin.tsx`), which is also unadjusted. A host that wants
+scroll-container-relative coordinates can subtract that container's own
+`getBoundingClientRect()` origin itself — exactly what
+`AnchorScrollPlugin.tsx` already does internally for its own purposes — so
+nothing is lost by not building that adjustment into the package.
+
+**`getMarkRects` is pull-only: a fresh snapshot computed at call time, with no
+subscription or observer.** `getBoundingClientRect()` is inherently a live
+query, so a pull-based method trivially satisfies "no caching, no staleness"
+with zero extra machinery. ADR-088 declined to add a host-seam member for
+positional data at all and deferred to "when #126 starts" — it did not
+direct that the eventual mechanism be a subscription, only that the simpler
+pull-based need (this issue's actual scope) be resolved once a real consumer
+existed. Building a push/subscribe model now, before any consumer has asked
+for continuous updates rather than an on-demand read, would be the same kind
+of speculative, untested surface ADR-088 itself avoided.
+
+Built directly on `markElementsByAnnotationId(editor, ids)`: for a multi-block
+annotation (several sibling `MarkNode`s sharing one id), the result is one
+`DOMRect` per constituent element, in document order — the host, not the
+package, decides how to combine them. An id with no currently live mark is
+simply absent from the result map, never a thrown error. Two ids can report
+an identical rect when their marks share one `MarkNode` (overlapping
+annotations) — expected, and documented on the method itself so a host does
+not mistake it for a bug.
+
+## Consequences
+
+**Good:**
+
+- Zero new architectural surface: `AnnotationEditorHandle` gains a third
+  closure over an already-existing, already-tested helper
+  (`markElementsByAnnotationId`), the same pattern its two existing members
+  already follow.
+- A host that wants scroll-container-relative geometry can derive it trivially
+  from the container's own rect; the package is not left guessing which of a
+  host's several possible scroll containers is the relevant one.
+- Resolves ADR-088's explicit deferral: #126 now has a concrete, shipped
+  primitive rather than a "wait until it's needed" placeholder.
+- No subscription lifecycle (registration, teardown, re-render scheduling) to
+  design, test, or maintain until a consumer actually needs push updates.
+
+**Bad / accepted:**
+
+- A host that wants to keep UI glued to a mark across every scroll/resize/edit
+  must poll `getMarkRects` itself (e.g. on a `ResizeObserver`/scroll listener
+  it owns) — the package does no observing on the host's behalf. Accepted as
+  the deliberately smaller, already-demonstrated scope; a push model can be
+  layered on later without displacing this pull-based method.
+- Viewport-relative coordinates mean a host embedding the editor inside a
+  transformed or nested scroll container must do its own translation to a
+  meaningful local space — no worse than the precedent
+  (`AnnotationCreateEvent.rect`) already accepts.
+
+**Neutral:**
+
+- If a genuinely continuous-update consumer emerges later, it can be added as
+  a second, additive API (e.g. a subscribe variant) without touching
+  `getMarkRects`'s existing shape or forcing every caller to opt into observer
+  bookkeeping they don't need.
+
+## References
+
+- Issue #73 (this decision)
+- `src/app/editor/annotation-marks.ts` — `getMarkRects`, built on `markElementsByAnnotationId`
+- `src/annotations/types.ts` — `AnnotationEditorHandle`, where `getMarkRects` joins `removeMarksForAnnotation` and `collectLiveAnchorSnapshots`
+- `src/app/editor/AnnotationSurface.tsx` — `AnnotationEditorHandlePlugin`, where the closure is wired
+- `src/app/editor/AnnotationPlugin.tsx` — the existing one-shot `AnnotationCreateEvent.rect`, the precedent for raw viewport-relative rects
+- `docs/decisions/adr-088.md` — the deferred host-seam-vs-package-local question this decision resolves for positional annotation data specifically (ADR-088's own scroll-container-discovery decision is untouched)
+- Zusammen issue [#126](https://github.com/verveguy/zusammen/issues/126) — the consumer this capability unblocks

package/docs/editor-api.md

@@ -56,9 +56,61 @@ All optional; supplying `annotationKinds` is what turns the mechanism on. See
 | `scrollToAnnotation` | `{ id: string; nonce: number } \| null` | Host-driven scroll signal. Bump `nonce` to re-scroll to the same id. |
 | `onCreateAnnotation` | `(event: AnnotationCreateEvent) => void` | Fires when a user creates one via a kind's create affordance. |
 | `onActivateAnnotation` | `(id: string) => void` | Fires when a marker is activated. Your app opens its own panel. |
-| `annotationEditorHandleRef` | `MutableRefObject<AnnotationEditorHandle \| null>` | Imperative handle for the mounted editor's live marks. |
+| `annotationEditorHandleRef` | `MutableRefObject<AnnotationEditorHandle \| null>` | Imperative handle for the mounted editor's live marks: `removeMarksForAnnotation`, `collectLiveAnchorSnapshots`, and `getMarkRects(annotationIds?)` — current on-screen `DOMRect[]` per annotation id (one rect per constituent mark, omitted ids means "every live annotation"), for a host positioning UI against annotated text. |
 | `annotationLogger` | `{ warn(message, ...args): void }` | Injected, so the package never imports a host logger. |
 
+## Document outline
+
+A live, navigable "on this page" heading list (issue #69) — `<Editor>` owns
+the Lexical document and its heading DOM, so the package derives entries and
+implements scroll-to-heading; you decide whether, where, and how the outline
+is shown.
+
+```tsx
+import { useState } from 'react'
+import { Editor, DocumentOutline, createDocumentOutlineHandle } from '@liminis/editor'
+
+function MyEditorWithOutline() {
+  // Create once per editor instance — the same object connects the two
+  // components. A second editor on the same page needs its own handle.
+  const [outlineHandle] = useState(() => createDocumentOutlineHandle())
+
+  return (
+    <div style={{ display: 'flex' }}>
+      <Editor
+        initialContent={markdown}
+        onChange={setMarkdown}
+        documentOutlineHandle={outlineHandle}
+      />
+      <aside>
+        <DocumentOutline handle={outlineHandle} />
+      </aside>
+    </div>
+  )
+}
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `<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. |
+
+`createDocumentOutlineHandle()` returns the shared controller: a React
+external store (`subscribe`/`getSnapshot`, so `<DocumentOutline>` re-renders
+live as the reader scrolls and the document changes) plus an imperative
+`scrollToHeading(index)`. You never call its methods directly — `<Editor>`
+feeds it, `<DocumentOutline>` reads it.
+
+- Entries are H1–H5 headings in document order, indented by level, with
+  inline formatting (including inline code) reduced to plain text. Identity
+  is by position, not text, so duplicate headings are handled correctly.
+- The active entry — the heading at the top of the viewport — is tracked as
+  the reader scrolls and kept visible within the outline itself.
+- `<DocumentOutline>` renders nothing when the document has no headings.
+- Visibility, placement, width-gating, and any collapse/persistence are
+  entirely up to you — `<DocumentOutline>` imposes no layout policy.
+
 ## 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.1.0",
+  "version": "0.2.0",
   "//publishing": "Publishing is deliberate, never incidental. `private: true` was this package's guard until verveguy/liminis-editor#39 took the publish decision; it is gone because that decision was taken, not because it was tidied away. The guard is now `prepublishOnly` -> scripts/guard-publish.mjs, which refuses unless LIMINIS_ALLOW_PUBLISH=1 is set explicitly. That variable is set at step scope in .github/workflows/publish.yml and nowhere else, so a release is the only path that publishes. Note that `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), which is why the guard is a script rather than a flag.",
   "license": "MIT",
   "description": "Lexical-based markdown WYSIWYG editor with mdast round-trip and a host-injection seam",
@@ -18,67 +18,43 @@
   ],
   "//packageManager": "Not cosmetic. This field used to live in the monorepo root manifest and did not travel with the package, so `pnpm/action-setup` had no version to read and CI failed before installing anything. It is also what pins the pnpm that resolves the lockfile.",
   "packageManager": "pnpm@10.33.0",
+  "//engines": "A support statement, not a technical floor. Nothing in the dependency graph needs it — the highest `engines.node` among runtime dependencies is `>= 14.6` (yaml), and 18 of 21 declare none at all. It says which runtimes this package is maintained against: Node 20 reached end of life on 24 March 2026, and 22 and 24 are Active LTS. CI and the release both run 24, so 22 is supported by intent rather than by test — see the note in .github/workflows/ci.yml. Consumers get a warning rather than a hard failure unless they set engine-strict.",
+  "engines": {
+    "node": ">=22"
+  },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "//entrypoints": "These point at dist/ here, in the checked-in manifest, and must stay that way. They lived under `publishConfig` until 0.1.1 so that in-workspace consumers could resolve raw TypeScript, and that silently shipped a broken 0.1.0: `publishConfig` manifest-field overrides (main/types/exports) are a pnpm and yarn feature, and npm honours `publishConfig` only for config values like access, registry and tag. `npm publish` therefore published src/ paths while `files` shipped only dist/, so every entry point resolved to a file that was not in the tarball. What is published is now exactly what is written here, and scripts/verify-package.mjs packs with the same client that publishes so the two cannot diverge again. See docs/decisions/adr-078.md.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./markdown": {
-      "types": "./src/markdown.ts",
-      "default": "./src/markdown.ts"
+      "types": "./dist/markdown.d.ts",
+      "default": "./dist/markdown.js"
     },
     "./annotations": {
-      "types": "./src/annotations.ts",
-      "default": "./src/annotations.ts"
+      "types": "./dist/annotations.d.ts",
+      "default": "./dist/annotations.js"
     },
     "./headless": {
-      "types": "./src/headless.ts",
-      "default": "./src/headless.ts"
+      "types": "./dist/headless.d.ts",
+      "default": "./dist/headless.js"
     },
     "./contract": {
-      "types": "./src/contract.ts",
-      "default": "./src/contract.ts"
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
     },
     "./nodes": {
-      "types": "./src/nodes.ts",
-      "default": "./src/nodes.ts"
+      "types": "./dist/nodes.d.ts",
+      "default": "./dist/nodes.js"
     },
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./dist/styles.css"
   },
   "publishConfig": {
-    "access": "public",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "./markdown": {
-        "types": "./dist/markdown.d.ts",
-        "default": "./dist/markdown.js"
-      },
-      "./annotations": {
-        "types": "./dist/annotations.d.ts",
-        "default": "./dist/annotations.js"
-      },
-      "./headless": {
-        "types": "./dist/headless.d.ts",
-        "default": "./dist/headless.js"
-      },
-      "./contract": {
-        "types": "./dist/contract.d.ts",
-        "default": "./dist/contract.js"
-      },
-      "./nodes": {
-        "types": "./dist/nodes.d.ts",
-        "default": "./dist/nodes.js"
-      },
-      "./styles.css": "./dist/styles.css"
-    }
+    "access": "public"
   },
   "files": [
     "dist",
@@ -98,6 +74,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "verify:package": "node scripts/verify-package.mjs",
+    "docs:theming": "node scripts/generate-theming-docs.mjs",
     "demo": "node scripts/run-demo.mjs",
     "build:examples": "node scripts/build-examples.mjs",
     "build:site": "node scripts/build-site.mjs"