@voithos-labs/aragonite 0.10.1

package/dist/reactivity/list-windowing.svelte.js

@@ -0,0 +1,402 @@
+/**
+ * One windowing wiring unit per BlockList-bearing scope (the editor root and every
+ * activated nested container). Composes the height oracle, a per-scope Fenwick model, and
+ * `createBlockWindow`; maps the single editor scrollport into this scope's coordinate
+ * range by DOM measurement, and reports this scope's own box height upward so ancestor
+ * spacers stay correct. See `docs/design/virtual-rendering.md`.
+ */
+import { tick, untrack } from 'svelte';
+import { HeightModel } from '../cursor/height-model';
+import { createBlockWindow } from './block-window.svelte';
+import { estimateWidth, effectiveViewportHeight, listTopWithinContent } from './scope-geometry';
+import { runMeasureBatch } from './measure-batch';
+/**
+ * Resize-gate decision (pure, unit-tested). Keyed on the height DIFFERING from what is
+ * recorded, never on which callback delivered it: a cached remount can report the grown
+ * size in the very first callback, so a callback-order heuristic would drop it.
+ * `recorded === undefined` means the batched mount pass hasn't measured this block yet —
+ * defer to it rather than racing a lone read in on a fling-dirtied layout.
+ */
+export function shouldRemeasureOnResize(recorded, observed) {
+    if (observed <= 0 || recorded === undefined)
+        return false;
+    return Math.abs(recorded - observed) >= 1;
+}
+// One shared result backs every collapsed scope — frozen so a consumer mutating
+// its window cannot silently corrupt sibling scopes through the singleton.
+const collapsedWindow = Object.freeze({
+    active: true,
+    start: 0,
+    end: 1,
+    topSpacerPx: 0,
+    bottomSpacerPx: 0
+});
+// This scope's list top within the port's scroll content — the offset mapping port scrollTop
+// into this scope's local range, real at every depth because spacers preserve the geometry
+// above the list. One home: a divergence between its consumers below would be a
+// coordinate-mapping bug. The arithmetic itself is pure (`scope-geometry`).
+function listTopInPort(port, listEl) {
+    return listTopWithinContent(listEl.getBoundingClientRect().top, port.viewportTop(), port.scrollTop());
+}
+export function createListWindowing(deps) {
+    // The id list index-aligned with the CURRENT `model`. Snapshotted, not read live: a
+    // structural rebuild needs the OLD ordering to remap the anchor by id, and by then
+    // `getChildIds()` already reflects the new children. Copied — it is spliced in place.
+    let modelChildIds = [];
+    function buildModel() {
+        const width = estimateWidth(deps.getListEl(), deps.getPort()?.contentWidth() ?? 0);
+        const children = deps.getChildren();
+        // Indexed, and off the snapshot: `map` pays a `has` trap beside every `get`, once per child.
+        modelChildIds = deps.getChildIds().slice();
+        const count = children.length;
+        const heights = new Array(count);
+        for (let i = 0; i < count; i++) {
+            heights[i] = deps.oracle.height(modelChildIds[i], children[i], width);
+        }
+        return new HeightModel(heights);
+    }
+    let model = $state(buildModel());
+    let heightVersion = $state(0);
+    // One scope-owned batched pass rather than a per-child effect, which would interleave a
+    // layout read with the prior child's write → one forced reflow per mounted block on a
+    // fling. `pending` holds ids awaiting their first measure; the batch effect drains it.
+    const registry = new Map();
+    const pending = new Set();
+    /**
+     * The scrollTop putting the active reveal target at its requested placement, or null
+     * when no reveal is in flight. The one definition of "where the target belongs",
+     * shared by the writer that moves there and the predicate that asks if we already are.
+     * The ancestor's offset comes from the Fenwick model, never `getBoundingClientRect`: a
+     * model write only marks `$state` dirty, so a DOM read here would see pre-flush layout.
+     */
+    function revealTargetScrollTop() {
+        const port = deps.getPort();
+        const listEl = deps.getListEl();
+        const reveal = deps.getRevealAnchorTarget?.() ?? null;
+        if (reveal == null || reveal.index >= model.size || !port || !listEl)
+            return null;
+        const targetTop = listTopInPort(port, listEl) + model.offsetOf(reveal.index) + reveal.innerOffset;
+        // Center off the PORT's own height, NOT `scopeViewportHeight()`: the port's is stable
+        // through the shrink, whereas the scope-intersection reads listEl geometry mid-mutate
+        // and would center off a transiently-tiny viewport.
+        const targetHeight = reveal.height ?? model.heightOf(reveal.index);
+        return reveal.block === 'center'
+            ? targetTop - Math.max(0, (port.viewportHeight() - targetHeight) / 2)
+            : targetTop;
+    }
+    function placeRevealTarget() {
+        const targetScrollTop = revealTargetScrollTop();
+        const port = deps.getPort();
+        if (targetScrollTop === null || !port)
+            return false;
+        port.setScrollTop(targetScrollTop);
+        // A programmatic scrollTop write fires no `scroll` event, so the window's derived
+        // scrollTop would stay stale and leave the target windowed OUT at the very position
+        // we just scrolled it to.
+        win.syncScrollTop();
+        return true;
+    }
+    /**
+     * Runs the mutation and writes no scroll while the HOST's native anchoring holds the reader
+     * (host mode below the windowing budget). It outranks even the reveal claim, which would
+     * otherwise re-assert an absolute position the browser is already holding — two writers,
+     * one scroll position, double the correction.
+     */
+    function skipWhileHostAnchors(mutate) {
+        if (deps.correctsScroll())
+            return false;
+        mutate();
+        return true;
+    }
+    /**
+     * The reveal claim outranks either anchor rule: the target's absolute position is
+     * re-asserted after the mutation, overriding the browser's auto-clamp (which drags
+     * scrollTop off the target as undecoded off-window images measure ~0). Delta
+     * compensation can't win — the clamp outpaces it. Returns true when it ran the
+     * mutation and owns the scroll position; shared because BOTH correctors need it.
+     */
+    function reassertRevealAnchor(mutate) {
+        const reveal = deps.getRevealAnchorTarget?.() ?? null;
+        if (reveal == null || reveal.index >= model.size || !deps.getPort())
+            return false;
+        mutate();
+        placeRevealTarget();
+        return true;
+    }
+    // Hold the anchor block's screen position across a height mutation that would otherwise
+    // slide the visible content (VR-2) — native `overflow-anchor` is off wherever this runs, so
+    // nothing else holds the line. The delta comes from the Fenwick model, not
+    // `getBoundingClientRect`: a model write only marks `$state` dirty, so a DOM read here
+    // would see pre-flush layout and a ~0 delta.
+    function correctAnchor(mutate) {
+        if (skipWhileHostAnchors(mutate))
+            return;
+        if (reassertRevealAnchor(mutate))
+            return;
+        const port = deps.getPort();
+        const anchorIndex = model.indexAtOffset(localScrollTop());
+        const before = model.offsetOf(anchorIndex);
+        mutate();
+        const delta = model.offsetOf(anchorIndex) - before;
+        if (delta !== 0 && port)
+            port.setScrollTop(port.scrollTop() + delta);
+    }
+    // The structural-rebuild variant of correctAnchor. A count change shifts every index
+    // above it, so the numeric form would measure a DIFFERENT block at index N and mis-correct
+    // by ~one anchor-block height (VR-2 jump on an above-fold edit). Remap by stable id
+    // instead, captured against the OLD ordering in `modelChildIds`; a deleted anchor has no
+    // surviving block to hold the line, so skip.
+    function correctAnchorByStableId(mutate) {
+        if (skipWhileHostAnchors(mutate))
+            return;
+        if (reassertRevealAnchor(mutate))
+            return;
+        const port = deps.getPort();
+        const lst = localScrollTop();
+        const anchorIndex = model.indexAtOffset(lst);
+        const before = model.offsetOf(anchorIndex);
+        const anchorId = modelChildIds[anchorIndex];
+        mutate();
+        // At lst === 0 the top-of-viewport block belongs to an ancestor scope, so there is no
+        // local anchor: a nonzero delta could only come from the anchor being relocated
+        // within this scope, and following it would shift the shared scrollTop spuriously.
+        // The numeric form needs no such guard — its offsetOf(same index) is 0 here anyway.
+        if (lst === 0)
+            return;
+        const newIndex = anchorId !== undefined ? modelChildIds.indexOf(anchorId) : -1;
+        if (newIndex === -1)
+            return;
+        const delta = model.offsetOf(newIndex) - before;
+        if (delta !== 0 && port)
+            port.setScrollTop(port.scrollTop() + delta);
+    }
+    let lastWidthVersion = deps.getWidthVersion();
+    // Rebuild on any structural child change or an editor WIDTH change, never per keystroke.
+    // Keying on the id SEQUENCE rather than its length is load-bearing: a reorder leaving the count
+    // unchanged would skip the rebuild. `untrack` keeps the effect from subscribing to every child's
+    // raw via the oracle; the reseed's wholesale offset shift anchor-corrects by stable id.
+    $effect(() => {
+        const ids = deps.getChildIds();
+        for (let i = 0; i < ids.length; i++)
+            void ids[i];
+        void deps.getPort();
+        const widthVersion = deps.getWidthVersion();
+        untrack(() => {
+            const widthChanged = widthVersion !== lastWidthVersion;
+            lastWidthVersion = widthVersion;
+            // ONE correction across ONE model transition: a delta taken between the reseed and
+            // the re-measure compares measured-before against all-estimate-after, and lands the
+            // anchor a block off wherever the poisoned model names a different top child (#188).
+            // Width only — re-measuring on a structural edit costs a reflow per split.
+            correctAnchorByStableId(() => {
+                model = buildModel();
+                heightVersion++;
+                if (widthChanged)
+                    remeasureMounted();
+            });
+        });
+    });
+    // Map the port's scrollTop into this scope's local range.
+    function localScrollTop() {
+        const port = deps.getPort();
+        const listEl = deps.getListEl();
+        if (!port || !listEl)
+            return 0;
+        return Math.max(0, port.scrollTop() - listTopInPort(port, listEl));
+    }
+    // Each scope windows against its OWN slice of the viewport: against the full port
+    // height, N stacked active scopes would each mount a viewport's worth of blocks. Falls
+    // back to the full height when the list is unmounted. Read only by the window derived,
+    // which is why the height version belongs here and not in `revealTargetScrollTop`.
+    function scopeViewportHeight() {
+        void deps.getViewportHeightVersion();
+        const port = deps.getPort();
+        const listEl = deps.getListEl();
+        if (!port)
+            return 0;
+        if (!listEl)
+            return port.viewportHeight();
+        const listRect = listEl.getBoundingClientRect();
+        return effectiveViewportHeight(port.viewportTop(), port.viewportHeight(), listRect.top, listRect.height);
+    }
+    // This scope's pin: the focused path's index at this scope's depth, iff the focus path
+    // descends through this scope.
+    function pinnedIndex() {
+        const fp = deps.getFocusPath();
+        const pp = deps.getParentPath();
+        if (!fp || fp.length <= pp.length)
+            return null;
+        for (let i = 0; i < pp.length; i++)
+            if (fp[i] !== pp[i])
+                return null;
+        return fp[pp.length];
+    }
+    const win = createBlockWindow({
+        getModel: () => {
+            void heightVersion;
+            return model;
+        },
+        getPort: deps.getPort,
+        getLocalScrollTop: localScrollTop,
+        getViewportHeight: scopeViewportHeight,
+        getPinnedIndex: pinnedIndex,
+        overscan: deps.overscan,
+        pinExtensionCap: deps.pinExtensionCap,
+        activateAbovePx: deps.activateAbovePx,
+        deactivateBelowPx: deps.deactivateBelowPx
+    });
+    // The collapse clamp substituted at the returned surface. While collapsed this doesn't
+    // read `win.result`, so the bypassed math (and the hysteresis tracking) never observes
+    // the clamp.
+    const effectiveWindow = $derived.by(() => (deps.isCollapsed?.() ? collapsedWindow : win.result));
+    // Children measuring in resize the spacers, so the box height the parent measured at
+    // this container's mount goes stale. BOX height, not `model.total()`, so it matches what
+    // this container's own BlockHost measured — otherwise two writers fight over the slot.
+    // Gated on the box actually moving: ungated, the rect read and the upward write chain up
+    // the scopes inside the observer's own delivery frame, raising the RO loop warning (#189).
+    let reportedSelfHeight = 0;
+    $effect(() => {
+        void heightVersion;
+        const el = deps.getOwnEl?.();
+        if (!el || !deps.reportSelfHeight)
+            return;
+        const h = el.getBoundingClientRect().height;
+        if (h > 0 && Math.abs(h - reportedSelfHeight) >= 1) {
+            reportedSelfHeight = h;
+            deps.reportSelfHeight(h);
+        }
+    });
+    // The batched measure pass for NEWLY-MOUNTED children, keyed on the EFFECTIVE window: the
+    // raw result can be identical across a collapse expand, stranding remounted children in
+    // `pending` until the next scroll. Registration deliberately does NOT bump reactive
+    // state — the mount that registers a child already moved the window, so a per-child
+    // trigger would re-enter this effect O(children) times and trip the update-depth guard.
+    $effect(() => {
+        void effectiveWindow;
+        untrack(() => flushMeasurements());
+    });
+    // The UNCORRECTED batch: the caller owns the anchor correction, because nesting a second
+    // one inside an outer `mutate` double-counts the delta.
+    function drainMeasurements() {
+        if (pending.size === 0)
+            return;
+        const entries = [];
+        for (const id of pending) {
+            const child = registry.get(id);
+            if (child)
+                entries.push(child);
+        }
+        pending.clear();
+        runMeasureBatch(entries);
+    }
+    // A width rebuild reseeds every slot from the new-width estimate, but mounted blocks hold
+    // real heights and their measure effects key on `node.raw`, not width.
+    function remeasureMounted() {
+        for (const id of registry.keys())
+            pending.add(id);
+        drainMeasurements();
+    }
+    function flushMeasurements() {
+        if (pending.size === 0)
+            return;
+        // The batch writes above-viewport slots too, so the anchor correction keeps the
+        // top-of-viewport block fixed.
+        correctAnchor(drainMeasurements);
+    }
+    // Read the height BEFORE correctAnchor so no DOM read follows the model write. The write
+    // is convergence-guarded (`recordMeasuredChild` no-ops once the height settles), so a
+    // redundant call can't spin the reactive graph.
+    function measureOne(id) {
+        const child = registry.get(id);
+        if (!child)
+            return;
+        const h = child.readHeight();
+        if (h > 0)
+            correctAnchor(() => child.applyHeight(h));
+    }
+    return {
+        get window() {
+            return effectiveWindow;
+        },
+        // PASSIVE — no scrollTop correction; anchor stability rides estimate quality plus
+        // the spacers.
+        recordMeasuredChild(index, id, height) {
+            deps.oracle.recordMeasured(id, height);
+            if (index < model.size && model.heightOf(index) !== height) {
+                model.setHeight(index, height);
+                heightVersion++;
+            }
+        },
+        // List items aren't BlockHosts and have no other oracle writer, so without this write
+        // a parent rebuild would reseed their slots from estimates and the viewport jumps.
+        // Idempotent for hosted children. `modelChildIds`, not the live list, for the same
+        // reason `recordMeasuredChild` takes its id from the caller: both write a model
+        // indexed by the snapshot.
+        setChildSubtotal(index, total) {
+            const id = modelChildIds[index];
+            if (id !== undefined)
+                deps.oracle.recordMeasured(id, total);
+            if (index >= model.size || model.heightOf(index) === total)
+                return;
+            const write = () => {
+                model.setHeight(index, total);
+                heightVersion++;
+            };
+            // Correction-free unless a reveal claim is live — the claim is the gate, so the
+            // no-cascade rule stands for every other write. Without it, growth INSIDE the
+            // target's own container pushes a resolved target down by its full height (#32).
+            if (!skipWhileHostAnchors(write) && !reassertRevealAnchor(write))
+                write();
+        },
+        // Enroll without touching reactive state: the mount that registers this child already
+        // moved the window, which re-runs the batch effect to drain `pending`.
+        registerChild(id, child) {
+            registry.set(id, child);
+            pending.add(id);
+            return () => {
+                registry.delete(id);
+                pending.delete(id);
+            };
+        },
+        // Ungated: raw changed, so the height almost certainly did too.
+        measureChildNow(id) {
+            measureOne(id);
+        },
+        // ResizeObserver path for async growth. The gate reads the oracle's recorded height
+        // (O(1), no DOM), so the no-op mount resize a fling fires for every newly-mounted
+        // block returns without a rect read on the spacer-dirtied layout (VR-4).
+        measureChildOnResize(id, observedHeight) {
+            if (shouldRemeasureOnResize(deps.oracle.measured(id), observedHeight))
+                measureOne(id);
+        },
+        revealHoldsScroll() {
+            const targetScrollTop = revealTargetScrollTop();
+            const port = deps.getPort();
+            // Sub-pixel tolerance: the settle's own refinement lands a fraction of a device
+            // pixel off the model-derived position, and a strict compare would re-admit the delta.
+            return (targetScrollTop !== null && !!port && Math.abs(port.scrollTop() - targetScrollTop) <= 1);
+        },
+        async revealChild(index) {
+            // A clamped-out body child can never mount, so degrade instead of scroll-and-wait.
+            if (index >= 1 && deps.isCollapsed?.())
+                return;
+            const port = deps.getPort();
+            const listEl = deps.getListEl();
+            if (!port || !listEl)
+                return;
+            port.setScrollTop(listTopInPort(port, listEl) + model.offsetOf(index));
+            win.syncScrollTop();
+            await tick();
+        },
+        isInWindow(index) {
+            // The EFFECTIVE result, mandatorily: the unclamped inactive window answers true
+            // for every index, so a reveal into a collapsed body would await a mount that can
+            // never come (VR-5).
+            const { start, end } = effectiveWindow;
+            return index >= start && index < end;
+        },
+        dispose() {
+            win.dispose();
+        }
+    };
+}

package/dist/reactivity/measure-batch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read-all-then-write height measurement: a rect read right after a layout-dirtying height
+ * write forces a synchronous reflow PER block, so the pass splits into a pure read phase
+ * and a pure write phase and costs at most one reflow. Kept free of DOM and reactive state
+ * so the ordering is unit-testable with spies.
+ */
+export interface MeasureEntry {
+    /** Read this entry's DOM height (a layout read). */
+    readHeight: () => number;
+    /** Write the measured height into the model (a layout-dirtying write). */
+    applyHeight: (height: number) => void;
+}
+/** Read every entry's height, THEN apply every write. Heights <= 0 (unlaid-out /
+ *  jsdom) are skipped on write — the read still happens so the phase split holds. */
+export declare function runMeasureBatch(entries: Iterable<MeasureEntry>): void;

package/dist/reactivity/measure-batch.js

@@ -0,0 +1,18 @@
+/**
+ * Read-all-then-write height measurement: a rect read right after a layout-dirtying height
+ * write forces a synchronous reflow PER block, so the pass splits into a pure read phase
+ * and a pure write phase and costs at most one reflow. Kept free of DOM and reactive state
+ * so the ordering is unit-testable with spies.
+ */
+/** Read every entry's height, THEN apply every write. Heights <= 0 (unlaid-out /
+ *  jsdom) are skipped on write — the read still happens so the phase split holds. */
+export function runMeasureBatch(entries) {
+    const measured = [];
+    for (const entry of entries) {
+        const height = entry.readHeight();
+        if (height > 0)
+            measured.push({ applyHeight: entry.applyHeight, height });
+    }
+    for (const { applyHeight, height } of measured)
+        applyHeight(height);
+}

package/dist/reactivity/publish-ref.svelte.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A scope's ref-slot array, reached only through the accessors its owner mints. Object
+ * identity IS the scope: the mount registry keys on it, so a mount in one scope cannot wake
+ * a waiter in another (a nested level, a sibling container, a second editor instance).
+ * Neither accessor is reactive: every owner mints the slots over a plain array, so a `get`
+ * registers no dependency and a `set` wakes no effect; `whenRefMounted` is how a caller waits.
+ */
+export interface RefSlots<T> {
+    set(index: number, ref: T | undefined): void;
+    get(index: number): T | undefined;
+}
+/** Mints a scope over its ref array. Takes the array itself, not a getter, so a scope
+ *  cannot be re-aimed at a replacement: Svelte pins a teardown's reads to pre-flush values,
+ *  so a swapped array takes each cleanup's clear with it and strands the dead ref in the
+ *  live one. Publish a new set of contents with `replaceRefs`. */
+export declare function refSlotsOver<T>(refs: (T | undefined)[]): RefSlots<T>;
+/** Publishes a whole slot array in place, the only sanctioned way to replace a scope's
+ *  contents wholesale (see `refSlotsOver` for why identity is load-bearing). */
+export declare function replaceRefs<T>(target: (T | undefined)[], values: readonly (T | undefined)[]): void;
+/**
+ * Replaces `bind:this={refs[i]}` in a keyed each — Svelte 5's `bind:this` doesn't re-target
+ * when the iteration index shifts. Cleanup is conditional because effect-cleanup order
+ * across siblings isn't guaranteed, and an unconditional clear stomps a neighbor's slot.
+ * `el` is the ref's own box, which is what makes `isSlotDetached` answerable.
+ */
+export declare function publishRefSlot<T>(slots: RefSlots<T>, index: number, ref: T | undefined, el?: Element | null): () => void;
+export interface RevealChildOptions<T> {
+    /** This scope's ref slots: the read/drop surface, and the mount-wait's scope key. */
+    readonly slots: RefSlots<T>;
+    /** This scope's child count; an index at or past it can never mount (size lag). */
+    readonly childCount: number;
+    /** Scroll this scope so child `index` enters its window; resolves after a tick. */
+    readonly revealChild: (index: number) => Promise<void>;
+    /** True iff `index` is inside the scope's CURRENT mounted window, read AFTER `revealChild`
+     *  resolved (VR-5's termination guarantee). Optional only for a scope that does not window:
+     *  every production reveal supplies it, so the bounded re-wait below is the harness
+     *  fallback, not a live path. */
+    readonly isInWindow?: (index: number) => boolean;
+}
+/**
+ * Bring child `index` into its window before a caller reads its ref: drop a detached ref,
+ * scroll it in, and await its mount. Shared by the canonical container reveal and TableBlock's
+ * hand-rolled one, so the "is this slot a live mount" gate has one home. Termination (VR-5): only
+ * a mount at this index in THIS scope wakes the wait, so a windowing caller proves membership
+ * first and a non-windowing one races each wait against a tick, rather than parking forever.
+ */
+export declare function revealChildOrWait<T>(index: number, opts: RevealChildOptions<T>): Promise<void>;
+/**
+ * Resolve when slot `index` of `slots` is (or becomes) populated. Event-driven, woken by
+ * `publishRefSlot` on a real mount, never a timer (Design Rule #2 / G4.4). A wake can still
+ * be spurious within one scope: a mount that unpublishes in the same flush leaves the slot
+ * empty, so the caller re-checks.
+ */
+export declare function whenRefMounted<T>(slots: RefSlots<T>, index: number): Promise<void>;

package/dist/reactivity/publish-ref.svelte.js

@@ -0,0 +1,128 @@
+import { tick, untrack } from 'svelte';
+/** Mints a scope over its ref array. Takes the array itself, not a getter, so a scope
+ *  cannot be re-aimed at a replacement: Svelte pins a teardown's reads to pre-flush values,
+ *  so a swapped array takes each cleanup's clear with it and strands the dead ref in the
+ *  live one. Publish a new set of contents with `replaceRefs`. */
+export function refSlotsOver(refs) {
+    return {
+        set: (index, ref) => {
+            refs[index] = ref;
+        },
+        get: (index) => refs[index]
+    };
+}
+/** Publishes a whole slot array in place, the only sanctioned way to replace a scope's
+ *  contents wholesale (see `refSlotsOver` for why identity is load-bearing). */
+export function replaceRefs(target, values) {
+    target.length = values.length;
+    for (let i = 0; i < values.length; i++)
+        target[i] = values[i];
+}
+/**
+ * Replaces `bind:this={refs[i]}` in a keyed each — Svelte 5's `bind:this` doesn't re-target
+ * when the iteration index shifts. Cleanup is conditional because effect-cleanup order
+ * across siblings isn't guaranteed, and an unconditional clear stomps a neighbor's slot.
+ * `el` is the ref's own box, which is what makes `isSlotDetached` answerable.
+ */
+export function publishRefSlot(slots, index, ref, el) {
+    slots.set(index, ref);
+    if (el && typeof ref === 'object' && ref !== null)
+        publishedElements.set(ref, el);
+    // The cleanup's identity check compares against what the slot actually holds, not the raw
+    // ref; untracked, since publishers run inside effects and would self-invalidate.
+    const publishedRef = untrack(() => slots.get(index));
+    if (publishedRef !== undefined)
+        resolveMountWaiters(slots, index);
+    return () => {
+        if (slots.get(index) === publishedRef) {
+            slots.set(index, undefined);
+        }
+    };
+}
+// ── Mount attachment ─────────────────────────────────────────────────────────
+// Keyed on ref identity, not on (slots, index): a wholesale `replaceRefs` re-seats a saved
+// ref no publisher will run for again, and only the ref itself still knows its box. Weak,
+// so the entry dies with the ref rather than outliving the scope.
+const publishedElements = new WeakMap();
+/**
+ * True when the slot's ref is a mount that already left the DOM. The one home for the
+ * question every reveal asks before trusting a filled slot — and it is an ATTACHMENT
+ * question, never a window-membership one: a programmatic scroll moves the slice a flush
+ * before the DOM follows, so "off-window" clears refs whose components are still mounted
+ * and which nothing re-publishes. A ref with no recorded box degrades to live.
+ */
+function isSlotDetached(slots, index) {
+    const ref = slots.get(index);
+    if (typeof ref !== 'object' || ref === null)
+        return false;
+    const el = publishedElements.get(ref);
+    return el !== undefined && !el.isConnected;
+}
+/** Each wait races a tick, so a scope with no membership oracle would spin forever on a
+ *  child that never publishes. This bounds those turns. */
+const MAX_MOUNT_REWAITS = 64;
+/**
+ * Bring child `index` into its window before a caller reads its ref: drop a detached ref,
+ * scroll it in, and await its mount. Shared by the canonical container reveal and TableBlock's
+ * hand-rolled one, so the "is this slot a live mount" gate has one home. Termination (VR-5): only
+ * a mount at this index in THIS scope wakes the wait, so a windowing caller proves membership
+ * first and a non-windowing one races each wait against a tick, rather than parking forever.
+ */
+export async function revealChildOrWait(index, opts) {
+    const detached = isSlotDetached(opts.slots, index);
+    if (index >= opts.childCount || (!detached && opts.slots.get(index)))
+        return;
+    if (detached)
+        opts.slots.set(index, undefined);
+    await opts.revealChild(index);
+    if (opts.slots.get(index))
+        return;
+    if (opts.isInWindow) {
+        // Provably outside the recomputed window → the mount can't fire; degrade now.
+        if (!opts.isInWindow(index))
+            return;
+        // In-window, the mount flush is at most one tick away; still unpublished after it
+        // means a failed-render boundary left bind:this unset, waking no waiter.
+        await tick();
+        return;
+    }
+    // Membership unknowable: bounded mount-wait, each raced against a tick so a child that
+    // never publishes degrades within the cap instead of parking forever.
+    let rewaits = 0;
+    while (!opts.slots.get(index) && rewaits++ < MAX_MOUNT_REWAITS) {
+        await Promise.race([whenRefMounted(opts.slots, index), tick()]);
+    }
+}
+// ── Mount-await registry ─────────────────────────────────────────────────────
+const mountWaiters = new WeakMap();
+/**
+ * Resolve when slot `index` of `slots` is (or becomes) populated. Event-driven, woken by
+ * `publishRefSlot` on a real mount, never a timer (Design Rule #2 / G4.4). A wake can still
+ * be spurious within one scope: a mount that unpublishes in the same flush leaves the slot
+ * empty, so the caller re-checks.
+ */
+export function whenRefMounted(slots, index) {
+    if (slots.get(index) !== undefined)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let byIndex = mountWaiters.get(slots);
+        if (!byIndex) {
+            byIndex = new Map();
+            mountWaiters.set(slots, byIndex);
+        }
+        const list = byIndex.get(index);
+        if (list)
+            list.push(resolve);
+        else
+            byIndex.set(index, [resolve]);
+    });
+}
+function resolveMountWaiters(slots, index) {
+    const byIndex = mountWaiters.get(slots);
+    const list = byIndex?.get(index);
+    if (!byIndex || !list)
+        return;
+    byIndex.delete(index);
+    for (const resolve of list)
+        resolve();
+}

package/dist/reactivity/scope-geometry.d.ts

@@ -0,0 +1,18 @@
+/** This scope's own content element, not the scrollport: nested content lays out narrower and
+ *  the oracle's line-wrap is monotonic in width, so the port width undercounts at depth. Falls
+ *  back to the port, then a constant, when neither is measurable. */
+export declare function estimateWidth(listEl: {
+    clientWidth: number;
+} | null, portWidth: number): number;
+/**
+ * This scope's list top in the scrollport's CONTENT space — the offset mapping port scrollTop
+ * into the scope's local range. The two port terms are distinct and both load-bearing: an editor
+ * embedded partway down a page-scrolled shell has a nonzero scroll AND page chrome above it, and
+ * conflating them slices the window a band off.
+ */
+export declare function listTopWithinContent(listTop: number, viewportTop: number, scrollTop: number): number;
+/** The intersection of the port's viewport with this scope's own box. Each nested scope
+ *  occupies only part of the viewport, so windowing against the full port height would
+ *  mount O(viewport × active-scope-count) blocks. The viewport arrives as top + client
+ *  height so the intersection excludes the scrollbar/border. */
+export declare function effectiveViewportHeight(viewportTop: number, viewportHeight: number, scopeTop: number, scopeHeight: number): number;

package/dist/reactivity/scope-geometry.js

@@ -0,0 +1,29 @@
+/**
+ * Pure per-scope geometry for windowing, isolated from the reactive wiring in
+ * `list-windowing.svelte.ts` so it can be unit-tested without mounting a component.
+ */
+import { FALLBACK_CONTENT_WIDTH } from '../cursor/typography-estimates';
+/** This scope's own content element, not the scrollport: nested content lays out narrower and
+ *  the oracle's line-wrap is monotonic in width, so the port width undercounts at depth. Falls
+ *  back to the port, then a constant, when neither is measurable. */
+export function estimateWidth(listEl, portWidth) {
+    return listEl?.clientWidth || portWidth || FALLBACK_CONTENT_WIDTH;
+}
+/**
+ * This scope's list top in the scrollport's CONTENT space — the offset mapping port scrollTop
+ * into the scope's local range. The two port terms are distinct and both load-bearing: an editor
+ * embedded partway down a page-scrolled shell has a nonzero scroll AND page chrome above it, and
+ * conflating them slices the window a band off.
+ */
+export function listTopWithinContent(listTop, viewportTop, scrollTop) {
+    return listTop - viewportTop + scrollTop;
+}
+/** The intersection of the port's viewport with this scope's own box. Each nested scope
+ *  occupies only part of the viewport, so windowing against the full port height would
+ *  mount O(viewport × active-scope-count) blocks. The viewport arrives as top + client
+ *  height so the intersection excludes the scrollbar/border. */
+export function effectiveViewportHeight(viewportTop, viewportHeight, scopeTop, scopeHeight) {
+    const top = Math.max(viewportTop, scopeTop);
+    const bottom = Math.min(viewportTop + viewportHeight, scopeTop + scopeHeight);
+    return Math.max(0, bottom - top);
+}