@liminis/editor 0.1.0-rc.1

package/docs/markdown-pipeline.md

@@ -0,0 +1,282 @@
+# The markdown pipeline
+
+Markdown ↔ mdast ↔ Lexical, usable with or without an editor mounted.
+
+```text
+markdown text  ──parseMarkdown──▶  mdast Root  ──importMarkdownToLexical──▶  Lexical
+markdown text  ◀─stringifyMarkdown──  mdast Root  ◀──exportLexicalToMdast──  Lexical
+```
+
+Everything on the mdast side is available from `@liminis/editor/markdown`,
+which has no React, no Lexical, no DOM and no MathJax in its graph. The
+Lexical mappers live on the root entry, because they need Lexical.
+
+## `parseMarkdown`
+
+```ts
+import { parseMarkdown } from '@liminis/editor/markdown'
+
+const { root } = parseMarkdown(text)
+```
+
+`root` is a standard mdast `Root`. Extensions enabled: GFM (tables, strikethrough,
+task lists, autolinks), footnotes, math, definition lists, YAML frontmatter, and
+wiki-links.
+
+Beyond the standard extensions, `parseMarkdown` runs several post-passes that
+exist to preserve information a plain mdast parse throws away:
+
+- **Task lists in ordered lists.** GFM only supports checkboxes in unordered
+  lists; Foam and Obsidian use them in ordered lists too, so they are added back.
+- **Emphasis marker annotation.** Whether the source wrote `*em*` or `_em_` is
+  recorded on the node, so a round trip does not silently rewrite one into the
+  other.
+- **Wiki-link pipe protection.** See below.
+- **Empty-alias marking.** `[[target|]]` is distinguishable from `[[target]]`.
+
+### Type guards
+
+The entry exports guards for the mdast node types you will actually branch on:
+`isParagraph`, `isHeading`, `isList`, `isListItem`, `isBlockquote`, `isCode`,
+`isThematicBreak`, `isTable`, `isImage`, `isLink`, `isHtml`, `isText`,
+`isStrong`, `isEmphasis`, `isInlineCode`, `isDelete`.
+
+```ts
+import { parseMarkdown, isHeading, isText } from '@liminis/editor/markdown'
+
+const { root } = parseMarkdown(text)
+const titles = root.children.filter(isHeading).map((h) => h.children.filter(isText).map(t => t.value).join(''))
+```
+
+`getFileType(path)` is also here — the editor's own file-type classifier.
+
+## `stringifyMarkdown`
+
+```ts
+import { stringifyMarkdown } from '@liminis/editor'
+
+const text = stringifyMarkdown(root, { bulletStyle: '-', fenceStyle: '`' })
+```
+
+| Option | Type | Default |
+|---|---|---|
+| `wrapWidth` | `number` | no wrapping |
+| `bulletStyle` | `'-' \| '*' \| '+'` | `'-'` |
+| `fenceStyle` | `` '`' \| '~' `` | `` '`' `` |
+
+Serialization is written to keep a document byte-stable across a round trip
+wherever markdown permits it. The most consequential piece is **list spread**:
+whether a list is "loose" (blank lines between items) is carried through the
+Lexical round trip and is only ever *upgraded* to loose, never downgraded — a
+downgrade silently collapses blank lines and, on re-parse, misreads item
+boundaries.
+
+## The Lexical mappers
+
+```ts
+import { importMarkdownToLexical, exportLexicalToMdast } from '@liminis/editor'
+```
+
+These are what `<Editor>` uses internally. Reach for them directly only if you
+are driving a Lexical editor yourself.
+
+### Building a headless editor
+
+The mapper functions instantiate Lexical node classes directly, so a
+`createEditor` you build yourself must be configured with the *exact* node set
+`<Editor>` uses — any node type Lexical encounters that isn't registered
+throws. `@liminis/editor/nodes` exports that array (`editorNodes`) alongside
+the two mapper functions, without pulling in `<Editor>`/`<App>`, Mermaid, or
+Prism. This is the entry point to use for a fast round-trip regression test
+that exercises the real mapper without mounting a React component:
+
+```ts
+import { createEditor } from 'lexical'
+import { editorNodes, importMarkdownToLexical, exportLexicalToMdast } from '@liminis/editor/nodes'
+import { parseMarkdown } from '@liminis/editor/markdown'
+
+const editor = createEditor({
+  namespace: 'headless',
+  nodes: editorNodes,
+  onError: (error) => { throw error },
+})
+
+const parsed = parseMarkdown(markdownSource)
+
+// `importMarkdownToLexical` schedules its own `editor.update()`, which by
+// default reconciles on a microtask. Wrap it in a `discrete: true` update so
+// the mutation is committed before `exportLexicalToMdast` reads it back.
+editor.update(() => {
+  importMarkdownToLexical(editor, parsed.root)
+}, { discrete: true })
+
+const mdast = exportLexicalToMdast(editor)
+```
+
+`editorNodes` is the same array `<Editor>` configures its own `LexicalComposer`
+with — not a separately maintained copy — so a node type added to the
+production editor is reflected here automatically. `EquationNode` imports
+MathJax's lite adaptor at module scope, so loading `./nodes` carries the same
+documented MathJax-lite exception as `./headless`; it does not initialize
+Mermaid, C4's layout engine, or Prism, since those node classes lazy-load their
+render components.
+
+## Wiki-links
+
+Wiki-links are `[[target]]` or `[[target|alias]]` (Obsidian/Foam style — the
+alias divider is `|`, not the upstream default `:`). They parse to a `wikiLink`
+mdast node:
+
+```ts
+{ type: 'wikiLink', value: 'target', data: { alias, permalink, exists, /* hast shim fields */ } }
+```
+
+`data.alias` is the display text — it falls back to the target when no explicit
+alias is given, which is upstream behaviour and occasionally surprising.
+
+### The pipe-in-tables problem (#347)
+
+A pipe inside a table cell terminates the cell. An aliased wiki-link in a table
+therefore has to escape its divider (`[[target\|alias]]`) or GFM parsing splits
+the link — and, worse, corrupts the shape of the whole table row.
+
+`parseMarkdown` escapes the divider before parsing and the wiki-link extension
+strips the resulting backslash off the target afterwards. The strip happens
+*before* the target is resolved, so `data.permalink` and `data.exists` are
+computed from the clean target.
+
+This behaviour originally came from a `pnpm patch` on the npm package. That
+patch could not travel outside the Liminis monorepo, so the extension is now
+**vendored** into this package (MIT, from
+[`landakram/mdast-util-wiki-link`](https://github.com/landakram/mdast-util-wiki-link);
+license and modifications ship at `dist/markdown/vendor/mdast-util-wiki-link/`).
+
+**If you are maintaining this package: do not remove the trailing-backslash
+strip.** It looks like a stray special case. It is the fix for
+[#347](https://github.com/verveguy/liminis/issues/347), and removing it breaks
+entire markdown tables that happen to contain an aliased wiki-link, not just the
+link.
+
+### Building your own pipeline
+
+If you need an mdast pipeline of your own that agrees with the editor's — a
+chunker, an indexer, an exporter — take the wiki-link extension from this
+package rather than from npm, or your parse will differ from the editor's:
+
+```ts
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { syntax as wikiLinkSyntax } from 'micromark-extension-wiki-link'
+import { wikiLinkFromMarkdown, wikiLinkToMarkdown } from '@liminis/editor/markdown'
+
+const OPTIONS = { aliasDivider: '|' }
+
+const tree = fromMarkdown(text, {
+  extensions: [wikiLinkSyntax(OPTIONS) /* , gfm(), … */],
+  mdastExtensions: [wikiLinkFromMarkdown(OPTIONS) /* , gfmFromMarkdown(), … */],
+})
+```
+
+`wikiLinkToMarkdown` is the matching serializer extension, built on
+`mdast-util-to-markdown` v2.
+
+> **The extensions alone are not equivalent to `parseMarkdown`.** If you enable
+> GFM tables alongside them, prefer `parseMarkdown` — see below.
+
+### What the extensions do *not* give you
+
+`parseMarkdown` is more than these two extensions, and the difference is not
+cosmetic. Two pre/post-passes live in `parseMarkdown` and have no equivalent
+inside the extension:
+
+- **Alias-pipe escaping (the #347 fix above).** The trailing-backslash strip in
+  `wikiLinkFromMarkdown` only helps once the divider is *already* escaped.
+  `parseMarkdown` does that escaping before parsing. Without it, GFM's table
+  parser reaches the `|` first. Measured on `| [[target\|alias]] | x |` in a
+  two-column table: the extensions alone yield **5 table cells and 0 wiki-link
+  nodes** — the row is corrupted and the link is gone — where `parseMarkdown`
+  yields 4 cells and 1 wiki-link.
+- **Empty-alias preservation.** `[[target|]]` is distinguishable from
+  `[[target]]` only because `parseMarkdown` substitutes a sentinel before parsing
+  and sets `data._emptyAlias` after. The extensions alone produce no wiki-link
+  node at all for that input.
+
+So: **if your pipeline enables GFM tables, or you care about `[[target|]]`, call
+`parseMarkdown` rather than assembling the extensions yourself.** Reach for the
+raw extensions only when you control the input and neither case applies.
+
+Note also that `<Editor>`'s own *serialization* does not go through
+`wikiLinkToMarkdown`: `stringifyMarkdown` carries a hand-rolled wiki-link handler
+that additionally understands `data._emptyAlias`. `wikiLinkToMarkdown` is the
+faithful vendored upstream serializer, not a byte-for-byte match for what the
+editor emits.
+
+## Wiki-link promotion on export
+
+Everything above is about *parsing* `[[target]]` syntax the author already wrote.
+Independently, `exportLexicalToMdast` (in `lexicalToMdast.ts`) also *produces*
+wiki-link syntax on export, for a link the author wrote as an ordinary standard
+markdown link: `convertLinkNode` promotes any **untitled** link whose URL looks
+like a relative note reference — a relative `.md` path (with or without a
+leading `./`/`../`), a `.md` path with an anchor, a bare `#anchor`, or a
+directory-style (trailing-slash) path (see `isWikiLinkUrl`) — into `[[target]]`
+/ `[[target|alias]]` on export. A **titled** link (`[text](url "title")`) is
+never promoted, regardless of URL shape — wiki-link syntax has no slot for a
+title, so promoting one would silently drop it
+([#919](https://github.com/verveguy/liminis/issues/919)).
+
+This is deliberate for `liminis-app`, whose documents are wiki-link-native: a
+relative link to another note *is* a wiki-link, and round-tripping it as one is
+correct. It is not correct for every consumer — a host whose documents are
+plain markdown rendered somewhere that doesn't understand `[[...]]` syntax
+(e.g. the GitHub web UI) would see every untitled relative link rewritten into
+non-rendering syntax on save, which is document corruption from that
+consumer's point of view, not a normalization
+([#951](https://github.com/verveguy/liminis/issues/951)).
+
+### The `wikiLinkPromotion` option
+
+`exportLexicalToMdast(editor, options)` accepts an optional `ExportOptions`
+object with a `wikiLinkPromotion?: 'promote' | 'off'` field, defaulting to
+`'promote'` — today's only behavior, unchanged for any caller that doesn't set
+it. `'off'` disables promotion of an *ordinary* standard-markdown link whose
+URL merely looks wiki-link-shaped: it is emitted as a standard markdown link
+instead of `[[target]]`. It does not affect a link that was genuine,
+author-written `[[target]]` / `[[target|alias]]` wiki-link syntax in the
+source — that always round-trips back out as a wiki-link, regardless of this
+setting, so an opted-out host still never corrupts a document's existing
+wiki-links, only stops creating new ones. (The two are distinguished by
+provenance, tracked on the parsed link node — not by re-inspecting the URL,
+which is identical either way.) This does not change which URLs
+`isWikiLinkUrl` classifies as wiki-link-like, and it has no effect on
+*parsing* — a genuine, author-written `[[target]]` in the source still parses
+to a link node on import regardless of this setting.
+
+Both types are exported from the root barrel (`@liminis/editor`), alongside
+`exportLexicalToMdast` itself:
+
+```ts
+import { exportLexicalToMdast, type ExportOptions, type WikiLinkPromotionMode } from '@liminis/editor'
+
+const mdast = exportLexicalToMdast(editor, { wikiLinkPromotion: 'off' })
+```
+
+The `<Editor>`/`<App>` component surface exposes the same setting as an
+optional `wikiLinkPromotion` prop, mirroring the existing `imagePathResolution`
+prop's shape (though sourced differently — see below):
+
+```tsx
+<App wikiLinkPromotion="off" ... />
+```
+
+Unlike `imagePathResolution` (which `<App>` derives from IPC-delivered
+`SlashMDSettings`), `wikiLinkPromotion` is a direct `AppProps` field, not
+settings-derived: `<App>` also supports a non-IPC "inline" mode (`content`/
+`onChange` props, bypassing the host-message channel entirely), where
+`settings` stays `null` forever — a settings-only path would be unreachable by
+a host running that way, which is exactly the shape the option was added for.
+
+The setting also reaches the annotation-anchor-capture export path
+(`annotation-marks.ts`), not just the disk-write path: both are expected to
+agree on whether a link's raw-markdown form is wiki-link or standard syntax, so
+an opted-out host's annotation anchors are captured against the same link
+syntax its saved document actually contains.

package/docs/provenance.md

@@ -0,0 +1,106 @@
+# Provenance
+
+Where this repository came from, and how to read the references in it.
+
+## The extraction
+
+`@liminis/editor` began as a directory inside the Liminis monorepo,
+`verveguy/liminis`. It was extracted into this repository by
+verveguy/liminis#995 on 2026-08-15.
+
+The extraction used `git filter-repo` against a throwaway clone of
+`verveguy/liminis` at commit `34f0d828`, scoped to the paths that made up the
+package and its examples:
+
+```
+packages/editor            → (repository root)
+examples/demo              → examples/demo
+examples/external-consumer → examples/external-consumer
+scripts/verify-package.mjs → scripts/verify-package.mjs
+scripts/run-demo.mjs       → scripts/run-demo.mjs
+```
+
+The result is **real history, not a squashed import**: the filtered import
+contributed 140 commits, including the sequence of adoption defects that a second
+consumer found in the package during August 2026 (verveguy/liminis#951 through
+#954, #961 and #965). `git log` on any file under `src/` shows the commit that
+introduced it.
+
+The source repository was not rewritten. The clone was thrown away.
+
+### One branch arrived after the cut
+
+verveguy/liminis#973 — a serializer defect that corrupted `**bold**` abutting an
+inline-code span on every save — was still open upstream when the filter ran, so
+its work sat on `preserved/liminis-issue-973-in-flight` rather than on `main`. It
+merged upstream shortly afterwards and was merged here too. The branch is kept as
+a record of the cut; it is an ancestor of `main` and nothing needs to be taken
+from it.
+
+### What did not come across
+
+- The package's CI jobs, which lived in the monorepo's `.github/workflows/test.yml`.
+  They are replaced by this repository's own `.github/workflows/ci.yml`.
+- The monorepo's `pnpm-workspace.yaml`. This repository has **no workspace file**,
+  which is what makes `examples/*` external consumers by construction rather than
+  by convention. See the note in `scripts/verify-package.mjs`.
+- History from before the package was a package. The editor previously lived at
+  `liminis-app/src/editor` and has roughly 287 commits of prior history there.
+  Those commits are interleaved with changes to an application this repository is
+  not about, so they were deliberately left behind. They remain in
+  `verveguy/liminis`.
+
+## Reading the references
+
+### `ADR-0NNN`
+
+Resolves to `docs/decisions/adr-0NNN.md`. See that directory's `README.md`,
+which also explains the handful of numbers cited *inside* those documents that
+belong to the host application rather than to this package.
+
+Where the package's own code cited an application decision — the Claude Agent SDK
+integration, MCP stdio concurrency, the knowledge corrections pipeline, the ban on
+native browser dialogs — the citation was removed at extraction and the reasoning
+written out at the call site instead, so it stands on its own.
+
+### `FR-NNN`, `SC-NNN`, `NFR-NNN`
+
+These are requirement and success-criterion identifiers from Spec Kit
+specifications, and they are **scoped to the issue whose work introduced them**.
+An `FR-004` in one comment and an `FR-004` in another are unrelated unless the
+comments are about the same issue.
+
+They resolve under `specs/` in `verveguy/liminis`, in the directory named for the
+issue number, e.g. `specs/995-extract-liminis-editor-into/spec.md`.
+
+They were left as-is rather than rewritten. There are several hundred across the
+package's source, concentrated in its most heavily commented code, and rewriting
+them all would have made `git log -p` unreadable for exactly the history this
+extraction went to some trouble to preserve. Where a comment was edited for other
+reasons during the extraction, its identifiers were made self-describing.
+
+### `#NNN`
+
+A bare `#NNN` in a source comment refers to an issue in **`verveguy/liminis`**,
+because that is where the package's backlog lived when the comment was written.
+Read `#973` as `verveguy/liminis#973`.
+
+References written *since* the extraction are fully qualified. Where you see
+`verveguy/liminis#995`, that qualification is deliberate and load-bearing: issue
+numbers in this repository are their own sequence, and this repository already has
+issues #1, #2 and #3 that have nothing to do with the ones the comments mean.
+
+## Vendored documents
+
+`src/app/mapper/__tests__/fixtures/real-documents/` holds byte-identical copies of
+real ADRs from `verveguy/liminis`, used as realistic round-trip input. Its own
+`README.md` records their provenance. They are vendored rather than read from a
+sibling checkout precisely so that no test in this repository reads a file outside
+it.
+
+`src/app/mapper/__tests__/fixtures/roundtrip/50-reference-readme.md` and its
+`.expected.md` pair contain strings that look like citations — `ADR-` prefixes, a
+`docs/project_notes/` path. They are neither citations nor mistakes: they are
+deliberately messy human prose being used as round-trip corpus. They were left
+untouched by the extraction's citation sweep, because editing them would change
+the bytes the fixture asserts on.

package/docs/zusammen-editor-capability-map.md

@@ -0,0 +1,232 @@
+# Zusammen Editor-Domain Capability Map
+
+**Date:** 2026-08-04
+**Issue:** #939 (Phase 2 — unified annotation mechanism), FR-008 / US3 / SC-006
+**Related:** ADR-077 (the unified annotation primitive), ADR-075 (the package boundary)
+
+## Why this document exists
+
+Zusammen (`verveguy/zusammen`) maintains its own copy of this editor, plus the
+anchor modules under `app/src/shared/`. Its adoption of `@liminis/editor` is a
+follow-up in that repository — out of scope here. What *is* in scope is proving
+the public API can serve it, because if there is a gap, adoption forces a fork
+or a deep import, which is the exact failure ADR-075 exists to prevent.
+
+This maps every editor-domain capability Zusammen has today to a symbol
+reachable from one of the package's declared export subpaths. It is checkable by
+reading it against `packages/editor/package.json`'s `exports` and the barrel
+files, without running Zusammen.
+
+**Result: zero unmet capabilities.** Three symbols are recorded as deliberate
+app-domain exclusions rather than gaps — see the last section for why each one
+is not the package's to provide.
+
+Package subpaths referenced below:
+
+| Subpath | Barrel |
+|---|---|
+| `.` | `packages/editor/src/index.ts` |
+| `./annotations` | `packages/editor/src/annotations.ts` |
+| `./markdown` | `packages/editor/src/markdown.ts` |
+| `./headless` | `packages/editor/src/headless.ts` |
+| `./contract` | `packages/editor/src/contract.ts` |
+| `./styles.css` | `packages/editor/src/styles.css` |
+
+### One adoption requirement that is not a symbol
+
+`./styles.css` carries the default `annotation-mark-*` rules, and **the host has
+to import it** — the package does not inject it, because a CSS import inside
+`<Editor>` or the root barrel would force a stylesheet on markdown-only
+consumers too. Zusammen should add:
+
+```ts
+import '@liminis/editor/styles.css'
+```
+
+alongside its `<Editor>` mount. Skipping it is not a build error and not a
+runtime error: anchors resolve, marks place, activation fires, and nothing
+renders. Called out here rather than left to discovery because Liminis cannot
+surface it — its only kind is `markerStyle: 'none'`, so it never places a mark
+whose styling could be missing. See ADR-077, "Marker styling ships with the
+package".
+
+---
+
+## 1. `app/src/shared/anchor-model.ts`
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `Anchor` | `Anchor` | `./annotations` |
+| `AnchorFields` | `AnchorFields` | `./annotations` |
+| `AnchorRange` | `AnchorRange` | `./annotations` |
+| `AnchorOutcome` | `AnchorOutcome` | `./annotations` |
+| `AnchorResolution` | `AnchorResolution` | `./annotations` |
+| `ANCHOR_SCHEMA` | `ANCHOR_SCHEMA` | `./annotations` |
+| `ANCHOR_RESOLUTION_SCHEMA` | `ANCHOR_RESOLUTION_SCHEMA` | `./annotations` |
+| `CONTEXT_WINDOW_CHARS` | `CONTEXT_WINDOW_CHARS` | `./annotations` |
+| `captureAnchor` | `captureAnchor` | `./annotations` |
+
+Ported verbatim; `anchor-model.test.ts` carries over and passes unmodified
+except for import paths.
+
+## 2. `app/src/shared/anchor-resolver.ts`
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `resolveAnchor` | `resolveAnchor` | `./annotations` |
+| `ResolveAnchorOptions` | `ResolveAnchorOptions` | `./annotations` |
+| `ProposeSemanticRelocation` | `ProposeSemanticRelocation` | `./annotations` |
+| `noopProposeSemanticRelocation` | `noopProposeSemanticRelocation` | `./annotations` |
+| `similarity` | `similarity` | `./annotations` |
+| `REATTACH_THRESHOLD` | `REATTACH_THRESHOLD` | `./annotations` |
+| `FLAG_THRESHOLD` | `FLAG_THRESHOLD` | `./annotations` |
+| *(no equivalent — new)* | `resolveAnchors`, `IdentifiedAnchor`, `AnchorResolutionResult` | `./annotations` |
+
+`resolveAnchors` is a batch wrapper added for the public surface (FR-002); it
+fans out over the same `resolveAnchor` path, so classification is unchanged.
+Zusammen's `main/comment-anchoring.ts` currently loops `resolveAnchor` itself
+behind its `comments:resolveAnchors` IPC handler and can call the wrapper
+instead.
+
+This module is the **sole** fuzzy-matching module for anchor re-resolution
+(FR-003). `anchor-resolver.test.ts` carries over unmodified.
+
+## 3. `app/src/shared/block-structure.ts`
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `BlockType` | `BlockType` | `./annotations` |
+| `Block` | `Block` | `./annotations` |
+| `SentenceChunk` | `SentenceChunk` | `./annotations` |
+| `parseBlocks` | `parseBlocks` | `./annotations` |
+| `findEnclosingBlock` | `findEnclosingBlock` | `./annotations` |
+| `blockPlainText` | `blockPlainText` | `./annotations` |
+| `sentenceChunks` | `sentenceChunks` | `./annotations` |
+
+Ported verbatim; `block-structure.test.ts` carries over unmodified.
+
+## 4. `app/src/shared/comment-anchor-align.ts` → `annotations/anchor-align.ts`
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `locateInSpan` | `locateInSpan` | `./annotations` |
+| `SpanRange` | `SpanRange` | `./annotations` |
+| `LocateInSpanOptions` | `LocateInSpanOptions` | `./annotations` |
+
+Renamed on port (the module is no longer comment-specific). Its test carries
+over unmodified.
+
+## 5. `app/src/shared/comment-editor-handle.ts`
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `CommentEditorHandle` | `AnnotationEditorHandle` | `./annotations` and `.` |
+
+Renamed, and its `removeMarksForComment` member is `removeMarksForAnnotation`.
+`collectLiveAnchorSnapshots` keeps its name and signature. The handle is
+populated by passing `annotationEditorHandleRef` to `<Editor>`; Zusammen's host
+reads it exactly as it does today.
+
+## 6. `app/src/shared/comment-thread.ts` — editor-domain parts only
+
+| Zusammen symbol | Package export | Subpath |
+|---|---|---|
+| `MarkerTarget` | `MarkerTarget` | `./annotations` and `.` |
+| `shouldPlaceLiveMark` | `shouldPlaceLiveMark` | `./annotations` |
+| `deriveMarkerTargets` | `deriveMarkerTargets` (re-expressed — see below) | `./annotations` |
+
+`MarkerTarget`'s `threadId` field is `annotationId` in the package, and it gains
+a `kind`. `shouldPlaceLiveMark` is identical, and the `shouldPlaceLiveMark`
+block of `comment-thread.test.ts` carries over.
+
+`deriveMarkerTargets` is **re-expressed, not ported**: Zusammen's takes
+`readonly Thread[]` and reaches into `thread.root` (a `Comment`), both of which
+are app-domain types under ADR-075. The package's takes
+`(annotations, kinds)`. Zusammen keeps its own thread→annotation projection —
+a few lines over types it already owns — and calls the package's version, or
+skips it entirely and passes `annotations` to `<Editor>`, which derives targets
+internally.
+
+## 7. `app/src/editor/app/editor/comment-anchor-marks.ts`
+
+Ported to `app/editor/annotation-marks.ts`. These are package-internal: they are
+Lexical-bound and are consumed by the package's own plugins, which now provide
+the behaviour Zusammen wired up by hand. The capability each one provided is
+still reachable, as shown:
+
+| Zusammen symbol | How the capability is reached | Subpath |
+|---|---|---|
+| `wrapNativeRangeInMark` | `<Editor onCreateAnnotation>` + `OPEN_ANNOTATION_COMPOSER_COMMAND` | `.` |
+| `readAnchorFields` | same — the captured anchor arrives on `AnnotationCreateEvent.anchor` | `.` |
+| `placeMarkForAnchor` | `<Editor annotations>` — the surface places marks per the kind's live-mark policy | `.` |
+| `collectLiveAnchorSnapshots` | `AnnotationEditorHandle.collectLiveAnchorSnapshots` | `.` |
+| `removeMarksForComment` | `AnnotationEditorHandle.removeMarksForAnnotation` | `.` |
+| `hasLiveMark` | not exported — see "Known gaps" | — |
+| `markElementsForId` | not exported — see "Known gaps" | — |
+
+## 8. Editor plugins
+
+| Zusammen module | Package equivalent | Subpath |
+|---|---|---|
+| `CommentSelectionPlugin.tsx` | `AnnotationPlugin` (mounted by `<Editor>`) | via `.` |
+| `CommentMarkerPlugin.tsx` | `AnnotationMarkerPlugin` (mounted by `<Editor>`) | via `.` |
+| `commentCommands.ts` | `OPEN_ANNOTATION_COMPOSER_COMMAND` | `.` |
+| `Editor.tsx`'s `CommentMarkPlacementPlugin` | internal to `AnnotationSurface`, driven by `annotations` | via `.` |
+| `Editor.tsx`'s `CommentEditorHandlePlugin` | internal, driven by `annotationEditorHandleRef` | via `.` |
+
+The plugins are not exported individually and do not need to be: `<Editor>`
+mounts them from `annotationKinds`. One behavioural difference Zusammen should
+know about — `CommentSelectionPlugin` renders its own composer (a textarea with
+Cancel/Comment buttons); `AnnotationPlugin` is headless and fires
+`onCreateAnnotation` with the captured anchor and the selection rect instead.
+The composer is host UX under ADR-075, so Zusammen brings its own. This is a
+deliberate boundary choice, not a missing capability.
+
+## 9. `app/src/editor/app/mapper/` — mark transparency
+
+| Zusammen capability | Package equivalent | Subpath |
+|---|---|---|
+| `effectiveChildren` mark-transparency | applied unconditionally inside `exportLexicalToMdast` | `.` |
+| `setAnnotateTarget` | package-internal (used by the capture primitive) | — |
+| `markOpenToken` / `markCloseToken` | package-internal | — |
+| `OffsetSpan` + `importMarkdownToLexical*WithOffsets` | package-internal; `<Editor>` collects spans itself | — |
+
+Mark transparency is a property of the export, not an API: a document with live
+marks exports byte-identically to the same document without them, asserted
+across the whole round-trip fixture corpus. Zusammen gets it by using the
+package's mapper at all.
+
+The sentinel and offset machinery is internal because its only consumer is the
+capture primitive, which the package now owns. Zusammen had to expose them
+because its host drove capture directly; it no longer does.
+
+---
+
+## Known gaps
+
+None that block adoption. Two symbols are intentionally unexported, with a
+rationale and a cheap escalation path:
+
+**`hasLiveMark(editor, id)` and `markElementsForId(editor, id)`.** Both take a
+`LexicalEditor`, which a host outside the composer tree does not have. In
+Zusammen both are used *inside* the editor tree — by `CommentMarkerPlugin` for
+decoration and scroll-to — and the package's `AnnotationMarkerPlugin` now does
+that work. If Zusammen finds a host-side use during adoption, the fix is to add
+them to `AnnotationEditorHandle`, which already exists for exactly this purpose
+and is the same one-line-per-method change `removeMarksForAnnotation` was. That
+is a considered export under ADR-075, not a fork.
+
+## Deliberate app-domain exclusions
+
+These are **not gaps**. Each stays app-side because ADR-075 draws the seam at
+persistence, and each of these is on the persistence side of it.
+
+| Symbol | Why it stays in Zusammen |
+|---|---|
+| `deriveMarkerTargets(threads: Thread[])` (original signature) | Takes `Thread`/`Comment` — Zusammen's own persistence model. The package cannot know their shape without importing the app's domain. Re-expressed over `Annotation[]` instead. |
+| `anchorOutcomeOf(comment: Comment)` | Reads a comment's last resolution event out of the WAL-reconstructed comment. That is Zusammen's event store's business; the package accepts an already-computed `outcome` on each annotation. |
+| `deriveWorkspaceCommentList` | App-domain by the issue's own instruction — cross-document browse UI, not an editor capability. |
+| `comment-store.ts`, `comment-anchoring.ts`, `comment-model.ts`, `renderer/comments/**`, `renderer/stores/comment*Store.ts` | Persistence, identity, lifecycle (resolve/reopen) and panel UX. FR-005 forbids all of it in the package. |
+
+The same rule applies symmetrically to Liminis: its correction store, and the
+accept/reject lifecycle, stay app-side too.