@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/image/ImageProperties.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
 	import type { ImageCrop, ImageFields } from '../../core/nodes';
-	import { IMAGE_CHROME_SELECTOR, type WidgetTarget } from './widget-selection-state.svelte';
+	import { pressLeavesImage } from './widget-selection-state.svelte';
+	import type { WidgetTarget } from '../../selection/primitives';
 	import {
 		IMAGE_ALT_FIELD,
 		IMAGE_ALT_PLACEHOLDER,
@@ -12,6 +13,7 @@
 		IMAGE_REMOVE
 	} from '../../a11y-strings';
 	import MenuIcon from '../menu/MenuIcon.svelte';
+	import type { MenuPresence } from '../menu/menu-presence.svelte';
 	import { DEFAULT_CROP, applyCropToWidget, panCrop, zoomCrop, type Size } from './image-crop';
 
 	let {
@@ -23,19 +25,24 @@
 		onRemove,
 		onDismiss,
 		maxFrameWidth,
+		menuPresence,
 		cropping = $bindable(false)
 	}: {
 		target: WidgetTarget;
 		fields: ImageFields;
 		getWidgetEl: () => HTMLElement | null;
-		/** The popover's dirty check is a byte comparison, and the bytes are the write
-		 *  seam's to decide. */
+		/** The popover decides it has changes by comparing bytes, and what those bytes are
+		 *  is the image write path's to decide. */
 		buildBytes: (target: WidgetTarget, fields: ImageFields) => string | null;
-		onCommit: (target: WidgetTarget, newFields: ImageFields) => void;
+		/** `fields` goes back with each write, so a draft for an image the document has since
+		 *  replaced is dropped. */
+		onCommit: (target: WidgetTarget, seenFields: ImageFields, newFields: ImageFields) => void;
 		onRemove: (target: WidgetTarget) => void;
 		onDismiss: () => void;
 		/** The column width: the widest frame a corner drag can open. */
 		maxFrameWidth: () => number;
+		/** The alt field is a popover over the document, so it counts as an open menu. */
+		menuPresence: MenuPresence;
 		cropping?: boolean;
 	} = $props();
 
@@ -45,13 +52,12 @@
 	let rootEl: HTMLDivElement | undefined = $state();
 	let fieldInput: HTMLInputElement | undefined = $state();
 
-	// The seed is the BYTES, not the fields object: a rebuild mints a fresh one per render, so
-	// identity says nothing about whether the image moved.
+	// The starting point is the bytes, not the fields object: a rebuild creates a fresh object
+	// every render, so its identity says nothing about whether the image changed.
 	let seedBytes = $state(untrack(() => buildBytes(target, fields)));
 
-	// The surface follows the document while it is open: an undo — or any write landing from
-	// outside this gesture — moves the image past the draft, and the dismiss commit would put the
-	// old bytes back. The in-flight draft is discarded rather than a committed change reverted.
+	// A write from outside the popover while it stays open (a find-bar replace) discards the
+	// draft, or an edit to it would put the earlier bytes back.
 	$effect(() => {
 		const live = buildBytes(target, fields);
 		if (live === seedBytes) return;
@@ -62,17 +68,14 @@
 	$effect(() => {
 		if (!rootEl) return;
 		const handler = (e: PointerEvent) => {
-			const target = e.target as Element | null;
-			if (target?.closest(IMAGE_CHROME_SELECTOR)) return;
-			onDismiss();
+			if (pressLeavesImage(e, getWidgetEl()?.closest('.editor') ?? null)) onDismiss();
 		};
 		document.addEventListener('pointerdown', handler, true);
 		return () => document.removeEventListener('pointerdown', handler, true);
 	});
 
-	// The commit runs in $effect cleanup so dismiss, image-switch (key change) and
-	// programmatic clear all commit through one seam. A crop still open is abandoned, not
-	// committed: only the tick writes one.
+	// In the effect's cleanup, so every way the popover closes commits here; an open crop is
+	// abandoned, since only the tick button writes one.
 	$effect(() => {
 		return () => {
 			if (cropping) cancelCrop();
@@ -87,7 +90,7 @@
 	// ── Alt ────────────────────────────────────────────────────────────────────
 
 	// The title (`![alt](url "title")`) has no field: it is a tooltip nobody reads in an editor,
-	// and an existing one rides through every commit untouched, as do the url, frame and crop.
+	// and an existing one passes through every commit untouched, as do the url, frame and crop.
 	function draftFields(): ImageFields {
 		return {
 			alt,
@@ -103,10 +106,10 @@
 		const next = draftFields();
 		const newBytes = buildBytes(target, next);
 		if (newBytes === seedBytes) return;
-		// Seeded now rather than when the write lands, so a blur and the unmount that follows
+		// Set now rather than when the write lands, so a blur and the unmount that follows
 		// it cannot commit the same draft twice.
 		seedBytes = newBytes;
-		onCommit(target, next);
+		onCommit(target, fields, next);
 	}
 
 	function toggleField() {
@@ -132,9 +135,8 @@
 	}
 
 	// ── Crop ───────────────────────────────────────────────────────────────────
-	// limestone's cover crop: drag pans, the wheel zooms, corner brackets mark the frame, and
-	// the tick writes it. The frame is the box the image has right now, so an unframed image
-	// gains `|WxH` on its first crop.
+	// Drag pans, the wheel zooms, the corners resize the frame, the tick writes it. The frame
+	// starts as the image's current box, so an unframed image gains `|WxH` on its first crop.
 
 	let draft = $state<ImageCrop>(DEFAULT_CROP);
 	let frame: Size = { width: 0, height: 0 };
@@ -200,11 +202,11 @@
 			height: Math.round(frame.height),
 			crop: draft
 		};
-		// The commit rebuilds the widget from the bytes; the preview styles go with the old DOM.
+		// The commit rebuilds the widget from the bytes; the preview styles go with the replaced DOM.
 		snapshot = null;
 		cropping = false;
 		seedBytes = buildBytes(target, next);
-		onCommit(target, next);
+		onCommit(target, fields, next);
 	}
 
 	function onCropPointerDown(e: PointerEvent) {
@@ -231,10 +233,8 @@
 		paintDraft();
 	}
 
-	// The corner brackets resize the frame itself, which is what changes its aspect. The frame
-	// is anchored where the image sits in the flow, so every corner moves the far edges: a
-	// left-hand corner dragged inward shrinks the width the way the right-hand one dragged
-	// inward does.
+	// The frame stays anchored in the flow, so every corner moves the far edges: a left corner
+	// dragged inward shrinks the width as a right one does.
 	type Corner = 'tl' | 'tr' | 'bl' | 'br';
 	const MIN_FRAME = 32;
 	let cornerDrag: { corner: Corner; startX: number; startY: number; start: Size } | null = null;
@@ -266,9 +266,8 @@
 		cornerDrag = null;
 	}
 
-	// A double click on the picture is the crop gesture: the first click selects the image, so
-	// by the second the toolbar (and this listener) is already mounted. On the document, since
-	// each commit rebuilds the widget and a listener bound to one goes stale with it.
+	// A double click on the picture starts a crop. On the document, since each commit rebuilds
+	// the widget and a listener bound to it would go stale.
 	$effect(() => {
 		const onDoubleClick = (e: MouseEvent) => {
 			if (cropping) return;
@@ -301,9 +300,8 @@
 
 	// ── Placement ──────────────────────────────────────────────────────────────
 
-	/** Beside the image, level with its top, when the viewport has room there; otherwise a row
-	 *  inside the image's top-right corner, clamped to the viewport when the image itself runs
-	 *  past it. Re-measured whenever the overlay re-anchors. */
+	/** Beside the image, level with its top, when there is room; otherwise a row inside its
+	 *  top-right corner, clamped to the viewport. Re-measured whenever the overlay moves. */
 	function keepBesideImage(node: HTMLElement): (() => void) | void {
 		const place = () => {
 			node.classList.remove('inside');
@@ -425,7 +423,7 @@
 		</button>
 	{/if}
 	{#if fieldOpen}
-		<label class="md-image-field" {@attach keepFieldOnScreen}>
+		<label class="md-image-field" {@attach keepFieldOnScreen} {@attach menuPresence.track}>
 			<span class="md-image-field-label">Alt</span>
 			<input
 				type="text"
@@ -440,8 +438,8 @@
 </div>
 
 <style>
-	/* limestone's cover actions: a stack of small surface buttons beside the image, level with
-	   its top. `inside` (no room beside) lays them as a row in the image's top-right corner. */
+	/* Small raised buttons beside the image, level with its top; `inside` (no room beside)
+	   lays them as a row in the image's top-right corner. */
 	.md-image-properties {
 		position: absolute;
 		top: 0;
@@ -481,8 +479,7 @@
 		background: var(--color-surface, #2d3033);
 	}
 
-	/* The alt field, hung off the toolbar's far side on the menu surface: a caption over its
-	   input, the way a properties row reads, rather than a label beside a box. */
+	/* The alt field hangs off the toolbar's far side: a caption over its input. */
 	.md-image-field {
 		position: absolute;
 		top: 0;
@@ -515,8 +512,7 @@
 		color: var(--color-text-muted, #aaaaaa);
 	}
 
-	/* Underlined, not boxed: one rule under the text reads as a field to fill in and keeps the
-	   surface calm, where a second rounded box inside a rounded card reads as chrome on chrome. */
+	/* Underlined, not boxed: a box inside the rounded panel would read as a frame in a frame. */
 	.md-image-field input {
 		width: 100%;
 		box-sizing: border-box;
@@ -539,7 +535,7 @@
 		color: var(--color-text-muted, #aaaaaa);
 	}
 
-	/* The crop session: the whole image is a pan surface, bracketed at the corners. */
+	/* While cropping: the whole image can be dragged to pan, with brackets at the corners. */
 	.md-image-crop-surface {
 		position: absolute;
 		inset: 0;

package/dist/components/image/ImageProperties.svelte.d.ts

@@ -1,17 +1,22 @@
 import type { ImageFields } from '../../core/nodes';
-import { type WidgetTarget } from './widget-selection-state.svelte';
+import type { WidgetTarget } from '../../selection/primitives';
+import type { MenuPresence } from '../menu/menu-presence.svelte';
 type $$ComponentProps = {
     target: WidgetTarget;
     fields: ImageFields;
     getWidgetEl: () => HTMLElement | null;
-    /** The popover's dirty check is a byte comparison, and the bytes are the write
-     *  seam's to decide. */
+    /** The popover decides it has changes by comparing bytes, and what those bytes are
+     *  is the image write path's to decide. */
     buildBytes: (target: WidgetTarget, fields: ImageFields) => string | null;
-    onCommit: (target: WidgetTarget, newFields: ImageFields) => void;
+    /** `fields` goes back with each write, so a draft for an image the document has since
+     *  replaced is dropped. */
+    onCommit: (target: WidgetTarget, seenFields: ImageFields, newFields: ImageFields) => void;
     onRemove: (target: WidgetTarget) => void;
     onDismiss: () => void;
     /** The column width: the widest frame a corner drag can open. */
     maxFrameWidth: () => number;
+    /** The alt field is a popover over the document, so it counts as an open menu. */
+    menuPresence: MenuPresence;
     cropping?: boolean;
 };
 declare const ImageProperties: import("svelte").Component<$$ComponentProps, {}, "cropping">;

package/dist/components/image/ImageResizeHandles.svelte

@@ -26,9 +26,8 @@
 		currentWidth: number;
 	} | null = $state(null);
 
-	// `md-image-broken` is toggled imperatively on the widget, which Svelte doesn't
-	// track, so a MutationObserver mirrors it into reactive state. Each commit rebuilds
-	// the widget DOM, so the observer re-attaches on every edit event.
+	// Mirrors the widget's `md-image-broken` class into state; re-attached on every edit, since
+	// each commit rebuilds the widget.
 	let isBroken = $state(false);
 	$effect(() => {
 		let observer: MutationObserver | null = null;
@@ -64,12 +63,8 @@
 		return getWidgetEl()?.querySelector('img') ?? null;
 	}
 
-	/**
-	 * What the drag measures and previews on. A cropped image is a FRAME (the widget) with the
-	 * picture panned inside it, so the `<img>` is neither the size being changed nor the box the
-	 * user is dragging: previewing on it bulges the picture out of its frame, and at a zoom above
-	 * 1 the drag would start from the painted image's width and jump.
-	 */
+	// A cropped image resizes its frame (the widget), not the `<img>` panned inside it, which
+	// would bulge out of the frame and, zoomed, start the drag from the wrong width.
 	function isCropped(): boolean {
 		return getWidgetEl()?.classList.contains('md-image-cropped') ?? false;
 	}
@@ -94,9 +89,8 @@
 			startWidth,
 			startHeight,
 			naturalWidth: img.naturalWidth,
-			// A crop's frame keeps its shape through a resize (`commitImageResize` derives the
-			// height from it), so Shift has nothing to unlock here; the crop session's corner
-			// brackets are where a frame's aspect changes.
+			// A crop's frame keeps its shape through a resize, so Shift unlocks nothing; the crop
+			// corners are where a frame's shape changes.
 			aspectLocked: isCropped() || !e.shiftKey,
 			currentWidth: startWidth
 		};
@@ -104,9 +98,8 @@
 
 	function moveDrag(e: PointerEvent) {
 		if (!dragState) return;
-		// Reflow mid-drag (a sibling image settling, a scrollbar appearing) can
-		// transiently zero the content width; hold the last good width instead of
-		// snapping the image to nothing.
+		// Reflow mid-drag can briefly zero the content width; the last good width holds rather
+		// than snapping the image to nothing.
 		if (editorContentWidth < MIN_WIDTH) return;
 		const dx = e.clientX - dragState.startX;
 		const proposed = dragState.startWidth + dx;
@@ -116,9 +109,8 @@
 		const preview = previewEl();
 		if (!preview) return;
 		preview.style.width = `${snapped}px`;
-		// Shift unlocks the aspect: the height stays where the user found it and the image
-		// distorts. Locked, the frame's own `aspect-ratio` (cropped) or the stylesheet's
-		// `height: auto` (plain) derives it from the new width.
+		// Unlocked, the height stays put and the image distorts; locked, the frame's `aspect-ratio`
+		// or the stylesheet's `height: auto` derives it from the width.
 		preview.style.height = dragState.aspectLocked ? '' : `${dragState.startHeight}px`;
 	}
 
@@ -173,8 +165,8 @@
 	}
 </script>
 
-<!-- One grip, on the right edge: width is the only thing a drag sets (Shift unlocks the
-	aspect), so a second corner grip was the same gesture twice. -->
+<!-- One handle, on the right edge: width is the only thing a drag sets (Shift unlocks the
+	aspect ratio), so a second corner handle would be the same gesture twice. -->
 {#if !isBroken}
 	<div
 		class="md-resize-handle md-resize-handle-right"
@@ -187,12 +179,8 @@
 {/if}
 
 <style>
-	/* A neutral grip sitting inside the picture's right edge: the selection ring owns the edge
-	   itself, and the accent is the ring's, so a second accent shape beside it reads as decoration
-	   rather than as a control. White over a hairline rim so it carries on a dark picture and a
-	   pale one alike. The hit strip is wider than the paint, so on a picture too narrow to hold
-	   both the strip and a clickable middle (an icon-sized image) the grip steps back outside
-	   the edge, where it stood before. */
+	/* White over a hairline rim, inside the right edge, so it shows on any picture without
+	   competing with the accent selection ring; on an icon-sized image it moves outside the edge. */
 	.md-resize-handle {
 		position: absolute;
 		right: clamp(-3px, calc(50% - 20px), 7px);

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

@@ -1,10 +1,7 @@
 /**
- * Pure math for the image crop: how a `{x, y, z}` window maps to the styles that paint it, and
- * how a pan or a wheel turn moves it. No DOM here beyond a style bag; the properties surface
- * owns the pointer events and `widget-dom.ts` paints a committed crop from the same styles.
- *
- * The model is CSS `background-size: cover` at `z` times the fill scale, with the image point
- * (`x`%, `y`%) pinned to that point of the frame, so `{50, 50, 1}` is a centred cover fit.
+ * Pure math for the image crop: the styles a `{x, y, z}` window paints with, and how a pan or a
+ * wheel turn moves it. The model is a cover fit scaled by `z`, with the image point (`x`%, `y`%)
+ * pinned to the same point of the frame, so `{50, 50, 1}` is a centred cover fit.
  */
 import type { ImageCrop } from '../../core/nodes';
 export declare const DEFAULT_CROP: ImageCrop;
@@ -13,11 +10,8 @@ export interface Size {
     height: number;
 }
 export declare function clampCrop(crop: ImageCrop): ImageCrop;
-/**
- * The styles an `<img>` inside an `overflow: hidden` frame takes. The image box is `z` times
- * the frame with `object-fit: cover`, offset so the pinned point stays put: at `z` 1 the offset
- * is zero and `object-position` alone pans the cover overflow.
- */
+/** The image box is `z` times the frame with `object-fit: cover`, offset so the pinned point
+ *  stays put; at `z` 1 the offset is zero and `object-position` alone pans. */
 export declare function cropImageStyle(crop: ImageCrop): {
     width: string;
     height: string;

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

@@ -1,10 +1,7 @@
 /**
- * Pure math for the image crop: how a `{x, y, z}` window maps to the styles that paint it, and
- * how a pan or a wheel turn moves it. No DOM here beyond a style bag; the properties surface
- * owns the pointer events and `widget-dom.ts` paints a committed crop from the same styles.
- *
- * The model is CSS `background-size: cover` at `z` times the fill scale, with the image point
- * (`x`%, `y`%) pinned to that point of the frame, so `{50, 50, 1}` is a centred cover fit.
+ * Pure math for the image crop: the styles a `{x, y, z}` window paints with, and how a pan or a
+ * wheel turn moves it. The model is a cover fit scaled by `z`, with the image point (`x`%, `y`%)
+ * pinned to the same point of the frame, so `{50, 50, 1}` is a centred cover fit.
  */
 import { MAX_CROP_ZOOM } from '../../core/inline/image-dimensions';
 export const DEFAULT_CROP = { x: 50, y: 50, z: 1 };
@@ -15,11 +12,8 @@ export function clampCrop(crop) {
         z: Math.min(MAX_CROP_ZOOM, Math.max(1, crop.z))
     };
 }
-/**
- * The styles an `<img>` inside an `overflow: hidden` frame takes. The image box is `z` times
- * the frame with `object-fit: cover`, offset so the pinned point stays put: at `z` 1 the offset
- * is zero and `object-position` alone pans the cover overflow.
- */
+/** The image box is `z` times the frame with `object-fit: cover`, offset so the pinned point
+ *  stays put; at `z` 1 the offset is zero and `object-position` alone pans. */
 export function cropImageStyle(crop) {
     const c = clampCrop(crop);
     const pct = (n) => `${Math.round(n * 1000) / 1000}%`;

package/dist/components/image/image-edit-commit.d.ts

@@ -1,18 +1,21 @@
 import type { Document, ImageFields, InlineNode } from '../../core/nodes';
-import type { LinkReferenceResolverRef } from '../../editor-keys';
-import type { UndoController } from '../../editor-actions/deps';
+import type { InlineRangeCommit } from '../../editor-actions/inline-range-commit';
 import type { EditorEvents } from '../../editor-events';
-import type { GrammarView } from '../../schema/block-openers';
-import type { WidgetSelectionState, WidgetTarget } from './widget-selection-state.svelte';
+import type { WidgetSelectionState } from './widget-selection-state.svelte';
+import type { WidgetTarget } from '../../selection/primitives';
+import type { Reading } from '../../schema/reading';
+/** The image `target` names in `doc`, or null once no image starts at its bytes. */
+export declare function imageAtTarget(doc: Document, target: WidgetTarget, reading: Reading): InlineNode | null;
 export interface ImageEditCommitterDeps {
     getDoc: () => Document;
     getEditorEl: () => HTMLElement | null;
     widgetSelection: WidgetSelectionState;
-    controller: UndoController;
+    /** The editor's inline range write, which every popover edit goes through. */
+    inlineRange: InlineRangeCommit;
     events: EditorEvents;
-    linkRef?: LinkReferenceResolverRef;
-    /** The instance's grammar, for the leaf's own raw-write rule. Absent = the global grammar. */
-    grammar?: GrammarView;
+    /** How the editor reads its bytes: the image is found in the block as drawn, and the block's
+     *  own raw-write rule reads its grammar. */
+    reading: Reading;
 }
 export interface SelectedImageFields {
     image: InlineNode;
@@ -20,20 +23,20 @@ export interface SelectedImageFields {
 }
 export interface ImageEditCommitter {
     getSelectedImageFields(): SelectedImageFields | null;
-    /**
-     * `target` is captured at popover-mount time, not read from the live
-     * widgetSelection: a popover commit can fire after the user clicked a different
-     * widget, and writing to the new selection cross-pollinates the two images.
-     */
-    commitImageEdit(target: WidgetTarget, newFields: ImageFields): void;
-    /** The bytes `commitImageEdit` would write, or `null` if it would decline — the
-     *  popover's dirty check compares against these. */
+    /** Writes only if the image at `target` still reads as `seenFields`, the image the popover
+     *  last showed, so a draft never lands on another image. */
+    commitImageEdit(target: WidgetTarget, seenFields: ImageFields, newFields: ImageFields): void;
+    /** The bytes `commitImageEdit` would write, or `null` if it would refuse; the popover
+     *  compares against these to see whether anything changed. */
     buildEditBytes(target: WidgetTarget, newFields: ImageFields): string | null;
     commitImageResize(newWidth: number, newHeight: number | undefined): void;
     removeImage(target: WidgetTarget): void;
     dismissImagePopover(): void;
     getEditorContentWidth(): number;
     attachWidgetSelectListener(): () => void;
+    /** Clears the widget selection once no image starts at its bytes; commits to this image or
+     *  to one before it keep it selected. */
+    clearStaleSelection(): void;
     syncOverlayToWidget(getOverlay: () => HTMLElement | null): () => void;
 }
 export declare function createImageEditCommitter(deps: ImageEditCommitterDeps): ImageEditCommitter;

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;
+}