@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/blocks/text/text-render.js

@@ -1,15 +1,15 @@
 /**
- * DOM-build steps for TextEditableBlock's render $effect. The component owns the
- * effect and the `pendingCursorOffset` restore (those writes touch $state); this
- * factory owns the imperative inline-DOM construction and carries a live caret across
- * a decoration-driven rebuild the edit path's pending restore doesn't cover.
+ * DOM-building steps for TextEditableBlock's render effect. The component owns the effect
+ * and the `pendingCursorOffset` restore, since those writes touch `$state`; this factory
+ * builds the inline DOM and keeps a live caret across a rebuild a decoration caused, which
+ * the edit path's own restore does not cover.
  */
 import { hidesMarkers } from '../../../presentation-mode';
 import { buildAmbientSpan } from '../../../ambient/ambient-dom';
-import { computeInlineContent, contentLengthOf, getContentRange, isProseKind } from '../../../core/inline';
-import { renderInlineNodes } from '../../../core/inline-render';
-import { CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome } from '../../../cursor/widget-offset';
-import { captureFocusedCaretWalkOffset, restoreCaretAtWalkOffset } from '../../../cursor/focused-caret';
+import { computeInlineContent, contentLengthOf, getContentRange, isProseKind, structuralSuffix, sameLineSuffix } from '../../../core/inline';
+import { PENDING_BREAK_ANCHOR, renderInlineNodes } from '../../../core/inline-render';
+import { BLOCK_PREFIX_ATTR, BLOCK_SUFFIX_ATTR, CONTENT_EMPTY_ATTR, createCaretAnchor, holdsOnlyMarkerChrome, placeCaretAtRaw } from '../../../cursor/widget-offset';
+import { captureFocusedCaret } from '../../../cursor/focused-caret';
 import { applyIslandDecorations, islandRenderKeyPart } from '../../../decorations/island-dom';
 import { mountDecorationWidget } from '../../../decorations/widget-dom';
 import { devWarn } from '../../../dev-warn';
@@ -28,8 +28,8 @@ const RENDER_KEY_SEGMENTS = [
     'kind',
     'islands'
 ];
-/** Which renderKey segment(s) differ — the interaction trace's rebuild cause. Pure over
- *  the key format, so the recorder never learns the NUL layout. */
+/** Which parts of the render key differ, which the interaction trace reports as the cause of
+ *  a rebuild. Pure over the key format, so the recorder never learns the NUL layout. */
 export function renderKeySegmentDiff(prev, next) {
     const a = prev.split('\0');
     const b = next.split('\0');
@@ -44,11 +44,11 @@ export function createTextRender(deps) {
     let lastRenderedKey = '';
     const widgetPool = createSvelteWidgetPool({
         reportError: deps.reportRenderError,
-        getPresentationMode: () => deps.presentationMode,
         getTheme: deps.getTheme,
         getDocument: deps.getDocument,
         getContentVersion: deps.getContentVersion,
-        navigateTo: deps.navigateTo
+        navigateTo: deps.navigateTo,
+        reading: deps.reading
     });
     let islandDestroys = [];
     function destroyIslands() {
@@ -59,13 +59,18 @@ export function createTextRender(deps) {
     function buildPortalWidget(node, raw) {
         return widgetPool.acquire(node.kind, node, raw.slice(node.start, node.end));
     }
-    // The dimmed marker portion of the raw — whatever the kind's descriptor excludes
-    // from the content range. Kinds that declare none yield ''.
+    // The dimmed marker part of the raw ahead of the content range. Kinds that declare none give ''.
     function getBlockMarkerPrefix() {
         const node = deps.node;
         const range = getContentRange(node);
         return node.raw.slice(0, range.start);
     }
+    function markerSpan(text) {
+        const span = document.createElement('span');
+        span.className = 'md-marker';
+        span.textContent = text;
+        return span;
+    }
     // The render path computes inline content on the pure path, never the caching
     // accessor: the cache is non-reactive and would skip render-relevant changes (G4.2).
     function buildInlineDOM(content) {
@@ -76,9 +81,8 @@ export function createTextRender(deps) {
         }
         const blockOwnPrefix = getBlockMarkerPrefix();
         if (blockOwnPrefix) {
-            const span = document.createElement('span');
-            span.className = 'md-marker';
-            span.textContent = blockOwnPrefix;
+            const span = markerSpan(blockOwnPrefix);
+            span.setAttribute(BLOCK_PREFIX_ATTR, '');
             frag.appendChild(span);
         }
         const descriptor = getBlockKindDescriptor(node.kind);
@@ -89,63 +93,82 @@ export function createTextRender(deps) {
             imageLoadPolicy: deps.imageLoadPolicy,
             buildImageWidget: (imgNode, imgRaw, imgOpts) => buildImageWidget(imgNode, imgRaw, { ...imgOpts, brokenUrlCache: deps.brokenUrlCache }),
             buildPortalWidget,
-            // Attribute-only stamps for the construct-reveal trigger, mode-gated so the
-            // other modes' DOM stays byte-identical.
-            tagConstructMarkers: deps.presentationMode === 'preview-inline',
-            pendingBreakSeat: hidesMarkers(deps.presentationMode)
+            grammar: deps.reading.grammar,
+            // Data attributes only, for the code that shows construct markers; set in this
+            // mode alone so the other modes' DOM stays byte-identical.
+            tagConstructMarkers: deps.reading.mode() === 'preview-inline',
+            pendingBreakAt: hidesMarkers(deps.reading.mode()) ? contentLengthOf(node) : undefined
         }));
+        // The bytes past the content (a setext underline, a heading's closing run) are block markers
+        // too, so they are drawn and hidden along with the prefix.
+        const suffix = structuralSuffix(node);
+        if (suffix) {
+            const span = markerSpan(suffix);
+            span.setAttribute(BLOCK_SUFFIX_ATTR, blockOwnPrefix ? 'after-prefix' : '');
+            // A closing run on the text's own line stays there when a pending break draws a new one.
+            const onTextLine = sameLineSuffix(node) === suffix;
+            frag.insertBefore(span, onTextLine ? frag.querySelector(PENDING_BREAK_ANCHOR) : null);
+        }
         return frag;
     }
     // No inline pass runs here, so the remainder is a verbatim text node.
     function buildMarkerPrefixDOM(marker, rest) {
         const frag = document.createDocumentFragment();
-        const span = document.createElement('span');
-        span.className = 'md-marker';
-        span.textContent = marker;
-        frag.appendChild(span);
+        frag.appendChild(markerSpan(marker));
         frag.appendChild(document.createTextNode(rest));
         return frag;
     }
-    // A `<br>` inside an island belongs to the widget, so it must not satisfy the empty
-    // block's caret anchor.
+    // A `<br>` inside a decoration widget belongs to that widget, so it cannot serve as the
+    // empty block's caret anchor.
     function ensureBr(el) {
-        if (deps.getDisplayText() !== '')
+        const display = deps.getDisplayText();
+        if (display.endsWith('\n'))
+            return anchorEmptyLastLine(el);
+        if (display !== '')
             return;
         const hasAnchorBr = [...el.querySelectorAll('br')].some((br) => !br.closest('[data-decoration-island]'));
         if (!hasAnchorBr)
             el.appendChild(document.createElement('br'));
     }
+    // Chromium paints no caret on the empty line after a trailing line break, so the next key
+    // would land before the break; the anchor adds no text, so offsets are untouched.
+    function anchorEmptyLastLine(el) {
+        const last = el.lastChild;
+        if (last instanceof HTMLElement && last.tagName === 'BR' && 'caretAnchor' in last.dataset) {
+            return;
+        }
+        el.appendChild(createCaretAnchor());
+    }
     function captureCaretIfFocused(el) {
-        const walk = captureFocusedCaretWalkOffset(el);
-        if (walk !== null)
-            traceCursorCapture(walk);
-        return walk;
+        const raw = captureFocusedCaret(el);
+        if (raw !== null)
+            traceCursorCapture(raw);
+        return raw;
     }
-    function restoreCaret(el, walkOffset) {
-        restoreCaretAtWalkOffset(el, walkOffset);
-        traceCursorRestore(walkOffset);
+    function restoreCaret(el, raw) {
+        placeCaretAtRaw(el, raw, { clamp: 'exact' });
+        traceCursorRestore(raw);
     }
     function render(opts) {
         const el = deps.el;
         if (!el)
             return;
         const node = deps.node;
-        // Gating both the signature dependency and the resolver read on the bracket keeps
-        // one LRD edit from re-rendering the whole document.
+        // Checking for a bracket before reading the signature or the resolver keeps one edit
+        // to a link-reference definition from re-rendering the whole document.
         const hasRef = node.raw.includes('[');
-        const refKeyPart = hasRef ? deps.linkStamp : '';
-        // The built widget bakes in imageLoadPolicy, so the key tracks it — but only for
-        // blocks with an image, which keeps image-free blocks off the policy dependency.
+        const refKeyPart = hasRef ? String(deps.reading.resolverEpoch) : '';
+        // The built widget bakes in `imageLoadPolicy`, so the key tracks it, but only for
+        // blocks with an image, which keeps image-free blocks off that dependency.
         const hasImg = node.raw.includes('![');
         const imgKeyPart = hasImg ? deps.imageLoadPolicy : '';
-        // Unconditional, unlike the ref/img gating: a mode flip re-renders every mounted
-        // block. '' in source keeps the default key byte-identical but for one NUL.
-        const mode = deps.presentationMode;
+        // Always included, unlike the reference and image parts: a mode change re-renders
+        // every mounted block. '' in source mode keeps the default key byte-identical.
+        const mode = deps.reading.mode();
         const modeKeyPart = mode === 'source' ? '' : mode;
         const islands = deps.islands;
-        // The kind is a render input, not just a branch selector: two prose kinds can share
-        // a raw when the registry gains an opener for bytes already in the document, and
-        // the memo would then early-return onto the previous kind's DOM.
+        // The kind is part of the key: two prose kinds can share a raw once the registry gains an
+        // opener for bytes already in the document.
         const renderKey = `${deps.ambientPrefixText}\0${node.raw}\0${refKeyPart}\0${imgKeyPart}\0${modeKeyPart}\0${node.kind}${islandRenderKeyPart(islands)}`;
         const forceRebuild = opts?.forceRebuild ?? false;
         const carryCaret = opts?.carryCaret ?? true;
@@ -153,34 +176,33 @@ export function createTextRender(deps) {
         if (isProseKind(node.kind)) {
             if (renderKey === lastRenderedKey && !forceRebuild)
                 return;
-            // Detail assembly (the segment diff) allocates, so it stays behind the gate.
+            // Working out which parts differ allocates, so it stays behind the trace check.
             if (isInteractionTraceEnabled())
                 traceRebuild(renderKeySegmentDiff(lastRenderedKey, renderKey), forceRebuild);
-            const content = computeInlineContent(node, hasRef ? deps.linkResolver : undefined);
-            // Edit-path rebuilds skip the capture/restore pair: the SFC's pending restore
-            // overwrites the selection right after, so the walk would be dead work.
-            const caretWalkOffset = carryCaret ? captureCaretIfFocused(el) : null;
+            const content = computeInlineContent(node, hasRef ? deps.reading.resolver : undefined, deps.reading.grammar);
+            // Rebuilds from the edit path skip the capture-and-restore pair: the component's
+            // pending restore overwrites the selection right after, so it would be wasted.
+            const carried = carryCaret ? captureCaretIfFocused(el) : null;
             // Bracketing the rebuild pools portal widgets: the sweep destroys only those the
-            // previous DOM held and this build didn't re-acquire. Island widgets are unpooled.
+            // previous DOM held and this build did not reuse. Decoration widgets are not pooled.
             widgetPool.beginPass();
             destroyIslands();
             el.replaceChildren(buildInlineDOM(content));
             islandDestroys = applyIslandDecorations(el, node.raw, islands, {
                 contentLength: contentLengthOf(node),
-                ambientLength: deps.ambientPrefixText.length,
                 mountWidget: (spec, dec) => mountDecorationWidget(spec, dec, deps.reportRenderError),
-                onSkipped: (dec, reason) => devWarn('decorations', `island skipped: ${reason}`, dec)
+                onSkipped: (dec, reason) => devWarn('decorations', `decoration skipped: ${reason}`, dec)
             });
             if (islands.length > 0) {
                 recordIslandRebuild();
                 traceIslandsApplied(islands.length);
             }
             widgetPool.sweep();
-            carriedCaret = caretWalkOffset;
+            carriedCaret = carried;
         }
         else {
-            // An empty pass sweeps any widget or island stranded by an in-place
-            // prose→non-prose kind change, which reuses this same component instance.
+            // An empty pass clears any widget stranded by a prose-to-non-prose kind change in
+            // place, which reuses this same component instance.
             widgetPool.beginPass();
             destroyIslands();
             widgetPool.sweep();
@@ -197,12 +219,11 @@ export function createTextRender(deps) {
                 el.textContent = display;
             }
         }
-        // Unconditional: after this pass the DOM reflects renderKey even where an arm
-        // skipped its write, and a key frozen by a skipped write would let a later render
-        // early-return onto stale DOM.
+        // Always set, even where a branch skipped its write: a stale key would let a later render
+        // return early onto outdated DOM.
         lastRenderedKey = renderKey;
         ensureBr(el);
-        // The stamp decides which spans the walk can land in, so it precedes the caret restore.
+        // This attribute decides which spans the caret can land in, so it is set first.
         el.toggleAttribute(CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome(el));
         if (carriedCaret !== null)
             restoreCaret(el, carriedCaret);

package/dist/components/blocks/text/widget-adjacency.d.ts

@@ -4,6 +4,7 @@
  * an offset has only whitespace to one side.
  */
 import type { AnyInlineKind, InlineNode } from '../../../core/nodes';
+import type { GrammarView } from '../../../schema/block-openers';
 export interface WidgetRange {
     start: number;
     end: number;
@@ -13,18 +14,17 @@ export interface WidgetAtCursor extends WidgetRange {
     kind: AnyInlineKind;
 }
 export type CaretDirection = 'forward' | 'backward';
-/** The live widget the caret sits against, or null. At a boundary two widgets share
- *  (A.end === B.start), `direction` breaks the tie: forward enters B's leading edge,
- *  backward A's trailing edge. Elsewhere only one match exists and it is inert. */
-export declare function widgetAtCursor(offset: number | null, inlineContent: ReadonlyArray<InlineNode> | undefined, raw: string, direction?: CaretDirection): WidgetAtCursor | null;
-export declare function findWidgetNodeByStart(sourceStart: number, inlineContent: ReadonlyArray<InlineNode> | undefined, raw: string): WidgetRange | null;
+/** The live widget the caret sits against, or null. At a boundary two widgets share,
+ *  `direction` breaks the tie: forward takes the second widget, backward the first. */
+export declare function widgetAtCursor(offset: number | null, inlineContent: ReadonlyArray<InlineNode> | undefined, raw: string, direction: CaretDirection | undefined, grammar: GrammarView): WidgetAtCursor | null;
+export declare function findWidgetNodeByStart(sourceStart: number, inlineContent: ReadonlyArray<InlineNode> | undefined, raw: string, grammar: GrammarView): WidgetRange | null;
 /** First widget reachable from the leading edge, skipping blank text; null once any
  *  non-blank, non-widget inline intervenes. */
-export declare function findFirstEdgeWidget(inlines: ReadonlyArray<InlineNode>, raw: string): InlineNode | null;
+export declare function findFirstEdgeWidget(inlines: ReadonlyArray<InlineNode>, raw: string, grammar: GrammarView): InlineNode | null;
 /** Trailing-edge counterpart of `findFirstEdgeWidget`. */
-export declare function findLastEdgeWidget(inlines: ReadonlyArray<InlineNode>, raw: string): InlineNode | null;
+export declare function findLastEdgeWidget(inlines: ReadonlyArray<InlineNode>, raw: string, grammar: GrammarView): InlineNode | null;
 export declare function rawHasNoTextBefore(raw: string, offset: number): boolean;
 export declare function rawHasNoTextAfter(raw: string, offset: number): boolean;
-/** The live inline-widget island whose source starts at `start`, or null. The one home
- *  for this selector — a typo'd copy would fail silently as a null querySelector. */
+/** The inline-widget element whose source starts at `start`, or null. The only place this
+ *  selector is written: a mistyped copy would fail silently as a null `querySelector`. */
 export declare function widgetElByStart(el: HTMLElement, start: number): HTMLElement | null;

package/dist/components/blocks/text/widget-adjacency.js

@@ -3,17 +3,17 @@
  * live widget a caret offset touches, the leading/trailing edge widgets, and whether
  * an offset has only whitespace to one side.
  */
+import { isBlankText } from '../../../core/lines';
 import { isInlineWidget, flattenInlineWidgets } from '../../../core/inline/inline-widgets';
-/** The live widget the caret sits against, or null. At a boundary two widgets share
- *  (A.end === B.start), `direction` breaks the tie: forward enters B's leading edge,
- *  backward A's trailing edge. Elsewhere only one match exists and it is inert. */
-export function widgetAtCursor(offset, inlineContent, raw, direction = 'backward') {
+/** The live widget the caret sits against, or null. At a boundary two widgets share,
+ *  `direction` breaks the tie: forward takes the second widget, backward the first. */
+export function widgetAtCursor(offset, inlineContent, raw, direction = 'backward', grammar) {
     if (offset === null)
         return null;
     let leadingMatch = null;
     let trailingMatch = null;
     // Recurse so a widget nested inside a link (`[![alt][ref]][repo]`) is seen.
-    for (const inline of flattenInlineWidgets(inlineContent ?? [], raw)) {
+    for (const inline of flattenInlineWidgets(inlineContent ?? [], raw, grammar)) {
         if (offset === inline.start && !leadingMatch)
             leadingMatch = { start: inline.start, end: inline.end, atRight: false, kind: inline.kind };
         if (offset === inline.end && !trailingMatch)
@@ -23,8 +23,8 @@ export function widgetAtCursor(offset, inlineContent, raw, direction = 'backward
         return leadingMatch ?? trailingMatch;
     return trailingMatch ?? leadingMatch;
 }
-export function findWidgetNodeByStart(sourceStart, inlineContent, raw) {
-    for (const inline of flattenInlineWidgets(inlineContent ?? [], raw)) {
+export function findWidgetNodeByStart(sourceStart, inlineContent, raw, grammar) {
+    for (const inline of flattenInlineWidgets(inlineContent ?? [], raw, grammar)) {
         if (inline.start === sourceStart) {
             return { start: inline.start, end: inline.end };
         }
@@ -33,36 +33,36 @@ export function findWidgetNodeByStart(sourceStart, inlineContent, raw) {
 }
 /** First widget reachable from the leading edge, skipping blank text; null once any
  *  non-blank, non-widget inline intervenes. */
-export function findFirstEdgeWidget(inlines, raw) {
+export function findFirstEdgeWidget(inlines, raw, grammar) {
     for (const inline of inlines) {
-        if (isInlineWidget(inline, raw))
+        if (isInlineWidget(inline, raw, grammar))
             return inline;
-        if (inline.kind === 'text' && (inline.text ?? '').trim() === '')
+        if (inline.kind === 'text' && isBlankText(inline.text ?? ''))
             continue;
         return null;
     }
     return null;
 }
 /** Trailing-edge counterpart of `findFirstEdgeWidget`. */
-export function findLastEdgeWidget(inlines, raw) {
+export function findLastEdgeWidget(inlines, raw, grammar) {
     for (let i = inlines.length - 1; i >= 0; i--) {
         const inline = inlines[i];
-        if (isInlineWidget(inline, raw))
+        if (isInlineWidget(inline, raw, grammar))
             return inline;
-        if (inline.kind === 'text' && (inline.text ?? '').trim() === '')
+        if (inline.kind === 'text' && isBlankText(inline.text ?? ''))
             continue;
         return null;
     }
     return null;
 }
 export function rawHasNoTextBefore(raw, offset) {
-    return raw.slice(0, offset).trim() === '';
+    return isBlankText(raw.slice(0, offset));
 }
 export function rawHasNoTextAfter(raw, offset) {
-    return raw.slice(offset).trim() === '';
+    return isBlankText(raw.slice(offset));
 }
-/** The live inline-widget island whose source starts at `start`, or null. The one home
- *  for this selector — a typo'd copy would fail silently as a null querySelector. */
+/** The inline-widget element whose source starts at `start`, or null. The only place this
+ *  selector is written: a mistyped copy would fail silently as a null `querySelector`. */
 export function widgetElByStart(el, start) {
     return el.querySelector(`[data-inline-widget][data-source-start="${start}"]`);
 }

package/dist/components/blocks/text/widget-interaction.d.ts

@@ -1,51 +1,57 @@
 /**
- * Inline-widget interaction for TextEditableBlock: the offset math and the handler
- * bodies that branch off keydown/click. Each keydown sub-handler returns whether it
- * consumed the event, so the component can interleave them with the shared pipeline.
+ * Inline-widget interaction for the prose editable elements (the text block and the table cell):
+ * selecting a widget, showing its source, and the keydown and click handlers around both. Each
+ * keydown handler returns whether it consumed the event, so the component can interleave them
+ * with the shared pipeline.
  */
 import type { BlockEditActions, FocusActions } from '../../../action-contracts';
 import type { AnyInlineKind } from '../../../core/nodes';
 import type { NodeView } from '../../../core/node-views';
-import type { PresentationMode } from '../../../presentation-mode';
-import type { LinkReferenceResolverRef } from '../../../editor-keys';
 import type { WidgetSelectionState } from '../../image/widget-selection-state.svelte';
-import type { AmbientCursorIO } from '../../../ambient/ambient-cursor';
+import type { SurfaceBackend } from '../../../cursor/surface-backend';
+import { type LineEnding } from '../../../core/lines';
 import type { RevealFold } from '../editable-surface';
+import type { StoredAs } from '../../../schema/stored-as';
+import type { Reading } from '../../../schema/reading';
+import type { WriteMode } from '../../../schema/block-kind-descriptor';
 export interface WidgetInteractionDeps {
     get node(): NodeView;
     get index(): number;
+    /** The document's line ending, which a commit takes where the block has none of its own. */
+    getLineEnding: () => LineEnding;
     get myPath(): number[];
     getEl: () => HTMLElement | null;
-    getAmbientLength: () => number;
     getEditorContentWidth: () => number;
-    cursor: AmbientCursorIO;
+    cursor: SurfaceBackend;
     widgetSelection: WidgetSelectionState;
     blockEdit: BlockEditActions;
     focusActions: FocusActions;
     setSnapTarget: (offset: number | null) => void;
-    /** Park a caret for the post-render restore. `writtenText` is the text that offset
-     *  addresses: a kind whose write sink rewrites bytes moves the offset, and only that
-     *  text can map it. */
-    setPendingCursor: (offset: number | null, writtenText?: string) => void;
-    /** The block's live DOM as raw text, read on reveal commit to pick up the ephemeral
-     *  source edit that never went through the CST. */
+    /** Remember a caret offset, counted in the stored bytes, for the restore after the next render. */
+    setPendingCursor: (offset: number | null) => void;
+    /** The block's live DOM as raw text, read when a shown source is committed, to pick up
+     *  the temporary edit that never went through the CST. */
     readRawText: () => string;
-    /** Mirrors reveal-active into the component, so `onInput` and IME compositionend
-     *  suppress the per-keystroke CST commit while source is shown. */
+    /** Tells the component a source is showing, so `onInput` and IME `compositionend`
+     *  skip the per-keystroke CST commit while it is. */
     setRevealing: (value: boolean) => void;
-    /** Folding a revealed source mid-selection would strand an endpoint anchored in it. */
+    /** Hiding a shown source mid-selection would strand a selection endpoint anchored in it. */
     isCrossBlock: () => boolean;
-    /** Effective mode; reading gates reveal-open and the widget edit arms. Optional so
-     *  bare harnesses read as 'source'. */
-    getPresentationMode?: () => PresentationMode;
-    get linkRef(): LinkReferenceResolverRef | undefined;
+    /** The grammar the widgets were rendered with, and the presentation mode: reading mode shows
+     *  no source and edits no widget. */
+    get reading(): Reading;
+    /** Where the block's bytes are stored, read when a selected widget is replaced. */
+    storedAs: () => StoredAs;
 }
 /** The click a widget gesture reads off: the same event the widget's own handler sees. */
 export interface WidgetPress {
-    /** Ctrl/Cmd at the CLICK: with it, a widget claiming the activation click keeps the gesture. */
+    /** Ctrl or Cmd held at the click: with it, a widget that takes the activation click keeps it. */
     modified?: boolean;
-    /** `MouseEvent.detail`; two or more is a double-click, which takes the token it just revealed. */
+    /** `MouseEvent.detail`; two or more is a double-click, which selects the token it just opened. */
     clickCount?: number;
+    /** The pointer travelled between press and release, so the gesture was a drag. Showing a
+     *  widget's source there would unmount the widget the drag just painted a range across. */
+    moved?: boolean;
 }
 export interface WidgetInteraction {
     /** Block holds only image/blank inline content, so vertical arrow traversal skips
@@ -54,40 +60,58 @@ export interface WidgetInteraction {
     /** Keydown while a widget is selected. Every key is consumed in that state, so a
      *  true return must not fall through to the shared pipeline. */
     handleSelectedWidgetKeydown(e: KeyboardEvent): Promise<boolean>;
-    /** Shift+Arrow into a widget; extends the native selection to the far boundary. */
+    /** Shift+Arrow into a widget; extends the browser selection to the far boundary. */
     handleShiftArrowIntoWidget(e: KeyboardEvent): boolean;
-    /** Enter a widget at a caret edge — the reveal-vs-select policy split. The caret-edge
-     *  dispatch classifies the edge and calls this. */
+    /** Enter a widget at a caret edge: show its source or select it, as the kind's policy
+     *  says. The caret-edge dispatch decides which edge and calls this. */
     enterWidget(widget: {
         start: number;
         end: number;
         kind: AnyInlineKind;
     }, fromTrailingEdge: boolean): void;
-    /** Cross-block edge landing: a reveal-capable widget at the near edge opens its
-     *  source, any other is selected. Returns whether an edge widget was entered. */
+    /** Arriving from another block: a widget at the near edge that can show its source
+     *  opens it, any other is selected. Returns whether an edge widget was entered. */
     enterEdgeWidget(side: 'start' | 'end'): boolean;
-    /** Snap a click that landed outside any text node to the nearest widget edge, or open a
-     *  reveal-source widget it hit. */
+    /** Move a click that landed outside any text node to the nearest widget edge, or open the
+     *  source of a widget it hit. */
     snapClickToWidgetEdge(clickX: number | null, clickY: number | null, press?: WidgetPress): void;
-    /** A caret restored strictly inside a reveal-source widget — a formula that just closed
-     *  around it — opens that source there instead of being pushed past the island. */
+    /** A caret restored strictly inside a widget that can show its source, such as a formula
+     *  that just closed around it, opens that source there instead of being pushed past it. */
     revealInterior(offset: number): boolean;
-    /** A reveal-source widget currently shows its editable `$…$` source. */
+    /** A widget is currently showing its editable `$…$` source. */
     isRevealing(): boolean;
-    /** Escape (cancel to rendered) while source is shown. Enter is deliberately NOT
-     *  claimed: it is the block's split command, and the command seam folds first. */
+    /** Escape, which cancels back to the rendered form, while a source is shown. Enter is
+     *  deliberately left alone: it is the block's split command, which hides the source first. */
     handleRevealingKeydown(e: KeyboardEvent): Promise<boolean>;
-    /** Commit the revealed source when focus leaves the block. */
+    /** Commit the shown source when focus leaves the block. */
     commitRevealOnBlur(): void;
-    /** Fold an active reveal before ANY mutation of the block, so the mutation runs
-     *  against a CST matching the swapped DOM. Null if none was open; otherwise the
-     *  committed caret and a write completion the caller MUST await before mutating. */
+    /** Hide a shown source before any edit, so the edit runs against a CST that matches the DOM.
+     *  Null if none was shown; otherwise a write the caller must await before editing. */
     foldRevealBeforeMutation(caretAfter?: number): RevealFold | null;
-    /** Fold when the caret escapes a revealed source but stays inside the block; blur
-     *  owns the focus-leaving fold. */
+    /** Hide the source when the caret leaves it but stays inside the block; blur handles
+     *  the case where focus leaves the block. */
     foldRevealIfSelectionEscaped(): void;
-    /** The point sits on a reveal-source widget — pointerdown preventDefaults the
-     *  browser's caret task so nothing races the reveal's own placement. */
+    /** The point sits on a widget that can show its source. `pointerdown` then cancels the
+     *  browser's own caret placement so nothing races this one. */
     isPointOnRevealWidget(x: number, y: number): boolean;
+    /** Where a press on an inline widget anchors a drag: the widget's raw edge on the point's side.
+     *  Null over no widget, or over one with a pointer gesture of its own. */
+    islandDragAnchor(x: number, y: number): number | null;
 }
+/** What {@link replaceSelectedWidget} writes through. */
+export interface WidgetReplaceDeps {
+    get node(): NodeView;
+    get index(): number;
+    blockEdit: BlockEditActions;
+    widgetSelection: WidgetSelectionState;
+    setPendingCursor: (offset: number | null) => void;
+    /** Where the block's bytes are stored, read when the widget is replaced. */
+    storedAs: () => StoredAs;
+}
+/** Replace a selected widget's bytes with `text` in one undoable write and put the caret after
+ *  `text`, since with the widget gone the browser has no caret to keep. */
+export declare function replaceSelectedWidget(deps: WidgetReplaceDeps, widget: {
+    start: number;
+    end: number;
+}, preSelectOffset: number, text: string, mode: WriteMode): Promise<void>;
 export declare function createWidgetInteraction(deps: WidgetInteractionDeps): WidgetInteraction;