@liminis/editor 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 Brett Adam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package vendors a modified copy of `mdast-util-wiki-link` (MIT,
+Copyright (c) 2020 Mark Hudnall). Its license and a description of the
+modifications ship alongside it, at
+`dist/markdown/vendor/mdast-util-wiki-link/`.
+
+This package derives from the `webview-ui` package of SlashMD
+(https://github.com/wolfdavo/SlashMD) by David Wolfenden, which that project's
+README declares to be MIT-licensed. SlashMD carries no LICENSE file and no
+copyright notice, so none is reproduced here; this notice records the
+derivation and the stated license in their absence.

package/README.md

@@ -0,0 +1,376 @@
+# `@liminis/editor`
+
+A Lexical-based markdown WYSIWYG editor that round-trips through mdast, with a
+host-injection seam so it can be embedded in an Electron app, a browser app, or
+anything else that can supply a message channel.
+
+It is the editor from [Liminis](https://github.com/verveguy/liminis), extracted
+into this repository so it can stand on its own. MIT-licensed.
+
+Its history, and how to read the `ADR-0NNN`, `FR-NNN` and `#NNN` references that
+travelled with the code, are recorded in [`docs/provenance.md`](./docs/provenance.md).
+
+## What you get
+
+- **`<Editor>`** — a WYSIWYG markdown editor. Tables, task lists (including in
+  ordered lists), footnotes, definition lists, callouts, toggles, code blocks
+  with Prism highlighting, images, LaTeX equations, Mermaid diagrams, C4
+  diagrams, YAML frontmatter, and wiki-links.
+- **A markdown pipeline** — `parseMarkdown` / `stringifyMarkdown` and the mdast
+  ↔ Lexical mappers, usable with no editor mounted.
+- **An annotation mechanism** — range-anchored markers over document text that
+  survive edits, with per-*kind* configuration. Comments and corrections are not
+  separate features; they are two configurations of one mechanism. Entirely
+  opt-in: configure no kinds and none of it loads.
+- **A host seam** — every service the editor needs from its environment is an
+  optional injected function with a safe default, so `<Editor>` renders in a
+  host that supplies nothing at all.
+
+## Install
+
+> **This package is not published.** It is `private: true` and `@liminis/editor`
+> does not exist on the npm registry, so `pnpm add @liminis/editor` will fail.
+> That is deliberate — see [Consuming it](#consuming-it) below for the mechanism
+> that actually works, and `docs/decisions/adr-078.md` for why.
+
+React and Lexical are **peer dependencies**, so your app resolves exactly one
+copy of each. Two React copies produce `Invalid hook call`; two Lexical copies
+produce a broken editor context — peering is what prevents both.
+
+```bash
+pnpm add react@^19 react-dom@^19 \
+  lexical@^0.44 @lexical/react@^0.44 @lexical/code@^0.44 \
+  @lexical/code-prism@^0.44 @lexical/link@^0.44 @lexical/list@^0.44 \
+  @lexical/mark@^0.44 @lexical/markdown@^0.44 @lexical/rich-text@^0.44 \
+  @lexical/selection@^0.44 @lexical/table@^0.44 @lexical/utils@^0.44
+```
+
+pnpm v8+ and npm v7+ install peers automatically, so in practice the first
+command is usually enough.
+
+The package ships ESM plus `.d.ts` declarations. It has no CommonJS build.
+
+## Quickstart
+
+```tsx
+import { useState } from 'react'
+import { Editor } from '@liminis/editor'
+import '@liminis/editor/styles.css'   // required — see "Styling" below
+
+export function MyEditor() {
+  const [markdown, setMarkdown] = useState('# Hello\n\nStart typing.')
+
+  return (
+    <Editor
+      initialContent={markdown}
+      onChange={setMarkdown}
+    />
+  )
+}
+```
+
+`initialContent` is markdown text; `onChange` receives markdown text back.
+The editor owns the Lexical state in between — you never see it unless you want
+to.
+
+## Entry points
+
+Seven, and they are not stylistic. Each keeps a specific dependency graph out of
+a specific consumer, and importing the wrong one is measured in megabytes.
+
+| Entry | Contains | Import it when | Lexical-free |
+|---|---|---|---|
+| `@liminis/editor` | Everything: `<Editor>`, `<App>`, the host seam, the markdown pipeline, the mappers | You are rendering an editor | No |
+| `@liminis/editor/markdown` | `parseMarkdown`, mdast type guards, `getFileType`, the wiki-link mdast extension. Pure mdast/micromark | You only need to *read* markdown — a search snippet, a table of contents, a chunker | Yes |
+| `@liminis/editor/annotations` | The anchor model, resolver, block structure, and annotation types. DOM-, React- and Lexical-free | You are resolving or storing annotations outside a rendered editor | Yes |
+| `@liminis/editor/headless` | The C4 subsystem, server-side SVG rendering, MathJax lite adaptor | You are rendering diagrams or equations with no DOM (a server, a worker, an Electron main process) | Yes |
+| `@liminis/editor/contract` | The host-message shapes, as types | You are writing a boundary that must not pull renderer code in — an Electron preload script. Use `import type` | Yes (type-only) |
+| `@liminis/editor/nodes` | `editorNodes` (the exact Lexical node array `<Editor>` configures itself with), plus `importMarkdownToLexical` / `exportLexicalToMdast` | You are building your own headless Lexical `createEditor` — for example, to test the markdown↔Lexical mapper without mounting `<Editor>` | No |
+| `@liminis/editor/styles.css` | The stylesheet | Always, once, in your app | N/A (not JS) |
+
+Three of these are load-bearing in ways that are easy to undo by accident:
+
+- **`./markdown` is deliberately *not* `./headless`.** `./headless` re-exports
+  the MathJax configuration, whose ~90 bare
+  `import '@mathjax/src/js/input/tex/…Configuration.js'` lines are genuinely
+  side-effectful and cannot be tree-shaken by anyone — roughly 1.9 MB. If all
+  you do is parse markdown, import `./markdown` and you never pay it.
+- **`./contract` is only type-free of `zod` if you `import type`.** A value
+  import pulls the schemas in.
+- **`./nodes` is the one entry that legitimately requires Lexical and React** —
+  its whole purpose is exporting the node classes the mapper instantiates. It
+  inherits `./headless`'s MathJax-lite exception (loading it evaluates the same
+  ~90 side-effectful TeX-configuration imports, via `EquationNode`), but it
+  pulls in none of Mermaid's, C4's, or Prism's rendering weight — those
+  decorator components are lazy-loaded and never evaluate in a headless editor.
+
+Do not deep-import into `dist/`. Everything intended for consumers is on one of
+the seven entries above; anything else is internal and will move.
+
+### Why there's no `sideEffects` field
+
+`package.json` deliberately does not declare `sideEffects`. If your bundler's
+tree-shaking pass ever runs against this package's own graph and you're
+tempted to add one to prune it further, don't — the field is permanently
+prohibited (ADR-075 §4), not merely undeclared for now.
+
+The failure it would cause is a transitive one: marking this package's modules
+side-effect-free changes how a whole-graph bundler like rolldown chunks
+everything reachable from it, including third-party code the package merely
+imports. `prismjs`, pulled in via `@lexical/code-prism`, has its core chunk
+separated from `prism-clike.js`, a companion module that mutates a bare
+`Prism` global at import time. Once the two are split into different chunks,
+`prism-clike.js` runs before `Prism` exists:
+
+```
+ReferenceError: Prism is not defined
+```
+
+The app that hits this doesn't fail to build — it fails to *render*, since the
+error is thrown by code Prism's own language-grammar files depend on running
+first. This can't be fixed from inside this package: the hazard lives in
+`prismjs`'s own module structure, three levels removed, so no `sideEffects`
+value this package could declare about *its own* files changes how the bundler
+chunks `prismjs`.
+
+## Versioning policy
+
+This package is `0.x`. While it stays there:
+
+- **Minor versions may break.** `0.1.0` → `0.2.0` is not guaranteed compatible.
+- **Patch versions may not.** `0.1.0` → `0.1.1` is a bug fix only.
+- **The seven subpaths above are the supported API.** Anything reachable only
+  by a deeper import path — `@liminis/editor/dist/...` or a relative path into
+  `src/` — is private. It can move or disappear in a patch release.
+
+## Styling
+
+The editor's markup carries semantic class names (`editor-paragraph`,
+`editor-heading-h1`, `annotation-mark-*`, …). **`@liminis/editor/styles.css`
+defines them.** Importing it is not optional — without it the editor renders as
+unstyled text, and annotation markers are invisible. This failure is silent:
+nothing errors, it just looks wrong.
+
+```ts
+import '@liminis/editor/styles.css'
+```
+
+The sheet is plain CSS — OKLCH design tokens plus the editor's own rules. It has
+no build-step requirement and works with any bundler.
+
+### TypeScript needs to be told CSS imports exist
+
+If you type-check your app, that import is an error out of the box:
+
+```text
+error TS2882: Cannot find module or type declarations for side-effect import
+  of '@liminis/editor/styles.css'.
+```
+
+This is a TypeScript language limitation, not something the package can fix from
+its side: TypeScript has no built-in meaning for a `.css` module, so *any*
+stylesheet import from *any* package needs an ambient declaration. Most React
+starters already provide one and you will never see this. If yours does not, one
+line anywhere in your project's `include` fixes it:
+
+```ts
+// css.d.ts
+declare module '*.css'
+```
+
+If you are on Vite, adding its client types does the same job and covers assets
+too:
+
+```jsonc
+// tsconfig.json
+{ "compilerOptions": { "types": ["vite/client"] } }
+```
+
+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
+
+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.
+
+Add an explicit `@source` for the package's built output in the CSS file where
+you import Tailwind:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@liminis/editor/dist";
+```
+
+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.
+
+## Annotations
+
+An annotation is a range-anchored marker over document text whose anchor
+survives edits to the surrounding document. The mechanism is entirely opt-in:
+supplying an `annotationKinds` prop is what turns it on. With no kinds
+configured, the annotation UI is never loaded — it sits behind a `React.lazy()`
+boundary, so it is not even in the chunk your app downloads.
+
+```tsx
+<Editor
+  initialContent={markdown}
+  onChange={setMarkdown}
+  annotationKinds={{
+    comment: {
+      markerStyle: 'highlight',
+      createAffordance: { surface: 'toolbar', label: 'Comment' },
+    },
+  }}
+  annotations={annotations}
+  onCreateAnnotation={(event) => { /* mint an id, persist, add to `annotations` */ }}
+  onActivateAnnotation={(id) => { /* open your own thread panel */ }}
+/>
+```
+
+The package owns anchor mechanics and marker rendering. Identity, storage and
+lifecycle stay in your app — `id` is opaque to the package and `payload` is
+carried through untouched. See [`docs/annotations.md`](./docs/annotations.md).
+
+Configuring more than one kind on the same `createAffordance.surface` offers
+one toolbar button or context-menu entry per kind, in `annotationKinds`'
+declaration order.
+
+A `toolbar`-surfaced affordance works the same way whether `editable` is
+`true` or `false` — annotating is decoupled from editing, so a selection in a
+read-only editor still shows the floating toolbar with the configured
+affordance (formatting controls are omitted there, since they would be
+inert).
+
+## Documentation
+
+- [`docs/editor-api.md`](./docs/editor-api.md) — the `<Editor>` props and the
+  host-injection seam.
+- [`docs/markdown-pipeline.md`](./docs/markdown-pipeline.md) — `parseMarkdown`,
+  `stringifyMarkdown`, the mdast ↔ Lexical mappers, and wiki-links.
+- [`docs/annotations.md`](./docs/annotations.md) — kinds, anchors, resolution,
+  and marker styling.
+
+## Consuming it
+
+Because the package is unpublished, consumers install a **packed tarball** rather
+than a registry version:
+
+```bash
+# in this repository
+pnpm build && pnpm pack --pack-destination /tmp
+
+# in the consuming application
+pnpm add /tmp/liminis-editor-0.1.0.tgz
+```
+
+Applications that do this commit the tarball into their own tree (typically under
+`vendor/`) and pin it by filename, so the install is reproducible and needs no
+credentials for this private repository. `pnpm pack` works on a private package;
+only `npm publish` is blocked, which is exactly the guard intended.
+
+A git dependency on this repository does **not** work, and the reasons are
+measured rather than assumed: `files` excludes the directory `main` points at, so
+a git install lands only the manifest and docs; the build runs from `prepack`,
+which a git install never invokes; and pnpm does not apply `publishConfig` for git
+installs. Adding a `prepare` script to work around this would change what an
+eventual npm tarball ships, so it has been deliberately avoided.
+
+## Demo
+
+```bash
+pnpm demo
+```
+
+Builds the package, packs it, installs the tarball into `examples/demo/` outside
+any workspace, and starts the Vite dev server. The demo imports only the public
+entry points, so it breaks when an adopter would break. Its content is a picker
+over the same round-trip fixture corpus the package's own test suite uses, so
+every fixture-representable node class renders somewhere in it. See
+[`examples/demo/README.md`](./examples/demo/README.md).
+
+`examples/demo` is also the source of the public GitHub Pages site: a
+`release`-triggered (not merge-triggered) build of this same shell, showing a
+visible version badge for the published release it represents and a
+Documentation tab rendering this README. Between releases the deployed site
+stays on the last published version even as `main` keeps moving — that
+staleness is intentional, not a bug (see `docs/decisions/adr-082.md`).
+
+## Electron e2e shell
+
+`examples/electron/` is a minimal Electron host for the package — a window, the
+editor, and stubbed host services, no more — that a Playwright e2e suite drives
+over CDP against real Chromium/Electron rather than a jsdom-class test
+environment. It exists so package-level e2e can catch defects that only ever
+surface in a real browser without needing `liminis-app`, or any other downstream
+application, to exist. See
+[`examples/electron/README.md`](./examples/electron/README.md).
+
+```bash
+pnpm build:examples   # builds and packs the package once, then builds both
+                       # examples/demo and examples/electron against it
+pnpm build:site       # builds examples/demo only — what the release-triggered
+                       # Pages deploy runs (see the Demo section above)
+```
+
+## Development
+
+This repository stands alone. It has no `pnpm-workspace.yaml` and no dependency
+on any other checkout — the `examples/` directories are external consumers by
+construction, not workspace members.
+
+```bash
+pnpm install
+pnpm build          # tsc emit + tsc-alias + asset copy → dist/
+pnpm typecheck      # tsc --noEmit
+pnpm lint           # eslint src/ tests/
+pnpm test           # vitest run
+```
+
+That sequence is what CI runs, in that order. One further gate needs a real built
+artifact and so runs separately:
+
+```bash
+pnpm verify:package
+```
+
+This builds, packs, installs the tarball into `examples/external-consumer/` with
+`--ignore-workspace`, type-checks it under `bundler` and `nodenext` module
+resolution, builds three measurement arms, and asserts the entry-graph boundaries
+the seven export subpaths exist to keep — that `./markdown` pulls in no MathJax,
+no Lexical and no react-dom, and that annotations stay behind a lazy boundary.
+It is the check that proves the package is publishable without publishing it.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+This package vendors a modified copy of `mdast-util-wiki-link` (MIT, Mark
+Hudnall); its license and the modifications are documented at
+`dist/markdown/vendor/mdast-util-wiki-link/`.
+
+## Acknowledgements
+
+This editor began as the `webview-ui` package of
+[**SlashMD**](https://github.com/wolfdavo/SlashMD) by David Wolfenden (MIT, as
+declared in that project's README) — a VS Code extension that opens Markdown
+files in a block-based WYSIWYG editor while keeping the file itself plain
+Markdown.
+
+That is the origin of the substance of this package, not a passing influence:
+the Lexical node set (callouts, toggles, equations, Mermaid, frontmatter,
+images), the mdast ↔ Lexical mappers, the Markdown parsing and stringification
+layer, and the host-message contract all descend from it. The contract's shape
+still shows its beginnings — `REQUEST_INIT`, `REQUEST_SETTINGS`, `WRITE_ASSET`
+were a VS Code webview protocol before they were carried over an Electron IPC
+bridge — and identifiers such as `SlashMDSettings` keep the name outright.
+
+What has changed since is the seam rather than the ideas: a curated set of
+export subpaths, peer-dependency inversion, an annotation mechanism, and a
+round-trip corpus that holds the Markdown pipeline to a fixed point.

package/dist/annotations/anchor-align.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PROVENANCE — ported from Zusammen (`verveguy/zusammen`) for Liminis #939.
+ *
+ * The doc comments below are the original author's and are kept verbatim so
+ * this module stays diffable against its source. Their `FR-NNN`/`SC-NNN`
+ * identifiers, `#NN` issue references and `adrs/` paths therefore name
+ * **Zusammen's** spec, issues and ADRs — not this repository's, where the same
+ * identifiers mean something else entirely. For the Liminis-side design see
+ * `docs/decisions/adr-077.md` and
+ * `docs/zusammen-editor-capability-map.md`.
+ *
+ * "Comment"/"thread" in these comments should be read as "annotation": this
+ * module now serves both annotation kinds, not comments alone.
+ */
+/**
+ * Comment Anchor Alignment
+ *
+ * `locateInSpan`: the verbatim-substring, context/occurrence-disambiguated
+ * text search shared by both directions of the comment-anchor mapping
+ * (capture and marker placement) — reused unchanged by #43's live-mark
+ * mechanism (`editor/app/editor/comment-anchor-marks.ts`) for the same
+ * lookup it always did: `targetText` -> location within the current raw
+ * markdown. Pure, git-free — no fs, no git, no DOM — safe to unit test with
+ * plain data.
+ */
+export interface SpanRange {
+    start: number;
+    end: number;
+}
+export interface LocateInSpanOptions {
+    /** 0-based index of which occurrence of `target` to prefer, when known. */
+    occurrenceIndex?: number;
+    /** Text immediately before the target, for disambiguating duplicate occurrences. */
+    prefixContext?: string;
+    /** Text immediately after the target, for disambiguating duplicate occurrences. */
+    suffixContext?: string;
+}
+/**
+ * Locate `target` verbatim within `spanText`. Returns null if `target` does
+ * not appear at all — the caller falls back to anchoring the whole enclosing
+ * block (the Plan's bounded v1 scope for selections that straddle inline
+ * markdown syntax, e.g. a selection starting mid-`**bold**`).
+ *
+ * When `target` appears more than once, candidates are ranked by how well
+ * their surrounding context matches `prefixContext`/`suffixContext` plus
+ * proximity to `occurrenceIndex` — the same disambiguation signal
+ * `anchor-resolver.ts` uses for duplicate exact matches, reused here (via the
+ * shared `similarity` export) rather than reinvented.
+ */
+export declare function locateInSpan(spanText: string, target: string, options?: LocateInSpanOptions): SpanRange | null;

package/dist/annotations/anchor-align.js

@@ -0,0 +1,74 @@
+/**
+ * PROVENANCE — ported from Zusammen (`verveguy/zusammen`) for Liminis #939.
+ *
+ * The doc comments below are the original author's and are kept verbatim so
+ * this module stays diffable against its source. Their `FR-NNN`/`SC-NNN`
+ * identifiers, `#NN` issue references and `adrs/` paths therefore name
+ * **Zusammen's** spec, issues and ADRs — not this repository's, where the same
+ * identifiers mean something else entirely. For the Liminis-side design see
+ * `docs/decisions/adr-077.md` and
+ * `docs/zusammen-editor-capability-map.md`.
+ *
+ * "Comment"/"thread" in these comments should be read as "annotation": this
+ * module now serves both annotation kinds, not comments alone.
+ */
+/**
+ * Comment Anchor Alignment
+ *
+ * `locateInSpan`: the verbatim-substring, context/occurrence-disambiguated
+ * text search shared by both directions of the comment-anchor mapping
+ * (capture and marker placement) — reused unchanged by #43's live-mark
+ * mechanism (`editor/app/editor/comment-anchor-marks.ts`) for the same
+ * lookup it always did: `targetText` -> location within the current raw
+ * markdown. Pure, git-free — no fs, no git, no DOM — safe to unit test with
+ * plain data.
+ */
+import { similarity } from './anchor-resolver.js';
+/** How many characters of context around a candidate occurrence to compare against `prefixContext`/`suffixContext`. */
+const CONTEXT_COMPARISON_CHARS = 40;
+function findOccurrences(spanText, target) {
+    if (!target)
+        return [];
+    const matches = [];
+    let idx = spanText.indexOf(target);
+    while (idx !== -1) {
+        matches.push({ start: idx, end: idx + target.length });
+        idx = spanText.indexOf(target, idx + 1);
+    }
+    return matches;
+}
+/**
+ * Locate `target` verbatim within `spanText`. Returns null if `target` does
+ * not appear at all — the caller falls back to anchoring the whole enclosing
+ * block (the Plan's bounded v1 scope for selections that straddle inline
+ * markdown syntax, e.g. a selection starting mid-`**bold**`).
+ *
+ * When `target` appears more than once, candidates are ranked by how well
+ * their surrounding context matches `prefixContext`/`suffixContext` plus
+ * proximity to `occurrenceIndex` — the same disambiguation signal
+ * `anchor-resolver.ts` uses for duplicate exact matches, reused here (via the
+ * shared `similarity` export) rather than reinvented.
+ */
+export function locateInSpan(spanText, target, options = {}) {
+    const matches = findOccurrences(spanText, target);
+    if (matches.length === 0)
+        return null;
+    if (matches.length === 1)
+        return matches[0];
+    const { occurrenceIndex, prefixContext = '', suffixContext = '' } = options;
+    // Only weigh in context when the caller actually supplied any — comparing
+    // against an empty context would otherwise favor whichever occurrence
+    // happens to have the shortest surrounding text, not the intended one.
+    const hasContext = prefixContext.length > 0 || suffixContext.length > 0;
+    const contextWeight = hasContext ? 0.8 : 0;
+    const proximityWeight = 1 - contextWeight;
+    const scored = matches.map((match, index) => {
+        const prefix = spanText.slice(Math.max(0, match.start - CONTEXT_COMPARISON_CHARS), match.start);
+        const suffix = spanText.slice(match.end, Math.min(spanText.length, match.end + CONTEXT_COMPARISON_CHARS));
+        const contextScore = (similarity(prefix, prefixContext) + similarity(suffix, suffixContext)) / 2;
+        const proximityScore = occurrenceIndex == null ? 0 : 1 - Math.abs(index - occurrenceIndex) / matches.length;
+        return { match, score: contextScore * contextWeight + proximityScore * proximityWeight };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored[0].match;
+}

package/dist/annotations/anchor-model.d.ts

@@ -0,0 +1,81 @@
+/**
+ * PROVENANCE — ported from Zusammen (`verveguy/zusammen`) for Liminis #939.
+ *
+ * The doc comments below are the original author's and are kept verbatim so
+ * this module stays diffable against its source. Their `FR-NNN`/`SC-NNN`
+ * identifiers, `#NN` issue references and `adrs/` paths therefore name
+ * **Zusammen's** spec, issues and ADRs — not this repository's, where the same
+ * identifiers mean something else entirely. For the Liminis-side design see
+ * `docs/decisions/adr-077.md` and
+ * `docs/zusammen-editor-capability-map.md`.
+ *
+ * "Comment"/"thread" in these comments should be read as "annotation": this
+ * module now serves both annotation kinds, not comments alone.
+ */
+/**
+ * Comment Anchor Model
+ *
+ * Defines the content-relative anchor payload persisted through the
+ * comment-event-store's (issue #13) `re-anchor`/`anchor-recorded` events, and
+ * the resolution-outcome payload persisted through `anchor-resolved` events.
+ * Both were left opaque (`unknown`) by that store on purpose — this module is
+ * what gives them shape (FR-001, FR-002).
+ *
+ * Pure, git-free — no fs, no git, safe to unit test with plain strings.
+ */
+import { z } from 'zod';
+import { type BlockType } from './block-structure.js';
+/** How many characters of surrounding text are captured on each side of the target, for duplicate disambiguation (FR-006). */
+export declare const CONTEXT_WINDOW_CHARS = 40;
+/**
+ * The durable, content-relative description of a comment's target (FR-001).
+ * Re-locating a target needs only an anchor plus the new document text — never
+ * the old document text — which is what makes resolution provenance-agnostic
+ * (FR-010): a direct edit and a merge produce the same new text.
+ */
+export interface Anchor {
+    /** The exact substring the comment targets. */
+    targetText: string;
+    /** Up to CONTEXT_WINDOW_CHARS of text immediately before the target. */
+    prefixContext: string;
+    /** Up to CONTEXT_WINDOW_CHARS of text immediately after the target. */
+    suffixContext: string;
+    /** The type of the single leaf block enclosing the target at capture time, or null if the target itself spans more than one block. */
+    blockType: BlockType | null;
+    /** 0-based index of which occurrence of `targetText` in the document this anchor refers to — disambiguates duplicate text (FR-006). */
+    occurrenceIndex: number;
+    /** The content-repo HEAD SHA the anchor was captured against. */
+    docVersion: string;
+}
+/** An anchor as read from the live editor structure, before the store stamps `docVersion`. */
+export type AnchorFields = Omit<Anchor, 'docVersion'>;
+export declare const ANCHOR_SCHEMA: z.ZodType<Anchor>;
+export interface AnchorRange {
+    start: number;
+    end: number;
+}
+/**
+ * Capture a durable anchor for the text at `range` within `text`, as of
+ * `docVersion`. The target's enclosing block type is null when the range
+ * spans more than one leaf block (e.g. a comment deliberately covering two
+ * paragraphs) — the resolver treats that the same as any other
+ * structural-boundary case.
+ */
+export declare function captureAnchor(text: string, range: AnchorRange, docVersion: string): Anchor;
+export type AnchorOutcome = 'unchanged' | 're-attached' | 'flagged' | 'orphaned';
+/**
+ * The outcome of re-evaluating a comment's anchor against a new document
+ * version (FR-002). Persisted verbatim as the payload of an `anchor-resolved`
+ * event; `anchor` is additionally persisted as the payload of the
+ * `anchor-recorded` event that accompanies a `re-attached` outcome.
+ */
+export interface AnchorResolution {
+    outcome: AnchorOutcome;
+    /** The content-repo HEAD SHA this resolution was evaluated against. */
+    docVersion: string;
+    /** Short, human-readable explanation of why this outcome was reached. */
+    reason: string;
+    /** Present only when outcome === 're-attached' — the anchor recomputed at the new location. */
+    anchor?: Anchor;
+}
+export declare const ANCHOR_RESOLUTION_SCHEMA: z.ZodType<AnchorResolution>;