@voithos-labs/aragonite 0.10.2 → 0.10.4

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

@@ -5,16 +5,53 @@
  */
 import { tick } from 'svelte';
 import { resolvedInlineContent } from '../../../core/inline/inline-cache';
-import { isInlineWidget, flattenInlineWidgets, getInlineWidgetEditing, isWidgetActivationClick } from '../../../core/inline/inline-widgets';
+import { flattenInlineWidgets, getInlineWidgetEditing, isCharacterLikeWidget, isWidgetActivationClick } from '../../../core/inline/inline-widgets';
 import { isVerticallyTransparentNode } from '../../../core/inline/transparency';
 import { trimTrailingLineEnding, trailingLineEnding } from '../../../core/lines';
 import { asRawOffset, toClampedRawOffset, toDomTextOffset } from '../../../cursor/coordinate-spaces';
 import { domTextOffsetAtNode, createRangeAtDomTextOffsets, selectionFocusWalkOffset } from '../../../cursor/widget-offset';
 import { createSourceReveal } from '../../../cursor/reveal-source';
+import { nearestWidgetEdgeSeat } from '../../../cursor/widget-edge-snap';
 import { traceRevealOpen, traceRevealFold } from '../../../debug/interaction-trace';
 import { assertInvariant } from '../../../assert';
-import { caretIsInTextContent, hasModifier, isPlainTypingKey } from './click-snap-guard';
+import { caretIsInTextContent, hasModifier, isPlainTypingKey, surfaceHoldsRange } from './click-snap-guard';
 import { findWidgetNodeByStart, findFirstEdgeWidget, findLastEdgeWidget, rawHasNoTextBefore, rawHasNoTextAfter, widgetElByStart } from './widget-adjacency';
+/**
+ * The inline-code wash over a revealed source, painted through the CSS Custom Highlight API
+ * (`::highlight(md-inline-reveal)` in editor.css) rather than a wrapper span: the reveal's
+ * contract, and every offset read on it, is that the source is a bare text node in the block.
+ * The range selects the NODE, so it keeps covering the text as typing grows it. Absent the API
+ * (jsdom, an old engine) the source simply shows unwashed.
+ */
+const REVEAL_HIGHLIGHT = 'md-inline-reveal';
+const washRanges = new WeakMap();
+function revealHighlight() {
+    if (typeof CSS === 'undefined' || !('highlights' in CSS) || typeof Highlight !== 'function') {
+        return null;
+    }
+    let highlight = CSS.highlights.get(REVEAL_HIGHLIGHT);
+    if (!highlight) {
+        highlight = new Highlight();
+        CSS.highlights.set(REVEAL_HIGHLIGHT, highlight);
+    }
+    return highlight;
+}
+function washRevealedSource(node) {
+    const highlight = revealHighlight();
+    if (!highlight)
+        return;
+    const range = document.createRange();
+    range.selectNode(node);
+    washRanges.set(node, range);
+    highlight.add(range);
+}
+function unwashRevealedSource(node) {
+    const range = washRanges.get(node);
+    if (!range)
+        return;
+    washRanges.delete(node);
+    revealHighlight()?.delete(range);
+}
 export function createWidgetInteraction(deps) {
     const isReading = () => deps.getPresentationMode?.() === 'reading';
     // Resolver-aware so widget detection matches the render path's view; a mismatch
@@ -22,12 +59,26 @@ export function createWidgetInteraction(deps) {
     function inlinesOf(node) {
         return resolvedInlineContent(node, deps.linkRef);
     }
+    /**
+     * Every widget in this block, DESCENDING into non-widget parents. The flat inline list is
+     * the wrong shape to scan for widgets: a construct wrapping one — emphasis around a math
+     * span, a link around an image — hides it, and every pointer and arrow-key path that
+     * scanned the flat list simply did not see it. `> *… $L/9 \times 10^{20}$ …*` is the case
+     * that surfaced it: the quote's whole text is one emphasis node, so nothing inside it was
+     * ever clickable.
+     */
+    function widgetsOf() {
+        return flattenInlineWidgets(inlinesOf(deps.node), deps.node.raw);
+    }
     let revealState = null;
     // Outside the record because they must survive `resetReveal` for the kernel's async
     // restore. Identity is load-bearing: two byte-identical widgets share a reuse-pool key,
     // so a lookup can return the OTHER instance and `replaceWith` would MOVE it.
     let activeSourceNode = null;
     let revealedWidget = null;
+    // The offset the last fold parked, which lies inside the construct it just folded: the
+    // restore must not read it as a formula closing around the caret and reopen the reveal.
+    let foldParkedCaret = null;
     // Every fold entry is module-private and pre-guarded by all of its callers, so a fold
     // with no active reveal means a new caller skipped the guard or a flag leaked (G1.26).
     function assertFoldTargetsActiveReveal(entry) {
@@ -38,6 +89,7 @@ export function createWidgetInteraction(deps) {
     function restoreRenderedWidget() {
         if (activeSourceNode === null || revealedWidget === null)
             return;
+        unwashRevealedSource(activeSourceNode);
         activeSourceNode.replaceWith(revealedWidget);
         activeSourceNode = null;
         revealedWidget = null;
@@ -93,6 +145,7 @@ export function createWidgetInteraction(deps) {
                 revealedWidget = widget;
                 activeSourceNode = document.createTextNode(source);
                 widget.replaceWith(activeSourceNode);
+                washRevealedSource(activeSourceNode);
             },
             // Re-inserts the exact element the swap detached, still current because the edit
             // was discarded. The persist path re-renders reactively instead.
@@ -138,9 +191,12 @@ export function createWidgetInteraction(deps) {
         const { caretBefore, originalDisplay } = active;
         // The reactive re-render rebuilds the island, so drop the swap handles without a
         // DOM restore, then run the canonical teardown.
+        if (sourceNode)
+            unwashRevealedSource(sourceNode);
         activeSourceNode = null;
         revealedWidget = null;
         resetReveal();
+        foldParkedCaret = caretAfter;
         // No edit: fold without touching the CST. A zero-diff write still pushes a dead
         // undo entry, so the user's next Ctrl+Z would revert nothing instead of their
         // prior action. The pending-cursor set alone re-renders from the untouched CST.
@@ -243,10 +299,60 @@ export function createWidgetInteraction(deps) {
     }
     // The ONE hit test the pointerdown probe, the click dispatch, and the post-fold
     // re-resolve share.
+    /**
+     * What the pointer is actually over, asked of the DOM rather than of a rectangle. An
+     * island's border box is not what the reader sees: a KaTeX render (a superscript, a
+     * fraction) paints ABOVE and BELOW its own box, so a click on the visible glyphs missed
+     * the rect by a pixel or two and the widget looked inert to the mouse while the keyboard
+     * reached it fine. `elementFromPoint` has no such gap — it answers with whatever is
+     * painted at the point, overflow included.
+     */
+    function revealWidgetFromDom(el, x, y) {
+        // Feature-detected: jsdom implements no hit testing, and the rect scan below is the
+        // answer there — the same shape as `getTargetRanges`' detection on the code surface.
+        if (typeof document.elementFromPoint !== 'function')
+            return null;
+        const at = document.elementFromPoint(x, y);
+        const island = at instanceof Element ? at.closest('[data-inline-widget][data-source-start]') : null;
+        // Containment guard: the point may sit over another block's widget entirely.
+        if (!island || !el.contains(island))
+            return null;
+        const start = Number(island.getAttribute('data-source-start'));
+        if (!Number.isInteger(start))
+            return null;
+        const inline = widgetsOf().find((n) => n.start === start && getInlineWidgetEditing(n.kind)?.revealSource);
+        return inline ? { inline } : null;
+    }
+    /**
+     * Where a click on a rendered widget seats the caret when its kind maps no point: the END of
+     * the content a kind names, INSIDE its delimiters, so typing continues the construct rather
+     * than escaping it. A kind naming no span keeps the leading edge — guessing an end from its
+     * parsed text put a footnote's caret past its bracket.
+     */
+    function insideEndOffset(inline) {
+        const source = deps.node.raw.slice(inline.start, inline.end);
+        const span = getInlineWidgetEditing(inline.kind)?.revealContentSpan?.(source);
+        return span && span.end >= 0 && span.end <= source.length ? span.end : 0;
+    }
+    /** The offset a press names inside a widget's source. Read against the PRE-fold geometry:
+     *  a fold reflows the line and the point stops meaning anything the moment it runs. */
+    function seatFromPoint(el, inline, x, y) {
+        const widget = widgetElByStart(el, inline.start);
+        const atPoint = getInlineWidgetEditing(inline.kind)?.revealOffsetAtPoint;
+        if (!widget || !atPoint)
+            return null;
+        const source = deps.node.raw.slice(inline.start, inline.end);
+        const seat = atPoint(widget, source, x, y);
+        return seat === null ? null : Math.max(0, Math.min(seat, source.length));
+    }
     function hitTestRevealWidget(el, x, y) {
-        for (const inline of inlinesOf(deps.node)) {
-            if (!isInlineWidget(inline, deps.node.raw))
-                continue;
+        const painted = revealWidgetFromDom(el, x, y);
+        if (painted)
+            return painted;
+        // Fallback for a point the DOM cannot answer for (a synthetic call with no element
+        // under it): the original box test, which still covers a widget that paints inside
+        // its own bounds.
+        for (const inline of widgetsOf()) {
             if (!getInlineWidgetEditing(inline.kind)?.revealSource)
                 continue;
             const widget = widgetElByStart(el, inline.start);
@@ -276,6 +382,7 @@ export function createWidgetInteraction(deps) {
         const hit = hitTestRevealWidget(el, clickX, clickY);
         if (!hit)
             return;
+        const seat = seatFromPoint(el, hit.inline, clickX, clickY);
         let targetStart = hit.inline.start;
         if (revealState) {
             const active = revealState;
@@ -292,26 +399,28 @@ export function createWidgetInteraction(deps) {
                     targetStart += deps.node.raw.length - rawBefore;
             }
         }
-        const target = inlinesOf(deps.node).find((n) => n.start === targetStart &&
-            isInlineWidget(n, deps.node.raw) &&
-            getInlineWidgetEditing(n.kind)?.revealSource);
+        const target = widgetsOf().find((n) => n.start === targetStart && getInlineWidgetEditing(n.kind)?.revealSource);
         if (!target)
             return;
         el.focus();
         revealOpenedByLastClick = true;
-        // A click can't map to a source glyph — land at the leading edge (offset 0).
-        void startReveal(target, target.start, 0);
+        void startReveal(target, target.start, seat ?? insideEndOffset(target));
     }
-    /** Take the whole revealed token; declines unless the native selection sits inside it. */
-    function selectRevealedSource() {
+    /**
+     * Take the whole revealed token; declines unless the double-click landed on it. Keyed off the
+     * point, not the selection: the root's second-press word select runs before this click and
+     * may have moved the selection off the source.
+     */
+    function selectRevealedSource(x, y) {
         const source = activeSourceNode;
-        if (!revealState || !source)
-            return false;
-        const selection = window.getSelection();
-        if (!selection || !selection.anchorNode || !source.contains(selection.anchorNode))
+        if (!revealState || !source || y === null)
             return false;
         const range = document.createRange();
         range.selectNodeContents(source);
+        const onSource = Array.from(range.getClientRects()).some((r) => x >= r.left && x <= r.right && y >= r.top && y <= r.bottom);
+        const selection = window.getSelection();
+        if (!onSource || !selection)
+            return false;
         selection.removeAllRanges();
         selection.addRange(range);
         return true;
@@ -411,6 +520,13 @@ export function createWidgetInteraction(deps) {
             }
             return true;
         }
+        // A vertical arrow is the shared pipeline's line walk, which needs a real caret to read:
+        // seat one at the edge the arrow leaves from and decline, so the walk runs from there.
+        if (!e.shiftKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+            deps.cursor.setRaw(asRawOffset(e.key === 'ArrowUp' ? widget.start : widget.end));
+            deps.widgetSelection.clear();
+            return false;
+        }
         // Reading mode still swallows — a selected widget owns its keys — but commits nothing.
         // Undo anchored at the pre-select caret, so Ctrl+Z restores the caret where the user
         // actually was when selection took over.
@@ -477,6 +593,26 @@ export function createWidgetInteraction(deps) {
             });
         }
     }
+    // Only where the kind names a content span and the caret is inside it: a hard break is two
+    // bytes with a caret position between them and nothing to edit there.
+    function revealInterior(offset) {
+        const parkedByFold = foldParkedCaret === offset;
+        foldParkedCaret = null;
+        if (parkedByFold || revealState)
+            return false;
+        const widget = widgetsOf().find((w) => w.start < offset && offset < w.end);
+        if (!widget)
+            return false;
+        const editing = getInlineWidgetEditing(widget.kind);
+        if (!editing?.revealSource || !editing.revealContentSpan)
+            return false;
+        const at = offset - widget.start;
+        const span = editing.revealContentSpan(deps.node.raw.slice(widget.start, widget.end));
+        if (!span || at < span.start || at > span.end)
+            return false;
+        void startReveal(widget, offset, at);
+        return true;
+    }
     function enterEdgeWidget(side) {
         const inlines = inlinesOf(deps.node);
         if (inlines.length === 0)
@@ -518,28 +654,37 @@ export function createWidgetInteraction(deps) {
         }
         // The first click of a double-click already revealed, so the second lands in the source
         // text and the browser's word rule takes `[` or `$` as a word of its own.
-        if (doubleClick && revealOpenedByLastClick && selectRevealedSource())
+        if (doubleClick && revealOpenedByLastClick && selectRevealedSource(clickX, clickY))
             return;
-        // A click in a real text node keeps the native caret; a synthetic overlay would compete.
-        if (caretIsInTextContent(el, window.getSelection()))
+        // The snap below seats a CARET, so it stands down for a range this surface paints, which it
+        // would collapse; the rule `clampOutOfAmbient` already carries.
+        const live = window.getSelection();
+        if (surfaceHoldsRange(el, live))
             return;
-        for (const inline of inlinesOf(deps.node)) {
-            if (!isInlineWidget(inline, deps.node.raw))
-                continue;
+        const seat = nearestWidgetEdgeSeat(measuredWidgets(el), clickX, clickY);
+        if (seat === null)
+            return;
+        // A press BESIDE an island stands down for a visible caret; a press ON one cannot, since the
+        // engine answers that hit test with a position in the neighbouring text.
+        if (!seat.inside && caretIsInTextContent(el, live))
+            return;
+        el.focus();
+        deps.cursor.setRaw(asRawOffset(seat.offset));
+        // `setRaw`'s walker may have landed in a trailing text node, where native renders.
+        if (!caretIsInTextContent(el, window.getSelection()))
+            deps.setSnapTarget(seat.offset);
+    }
+    function* measuredWidgets(el) {
+        for (const inline of widgetsOf()) {
             const widget = widgetElByStart(el, inline.start);
-            if (!widget)
-                continue;
-            const rect = widget.getBoundingClientRect();
-            const snapTo = clickX > rect.right ? inline.end : clickX < rect.left ? inline.start : null;
-            if (snapTo === null)
-                continue;
-            el.focus();
-            deps.cursor.setRaw(asRawOffset(snapTo));
-            // `setRaw`'s walker may have landed in a trailing text node, where native renders.
-            if (!caretIsInTextContent(el, window.getSelection())) {
-                deps.setSnapTarget(snapTo);
+            if (widget) {
+                yield {
+                    start: inline.start,
+                    end: inline.end,
+                    rect: widget.getBoundingClientRect(),
+                    seatsInside: isCharacterLikeWidget(inline.kind)
+                };
             }
-            return;
         }
     }
     function widgetExtensionTarget(key) {
@@ -549,9 +694,7 @@ export function createWidgetInteraction(deps) {
         const focus = selectionFocusWalkOffset(el, deps.getAmbientLength());
         if (focus === null)
             return null;
-        for (const inline of inlinesOf(deps.node)) {
-            if (!isInlineWidget(inline, deps.node.raw))
-                continue;
+        for (const inline of widgetsOf()) {
             if (key === 'ArrowRight' && focus >= inline.start && focus < inline.end) {
                 return inline.end;
             }
@@ -579,6 +722,7 @@ export function createWidgetInteraction(deps) {
         handleSelectedWidgetKeydown,
         handleShiftArrowIntoWidget,
         enterWidget,
+        revealInterior,
         enterEdgeWidget,
         snapClickToWidgetEdge,
         isRevealing,

package/dist/components/drag-handle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The block drag handle's two policies, kept out of the components that render it: which
+ * blocks carry one, and where its grip sits.
+ *
+ * Presence: prose carries none. A paragraph, a heading, a quote and the note cards read as
+ * text on the page, and a grip beside every one of them is noise; the blocks that get one are
+ * the objects a reader picks up whole — pictures, code, tables, equations, diagrams, list
+ * items, dividers. A gripless block is still a reorder unit: keyboard reorder moves it and a
+ * dragged block still drops beside it.
+ */
+import type { NodeView } from '../core/node-views';
+export declare function isImageOnlyParagraph(node: NodeView): boolean;
+/**
+ * A picture's grip does NOT wait for `blockDragHandles`: dragging it is the only pointer road
+ * to move a picture, and unlike prose it is a discrete object a reader expects to pick up. The
+ * caller still gates reading mode, which shows no affordances at all.
+ */
+export declare function showsDragHandle(node: NodeView, handlesEnabled: boolean): boolean;
+/**
+ * A list item's grip reorders it among its SIBLINGS and nowhere else: the drag is scoped to
+ * the enclosing list, so a lone item has nothing to trade places with and its grip is a
+ * promise the drop can't keep. It reappears the moment a second item joins the list.
+ */
+export declare function showsListItemDragHandle(itemCount: number, handlesEnabled: boolean): boolean;
+/**
+ * Vertical centre of the grip. A one-line block centres on its row. A taller one takes the
+ * first line-height of its OWN box — not its first line of text, since a card pads above that
+ * and a grip level with the first code line hangs below the card's shoulder. A declared anchor
+ * SHORTER than a line is a marker to centre on instead (a wrapped task item's checkbox); a
+ * taller one is a card, and the band already covers it.
+ */
+export declare function dragHandleAnchorY(host: HTMLElement): number | null;
+/**
+ * Svelte attachment for the handle element: places the grip once the block has laid out, and
+ * again on every pointerover inside its host, so it follows edits made while hovered.
+ *
+ * The mount placement is what makes the grip HITTABLE where it appears: it is its own hit
+ * target before any hover, so a target parked at the stylesheet's default while the grip would
+ * settle elsewhere is a target the pointer misses. One rAF-batched read per handle.
+ */
+export declare function alignDragHandle(handle: HTMLElement): (() => void) | void;

package/dist/components/drag-handle.js

@@ -0,0 +1,134 @@
+/**
+ * The block drag handle's two policies, kept out of the components that render it: which
+ * blocks carry one, and where its grip sits.
+ *
+ * Presence: prose carries none. A paragraph, a heading, a quote and the note cards read as
+ * text on the page, and a grip beside every one of them is noise; the blocks that get one are
+ * the objects a reader picks up whole — pictures, code, tables, equations, diagrams, list
+ * items, dividers. A gripless block is still a reorder unit: keyboard reorder moves it and a
+ * dragged block still drops beside it.
+ */
+import { BLOCK_CONTENT_SELECTOR, DRAG_ANCHOR_ATTR } from './block-content-selector';
+/**
+ * Prose — the page's background and its asides — plus the list SHELL, whose own grip would
+ * land in the gutter on top of its first item's and take the hit test with it. A list moves
+ * an item at a time; the shell is a wrapper, not a thing to pick up.
+ */
+const GRIPLESS_KINDS = new Set([
+    'paragraph',
+    'heading',
+    'blockquote',
+    'admonition',
+    'githubAlert',
+    'list'
+]);
+/**
+ * A paragraph holding nothing but images is a picture in the page, not prose: it reads as a
+ * block of its own and is exactly the thing a reader reaches to move. A false negative here
+ * (an alt with an escaped bracket, an image beside a word) is the plain no-grip paragraph.
+ */
+const IMAGE_ONLY_PARAGRAPH = /^\s*(?:!\[[^\]]*\](?:\([^)]*\)|\[[^\]]*\])\s*)+$/;
+export function isImageOnlyParagraph(node) {
+    return node.kind === 'paragraph' && IMAGE_ONLY_PARAGRAPH.test(node.raw);
+}
+/**
+ * A picture's grip does NOT wait for `blockDragHandles`: dragging it is the only pointer road
+ * to move a picture, and unlike prose it is a discrete object a reader expects to pick up. The
+ * caller still gates reading mode, which shows no affordances at all.
+ */
+export function showsDragHandle(node, handlesEnabled) {
+    if (isImageOnlyParagraph(node))
+        return true;
+    return handlesEnabled && !GRIPLESS_KINDS.has(node.kind);
+}
+/**
+ * A list item's grip reorders it among its SIBLINGS and nowhere else: the drag is scoped to
+ * the enclosing list, so a lone item has nothing to trade places with and its grip is a
+ * promise the drop can't keep. It reappears the moment a second item joins the list.
+ */
+export function showsListItemDragHandle(itemCount, handlesEnabled) {
+    return handlesEnabled && itemCount > 1;
+}
+/** A box within this many line-heights holds one row of content, margins included. */
+const SINGLE_LINE = 1.5;
+/**
+ * Vertical centre of the grip. A one-line block centres on its row. A taller one takes the
+ * first line-height of its OWN box — not its first line of text, since a card pads above that
+ * and a grip level with the first code line hangs below the card's shoulder. A declared anchor
+ * SHORTER than a line is a marker to centre on instead (a wrapped task item's checkbox); a
+ * taller one is a card, and the band already covers it.
+ */
+export function dragHandleAnchorY(host) {
+    const content = host.querySelector(BLOCK_CONTENT_SELECTOR);
+    if (!content)
+        return null;
+    const hostRect = host.getBoundingClientRect();
+    const line = lineHeightOf(content);
+    const rect = paintedRect(content);
+    // A one-line block IS its own band, and the eye puts the grip level with the row rather
+    // than a hair above its middle — a list item, a task row, a rule.
+    const box = rect.height <= line * SINGLE_LINE ? rect : (markerRect(content, line) ?? bandRect(rect, line));
+    if (!box || box.height === 0)
+        return null;
+    const y = box.top + box.height / 2 - hostRect.top;
+    // A box painting outside the host (a scrolled or offscreen region) seats nothing.
+    return y >= 0 && y <= hostRect.height ? y : null;
+}
+function lineHeightOf(content) {
+    const line = parseFloat(getComputedStyle(content).lineHeight);
+    return Number.isFinite(line) && line > 0 ? line : 20;
+}
+/** The declared anchor, taken only while it is marker-sized and on the block's first line. */
+function markerRect(content, line) {
+    const declared = content.matches(`[${DRAG_ANCHOR_ATTR}]`)
+        ? content
+        : content.querySelector(`[${DRAG_ANCHOR_ATTR}]`);
+    const rect = declared?.getBoundingClientRect();
+    if (!rect || rect.height === 0 || rect.height > line)
+        return null;
+    return rect.top - content.getBoundingClientRect().top > line ? null : rect;
+}
+/**
+ * The box the band measures from: the content's own, unless it leads with an atomic widget
+ * (a picture in a paragraph), whose margin would otherwise seat the grip above the picture and
+ * flush with its corner.
+ */
+function paintedRect(content) {
+    const rect = content.getBoundingClientRect();
+    const widget = content.firstElementChild?.closest('[data-inline-widget]');
+    const widgetRect = widget?.getBoundingClientRect();
+    return widgetRect && widgetRect.height > 0 && widgetRect.top > rect.top ? widgetRect : rect;
+}
+/** The top line-height of a box; a box shorter than a line is its own band. */
+function bandRect(rect, line) {
+    return new DOMRect(rect.x, rect.y, rect.width, Math.min(line, rect.height));
+}
+/**
+ * Svelte attachment for the handle element: places the grip once the block has laid out, and
+ * again on every pointerover inside its host, so it follows edits made while hovered.
+ *
+ * The mount placement is what makes the grip HITTABLE where it appears: it is its own hit
+ * target before any hover, so a target parked at the stylesheet's default while the grip would
+ * settle elsewhere is a target the pointer misses. One rAF-batched read per handle.
+ */
+export function alignDragHandle(handle) {
+    const host = handle.parentElement;
+    if (!host)
+        return;
+    const grip = handle.firstElementChild;
+    if (!grip)
+        return;
+    // Inline `top` on the grip (px from the host's top to its centre; the stylesheet's
+    // translateY(-50%) does the centring) overrides the stylesheet's half-line default.
+    const place = () => {
+        const y = dragHandleAnchorY(host);
+        if (y !== null)
+            grip.style.top = `${y}px`;
+    };
+    const settled = requestAnimationFrame(place);
+    host.addEventListener('pointerover', place);
+    return () => {
+        cancelAnimationFrame(settled);
+        host.removeEventListener('pointerover', place);
+    };
+}

package/dist/components/editor-root-focus.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Editor-root focus attribution: which block host holds the caret. The path drives each
+ * windowing scope's per-level pin, so a scroll that pushes the caret off-screen never tears
+ * down native focus/IME; the `data-focused` attribute is what both preview modes' CSS key
+ * their focused-block reveal off. The installing `$effect`s stay in `Editor.svelte`.
+ */
+import { type PresentationMode } from '../presentation-mode';
+export interface FocusAttributionDeps {
+    /** A getter, never a value: every attribute write is gated on the mode in force. */
+    get mode(): PresentationMode;
+}
+export interface FocusAttribution {
+    /** `root` is the element the installing effect captured, not a live binding. */
+    install(root: HTMLElement): () => void;
+    /** Entering a preview mode marks the already-focused block, since no re-focus fires. */
+    applyForMode(): void;
+    getFocusedPath(): number[] | null;
+}
+export declare function createFocusAttribution(deps: FocusAttributionDeps): FocusAttribution;

package/dist/components/editor-root-focus.js

@@ -0,0 +1,67 @@
+/**
+ * Editor-root focus attribution: which block host holds the caret. The path drives each
+ * windowing scope's per-level pin, so a scroll that pushes the caret off-screen never tears
+ * down native focus/IME; the `data-focused` attribute is what both preview modes' CSS key
+ * their focused-block reveal off. The installing `$effect`s stay in `Editor.svelte`.
+ */
+import { assertInvariant } from '../assert';
+import { checkLandableCaret } from '../invariants/landable-caret';
+import { isPreviewMode } from '../presentation-mode';
+import { readBlockPath } from '../selection/path-lookup';
+import { onRoot, removeAll } from './editor-root-listeners';
+export function createFocusAttribution(deps) {
+    // Plain fields, never reactive: focusout fires mid-teardown during a structural commit,
+    // where a reactive write would trip state_unsafe_mutation.
+    let focusedPath = null;
+    let focusedHostEl = null;
+    // Mode-gated so source/reading DOM stays byte-identical.
+    function applyFocusedAttr() {
+        if (focusedHostEl && isPreviewMode(deps.mode)) {
+            focusedHostEl.setAttribute('data-focused', '');
+        }
+        else {
+            focusedHostEl?.removeAttribute('data-focused');
+        }
+    }
+    function setFocusedHost(host) {
+        if (focusedHostEl === host)
+            return;
+        focusedHostEl?.removeAttribute('data-focused');
+        focusedHostEl = host;
+        applyFocusedAttr();
+    }
+    function clear() {
+        focusedPath = null;
+        setFocusedHost(null);
+    }
+    function install(root) {
+        const onFocusIn = (e) => {
+            const host = e.target?.closest('[data-block-path]');
+            if (!host || !root.contains(host)) {
+                clear();
+                return;
+            }
+            setFocusedHost(host);
+            const path = readBlockPath(host);
+            focusedPath = path && path.length > 0 ? path : null;
+            // G1.33 at the seam every caret door crosses: a door seats a caret by focusing the
+            // surface, whoever minted it, so a consumer's own door inherits the guard here.
+            const landed = e.target;
+            if (landed instanceof HTMLElement) {
+                assertInvariant('landable-caret', () => checkLandableCaret(landed, deps.mode, path ?? []));
+            }
+        };
+        const onFocusOut = (e) => {
+            const next = e.relatedTarget;
+            if (next && root.contains(next))
+                return; // moving between blocks — keep the pin
+            clear();
+        };
+        return removeAll(onRoot(root, 'focusin', onFocusIn), onRoot(root, 'focusout', onFocusOut));
+    }
+    return {
+        install,
+        applyForMode: applyFocusedAttr,
+        getFocusedPath: () => focusedPath
+    };
+}

package/dist/components/editor-root-geometry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Editor-root geometry observers: the width and viewport-height watchers, the type-scale probe
+ * and the header-slot compensation. Each observes the element its installing `$effect`
+ * captured and returns the teardown; the reactive signals they feed (`widthVersion`,
+ * `typeScale`, `viewportHeightVersion`) stay in `Editor.svelte`, which is what the rest of the
+ * root reads. ResizeObserver's per-callback batching is the coalescing; no timer debounce (G4.4).
+ */
+import type { UserScrollport } from '../cursor/scroll-ancestors';
+import type { Scrollport } from '../cursor/scrollport';
+/** Calls `onWidthChange` when `el`'s width moves. A height-only resize is ignored: only a
+ *  re-wrap stales the measured heights. */
+export declare function installWidthWatcher(el: HTMLElement, onWidthChange: () => void): () => void;
+/** Calls `bump` on a height change of the resolved scrollport `target`. */
+export declare function installViewportHeightWatcher(target: UserScrollport, bump: () => void): () => void;
+export interface TypeScaleProbeDeps {
+    /** Read at each report, so the sub-percent guard compares against the scale in force. */
+    getScale(): number;
+    onScale(next: number): void;
+}
+/**
+ * The width watcher's sibling: a font-size move puts the height estimates off several-fold, so
+ * a document whose true height clears the activation watermark can fail to window at all. No
+ * other box in the root reports it, hence the `1em` probe; the scale is relative to the size
+ * `HEIGHT_ESTIMATES` were calibrated at.
+ */
+export declare function installTypeScaleProbe(el: HTMLElement, deps: TypeScaleProbeDeps): () => void;
+export interface HeaderSlotCompensationDeps {
+    el: HTMLElement;
+    port: Pick<Scrollport, 'scrollTop' | 'scrollBy'>;
+    ownsScrollCorrection(): boolean;
+    revealHoldsScroll(): boolean;
+}
+/**
+ * The header slot's height lives outside the height model, so while the editor owns the
+ * correction a growing header would slide the document under the reader. Compensating from
+ * the SLOT's own resize composes with `correctAnchor` instead of double-correcting; a reveal
+ * already holding the scroll outranks it.
+ */
+export declare function installHeaderSlotCompensation(deps: HeaderSlotCompensationDeps): () => void;