@liminis/editor 0.1.0-rc.1

package/dist/app/editor/AmbientCorrectionPlugin.js

@@ -0,0 +1,185 @@
+import { useEffect, useRef } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { $getRoot, $isElementNode, $isTextNode } from 'lexical';
+import { $isCodeNode } from '@lexical/code';
+import { $isFrontmatterNode } from './nodes/index.js';
+// ── Utilities ────────────────────────────────────────────────────────────────
+/** Return text content from prose nodes only (skips code blocks and frontmatter). */
+function collectProseText(root) {
+    let text = '';
+    const walk = (node) => {
+        if ($isCodeNode(node) || $isFrontmatterNode(node))
+            return;
+        if ($isTextNode(node)) {
+            text += node.getTextContent();
+            return;
+        }
+        if ($isElementNode(node)) {
+            for (const child of node.getChildren())
+                walk(child);
+        }
+    };
+    walk(root);
+    return text;
+}
+/** True if the char is a word character (letter, digit, or underscore). */
+function isWordChar(c) {
+    return /\w/.test(c);
+}
+/** True if `region` consists only of word characters (single word token). */
+function isSingleWordToken(region) {
+    return region.length > 0 && /^\w+$/.test(region);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Preserve the original capitalisation pattern of a matched word when replacing.
+ * - ALL-CAPS → ALL-CAPS replacement
+ * - Title-case → Title-case replacement
+ * - otherwise → lowercase replacement
+ */
+function applyCase(match, replacement) {
+    if (match === match.toUpperCase() && match !== match.toLowerCase()) {
+        return replacement.toUpperCase();
+    }
+    const firstChar = match.charAt(0);
+    if (match.length > 0 &&
+        firstChar.toUpperCase() === firstChar &&
+        firstChar.toLowerCase() !== firstChar &&
+        match.slice(1) === match.slice(1).toLowerCase()) {
+        return replacement.length > 0
+            ? replacement.charAt(0).toUpperCase() + replacement.slice(1).toLowerCase()
+            : replacement;
+    }
+    return replacement.toLowerCase();
+}
+// ── Substitution detection ────────────────────────────────────────────────────
+/**
+ * Analyse a before/after text pair to detect a single-word substitution.
+ * Returns `{ oldTerm, newTerm }` when a valid substitution is detected, or null.
+ */
+function analyzeForSubstitution(prev, current) {
+    if (prev === current)
+        return null;
+    // Find common prefix
+    let prefixLen = 0;
+    const minLen = Math.min(prev.length, current.length);
+    while (prefixLen < minLen && prev[prefixLen] === current[prefixLen])
+        prefixLen++;
+    // Find common suffix (must not overlap with prefix)
+    let suffixLen = 0;
+    const maxSuffix = minLen - prefixLen;
+    while (suffixLen < maxSuffix &&
+        prev[prev.length - 1 - suffixLen] === current[current.length - 1 - suffixLen]) {
+        suffixLen++;
+    }
+    const oldRegion = prev.slice(prefixLen, suffixLen > 0 ? -suffixLen : undefined);
+    const newRegion = current.slice(prefixLen, suffixLen > 0 ? -suffixLen : undefined);
+    if (!isSingleWordToken(oldRegion) || !isSingleWordToken(newRegion))
+        return null;
+    if (oldRegion.toLowerCase() === newRegion.toLowerCase())
+        return null;
+    // Must sit at word boundaries in the prose text
+    const charBefore = prefixLen > 0 ? prev[prefixLen - 1] : null;
+    const charAfter = prev.length - suffixLen < prev.length ? prev[prev.length - suffixLen] : null;
+    if (charBefore !== null && isWordChar(charBefore))
+        return null;
+    if (charAfter !== null && isWordChar(charAfter))
+        return null;
+    return { oldTerm: oldRegion, newTerm: newRegion };
+}
+// ── Plugin ────────────────────────────────────────────────────────────────────
+/**
+ * Ambient correction plugin.
+ *
+ * 1. Detects single-word substitutions (debounced 300 ms) and calls
+ *    `onSubstitutionDetected` so the parent can show a nudge toast.
+ *
+ * 2. Populates `sweepRef.current` with a function that performs the confirmed
+ *    sweep: replaces all remaining occurrences of `oldTerm` with `newTerm`
+ *    (case-preserving, skipping code blocks and frontmatter) inside a single
+ *    `editor.update()` call so undo produces one history entry.
+ */
+export function AmbientCorrectionPlugin({ onSubstitutionDetected, sweepRef, }) {
+    const [editor] = useLexicalComposerContext();
+    const debounceRef = useRef(null);
+    const callbackRef = useRef(onSubstitutionDetected);
+    callbackRef.current = onSubstitutionDetected;
+    // Populate the sweep ref so the parent can trigger a sweep from outside.
+    useEffect(() => {
+        if (!sweepRef)
+            return;
+        sweepRef.current = (oldTerm, newTerm) => new Promise((resolve) => {
+            let count = 0;
+            const escaped = escapeRegex(oldTerm);
+            const regex = new RegExp(`\\b${escaped}\\b`, 'gi');
+            editor.update(() => {
+                // Tree-walker: skip entire code/frontmatter subtrees rather than
+                // checking ancestors per-node (O(N) vs O(N * depth)).
+                const walk = (node) => {
+                    if ($isCodeNode(node) || $isFrontmatterNode(node))
+                        return;
+                    if ($isTextNode(node)) {
+                        const text = node.getTextContent();
+                        const replaced = text.replace(regex, (match) => {
+                            count++;
+                            return applyCase(match, newTerm);
+                        });
+                        if (replaced !== text)
+                            node.setTextContent(replaced);
+                        return;
+                    }
+                    if ($isElementNode(node)) {
+                        for (const child of node.getChildren())
+                            walk(child);
+                    }
+                };
+                walk($getRoot());
+            }, { discrete: true, onUpdate: () => resolve(count) });
+        });
+        return () => {
+            sweepRef.current = null;
+        };
+    }, [editor, sweepRef]);
+    // Register change listener for substitution detection.
+    useEffect(() => {
+        const unregister = editor.registerUpdateListener(({ editorState, prevEditorState, dirtyElements, dirtyLeaves }) => {
+            // Skip pure selection changes that don't touch content nodes.
+            if (dirtyLeaves.size === 0 && dirtyElements.size === 0)
+                return;
+            if (debounceRef.current !== null)
+                clearTimeout(debounceRef.current);
+            // Capture editor state refs — defer expensive getTextContent() reads
+            // until the debounce fires, so we don't read full document on every keystroke.
+            const capturedState = editorState;
+            const capturedPrevState = prevEditorState;
+            debounceRef.current = setTimeout(() => {
+                debounceRef.current = null;
+                // Compare prose-only text (skipping code blocks and frontmatter) so that:
+                // - substitutions inside excluded regions don't fire (false positives)
+                // - terms that appear in code blocks don't suppress prose detection (false negatives)
+                let currentProseText = '';
+                let prevProseText = '';
+                capturedState.read(() => {
+                    currentProseText = collectProseText($getRoot());
+                });
+                capturedPrevState.read(() => {
+                    prevProseText = collectProseText($getRoot());
+                });
+                const result = analyzeForSubstitution(prevProseText, currentProseText);
+                if (result) {
+                    callbackRef.current(result.oldTerm, result.newTerm);
+                }
+            }, 300);
+        });
+        return () => {
+            unregister();
+            if (debounceRef.current !== null) {
+                clearTimeout(debounceRef.current);
+                debounceRef.current = null;
+            }
+        };
+    }, [editor]);
+    return null;
+}

package/dist/app/editor/AnchorScrollPlugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AnchorScrollPlugin - Scrolls to headings when anchor links are clicked
+ *
+ * This plugin listens for host "scroll to anchor" requests (raised when an anchor
+ * link like `[[#Heading Name]]` is clicked) and scrolls to the matching heading in
+ * the document.
+ *
+ * The plugin:
+ * 1. Subscribes via the injected `onScrollToAnchor` host service
+ * 2. Finds headings by GitHub-style slug matching (case-insensitive, punctuation-stripped)
+ * 3. Retries across animation frames (bounded) while async content (equations,
+ *    diagrams, code highlighting) is still rendering the target heading
+ * 4. Scrolls the discovered scrollable ancestor, positioning the heading near the top
+ * 5. Cleans up the subscription and any in-flight retry loop on unmount
+ */
+export declare function AnchorScrollPlugin(): null;

package/dist/app/editor/AnchorScrollPlugin.js

@@ -0,0 +1,134 @@
+import { useEffect } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { useEditorHost } from '../../host/context.js';
+/**
+ * Reduce text to a GitHub-style anchor slug so a link fragment matches a heading
+ * regardless of punctuation the anchor drops. GitHub lowercases, removes
+ * punctuation (dots, backticks, `?`, emoji, …), and turns spaces into hyphens —
+ * e.g. a heading "Rebase and migration from `.env.enc`" slugs to
+ * `rebase-and-migration-from-envenc`, matching that link fragment. Applying the
+ * same reduction to both the anchor and each heading makes them comparable.
+ * `\p{L}\p{N}` (rather than `a-z0-9`) keeps non-Latin letters — e.g. "Übersicht"
+ * or "介绍" — instead of stripping them to nothing, which would make such
+ * headings permanently unreachable and collide with unrelated ASCII headings.
+ */
+function normalizeForMatch(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s\-_]/gu, '') // drop punctuation/emoji GitHub strips
+        .trim()
+        .replace(/[\s-]+/g, '-') // spaces and dash runs → single hyphen
+        .replace(/^-+|-+$/g, ''); // trim stray hyphens
+}
+/**
+ * Find the scrollable container for a heading: the known editor scroll ids first,
+ * then the nearest ancestor that actually scrolls (robust to host markup).
+ */
+function scrollContainerFor(heading) {
+    // Assumes the two known ids are never nested inside one another; neither
+    // known host does. If that ever changes, the closer one should win instead.
+    const byId = heading.closest('#editor-scroll-container') ||
+        heading.closest('#editor-panel-scroll-container');
+    if (byId)
+        return byId;
+    let el = heading.parentElement;
+    while (el) {
+        const overflowY = getComputedStyle(el).overflowY;
+        if (/(auto|scroll)/.test(overflowY) && el.scrollHeight > el.clientHeight)
+            return el;
+        el = el.parentElement;
+    }
+    return null;
+}
+/**
+ * Scroll the editor to the heading whose normalized text matches `anchor`.
+ * Returns true if a matching heading was found and scrolled — false if not (yet)
+ * present, so the caller can retry while async content finishes rendering.
+ */
+function scrollToHeading(editor, anchor) {
+    const normalizedAnchor = normalizeForMatch(anchor);
+    if (!normalizedAnchor)
+        return false;
+    const rootElement = editor.getRootElement();
+    if (!rootElement)
+        return false;
+    const selector = [
+        '.editor-heading-h1',
+        '.editor-heading-h2',
+        '.editor-heading-h3',
+        '.editor-heading-h4',
+        '.editor-heading-h5',
+    ].join(',');
+    const headings = Array.from(rootElement.querySelectorAll(selector));
+    const heading = headings.find((h) => normalizeForMatch(h.textContent || '') === normalizedAnchor);
+    if (!heading)
+        return false;
+    const container = scrollContainerFor(heading);
+    if (container) {
+        // rect-based offset is robust regardless of the heading's offsetParent;
+        // leave a small margin so the heading sits near the top, not flush against it.
+        const MARGIN = 16;
+        const top = Math.max(0, heading.getBoundingClientRect().top -
+            container.getBoundingClientRect().top +
+            container.scrollTop -
+            MARGIN);
+        container.scrollTo({ top, behavior: 'smooth' });
+    }
+    else {
+        heading.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+    return true;
+}
+/**
+ * AnchorScrollPlugin - Scrolls to headings when anchor links are clicked
+ *
+ * This plugin listens for host "scroll to anchor" requests (raised when an anchor
+ * link like `[[#Heading Name]]` is clicked) and scrolls to the matching heading in
+ * the document.
+ *
+ * The plugin:
+ * 1. Subscribes via the injected `onScrollToAnchor` host service
+ * 2. Finds headings by GitHub-style slug matching (case-insensitive, punctuation-stripped)
+ * 3. Retries across animation frames (bounded) while async content (equations,
+ *    diagrams, code highlighting) is still rendering the target heading
+ * 4. Scrolls the discovered scrollable ancestor, positioning the heading near the top
+ * 5. Cleans up the subscription and any in-flight retry loop on unmount
+ */
+export function AnchorScrollPlugin() {
+    const [editor] = useLexicalComposerContext();
+    const { onScrollToAnchor } = useEditorHost();
+    useEffect(() => {
+        // Early exit if the host does not offer anchor scrolling
+        if (!onScrollToAnchor) {
+            return;
+        }
+        let raf = 0;
+        const unsubscribe = onScrollToAnchor((anchor) => {
+            // A new anchor emission supersedes any retry loop still in flight for a
+            // previous one.
+            cancelAnimationFrame(raf);
+            // Normalization is independent of DOM timing, so an anchor that
+            // normalizes to empty (e.g. punctuation-only) can never match no
+            // matter how long we retry — skip the animation-frame budget entirely.
+            if (!normalizeForMatch(anchor))
+                return;
+            // attempts counts this call before scrollToHeading runs, so the budget
+            // below caps the loop at exactly 30 total calls (1 immediate + up to 29
+            // retries), not 31.
+            let attempts = 0;
+            const tryScroll = () => {
+                attempts++;
+                if (scrollToHeading(editor, anchor))
+                    return;
+                if (attempts < 30)
+                    raf = requestAnimationFrame(tryScroll);
+            };
+            tryScroll();
+        });
+        return () => {
+            cancelAnimationFrame(raf);
+            unsubscribe();
+        };
+    }, [editor, onScrollToAnchor]);
+    return null;
+}

package/dist/app/editor/AnnotationMarkerPlugin.d.ts

@@ -0,0 +1,24 @@
+import type { AnnotationKindConfigs, MarkerTarget } from '../../annotations/types.js';
+interface AnnotationMarkerPluginProps {
+    targets: MarkerTarget[];
+    kinds: AnnotationKindConfigs;
+    activeAnnotationId: string | null;
+    onActivateAnnotation: (id: string) => void;
+    /** Host-driven signal to scroll to an annotation's marker (nonce forces re-scroll on repeats). */
+    scrollToAnnotation?: {
+        id: string;
+        nonce: number;
+    } | null;
+}
+/**
+ * Decorates the real `MarkNode` DOM elements placed by `annotation-marks.ts`
+ * with per-kind styling and click/keydown activation — never a separate
+ * overlay layer.
+ *
+ * Only targets that earned a live mark are decorated; `flagged`/`orphaned`
+ * anchors, and any kind whose `livemarkPolicy` declines, are simply absent
+ * from the DOM here and stay panel-only. Activation routes back to the host,
+ * which owns whatever panel or thread the annotation belongs to.
+ */
+export declare function AnnotationMarkerPlugin({ targets, kinds, activeAnnotationId, onActivateAnnotation, scrollToAnnotation, }: AnnotationMarkerPluginProps): null;
+export {};

package/dist/app/editor/AnnotationMarkerPlugin.js

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { markElementsByAnnotationId, markElementsForId } from './annotation-marks.js';
+const ACTIVE_CLASS = 'annotation-mark-active';
+const PULSE_CLASS = 'annotation-mark-pulse';
+/**
+ * Decorates the real `MarkNode` DOM elements placed by `annotation-marks.ts`
+ * with per-kind styling and click/keydown activation — never a separate
+ * overlay layer.
+ *
+ * Only targets that earned a live mark are decorated; `flagged`/`orphaned`
+ * anchors, and any kind whose `livemarkPolicy` declines, are simply absent
+ * from the DOM here and stay panel-only. Activation routes back to the host,
+ * which owns whatever panel or thread the annotation belongs to.
+ */
+export function AnnotationMarkerPlugin({ targets, kinds, activeAnnotationId, onActivateAnnotation, scrollToAnnotation, }) {
+    const [editor] = useLexicalComposerContext();
+    // Cleanups from the previous decoration pass, run before the next one —
+    // avoids leaking listeners/attributes onto an element a since-removed or
+    // since-recreated target no longer covers.
+    const cleanupsRef = useRef([]);
+    const decorate = useCallback(() => {
+        const cleanups = cleanupsRef.current;
+        for (const cleanup of cleanups)
+            cleanup();
+        cleanups.length = 0;
+        // Group by DOM element before decorating, rather than iterating targets.
+        // Overlapping annotations share one MarkNode — and therefore one element —
+        // by design (`removeMarksForAnnotation` keeps a mark alive while it still
+        // carries other ids). Decorating per-target would attach a second listener
+        // pair to that shared element, so one click fired `onActivateAnnotation`
+        // once per overlapping annotation, and title/aria-label/data-kind/active
+        // would each reflect only whichever target happened to be processed last.
+        const decoratable = targets.filter((target) => {
+            const config = kinds[target.kind];
+            return !!config && config.markerStyle !== 'none';
+        });
+        // One tree walk for the whole set, not one per target — this runs after
+        // every content edit, so the single-id lookup would make it
+        // O(annotations x nodes) per keystroke.
+        const elementsById = markElementsByAnnotationId(editor, new Set(decoratable.map((target) => target.annotationId)));
+        const byElement = new Map();
+        for (const target of decoratable) {
+            for (const element of elementsById.get(target.annotationId) ?? []) {
+                const existing = byElement.get(element);
+                if (existing)
+                    existing.push(target);
+                else
+                    byElement.set(element, [target]);
+            }
+        }
+        for (const [element, elementTargets] of byElement) {
+            // Visual classes are additive — every annotation covering this element
+            // contributes its kind's marker style and any host-supplied className, so
+            // an overlap can be styled as one.
+            const classes = new Set();
+            for (const target of elementTargets) {
+                classes.add(`annotation-mark-${kinds[target.kind].markerStyle}`);
+                const extra = target.presentation?.className;
+                if (extra)
+                    classes.add(extra);
+            }
+            // Identity and behaviour are single-valued, so one target has to speak
+            // for the element: the active annotation if one of them is active,
+            // otherwise the first in document order. Activation fires exactly once.
+            const representative = elementTargets.find((t) => t.annotationId === activeAnnotationId) ?? elementTargets[0];
+            const isActive = elementTargets.some((t) => t.annotationId === activeAnnotationId);
+            const baseLabel = representative.presentation?.label ?? representative.kind;
+            // A host-supplied `presentation.label` wins over the kind default; the
+            // flagged suffix still applies so the uncertainty isn't hidden by an
+            // override, and an overlap says so rather than silently naming one of them.
+            const flaggedLabel = representative.outcome === 'flagged'
+                ? `${baseLabel} — location uncertain since this text changed`
+                : baseLabel;
+            const label = elementTargets.length > 1
+                ? `${flaggedLabel} (+${elementTargets.length - 1} more here)`
+                : flaggedLabel;
+            for (const className of classes)
+                element.classList.add(className);
+            element.classList.toggle(ACTIVE_CLASS, isActive);
+            element.dataset.annotationKind = representative.kind;
+            element.title = label;
+            element.tabIndex = 0;
+            element.setAttribute('role', 'button');
+            element.setAttribute('aria-label', label);
+            const activate = () => onActivateAnnotation(representative.annotationId);
+            const handleKeydown = (e) => {
+                if (e.key !== 'Enter' && e.key !== ' ')
+                    return;
+                e.preventDefault();
+                activate();
+            };
+            element.addEventListener('click', activate);
+            element.addEventListener('keydown', handleKeydown);
+            cleanups.push(() => {
+                element.classList.remove(ACTIVE_CLASS);
+                for (const className of classes)
+                    element.classList.remove(className);
+                delete element.dataset.annotationKind;
+                element.removeAttribute('title');
+                element.removeAttribute('aria-label');
+                element.removeAttribute('role');
+                element.removeAttribute('tabindex');
+                element.removeEventListener('click', activate);
+                element.removeEventListener('keydown', handleKeydown);
+            });
+        }
+    }, [editor, targets, kinds, activeAnnotationId, onActivateAnnotation]);
+    useEffect(() => {
+        decorate();
+    }, [decorate]);
+    useEffect(() => {
+        return editor.registerUpdateListener(({ dirtyElements, dirtyLeaves }) => {
+            // Selection-only updates cannot move or recreate a mark's element, so
+            // there is nothing to re-decorate. Lexical fires this listener on every
+            // cursor move as well as every edit, and decoration tears down and
+            // rebuilds each element's listeners and attributes — so skipping the
+            // no-op case takes arrow-key navigation off that path entirely
+            // (review finding, @handarbeit-pruefer).
+            if (dirtyElements.size === 0 && dirtyLeaves.size === 0)
+                return;
+            decorate();
+        });
+    }, [editor, decorate]);
+    useEffect(() => {
+        // Captured here rather than read in the cleanup: the ref's *identity* is
+        // stable for the component's lifetime (decorate mutates the array in
+        // place, never reassigns), so this holds the same array the last
+        // decoration pass filled.
+        const cleanups = cleanupsRef.current;
+        return () => {
+            for (const cleanup of cleanups)
+                cleanup();
+            cleanups.length = 0;
+        };
+    }, []);
+    // Smooth-scroll to an annotation's marker, keep it centered as the layout
+    // settles, and pulse it on arrival. Scrolling once lands short on a fresh
+    // open: async content above the anchor (images loading their height,
+    // diagrams/syntax highlighting rendering) shifts the anchor down *after* the
+    // scroll, and that timing is variable. Rather than guess when layout is
+    // "done", react to it — scroll once the marker exists, then re-center on
+    // every content resize for a short window.
+    //
+    // An unknown or orphaned id has no marker element, so `center` never
+    // succeeds and this quietly gives up after the appear window: a no-op, not
+    // an error.
+    useEffect(() => {
+        const id = scrollToAnnotation?.id;
+        if (!id)
+            return;
+        let raf = 0;
+        let appearFrames = 0;
+        let stopTimer = 0;
+        let pulseTimer = 0;
+        let observer = null;
+        let visibility = null;
+        const center = (behavior) => {
+            const element = markElementsForId(editor, id)[0];
+            if (!element)
+                return false;
+            element.scrollIntoView({ behavior, block: 'center' });
+            return true;
+        };
+        const pulse = () => {
+            for (const el of markElementsForId(editor, id)) {
+                el.classList.remove(PULSE_CLASS);
+                void el.offsetWidth; // reflow so the animation restarts on a repeat navigation
+                el.classList.add(PULSE_CLASS);
+            }
+            pulseTimer = window.setTimeout(() => {
+                for (const el of markElementsForId(editor, id))
+                    el.classList.remove(PULSE_CLASS);
+            }, 1400);
+        };
+        const start = () => {
+            if (!center('smooth')) {
+                if (appearFrames++ < 60)
+                    raf = requestAnimationFrame(start); // wait for the mark to be placed
+                return;
+            }
+            // Pulse when the anchor actually scrolls into view, not now — firing it
+            // here plays the flash while it's still off-screen so it fades before you
+            // see it.
+            const marker = markElementsForId(editor, id)[0];
+            if (marker && typeof IntersectionObserver !== 'undefined') {
+                visibility = new IntersectionObserver((entries, io) => {
+                    if (entries.some((e) => e.isIntersecting)) {
+                        pulse();
+                        io.disconnect();
+                        visibility = null;
+                    }
+                }, 
+                // threshold 0 (fire as soon as any part is visible), not 0.5 — a mark
+                // spanning more than half the viewport never reaches a 0.5 ratio, so
+                // the pulse would silently never play.
+                { threshold: 0 });
+                visibility.observe(marker);
+            }
+            else {
+                pulse();
+            }
+            const root = editor.getRootElement();
+            if (root && typeof ResizeObserver !== 'undefined') {
+                observer = new ResizeObserver(() => center('smooth'));
+                observer.observe(root);
+                stopTimer = window.setTimeout(() => observer?.disconnect(), 2500);
+            }
+        };
+        start();
+        return () => {
+            cancelAnimationFrame(raf);
+            observer?.disconnect();
+            visibility?.disconnect();
+            if (stopTimer)
+                clearTimeout(stopTimer);
+            if (pulseTimer)
+                clearTimeout(pulseTimer);
+        };
+        // Depends on `nonce` as well as `id` so a repeat scroll-to the same
+        // annotation re-triggers rather than being skipped as an unchanged dep.
+    }, [editor, scrollToAnnotation?.id, scrollToAnnotation?.nonce]);
+    return null;
+}

package/dist/app/editor/AnnotationPlugin.d.ts

@@ -0,0 +1,42 @@
+import type { AnchorFields } from '../../annotations/anchor-model.js';
+import type { AnnotationKindConfigs } from '../../annotations/types.js';
+import type { WikiLinkPromotionMode } from '../mapper/lexicalToMdast.js';
+export interface AnnotationCreateEvent {
+    /** The kind that was created, as configured by the host. */
+    kind: string;
+    /** The id the package minted for the transient mark. Hosts may adopt it or mint their own. */
+    id: string;
+    /** The captured anchor, or null if the selection didn't resolve to real content. */
+    anchor: AnchorFields | null;
+    /** Where the selection was on screen, for hosts that position a composer. */
+    rect: DOMRect;
+}
+interface AnnotationPluginProps {
+    kinds: AnnotationKindConfigs;
+    /**
+     * Fires when the user invokes a kind's create affordance. The package
+     * captures the anchor and hands it over — it never persists anything
+     * (ADR-075/FR-005); storage, identity and lifecycle are the host's.
+     */
+    onCreateAnnotation: (event: AnnotationCreateEvent) => void;
+    /** Injected so the package never imports a host logger directly (FR-010). */
+    logger?: {
+        warn: (message: string, ...args: unknown[]) => void;
+    };
+    /** Forwarded to the anchor-capture export pass — see `Editor`'s own prop of the same name. */
+    wikiLinkPromotion?: WikiLinkPromotionMode;
+}
+/**
+ * Turns a user selection into a captured anchor for a configured kind.
+ *
+ * Deliberately headless: it renders no composer of its own. Whether a comment
+ * gets a textarea or a correction gets a panel is host UX, so this plugin's
+ * whole job is to listen for the create command, run the shared capture
+ * primitive, and hand the anchor out. Both kinds take the same path here —
+ * only `retainMarkOnCreate` differs, which is what SC-001 rests on.
+ *
+ * Not gated on `editable`: annotating is decoupled from editing, and a
+ * read-only document is a legitimate place to comment.
+ */
+export declare function AnnotationPlugin({ kinds, onCreateAnnotation, logger, wikiLinkPromotion }: AnnotationPluginProps): null;
+export {};