@voithos-labs/aragonite 0.10.3 → 0.10.7

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

@@ -1,216 +1,101 @@
 /**
- * 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`.
+ * One windowing unit per block list, the editor root or a nested container: its height table
+ * and mounted range, read against the editor's one scroll container in this list's coordinates.
+ * See `docs/design/virtual-rendering.md` § Nesting.
  */
 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 scope has applied no height for this block yet —
- * defer to the batched pass rather than racing a lone read in on a fling-dirtied layout.
- */
+import { focusedIndexIn } from './hold-across';
+import { recordHeightTableBuild } from '../perf/instruments';
+/** Whether a resize is worth re-measuring: only when the height differs from the one this list
+ *  applied. With none applied yet, the batched pass owns the first measure. */
 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.
+// One shared result backs every collapsed list, frozen so a consumer that mutates its
+// window cannot quietly corrupt other lists through the shared object.
 const collapsedWindow = Object.freeze({
     active: true,
     start: 0,
     end: 1,
     topSpacerPx: 0,
-    bottomSpacerPx: 0
+    bottomSpacerPx: 0,
+    floorPx: 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`).
+// The box a nested list's parent measures: a container's block host, or a list item's own box.
+const MEASURED_BOX = '.block-host, .list-item-block';
 function listTopInPort(port, listEl) {
     return listTopWithinContent(listEl.getBoundingClientRect().top, port.viewportTop(), port.scrollTop());
 }
+/** The heights a table holds, keyed by id, for the next build to keep. */
+function heightsById(table) {
+    const carried = new Map();
+    const known = Math.min(table.ids.length, table.model.size);
+    for (let i = 0; i < known; i++)
+        carried.set(table.ids[i], table.model.heightOf(i));
+    return carried;
+}
 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);
+    // One batched pass per list, not an effect per child, which would interleave each layout read
+    // with the previous write and reflow once per mounted block. `pending` awaits a first measure.
+    const registry = new Map();
+    const pending = new Set();
+    /** A block that survives a rebuild keeps its measured height (`carried`), or the user scrolls by
+     *  the estimate error (VR-15). Null once a width or font-size change has made them wrong. */
+    function buildTable(carried, widthVersion) {
+        const listEl = deps.getListEl();
+        const width = estimateWidth(listEl, deps.getPort()?.contentWidth() ?? 0);
+        recordHeightTableBuild(deps.getParentPath(), width);
         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 ids = 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);
+            const id = ids[i];
+            heights[i] =
+                deps.oracle.measured(id) ?? carried?.get(id) ?? deps.oracle.estimate(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; registration 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;
-    }
-    /**
-     * Which block this correction holds still: the top-of-viewport one by default, the FOCUSED
-     * one when it sits at or below the fold. Clicking a construct that reveals its source (a
-     * math block, a paragraph holding inline math) resizes that block and folds whichever was
-     * revealed before it; anchored on the viewport top, both slide the clicked block out from
-     * under the pointer. Anchoring on the focused block holds its start offset instead, so it
-     * stays put and only the content after it reflows.
-     */
-    function anchorIndexFor(topIndex) {
-        const pinned = pinnedIndex();
-        if (pinned === null || pinned < topIndex || pinned >= model.size)
-            return topIndex;
-        return pinned;
+        return { model: new HeightModel(heights), ids, widthVersion, atListWidth: listEl !== null };
     }
-    // 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 = anchorIndexFor(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(() => {
+    // A derived, so new children window from their own table (VR-14); it tracks ids, not estimates,
+    // and the list element, so the first table, built before the element exists, is redone (VR-3).
+    let latestTable = null;
+    const table = $derived.by(() => {
         const ids = deps.getChildIds();
         for (let i = 0; i < ids.length; i++)
             void ids[i];
         void deps.getPort();
+        void deps.getListEl();
         const widthVersion = deps.getWidthVersion();
+        return untrack(() => {
+            const previous = latestTable;
+            if (previous !== null)
+                deps.scroll.beginRound();
+            const keepsHeights = previous !== null && previous.widthVersion === widthVersion && previous.atListWidth;
+            latestTable = buildTable(keepsHeights ? heightsById(previous) : null, widthVersion);
+            return latestTable;
+        });
+    });
+    let heightVersion = $state(0);
+    // Built now, so the tree has a table to count from before anything reads the window.
+    untrack(() => table);
+    // Width changes only: re-measuring on a structural edit costs a reflow.
+    let measuredWidth = untrack(() => table.widthVersion);
+    $effect(() => {
+        const next = table;
         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();
-            });
+            if (next.widthVersion === measuredWidth)
+                return;
+            measuredWidth = next.widthVersion;
+            remeasureMounted();
         });
     });
-    // Map the port's scrollTop into this scope's local range.
     function localScrollTop() {
         const port = deps.getPort();
         const listEl = deps.getListEl();
@@ -218,10 +103,8 @@ export function createListWindowing(deps) {
             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`.
+    // Each list windows against its own slice of the viewport, or N stacked lists would each
+    // mount a viewport's worth of blocks. The full height stands in while the list is unmounted.
     function scopeViewportHeight() {
         void deps.getViewportHeightVersion();
         const port = deps.getPort();
@@ -233,68 +116,33 @@ export function createListWindowing(deps) {
         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];
+    function focusedIndex() {
+        return focusedIndexIn(deps.getFocusPath(), deps.getParentPath());
     }
     const win = createBlockWindow({
         getModel: () => {
             void heightVersion;
-            return model;
+            return table.model;
         },
         getPort: deps.getPort,
         getLocalScrollTop: localScrollTop,
         getViewportHeight: scopeViewportHeight,
-        getPinnedIndex: pinnedIndex,
+        getPinnedIndex: focusedIndex,
+        holdsRange: deps.scroll.roundOpen,
         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
+    // While collapsed `win.result` goes unread, so the window math and its hysteresis never see
     // 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?.();
-        const report = deps.reportSelfHeight;
-        if (!el || !report)
-            return;
-        // After the flush, like the batch: at this effect's first run the children are unrendered.
-        let live = true;
-        void tick().then(() => {
-            if (!live)
-                return;
-            const h = el.getBoundingClientRect().height;
-            if (h > 0 && Math.abs(h - reportedSelfHeight) >= 1) {
-                reportedSelfHeight = h;
-                report(h);
-            }
-        });
-        return () => {
-            live = false;
-        };
-    });
-    // The UNCORRECTED batch: the caller owns the anchor correction, because nesting a second
-    // one inside an outer `mutate` double-counts the delta.
+    // A mount batch is a round even when nothing it measures moves, so a held placement is put back
+    // after whatever scrolled the blocks into mounting.
     function drainMeasurements() {
         if (pending.size === 0)
             return;
+        deps.scroll.beginRound();
         const entries = [];
         for (const id of pending) {
             const child = registry.get(id);
@@ -304,122 +152,125 @@ export function createListWindowing(deps) {
         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.
+    // A width rebuild re-estimates every entry at the new width, but mounted blocks have real
+    // heights and their measure effects depend on `node.raw`, not width.
     function remeasureMounted() {
         for (const id of registry.keys())
             pending.add(id);
         drainMeasurements();
     }
-    function flushMeasurements() {
-        if (pending.size === 0)
+    // The one write of a child's height into this table. An index that now holds another block
+    // keeps its height; the next build reads this id's measurement.
+    function applyMeasured(index, id, height) {
+        deps.oracle.recordMeasured(id, height);
+        // A height the table already holds moves nothing, so a keystroke that doesn't re-wrap opens
+        // no round.
+        if (table.ids[index] !== id || table.model.heightOf(index) === height)
             return;
-        // The batch writes above-viewport slots too, so the anchor correction keeps the
-        // top-of-viewport block fixed.
-        correctAnchor(drainMeasurements);
+        deps.scroll.beginRound();
+        table.model.setHeight(index, height);
+        heightVersion++;
     }
-    // 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.
+    // Read before the write so no DOM read follows it; a repeated call writes nothing once the
+    // height is stable, so it cannot 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));
+            child.applyHeight(h);
+    }
+    // A nested list's path reads its container's window, which a round opening inside the root
+    // table's build can't read again, so the tree reads the path as of the last flush.
+    let knownPath = untrack(deps.getParentPath);
+    $effect.pre(() => {
+        knownPath = deps.getParentPath();
+    });
+    const level = {
+        path: () => knownPath,
+        built: () => latestTable ?? table,
+        current: () => table,
+        contentTop: () => {
+            const port = deps.getPort();
+            const listEl = deps.getListEl();
+            return port && listEl ? listTopInPort(port, listEl) : null;
+        },
+        top: () => {
+            const port = deps.getPort();
+            const listEl = deps.getListEl();
+            if (!port || !listEl)
+                return null;
+            if (knownPath.length === 0)
+                return listTopInPort(port, listEl);
+            const box = listEl.closest(MEASURED_BOX);
+            return box ? listEl.getBoundingClientRect().top - box.getBoundingClientRect().top : null;
+        },
+        isInWindow
+    };
+    function isInWindow(index) {
+        // The effective window: with windowing off, `win.result` covers every index, so a scroll
+        // into a collapsed body would wait on a mount that never comes (VR-5).
+        const { start, end } = effectiveWindow;
+        return index >= start && index < end;
     }
     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();
-        },
+        level,
         // Read after the flush that mounted the child, not inside it: content can land later in
-        // that flush (an inline widget's root flushes after this one), and an empty-host read is
-        // a scroll correction the observer undoes a frame later. Still ahead of paint.
+        // that flush (an inline widget's root), and measuring an empty block costs a correction.
         registerChild(id, child) {
             const entry = {
                 readHeight: child.readHeight,
                 applyHeight: (h) => {
                     entry.applied = h;
-                    child.applyHeight(h);
+                    applyMeasured(child.index, id, h);
                 },
-                applied: undefined
+                applied: undefined,
+                index: child.index
             };
             registry.set(id, entry);
             pending.add(id);
-            void tick().then(flushMeasurements);
+            deps.scroll.measureSoon(drainMeasurements);
             return () => {
                 registry.delete(id);
                 pending.delete(id);
             };
         },
-        // Ungated: raw changed, so the height almost certainly did too.
+        // No check first: the raw changed, so the height almost certainly did too.
         measureChildNow(id) {
             measureOne(id);
         },
-        // ResizeObserver path for async growth. The gate reads what this scope last applied
-        // (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).
+        // For growth that arrives later. The check reads the last applied height, not the DOM, so
+        // the no-op resize of each freshly mounted block skips a rect read (VR-4).
         measureChildOnResize(id, observedHeight) {
             if (shouldRemeasureOnResize(registry.get(id)?.applied, observedHeight))
                 measureOne(id);
         },
-        revealHoldsScroll() {
-            const targetScrollTop = revealTargetScrollTop();
+        targetTopOf(index) {
             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);
+            const listEl = deps.getListEl();
+            if (index >= table.model.size || !port || !listEl)
+                return null;
+            return {
+                top: listTopInPort(port, listEl) + table.model.offsetOf(index),
+                height: table.model.heightOf(index)
+            };
+        },
+        syncScrollTop() {
+            win.syncScrollTop();
         },
         async revealChild(index) {
-            // A clamped-out body child can never mount, so degrade instead of scroll-and-wait.
+            // A body child of a collapsed list can never mount, so give up rather than 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));
+            deps.scroll.scrollToMount([...deps.getParentPath(), 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;
-        },
+        isInWindow,
         dispose() {
             win.dispose();
         }

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

@@ -1,15 +1,13 @@
 /**
- * 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 height, then write every height: a rect read right after a height write that
+ * dirties layout forces one synchronous reflow per block, so the pass splits into a read phase
+ * and a write phase and costs at most one reflow. Kept free of DOM and reactive state so the
+ * ordering can be unit-tested 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). */
+    /** Writes the measured height into the height table, which can dirty layout. */
     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. */
+/** A height of 0 or less (not laid out, or under jsdom) is never written. */
 export declare function runMeasureBatch(entries: Iterable<MeasureEntry>): void;

package/dist/reactivity/measure-batch.js

@@ -1,11 +1,10 @@
 /**
- * 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 height, then write every height: a rect read right after a height write that
+ * dirties layout forces one synchronous reflow per block, so the pass splits into a read phase
+ * and a write phase and costs at most one reflow. Kept free of DOM and reactive state so the
+ * ordering can be unit-tested 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. */
+/** A height of 0 or less (not laid out, or under jsdom) is never written. */
 export function runMeasureBatch(entries) {
     const measured = [];
     for (const entry of entries) {