@voithos-labs/aragonite 0.10.1

package/dist/components/blocks/editable-leaf.js

@@ -0,0 +1,410 @@
+/**
+ * The editable-leaf seam a plugin block component builds on: a text-editing block surface with
+ * native caret/IME/undo/cross-block-selection parity, in one factory so a plugin never touches an
+ * editor context key. Two modes: `plain` commits per keystroke, `render-primary` reveals its
+ * source and commits on blur. Call synchronously during init. Contract: plugin-guide § The
+ * editable leaf.
+ */
+import { getContext } from 'svelte';
+import { createAttachmentKey } from 'svelte/attachments';
+import { EDITOR_POLICIES_KEY, EDITOR_SERVICES_KEY } from '../../editor-keys';
+import { asDomTextOffset } from '../../cursor/coordinate-spaces';
+import { setCursorOffset, getCursorOffset, getSelectionOffsets } from '../../cursor/content-offsets';
+import { handleSharedKeydown } from '../../selection/shared-keydown';
+import { createEditableSurface, createClipboardHandlers, consumePendingRestore } from './editable-surface';
+import { wireSurfaceContexts } from './surface-wiring.svelte';
+import { createContentOffsetBackend, anchorTrailingNewline } from './plain-text-backend';
+import { parkFocusOnEditorRoot } from '../../selection/native-bridge';
+import { resetForPointerDown } from '../../selection/cross-block/pointer';
+import { placeCaret } from '../../selection/caret-doors';
+import { createSourceReveal } from '../../cursor/reveal-source';
+import { traceRevealOpen, traceRevealFold } from '../../debug/interaction-trace';
+import { trimTrailingLineEnding, trailingLineEnding } from '../../core/lines';
+import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+import {} from '../../schema/commands';
+import {} from '../../schema/block-commands';
+import { owningPluginEditor } from '../../schema/plugin-install';
+import { reorderRunCommand } from '../../editor-actions/reorder-action';
+/**
+ * The node → metadata bridge (plus `commandHooks`) a minted block command resolves
+ * against on the leaf tier — the container factory's `buildContainerKindTarget` sibling.
+ * Every field reads through `deps`' thunks at dispatch, so a node swap or hook rebind is
+ * observed live; `pluginEditor` resolves by the kind's recorded owner.
+ */
+export function buildLeafCommandContext(deps, blockEdit, pluginEditor) {
+    return {
+        node: deps.getNode(),
+        updateMetadata: (patch) => void blockEdit.updateBlockMetadata(deps.getIndex(), patch),
+        hooks: deps.commandHooks?.(),
+        editor: owningPluginEditor(pluginEditor, deps.getNode().kind)
+    };
+}
+export function createEditableLeaf(deps) {
+    const mode = deps.mode ?? 'plain';
+    const singleLine = deps.singleLine ?? false;
+    if (mode === 'render-primary' && (!deps.isRevealed || !deps.setRevealed)) {
+        throw new Error('createEditableLeaf: render-primary mode requires isRevealed + setRevealed');
+    }
+    // Plain mode's source is always the editable view.
+    const isRevealed = mode === 'render-primary' ? deps.isRevealed : () => true;
+    const wiring = wireSurfaceContexts();
+    const { blockEdit, stickyColumn, edgeAffinity, selection, getDoc, getBlockElByPath, getEditorRoot, pluginEditor, events: editorEvents } = wiring.deps;
+    const { reorder } = getContext(EDITOR_SERVICES_KEY);
+    const { presentationMode: getPresentationModeCtx, theme: getThemeCtx, onPasteImage } = getContext(EDITOR_POLICIES_KEY);
+    const getPresentationMode = () => getPresentationModeCtx?.() ?? 'source';
+    const getTheme = () => getThemeCtx?.() ?? 'dark';
+    // Resolved by the kind's recorded owner, like the command context's `editor`.
+    const getOptions = () => owningPluginEditor(pluginEditor, deps.getNode().kind)?.options;
+    const isReading = () => getPresentationMode() === 'reading';
+    let composing = false;
+    let preEditOffset = 0;
+    let pendingCursor = null;
+    /** The bytes the open reveal was measured against; null while folded. */
+    let revealedBase = null;
+    const sourceText = () => trimTrailingLineEnding(deps.getNode().raw);
+    const { backend, getFocusOffset, getTextLen, readText } = createContentOffsetBackend(() => deps.getEl());
+    const editableSurface = createEditableSurface({
+        ...wiring.deps,
+        getEl: () => deps.getEl(),
+        getAmbientLength: () => 0,
+        // render-primary edits are ephemeral (one commit on blur); plain commits per keystroke.
+        isInputSuppressed: () => mode === 'render-primary',
+        backend,
+        getMyPath: deps.getPath,
+        getIndex: deps.getIndex,
+        getComposing: () => composing,
+        setComposing: (value) => {
+            composing = value;
+        },
+        getPreEditOffset: () => preEditOffset,
+        setPreEditOffset: (offset) => {
+            preEditOffset = offset;
+        },
+        // render-primary never restores a pending caret — focus has already left on
+        // commit, and a re-render must not yank it back.
+        setPendingCursor: (offset) => {
+            if (mode === 'plain')
+                pendingCursor = offset;
+        },
+        getPresentationMode,
+        getFocusOffset,
+        getTextLen,
+        readText,
+        commitInput: (text, preEdit, saved) => {
+            // !isReading: the leaf is the seam — even if a plain-mode component keeps
+            // its source editable in reading mode, nothing reaches the CST.
+            if (mode === 'plain' && !isReading()) {
+                void blockEdit.updateBlockContent(deps.getIndex(), text + trailingLineEnding(deps.getNode().raw), preEdit, saved);
+            }
+        }
+    });
+    const surface = editableSurface.surface;
+    const crossBlock = editableSurface.crossBlock;
+    // The caret core; the swap is the component's reveal flag. Blocks commit on blur via
+    // `commitReveal`, never the kernel's Escape-cancel `commit()`, so only `reveal()` is
+    // driven here. Plain mode's swap thunks are inert.
+    const revealKernel = createSourceReveal({
+        get container() {
+            return deps.getEl();
+        },
+        get sourceStart() {
+            return 0;
+        },
+        get sourceEnd() {
+            return sourceText().length;
+        },
+        get source() {
+            return sourceText();
+        },
+        getAmbientLength: () => 0,
+        isRevealed,
+        // The one point block source is shown — the kernel calls it only when not
+        // already revealed, so it fires once per open.
+        showSource: () => {
+            traceRevealOpen('leaf');
+            revealedBase = sourceText();
+            deps.setRevealed?.(true);
+        },
+        showRendered: () => {
+            revealedBase = null;
+            deps.setRevealed?.(false);
+        }
+    });
+    // ── Commit ─────────────────────────────────────────────────────────────────
+    // Returns the commit's own promise, so a caller that has to act on the committed bytes
+    // (a single-line Enter's split) can wait for the write to land.
+    function commitSource(edited) {
+        // One undo entry: the anchor is where the caret entered the edit; the post-edit
+        // caret follows the edit position.
+        return Promise.resolve(blockEdit.updateBlockContent(deps.getIndex(), edited + trailingLineEnding(deps.getNode().raw), preEditOffset, edited.length));
+    }
+    async function commitReveal() {
+        if (mode !== 'render-primary' || !isRevealed())
+            return;
+        // A cross-block selection sweeping through keeps the source revealed so its rects
+        // measure real text, and focusout is this fold's only entry — so the leaf stays in
+        // source view until the user focuses it and leaves again.
+        if (selection.isCrossBlock)
+            return;
+        // Only wired to onFocusOut — the block leaf folds on blur, never Escape-cancel.
+        traceRevealFold('blur');
+        const edited = deps.getEl()?.textContent ?? sourceText();
+        const base = revealedBase;
+        revealedBase = null;
+        deps.setRevealed(false); // reactive re-render of the edited source
+        // The fold writes back only what the reveal measured. An undo, or a `source` prop swap,
+        // can seat a DIFFERENT document at this index before focusout fires — the component is
+        // destroyed and the blur arrives on the way out, so these bytes belong to a block that is
+        // no longer here and writing them corrupts the one that is (#161).
+        if (base !== null && base !== sourceText())
+            return;
+        if (edited === sourceText())
+            return; // pure view toggle, nothing for the CST
+        await commitSource(edited);
+    }
+    // ── BlockComponent surface ─────────────────────────────────────────────────
+    function parkCaret(offset) {
+        if (mode === 'render-primary') {
+            // Reading mode: a rendered view has no source to reveal; focus is a no-op
+            // and block-level traversal passes over.
+            if (isReading())
+                return;
+            void revealKernel.reveal(offset);
+            return;
+        }
+        surface.parkCaret(offset);
+    }
+    const focus = placeCaret(selection, parkCaret);
+    // Sticky-column entry: mount the source, then land at the column nearest x
+    // on the first/last visual line — the code-block traversal contract.
+    function focusAtColumn(x, from) {
+        void (async () => {
+            if (!isRevealed()) {
+                if (isReading())
+                    return;
+                // Through the kernel like every other open, so this entry gets the same trace pair,
+                // length assert and reveal base; it seats a caret at 0, which the column re-seats.
+                await revealKernel.reveal();
+            }
+            if (!deps.getEl())
+                return;
+            surface.focusAtColumn(x, from);
+        })();
+    }
+    function runCommand(id) {
+        return reorderRunCommand(id, reorder, deps.getPath);
+    }
+    const getCommandContext = () => buildLeafCommandContext(deps, blockEdit, pluginEditor);
+    // ── View sync ──────────────────────────────────────────────────────────────
+    function syncSource() {
+        const text = sourceText();
+        const el = deps.getEl();
+        if (!el)
+            return;
+        const pending = pendingCursor;
+        pendingCursor = null;
+        if ((el.textContent ?? '') !== text) {
+            el.textContent = text;
+            anchorTrailingNewline(el);
+            // Restore only under a live caret — an external rewrite (undo, structural
+            // replace) must not steal focus.
+            consumePendingRestore(el, pending, (offset) => setCursorOffset(el, asDomTextOffset(offset)));
+        }
+    }
+    // ── Event handlers ─────────────────────────────────────────────────────────
+    // Splice `insert` over the source text node's [start, end) and reseat the caret. A
+    // DOM-text mutation keeps the offset walk exact where a native Enter/cut/paste would
+    // inject <div>/<br> that vanish from textContent.
+    function spliceSourceText(el, start, end, insert) {
+        const text = el.textContent ?? '';
+        el.textContent = text.slice(0, start) + insert + text.slice(end);
+        anchorTrailingNewline(el);
+        preEditOffset = start;
+        setCursorOffset(el, asDomTextOffset(start + insert.length));
+        if (mode === 'plain')
+            editableSurface.onInput();
+    }
+    // ── Clipboard ────────────────────────────────────────────────────────────
+    // The leaf's DOM-text space IS its raw, so copy falls to the seam's visible-selection
+    // default and cut/paste splice verbatim. No structural paste hook: the commit
+    // re-parses the whole raw, re-splitting only where the grammar demands. No reveal
+    // fold — the render-primary source folds on blur instead.
+    const clipboard = createClipboardHandlers({
+        stickyColumn,
+        edgeAffinity,
+        selection,
+        getDoc,
+        crossBlock,
+        isReadOnly: isReading,
+        caret: editableSurface.caret,
+        events: editorEvents,
+        onPasteImage,
+        cutTail: (e) => {
+            const el = deps.getEl();
+            if (!el)
+                return;
+            const sel = getSelectionOffsets(el);
+            if (!sel || sel.start === sel.end)
+                return;
+            e.clipboardData?.setData('text/plain', (el.textContent ?? '').slice(sel.start, sel.end));
+            spliceSourceText(el, sel.start, sel.end, '');
+        },
+        pasteTail: (pastedText) => {
+            const el = deps.getEl();
+            if (!el)
+                return;
+            const sel = getSelectionOffsets(el);
+            const start = sel ? sel.start : (getCursorOffset(el) ?? (el.textContent ?? '').length);
+            const end = sel ? sel.end : start;
+            spliceSourceText(el, start, end, pastedText);
+        }
+    });
+    /** Resolve a chord at this leaf's kind and report whether it was consumed. Both views spend
+     *  it: undo belongs to the block whatever half of the swap holds focus. */
+    const dispatchChord = (e) => wiring.dispatchChord(e, { kind: deps.getNode().kind, runCommand, getCommandContext });
+    async function handleKeydown(e) {
+        const el = deps.getEl();
+        if (composing || !el)
+            return;
+        preEditOffset = getCursorOffset(el) ?? 0;
+        if ((await handleSharedKeydown(e, editableSurface.sharedCtx)) || editableSurface.isDetached())
+            return;
+        if (dispatchChord(e))
+            return;
+        // Enter stays inside the leaf as a literal newline (multiline source); it never splits
+        // the block, and plain mode commits the insertion. A single-line leaf has nowhere to put
+        // that byte, so it spends the press on the document instead.
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            if (isReading())
+                return;
+            // Read before any fold: `setRevealed(false)` unmounts the element the offset lives in.
+            const offset = getCursorOffset(el) ?? (el.textContent ?? '').length;
+            if (singleLine) {
+                // Through the fold, not a bare commit: it is the one door deciding whether an open
+                // reveal's bytes may still be written, and the split reads `node.raw` after it.
+                await commitReveal();
+                await blockEdit.splitBlock(deps.getIndex(), offset);
+                return;
+            }
+            spliceSourceText(el, offset, offset, '\n');
+        }
+    }
+    function onPointerDown(e) {
+        void crossBlock.handlePointerDown(e);
+    }
+    // The rendered view and the source are different strings, so only the kind can map a point
+    // to a source offset: `caretTargetAtPoint` is that one declaration, and a kind naming none
+    // reveals at the source start. The host, not the component root, is what the hook is bound to.
+    function revealOffsetAt(e) {
+        const host = getBlockElByPath(deps.getPath())?.closest('[data-block-path]');
+        if (!(host instanceof HTMLElement))
+            return 0;
+        const descriptor = tryGetBlockKindDescriptor(deps.getNode().kind);
+        return descriptor?.caretTargetAtPoint?.(host, e.clientX, e.clientY)?.offset ?? 0;
+    }
+    function onRenderPointerDown(e) {
+        // Shift-click extends a selection; a plain click reveals. Reading mode: no reveal
+        // and no preventDefault, so native selection over the rendered view stays live.
+        if (e.shiftKey || isReading())
+            return;
+        e.preventDefault();
+        // The reveal lands a caret, so this owes the shared preamble. NOT through
+        // crossBlock.handlePointerDown: that hit-tests against the SOURCE text, which the
+        // rendered view is not.
+        resetForPointerDown(selection, stickyColumn, edgeAffinity, e.shiftKey);
+        void revealKernel.reveal(revealOffsetAt(e));
+    }
+    // The revealed source owns the press and has already spent the chord, so a spread the fold
+    // does not unmount must not re-run either on the way up.
+    const renderProps = {
+        onpointerdown: (e) => {
+            if (!isRevealed())
+                onRenderPointerDown(e);
+        },
+        onkeydown: (e) => {
+            if (!isRevealed())
+                void dispatchChord(e);
+        }
+    };
+    // ── Source surface bundle ────────────────────────────────────────────────────
+    const surfaceHandlers = {
+        tabindex: 0,
+        role: 'textbox',
+        spellcheck: 'false',
+        oninput: editableSurface.onInput,
+        onkeydown: handleKeydown,
+        oncopy: clipboard.onCopy,
+        oncut: clipboard.onCut,
+        onpaste: clipboard.onPaste,
+        onpointerdown: onPointerDown,
+        onfocusout: () => void commitReveal(),
+        oncompositionstart: editableSurface.onCompositionStart,
+        oncompositionend: editableSurface.onCompositionEnd
+    };
+    // Both modes mirror external raw changes (undo, structural replace) into the source —
+    // tracked, so it re-runs on raw change. A render-primary edit is ephemeral until blur, so
+    // nothing else moves the raw mid-edit and the mirror cannot clobber an in-flight one. No
+    // cleanup, so it never parks focus mid-edit.
+    const syncAttachment = () => {
+        syncSource();
+    };
+    // Park focus when the source unmounts. A separate, stable, untracked attachment, so a
+    // recompute of the spread never fires the park mid-edit.
+    const parkAttachment = (el) => () => parkFocusOnEditorRoot(el, getEditorRoot());
+    // The mode splits the rest of the view-lifecycle contract: render-primary's
+    // `contenteditable` is constant, since reveal never fires in reading mode.
+    const surfaceProps = mode === 'render-primary'
+        ? {
+            ...surfaceHandlers,
+            contenteditable: 'true',
+            [createAttachmentKey()]: syncAttachment,
+            [createAttachmentKey()]: parkAttachment
+        }
+        : {
+            ...surfaceHandlers,
+            get contenteditable() {
+                return isReading() ? 'false' : 'true';
+            },
+            [createAttachmentKey()]: syncAttachment,
+            [createAttachmentKey()]: parkAttachment
+        };
+    return {
+        get sourceText() {
+            return sourceText();
+        },
+        surfaceProps,
+        renderProps,
+        getPresentationMode,
+        getTheme,
+        getOptions,
+        focus,
+        parkCaret,
+        focusAtColumn,
+        getCursorOffset: () => (isRevealed() ? surface.getCursorOffset() : null),
+        getSelectedText: () => (isRevealed() ? surface.getSelectedText() : ''),
+        setSelection: (start, end) => {
+            if (isRevealed())
+                surface.setSelection(start, end);
+        },
+        measurePartialRects: (startOffset, endOffset) => {
+            if (isRevealed())
+                return surface.measurePartialRects(startOffset, endOffset);
+            // Folded render-primary leaf: no source text node to measure, so mirror the
+            // opaque single-unit container shim and cover the rendered block box for any
+            // non-empty range (SELECTION_END exceeds every real start, so to-end paints too).
+            if (endOffset <= startOffset)
+                return [];
+            const box = getBlockElByPath(deps.getPath());
+            return box ? [box.getBoundingClientRect()] : [];
+        },
+        runCommand,
+        insertMarkdown: clipboard.insertMarkdown,
+        reveal: (offset = 0) => {
+            if (mode !== 'render-primary')
+                return Promise.resolve(surface.focus(offset));
+            return isReading() ? Promise.resolve() : revealKernel.reveal(offset);
+        },
+        commitSource: (edited) => void commitSource(edited)
+    };
+}

package/dist/components/blocks/editable-surface.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Shared editable-surface plumbing for the core contenteditable blocks (TextEditableBlock,
+ * CodeBlock, TableCellBlock) and the `editable-leaf` seam: cross-block wiring, the
+ * SharedKeydownContext, the BlockComponent surface methods, the input/composition + clipboard
+ * skeletons. Each consumer supplies a CursorBackend for its own coordinate system plus the input
+ * commit; mutable block state crosses the seam as live thunks, never as snapshots.
+ */
+import type { BlockEditActions, FocusActions, HistoryActions } from '../../action-contracts';
+import { type StickyColumnDirection } from '../../block-component';
+import type { UserScrollport } from '../../cursor/scroll-ancestors';
+import type { BlockElLookup, DocumentGetter, PasteImageHook, PluginEditorLookup, LinkReferenceResolverRef, PresentationModeGetter } from '../../editor-keys';
+import { type EditorEvents } from '../../editor-events';
+import type { KeybindingOverrideMap } from '../../schema/keybinding-overrides';
+import type { CommandErrorSink, CrossBlockCommandRouter } from '../../schema/block-commands';
+import type { GrammarView } from '../../schema/block-openers';
+import type { PluginActivation } from '../../schema/plugin-activation';
+import type { UndoController } from '../../editor-actions/deps';
+import type { PasteCommitCoordinator } from '../../tree-operations/paste/paste-deps';
+import type { StickyColumnState } from '../../cursor/sticky-column';
+import type { EdgeAffinityState } from '../../cursor/edge-affinity';
+import type { SelectionState } from '../../selection/selection-state.svelte';
+import { type RawOffset } from '../../cursor/coordinate-spaces';
+import { type CrossBlockHandlers } from '../../selection/cross-block/dispatch';
+import type { SharedKeydownContext } from '../../selection/shared-keydown';
+/**
+ * Per-surface cursor I/O in raw-content coordinates (ambient marker excluded).
+ * `buildRange` maps a raw-offset span to a DOM Range for selection writes.
+ */
+export interface CursorBackend {
+    getRaw(): RawOffset | null;
+    setRaw(offset: RawOffset): void;
+    buildRange(start: RawOffset, end: RawOffset): Range | null;
+}
+/**
+ * Guarded pending-caret restore. Applies only while `el` still holds focus, so a blur
+ * between arming the restore and the render drops it instead of yanking the global
+ * selection back. Callers clear their pending field unconditionally regardless.
+ */
+export declare function consumePendingRestore<T>(el: HTMLElement | null, pending: T | null, apply: (value: T) => void): boolean;
+export interface EditableSurfaceDeps {
+    getEl: () => HTMLElement | null;
+    /** Ambient marker length in raw units — 0 for code/cell, prose marker width for text. */
+    getAmbientLength: () => number;
+    backend: CursorBackend;
+    /** True while an ephemeral edit (inline-math source reveal) owns the DOM: the block
+     *  commits on exit, so keyboard input and IME compositionend both skip the commit. */
+    isInputSuppressed?: () => boolean;
+    getMyPath: () => number[];
+    getIndex: () => number;
+    getComposing: () => boolean;
+    setComposing: (value: boolean) => void;
+    getPreEditOffset: () => number;
+    setPreEditOffset: (offset: number) => void;
+    setPendingCursor: (offset: number | null) => void;
+    selection: SelectionState;
+    getDoc: DocumentGetter;
+    getBlockElByPath: BlockElLookup;
+    focusActions: FocusActions;
+    getEditorRoot: () => HTMLElement | null;
+    /** What scrolls this editor — the root in self mode, the host's scroller (or the
+     *  window) in host mode; threaded to the cross-block drag-select autoscroll. */
+    getScrollHost: () => UserScrollport | null;
+    getEditorLifetime: () => AbortSignal | null;
+    stickyColumn: StickyColumnState;
+    edgeAffinity: EdgeAffinityState;
+    blockEdit: BlockEditActions;
+    controller: UndoController;
+    history: HistoryActions;
+    pluginEditor: PluginEditorLookup | undefined;
+    /** The effective presentation mode, threaded to the cross-block reading gate — a
+     *  sibling to `pluginEditor`, never smuggled through it. */
+    getPresentationMode: PresentationModeGetter | undefined;
+    /** The instance's link-reference resolver, forwarded to the cross-block join seam. */
+    linkRef: LinkReferenceResolverRef | undefined;
+    onCommandError: CommandErrorSink | undefined;
+    /** The arm a range command routes to; forwarded to the cross-block composer. */
+    crossBlockCommands: CrossBlockCommandRouter;
+    getKeybindingOverrides: () => KeybindingOverrideMap;
+    pasteCoordinator: PasteCommitCoordinator;
+    /** The instance's block grammar, forwarded to the cross-block join-paste reparse.
+     *  Required-nullable: a surface must answer, and `undefined` means the global one. */
+    grammar: GrammarView | undefined;
+    /** The plugins this instance activated, forwarded to the paste-transform pipeline. */
+    activePlugins: PluginActivation;
+    /** The instance event surface, forwarded to the cross-block tier's clipboard
+     *  error channel — the same `EditorServices.events` the clipboard seam takes. */
+    events: EditorEvents;
+    /** Selection focus endpoint in raw space — surfaces convert or door-mint their DOM read. */
+    getFocusOffset: () => RawOffset | null;
+    getTextLen: () => number;
+    /** Read the current DOM content as raw text for the input commit. */
+    readText: () => string;
+    /** Live mode's typing seat for a COMPOSITION: an IME inserts at the DOM caret and its
+     *  beforeinput is not cancelable, so the byte relocation a keystroke takes at keydown is
+     *  taken on this commit instead. Null keeps the read verbatim. */
+    relocateComposedText?: (after: string, composedAt: number) => {
+        raw: string;
+        caret: number;
+    } | null;
+    /**
+     * Commit the read text to the CST. Returns the caret offset to restore when the
+     * committed bytes differ from the DOM (a cell escaping a typed `|` to `\|`); void
+     * keeps the DOM caret.
+     */
+    commitInput: (text: string, preEditOffset: number, savedOffset: number) => number | void;
+    /** Extra input prelude before the shared body (text resets snap target + keystroke mark). */
+    inputPrelude?: () => void;
+}
+export interface EditableSurface {
+    crossBlock: CrossBlockHandlers;
+    sharedCtx: SharedKeydownContext;
+    surface: EditableSurfaceMethods;
+    caret: ClipboardCaretIO;
+    /**
+     * True while this surface's element is out of the document — a torn-down host, and equally a
+     * render-primary leaf whose source is folded. Svelte's delegated walk does not await a keydown
+     * handler, so a container above it (a list item's Tab) claims the press and unmounts the block
+     * while a step is suspended; every awaited step asks this before reading on.
+     */
+    isDetached(): boolean;
+    onInput: () => void;
+    onCompositionStart: () => void;
+    onCompositionEnd: () => void;
+}
+/**
+ * The caret door the clipboard seam borrows from its surface. `getEl` is a liveness
+ * test: a host import hook can outlive the block that started the paste.
+ */
+export interface ClipboardCaretIO {
+    getEl: () => HTMLElement | null;
+    getCursorOffset: () => number | null;
+    focus: (offset: number) => void;
+}
+/** The BlockComponent methods shared verbatim across every editable surface. */
+export interface EditableSurfaceMethods {
+    focus(offset: number): void;
+    /** Required here, optional on `BlockComponent`: an editable surface is what the
+     *  cross-block extend paths park into, so every one of them owes the door. */
+    parkCaret(offset: number): void;
+    focusAtColumn(x: number, from: StickyColumnDirection): void;
+    getCursorOffset(): number | null;
+    getSelectedText(): string;
+    setSelection(start: number, end: number): void;
+    measurePartialRects(startOffset: number, endOffset: number): DOMRect[];
+}
+export declare function createEditableSurface(deps: EditableSurfaceDeps): EditableSurface;
+/**
+ * What folding a live source reveal hands the mutation that triggered it. A fold that
+ * changes the block's KIND takes the structural path, whose completion is a promise —
+ * so a mutation seam waits on `settled`, not on a tick that happens to outlast it.
+ */
+export interface RevealFold {
+    /** Committed caret offset — where the folded edit left the caret. */
+    caret: number;
+    /** Resolves once the fold's write has landed and its render has flushed. */
+    settled: Promise<void>;
+}
+/**
+ * The ordered copy / cut / paste skeleton shared by the four editable surfaces, owning the arms
+ * that must stay in lockstep (reading gate, cross-block write, reveal fold, image arm) so no
+ * surface can skip or resequence one. Paste prevents before its first await, or native paste fires
+ * while the fold settles. Reads and writes go through the event's synchronous `clipboardData`;
+ * `navigator.clipboard` is permission-gated and unreliable in Tauri's wry webview.
+ */
+export interface ClipboardSurfaceDeps {
+    stickyColumn: StickyColumnState;
+    edgeAffinity: EdgeAffinityState;
+    selection: SelectionState;
+    getDoc: DocumentGetter;
+    crossBlock: CrossBlockHandlers;
+    /** Reading mode: copy/cut write the visible selection string, paste is inert. */
+    isReadOnly: () => boolean;
+    /** The surface's caret door, borrowed by the image arm to anchor its insertion. */
+    caret: ClipboardCaretIO;
+    /** The instance event surface — the image arm's only channel for a host hook that
+     *  rejects. Non-nullable so a surface cannot silently swallow a failed import. */
+    events: EditorEvents;
+    /** Host image-import hook from the policies context. Undefined leaves an
+     *  image-bearing paste on the text/plain path, exactly as before the hook. */
+    onPasteImage: PasteImageHook | undefined;
+    /** Fold a live inline-source reveal before a cut/paste mutates, so the mutation runs
+     *  against a CST consistent with the swapped DOM. Omit on a surface with no reveal. */
+    foldReveal?: () => RevealFold | null;
+    /** Pre-cross-block copy arm (selected-widget slice, intra-table rect). True when it
+     *  wrote the payload and the handler should stop; owns its own preventDefault. */
+    copyPreHook?: (e: ClipboardEvent) => boolean;
+    /** Pre-cross-block cut arm (selected-widget splice, intra-table rect cut). */
+    cutPreHook?: (e: ClipboardEvent) => boolean | Promise<boolean>;
+    /** The intra-block copy payload; owns its preventDefault. Omit to write the
+     *  visible selection string (code, leaf); text and the cell slice their raw. */
+    copyTail?: (e: ClipboardEvent) => void;
+    /** The intra-block cut: a synchronous clipboardData write, then the CST delete. */
+    cutTail: (e: ClipboardEvent) => void | Promise<void>;
+    /** The intra-block paste after normalize: the surface's splice/dispatch, handed
+     *  the normalized text and the reveal-fold landing caret. */
+    pasteTail: (pastedText: string, foldedCaret: number | null) => void | Promise<void>;
+}
+export interface ClipboardHandlers {
+    onCopy(e: ClipboardEvent): void;
+    onCut(e: ClipboardEvent): Promise<void>;
+    onPaste(e: ClipboardEvent): Promise<void>;
+    /**
+     * Insert `md` exactly as pasting it here would, minus the clipboard — the surface half of
+     * `EditorInstance.insertMarkdown`. True means the pipeline took the text, not that its
+     * commit has flushed; the synchronous declines are reading mode and an empty payload.
+     */
+    insertMarkdown(md: string): boolean;
+}
+export declare function createClipboardHandlers(deps: ClipboardSurfaceDeps): ClipboardHandlers;