@liminis/editor 0.1.1 → 0.2.0

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.1",
+  "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,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"