@memorysmithapp/markdown-renderer 0.7.0 → 0.8.0

package/dist/edit/blocks.js

@@ -17,8 +17,8 @@ import { isTrue, readProperties } from '../properties.js';
 import { Transclusion } from '../Transclusion.js';
 import { splitEmbeds } from '../transclusion.js';
 import { wikilinkAddress } from '../wikilink-address.js';
-import { ICON_OWN_SIZE } from '../mode-icons.js';
-import { MAX_IMAGE_WIDTH, readImageSize, resizeImage } from './image-size.js';
+import { ICON_OWN_SIZE, ICON_RATIO_FREE, ICON_RATIO_LOCKED, ICON_RESIZE } from '../mode-icons.js';
+import { describeImage, MAX_IMAGE_WIDTH, readImageSize, resizeImage } from './image-size.js';
 import { addEntry, readFrontmatter, removeEntry, renameKey, setList, setScalar, } from './frontmatter.js';
 import { addColumn, addRow, alignColumn, columnCount, readTable, removeColumn, removeRow, setCell, } from './table.js';
 /** Whether a block's edit is being applied: the block is drawn anew, and the field it held lets the focus go. */
@@ -54,8 +54,8 @@ export function Snippet({ text }) {
     return (_jsx(_Fragment, { children: splitEmbeds(body, host.keeps).map((segment, index) => segment.kind === 'text' ? (_jsx(Markdown, { children: resolveWikilinks(segment.text, (name) => wikilinkAddress(host, name), host.keeps) }, index)) : (_jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index))) }));
 }
 /** A small button of the editor's own, outside the note's notation. */
-function Control({ label, onClick, children, pressed }) {
-    return (_jsx("button", { type: "button", className: "edit-control", title: label, "aria-label": label, "aria-pressed": pressed, "data-ms-control": "", onMouseDown: (event) => event.preventDefault(), onClick: onClick, children: children }));
+function Control({ label, onClick, children, pressed, disabled, focusable = false, }) {
+    return (_jsx("button", { type: "button", className: "edit-control", title: label, "aria-label": label, "aria-pressed": pressed, disabled: disabled, "data-ms-control": "", onMouseDown: focusable ? undefined : (event) => event.preventDefault(), onClick: onClick, children: children }));
 }
 // ── Callouts ─────────────────────────────────────────────────────────────────
 /** The types a callout may take from the toolbar: the families the default theme draws. */
@@ -74,14 +74,67 @@ export function CalloutBlock({ view, text, marker }) {
     return (_jsxs("div", { className: "edit-block edit-callout", children: [_jsxs("div", { className: "edit-block-controls", "data-ms-control": "", children: [_jsx("select", { "aria-label": words.calloutType, title: words.calloutType, value: marker.type, onChange: (event) => rewrite(event.target.value, marker.fold), children: types.map((type) => (_jsx("option", { value: type, children: strings.callouts[type] ?? type }, type))) }), _jsxs("select", { "aria-label": words.fold, title: words.fold, value: marker.fold ?? '', onChange: (event) => rewrite(marker.type, (event.target.value || null)), children: [_jsx("option", { value: "", children: words.foldNone }), _jsx("option", { value: "+", children: words.foldOpen }), _jsx("option", { value: "-", children: words.foldClosed })] })] }), _jsx(Snippet, { text: text })] }));
 }
 // ── Images ───────────────────────────────────────────────────────────────────
-/** The narrowest an image is dragged to, so its handle stays within reach. */
-const MIN_DRAGGED_WIDTH = 24;
+/** The narrowest an image is sized to, by a field or the handle: something a reader still sees (#105). */
+export const MIN_IMAGE_SIZE = 16;
+/** How long after a pointer or a touch on its controls a click on the image is not taken as one to edit its source (#107). */
+const CONTROLS_GUARD_MS = 800;
+/** How long after a control of an image writes the image is held where it was on the screen (#107). */
+const SCROLL_HOLD_MS = 600;
+/** A move of the image larger than this, in that moment, is the browser's and not the author's. */
+const SCROLL_JUMP = 120;
 /**
- * An image drawn in edit mode with the size it is drawn at set in place (#98): a width in pixels,
- * its height following, a handle at its corner that drags it, and a button back to its own size.
- * Each writes the dimensions of its notation — `![description|300](…)` or `![[photo.jpg|300]]` —
- * and no other byte. The controls appear once an image is drawn inside it, so an embed of a file
- * that is not an image, or a host's own drawing without one, offers none.
+ * Holds the image where it is on the screen while one of its controls writes (#107). The write draws
+ * the image again for its new source, which takes the control that had the focus out of the page,
+ * and Chrome on a touch screen then scrolls the page a screen or more away, with no script asking
+ * it to: the image and its controls were gone from sight (*observed* in the playground, Pixel 7,
+ * 2026-10-16). For a moment after the write, a move of the image larger than a jump is undone, by
+ * scrolling what the editor scrolls in — a pane of the host, or the window — by as much.
+ */
+function holdInPlace(view, block, run) {
+    const top = block.getBoundingClientRect().top;
+    let scroller = view.scrollDOM;
+    while (scroller && !(scroller.scrollHeight > scroller.clientHeight && /(auto|scroll)/.test(getComputedStyle(scroller).overflowY)))
+        scroller = scroller.parentElement;
+    const scrolled = () => (scroller ? scroller.scrollTop : window.scrollY);
+    const before = scrolled();
+    const back = () => {
+        // The editor lets go of a block it scrolled out of its viewport: the page goes back to where it was.
+        const moved = block.isConnected ? block.getBoundingClientRect().top - top : before - scrolled();
+        if (Math.abs(moved) <= SCROLL_JUMP)
+            return;
+        if (scroller)
+            scroller.scrollBy(0, moved);
+        else
+            window.scrollBy(0, moved);
+    };
+    run();
+    window.addEventListener('scroll', back, true);
+    setTimeout(() => window.removeEventListener('scroll', back, true), SCROLL_HOLD_MS);
+}
+/** A number as a field holds it: digits and nothing else, or `null`. */
+function wholeNumber(text) {
+    return /^\d{1,6}$/.test(text.trim()) ? Number(text.trim()) : null;
+}
+/**
+ * An image drawn in edit mode with what its notation writes set in place (#98, #106): its width and
+ * its height with a lock between them — locked, the height follows and only the width is written,
+ * `|300`; open, both are, `|300x180` — the width's unit, pixels or a share of the page (`|50%`,
+ * #108), its description for a Markdown image, a button back to its own size, and a handle at its
+ * corner that drags it, keeping the proportion or, with the lock open or Shift held, not. Each
+ * writes the dimensions or the description of its notation, and no other byte.
+ *
+ * A field selects what it holds when it takes the focus, so typing replaces it, and writes on Enter
+ * or when it is left; Escape leaves the note as it is. A value outside the range a reader can see
+ * — from 16 pixels to the column or the image's own width, the wider — is refused where it was
+ * typed, never brought into the range and written (#105).
+ *
+ * The controls stand under the picture, never over it, and nothing that starts on them or in the
+ * moment after reaches the click that shows the image's source (#107): they are all marked as
+ * controls, gaps included, and the frame is marked busy while one of them has the focus, while the
+ * handle is dragged and for a moment after a pointer or a touch on them.
+ *
+ * The controls appear once an image is drawn inside it, so an embed of a file that is not an image,
+ * or a host's own drawing without one, offers none.
  */
 export function ImageBlock({ view, source, children }) {
     const words = useHost().strings.editor;
@@ -89,9 +142,14 @@ export function ImageBlock({ view, source, children }) {
     const size = readImageSize(source);
     const [image, setImage] = useState(null);
     const [natural, setNatural] = useState(null);
-    const [typed, setTyped] = useState(null);
+    const [locked, setLocked] = useState(() => size?.height == null);
+    const [unit, setUnit] = useState(() => (size?.percent == null ? 'px' : '%'));
+    const [typed, setTyped] = useState({});
+    const [refused, setRefused] = useState(null);
     const [dragged, setDragged] = useState(null);
+    const [shift, setShift] = useState(false);
     const drag = useRef(null);
+    const guard = useRef(null);
     // An embed's image arrives when the host answers; the controls wait for it.
     useEffect(() => {
         const element = frame.current;
@@ -108,74 +166,288 @@ export function ImageBlock({ view, source, children }) {
     useEffect(() => {
         if (!image)
             return;
-        const read = () => setNatural(image.naturalWidth || null);
+        const read = () => setNatural(image.naturalWidth && image.naturalHeight ? { width: image.naturalWidth, height: image.naturalHeight } : null);
         read();
         image.addEventListener('load', read);
         return () => image.removeEventListener('load', read);
     }, [image]);
-    const resize = (width) => {
+    useEffect(() => () => {
+        if (guard.current)
+            clearTimeout(guard.current);
+    }, []);
+    // The handle and the controls are placed by the picture itself, not by the frame, which also holds
+    // its margins and, in an embed, a paragraph's: its bottom right corner is where the handle goes.
+    useEffect(() => {
+        const element = frame.current;
+        if (!image || !element)
+            return;
+        const place = () => {
+            const outer = element.getBoundingClientRect();
+            const inner = image.getBoundingClientRect();
+            element.style.setProperty('--edit-image-bottom', `${Math.round(inner.bottom - outer.top)}px`);
+            element.style.setProperty('--edit-image-right', `${Math.round(inner.right - outer.left)}px`);
+        };
+        place();
+        image.addEventListener('load', place);
+        if (typeof ResizeObserver === 'undefined')
+            return () => image.removeEventListener('load', place);
+        const observer = new ResizeObserver(place);
+        observer.observe(image);
+        observer.observe(element);
+        return () => {
+            image.removeEventListener('load', place);
+            observer.disconnect();
+        };
+    }, [image]);
+    /** Marks the frame busy for a moment, so the click a touch or a pointer leaves behind reveals nothing (#107). */
+    const hold = () => {
+        const element = frame.current;
+        if (!element)
+            return;
+        element.dataset['msBusy'] = '';
+        if (guard.current)
+            clearTimeout(guard.current);
+        guard.current = setTimeout(() => {
+            if (!element.matches(':focus-within') && !drag.current)
+                delete element.dataset['msBusy'];
+        }, CONTROLS_GUARD_MS);
+    };
+    /** The width the note is read at, where the image stands: what a share of the page is a share of. */
+    const column = () => {
+        const content = frame.current?.closest('.cm-content') ?? null;
+        const width = content ? content.clientWidth - parseFloat(getComputedStyle(content).paddingLeft || '0') - parseFloat(getComputedStyle(content).paddingRight || '0') : 0;
+        return width > 0 ? Math.round(width) : null;
+    };
+    /** The image as it is drawn now, or `null` before it is laid out. */
+    const drawn = () => {
+        const box = image?.getBoundingClientRect();
+        return box && box.width > 0 && box.height > 0 ? { width: Math.round(box.width), height: Math.round(box.height) } : null;
+    };
+    /** Its proportion, height over width: its own, else as it is drawn. */
+    const ratio = () => {
+        const shape = natural ?? drawn();
+        return shape ? shape.height / shape.width : null;
+    };
+    /** What a field accepts (#105): a share from 1% to 100%, or pixels a reader sees, up to the column or the image's own size. */
+    const rangeOf = (field) => {
+        if (field === 'width' && unit === '%')
+            return { min: 1, max: 100 };
+        const widest = Math.max(column() ?? 0, natural?.width ?? 0);
+        const width = widest > 0 ? widest : MAX_IMAGE_WIDTH;
+        if (field === 'width')
+            return { min: MIN_IMAGE_SIZE, max: width };
+        const proportion = ratio();
+        const tallest = Math.max(proportion === null ? 0 : Math.ceil(width * proportion), natural?.height ?? 0);
+        return { min: MIN_IMAGE_SIZE, max: tallest > 0 && widest > 0 ? tallest : MAX_IMAGE_WIDTH };
+    };
+    const apply = (changes) => {
         const widget = frame.current?.closest('.cm-ms-inline-block, .cm-ms-block');
-        if (!widget)
+        if (!widget || changes.length === 0)
             return;
         const from = view.posAtDOM(widget);
         // The widget stands where its source was: anything else means the note moved under it.
         if (view.state.sliceDoc(from, from + source.length) !== source)
             return;
-        write(view, resizeImage(source, from, width));
+        holdInPlace(view, widget, () => write(view, changes.map((change) => ({ ...change, from: change.from + from, to: change.to + from }))));
     };
-    const commitTyped = () => {
-        if (typed === null)
+    const resize = (dimensions) => apply(resizeImage(source, 0, dimensions));
+    /** The width it is written or drawn at, in pixels, for a height written beside it. */
+    const widthNow = () => size?.width ?? drawn()?.width ?? natural?.width ?? null;
+    /** Writes what a field holds, or refuses it in place; `true` when the field may let go of what was typed. */
+    const commit = (field) => {
+        const text = typed[field];
+        if (text === undefined)
+            return true;
+        if (text.trim() === '') {
+            // Empty is "not set": no width is its own size, no height a width alone (#106).
+            setTyped((now) => ({ ...now, [field]: undefined }));
+            setRefused(null);
+            if (field === 'width')
+                resize(null);
+            else if (size?.width != null)
+                resize({ width: size.width, height: null, percent: null });
+            return true;
+        }
+        const value = wholeNumber(text);
+        const range = rangeOf(field);
+        if (value === null || value < range.min || value > range.max) {
+            setRefused({ field, range });
+            return false;
+        }
+        setRefused(null);
+        setTyped((now) => ({ ...now, [field]: undefined }));
+        if (field === 'width') {
+            if (unit === '%')
+                resize({ width: null, height: null, percent: value });
+            else if (locked)
+                resize({ width: value, height: null, percent: null });
+            else
+                resize({ width: value, height: size?.height ?? drawn()?.height ?? null, percent: null });
+        }
+        else if (locked) {
+            // A height typed under the lock sets the width that draws it, and only the width is written.
+            const proportion = ratio();
+            if (proportion !== null)
+                resize({ width: Math.max(1, Math.round(value / proportion)), height: null, percent: null });
+        }
+        else {
+            const width = widthNow();
+            if (width !== null)
+                resize({ width, height: value, percent: null });
+        }
+        return true;
+    };
+    const commitDescription = () => {
+        const text = typed.description;
+        if (text === undefined)
             return;
-        const width = Number(typed.trim());
-        setTyped(null);
-        if (typed.trim() === '')
-            resize(null);
-        else if (Number.isFinite(width) && width >= 1)
-            resize(width);
+        setTyped((now) => ({ ...now, description: undefined }));
+        apply(describeImage(source, 0, text));
     };
-    const onKeyDown = (event) => {
-        if (event.key === 'Enter') {
-            event.preventDefault();
-            commitTyped();
+    const field = (name) => ({
+        onChange: (event) => {
+            const value = event.target.value;
+            setTyped((now) => ({ ...now, [name]: value }));
+            if (refused?.field === name)
+                setRefused(null);
+        },
+        // Whatever takes it there — a click, a double click, Tab — the value is selected, so what is typed replaces it (#105).
+        onFocus: (event) => event.currentTarget.select(),
+        onMouseUp: (event) => {
+            const input = event.currentTarget;
+            if (document.activeElement === input && input.selectionStart === input.selectionEnd && typed[name] === undefined) {
+                event.preventDefault();
+                input.select();
+            }
+        },
+        onDoubleClick: (event) => event.currentTarget.select(),
+        onKeyDown: (event) => {
+            if (event.key === 'Enter') {
+                event.preventDefault();
+                if (name === 'description')
+                    commitDescription();
+                else if (commit(name))
+                    event.currentTarget.select();
+            }
+            else if (event.key === 'Escape') {
+                event.preventDefault();
+                setTyped((now) => ({ ...now, [name]: undefined }));
+                setRefused(null);
+            }
+        },
+        onBlur: () => {
+            if (name === 'description')
+                commitDescription();
+            // A value refused is let go when the field is left, and the note keeps what it held.
+            else if (!commit(name)) {
+                setTyped((now) => ({ ...now, [name]: undefined }));
+                setRefused(null);
+            }
+        },
+    });
+    const toggleLock = () => {
+        const next = !locked;
+        setLocked(next);
+        // Locked, the height follows the width: one written beside it goes (#106).
+        if (next && size?.height != null && size.width !== null)
+            resize({ width: size.width, height: null, percent: null });
+    };
+    const chooseUnit = (next) => {
+        setUnit(next);
+        setTyped((now) => ({ ...now, width: undefined }));
+        setRefused(null);
+        const now = drawn();
+        const wide = column();
+        // The size it is drawn at, said in the other unit, when it has one.
+        if (next === '%' && size?.percent == null && size?.width != null && now && wide) {
+            resize({ width: null, height: null, percent: Math.min(100, Math.max(1, Math.round((now.width / wide) * 100))) });
         }
-        else if (event.key === 'Escape') {
-            event.preventDefault();
-            setTyped(null);
+        else if (next === 'px' && size?.percent != null && now) {
+            resize({ width: now.width, height: null, percent: null });
         }
+        if (next === '%')
+            setLocked(true);
+    };
+    const free = (!locked && unit === 'px') || shift;
+    const shownWidth = dragged ? (unit === '%' ? percentOf(dragged.width) : dragged.width) : unit === '%' ? size?.percent ?? null : size?.width ?? null;
+    const shownHeight = dragged ? dragged.height : size?.height ?? (locked && size?.width != null && ratio() !== null ? Math.round(size.width * ratio()) : null);
+    function percentOf(width) {
+        const wide = column();
+        return wide ? Math.min(100, Math.max(1, Math.round((width / wide) * 100))) : null;
+    }
+    const endDrag = (event, cancelled) => {
+        const start = drag.current;
+        if (!start || start.pointer !== event.pointerId)
+            return;
+        drag.current = null;
+        const end = drawn();
+        setDragged(null);
+        if (image) {
+            image.style.width = '';
+            image.style.height = '';
+            image.style.maxWidth = '';
+        }
+        hold();
+        if (cancelled || !end)
+            return;
+        if (Math.abs(end.width - start.width) < 1 && Math.abs(end.height - start.height) < 1)
+            return;
+        if (unit === '%') {
+            const percent = percentOf(end.width);
+            if (percent !== null)
+                resize({ width: null, height: null, percent });
+        }
+        else if (free || event.shiftKey)
+            resize({ width: end.width, height: end.height, percent: null });
+        else
+            resize({ width: end.width, height: null, percent: null });
     };
-    const shown = dragged ?? size?.width ?? null;
     const offered = size !== null && image !== null;
-    return (_jsxs("span", { ref: frame, className: "edit-image", "data-resizing": dragged === null ? undefined : '', children: [children, offered && (_jsxs(_Fragment, { children: [_jsxs("span", { className: "edit-block-controls edit-image-controls", "data-ms-control": "", children: [_jsx("input", { className: "edit-field edit-image-width", type: "number", inputMode: "numeric", min: 1, max: MAX_IMAGE_WIDTH, "aria-label": words.imageWidth, title: words.imageWidth, placeholder: natural === null ? '' : String(natural), value: typed ?? (shown === null ? '' : String(shown)), onChange: (event) => setTyped(event.target.value), onKeyDown: onKeyDown, onBlur: commitTyped }), _jsx("span", { className: "edit-image-unit", "aria-hidden": "true", children: "px" }), _jsx(Control, { label: words.imageOwnSize, onClick: () => resize(null), pressed: size.width === null, children: ICON_OWN_SIZE })] }), _jsx("span", { className: "edit-image-handle", "data-ms-control": "", title: words.imageResize, "aria-hidden": "true", onPointerDown: (event) => {
+    const unitWord = unit === '%' ? '%' : 'px';
+    const invalid = (name) => (refused?.field === name ? { 'aria-invalid': true, title: words.imageOutOfRange(refused.range.min, refused.range.max, name === 'width' ? unitWord : 'px') } : {});
+    return (_jsxs("span", { ref: frame, className: "edit-image", "data-resizing": dragged === null ? undefined : '', onFocus: () => frame.current && (frame.current.dataset['msBusy'] = ''), onBlur: hold, onMouseDown: (event) => {
+            // The frame's own area is the space between the picture and its controls: a press there is
+            // one meant for them, and shows nothing (#107).
+            if (event.target === event.currentTarget) {
+                event.preventDefault();
+                hold();
+            }
+        }, children: [children, offered && (_jsxs(_Fragment, { children: [_jsxs("span", { className: "edit-image-controls", "data-ms-control": "", onPointerDown: hold, onTouchStart: hold, onMouseDown: (event) => {
+                            // A press anywhere but on a field, a choice or a button — a gap between them, the
+                            // padding, a word beside a field — keeps the focus where it is. Its default would put
+                            // the editor's caret where the press fell, and the image would show its source (#107).
+                            if (!event.target.closest('input, select, textarea, button'))
+                                event.preventDefault();
+                        }, children: [size.description ? (_jsx("input", { className: "edit-field edit-image-description", type: "text", "aria-label": words.imageDescription, title: words.imageDescription, placeholder: image.alt, value: typed.description ?? size.description.text, ...field('description') })) : (
+                            // An embed writes no description (§5.8): the file's own is shown, and is not edited here.
+                            _jsx("input", { className: "edit-field edit-image-description", type: "text", readOnly: true, "aria-label": words.imageDescription, title: words.imageDescription, placeholder: image.alt, value: "" })), _jsxs("span", { className: "edit-image-size", children: [_jsx("input", { className: "edit-field edit-image-width", type: "text", inputMode: "numeric", autoComplete: "off", "aria-label": words.imageWidth, title: words.imageWidth, placeholder: unit === '%' ? '' : natural === null ? '' : String(natural.width), value: typed.width ?? (shownWidth === null ? '' : String(shownWidth)), ...field('width'), ...invalid('width') }), _jsxs("select", { className: "edit-image-unit", "aria-label": words.imageUnit, title: words.imageUnit, value: unit, onChange: (event) => chooseUnit(event.target.value), children: [_jsx("option", { value: "px", children: "px" }), _jsx("option", { value: "%", children: "%" })] }), _jsx(Control, { label: locked ? words.imageKeepRatio : words.imageFreeRatio, onClick: toggleLock, pressed: locked, disabled: unit === '%', focusable: true, children: locked ? ICON_RATIO_LOCKED : ICON_RATIO_FREE }), _jsx("input", { className: "edit-field edit-image-height", type: "text", inputMode: "numeric", autoComplete: "off", "aria-label": words.imageHeight, title: words.imageHeight, disabled: unit === '%', placeholder: natural === null || unit === '%' ? '' : String(natural.height), value: unit === '%' ? '' : (typed.height ?? (shownHeight === null ? '' : String(shownHeight))), ...field('height'), ...invalid('height') }), _jsx("span", { className: "edit-image-unit-label", "aria-hidden": "true", children: "px" }), _jsx(Control, { label: words.imageOwnSize, onClick: () => resize(null), pressed: size.width === null && size.percent === null, focusable: true, children: ICON_OWN_SIZE })] }), refused && (_jsx("span", { className: "edit-image-refused", role: "status", children: words.imageOutOfRange(refused.range.min, refused.range.max, refused.field === 'width' ? unitWord : 'px') }))] }), _jsx("span", { className: "edit-image-handle", "data-ms-control": "", "data-free": free ? '' : undefined, title: free ? words.imageResizeFree : words.imageResizeKeep, "aria-hidden": "true", onPointerDown: (event) => {
                             event.preventDefault();
+                            event.stopPropagation();
+                            const now = drawn();
+                            if (!now)
+                                return;
                             event.currentTarget.setPointerCapture?.(event.pointerId);
-                            drag.current = { x: event.clientX, width: image.getBoundingClientRect().width, pointer: event.pointerId };
-                            setDragged(Math.round(drag.current.width));
+                            drag.current = { x: event.clientX, y: event.clientY, ...now, pointer: event.pointerId };
+                            if (frame.current)
+                                frame.current.dataset['msBusy'] = '';
+                            setShift(event.shiftKey);
+                            setDragged(now);
                         }, onPointerMove: (event) => {
                             const start = drag.current;
-                            if (!start || start.pointer !== event.pointerId)
+                            if (!image || !start || start.pointer !== event.pointerId)
                                 return;
-                            const width = Math.max(MIN_DRAGGED_WIDTH, Math.round(start.width + event.clientX - start.x));
+                            setShift(event.shiftKey);
+                            const width = Math.max(MIN_IMAGE_SIZE, Math.round(start.width + event.clientX - start.x));
+                            image.style.maxWidth = '100%';
                             image.style.width = `${width}px`;
-                            image.style.height = 'auto';
+                            if ((!locked && unit === 'px') || event.shiftKey) {
+                                image.style.height = `${Math.max(MIN_IMAGE_SIZE, Math.round(start.height + event.clientY - start.y))}px`;
+                            }
+                            else
+                                image.style.height = 'auto';
                             // What the page lets it be: never wider than the column.
-                            setDragged(Math.round(image.getBoundingClientRect().width));
-                        }, onPointerUp: (event) => {
-                            const start = drag.current;
-                            if (!start || start.pointer !== event.pointerId)
-                                return;
-                            drag.current = null;
-                            const width = Math.round(image.getBoundingClientRect().width);
-                            setDragged(null);
-                            image.style.width = '';
-                            image.style.height = '';
-                            if (Math.abs(width - start.width) >= 1)
-                                resize(width);
-                        }, onPointerCancel: () => {
-                            drag.current = null;
-                            setDragged(null);
-                            image.style.width = '';
-                            image.style.height = '';
-                        } })] }))] }));
+                            setDragged(drawn());
+                        }, onPointerUp: (event) => endDrag(event, false), onPointerCancel: (event) => endDrag(event, true), children: ICON_RESIZE })] }))] }));
 }
 // ── Tables ───────────────────────────────────────────────────────────────────
 /** Where the focus goes back to when a table is drawn again after an edit of one of its cells. */

package/dist/edit/click-source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where in a block's source a click on its drawing lands (#102): the text under the pointer is
+ * found in the source the block was drawn from, so the caret goes where the author clicked once
+ * the source is revealed, rather than to the end of the block's first line.
+ */
+/** The text node and offset under a point of the page, where the browser can say. */
+export declare function caretAt(x: number, y: number): {
+    node: Node;
+    offset: number;
+} | null;
+/**
+ * The offset in `source` that draws `offset` in the text node `node` of the drawing `root`, or
+ * `null` when the text there is not written in the source as it is drawn — a formula's typesetting,
+ * an escaped character, a note an embed draws — and the click cannot be mapped.
+ */
+export declare function sourceOffsetOf(root: HTMLElement, source: string, node: Node, offset: number): number | null;

package/dist/edit/click-source.js

@@ -0,0 +1,74 @@
+/**
+ * Where in a block's source a click on its drawing lands (#102): the text under the pointer is
+ * found in the source the block was drawn from, so the caret goes where the author clicked once
+ * the source is revealed, rather than to the end of the block's first line.
+ */
+/** How much of the text beside the pointer is looked for when its whole line is not in the source. */
+const WINDOW = 24;
+/** The least of it looked for: a letter or two is found anywhere. */
+const LEAST = 3;
+/** The text node and offset under a point of the page, where the browser can say. */
+export function caretAt(x, y) {
+    const position = document.caretPositionFromPoint?.(x, y);
+    if (position)
+        return { node: position.offsetNode, offset: position.offset };
+    const range = document.caretRangeFromPoint?.(x, y);
+    return range ? { node: range.startContainer, offset: range.startOffset } : null;
+}
+/**
+ * The offset in `source` that draws `offset` in the text node `node` of the drawing `root`, or
+ * `null` when the text there is not written in the source as it is drawn — a formula's typesetting,
+ * an escaped character, a note an embed draws — and the click cannot be mapped.
+ */
+export function sourceOffsetOf(root, source, node, offset) {
+    if (node.nodeType !== Node.TEXT_NODE || !root.contains(node))
+        return null;
+    const data = node.textContent ?? '';
+    const at = Math.max(0, Math.min(offset, data.length));
+    // A drawn paragraph joins its lines, which the source writes each after its own marker (`> `).
+    const lineStart = data.lastIndexOf('\n', at - 1) + 1;
+    const lineEnd = data.indexOf('\n', at) === -1 ? data.length : data.indexOf('\n', at);
+    const before = textBefore(root, node) + data.slice(0, lineStart);
+    const left = data.slice(Math.max(lineStart, at - WINDOW), at);
+    const right = data.slice(at, Math.min(lineEnd, at + WINDOW));
+    const candidates = [
+        { text: data.slice(lineStart, lineEnd), caret: at - lineStart },
+        { text: left + right, caret: left.length },
+        { text: left, caret: left.length },
+        { text: right, caret: 0 },
+    ];
+    for (const [index, { text, caret }] of candidates.entries()) {
+        if (!text.trim() || (index > 0 && text.trim().length < LEAST))
+            continue;
+        const found = nth(source, text, count(before, text));
+        if (found !== -1)
+            return found + caret;
+    }
+    return null;
+}
+/** The text drawn before `node` within `root`. */
+function textBefore(root, node) {
+    const range = document.createRange();
+    range.setStart(root, 0);
+    range.setEnd(node, 0);
+    return range.toString();
+}
+function count(text, piece) {
+    let found = 0;
+    for (let at = text.indexOf(piece); at !== -1; at = text.indexOf(piece, at + 1))
+        found++;
+    return found;
+}
+/**
+ * Where the `n`-th occurrence of `piece` (from 0) starts in `text`: the same text drawn twice is
+ * mapped to the occurrence it draws, and to the last one when the drawing shows more than the source.
+ */
+function nth(text, piece, n) {
+    let last = -1;
+    for (let at = text.indexOf(piece), seen = 0; at !== -1; at = text.indexOf(piece, at + 1), seen++) {
+        if (seen === n)
+            return at;
+        last = at;
+    }
+    return last;
+}

package/dist/edit/heights.js

@@ -138,6 +138,8 @@ export function estimateHeight(kind, source, metrics) {
             const size = readImageSize(source.trim());
             if (size?.height != null)
                 return size.height;
+            if (size?.percent != null)
+                return Math.round(((metrics.width * size.percent) / 100) * 0.75);
             return size?.width != null ? Math.round(size.width * 0.75) : UNDECLARED_IMAGE_HEIGHT;
         }
     }

package/dist/edit/image-size.d.ts

@@ -1,14 +1,13 @@
 /**
  * The size an image is drawn at, as its notation writes it (#98): the dimensions after the pipe
  * of a Markdown image's description, `![description|300](address)` (`SPEC.md` §3.14), or of the
- * embed of a file the notebook keeps, `![[photo.jpg|300]]` (§5.7). The editor reads them and
- * rewrites them, and no other byte.
+ * embed of a file the notebook keeps, `![[photo.jpg|300]]` (§5.7) — pixels, a width and a height,
+ * or a share of the page (#108). The editor reads them and rewrites them, and the description
+ * before the pipe of a Markdown image (#106), and no other byte.
  */
+import { type Dimensions } from '../image-dimensions.js';
 import type { TextChange } from './table.js';
-export interface ImageSize {
-    /** The width it declares, or `null` when it is drawn at its own size. */
-    readonly width: number | null;
-    readonly height: number | null;
+export interface ImageSize extends Dimensions {
     /**
      * Where in the source the dimensions are written, their pipe included; an empty span where they
      * would be written when there are none.
@@ -19,6 +18,15 @@ export interface ImageSize {
     };
     /** What separates them from the rest: `|`, or `\|` in an embed whose pipe is escaped. */
     readonly pipe: string;
+    /**
+     * The description of a Markdown image, as it reads, and where it is written, before its pipe;
+     * `null` for an embed, whose pipe is the only thing it writes (§5.8).
+     */
+    readonly description: {
+        readonly text: string;
+        readonly from: number;
+        readonly to: number;
+    } | null;
 }
 /** The largest width the notation writes: five digits (`SPEC.md` §3.14). */
 export declare const MAX_IMAGE_WIDTH = 99999;
@@ -29,8 +37,16 @@ export declare const MAX_IMAGE_WIDTH = 99999;
  */
 export declare function readImageSize(source: string): ImageSize | null;
 /**
- * The change that draws the image whose source starts at `from` at `width`, its height following,
- * or at its own size for `null`: the dimensions written, replaced or taken away, and nothing else.
- * Empty when the source is not an image's notation or already says so.
+ * The change that draws the image whose source starts at `from` at the dimensions asked — a width
+ * as a number, its height following, or whole `Dimensions` — or at its own size for `null`: the
+ * dimensions written, replaced or taken away, and nothing else. Empty when the source is not an
+ * image's notation, already says so, or the dimensions asked are none the notation writes: a
+ * value out of its range is refused, never brought into it.
+ */
+export declare function resizeImage(source: string, from: number, asked: number | Dimensions | null): TextChange[];
+/**
+ * The change that writes `text` as the description of the Markdown image whose source starts at
+ * `from`, before its pipe, which it keeps (§3.14): a bracket and a backslash escaped, so the image
+ * stays one. Empty for an embed, which has no description to write (§5.8), and when nothing changes.
  */
-export declare function resizeImage(source: string, from: number, width: number | null): TextChange[];
+export declare function describeImage(source: string, from: number, text: string): TextChange[];