@liminis/editor 0.1.1 → 0.2.1

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/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

@@ -56,9 +56,88 @@ 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.
+
+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.1.1",
+  "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",
@@ -18,6 +18,10 @@
   ],
   "//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",
   "//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",
@@ -70,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"