@liminis/editor 0.1.0-rc.1

package/dist/annotations/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Unified annotation types (ADR-077).
+ *
+ * An annotation is a range-anchored marker over document text. Comments and
+ * corrections are not separate features here — they are two *kinds*, differing
+ * only by the {@link AnnotationKindConfig} a host supplies. Everything in this
+ * module is DOM-free, Lexical-free and React-free so it can be reached from the
+ * `./annotations` subpath and used outside a rendered editor.
+ *
+ * Per ADR-075 the seam is persistence: the package owns anchor mechanics and
+ * marker rendering; identity, storage and lifecycle (resolve/reopen for
+ * comments, accept/reject for corrections) stay in the consuming app. The
+ * package treats `id` as opaque and `payload` as pass-through.
+ */
+import type { Anchor, AnchorOutcome, AnchorRange } from './anchor-model.js';
+/**
+ * Which kind of annotation this is. Deliberately a plain string rather than a
+ * closed union — a host may configure kinds the package has never heard of,
+ * and the two Liminis/Zusammen kinds carry no special status in the mechanism.
+ */
+export type AnnotationKind = string;
+/** Presentation hints a host may attach per annotation, overriding kind defaults. */
+export interface AnnotationPresentation {
+    /** Extra CSS class applied to this annotation's marker element. */
+    className?: string;
+    /** Accessible label for the marker; falls back to the kind name. */
+    label?: string;
+}
+/**
+ * A range-anchored marker over document text. `id` is opaque to the package —
+ * hosts mint and persist it. `payload` is carried through untouched and handed
+ * back on activation, so a host can round-trip its own domain object without
+ * the package understanding it.
+ */
+export interface Annotation<TPayload = unknown> {
+    id: string;
+    kind: AnnotationKind;
+    anchor: Anchor;
+    /**
+     * The resolution outcome currently in effect for this anchor. Hosts compute
+     * this (via `resolveAnchors` or their own store) — the package never
+     * classifies on the host's behalf. Defaults to `unchanged` when omitted.
+     */
+    outcome?: AnchorOutcome;
+    presentation?: AnnotationPresentation;
+    payload?: TPayload;
+}
+/**
+ * How a kind's markers paint. `none` places no visible marker at all, which is
+ * what corrections use: they adopt the anchor model and the capture primitive
+ * but render exactly what they render today — nothing (FR-006 parity).
+ */
+export type AnnotationMarkerStyle = 'highlight' | 'squiggle' | 'none';
+/** Where a kind's user-initiated create affordance is offered, if anywhere. */
+export interface AnnotationCreateAffordance {
+    surface: 'toolbar' | 'contextMenu';
+    label?: string;
+}
+/**
+ * The per-kind configuration record. SC-001's claim rests on this type: a
+ * reviewer can point at two values of it as the entire difference between the
+ * comment feature and the correction feature.
+ */
+export interface AnnotationKindConfig<TPayload = unknown> {
+    markerStyle: AnnotationMarkerStyle;
+    /**
+     * User-initiated creation. Omitted or null means host-injected only — the
+     * package offers no way for a user to create one.
+     *
+     * CAUTION: a kind literally named `correction` on the `contextMenu` surface
+     * is special-cased internally — `SelectionContextMenuPlugin` opens the
+     * package's own legacy correction panel for it in addition to dispatching
+     * this create flow. If such a kind's host also supplies
+     * `onCreateAnnotation`, both UIs open off the same click with no
+     * coordination between them. Name a kind something other than `correction`
+     * if you want only the standard create flow.
+     */
+    createAffordance?: AnnotationCreateAffordance | null;
+    /**
+     * Whether this annotation gets a live `MarkNode` in the document. Defaults to
+     * {@link shouldPlaceLiveMark} over the annotation's outcome when omitted.
+     *
+     * Consulted only when `markerStyle` is not `none` — see
+     * {@link deriveMarkerTargets} for why that precedence exists.
+     */
+    livemarkPolicy?: (annotation: Annotation<TPayload>) => boolean;
+    /**
+     * Whether the capture primitive leaves its transient mark in place after
+     * capturing an anchor. Comments retain it (the composer highlights the
+     * passage); corrections discard it.
+     *
+     * The discard is *not* part of the wrapping update. `AnnotationPlugin` wraps
+     * inside the command handler, then reads the anchor back and removes the
+     * mark on a `queueMicrotask` — the read cannot be inline, because a command
+     * handler runs inside an active Lexical update and the nested wrap is not
+     * observable until that update flushes. The guarantee is therefore "removed
+     * before the browser paints" (microtasks drain ahead of paint), not "removed
+     * in the same update". Anything that pushes the discard past a task boundary
+     * — an `await`, a `setTimeout`, a `requestAnimationFrame` — would let the
+     * mark flash visibly first.
+     */
+    retainMarkOnCreate?: boolean;
+}
+/** A host's full annotation configuration: kind name → its config. */
+export type AnnotationKindConfigs = Record<AnnotationKind, AnnotationKindConfig>;
+/**
+ * A resolved instruction to place one marker. Ported from Zusammen's
+ * `comment-thread.ts`; its `deriveMarkerTargets` is deliberately *not* ported —
+ * that function takes Zusammen's `Thread`/`Comment`, which are app-domain under
+ * ADR-075. The package accepts already-derived annotations instead.
+ */
+export interface MarkerTarget {
+    annotationId: string;
+    kind: AnnotationKind;
+    anchor: Anchor;
+    outcome: AnchorOutcome;
+    /**
+     * Carried through from the source annotation. The marker renderer sees only
+     * targets, so without this the per-annotation className/label overrides
+     * {@link AnnotationPresentation} promises would be silently unreachable.
+     */
+    presentation?: AnnotationPresentation;
+}
+/**
+ * Whether `outcome` gets a live in-document `MarkNode` at all. Only
+ * `unchanged`/`re-attached` do — `flagged`'s match is uncertain and `orphaned`
+ * has nothing left to point at, so both stay panel-only, never placed on text
+ * the resolver wasn't confident about.
+ */
+export declare function shouldPlaceLiveMark(outcome: AnchorOutcome): boolean;
+/**
+ * Derive marker targets from host-supplied annotations, applying each kind's
+ * live-mark policy. Annotations whose `kind` has no configuration are dropped;
+ * the caller is responsible for warning about them (the logger is injected at
+ * the React layer, and this module stays dependency-free).
+ *
+ * `markerStyle: 'none'` takes precedence over `livemarkPolicy` and yields no
+ * target at all. A target is not merely a styling instruction — it is what
+ * makes `AnnotationMarkPlacementPlugin` wrap the text in a real `MarkNode`,
+ * which reaches the DOM as a `<mark>` element. `AnnotationMarkerPlugin` skips
+ * decoration for `none`, so that element would carry no `annotation-mark-*`
+ * class, and `styles.css` neutralizes the UA's default yellow `<mark>`
+ * background only under those classes — leaving a persistent uncontrolled
+ * highlight, the exact opposite of what `none` promises. Gating here rather
+ * than at paint time keeps the promise structural instead of leaving it to a
+ * host remembering to pair `none` with `livemarkPolicy: () => false`.
+ */
+export declare function deriveMarkerTargets(annotations: readonly Annotation[], kinds: AnnotationKindConfigs): MarkerTarget[];
+/**
+ * The imperative bridge from a host to the live marks inside a mounted editor —
+ * set once the editor mounts, read by the host at delete-time and
+ * checkpoint-time. Ported from Zusammen's `comment-editor-handle.ts`.
+ */
+export interface AnnotationEditorHandle {
+    /** Removes every live mark wrapping `annotationId` (annotation deleted, or composer cancelled). */
+    removeMarksForAnnotation: (annotationId: string) => void;
+    /** The current live range of every marked passage, keyed by annotation id. */
+    collectLiveAnchorSnapshots: (markdownText: string) => Map<string, AnchorRange>;
+}

package/dist/annotations/types.js

@@ -0,0 +1,50 @@
+/**
+ * Whether `outcome` gets a live in-document `MarkNode` at all. Only
+ * `unchanged`/`re-attached` do — `flagged`'s match is uncertain and `orphaned`
+ * has nothing left to point at, so both stay panel-only, never placed on text
+ * the resolver wasn't confident about.
+ */
+export function shouldPlaceLiveMark(outcome) {
+    return outcome === 'unchanged' || outcome === 're-attached';
+}
+/**
+ * Derive marker targets from host-supplied annotations, applying each kind's
+ * live-mark policy. Annotations whose `kind` has no configuration are dropped;
+ * the caller is responsible for warning about them (the logger is injected at
+ * the React layer, and this module stays dependency-free).
+ *
+ * `markerStyle: 'none'` takes precedence over `livemarkPolicy` and yields no
+ * target at all. A target is not merely a styling instruction — it is what
+ * makes `AnnotationMarkPlacementPlugin` wrap the text in a real `MarkNode`,
+ * which reaches the DOM as a `<mark>` element. `AnnotationMarkerPlugin` skips
+ * decoration for `none`, so that element would carry no `annotation-mark-*`
+ * class, and `styles.css` neutralizes the UA's default yellow `<mark>`
+ * background only under those classes — leaving a persistent uncontrolled
+ * highlight, the exact opposite of what `none` promises. Gating here rather
+ * than at paint time keeps the promise structural instead of leaving it to a
+ * host remembering to pair `none` with `livemarkPolicy: () => false`.
+ */
+export function deriveMarkerTargets(annotations, kinds) {
+    const targets = [];
+    for (const annotation of annotations) {
+        const config = kinds[annotation.kind];
+        if (!config)
+            continue;
+        if (config.markerStyle === 'none')
+            continue;
+        const outcome = annotation.outcome ?? 'unchanged';
+        const placeLive = config.livemarkPolicy
+            ? config.livemarkPolicy(annotation)
+            : shouldPlaceLiveMark(outcome);
+        if (!placeLive)
+            continue;
+        targets.push({
+            annotationId: annotation.id,
+            kind: annotation.kind,
+            anchor: annotation.anchor,
+            outcome,
+            presentation: annotation.presentation,
+        });
+    }
+    return targets;
+}

package/dist/annotations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@liminis/editor/annotations` — the headless annotation surface (ADR-077).
+ *
+ * The sixth declared export subpath, added as a *considered* export under
+ * ADR-075's five-subpath rule. It exists because this surface has a profile no
+ * existing subpath has: it must be callable outside a rendered editor, so it
+ * is free of DOM, React and Lexical — but it is not pure-mdast either (the
+ * anchor schema imports `zod`), so it does not belong on `./markdown`, and it
+ * must not go on `./headless`, whose `mathjax-config` re-export drags ~1.9 MB
+ * of side-effectful imports.
+ *
+ * Everything reachable from here is safe to call from a main process, a worker,
+ * or a test with no DOM. The React plugins and the marker-placement code live
+ * on the root barrel alongside `<Editor>` instead.
+ */
+export { ANCHOR_SCHEMA, ANCHOR_RESOLUTION_SCHEMA, CONTEXT_WINDOW_CHARS, captureAnchor, } from './annotations/anchor-model.js';
+export type { Anchor, AnchorFields, AnchorRange, AnchorOutcome, AnchorResolution, } from './annotations/anchor-model.js';
+export { resolveAnchor, resolveAnchors, similarity, noopProposeSemanticRelocation, REATTACH_THRESHOLD, FLAG_THRESHOLD, } from './annotations/anchor-resolver.js';
+export type { ProposeSemanticRelocation, ResolveAnchorOptions, IdentifiedAnchor, AnchorResolutionResult, } from './annotations/anchor-resolver.js';
+export { parseBlocks, findEnclosingBlock, blockPlainText, sentenceChunks, } from './annotations/block-structure.js';
+export type { Block, BlockType, SentenceChunk } from './annotations/block-structure.js';
+export { locateInSpan } from './annotations/anchor-align.js';
+export type { SpanRange, LocateInSpanOptions } from './annotations/anchor-align.js';
+export { shouldPlaceLiveMark, deriveMarkerTargets } from './annotations/types.js';
+export type { Annotation, AnnotationKind, AnnotationKindConfig, AnnotationKindConfigs, AnnotationCreateAffordance, AnnotationMarkerStyle, AnnotationPresentation, AnnotationEditorHandle, MarkerTarget, } from './annotations/types.js';

package/dist/annotations.js

@@ -0,0 +1,27 @@
+/**
+ * `@liminis/editor/annotations` — the headless annotation surface (ADR-077).
+ *
+ * The sixth declared export subpath, added as a *considered* export under
+ * ADR-075's five-subpath rule. It exists because this surface has a profile no
+ * existing subpath has: it must be callable outside a rendered editor, so it
+ * is free of DOM, React and Lexical — but it is not pure-mdast either (the
+ * anchor schema imports `zod`), so it does not belong on `./markdown`, and it
+ * must not go on `./headless`, whose `mathjax-config` re-export drags ~1.9 MB
+ * of side-effectful imports.
+ *
+ * Everything reachable from here is safe to call from a main process, a worker,
+ * or a test with no DOM. The React plugins and the marker-placement code live
+ * on the root barrel alongside `<Editor>` instead.
+ */
+// The durable anchor model — capture, schemas, and the outcome vocabulary.
+export { ANCHOR_SCHEMA, ANCHOR_RESOLUTION_SCHEMA, CONTEXT_WINDOW_CHARS, captureAnchor, } from './annotations/anchor-model.js';
+// The sole fuzzy-matching module (FR-003). `resolveAnchors` is the batch entry
+// point hosts call; it is async because the relocation seam may be host-supplied.
+export { resolveAnchor, resolveAnchors, similarity, noopProposeSemanticRelocation, REATTACH_THRESHOLD, FLAG_THRESHOLD, } from './annotations/anchor-resolver.js';
+// Block structure — the structural context anchors are captured against.
+export { parseBlocks, findEnclosingBlock, blockPlainText, sentenceChunks, } from './annotations/block-structure.js';
+// Span alignment, used when mapping an anchor onto a live document offset span.
+export { locateInSpan } from './annotations/anchor-align.js';
+// The annotation primitive and its per-kind configuration — the sole difference
+// between the comment feature and the correction feature (SC-001).
+export { shouldPlaceLiveMark, deriveMarkerTargets } from './annotations/types.js';

package/dist/app/App.d.ts

@@ -0,0 +1,64 @@
+import { type MutableRefObject } from 'react';
+import type { SelectionContextMenuEvent } from './editor/SelectionContextMenuPlugin.js';
+import type { SweepFn } from './editor/AmbientCorrectionPlugin.js';
+import type { AnnotationCreateEvent } from './editor/AnnotationPlugin.js';
+import type { Annotation, AnnotationEditorHandle, AnnotationKindConfigs } from '../annotations/types.js';
+import type { WikiLinkPromotionMode } from './mapper/lexicalToMdast.js';
+export interface CursorState {
+    offset: number;
+    contextBefore: string;
+    contextAfter: string;
+}
+interface AppProps {
+    /** When false, the editor is read-only */
+    editable?: boolean;
+    /**
+     * Whether the editor takes focus shortly after mounting. Defaults to
+     * `false`; see `Editor`'s own prop for when to opt in.
+     */
+    autoFocus?: boolean;
+    /** Content to display - when provided, used instead of IPC */
+    content?: string;
+    /** Called when content changes */
+    onChange?: (content: string) => void;
+    /** Path to the file being edited (used for file-type-specific UI like .mdc) */
+    filePath?: string;
+    /** Resolve a workspace-relative file path to a data URL for display */
+    resolveLocalAsset?: (relativePath: string) => Promise<string | null>;
+    /**
+     * Whether an untitled relative link is promoted to wiki-link syntax on
+     * export. Defaults to `'promote'`, today's only behavior. Unlike
+     * `imagePathResolution`, this is a direct prop rather than sourced from IPC
+     * `SlashMDSettings` — `App` also supports a non-IPC "inline" mode (`content`/
+     * `onChange` props), where `settings` stays null forever, and a
+     * settings-only path would be unreachable there (liminis#951).
+     */
+    wikiLinkPromotion?: WikiLinkPromotionMode;
+    /** Called when user right-clicks a text selection and chooses a context menu action */
+    onSelectionContextMenu?: (event: SelectionContextMenuEvent) => void;
+    /** Called when a single-word substitution is detected after a debounce window. */
+    onSubstitutionDetected?: (oldTerm: string, newTerm: string) => void;
+    /** Ref populated with a sweep function by AmbientCorrectionPlugin when active. */
+    sweepRef?: MutableRefObject<SweepFn | null>;
+    /**
+     * Annotation kind configuration (ADR-077), forwarded to <Editor>. Absent
+     * means the annotation mechanism stays off entirely.
+     */
+    annotationKinds?: AnnotationKindConfigs;
+    annotations?: Annotation[];
+    activeAnnotationId?: string | null;
+    scrollToAnnotation?: {
+        id: string;
+        nonce: number;
+    } | null;
+    onCreateAnnotation?: (event: AnnotationCreateEvent) => void;
+    onActivateAnnotation?: (id: string) => void;
+    annotationEditorHandleRef?: MutableRefObject<AnnotationEditorHandle | null>;
+    annotationLogger?: {
+        warn: (message: string, ...args: unknown[]) => void;
+    };
+    /** Override className on the root div (default: "min-h-screen p-0"). */
+    className?: string;
+}
+export declare function App({ editable, autoFocus, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, className }: AppProps): import("react").JSX.Element;
+export {};

package/dist/app/App.js

@@ -0,0 +1,180 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState, useRef } from 'react';
+import { Editor } from './editor/index.js';
+import { useEditorHost } from '../host/context.js';
+import { useHostMessages } from '../host/messages.js';
+// Simple diff algorithm to find the changed region between two strings
+function computeMinimalEdits(oldText, newText) {
+    if (oldText === newText)
+        return [];
+    // Find common prefix
+    let prefixLen = 0;
+    const minLen = Math.min(oldText.length, newText.length);
+    while (prefixLen < minLen && oldText[prefixLen] === newText[prefixLen]) {
+        prefixLen++;
+    }
+    // Find common suffix (but don't overlap with prefix)
+    let suffixLen = 0;
+    while (suffixLen < minLen - prefixLen &&
+        oldText[oldText.length - 1 - suffixLen] === newText[newText.length - 1 - suffixLen]) {
+        suffixLen++;
+    }
+    // Calculate the changed region
+    const start = prefixLen;
+    const end = oldText.length - suffixLen;
+    const newTextContent = newText.slice(prefixLen, newText.length - suffixLen);
+    return [{
+            start,
+            end,
+            newText: newTextContent,
+        }];
+}
+export function App({ editable = true, autoFocus = false, content: propContent, onChange: propOnChange, filePath, resolveLocalAsset, wikiLinkPromotion, onSelectionContextMenu, onSubstitutionDetected, sweepRef, annotationKinds, annotations, activeAnnotationId, scrollToAnnotation, onCreateAnnotation, onActivateAnnotation, annotationEditorHandleRef, annotationLogger, className = 'min-h-screen p-0' }) {
+    const { bridge, logger } = useEditorHost();
+    const log = useMemo(() => logger('slashmd/App'), [logger]);
+    const { requestInit, applyTextEdits } = useHostMessages();
+    const [internalContent, setInternalContent] = useState(null);
+    const [settings, setSettings] = useState(null);
+    const [assetBaseUri, setAssetBaseUri] = useState(undefined);
+    const [ipcDocumentDirUri, setIpcDocumentDirUri] = useState(undefined);
+    // Derive documentDirUri from filePath when not provided via IPC (inline mode).
+    // This ensures relative image paths like "image.svg" resolve relative to the document's directory.
+    const documentDirUri = useMemo(() => {
+        if (ipcDocumentDirUri)
+            return ipcDocumentDirUri;
+        if (!filePath)
+            return undefined;
+        const lastSlash = filePath.lastIndexOf('/');
+        return lastSlash >= 0 ? filePath.slice(0, lastSlash + 1) : '';
+    }, [ipcDocumentDirUri, filePath]);
+    const [themeOverrides, setThemeOverrides] = useState(undefined);
+    const [error, setError] = useState(null);
+    const pendingAssetCallback = useRef(null);
+    // Track the last known document content for diff computation
+    const lastDocumentContent = useRef('');
+    // Cursor state - persists across content reloads
+    const cursorStateRef = useRef(null);
+    // Counter to trigger cursor restoration after content changes
+    const [contentVersion, setContentVersion] = useState(0);
+    // Use prop content if provided, otherwise use internal state
+    const content = propContent !== undefined ? propContent : internalContent;
+    // Track when editor-initiated changes happen to skip cursor restoration
+    const lastEditorChangeTime = useRef(0);
+    // Track prop content changes to update lastDocumentContent and trigger cursor restoration
+    // BUT only increment contentVersion for EXTERNAL changes (file switch, reload)
+    // NOT for changes that came from the editor itself (typing)
+    const prevPropContent = useRef(propContent);
+    useEffect(() => {
+        if (propContent !== undefined && propContent !== prevPropContent.current) {
+            const timeSinceEditorChange = Date.now() - lastEditorChangeTime.current;
+            const isEditorInitiated = timeSinceEditorChange < 500;
+            log.info('Content prop changed', {
+                chars: propContent.length,
+                isEditorInitiated,
+                timeSinceEditorChange
+            });
+            lastDocumentContent.current = propContent;
+            // Only increment contentVersion for external changes (triggers cursor restore)
+            // Skip for editor-initiated changes (would mess up cursor during typing)
+            if (!isEditorInitiated) {
+                setContentVersion((v) => v + 1);
+            }
+        }
+        prevPropContent.current = propContent;
+    }, [propContent, log]);
+    useEffect(() => {
+        log.info('Setting up message handler');
+        const removeHandler = bridge.addMessageHandler((message) => {
+            log.debug('Handling message', message.type);
+            switch (message.type) {
+                case 'DOC_INIT':
+                    // Only use IPC content if not controlled by prop
+                    if (propContent === undefined) {
+                        log.info('DOC_INIT', { chars: message.text?.length });
+                        lastDocumentContent.current = message.text;
+                        setInternalContent(message.text);
+                    }
+                    setSettings(message.settings);
+                    setAssetBaseUri(message.assetBaseUri);
+                    setIpcDocumentDirUri(message.documentDirUri);
+                    setThemeOverrides(message.themeOverrides);
+                    break;
+                case 'DOC_CHANGED':
+                    // Only use IPC content if not controlled by prop
+                    if (propContent === undefined) {
+                        log.debug('DOC_CHANGED', { chars: message.text?.length });
+                        // Skip if content matches what we already have (our own save echoing back)
+                        if (message.text === lastDocumentContent.current) {
+                            log.debug('DOC_CHANGED skipped - content unchanged');
+                            return;
+                        }
+                        log.info('DOC_CHANGED - content differs, will restore cursor', {
+                            cursorOffset: cursorStateRef.current?.offset,
+                        });
+                        lastDocumentContent.current = message.text;
+                        setInternalContent(message.text);
+                        // Increment version to signal Editor to restore cursor
+                        setContentVersion((v) => v + 1);
+                    }
+                    break;
+                case 'SETTINGS_CHANGED':
+                    setSettings(message.settings);
+                    setThemeOverrides(message.themeOverrides);
+                    break;
+                case 'ASSET_WRITTEN':
+                    if (pendingAssetCallback.current) {
+                        pendingAssetCallback.current(message.relPath);
+                        pendingAssetCallback.current = null;
+                    }
+                    break;
+                case 'ERROR':
+                    log.warn('ERROR', message.message);
+                    setError(message.message);
+                    setTimeout(() => setError(null), 5000);
+                    break;
+            }
+        });
+        // Only request init if not controlled by prop
+        if (propContent === undefined) {
+            requestInit();
+        }
+        return removeHandler;
+    }, [propContent, bridge, requestInit, log]);
+    // Apply theme overrides as CSS variables
+    useEffect(() => {
+        if (!themeOverrides)
+            return;
+        const root = document.documentElement;
+        for (const [property, value] of Object.entries(themeOverrides)) {
+            root.style.setProperty(property, value);
+        }
+    }, [themeOverrides]);
+    const handleChange = useCallback((markdown) => {
+        // Calculate diff and send minimal edits
+        const edits = computeMinimalEdits(lastDocumentContent.current, markdown);
+        if (edits.length > 0) {
+            // This can happen even without typing if the editor normalizes/serializes markdown
+            // (e.g., whitespace normalization). Logging helps verify what's being changed.
+            log.debug('onChange -> applyTextEdits', {
+                edits: edits.map((e) => ({ start: e.start, end: e.end, newTextLen: e.newText.length })),
+                beforeLen: lastDocumentContent.current.length,
+                afterLen: markdown.length,
+            });
+            lastDocumentContent.current = markdown;
+            applyTextEdits(edits, 'typing');
+            // Mark this as an editor-initiated change BEFORE calling propOnChange
+            // This prevents the prop change from triggering cursor restoration
+            lastEditorChangeTime.current = Date.now();
+            // Call prop onChange if provided
+            propOnChange?.(markdown);
+        }
+    }, [propOnChange, applyTextEdits, log]);
+    // Track cursor position whenever it changes
+    const handleCursorChange = useCallback((cursor) => {
+        cursorStateRef.current = cursor;
+    }, []);
+    if (content === null) {
+        return (_jsxs("div", { className: "flex items-center justify-center gap-3 min-h-screen text-[var(--vscode-foreground)] opacity-70", children: [_jsx("div", { className: "loading-spinner" }), _jsx("span", { children: "Loading document..." })] }));
+    }
+    return (_jsxs("div", { className: className, children: [error && (_jsx("div", { className: "fixed top-0 left-0 right-0 px-4 py-2 bg-red-500 text-white text-center z-[1000]", role: "alert", children: error })), _jsx(Editor, { initialContent: content, autoFocus: autoFocus, contentVersion: contentVersion, cursorToRestoreRef: cursorStateRef, onChange: handleChange, onCursorChange: handleCursorChange, assetBaseUri: assetBaseUri, documentDirUri: documentDirUri, imagePathResolution: settings?.imagePathResolution ?? 'document', wikiLinkPromotion: wikiLinkPromotion, resolveLocalAsset: resolveLocalAsset, editable: editable, filePath: filePath, onSelectionContextMenu: onSelectionContextMenu, onSubstitutionDetected: onSubstitutionDetected, sweepRef: sweepRef, annotationKinds: annotationKinds, annotations: annotations, activeAnnotationId: activeAnnotationId, scrollToAnnotation: scrollToAnnotation, onCreateAnnotation: onCreateAnnotation, onActivateAnnotation: onActivateAnnotation, annotationEditorHandleRef: annotationEditorHandleRef, annotationLogger: annotationLogger })] }));
+}

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

@@ -0,0 +1,18 @@
+export type SweepFn = (oldTerm: string, newTerm: string) => Promise<number>;
+interface AmbientCorrectionPluginProps {
+    onSubstitutionDetected: (oldTerm: string, newTerm: string) => void;
+    sweepRef?: React.MutableRefObject<SweepFn | null>;
+}
+/**
+ * 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 declare function AmbientCorrectionPlugin({ onSubstitutionDetected, sweepRef, }: AmbientCorrectionPluginProps): null;
+export {};