@voithos-labs/aragonite 0.10.2 → 0.10.4

package/dist/core/inline/format-toggle.js

@@ -1,10 +1,11 @@
 /**
  * Toggle an inline format inside a prose block. Over a SELECTION the direction is parse coverage,
  * not edge adjacency: a covered range unapplies (aligned strip, else split, over every covering run
- * in turn), overlapping or abutting runs apply over their union, a bare range wraps. Where the mode
- * PAINTS delimiters the strip and the wrap write literally; every other candidate declines unless it
- * verifies. At a COLLAPSED CARET: unwrap the span, else drop the empty pair, else insert one
- * (live-mode.md § 4.3). Every write clamps to the CONTENT range: a marker in `# ` changes the kind.
+ * in turn), overlapping or abutting runs apply over their union, a bare range wraps the core its
+ * boundary whitespace leaves. Where the mode PAINTS delimiters the strip and the wrap write
+ * unverified; every other candidate declines unless it verifies. At a COLLAPSED CARET: unwrap the
+ * span, else drop the empty pair, else insert one (live-mode.md § 4.3). Every write clamps to the
+ * CONTENT range: a marker in `# ` changes the kind.
  */
 import { recordFormatCoverageRead } from '../../perf/instruments';
 import { paintsFocusedMarkers } from '../../presentation-mode';
@@ -29,29 +30,31 @@ export function toggleInlineFormat(edit, format, mode) {
     // Painted delimiters are the mode's own answer, so those modes write their candidate unverified.
     // The preview rungs paint: this seam only writes into the block those rungs reveal.
     const paints = paintsFocusedMarkers(mode ?? 'source');
-    const covering = coveringSpansOf(inlines, start, end, format);
+    const { from, to, covering } = coveredReading(display, inlines, start, end, format);
     // A strip sheds ONE run, so where a second of the same kind covers the selection too, the answer
     // is the covering arm's split: stripping there leaves the press's own read still active.
-    const sole = covering.length > 1 ? null : soleStripCandidate(display, inlines, start, end, format);
+    const sole = covering.length > 1 ? null : soleStripCandidate(display, inlines, from, to, format);
     if (sole)
         return paints || preservesScreen(sole, edit, screenOf(display, content)) ? sole : null;
     // The flank strip rewrites bytes OUTSIDE the selection, and byte equality can mistake a nested
     // run's delimiters for the enclosing one's, so its candidate verifies like the split's.
-    const enclosing = enclosingSpanOf(inlines, start, end, format);
-    if (enclosing && flanksAreItsMarkers(display, start, end, enclosing)) {
-        const flank = firstFlipVerified([flankStrip(display, start, end, enclosing)], edit, format, 'unapply');
+    const enclosing = enclosingSpanOf(inlines, from, to, format);
+    if (enclosing && flanksAreItsMarkers(display, from, to, enclosing)) {
+        const flank = firstFlipVerified([flankStrip(display, from, to, enclosing)], edit, format, 'unapply');
         if (flank)
             return flank;
     }
     if (covering.length > 0)
-        return firstFlipVerified(covering.flatMap((span) => splitCandidates(display, inlines, span, start, end, format)), edit, format, 'unapply');
+        return firstFlipVerified(covering.flatMap((span) => splitCandidates(display, inlines, span, from, to, format)), edit, format, 'unapply');
     const union = formatUnionOf(inlines, start, end, format);
     if (union)
-        return firstFlipVerified(absorbCandidates(display, inlines, union, format, mark), edit, format, 'apply');
+        return firstFlipVerified(absorbCandidates(display, inlines, union, { start, end }, format, mark), edit, format, 'apply');
     // A wrap whose markers do not paint owes split and absorb's coverage check: bytes that re-pair
     // against a neighbouring run leave the range unformatted with nothing on screen to say so.
-    const wraps = wrapCandidates(display, inlines, start, end, mark);
-    return paints ? (wraps[0] ?? null) : firstFlipVerified(wraps, edit, format, 'apply');
+    const wrap = wrapCandidate(display, inlines, start, end, mark);
+    if (!wrap)
+        return null;
+    return paints ? wrap : firstFlipVerified([wrap], edit, format, 'apply');
 }
 /** Whether a toggle right now would UNAPPLY — the pressed-state a toolbar paints. The same arms
  *  the toggle routes by, asked without emitting: a caret inside the construct, a selection
@@ -137,7 +140,24 @@ function coverageCarries({ display, start, end, inlines, sliceNodes }, format) {
     const enclosing = enclosingSpanOf(inlines, start, end, format);
     if (enclosing && flanksAreItsMarkers(display, start, end, enclosing))
         return true;
-    return coveringSpansOf(inlines, start, end, format).length > 0;
+    return coveredReading(display, inlines, start, end, format).covering.length > 0;
+}
+/**
+ * The range an unapply reads, with the runs covering it. A run closes against a word and never
+ * whitespace, so the wrap leaves a boundary space OUTSIDE the delimiters: a selection reaching
+ * past a run by whitespace alone is still that run's own, or it could not take its own mark off.
+ */
+function coveredReading(display, inlines, start, end, format) {
+    const covering = coveringSpansOf(inlines, start, end, format);
+    if (covering.length > 0)
+        return { from: start, to: end, covering };
+    const trimmed = withoutBoundaryWhitespace(display, start, end);
+    if (!trimmed || (trimmed.start === start && trimmed.end === end))
+        return { from: start, to: end, covering };
+    const inner = coveringSpansOf(inlines, trimmed.start, trimmed.end, format);
+    return inner.length > 0
+        ? { from: trimmed.start, to: trimmed.end, covering: inner }
+        : { from: start, to: end, covering };
 }
 // ── Aligned unapply ──────────────────────────────────────────────────────────
 /** The selection carries its own flanking markers (the user selected `**word**`): exactly one
@@ -247,18 +267,37 @@ function formatUnionOf(inlines, start, end, format) {
     }
     return touched ? { start: from, end: to } : null;
 }
-function absorbCandidates(display, inlines, union, format, mark) {
+/** The run grows to the union, the SELECTION does not: each endpoint is carried through the
+ *  strip and re-wrap, so a press over half a run leaves that half selected. An endpoint on the
+ *  union's edge keeps the new marker inside the range, as a bare wrap's selection does. */
+function absorbCandidates(display, inlines, union, selected, format, mark) {
     if (!cutsLandCleanly(inlines, union, union))
         return [];
-    const stripped = stripKindMarkers(display, inlines, format, union.start, union.end);
+    const cuts = kindMarkerCuts(inlines, format, union.start, union.end);
+    const stripped = spliceOutCuts(display, cuts, union.start, union.end);
     const prefix = display.slice(0, union.start);
     const suffix = display.slice(union.end);
     const wrapAt = (lead, core, trail) => {
         const wrapped = wrapSlice(core, mark);
+        // The kind may pad its fence, so the marker widths are read off the wrap, not the row.
+        const found = core ? wrapped.indexOf(core) : -1;
+        const open = found >= 0 ? found : (wrapped.length - core.length) / 2;
+        const close = wrapped.length - core.length - open;
+        const coreStart = lead.length;
+        const coreEnd = lead.length + core.length;
+        const startAt = strippedOffset(cuts, union.start, selected.start);
+        const endAt = strippedOffset(cuts, union.start, selected.end);
+        const shift = (at, edgeInclusive) => {
+            if (edgeInclusive === 'start' ? at <= coreStart : at < coreStart)
+                return at;
+            if (edgeInclusive === 'start' ? at <= coreEnd : at < coreEnd)
+                return at + open;
+            return at + open + close;
+        };
         return {
             newDisplay: prefix + lead + wrapped + trail + suffix,
-            newSelStart: prefix.length + lead.length,
-            newSelEnd: prefix.length + lead.length + wrapped.length
+            newSelStart: prefix.length + shift(startAt, 'start'),
+            newSelEnd: prefix.length + shift(endAt, 'end')
         };
     };
     const out = [wrapAt('', stripped, '')];
@@ -288,6 +327,10 @@ function cutsLandCleanly(inlines, cuts, within) {
 /** The bytes of `[from, to)` with the delimiter runs of every same-format construct lying wholly
  *  inside removed; one straddling the range keeps its markers, for the verifier to judge. */
 function stripKindMarkers(display, inlines, format, from, to) {
+    return spliceOutCuts(display, kindMarkerCuts(inlines, format, from, to), from, to);
+}
+/** The marker byte ranges of every `format` run lying wholly inside [from, to), in order. */
+function kindMarkerCuts(inlines, format, from, to) {
     const cuts = [];
     for (const node of inlineDescendants(inlines)) {
         if (node.kind !== format)
@@ -297,7 +340,9 @@ function stripKindMarkers(display, inlines, format, from, to) {
             continue;
         cuts.push([span.start, span.contentStart], [span.contentEnd, span.end]);
     }
-    cuts.sort((a, b) => a[0] - b[0]);
+    return cuts.sort((a, b) => a[0] - b[0]);
+}
+function spliceOutCuts(display, cuts, from, to) {
     let out = '';
     let at = from;
     for (const [cutFrom, cutTo] of cuts) {
@@ -306,30 +351,27 @@ function stripKindMarkers(display, inlines, format, from, to) {
     }
     return out + display.slice(at, to);
 }
+/** Where a display offset lands in the stripped slice: the cut bytes before it fall away, and an
+ *  offset inside a marker rides to that marker's start. */
+function strippedOffset(cuts, from, offset) {
+    let removed = 0;
+    for (const [cutFrom, cutTo] of cuts)
+        if (cutFrom < offset)
+            removed += Math.min(cutTo, offset) - cutFrom;
+    return Math.max(0, offset - from - removed);
+}
 // ── Wrap ─────────────────────────────────────────────────────────────────────
 /**
- * What a bare wrap could mean, what it literally says first. Only the wrap has a second reading:
- * markdown opens and closes a run against a word, never whitespace, so a boundary space goes to
- * the plain text beside the run, as `live-split-rebalance` reads the same problem. Either reading
- * needs both its endpoints to be legal cuts: markers spliced into a construct's bytes re-pair.
+ * The bare wrap, over the selection's trimmed core: markdown opens and closes a run against a word,
+ * never whitespace, so a boundary space goes to the plain text beside the run, as
+ * `live-split-rebalance` reads the same problem. Null where nothing survives the trim, or where an
+ * endpoint is no legal cut: markers spliced into a construct's bytes re-pair.
  */
-function wrapCandidates(display, inlines, start, end, mark) {
-    const core = trimmedRange(display, start, end);
-    const readings = core === null ? [{ start, end }] : [{ start, end }, core];
-    return readings
-        .filter((range) => cutsLandCleanly(inlines, range, range))
-        .map((range) => wrapRange(display, range.start, range.end, mark));
-}
-/** The selection minus its boundary whitespace, or null when there is none to trim or nothing
- *  left once it goes. */
-function trimmedRange(display, start, end) {
-    let from = start;
-    let to = end;
-    while (from < to && /\s/.test(display[from]))
-        from++;
-    while (to > from && /\s/.test(display[to - 1]))
-        to--;
-    return (from === start && to === end) || from === to ? null : { start: from, end: to };
+function wrapCandidate(display, inlines, start, end, mark) {
+    const core = withoutBoundaryWhitespace(display, start, end);
+    if (!core || !cutsLandCleanly(inlines, core, core))
+        return null;
+    return wrapRange(display, core.start, core.end, mark);
 }
 function wrapRange(display, start, end, mark) {
     const wrapped = wrapSlice(display.slice(start, end), mark);
@@ -527,6 +569,18 @@ function leadingWs(text) {
 function trailingWs(text) {
     return /\s*$/.exec(text)[0];
 }
+/** A range minus its boundary whitespace, null once nothing is left. One home for the trim, so the
+ *  wrap here and the cross-block decomposition that trims before it ever asks
+ *  (`selection/cross-block/format-range.ts`) cannot disagree about where a run may close. */
+export function withoutBoundaryWhitespace(display, from, to) {
+    let start = from;
+    let end = to;
+    while (start < end && /\s/.test(display[start]))
+        start++;
+    while (end > start && /\s/.test(display[end - 1]))
+        end--;
+    return start === end ? null : { start, end };
+}
 // ── Content clamp ────────────────────────────────────────────────────────────
 function clampToContent(offset, content) {
     return Math.min(Math.max(offset, content.start), content.end);

package/dist/core/inline/image-dimensions.d.ts

@@ -1,6 +1,9 @@
+import type { ImageCrop } from '../nodes';
+export declare const MAX_CROP_ZOOM = 4;
 export interface ParsedImageAlt {
     displayAlt: string;
     width: number | undefined;
     height: number | undefined;
+    crop: ImageCrop | undefined;
 }
 export declare function parseImageDimensions(alt: string): ParsedImageAlt;

package/dist/core/inline/image-dimensions.js

@@ -1,14 +1,17 @@
-// `|N` / `|NxM` is an Obsidian extension, not part of GFM.
+// `|N` / `|NxM` is an Obsidian extension, not part of GFM. The `@X,Y[,Z]` tail on the `NxM`
+// form is this editor's own: the pan and zoom of the image inside that frame.
 const MAX_DIMENSION = 10000;
-// The longest zero-free decodable suffix, `|10000x10000`. Bounding the pipe search to that tail
-// keeps nested-label floods linear, at the deliberate cost of not decoding zero-padded runs.
-const MAX_SUFFIX_SEARCH = 12;
+export const MAX_CROP_ZOOM = 4;
+// The longest decodable suffix, `|10000x10000@100,100,4.00`. Bounding the pipe search to that
+// tail keeps nested-label floods linear.
+const MAX_SUFFIX_SEARCH = 26;
+const NO_HINT = { width: undefined, height: undefined, crop: undefined };
 export function parseImageDimensions(alt) {
     const lastPipe = boundedLastPipe(alt);
     const dims = lastPipe === -1 ? null : parseDimensionSuffix(alt.slice(lastPipe + 1));
     if (dims === null)
-        return { displayAlt: alt, width: undefined, height: undefined };
-    return { displayAlt: alt.slice(0, lastPipe), width: dims.width, height: dims.height };
+        return { displayAlt: alt, ...NO_HINT };
+    return { displayAlt: alt.slice(0, lastPipe), ...dims };
 }
 function boundedLastPipe(alt) {
     const floor = alt.length > MAX_SUFFIX_SEARCH ? alt.length - MAX_SUFFIX_SEARCH : 0;
@@ -24,16 +27,49 @@ function parseDimensionSuffix(s) {
         const w = parseStrictInt(s);
         if (w === null)
             return null;
-        return { width: w, height: undefined };
+        return { width: w, height: undefined, crop: undefined };
     }
+    const atIdx = s.indexOf('@');
+    const heightEnd = atIdx === -1 ? s.length : atIdx;
     const w = parseStrictInt(s.slice(0, xIdx));
-    const h = parseStrictInt(s.slice(xIdx + 1));
+    const h = parseStrictInt(s.slice(xIdx + 1, heightEnd));
     if (w === null || h === null)
         return null;
-    return { width: w, height: h };
+    if (atIdx === -1)
+        return { width: w, height: h, crop: undefined };
+    const crop = parseCropTail(s.slice(atIdx + 1));
+    // A malformed tail is not a hint at all: the whole suffix stays alt text.
+    if (crop === null)
+        return null;
+    return { width: w, height: h, crop };
+}
+/** `X,Y` or `X,Y,Z`: whole percents 0–100 and a zoom of 1–4 with up to two decimals. */
+function parseCropTail(s) {
+    const parts = s.split(',');
+    if (parts.length < 2 || parts.length > 3)
+        return null;
+    const x = parsePercent(parts[0]);
+    const y = parsePercent(parts[1]);
+    if (x === null || y === null)
+        return null;
+    if (parts.length === 2)
+        return { x, y, z: 1 };
+    if (!/^[1-4](?:\.\d{1,2})?$/.test(parts[2]))
+        return null;
+    const z = Number(parts[2]);
+    if (z > MAX_CROP_ZOOM)
+        return null;
+    return { x, y, z };
+}
+function parsePercent(s) {
+    if (!/^\d{1,3}$/.test(s))
+        return null;
+    const n = Number(s);
+    return n > 100 ? null : n;
 }
+/** No leading zeros: a padded run is alt text, not a hint. */
 function parseStrictInt(s) {
-    if (s.length === 0 || !/^\d+$/.test(s))
+    if (!/^[1-9]\d*$/.test(s))
         return null;
     const n = Number(s);
     if (n <= 0 || n > MAX_DIMENSION)

package/dist/core/inline/inline-widgets.d.ts

@@ -67,6 +67,22 @@ export declare const ON_EDGE_POLICIES: readonly ["select", "step-over"];
  */
 export interface InlineWidgetEditingPolicy {
     revealSource?: boolean;
+    /**
+     * Where this kind's editable CONTENT sits inside its source span, as offsets relative to
+     * that span — `$x$` answers `{ start: 1, end: 2 }`. It bounds a caret entering the source,
+     * and `end` is where a revealing click lands when the kind maps no point of its own. Only
+     * the kind knows its own delimiters; absent, the caret keeps the leading edge.
+     */
+    revealContentSpan?: (source: string) => {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * The offset in `source` a press on the RENDERED widget names, so a click seats the caret
+     * where it landed rather than at one edge. Only the kind can map its render back to bytes (a
+     * KaTeX island paints glyphs, not source); null declines this point and keeps the fallback.
+     */
+    revealOffsetAtPoint?: (widgetEl: HTMLElement, source: string, clientX: number, clientY: number) => number | null;
     deleteGranularity?: (typeof DELETE_GRANULARITIES)[number];
     onEdge?: (typeof ON_EDGE_POLICIES)[number];
     onSelectedKey?: (e: KeyboardEvent, ctx: InlineWidgetEditingContext) => boolean;
@@ -107,6 +123,9 @@ export declare function augmentInlineWidgetKind(kind: AnyInlineKind, editing: Pa
 /** Kind-level recognition, independent of per-block render policy (renderImagesAsWidgets). */
 export declare function isInlineWidget(node: InlineNode, raw: string): boolean;
 export declare function getInlineWidgetEditing(kind: AnyInlineKind): InlineWidgetEditingPolicy | undefined;
+/** A kind the caret reads as one character: it steps over in one press, carries a column of its
+ *  own, and a press ON its glyph names an edge rather than selecting the island whole. */
+export declare function isCharacterLikeWidget(kind: AnyInlineKind): boolean;
 export declare function getInlineWidgetComponent(kind: AnyInlineKind): Component<InlineWidgetComponentProps> | undefined;
 /**
  * Every live widget reachable from `nodes`, in document order. Descends so a widget nested in a

package/dist/core/inline/inline-widgets.js

@@ -74,6 +74,11 @@ export function isInlineWidget(node, raw) {
 export function getInlineWidgetEditing(kind) {
     return registry.get(kind)?.editing;
 }
+/** A kind the caret reads as one character: it steps over in one press, carries a column of its
+ *  own, and a press ON its glyph names an edge rather than selecting the island whole. */
+export function isCharacterLikeWidget(kind) {
+    return getInlineWidgetEditing(kind)?.onEdge === 'step-over';
+}
 export function getInlineWidgetComponent(kind) {
     return registry.get(kind)?.component;
 }

package/dist/core/inline/scan/brackets.js

@@ -112,6 +112,7 @@ function buildImage(raw, opener, labelEnd, target, children) {
         ...(target.title !== undefined ? { title: target.title } : {}),
         ...(dims.width !== undefined ? { width: dims.width } : {}),
         ...(dims.height !== undefined ? { height: dims.height } : {}),
+        ...(dims.crop !== undefined ? { crop: dims.crop } : {}),
         ...(target.label !== undefined ? { label: target.label } : {})
     };
 }

package/dist/core/inline/scan/plugin-syntax.d.ts

@@ -38,6 +38,12 @@ export interface InlineSyntaxOptions {
      * commit's equality guard. See the plugin guide's inline section.
      */
     rewriteImage?: ImageSyntaxRewriter;
+    /**
+     * The trigger is a symmetric one-byte delimiter (`$…$`) a keystroke should close at once:
+     * typing it lands its twin after the caret, so the new opener pairs with that twin rather
+     * than with a later formula's delimiter (see `delimiter-autopair.ts`). Bare triggers only.
+     */
+    autoPair?: boolean;
 }
 export interface InlineRung extends InlineSyntaxClaim {
     recognizer: InlineSyntaxRecognizer;
@@ -57,6 +63,8 @@ export declare function hasInlineSyntax(): boolean;
 /** Read once per scan, so an empty set leaves `needsScan` at its pre-plugin cost. */
 export declare function hasScanProbeRungs(): boolean;
 export declare function isScanProbeTrigger(char: string): boolean;
+/** Whether a plugin asked for `char` to close itself as it is typed. */
+export declare function isAutoPairTrigger(char: string): boolean;
 /** False costs the scan loop nothing. */
 export declare function hasPrefixRungs(): boolean;
 export declare function __resetInlineSyntaxForTests(): void;

package/dist/core/inline/scan/plugin-syntax.js

@@ -36,6 +36,9 @@ const NO_RUNGS = [];
 // (`default` arm) so each dispatch path reads one map and its empty gate is one `size` check.
 const reservedRegistry = new Map();
 const unreservedRegistry = new Map();
+// Triggers whose keystroke closes itself (`autoPair`); the built-in backtick is not registered
+// here, the typing seam knows it on its own.
+const autoPairTriggers = new Set();
 // Triggers the fast bail (`needsScan`, scan/index.ts) must visit while a rung lives on them.
 // Maintained at registration, so a rung on a trigger `SPECIAL_CHARS` already visits costs nothing.
 const scanProbeTriggers = new Set();
@@ -44,7 +47,7 @@ export function registerInlineSyntax(trigger, recognizer, options) {
     if (trigger.length !== 1) {
         throw new Error('registerInlineSyntax: trigger must be a single character');
     }
-    const { prefix, priority = INLINE_PRIORITIES.plugin, rewriteImage } = options ?? {};
+    const { prefix, priority = INLINE_PRIORITIES.plugin, rewriteImage, autoPair } = options ?? {};
     if (prefix !== undefined && (prefix.length < 2 || !prefix.startsWith(trigger))) {
         throw new Error(`registerInlineSyntax: prefix ${JSON.stringify(prefix)} must begin with the trigger ` +
             `${JSON.stringify(trigger)} and be at least two characters`);
@@ -69,6 +72,10 @@ export function registerInlineSyntax(trigger, recognizer, options) {
                 `the built-in scanner; got ${priority}`);
         }
     }
+    if (autoPair && prefix !== undefined) {
+        throw new Error(`registerInlineSyntax: autoPair pairs the bare trigger ${JSON.stringify(trigger)} with ` +
+            `itself, so it cannot be combined with a prefix`);
+    }
     const effectivePrefix = prefix ?? trigger;
     const registry = reserved ? reservedRegistry : unreservedRegistry;
     const existing = registry.get(trigger);
@@ -84,6 +91,8 @@ export function registerInlineSyntax(trigger, recognizer, options) {
         // or the recognizer is the silent no-op this seam refuses to accept.
         if (!reserved || SCAN_PROBED_RESERVED.has(trigger))
             scanProbeTriggers.add(trigger);
+        if (autoPair)
+            autoPairTriggers.add(trigger);
     }, `registerInlineSyntax: ${JSON.stringify(trigger)} already registered at prefix ` +
         `${JSON.stringify(effectivePrefix)}, priority ${priority}`);
 }
@@ -139,6 +148,10 @@ export function hasScanProbeRungs() {
 export function isScanProbeTrigger(char) {
     return scanProbeTriggers.has(char);
 }
+/** Whether a plugin asked for `char` to close itself as it is typed. */
+export function isAutoPairTrigger(char) {
+    return autoPairTriggers.has(char);
+}
 /** False costs the scan loop nothing. */
 export function hasPrefixRungs() {
     return reservedRegistry.size > 0;
@@ -147,4 +160,5 @@ export function __resetInlineSyntaxForTests() {
     reservedRegistry.clear();
     unreservedRegistry.clear();
     scanProbeTriggers.clear();
+    autoPairTriggers.clear();
 }

package/dist/core/inline/transparency.js

@@ -5,7 +5,7 @@
  * an unparsed block degrades to "land on it".
  */
 import { getInlineContent } from './inline-cache';
-import { isInlineWidget, getInlineWidgetEditing } from './inline-widgets';
+import { isInlineWidget, isCharacterLikeWidget } from './inline-widgets';
 export function isVerticallyTransparentNode(node) {
     if (!node)
         return false;
@@ -26,8 +26,8 @@ export function isVerticallyTransparentNode(node) {
         return false;
     for (const inline of inlines) {
         if (isInlineWidget(inline, node.raw)) {
-            // A step-over widget is character-like: it carries a column, so it reads as text.
-            if (getInlineWidgetEditing(inline.kind)?.onEdge === 'step-over')
+            // A character-like widget carries a column, so it reads as text.
+            if (isCharacterLikeWidget(inline.kind))
                 return false;
             continue;
         }

package/dist/core/inline-render.d.ts

@@ -25,6 +25,12 @@ export interface RenderInlineOptions {
      * as `buildImageWidget`; absent or null falls the widget back to its raw source.
      */
     buildPortalWidget?: (node: InlineNode, raw: string) => HTMLElement | null;
+    /**
+     * Paint a lone backslash ending the display as the hard break it is about to become: the
+     * byte as a (hidden) marker plus two `br` anchors so the caret has a second line to sit on.
+     * Only for a mode that hides markers; the DOM stays byte-identical elsewhere.
+     */
+    pendingBreakSeat?: boolean;
     /**
      * Stamp marker spans with the construct's raw range, so preview-inline's reveal trigger can
      * address them. Attributes only, leaving textContent and the offset walk untouched. Off by

package/dist/core/inline-render.js

@@ -288,8 +288,40 @@ export function renderInlineNodes(nodes, raw, opts = {}) {
         if (child !== null)
             stack.push(child);
     }
+    if (opts.pendingBreakSeat)
+        paintPendingBreak(nodes, raw, root.content);
     return root.content;
 }
+/**
+ * `insertHardBreak` at the end of a block writes `\` whose line ending IS the block's trailing
+ * one, so until the next key supplies the following line CommonMark (and the scanner) read the
+ * byte as literal text. Left as text it shows as a stray backslash and the caret stays on the
+ * first line; painted like this the user sees the new line they asked for. A `br` adds no
+ * textContent, so G1.28 holds; the walk seats offset `length` after the first anchor.
+ */
+function paintPendingBreak(nodes, raw, frag) {
+    const last = nodes[nodes.length - 1];
+    if (!last || last.kind !== 'text' || raw[last.end - 1] !== '\\')
+        return;
+    const rest = raw.slice(last.end);
+    if (rest !== '' && rest !== '\n' && rest !== '\r\n')
+        return;
+    const tail = frag.lastChild;
+    if (!tail || tail.nodeType !== Node.TEXT_NODE || !tail.textContent?.endsWith('\\'))
+        return;
+    if (tail.textContent.length === 1)
+        tail.remove();
+    else
+        tail.textContent = tail.textContent.slice(0, -1);
+    const marker = markerSpan('\\');
+    marker.classList.add('md-break-pending');
+    frag.appendChild(marker);
+    for (let i = 0; i < 2; i++) {
+        const anchor = document.createElement('br');
+        anchor.dataset.caretAnchor = 'break';
+        frag.appendChild(anchor);
+    }
+}
 /**
  * The leaf containing `offset`, preferring the right node at a boundary; `offset === end` only
  * matches the last node. Model-layer, touching no DOM: the DOM counterpart is

package/dist/core/nodes.d.ts

@@ -259,6 +259,8 @@ export interface InlineNode {
     decoded?: string;
     width?: number;
     height?: number;
+    /** Pan/zoom inside the `|WxH` frame, read from a `@X,Y[,Z]` tail on the hint. */
+    crop?: ImageCrop;
     /** Discriminator for `unresolvedReference` nodes: which form they would have been. */
     refKind?: 'link' | 'image';
     /**
@@ -271,12 +273,24 @@ export interface InlineNode {
  * Optional keys are omitted rather than set to `undefined`, so a serializer can tell "no title"
  * from "empty title" and reproduce a node that never carried one.
  */
+/**
+ * How an image sits inside its `|WxH` frame: the image point (`x`%, `y`%) pinned to the same
+ * point of the frame, at `z` times the smallest scale that fills it. `{50, 50, 1}` is a plain
+ * centred cover fit; absent, the frame stretches the image the way `<img width height>` does.
+ */
+export interface ImageCrop {
+    x: number;
+    y: number;
+    z: number;
+}
 export interface ImageFields {
     alt: string;
     url: string;
     title?: string;
     width?: number;
     height?: number;
+    /** Needs both dimensions: a crop is a window into a fixed frame. */
+    crop?: ImageCrop;
     /**
      * Reference-style images only (`![alt][label]`). When set, the serializer emits the reference
      * form and writes no url/title: those live in the LRD, and inlining them would orphan it.

package/dist/cursor/edge-affinity.js

@@ -39,7 +39,8 @@ export function classifyArrivalKey(key, metaKey = false) {
     if (metaKey && (key === 'ArrowLeft' || key === 'ArrowRight'))
         return 'outside';
     // A step stops on the side of the run it approached from, so one press never changes which
-    // construct the caret is in: forward keys reach the near side, backward keys the far one.
+    // construct the caret is in (live-mode.md § 4.2); leaving a construct is a typed closer's job
+    // (delimiter-autopair.ts) or a toggle's, not the arrow's.
     if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'PageDown')
         return 'near';
     if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'PageUp')

package/dist/cursor/height-oracle.d.ts

@@ -16,9 +16,8 @@ export interface HeightOracle {
     estimate(node: NodeView, width: number): number;
     measured(id: string): number | undefined;
     recordMeasured(id: string, height: number): void;
-    /** measured(id) ?? estimate(node, width). */
-    height(id: string, node: NodeView, width: number): number;
-    /** Drop every measured height; estimates carry the model until each block re-measures. */
+    /** Drop every measured height. A live scope carries its own across a rebuild (VR-15), so
+     *  estimates seed only a scope built after the drop, and any block with a fresh id. */
     dropMeasured(): void;
 }
 export declare function createHeightOracle(opts: HeightOracleOptions): HeightOracle;

package/dist/cursor/height-oracle.js

@@ -88,7 +88,6 @@ export function createHeightOracle(opts) {
         recordMeasured: (id, height) => {
             measuredById.set(id, height);
         },
-        height: (id, node, width) => measuredById.get(id) ?? estimate(node, width),
         dropMeasured: () => measuredById.clear()
     };
 }

package/dist/cursor/overlay-remeasure.js

@@ -27,5 +27,13 @@ export function wireOverlayRemeasure(opts) {
         editorRoot.addEventListener('scroll', measure, { passive: true });
         disposers.push(() => editorRoot.removeEventListener('scroll', measure));
     }
+    // The block's own box changing under a live range — a paragraph set to a heading, a font
+    // load, a resize — moves the text the rects were measured against. Layout-driven, so it
+    // fires after the change has painted; absent (jsdom) the scroll paths above still hold.
+    if (typeof ResizeObserver === 'function') {
+        const observer = new ResizeObserver(() => measure());
+        observer.observe(el);
+        disposers.push(() => observer.disconnect());
+    }
     return () => disposers.forEach((dispose) => dispose());
 }

package/dist/cursor/reveal-source.js

@@ -8,13 +8,18 @@
 import { tick } from 'svelte';
 import { asRawOffset, toDomTextOffset } from './coordinate-spaces';
 import { restoreCaretAtWalkOffset } from './focused-caret';
+import { clampToLandableRaw } from './widget-offset';
 import { assertInvariant } from '../assert';
 import { checkRevealSourceLength } from '../invariants/inline-transitions';
 export function createSourceReveal(deps) {
     /** Places the caret at a BLOCK-source offset, converting to ambient-included walk space. */
     function placeCaret(container, blockSourceOffset) {
-        const walkOffset = toDomTextOffset(asRawOffset(blockSourceOffset), deps.getAmbientLength());
-        restoreCaretAtWalkOffset(container, walkOffset);
+        // Offset 0 of a source that opens with hidden chrome (a leaf painting `$$` fence lines) is
+        // BEFORE that chrome: typing there would land outside the fence. The seat is the nearest
+        // landable position, which is a no-op wherever nothing hides.
+        const ambient = deps.getAmbientLength();
+        const seat = clampToLandableRaw(container, blockSourceOffset, ambient);
+        restoreCaretAtWalkOffset(container, toDomTextOffset(asRawOffset(seat), ambient));
     }
     async function reveal(atSourceOffset = 0) {
         assertInvariant('reveal-transition', () => checkRevealSourceLength(deps.source.length, deps.sourceStart, deps.sourceEnd));

package/dist/cursor/scroll-hold.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Scroll-position hold across a block's render swap. A swap that shortens a block clamps the
+ * scrollport against the transient layout on the way to its settled height, and the clamp is
+ * never given back. A reveal in flight outranks the hold and owns the position; host mode does
+ * not, since native anchoring cannot undo a max-scroll clamp. Only a measure-then-fit surface
+ * needs this, and today that is one: an editable leaf's source is content-sized at mount.
+ */
+/** Capture the position of whatever scrolls `el`; await the result AFTER the state flip that
+ *  changes the block's height. */
+export declare function captureScrollPosition(el: HTMLElement | null | undefined, isRevealInFlight: () => boolean): () => Promise<void>;