@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/image/image-edit-commit.js

@@ -1,42 +1,36 @@
+import { tick } from 'svelte';
 import { resolvedInlineContent } from '../../core/inline/inline-cache';
 import { flattenInlineWidgets } from '../../core/inline/inline-widgets';
-import { createInlineRangeCommit } from '../../editor-actions/inline-range-commit';
 import { FALLBACK_CONTENT_WIDTH } from '../../cursor/typography-estimates';
 import { blockNodeAt } from '../../tree-operations/node-primitives';
-import { buildImageEditBytes } from './image-source-bytes';
+import { buildImageEditBytes, imageFieldsFromInline, sameImageFields } from '../../core/inline/image-source-bytes';
+// ── Public API ──────────────────────────────────────────────────────────
+/** The image `target` names in `doc`, or null once no image starts at its bytes. */
+export function imageAtTarget(doc, target, reading) {
+    const paragraph = blockNodeAt(doc, target.paragraphPath);
+    return paragraph ? findImageInParagraph(paragraph, target.sourceStart, reading) : null;
+}
 export function createImageEditCommitter(deps) {
-    const { getDoc, getEditorEl, widgetSelection, controller, events } = deps;
-    const inlineRange = createInlineRangeCommit({ getDoc, controller, grammar: deps.grammar });
-    function findImageInParagraph(para, sourceStart) {
-        // Resolver-aware so a reference-style image resolves as the render path saw it,
-        // and flattened so an image nested in a link (`[![alt][ref]][repo]`) is found.
-        const inlines = resolvedInlineContent(para, deps.linkRef);
-        for (const widget of flattenInlineWidgets(inlines, para.raw)) {
-            if (widget.kind === 'image' && widget.start === sourceStart)
-                return widget;
-        }
-        return null;
-    }
+    const { getDoc, getEditorEl, widgetSelection, inlineRange, events } = deps;
     function queryWidgetEl(paragraphPath, sourceStart) {
         const root = getEditorEl();
         if (!root)
             return null;
-        // Locate by the live block-host path, never a baked attribute on the widget —
+        // Locate by the live block-host path, never an attribute baked into the widget:
         // see widget-dom.ts's click handler.
         const host = root.querySelector(`[data-block-path='${JSON.stringify(paragraphPath)}']`);
         if (!host)
             return null;
         return host.querySelector(`[data-image-widget][data-source-start="${sourceStart}"]`);
     }
+    const imageAt = (target) => imageAtTarget(getDoc(), target, deps.reading);
+    // The bytes the last popover write moved, applied by the next stale check: the write runs as
+    // the popover unmounts, where a read of the selection still returns the one before the click.
+    let lastShift = null;
     function getSelectedImageFields() {
         const sel = widgetSelection.getSelected();
-        if (!sel)
-            return null;
-        const paragraph = blockNodeAt(getDoc(), sel.paragraphPath);
-        if (!paragraph)
-            return null;
-        const image = findImageInParagraph(paragraph, sel.sourceStart);
-        if (!image)
+        const image = sel && imageAt(sel);
+        if (!sel || !image)
             return null;
         return { image, widgetEl: queryWidgetEl(sel.paragraphPath, sel.sourceStart) };
     }
@@ -44,11 +38,11 @@ export function createImageEditCommitter(deps) {
         const paragraph = blockNodeAt(getDoc(), target.paragraphPath);
         if (!paragraph)
             return null;
-        const image = findImageInParagraph(paragraph, target.sourceStart);
+        const image = findImageInParagraph(paragraph, target.sourceStart, deps.reading);
         if (!image)
             return null;
-        // Preserve the reference form when url/title are untouched: inlining the
-        // resolved url would orphan the LRD. Changing either is the user opting in.
+        // Keep the reference form when the url and title are untouched: writing the resolved
+        // url inline would leave the definition unused. Changing either is the user asking.
         const fields = image.label !== undefined && newFields.url === image.url && newFields.title === image.title
             ? { ...newFields, label: image.label }
             : newFields;
@@ -58,11 +52,24 @@ export function createImageEditCommitter(deps) {
     function buildEditBytes(target, newFields) {
         return resolveEdit(target, newFields)?.bytes ?? null;
     }
-    function commitImageEdit(target, newFields) {
+    function commitImageEdit(target, seenFields, newFields) {
+        const image = imageAt(target);
+        if (!image || !sameImageFields(imageFieldsFromInline(image), seenFields))
+            return;
+        writeImageEdit(target, newFields);
+    }
+    // The caret from before the image was selected anchors the undo entry when no other caret
+    // answers: the popover can commit after the selection has moved on.
+    function writeImageEdit(target, newFields) {
         const edit = resolveEdit(target, newFields);
         if (!edit)
             return;
-        void inlineRange.commitInlineRange(target.paragraphPath, edit.image.start, edit.image.end, edit.bytes, 0);
+        // Read from the bytes the block's kind will store, which a kind's own write rule can change.
+        const delta = inlineRange.writtenDelta(target.paragraphPath, edit.image.start, edit.image.end, edit.bytes);
+        if (delta !== 0) {
+            lastShift = { paragraphPath: target.paragraphPath, editEnd: edit.image.end, delta };
+        }
+        void inlineRange.commitInlineRange(target.paragraphPath, edit.image.start, edit.image.end, edit.bytes, target.preSelectOffset);
     }
     function commitImageResize(newWidth, newHeight) {
         const sel = widgetSelection.getSelected();
@@ -84,16 +91,16 @@ export function createImageEditCommitter(deps) {
             ...(framedHeight !== undefined ? { height: framedHeight } : {}),
             ...(image.crop !== undefined && framedHeight !== undefined ? { crop: image.crop } : {})
         };
-        commitImageEdit(sel, newFields);
+        writeImageEdit(sel, newFields);
     }
-    /** The whole `![...](...)` span goes; the caret lands where the image began. */
+    /** The whole `![...](...)` span goes. The selection clears first, so the undo entry is told
+     *  the caret the user had before selecting the image rather than reading it. */
     function removeImage(target) {
-        const paragraph = blockNodeAt(getDoc(), target.paragraphPath);
-        const image = paragraph && findImageInParagraph(paragraph, target.sourceStart);
+        const image = imageAt(target);
         if (!image)
             return;
         widgetSelection.clear();
-        void inlineRange.commitInlineRange(target.paragraphPath, image.start, image.end, '', 0);
+        void inlineRange.commitInlineRange(target.paragraphPath, image.start, image.end, '', target.preSelectOffset);
     }
     function dismissImagePopover() {
         widgetSelection.clear();
@@ -109,15 +116,33 @@ export function createImageEditCommitter(deps) {
         root.addEventListener('image-widget-select', handler);
         return () => root.removeEventListener('image-widget-select', handler);
     }
+    function clearStaleSelection() {
+        const shift = lastShift;
+        lastShift = null;
+        if (!shift) {
+            dropSelectionIfStale();
+            return;
+        }
+        // The overlay finds the widget by the bytes its element names, so the move waits for the
+        // block to render the write.
+        void tick().then(() => {
+            widgetSelection.followEdit(shift.paragraphPath, shift.editEnd, shift.delta);
+            dropSelectionIfStale();
+        });
+    }
+    function dropSelectionIfStale() {
+        const sel = widgetSelection.getSelected();
+        if (sel && !imageAt(sel))
+            widgetSelection.clear();
+    }
     function syncOverlayToWidget(getOverlay) {
         const noop = () => { };
         const overlayEl = getOverlay();
         const editorEl = getEditorEl();
         if (!overlayEl || !editorEl)
             return noop;
-        // Each commit rebuilds the inline DOM, so a captured widget ref would observe a
-        // detached node forever: re-resolve on every update and re-attach the observer
-        // when widget identity changes.
+        // Each commit rebuilds the inline DOM, so the widget is re-resolved on every update and
+        // the observer re-attached when it changes.
         let observer = null;
         let observed = null;
         const update = () => {
@@ -144,9 +169,8 @@ export function createImageEditCommitter(deps) {
         // Edits above the widget shift its y without resizing it.
         const unsubscribeEdit = events.on('edit', update);
         window.addEventListener('resize', update);
-        // Sibling images settling their dimensions shift the selected widget's y without
-        // resizing it, which the ResizeObserver never sees. Capture phase: neither
-        // event bubbles.
+        // Sibling images settling shift the widget's y without resizing it; capture phase,
+        // since neither event bubbles.
         const onImgSettle = (e) => {
             if (e.target instanceof HTMLImageElement)
                 update();
@@ -170,6 +194,18 @@ export function createImageEditCommitter(deps) {
         dismissImagePopover,
         getEditorContentWidth,
         attachWidgetSelectListener,
+        clearStaleSelection,
         syncOverlayToWidget
     };
 }
+// ── Internal ────────────────────────────────────────────────────────────
+function findImageInParagraph(para, sourceStart, reading) {
+    // Resolver-aware so a reference-style image resolves as the render path saw it,
+    // and flattened so an image nested in a link (`[![alt][ref]][repo]`) is found.
+    const inlines = resolvedInlineContent(para, reading);
+    for (const widget of flattenInlineWidgets(inlines, para.raw, reading.grammar)) {
+        if (widget.kind === 'image' && widget.start === sourceStart)
+            return widget;
+    }
+    return null;
+}

package/dist/components/image/image-resize.d.ts

@@ -3,9 +3,6 @@ export declare function clampWidth(width: number, maxWidth: number): number;
 export declare const KEYBOARD_MIN_WIDTH = 32;
 export declare function keyboardResizeWidth(currentWidth: number, delta: number, maxWidth: number): number;
 export declare function snapWidth(width: number, maxWidth: number, snapThresholdPx: number): number;
-/**
- * The height a release persists — the one the drag showed. An aspect-locked drag lets the height
- * follow the width, so it persists `|N` and leaves the derivation to the renderer; an unlocked
- * drag holds the height the image already had, which only the explicit `|NxM` form can carry.
- */
+/** The height the drag showed: none for an aspect-locked drag (`|N`, the renderer derives it),
+ *  the existing height for an unlocked one, which needs the `|NxM` form. */
 export declare function resolveDraggedHeight(aspectLocked: boolean, previewHeight: number): number | undefined;

package/dist/components/image/image-resize.js

@@ -1,5 +1,5 @@
 // Pure math for image drag-to-resize: clamp, snap-to-percentage, aspect lock.
-// No DOM — the handles component owns pointer events and calls these.
+// No DOM: the handles component owns pointer events and calls these.
 export const MIN_WIDTH = 16;
 const SNAP_PERCENTAGES = [25, 50, 75, 100];
 export function clampWidth(width, maxWidth) {
@@ -25,11 +25,8 @@ export function snapWidth(width, maxWidth, snapThresholdPx) {
     }
     return rounded;
 }
-/**
- * The height a release persists — the one the drag showed. An aspect-locked drag lets the height
- * follow the width, so it persists `|N` and leaves the derivation to the renderer; an unlocked
- * drag holds the height the image already had, which only the explicit `|NxM` form can carry.
- */
+/** The height the drag showed: none for an aspect-locked drag (`|N`, the renderer derives it),
+ *  the existing height for an unlocked one, which needs the `|NxM` form. */
 export function resolveDraggedHeight(aspectLocked, previewHeight) {
     // A widget that never laid out reports 0; `|Nx0` is worse than no hint at all.
     if (aspectLocked || previewHeight < 1)

package/dist/components/image/image-widget-editing.d.ts

@@ -1,7 +1,7 @@
 /**
- * The image widget's selected-key behavior: Shift+Arrow keyboard resize. Attached as
- * the image kind's `onSelectedKey` at mount (built-in-blocks.ts), so the generic
- * selected-widget keydown path stays kind-agnostic.
+ * What a key does while an image widget is selected: Shift+Arrow resizes it. Registered as
+ * the image kind's `onSelectedKey` at mount (built-in-blocks.ts), so the shared
+ * selected-widget keydown path stays the same for every kind.
  */
 import type { InlineWidgetEditingContext } from '../../core/inline/inline-widgets';
 export declare function imageWidgetOnSelectedKey(e: KeyboardEvent, ctx: InlineWidgetEditingContext): boolean;

package/dist/components/image/image-widget-editing.js

@@ -1,14 +1,14 @@
 /**
- * The image widget's selected-key behavior: Shift+Arrow keyboard resize. Attached as
- * the image kind's `onSelectedKey` at mount (built-in-blocks.ts), so the generic
- * selected-widget keydown path stays kind-agnostic.
+ * What a key does while an image widget is selected: Shift+Arrow resizes it. Registered as
+ * the image kind's `onSelectedKey` at mount (built-in-blocks.ts), so the shared
+ * selected-widget keydown path stays the same for every kind.
  */
-import { buildImageEditBytes } from './image-source-bytes';
+import { buildImageEditBytes } from '../../core/inline/image-source-bytes';
 import { keyboardResizeWidth } from './image-resize';
 const KEYBOARD_STEP = 20;
 const FALLBACK_DEFAULT_WIDTH = 400;
 export function imageWidgetOnSelectedKey(e, ctx) {
-    // A resize is an edit; declining lets the caller's generic swallow keep the key inert.
+    // A resize is an edit; refusing here lets the caller swallow the key and do nothing.
     if (ctx.presentationMode === 'reading')
         return false;
     if (!(e.shiftKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')))
@@ -18,8 +18,8 @@ export function imageWidgetOnSelectedKey(e, ctx) {
     const delta = e.key === 'ArrowRight' ? KEYBOARD_STEP : -KEYBOARD_STEP;
     const currentWidth = inline.width ?? FALLBACK_DEFAULT_WIDTH;
     const newWidth = keyboardResizeWidth(currentWidth, delta, ctx.editorContentWidth);
-    // url and title are untouched, so carry the label through and preserve the
-    // `![alt][label]` form rather than inlining the LRD-resolved url.
+    // The url and title are untouched, so keep the label and the `![alt][label]` form
+    // rather than writing the resolved url inline.
     const newFields = {
         alt: inline.alt ?? '',
         url: inline.url ?? '',
@@ -32,8 +32,8 @@ export function imageWidgetOnSelectedKey(e, ctx) {
         ...(inline.label !== undefined ? { label: inline.label } : {})
     };
     const newBytes = buildImageEditBytes(inline, node.raw, newFields);
-    // The rung owning these bytes cannot express the resize, but consume the key
-    // anyway: handing a Shift+Arrow on would extend the selection out of the image.
+    // The inline syntax handler that owns these bytes cannot express the resize, but take
+    // the key anyway: passing a Shift+Arrow on would extend the selection out of the image.
     if (newBytes === null)
         return true;
     const newRaw = node.raw.slice(0, ctx.widgetStart) + newBytes + node.raw.slice(ctx.widgetEnd);

package/dist/components/image/widget-dom.d.ts

@@ -3,9 +3,8 @@ import type { ImageLoadPolicy } from '../../core/inline-render';
 export interface BuildImageWidgetOpts {
     resolveImageUrl: (rawUrl: string) => string;
     imageLoadPolicy?: ImageLoadPolicy;
-    /** Resolved URLs that failed to load this session, per editor instance. Inline
-     *  rebuild creates a fresh <img> per keystroke, which without this renders
-     *  unbroken until the async `error` re-fires — a flicker on every keystroke. */
+    /** URLs that failed to load this session, so a rebuilt <img> renders broken at once instead
+     *  of flickering until its `error` fires again. */
     brokenUrlCache: Set<string>;
 }
 export declare function buildImageWidget(node: InlineNode, _raw: string, opts: BuildImageWidgetOpts): HTMLSpanElement;

package/dist/components/image/widget-dom.js

@@ -1,6 +1,6 @@
-// The widget contributes its raw bytes via data-source-start/end, which
-// `cursor/widget-offset.ts` reads; textContent stays empty so prose
-// `textContent === ambientPrefix + raw` still holds.
+// The widget reports its raw bytes through data-source-start and data-source-end, which
+// `cursor/widget-offset.ts` reads; its textContent stays empty so a prose block's
+// `textContent === marker prefix + raw` still holds.
 import { isAllowedImageSrcScheme } from '../../core/url-policy';
 import { findSurfacePathForElement } from '../../selection/path-lookup';
 import { devWarn } from '../../dev-warn';
@@ -8,28 +8,25 @@ import { applyCropToWidget } from './image-crop';
 export function buildImageWidget(node, _raw, opts) {
     const widget = document.createElement('span');
     widget.className = 'md-image-widget';
-    // `data-inline-widget` is the shared atomic-widget marker read by the cursor
-    // walker, selection painter and raw reader; `data-image-widget` is image-specific.
+    // `data-inline-widget` marks any widget the caret cannot enter, and is read by the
+    // caret code, the selection painter and the raw reader; `data-image-widget` is this one.
     widget.dataset.inlineWidget = '';
     widget.dataset.imageWidget = '';
     widget.dataset.sourceStart = String(node.start);
     widget.dataset.sourceEnd = String(node.end);
     widget.setAttribute('contenteditable', 'false');
-    // Select on `click`, never `pointerdown`: a pointerdown listener hijacks a gesture
-    // STARTING on the image, so no cross-block drag could originate here. Shift-click
-    // is a cross-block extension the block owns, so decline it.
+    // On `click`, not `pointerdown`, so a drag can still start on the image; a Shift-click
+    // extends the block's own selection.
     widget.addEventListener('click', (e) => {
         if (e.shiftKey)
             return;
-        // Resolve the path live rather than baking it at build time: content inserted
-        // above shifts the block's path without touching its `raw`, so the render memo
-        // skips a rebuild and a baked path resolves the wrong CST node. The SURFACE door:
-        // inside a cell the block path stops at the table, whose offsets are cell indices.
+        // Resolved at the click: content inserted above moves the block's path without a
+        // rebuild of this widget, so a path stored at build time would go stale.
         const paragraphPath = findSurfacePathForElement(widget);
         if (!paragraphPath)
             return;
-        // Match TextEditableBlock.snapClickToWidgetEdge, which lands the caret at the
-        // widget's right edge, so Ctrl+Z restores the click's visual landing.
+        // Match TextEditableBlock.snapClickToWidgetEdge, which puts the caret at the
+        // widget's right edge, so Ctrl+Z restores the caret where the click left it.
         const event = new CustomEvent('image-widget-select', {
             bubbles: true,
             detail: {
@@ -62,9 +59,8 @@ export function buildImageWidget(node, _raw, opts) {
         img.setAttribute('width', String(node.width));
     if (node.height !== undefined)
         img.setAttribute('height', String(node.height));
-    // A declared `|WxH` box belongs to the author, so it both reserves space before the bytes
-    // arrive and survives the decode: the attribute pair alone loses to the natural ratio the
-    // moment `height: auto` has one to read. With a crop the box is a frame the image pans in.
+    // A `|WxH` box reserves space before the bytes arrive and survives the decode, where the
+    // attributes alone lose to the natural ratio; with a crop it is the frame.
     if (node.width !== undefined && node.height !== undefined) {
         img.style.aspectRatio = `${node.width} / ${node.height}`;
         if (node.crop) {
@@ -75,18 +71,17 @@ export function buildImageWidget(node, _raw, opts) {
         opts.brokenUrlCache.add(resolvedUrl);
         widget.classList.add('md-image-broken');
     };
-    // Broken means the request finished and produced nothing to lay out, so each site
-    // establishes completion itself: `complete` here, by definition in the load listener.
+    // Broken means the request finished and produced nothing to lay out, so each place
+    // below checks that it finished: `complete` here, and the load event itself below.
     const hasNoIntrinsicSize = () => img.naturalWidth === 0;
-    // Only a loaded image can be broken: a blocked/placeholder widget leaves src unset,
-    // and an unset <img> reports complete && naturalWidth === 0 in a real browser.
+    // Only a loaded image can be broken: a blocked or placeholder widget leaves src unset,
+    // and an unset <img> reports complete with naturalWidth 0 in a real browser.
     if (img.src && (opts.brokenUrlCache.has(resolvedUrl) || (img.complete && hasNoIntrinsicSize()))) {
         markBroken();
     }
     img.addEventListener('error', markBroken);
-    // A load event is not proof of success: a 200 the decoder cannot size (truncated
-    // body, an SVG with no intrinsic dimensions) fires `load` with naturalWidth 0, and
-    // deferring that to the next rebuild leaves the placeholder a render behind.
+    // `load` can fire with no size (a truncated body, an SVG without dimensions), so it is
+    // checked here rather than a render later.
     img.addEventListener('load', () => {
         if (hasNoIntrinsicSize()) {
             markBroken();

package/dist/components/image/widget-selection-state.svelte.d.ts

@@ -1,18 +1,17 @@
-/** What an outside-press dismiss handler must NOT treat as outside: the widget itself and
- *  the overlay chrome anchored to it. One string, because both handlers must move together. */
+import type { WidgetTarget } from '../../selection/primitives';
+import type { SelectionState } from '../../selection/selection-state.svelte';
+/** What a click-outside handler must not count as outside: the widget itself and the overlay
+ *  controls attached to it. */
 export declare const IMAGE_CHROME_SELECTOR = "[data-image-widget], [data-image-overlay]";
-export interface WidgetTarget {
-    paragraphPath: number[];
-    sourceStart: number;
-    preSelectOffset: number;
-}
+/** Whether a press should end the image selection, for both click-outside handlers. A Shift-press
+ *  on this editor's text is left to that block, which grows a range from the image and ends it. */
+export declare function pressLeavesImage(press: PointerEvent, editorRoot: Element | null): boolean;
 export interface WidgetSelectionState {
     getSelected(): WidgetTarget | null;
     select(target: WidgetTarget): void;
+    /** Ends a selected widget; with none selected, touches nothing else the store holds. */
     clear(): void;
+    followEdit(paragraphPath: number[], editEnd: number, delta: number): void;
     isSelected(paragraphPath: number[], sourceStart: number): boolean;
 }
-export interface CreateWidgetSelectionOpts {
-    onSelect: () => void;
-}
-export declare function createWidgetSelectionState(opts: CreateWidgetSelectionOpts): WidgetSelectionState;
+export declare function createWidgetSelectionState(selection: SelectionState): WidgetSelectionState;

package/dist/components/image/widget-selection-state.svelte.js

@@ -1,26 +1,33 @@
-// Image-widget selection is mutually exclusive with caret and cross-block
-// selection; `select` fires `onSelect` so the editor shell can clear the others.
+// The image and text-block readers' view of the widget the selection state holds. It keeps no state
+// of its own, so it can't disagree with the store. Interim: it goes once those readers read the
+// selection state themselves.
+import { selectWidgetWhole } from '../../selection/caret-doors';
 import { pathsEqual } from '../../selection/path-math';
-/** What an outside-press dismiss handler must NOT treat as outside: the widget itself and
- *  the overlay chrome anchored to it. One string, because both handlers must move together. */
+import { findSurfacePathForElement } from '../../selection/path-lookup';
+/** What a click-outside handler must not count as outside: the widget itself and the overlay
+ *  controls attached to it. */
 export const IMAGE_CHROME_SELECTOR = '[data-image-widget], [data-image-overlay]';
-export function createWidgetSelectionState(opts) {
-    let selected = $state(null);
+/** Whether a press should end the image selection, for both click-outside handlers. A Shift-press
+ *  on this editor's text is left to that block, which grows a range from the image and ends it. */
+export function pressLeavesImage(press, editorRoot) {
+    const target = press.target instanceof Element ? press.target : null;
+    if (target?.closest(IMAGE_CHROME_SELECTOR))
+        return false;
+    const ownedByBlock = press.shiftKey && !!editorRoot?.contains(target) && findSurfacePathForElement(target) !== null;
+    return !ownedByBlock;
+}
+export function createWidgetSelectionState(selection) {
     return {
-        getSelected: () => selected,
-        select: (target) => {
-            selected = {
-                paragraphPath: [...target.paragraphPath],
-                sourceStart: target.sourceStart,
-                preSelectOffset: target.preSelectOffset
-            };
-            opts.onSelect();
-        },
+        getSelected: () => selection.widget,
+        select: (target) => selectWidgetWhole(selection, target),
         clear: () => {
-            selected = null;
+            if (selection.widget !== null)
+                selection.clear();
         },
-        isSelected: (path, start) => selected !== null &&
-            selected.sourceStart === start &&
-            pathsEqual(selected.paragraphPath, path)
+        followEdit: (path, editEnd, delta) => selection.followWidgetEdit(path, editEnd, delta),
+        isSelected: (path, start) => {
+            const widget = selection.widget;
+            return (widget !== null && widget.sourceStart === start && pathsEqual(widget.paragraphPath, path));
+        }
     };
 }

package/dist/components/kind-cue.svelte.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The kind cue: in a mode that hides markers, a keystroke that turns its block into another kind
+ * leaves the new kind's name at the block's corner for a moment and says it once to a screen
+ * reader, so the change has a visible cause. Only typed text reports here, never a command.
+ */
+import type { AnyBlockKind } from '../core/nodes';
+import type { DocumentView } from '../core/node-views';
+import { type PresentationMode } from '../presentation-mode';
+export interface KindCue {
+    /** Once `write` settles, cue the block at `path` if its shown kind differs from `before`. */
+    afterTypedWrite(write: Promise<unknown>, path: readonly number[], before: AnyBlockKind): Promise<void>;
+    /** The label the block at `path` shows, until its fade ends or the block there loses that name. */
+    labelAt(path: readonly number[]): string | undefined;
+    dismiss(path: readonly number[]): void;
+}
+export interface KindCueDeps {
+    getDoc: () => DocumentView;
+    getPresentationMode: () => PresentationMode;
+    announce: (label: string) => void;
+}
+export declare function createKindCue(deps: KindCueDeps): KindCue;

package/dist/components/kind-cue.svelte.js

@@ -0,0 +1,35 @@
+/**
+ * The kind cue: in a mode that hides markers, a keystroke that turns its block into another kind
+ * leaves the new kind's name at the block's corner for a moment and says it once to a screen
+ * reader, so the change has a visible cause. Only typed text reports here, never a command.
+ */
+import { SvelteMap } from 'svelte/reactivity';
+import { shownKind } from '../core/parsers/heading';
+import { blockAccessibleName } from '../a11y-strings';
+import { hidesMarkers } from '../presentation-mode';
+import { blockNodeAt } from '../tree-operations/node-primitives';
+export function createKindCue(deps) {
+    const labels = new SvelteMap();
+    const keyOf = (path) => path.join(',');
+    return {
+        async afterTypedWrite(write, path, before) {
+            await write;
+            // Source mode draws the markers that explain the change; reading mode cannot type.
+            if (!hidesMarkers(deps.getPresentationMode()))
+                return;
+            const after = blockNodeAt(deps.getDoc(), [...path]);
+            if (!after || shownKind(after) === before)
+                return;
+            const label = blockAccessibleName(after);
+            labels.set(keyOf(path), label);
+            deps.announce(label);
+        },
+        // Keyed by path, so the label shows only while the block there still carries that name.
+        labelAt(path) {
+            const label = labels.get(keyOf(path));
+            const node = label === undefined ? undefined : blockNodeAt(deps.getDoc(), [...path]);
+            return node && blockAccessibleName(node) === label ? label : undefined;
+        },
+        dismiss: (path) => void labels.delete(keyOf(path))
+    };
+}