@driftengine/ui2d 3.63.0 → 4.0.0

package/dist/uiDirty.js

@@ -0,0 +1,116 @@
+const STRIDE = 6;
+export function createDirtyTracker(capacity) {
+    return {
+        nodes: Array.from({ length: capacity }, () => null),
+        state: new Float64Array(capacity * STRIDE),
+        count: 0,
+        x: 0,
+        y: 0,
+        w: 0,
+        h: 0,
+        any: false,
+    };
+}
+export function clearDirty(tracker) {
+    tracker.any = false;
+    tracker.x = 0;
+    tracker.y = 0;
+    tracker.w = 0;
+    tracker.h = 0;
+}
+/** Union `rect` into what must be redrawn. A zero-area rectangle still counts as a change. */
+export function markDirty(tracker, rect) {
+    if (!tracker.any) {
+        tracker.x = rect.x;
+        tracker.y = rect.y;
+        tracker.w = rect.w;
+        tracker.h = rect.h;
+        tracker.any = true;
+        return;
+    }
+    const left = Math.min(tracker.x, rect.x);
+    const top = Math.min(tracker.y, rect.y);
+    const right = Math.max(tracker.x + tracker.w, rect.x + rect.w);
+    const bottom = Math.max(tracker.y + tracker.h, rect.y + rect.h);
+    tracker.x = left;
+    tracker.y = top;
+    tracker.w = right - left;
+    tracker.h = bottom - top;
+}
+/** The union of everything marked. Returns false when nothing was. */
+export function dirtyBounds(tracker, out) {
+    out.x = tracker.x;
+    out.y = tracker.y;
+    out.w = tracker.w;
+    out.h = tracker.h;
+    return tracker.any;
+}
+/** Visual state that changes pixels, packed so one comparison covers all of it. */
+function visualOf(node) {
+    return ((node.hidden ? 1 : 0) |
+        (node.hovered ? 2 : 0) |
+        (node.pressed ? 4 : 0) |
+        ((node.texture + 1) * 8));
+}
+const SCRATCH = { x: 0, y: 0, w: 0, h: 0 };
+function visit(tracker, node, at) {
+    const base = at * STRIDE;
+    const previous = tracker.nodes[at] ?? null;
+    const visual = visualOf(node);
+    const textHash = node.text.length;
+    const moved = previous !== node ||
+        tracker.state[base] !== node.rect.x ||
+        tracker.state[base + 1] !== node.rect.y ||
+        tracker.state[base + 2] !== node.rect.w ||
+        tracker.state[base + 3] !== node.rect.h ||
+        tracker.state[base + 4] !== visual ||
+        tracker.state[base + 5] !== textHash;
+    if (moved) {
+        /* Where it was, so a node that moved or vanished does not leave its pixels behind. */
+        if (previous !== null) {
+            SCRATCH.x = tracker.state[base] ?? 0;
+            SCRATCH.y = tracker.state[base + 1] ?? 0;
+            SCRATCH.w = tracker.state[base + 2] ?? 0;
+            SCRATCH.h = tracker.state[base + 3] ?? 0;
+            markDirty(tracker, SCRATCH);
+        }
+        if (!node.hidden)
+            markDirty(tracker, node.rect);
+    }
+    tracker.nodes[at] = node;
+    tracker.state[base] = node.rect.x;
+    tracker.state[base + 1] = node.rect.y;
+    tracker.state[base + 2] = node.rect.w;
+    tracker.state[base + 3] = node.rect.h;
+    tracker.state[base + 4] = visual;
+    tracker.state[base + 5] = textHash;
+    let next = at + 1;
+    for (const child of node.children)
+        next = visit(tracker, child, next);
+    return next;
+}
+/**
+ * Compare the tree against last frame and mark what changed.
+ *
+ * Walks hidden nodes too, because a node that just became hidden is exactly the one whose previous
+ * rectangle has to be marked.
+ */
+export function diffTree(tracker, root) {
+    clearDirty(tracker);
+    const count = visit(tracker, root, 0);
+    /* A node that existed last frame and is gone now: its rectangle must be repainted. */
+    for (let at = count; at < tracker.count; at += 1) {
+        const previous = tracker.nodes[at];
+        if (previous === null || previous === undefined)
+            continue;
+        const base = at * STRIDE;
+        SCRATCH.x = tracker.state[base] ?? 0;
+        SCRATCH.y = tracker.state[base + 1] ?? 0;
+        SCRATCH.w = tracker.state[base + 2] ?? 0;
+        SCRATCH.h = tracker.state[base + 3] ?? 0;
+        markDirty(tracker, SCRATCH);
+        tracker.nodes[at] = null;
+    }
+    tracker.count = count;
+    return tracker.any;
+}

package/dist/uiLayer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Draw order when tree order is not enough.
+ *
+ * A dropdown is owned by the control that opens it and must cover the panel that control sits in;
+ * a drag preview is owned by the thing being dragged and must cover everything. Tree order cannot
+ * express either, because ownership and covering point in opposite directions.
+ *
+ * **A layer is inherited.** A popup's own children have to ride with it, or a menu draws above the
+ * panel and its labels draw below it — which is the first bug any other arrangement produces.
+ *
+ * **A stable sort, and the stability is a requirement rather than a nicety.** Two nodes on one
+ * layer that swap between frames produce a flicker nobody can reproduce on demand. Sorting the
+ * traversal indices rather than the nodes makes the tiebreaker the traversal order by
+ * construction, so it cannot be lost to whatever the sort implementation guarantees.
+ */
+import type { UiNode } from './uiNode.ts';
+/** Fill `out` with the tree in draw order and return how many entries were written. */
+export declare function layerOrder(root: UiNode, out: UiNode[]): number;

package/dist/uiLayer.js

@@ -0,0 +1,30 @@
+/* Reused across calls: this runs per frame and these are its only allocations. */
+const FLAT = [];
+const LAYERS = [];
+const ORDER = [];
+function gather(node, inherited, at) {
+    if (node.hidden)
+        return at;
+    const layer = node.layer === 0 ? inherited : node.layer;
+    FLAT[at] = node;
+    LAYERS[at] = layer;
+    let next = at + 1;
+    for (const child of node.children)
+        next = gather(child, layer, next);
+    return next;
+}
+/** Fill `out` with the tree in draw order and return how many entries were written. */
+export function layerOrder(root, out) {
+    const count = gather(root, 0, 0);
+    ORDER.length = 0;
+    for (let i = 0; i < count; i += 1)
+        ORDER.push(i);
+    ORDER.sort((a, b) => {
+        const byLayer = (LAYERS[a] ?? 0) - (LAYERS[b] ?? 0);
+        return byLayer !== 0 ? byLayer : a - b;
+    });
+    for (let i = 0; i < count; i += 1)
+        out[i] = FLAT[ORDER[i] ?? 0];
+    out.length = count;
+    return count;
+}

package/dist/uiLayout.js

@@ -66,8 +66,14 @@ function place(node, x, y, w, h) {
     node.rect.w = w;
     node.rect.h = h;
     const row = node.direction === 'row';
-    const contentX = x + node.paddingLeft;
-    const contentY = y + node.paddingTop;
+    /*
+     * Scrolling is subtracted here, at placement, rather than applied as a transform at draw.
+     * Applied at draw, hit testing would need the inverse and every consumer would eventually get
+     * it wrong in one direction; applied here, a scrolled child's rectangle simply *is* where it is,
+     * and hit testing, focus and clipping all keep working without knowing scrolling exists.
+     */
+    const contentX = x + node.paddingLeft - node.scrollX;
+    const contentY = y + node.paddingTop - node.scrollY;
     const contentW = Math.max(0, w - node.paddingLeft - node.paddingRight);
     const contentH = Math.max(0, h - node.paddingTop - node.paddingBottom);
     const contentAlong = row ? contentW : contentH;
@@ -129,6 +135,7 @@ function place(node, x, y, w, h) {
         }
         cursor += sizeAlong + node.gap + between;
     }
+    measureSpan(node, contentX, contentY);
 }
 /**
  * A child taken out of the flow: at its own offset inside the parent's content box.
@@ -137,6 +144,26 @@ function place(node, x, y, w, h) {
  * where the panel's contents start — which is where a caller reading the padding expects it, and
  * the only reading under which `x: 0` means the same thing for an absolute child as for a flow one.
  */
+/**
+ * How far the placed children reach past the content origin.
+ *
+ * Measured after placement and relative to `contentX`/`contentY`, which the scroll has already
+ * moved — so the offset cancels and the answer is the same whatever the node is scrolled to.
+ * `uiScroll.ts` clamps against this and would be wrong clamping against anything derived from the
+ * live scroll value.
+ */
+function measureSpan(node, contentX, contentY) {
+    let spanX = 0;
+    let spanY = 0;
+    for (const child of node.children) {
+        if (child.hidden)
+            continue;
+        spanX = Math.max(spanX, child.rect.x + child.rect.w - contentX);
+        spanY = Math.max(spanY, child.rect.y + child.rect.h - contentY);
+    }
+    node.contentSpanX = spanX;
+    node.contentSpanY = spanY;
+}
 function placeAbsolute(child, contentX, contentY, contentW, contentH) {
     const w = child.width === 'grow' ? contentW : child.measuredWidth;
     const h = child.height === 'grow' ? contentH : child.measuredHeight;

package/dist/uiNode.d.ts

@@ -39,6 +39,18 @@ export interface UiNodeOptions {
     readonly contentWidth?: number;
     readonly contentHeight?: number;
     readonly hidden?: boolean;
+    /**
+     * Whether this node cuts its descendants to its own rectangle.
+     *
+     * Off by default, because most nodes do not clip and one that does costs a scissor change in
+     * the pass. A scroll container sets it and a panel sets it; a row of buttons does not.
+     */
+    readonly clip?: boolean;
+    /** How far this node's contents are moved under it. Only meaningful with `clip`. */
+    readonly scrollX?: number;
+    readonly scrollY?: number;
+    /** Draw order beyond tree order. Inherited by descendants that do not set their own. */
+    readonly layer?: number;
     readonly background?: ArrayLike<number> | null;
     /** The sprite slot this node draws from, or `-1` for none. */
     readonly texture?: number;
@@ -78,6 +90,23 @@ export interface UiNode {
     contentWidth: number;
     contentHeight: number;
     hidden: boolean;
+    /** Whether this node cuts its descendants to its own rectangle. See `uiClip.ts`. */
+    clip: boolean;
+    /** How far this node's contents are moved under it. See `uiScroll.ts`. */
+    scrollX: number;
+    scrollY: number;
+    /**
+     * How far the placed children reach past this node's content origin, along each axis.
+     *
+     * Written by `layoutUiTree` and **independent of the current scroll**, because it is measured
+     * relative to the content origin that the scroll already moved — the offset cancels. That
+     * independence is the point: an extent derived from placed positions plus the live scroll value
+     * is wrong the moment the two disagree, which is exactly when a caller is scrolling.
+     */
+    contentSpanX: number;
+    contentSpanY: number;
+    /** Draw order beyond tree order. See `uiLayer.ts`. */
+    layer: number;
     /** Where this node ended up. Meaningless until `layoutUiTree` has run over its root. */
     readonly rect: UiRect;
     /** What it measured to along each axis, before the parent distributed anything. */

package/dist/uiNode.js

@@ -30,6 +30,12 @@ export function createUiNode(options = {}) {
         contentWidth: options.contentWidth ?? 0,
         contentHeight: options.contentHeight ?? 0,
         hidden: options.hidden ?? false,
+        clip: options.clip ?? false,
+        scrollX: options.scrollX ?? 0,
+        scrollY: options.scrollY ?? 0,
+        contentSpanX: 0,
+        contentSpanY: 0,
+        layer: options.layer ?? 0,
         rect: { x: 0, y: 0, w: 0, h: 0 },
         measuredWidth: 0,
         measuredHeight: 0,

package/dist/uiPointer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Who the pointer belongs to, and what a drag is carrying.
+ *
+ * **Capture is the half without which every slider in the interface is wrong in the same way.** A
+ * control being dragged has to keep receiving motion after the pointer leaves its rectangle — that
+ * is what dragging *is* — and a framework that routes purely by hit test cannot express it.
+ *
+ * **A drag records its target as the pointer moves**, rather than hit-testing once at release,
+ * because the release position is the only thing a drop handler could otherwise use and a pointer
+ * that leaves the window never produces one.
+ */
+import type { UiNode } from './uiNode.ts';
+export interface PointerState {
+    /** The node holding the pointer, or null. */
+    captured: UiNode | null;
+    /** Where a drag began, or null when none is in progress. */
+    dragSource: UiNode | null;
+    /** The last node the drag was over, excluding the source itself. */
+    dragTarget: UiNode | null;
+    /** What the drag is carrying. Opaque to this module. */
+    dragPayload: string;
+}
+export declare function createPointerState(): PointerState;
+export declare function capturePointer(state: PointerState, node: UiNode): void;
+export declare function releasePointer(state: PointerState): void;
+/**
+ * Who should receive pointer input at this position.
+ *
+ * A captured node receives it wherever the pointer is, including outside the window. Otherwise it
+ * is an ordinary hit test — and while a drag is in progress, the result is remembered as the
+ * prospective drop target.
+ */
+export declare function pointerTarget(state: PointerState, root: UiNode, x: number, y: number): UiNode | null;
+export declare function beginDrag(state: PointerState, source: UiNode, payload: string): void;
+/** The node a drop would land on, or null. */
+export declare function dropTarget(state: PointerState): UiNode | null;
+/**
+ * Finish a drag and report where it landed. Null when no drag was in progress.
+ *
+ * A null `target` is an ordinary outcome — a drop on nothing — and is reported rather than
+ * suppressed, because a caller often wants to know a drag ended even where it achieved nothing.
+ */
+export declare function endDrag(state: PointerState): {
+    source: UiNode;
+    target: UiNode | null;
+    payload: string;
+} | null;

package/dist/uiPointer.js

@@ -0,0 +1,50 @@
+import { uiHitTest } from './uiFocus.js';
+export function createPointerState() {
+    return { captured: null, dragSource: null, dragTarget: null, dragPayload: '' };
+}
+export function capturePointer(state, node) {
+    state.captured = node;
+}
+export function releasePointer(state) {
+    state.captured = null;
+}
+/**
+ * Who should receive pointer input at this position.
+ *
+ * A captured node receives it wherever the pointer is, including outside the window. Otherwise it
+ * is an ordinary hit test — and while a drag is in progress, the result is remembered as the
+ * prospective drop target.
+ */
+export function pointerTarget(state, root, x, y) {
+    if (state.captured !== null)
+        return state.captured;
+    const hit = uiHitTest(root, x, y);
+    if (state.dragSource !== null)
+        state.dragTarget = hit === state.dragSource ? null : hit;
+    return hit;
+}
+export function beginDrag(state, source, payload) {
+    state.dragSource = source;
+    state.dragTarget = null;
+    state.dragPayload = payload;
+}
+/** The node a drop would land on, or null. */
+export function dropTarget(state) {
+    return state.dragTarget;
+}
+/**
+ * Finish a drag and report where it landed. Null when no drag was in progress.
+ *
+ * A null `target` is an ordinary outcome — a drop on nothing — and is reported rather than
+ * suppressed, because a caller often wants to know a drag ended even where it achieved nothing.
+ */
+export function endDrag(state) {
+    const source = state.dragSource;
+    if (source === null)
+        return null;
+    const result = { source, target: state.dragTarget, payload: state.dragPayload };
+    state.dragSource = null;
+    state.dragTarget = null;
+    state.dragPayload = '';
+    return result;
+}

package/dist/uiScroll.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Moving a clipping node's contents underneath it.
+ *
+ * **Scrolling is an offset applied at placement, not a transform applied at draw.** `uiLayout.ts`
+ * subtracts it from the content origin, so a scrolled child's rectangle simply is where it is —
+ * and hit testing, focus and clipping keep working without any of them knowing that scrolling
+ * exists. Applied at draw, each of those would need the inverse and one of them would eventually
+ * get it wrong in one direction only.
+ *
+ * **A scroll that moves nothing says so.** Nested containers are the case: a wheel over an inner
+ * list that has reached its end should scroll the outer one rather than stopping dead, and a
+ * caller that cannot tell "consumed" from "already at the end" cannot implement that. The boolean
+ * is the whole mechanism.
+ */
+import type { UiNode } from './uiNode.ts';
+/**
+ * How far this node's contents extend past its own box, along each axis.
+ *
+ * Read from the span `layoutUiTree` measured, which is relative to the content origin and so does
+ * not change as the node scrolls. **Deriving it from placed rectangles plus the live scroll value
+ * is wrong**, and wrong in the one situation it is asked about: after a caller has moved the
+ * scroll, the rectangles still reflect the previous value and the two no longer agree.
+ */
+export declare function scrollExtent(node: UiNode): {
+    x: number;
+    y: number;
+};
+export declare function clampScroll(node: UiNode): void;
+/** Scroll, clamped. Returns whether anything actually moved — see the header for why. */
+export declare function scrollBy(node: UiNode, dx: number, dy: number): boolean;
+/**
+ * Give a wheel to the innermost container under the pointer that can use it, then outwards.
+ *
+ * Innermost first is the order a person expects and the opposite of the order the tree makes
+ * convenient, so the chain is collected on the way down and walked back up. Returns the node that
+ * consumed it, or null when nothing did — which is a caller's signal to let the page have it.
+ */
+export declare function routeScrollWheel(root: UiNode, x: number, y: number, dx: number, dy: number): UiNode | null;

package/dist/uiScroll.js

@@ -0,0 +1,65 @@
+import { uiRectHolds } from './uiNode.js';
+/**
+ * How far this node's contents extend past its own box, along each axis.
+ *
+ * Read from the span `layoutUiTree` measured, which is relative to the content origin and so does
+ * not change as the node scrolls. **Deriving it from placed rectangles plus the live scroll value
+ * is wrong**, and wrong in the one situation it is asked about: after a caller has moved the
+ * scroll, the rectangles still reflect the previous value and the two no longer agree.
+ */
+export function scrollExtent(node) {
+    const contentW = Math.max(0, node.rect.w - node.paddingLeft - node.paddingRight);
+    const contentH = Math.max(0, node.rect.h - node.paddingTop - node.paddingBottom);
+    return {
+        x: Math.max(0, node.contentSpanX - contentW),
+        y: Math.max(0, node.contentSpanY - contentH),
+    };
+}
+export function clampScroll(node) {
+    const extent = scrollExtent(node);
+    node.scrollX = Math.min(Math.max(0, node.scrollX), extent.x);
+    node.scrollY = Math.min(Math.max(0, node.scrollY), extent.y);
+}
+/** Scroll, clamped. Returns whether anything actually moved — see the header for why. */
+export function scrollBy(node, dx, dy) {
+    const beforeX = node.scrollX;
+    const beforeY = node.scrollY;
+    node.scrollX += dx;
+    node.scrollY += dy;
+    clampScroll(node);
+    return node.scrollX !== beforeX || node.scrollY !== beforeY;
+}
+/* Reused across calls: this runs per wheel event and the chain is its only allocation. */
+const CHAIN = [];
+/**
+ * Give a wheel to the innermost container under the pointer that can use it, then outwards.
+ *
+ * Innermost first is the order a person expects and the opposite of the order the tree makes
+ * convenient, so the chain is collected on the way down and walked back up. Returns the node that
+ * consumed it, or null when nothing did — which is a caller's signal to let the page have it.
+ */
+export function routeScrollWheel(root, x, y, dx, dy) {
+    let depth = 0;
+    let walk = root;
+    while (walk !== null) {
+        CHAIN[depth] = walk;
+        depth += 1;
+        let next = null;
+        for (let i = walk.children.length - 1; i >= 0; i -= 1) {
+            const child = walk.children[i];
+            if (!child.hidden && uiRectHolds(child, x, y)) {
+                next = child;
+                break;
+            }
+        }
+        walk = next;
+    }
+    for (let i = depth - 1; i >= 0; i -= 1) {
+        const node = CHAIN[i];
+        if (!node.clip)
+            continue;
+        if (scrollBy(node, dx, dy))
+            return node;
+    }
+    return null;
+}

package/dist/uiSlice.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A panel background that stretches without stretching its corners.
+ *
+ * Nine cells: the four corners keep their source size, the four edges stretch along one axis, and
+ * the middle stretches along both. Written into a caller's array as
+ * `x, y, w, h, u0, v0, u1, v1` per cell, in row-major order — top-left, top, top-right, left,
+ * middle, right, bottom-left, bottom, bottom-right — so the middle is always index 4.
+ *
+ * **A box narrower than its own insets scales them down rather than letting them overlap.**
+ * Overlapping corners draw the same alpha twice, which on a translucent panel is a visible seam
+ * exactly where the design was trying to be careful.
+ *
+ * **The source size is a parameter because `SpriteFrame` carries only texture coordinates.** The
+ * insets are in texels, so splitting the frame needs to know what the frame's texels span.
+ */
+import type { SpriteFrame } from './spriteSheet.ts';
+/** Floats per placement: x, y, w, h, u0, v0, u1, v1. */
+export declare const SLICE_STRIDE = 8;
+export interface SliceInset {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+export declare function sliceInto(out: Float32Array, frame: SpriteFrame, sourceWidth: number, sourceHeight: number, inset: SliceInset, x: number, y: number, w: number, h: number): number;

package/dist/uiSlice.js

@@ -0,0 +1,51 @@
+/** Floats per placement: x, y, w, h, u0, v0, u1, v1. */
+export const SLICE_STRIDE = 8;
+export function sliceInto(out, frame, sourceWidth, sourceHeight, inset, x, y, w, h) {
+    /*
+     * Scaled down together when the box cannot hold both, so the two corners meet exactly at the
+     * midpoint instead of overlapping. The texture coordinates are deliberately *not* scaled with
+     * them: the corner draws a smaller piece of the box out of the same piece of the source, which
+     * is squashing rather than seaming and is the better of the two wrong pictures available.
+     */
+    const sideX = inset.left + inset.right;
+    const kx = sideX > w && sideX > 0 ? w / sideX : 1;
+    const left = inset.left * kx;
+    const right = inset.right * kx;
+    const sideY = inset.top + inset.bottom;
+    const ky = sideY > h && sideY > 0 ? h / sideY : 1;
+    const top = inset.top * ky;
+    const bottom = inset.bottom * ky;
+    const colX = [x, x + left, x + w - right];
+    const colW = [left, Math.max(0, w - left - right), right];
+    const rowY = [y, y + top, y + h - bottom];
+    const rowH = [top, Math.max(0, h - top - bottom), bottom];
+    const du = frame.u1 - frame.u0;
+    const dv = frame.v1 - frame.v0;
+    const uAt = [
+        frame.u0,
+        frame.u0 + (inset.left / sourceWidth) * du,
+        frame.u1 - (inset.right / sourceWidth) * du,
+        frame.u1,
+    ];
+    const vAt = [
+        frame.v0,
+        frame.v0 + (inset.top / sourceHeight) * dv,
+        frame.v1 - (inset.bottom / sourceHeight) * dv,
+        frame.v1,
+    ];
+    let at = 0;
+    for (let r = 0; r < 3; r += 1) {
+        for (let c = 0; c < 3; c += 1) {
+            out[at] = colX[c];
+            out[at + 1] = rowY[r];
+            out[at + 2] = colW[c];
+            out[at + 3] = rowH[r];
+            out[at + 4] = uAt[c];
+            out[at + 5] = vAt[r];
+            out[at + 6] = uAt[c + 1];
+            out[at + 7] = vAt[r + 1];
+            at += SLICE_STRIDE;
+        }
+    }
+    return 9;
+}

package/dist/virtualList.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which rows a scroll offset makes visible, so that a list costs a screenful rather than a list.
+ *
+ * An asset browser with ten thousand entries has to cost what a screenful costs. Without this the
+ * scene tree is unusable the first time somebody opens a real project, which is the moment nobody
+ * wants to discover it.
+ *
+ * **Overscan is applied before clamping, not after.** Applied after, a window near either end
+ * runs past the row count and a caller indexes rows that do not exist.
+ */
+export interface RowWindow {
+    first: number;
+    count: number;
+}
+/** Uniform row heights, which is arithmetic. */
+export declare function visibleRange(scrollY: number, viewHeight: number, rowHeight: number, rowCount: number, overscan: number): RowWindow;
+/**
+ * Variable row heights, through a prefix-sum table of row tops the caller owns.
+ *
+ * **The caller owns the table** because only the caller knows when a row's height changed, and
+ * recomputing it here every frame would be the cost this module exists to avoid. `offsets` holds
+ * `rowCount + 1` entries: the top of each row, then the bottom of the last.
+ */
+export declare function visibleRangeVariable(scrollY: number, viewHeight: number, offsets: Float64Array, rowCount: number, overscan: number): RowWindow;

package/dist/virtualList.js

@@ -0,0 +1,49 @@
+function clampWindow(first, lastExclusive, rowCount) {
+    const lo = Math.max(0, Math.min(rowCount, first));
+    const hi = Math.max(lo, Math.min(rowCount, lastExclusive));
+    return { first: lo, count: hi - lo };
+}
+/** Uniform row heights, which is arithmetic. */
+export function visibleRange(scrollY, viewHeight, rowHeight, rowCount, overscan) {
+    if (rowHeight <= 0 || rowCount <= 0)
+        return { first: 0, count: 0 };
+    const top = Math.max(0, scrollY);
+    const first = Math.floor(top / rowHeight) - overscan;
+    const lastExclusive = Math.ceil((top + viewHeight) / rowHeight) + overscan;
+    return clampWindow(first, lastExclusive, rowCount);
+}
+/**
+ * Variable row heights, through a prefix-sum table of row tops the caller owns.
+ *
+ * **The caller owns the table** because only the caller knows when a row's height changed, and
+ * recomputing it here every frame would be the cost this module exists to avoid. `offsets` holds
+ * `rowCount + 1` entries: the top of each row, then the bottom of the last.
+ */
+export function visibleRangeVariable(scrollY, viewHeight, offsets, rowCount, overscan) {
+    if (rowCount <= 0)
+        return { first: 0, count: 0 };
+    const top = Math.max(0, scrollY);
+    const bottom = top + viewHeight;
+    /* Largest index whose top is at or before the window's top. */
+    let lo = 0;
+    let hi = rowCount;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if ((offsets[mid] ?? 0) <= top)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const first = lo - overscan;
+    /* Smallest index whose top is at or after the window's bottom. */
+    let a = 0;
+    let b = rowCount;
+    while (a < b) {
+        const mid = (a + b) >> 1;
+        if ((offsets[mid] ?? 0) >= bottom)
+            b = mid;
+        else
+            a = mid + 1;
+    }
+    return clampWindow(first, a + overscan, rowCount);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "3.63.0",
+  "version": "4.0.0",
   "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "3.63.0"
+    "@driftengine/core": "4.0.0"
   },
   "author": "Drift Technologies",
   "repository": {