@liminis/editor 0.1.0-rc.1

package/dist/app/editor/annotation-marks.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 Marks (#43)
+ *
+ * Replaces `comment-anchor-mapping.ts`'s ordinal-block-index glue with a live
+ * `@lexical/mark` `MarkNode` per annotation id — the anchor moves with
+ * its text across in-app edits for free (Lexical splits/merges nodes around
+ * it), and serializes to nothing (see `lexicalToMdast.ts`'s
+ * `effectiveChildren`), so it never touches document content — an annotation is
+ * editor state, never bytes on disk.
+ *
+ * Two directions, both content-based rather than block-ordinal-based:
+ *
+ * - **Write** (capture, FR-006 re-anchor): a mark's own live plain text is
+ *   *not* generally a verbatim substring of the document's current raw
+ *   markdown — once the target contains or abuts bold/italic/inline-code/
+ *   link syntax, the rendered text and the markdown diverge (#47 fixes the
+ *   defect this caused: comments on formatted text spuriously flagging as
+ *   changed on a completely unchanged document; see the corrected premise
+ *   noted in `adrs/012-comment-anchor-as-live-mark.md`). Instead, a mark's
+ *   raw-markdown range is recovered via {@link locateLiveMarkdownRange}'s
+ *   annotated-serialize mechanism. A multi-block annotation shares one id
+ *   across several sibling `MarkNode`s (the Lexical playground's own
+ *   pattern); each is independently located, and the comment's overall
+ *   range is the span from the first mark's start to the last mark's end —
+ *   recovering exactly what
+ *   {@link import('../../../shared/anchor-model').captureAnchor} would slice
+ *   for a single-block annotation, and the same *kind* of raw-markdown slice
+ *   (including whatever lies between the marks) for a multi-block one.
+ * - **Read** (load-time placement): an anchor's `targetText` is already the
+ *   resolver's exact/resolved current text (main-process
+ *   `resolveAnchorsForDocument` runs before marker targets ever reach the
+ *   editor) — locate it once in the raw markdown via `locateInSpan`, map
+ *   that offset range onto Lexical nodes via the parse-time `OffsetSpan[]`
+ *   (boundary-snapping past any formatting-delimiter gap the target's edge
+ *   falls on, #47), and wrap. No client-side fuzzy matching.
+ */
+import { type LexicalEditor } from 'lexical';
+import { type Anchor, type AnchorFields, type AnchorRange } from '../../annotations/anchor-model.js';
+import type { OffsetSpan } from '../mapper/mdastToLexical.js';
+import { type ExportOptions } from '../mapper/lexicalToMdast.js';
+/**
+ * Wrap a native DOM Range in a `MarkNode` keyed by `id`. Fire-and-forget: the
+ * Lexical update runs the wrap, but its commit isn't observable synchronously
+ * (in controlled mode the callback runs on a later tick), so callers must NOT
+ * gate anything on a return value here — the anchor is read back from the live
+ * mark later via {@link readAnchorFields}.
+ */
+export declare function wrapNativeRangeInMark(editor: LexicalEditor, range: Range, id: string): void;
+/**
+ * Read an annotation's anchor fields directly from its live `MarkNode`(s) in the
+ * Lexical tree — targetText, surrounding context, block type, and an
+ * occurrence hint. The mark *is* the anchor; its position is known precisely
+ * from the node structure, so capture never depends on a (possibly stale)
+ * serialized-markdown string held elsewhere (`currentContentRef`) — this
+ * function derives its own current markdown export fresh, every call. The
+ * store stamps `docVersion`; the resolver (#25) still re-locates by content
+ * on future document versions.
+ *
+ * #47: targetText (and the context/blockType/occurrenceIndex derived from
+ * it) is a raw-*markdown* slice, not the mark's rendered plain text — see
+ * {@link locateLiveMarkdownRange}. Once the mark's exact raw-markdown range
+ * is known, {@link captureAnchor} (already markdown-domain-correct, and
+ * already used by the FR-006 re-anchor path) does the rest.
+ */
+export declare function readAnchorFields(editor: LexicalEditor, id: string, exportOptions?: ExportOptions): AnchorFields | null;
+/**
+ * Read pathway: places a `MarkNode` for `anchor` by locating its (already
+ * resolved/current) `targetText` in `markdownText` and mapping the located
+ * offset range onto Lexical nodes via `offsetSpans` (the parse-time
+ * offset->node table from `importMarkdownToLexicalWithOffsets`). Idempotent:
+ * a no-op if `id` already has a live mark. Returns whether a mark now
+ * exists for `id` (already present, or just placed) — false only when the
+ * anchor's target can't be located or mapped, in which case the comment
+ * stays panel-only (FR-008), never placed on unrelated text.
+ */
+export declare function placeMarkForAnchor(editor: LexicalEditor, offsetSpans: readonly OffsetSpan[], markdownText: string, anchor: Anchor, id: string): boolean;
+/**
+ * Places many anchors inside a *single* `editor.update()`.
+ *
+ * Same per-anchor logic as {@link placeMarkForAnchor}, but one Lexical
+ * reconciliation for the whole batch instead of one per annotation — a
+ * document with dozens of live annotations otherwise pays a synchronous
+ * reconcile each, every time a re-parse invalidates the offset table (review
+ * finding, @handarbeit-pruefer). Returns the ids that now have a live mark, in
+ * the caller's own order.
+ *
+ * **Two phases, because `offsetSpans` describes only the pristine parse.**
+ * Placing a mark splits the `TextNode` it lands in, and Lexical's `splitText`
+ * keeps the original key on the *first* segment — so after one placement the
+ * table's `(nodeKey, offset)` pairs can point past the end of what that key now
+ * holds, and the guards below decline. An earlier fix ordered the batch back to
+ * front, which keeps every *disjoint* entry's span valid but does nothing for
+ * ranges that overlap, nest or coincide: there the later placement splits a node
+ * an *earlier* entry still needs, and that entry silently declines (Liminis
+ * #970 — an ordinary pair of overlapping annotations placed only one mark).
+ *
+ * The fix is to stop depending on the table surviving at all. Marking changes
+ * no text, so a point's *absolute* character offset across every text node in
+ * the document is invariant under placement — the same invariant
+ * {@link $withPreservedSelection} already relies on to put the caret back.
+ * So:
+ *
+ * 1. **Resolve**, against the pristine tree, before anything is mutated: run
+ *    every entry through the offset table and today's decline guards, and
+ *    convert each surviving endpoint to an absolute text offset.
+ * 2. **Place**, in the caller's order: re-resolve each absolute offset against
+ *    the *current* tree and wrap.
+ *
+ * Every entry is therefore independent of every other, so the set of ids placed
+ * no longer depends on the order they were supplied in and the back-to-front
+ * sort is gone. Both phases run inside the one `editor.update()`.
+ */
+export declare function placeMarksForAnchors(editor: LexicalEditor, offsetSpans: readonly OffsetSpan[], markdownText: string, entries: readonly {
+    anchor: Anchor;
+    id: string;
+}[]): string[];
+/**
+ * FR-006: the current live range of every comment with a mark in the
+ * document, keyed by comment id — used at checkpoint time to decide which
+ * comments' anchors actually need re-recording (only those whose current
+ * range's text differs from their last durable `anchor.targetText`).
+ * Comments with no live mark (orphaned, flagged, or not yet resolved into
+ * the open document) are simply absent from the returned map.
+ */
+export declare function collectLiveAnchorSnapshots(editor: LexicalEditor, markdownText: string, exportOptions?: ExportOptions): Map<string, AnchorRange>;
+/** Whether `id` currently has a live mark anywhere in the document. */
+export declare function hasLiveMark(editor: LexicalEditor, id: string): boolean;
+/**
+ * The real, rendered DOM elements for every live `MarkNode` wrapping `id`,
+ * in document order — for `CommentMarkerPlugin` to decorate directly
+ * (outcome/active class, click/keydown navigation) instead of computing a
+ * synthetic overlay. Empty when `id` has no live mark (e.g. a `flagged`
+ * target, which never gets one placed — see `placeMarkForAnchor` callers).
+ */
+export declare function markElementsForId(editor: LexicalEditor, id: string): HTMLElement[];
+/**
+ * {@link markElementsForId} for many ids at once, in one tree walk.
+ *
+ * The marker plugin re-decorates on every editor update, and calling the
+ * single-id form per annotation makes that O(annotations x nodes) on a path
+ * that runs after each edit (review finding, @handarbeit-pruefer). One walk
+ * makes it O(nodes) regardless of how many annotations are live. Element lists
+ * are in document order, and ids with no live mark are simply absent.
+ */
+export declare function markElementsByAnnotationId(editor: LexicalEditor, ids: ReadonlySet<string>): Map<string, HTMLElement[]>;
+/**
+ * Removes every `MarkNode` wrapping `id` (annotation deleted, or composer
+ * cancelled before submit). A mark shared with other annotation ids
+ * (overlapping annotations) keeps its other ids and stays in the tree; a mark
+ * left with none is unwrapped back to plain content.
+ */
+export declare function removeMarksForAnnotation(editor: LexicalEditor, id: string): void;
+/**
+ * Removes many annotations' marks inside a *single* `editor.update()`.
+ *
+ * The batched counterpart to {@link removeMarksForAnnotation}, for the same
+ * reason {@link placeMarksForAnchors} exists: a host that drops a set of live
+ * annotations at once — "resolve all comments", or an `offsetsVersion` bump
+ * that takes a batch of ids out of the marker targets — would otherwise force
+ * one synchronous Lexical reconciliation per id (review finding,
+ * @handarbeit-pruefer). One tree walk covers the whole set.
+ */
+export declare function removeMarksForAnnotations(editor: LexicalEditor, ids: readonly string[]): void;