@voithos-labs/aragonite 0.10.1

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

@@ -0,0 +1,131 @@
+/**
+ * Clipboard handler bodies for TextEditableBlock; the component keeps the
+ * oncopy/oncut/onpaste bindings.
+ */
+import { resolvedInlineContent } from '../../../core/inline/inline-cache';
+import { isInlineWidget } from '../../../core/inline/inline-widgets';
+import { createClipboardHandlers } from '../editable-surface';
+import { pasteDispatch } from '../../../tree-operations/paste/dispatch';
+import { deleteRangeRaw } from './live-selection-edit';
+export function createTextClipboard(deps) {
+    function getSelectedTextFromRaw() {
+        const offsets = deps.cursor.getRawSelection();
+        if (!offsets)
+            return '';
+        return deps.node.raw.slice(offsets.start, offsets.end);
+    }
+    // Null unless a widget on THIS block is selected and still present in the parsed
+    // inline content. Shared by copy, cut, and paste-over-widget.
+    function selectedWidgetOnThisBlock() {
+        const selected = deps.widgetSelection.getSelected();
+        if (selected === null || !deps.widgetSelection.isSelected(deps.myPath, selected.sourceStart)) {
+            return null;
+        }
+        const inline = resolvedInlineContent(deps.node, deps.linkRef).find((n) => isInlineWidget(n, deps.node.raw) && n.start === selected.sourceStart);
+        return inline ? { inline, preSelectOffset: selected.preSelectOffset } : null;
+    }
+    const handlers = createClipboardHandlers({
+        stickyColumn: deps.stickyColumn,
+        edgeAffinity: deps.edgeAffinity,
+        selection: deps.selection,
+        getDoc: deps.getDoc,
+        crossBlock: deps.crossBlock,
+        isReadOnly: deps.isReadOnly,
+        caret: deps.caret,
+        events: deps.events,
+        onPasteImage: deps.onPasteImage,
+        foldReveal: deps.foldRevealBeforeMutation,
+        // Copy never mutates, so the widget stays selected.
+        copyPreHook: (e) => {
+            const widget = selectedWidgetOnThisBlock();
+            if (widget === null)
+                return false;
+            e.preventDefault();
+            e.clipboardData?.setData('text/plain', deps.node.raw.slice(widget.inline.start, widget.inline.end));
+            return true;
+        },
+        // A selection over an ACTIVE reveal covers uncommitted DOM, so slice the live text
+        // rather than the stale `node.raw`; copy must not fold, because folding mutates.
+        copyTail: (e) => {
+            e.preventDefault();
+            if (deps.isRevealing()) {
+                const offsets = deps.cursor.getRawSelection();
+                e.clipboardData?.setData('text/plain', offsets ? deps.readRevealedText().slice(offsets.start, offsets.end) : '');
+                return;
+            }
+            e.clipboardData?.setData('text/plain', getSelectedTextFromRaw());
+        },
+        // A selected widget: copy its slice, then splice it out as one undoable commit.
+        cutPreHook: (e) => {
+            const widget = selectedWidgetOnThisBlock();
+            if (widget === null)
+                return false;
+            const { inline, preSelectOffset } = widget;
+            e.clipboardData?.setData('text/plain', deps.node.raw.slice(inline.start, inline.end));
+            const newRaw = deps.node.raw.slice(0, inline.start) + deps.node.raw.slice(inline.end);
+            void deps.blockEdit.updateBlockContent(deps.index, newRaw, preSelectOffset, inline.start);
+            deps.widgetSelection.clear();
+            return true;
+        },
+        cutTail: (e) => {
+            const selectedText = getSelectedTextFromRaw();
+            if (!selectedText)
+                return;
+            e.clipboardData?.setData('text/plain', selectedText);
+            const selOffsets = deps.cursor.getRawSelection();
+            if (!selOffsets)
+                return;
+            // A cut is a delete, so it crosses the same join seam: in live the range can span
+            // delimiter runs the reader never saw, and a raw splice would print them.
+            const edit = deleteRangeRaw(deps.node, selOffsets, deps.getPresentationMode(), deps.linkRef, deps.getAmbientPrefix());
+            void deps.blockEdit.updateBlockContent(deps.index, edit.raw, selOffsets.start);
+            deps.setPendingCursor(edit.caret);
+        },
+        pasteTail: async (pastedText, foldedCaret) => {
+            const widget = selectedWidgetOnThisBlock();
+            if (widget !== null) {
+                const { inline, preSelectOffset } = widget;
+                const newRaw = deps.node.raw.slice(0, inline.start) + pastedText + deps.node.raw.slice(inline.end);
+                void deps.blockEdit.updateBlockContent(deps.index, newRaw, preSelectOffset, inline.start + pastedText.length);
+                deps.widgetSelection.clear();
+                return;
+            }
+            // After a reveal fold the caret sits on the widget's element-level edge, where
+            // getRaw can read null; the committed caret is the correct landing offset.
+            const offset = deps.cursor.getRaw() ?? foldedCaret ?? 0;
+            const selOffsets = deps.cursor.getRawSelection();
+            const result = await pasteDispatch({
+                pastedText,
+                targetPath: deps.myPath,
+                offset: selOffsets ? selOffsets.start : offset,
+                preDelete: selOffsets ? { start: selOffsets.start, end: selOffsets.end } : undefined
+            }, {
+                doc: deps.getDoc(),
+                blockEdit: deps.blockEdit,
+                controller: deps.pasteCoordinator,
+                grammar: deps.grammar,
+                activePlugins: deps.activePlugins,
+                seam: { presentationMode: deps.getPresentationMode(), linkRef: deps.linkRef }
+            });
+            // Pending, so the caret set and the raw mutation land in one reactive flush.
+            if (result.inlineCaretOffset !== undefined) {
+                deps.setPendingCursor(result.inlineCaretOffset);
+            }
+        }
+    });
+    return {
+        ...handlers,
+        // Routed to the same arms the caret route reaches, so the reading gate, the reveal
+        // fold and the sticky reset come along rather than being re-carried here.
+        claimRootClipboard(event) {
+            if (selectedWidgetOnThisBlock() === null)
+                return;
+            if (event.type === 'copy')
+                handlers.onCopy(event);
+            else if (event.type === 'cut')
+                void handlers.onCut(event);
+            else if (event.type === 'paste')
+                void handlers.onPaste(event);
+        }
+    };
+}

package/dist/components/blocks/text/text-keydown.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure raw/caret transforms for TextEditableBlock keydown branches — heading-level
+ * swap, demotion to prose, hard-break insertion, literal-tab insertion. The component
+ * owns the plumbing; these own the string math.
+ */
+import type { ContentRange } from '../../../core/inline';
+export interface TextEditResult {
+    newRaw: string;
+    caretOffset: number;
+}
+/**
+ * Give up the block's own structural bytes, whichever end the kind keeps them at: a prefix for
+ * ATX, an underline line for setext. Both sides read the kind's CONTENT RANGE and nothing else, so
+ * a prefix rewrite cannot disagree with the gate that let the press through (`  ## x` is a heading
+ * whose `#`s a `^#` regex never reaches). Null where the content IS the whole display.
+ */
+export declare function demoteToParagraph(raw: string, content: ContentRange, preEditOffset: number): TextEditResult | null;
+/** Drop everything before `contentStart` — a heading's marker prefix and any spaces that precede
+ *  it, which sit before every caret the content range admits. */
+export declare function dropStructuralPrefix(raw: string, contentStart: number, preEditOffset: number): TextEditResult;
+/** Drop everything past `contentEnd` but the block's own trailing line ending — the setext
+ *  underline, which sits after every caret the content range admits. */
+export declare function dropStructuralSuffix(raw: string, contentEnd: number, preEditOffset: number): TextEditResult;
+/**
+ * Re-mark the block's CONTENT with an ATX prefix for `level`, replacing whatever structural bytes
+ * the current kind keeps — the same content range {@link demoteToParagraph} reads, so an indented
+ * `  ## x` or a setext underline is given up rather than left in the new heading's text.
+ * `level === 0` IS the demotion, and null there means the content already is the whole display.
+ * Idempotent, not a toggle: stripping is reached only by asking for level 0.
+ */
+export declare function cycleHeading(raw: string, content: ContentRange, level: number, preEditOffset: number): TextEditResult | null;
+/**
+ * Insert a GFM hard-break (a backslash at end of line) at `offset` within the display.
+ * At end-of-display the break's own ending becomes the block's trailing ending, so the
+ * break is transitional there until the next keystroke supplies its following line.
+ */
+export declare function insertHardBreak(raw: string, offset: number): TextEditResult;
+/** Insert a literal tab character at `offset` within the display portion. */
+export declare function insertLiteralTab(raw: string, offset: number): TextEditResult;

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

@@ -0,0 +1,80 @@
+/**
+ * Pure raw/caret transforms for TextEditableBlock keydown branches — heading-level
+ * swap, demotion to prose, hard-break insertion, literal-tab insertion. The component
+ * owns the plumbing; these own the string math.
+ */
+import { displayLength, ownTrailingLineEnding, trailingLineEnding, trimTrailingLineEnding } from '../../../core/lines';
+/**
+ * Give up the block's own structural bytes, whichever end the kind keeps them at: a prefix for
+ * ATX, an underline line for setext. Both sides read the kind's CONTENT RANGE and nothing else, so
+ * a prefix rewrite cannot disagree with the gate that let the press through (`  ## x` is a heading
+ * whose `#`s a `^#` regex never reaches). Null where the content IS the whole display.
+ */
+export function demoteToParagraph(raw, content, preEditOffset) {
+    if (content.start > 0)
+        return dropStructuralPrefix(raw, content.start, preEditOffset);
+    if (content.end < displayLength(raw))
+        return dropStructuralSuffix(raw, content.end, preEditOffset);
+    return null;
+}
+/** Drop everything before `contentStart` — a heading's marker prefix and any spaces that precede
+ *  it, which sit before every caret the content range admits. */
+export function dropStructuralPrefix(raw, contentStart, preEditOffset) {
+    return {
+        newRaw: raw.slice(contentStart),
+        caretOffset: Math.max(0, preEditOffset - contentStart)
+    };
+}
+/** Drop everything past `contentEnd` but the block's own trailing line ending — the setext
+ *  underline, which sits after every caret the content range admits. */
+export function dropStructuralSuffix(raw, contentEnd, preEditOffset) {
+    return {
+        newRaw: raw.slice(0, contentEnd) + ownTrailingLineEnding(raw),
+        caretOffset: Math.min(preEditOffset, contentEnd)
+    };
+}
+/**
+ * Re-mark the block's CONTENT with an ATX prefix for `level`, replacing whatever structural bytes
+ * the current kind keeps — the same content range {@link demoteToParagraph} reads, so an indented
+ * `  ## x` or a setext underline is given up rather than left in the new heading's text.
+ * `level === 0` IS the demotion, and null there means the content already is the whole display.
+ * Idempotent, not a toggle: stripping is reached only by asking for level 0.
+ */
+export function cycleHeading(raw, content, level, preEditOffset) {
+    if (level === 0)
+        return demoteToParagraph(raw, content, preEditOffset);
+    const prefix = '#'.repeat(level) + ' ';
+    const newDisplay = prefix + raw.slice(content.start, content.end);
+    const inContent = Math.min(Math.max(preEditOffset, content.start), content.end);
+    return {
+        newRaw: newDisplay + ownTrailingLineEnding(raw),
+        caretOffset: prefix.length + (inContent - content.start)
+    };
+}
+/**
+ * Insert a GFM hard-break (a backslash at end of line) at `offset` within the display.
+ * At end-of-display the break's own ending becomes the block's trailing ending, so the
+ * break is transitional there until the next keystroke supplies its following line.
+ */
+export function insertHardBreak(raw, offset) {
+    const display = trimTrailingLineEnding(raw);
+    const trailing = ownTrailingLineEnding(raw);
+    // The break carries the block's own ending (G4.20): CommonMark reads a backslash
+    // before either LF or CRLF as a hard break, so a CRLF block stays CRLF.
+    const breakBytes = '\\' + trailingLineEnding(raw);
+    const newDisplay = display.slice(0, offset) + breakBytes + display.slice(offset);
+    // At end-of-display the inserted ending is itself the trailing ending; reattaching
+    // the original would double it into a blank line and break list-item continuation.
+    const newRaw = offset >= display.length ? newDisplay : newDisplay + trailing;
+    return {
+        newRaw,
+        caretOffset: Math.min(offset + breakBytes.length, displayLength(newRaw))
+    };
+}
+/** Insert a literal tab character at `offset` within the display portion. */
+export function insertLiteralTab(raw, offset) {
+    const display = trimTrailingLineEnding(raw);
+    const trailing = ownTrailingLineEnding(raw);
+    const newDisplay = display.slice(0, offset) + '\t' + display.slice(offset);
+    return { newRaw: newDisplay + trailing, caretOffset: offset + 1 };
+}

package/dist/components/blocks/text/text-render.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+import type { AmbientPrefix } from '../../../block-component';
+import type { DocumentView, NodeView } from '../../../core/node-views';
+import type { PresentationMode } from '../../../presentation-mode';
+import type { ResolveImageUrl, ResolveLinkUrl } from '../../../editor-keys';
+import type { LinkReferenceResolver } from '../../../core/inline/link-reference-resolver';
+import { type ImageLoadPolicy } from '../../../core/inline-render';
+import type { IndexedDecoration } from '../../../decorations/buckets';
+import type { ReplaceDecoration, WidgetDecoration } from '../../../decorations/types';
+export interface TextRenderDeps {
+    get el(): HTMLElement | null;
+    get node(): NodeView;
+    get ambientPrefix(): AmbientPrefix;
+    get ambientPrefixText(): string;
+    getDisplayText: () => string;
+    resolveImageUrl: ResolveImageUrl;
+    resolveLinkUrl: ResolveLinkUrl;
+    get imageLoadPolicy(): ImageLoadPolicy;
+    /** Effective mode. Read inside the render pass on purpose: the read is the
+     *  reactive dependency that re-renders every mounted block on a mode flip. */
+    get presentationMode(): PresentationMode;
+    /** The editor's theme name, forwarded to widgets. NOT a render-key term: this DOM is
+     *  themed by CSS, so only a widget whose engine paints its own colors reads it. */
+    getTheme?: () => string;
+    /** Live root document for widgets that derive from it. A getter, so a pooled widget
+     *  re-reads the current document across edits rather than a mount-time snapshot. */
+    getDocument: () => DocumentView | undefined;
+    /** The editor's content version, so a widget can memoize a document-wide derivation
+     *  on it. Absent in a bare harness. */
+    getContentVersion?: () => number;
+    /** The editor's navigation door, forwarded to widgets whose gesture jumps elsewhere. */
+    navigateTo?: (path: number[]) => Promise<boolean>;
+    get linkResolver(): LinkReferenceResolver | undefined;
+    /** A compact stamp changing exactly when the document's LRD signature does
+     *  (`link-reference-resolver.ts` mints it), so a reference-bearing block folds this
+     *  into its render key instead of a signature string that reaches ~MB scale. */
+    get linkStamp(): string;
+    /** Position-sorted islands. A getter read inside the render pass on purpose: that
+     *  read is the reactive dependency that re-renders the block on an island change. */
+    get islands(): IndexedDecoration<WidgetDecoration | ReplaceDecoration>[];
+    brokenUrlCache: Set<string>;
+    /** A widget's synchronous mount throw goes to the editor's `error` channel. Absent →
+     *  unsurfaced; the widget still falls back to its raw source. */
+    reportRenderError?: (error: unknown) => void;
+}
+export interface TextRender {
+    /**
+     * Rebuild the block's children from current node state. Skips work on an unchanged
+     * render key unless `forceRebuild` — pass it when a pending cursor restore needs the
+     * DOM re-anchored. `carryCaret` re-anchors the caret; the edit path passes false.
+     */
+    render(opts?: {
+        forceRebuild?: boolean;
+        carryCaret?: boolean;
+    }): void;
+    /** Destroy every pooled widget instance — called when the block unmounts. */
+    dispose(): void;
+}
+/** Which renderKey segment(s) differ — the interaction trace's rebuild cause. Pure over
+ *  the key format, so the recorder never learns the NUL layout. */
+export declare function renderKeySegmentDiff(prev: string, next: string): string;
+export declare function createTextRender(deps: TextRenderDeps): TextRender;

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

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+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 { applyIslandDecorations, islandRenderKeyPart } from '../../../decorations/island-dom';
+import { mountDecorationWidget } from '../../../decorations/widget-dom';
+import { devWarn } from '../../../dev-warn';
+import { recordIslandRebuild } from '../../../perf/instruments';
+import { isInteractionTraceEnabled, traceRebuild, traceCursorCapture, traceCursorRestore, traceIslandsApplied } from '../../../debug/interaction-trace';
+import { buildImageWidget } from '../../image/widget-dom';
+import { getBlockKindDescriptor } from '../../../schema/block-kind-descriptor';
+import { createSvelteWidgetPool } from '../widget-portal';
+// The NUL-joined parts of a prose renderKey, index-aligned.
+const RENDER_KEY_SEGMENTS = [
+    'ambient',
+    'raw',
+    'ref',
+    'imgPolicy',
+    'mode',
+    '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. */
+export function renderKeySegmentDiff(prev, next) {
+    const a = prev.split('\0');
+    const b = next.split('\0');
+    const changed = [];
+    for (let i = 0; i < RENDER_KEY_SEGMENTS.length; i++) {
+        if ((a[i] ?? '') !== (b[i] ?? ''))
+            changed.push(RENDER_KEY_SEGMENTS[i]);
+    }
+    return changed.join(',') || '(none)';
+}
+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
+    });
+    let islandDestroys = [];
+    function destroyIslands() {
+        for (const destroy of islandDestroys)
+            destroy();
+        islandDestroys = [];
+    }
+    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 ''.
+    function getBlockMarkerPrefix() {
+        const node = deps.node;
+        const range = getContentRange(node);
+        return node.raw.slice(0, range.start);
+    }
+    // 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) {
+        const node = deps.node;
+        const frag = document.createDocumentFragment();
+        if (deps.ambientPrefixText) {
+            frag.appendChild(buildAmbientSpan(deps.ambientPrefix));
+        }
+        const blockOwnPrefix = getBlockMarkerPrefix();
+        if (blockOwnPrefix) {
+            const span = document.createElement('span');
+            span.className = 'md-marker';
+            span.textContent = blockOwnPrefix;
+            frag.appendChild(span);
+        }
+        const descriptor = getBlockKindDescriptor(node.kind);
+        frag.appendChild(renderInlineNodes(content, node.raw, {
+            renderImagesAsWidgets: descriptor.renderImagesAsWidgets ?? true,
+            resolveImageUrl: deps.resolveImageUrl,
+            resolveLinkUrl: deps.resolveLinkUrl,
+            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'
+        }));
+        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(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.
+    function ensureBr(el) {
+        if (deps.getDisplayText() !== '')
+            return;
+        const hasAnchorBr = [...el.querySelectorAll('br')].some((br) => !br.closest('[data-decoration-island]'));
+        if (!hasAnchorBr)
+            el.appendChild(document.createElement('br'));
+    }
+    function captureCaretIfFocused(el) {
+        const walk = captureFocusedCaretWalkOffset(el);
+        if (walk !== null)
+            traceCursorCapture(walk);
+        return walk;
+    }
+    function restoreCaret(el, walkOffset) {
+        restoreCaretAtWalkOffset(el, walkOffset);
+        traceCursorRestore(walkOffset);
+    }
+    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.
+        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 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;
+        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.
+        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;
+        let carriedCaret = null;
+        if (isProseKind(node.kind)) {
+            if (renderKey === lastRenderedKey && !forceRebuild)
+                return;
+            // Detail assembly (the segment diff) allocates, so it stays behind the gate.
+            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;
+            // 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.
+            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)
+            });
+            if (islands.length > 0) {
+                recordIslandRebuild();
+                traceIslandsApplied(islands.length);
+            }
+            widgetPool.sweep();
+            carriedCaret = caretWalkOffset;
+        }
+        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.
+            widgetPool.beginPass();
+            destroyIslands();
+            widgetPool.sweep();
+            const display = deps.getDisplayText();
+            const markerPrefix = getBlockMarkerPrefix();
+            if (markerPrefix) {
+                // The line stays one editable coordinate space, so an edit that breaks the
+                // fence reparses to the natural kind.
+                if (el.textContent !== display || forceRebuild) {
+                    el.replaceChildren(buildMarkerPrefixDOM(markerPrefix, display.slice(markerPrefix.length)));
+                }
+            }
+            else if (el.textContent !== display) {
+                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.
+        lastRenderedKey = renderKey;
+        ensureBr(el);
+        // The stamp decides which spans the walk can land in, so it precedes the caret restore.
+        el.toggleAttribute(CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome(el));
+        if (carriedCaret !== null)
+            restoreCaret(el, carriedCaret);
+    }
+    return {
+        render,
+        dispose: () => {
+            destroyIslands();
+            widgetPool.dispose();
+        }
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Pure adjacency queries over a prose block's inline content and raw source: which
+ * live widget a caret offset touches, the leading/trailing edge widgets, and whether
+ * an offset has only whitespace to one side.
+ */
+import type { AnyInlineKind, InlineNode } from '../../../core/nodes';
+export interface WidgetRange {
+    start: number;
+    end: number;
+}
+export interface WidgetAtCursor extends WidgetRange {
+    atRight: boolean;
+    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;
+/** 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;
+/** Trailing-edge counterpart of `findFirstEdgeWidget`. */
+export declare function findLastEdgeWidget(inlines: ReadonlyArray<InlineNode>, raw: string): 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. */
+export declare function widgetElByStart(el: HTMLElement, start: number): HTMLElement | null;

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

@@ -0,0 +1,68 @@
+/**
+ * Pure adjacency queries over a prose block's inline content and raw source: which
+ * live widget a caret offset touches, the leading/trailing edge widgets, and whether
+ * an offset has only whitespace to one side.
+ */
+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') {
+    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)) {
+        if (offset === inline.start && !leadingMatch)
+            leadingMatch = { start: inline.start, end: inline.end, atRight: false, kind: inline.kind };
+        if (offset === inline.end && !trailingMatch)
+            trailingMatch = { start: inline.start, end: inline.end, atRight: true, kind: inline.kind };
+    }
+    if (direction === 'forward')
+        return leadingMatch ?? trailingMatch;
+    return trailingMatch ?? leadingMatch;
+}
+export function findWidgetNodeByStart(sourceStart, inlineContent, raw) {
+    for (const inline of flattenInlineWidgets(inlineContent ?? [], raw)) {
+        if (inline.start === sourceStart) {
+            return { start: inline.start, end: inline.end };
+        }
+    }
+    return null;
+}
+/** First widget reachable from the leading edge, skipping blank text; null once any
+ *  non-blank, non-widget inline intervenes. */
+export function findFirstEdgeWidget(inlines, raw) {
+    for (const inline of inlines) {
+        if (isInlineWidget(inline, raw))
+            return inline;
+        if (inline.kind === 'text' && (inline.text ?? '').trim() === '')
+            continue;
+        return null;
+    }
+    return null;
+}
+/** Trailing-edge counterpart of `findFirstEdgeWidget`. */
+export function findLastEdgeWidget(inlines, raw) {
+    for (let i = inlines.length - 1; i >= 0; i--) {
+        const inline = inlines[i];
+        if (isInlineWidget(inline, raw))
+            return inline;
+        if (inline.kind === 'text' && (inline.text ?? '').trim() === '')
+            continue;
+        return null;
+    }
+    return null;
+}
+export function rawHasNoTextBefore(raw, offset) {
+    return raw.slice(0, offset).trim() === '';
+}
+export function rawHasNoTextAfter(raw, offset) {
+    return raw.slice(offset).trim() === '';
+}
+/** 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. */
+export function widgetElByStart(el, start) {
+    return el.querySelector(`[data-inline-widget][data-source-start="${start}"]`);
+}