@driftengine/ui2d 3.61.0

package/dist/tilemap.js

@@ -0,0 +1,70 @@
+/** A grid of sheet frames, drawn as sprites, culled to what the view can see. */
+import { drawSprite } from './spriteBatch.js';
+import { createSpriteFrame, sheetFrame } from './spriteSheet.js';
+/** A cell holding nothing. Negative, so it can never be a frame index. */
+export const TILE_EMPTY = -1;
+export function createTilemap(columns, rows, tileWidth, tileHeight) {
+    const tiles = new Int32Array(columns * rows);
+    tiles.fill(TILE_EMPTY);
+    return { columns, rows, tiles, tileWidth, tileHeight, x: 0, y: 0 };
+}
+/** The frame in a cell, or `TILE_EMPTY` — including for a cell outside the map. */
+export function tileAt(map, column, row) {
+    if (column < 0 || column >= map.columns || row < 0 || row >= map.rows)
+        return TILE_EMPTY;
+    return map.tiles[row * map.columns + column];
+}
+/** Put a frame in a cell. A cell outside the map is ignored rather than wrapping into another row. */
+export function setTile(map, column, row, tile) {
+    if (column < 0 || column >= map.columns || row < 0 || row >= map.rows)
+        return;
+    map.tiles[row * map.columns + column] = tile;
+}
+/*
+ * One frame rectangle, refilled per tile. Module scope because `drawTilemap` is a per-frame hot
+ * path and this is the only object in it.
+ */
+const FRAME = createSpriteFrame();
+/**
+ * Draw the tiles the view can see. Returns how many that was.
+ *
+ * **The cost is the view rather than the map**, which is the whole reason this is a function and
+ * not a loop the caller writes: the visible span is arithmetic on four numbers, so a map of a
+ * million cells costs the few hundred on screen. A walk over every cell testing each against the
+ * view would draw exactly the same picture and be unusable at the size a tilemap exists for.
+ *
+ * **Which way the rows run is the affine's business, not this function's.** A cell's corner is
+ * `y + row * tileHeight`, so in screen space — where y counts down — row 0 is the top row, and in a
+ * 2D world — where y counts up — it is the bottom. That is the same rule `SpritePlacement` states
+ * about its own corner, and having one rule rather than a flag is what keeps the two agreeing.
+ */
+export function drawTilemap(batch, map, sheet, view, tint) {
+    const firstColumn = Math.max(0, Math.floor((view.x - map.x) / map.tileWidth));
+    const firstRow = Math.max(0, Math.floor((view.y - map.y) / map.tileHeight));
+    /* Exclusive, and `ceil` rather than `floor + 1` so a view ending exactly on a boundary stops. */
+    const lastColumn = Math.min(map.columns, Math.ceil((view.x + view.w - map.x) / map.tileWidth));
+    const lastRow = Math.min(map.rows, Math.ceil((view.y + view.h - map.y) / map.tileHeight));
+    PLACEMENT.w = map.tileWidth;
+    PLACEMENT.h = map.tileHeight;
+    let drawn = 0;
+    for (let row = firstRow; row < lastRow; row += 1) {
+        const rowBase = row * map.columns;
+        const y = map.y + row * map.tileHeight;
+        for (let column = firstColumn; column < lastColumn; column += 1) {
+            const tile = map.tiles[rowBase + column];
+            if (tile === TILE_EMPTY)
+                continue;
+            sheetFrame(sheet, tile, FRAME);
+            PLACEMENT.x = map.x + column * map.tileWidth;
+            PLACEMENT.y = y;
+            drawSprite(batch, sheet.texture, PLACEMENT, FRAME, tint);
+            drawn += 1;
+        }
+    }
+    return drawn;
+}
+/*
+ * The placement handed to `drawSprite`, refilled per tile. Its size never changes within a call, so
+ * `drawTilemap` sets it once; the two coordinates move per cell.
+ */
+const PLACEMENT = { x: 0, y: 0, w: 0, h: 0 };

package/dist/uiDraw.d.ts

@@ -0,0 +1,28 @@
+/** Turn a laid-out interface tree into quads, parents first so children land on top. */
+import type { SpriteBatch } from './spriteBatch.ts';
+import type { UiNode } from './uiNode.ts';
+/**
+ * Where a caller draws what a quad cannot be.
+ *
+ * Text is the whole of it today. This package draws textured quads and core already draws two kinds
+ * of text — `drawText` from the pixel font and `drawSdfText` from an atlas — so the honest seam is
+ * that the tree says *where* a label goes and the caller says *how* it is drawn. Wrapping either
+ * here would mean this package importing the renderer's verb surface to re-export it.
+ *
+ * Called with the node's resolved rect already filled in, in the order the node is drawn, so a
+ * label lands over its own background and under whatever is drawn after it.
+ */
+export interface UiContentSink {
+    content(node: UiNode): void;
+}
+/**
+ * Draw a tree. Returns how many quads it came to.
+ *
+ * **Parents before children, siblings in order**, which is the same rule the batch already has:
+ * there is no depth here, so what is drawn later is what is on top. A node draws its background
+ * first and its image second, so an icon lands on its own plate.
+ *
+ * Allocates nothing. `layoutUiTree` must have run over this root, or every rect is whatever it was
+ * left at.
+ */
+export declare function drawUiTree(batch: SpriteBatch, root: UiNode, white: number, sink: UiContentSink | null): number;

package/dist/uiDraw.js

@@ -0,0 +1,41 @@
+/** Turn a laid-out interface tree into quads, parents first so children land on top. */
+import { drawSprite } from './spriteBatch.js';
+/* One placement, refilled per node. This is a per-frame path and it is the only object in it. */
+const PLACEMENT = {
+    x: 0,
+    y: 0,
+    w: 0,
+    h: 0,
+};
+/**
+ * Draw a tree. Returns how many quads it came to.
+ *
+ * **Parents before children, siblings in order**, which is the same rule the batch already has:
+ * there is no depth here, so what is drawn later is what is on top. A node draws its background
+ * first and its image second, so an icon lands on its own plate.
+ *
+ * Allocates nothing. `layoutUiTree` must have run over this root, or every rect is whatever it was
+ * left at.
+ */
+export function drawUiTree(batch, root, white, sink) {
+    if (root.hidden)
+        return 0;
+    let drawn = 0;
+    PLACEMENT.x = root.rect.x;
+    PLACEMENT.y = root.rect.y;
+    PLACEMENT.w = root.rect.w;
+    PLACEMENT.h = root.rect.h;
+    if (root.background !== null) {
+        drawSprite(batch, white, PLACEMENT, null, root.background);
+        drawn += 1;
+    }
+    if (root.texture >= 0) {
+        drawSprite(batch, root.texture, PLACEMENT, root.frame, root.tint);
+        drawn += 1;
+    }
+    if (sink !== null && root.text !== '')
+        sink.content(root);
+    for (const child of root.children)
+        drawn += drawUiTree(batch, child, white, sink);
+    return drawn;
+}

package/dist/uiFocus.d.ts

@@ -0,0 +1,36 @@
+/** Which node a point is on, and which node a keyboard should be talking to. */
+import type { UiNode } from './uiNode.ts';
+/**
+ * The interactive node under a point, or `null`.
+ *
+ * **Searched last-drawn first**, because the last thing drawn is the thing on top and a hit test
+ * that disagreed with the picture would be a button that responds where it is not.
+ *
+ * **A node that is not `interactive` does not block what is behind it.** A panel is a backdrop, and
+ * a backdrop that swallowed clicks would make every button under a plate dead — which is the
+ * failure a caller cannot see and would spend an afternoon on. A caller that wants a modal to
+ * swallow clicks marks the modal itself interactive, which says so.
+ *
+ * Allocates nothing.
+ */
+export declare function uiHitTest(root: UiNode, x: number, y: number): UiNode | null;
+/**
+ * Every focusable node, in tree order, appended to `out`.
+ *
+ * Tree order rather than a declared tab index: the order a tree is built in is the order it reads
+ * in, and a second ordering is a second thing to keep in step with the first. A caller that wants a
+ * different order moves the node.
+ *
+ * `out` is cleared first and reused, so a caller may hold one array. This is not a per-frame path —
+ * focus changes when a key is pressed.
+ */
+export declare function uiFocusOrder(root: UiNode, out: UiNode[]): UiNode[];
+/**
+ * The next focusable node after `current`, wrapping.
+ *
+ * `null` for `current` starts at the first, which is what a tree that has never been focused wants.
+ * `null` comes back only when nothing at all is focusable.
+ */
+export declare function uiFocusNext(root: UiNode, current: UiNode | null): UiNode | null;
+/** The focusable node before `current`, wrapping. */
+export declare function uiFocusPrevious(root: UiNode, current: UiNode | null): UiNode | null;

package/dist/uiFocus.js

@@ -0,0 +1,78 @@
+/** Which node a point is on, and which node a keyboard should be talking to. */
+import { uiRectHolds } from './uiNode.js';
+/**
+ * The interactive node under a point, or `null`.
+ *
+ * **Searched last-drawn first**, because the last thing drawn is the thing on top and a hit test
+ * that disagreed with the picture would be a button that responds where it is not.
+ *
+ * **A node that is not `interactive` does not block what is behind it.** A panel is a backdrop, and
+ * a backdrop that swallowed clicks would make every button under a plate dead — which is the
+ * failure a caller cannot see and would spend an afternoon on. A caller that wants a modal to
+ * swallow clicks marks the modal itself interactive, which says so.
+ *
+ * Allocates nothing.
+ */
+export function uiHitTest(root, x, y) {
+    if (root.hidden)
+        return null;
+    for (let i = root.children.length - 1; i >= 0; i -= 1) {
+        const hit = uiHitTest(root.children[i], x, y);
+        if (hit !== null)
+            return hit;
+    }
+    return root.interactive && uiRectHolds(root, x, y) ? root : null;
+}
+/**
+ * Every focusable node, in tree order, appended to `out`.
+ *
+ * Tree order rather than a declared tab index: the order a tree is built in is the order it reads
+ * in, and a second ordering is a second thing to keep in step with the first. A caller that wants a
+ * different order moves the node.
+ *
+ * `out` is cleared first and reused, so a caller may hold one array. This is not a per-frame path —
+ * focus changes when a key is pressed.
+ */
+export function uiFocusOrder(root, out) {
+    out.length = 0;
+    gather(root, out);
+    return out;
+}
+function gather(node, out) {
+    if (node.hidden)
+        return;
+    if (node.focusable)
+        out.push(node);
+    for (const child of node.children)
+        gather(child, out);
+}
+/* One array, reused by the two step functions below. Neither is reentrant and neither needs to be. */
+const ORDER = [];
+/**
+ * The next focusable node after `current`, wrapping.
+ *
+ * `null` for `current` starts at the first, which is what a tree that has never been focused wants.
+ * `null` comes back only when nothing at all is focusable.
+ */
+export function uiFocusNext(root, current) {
+    return step(root, current, 1);
+}
+/** The focusable node before `current`, wrapping. */
+export function uiFocusPrevious(root, current) {
+    return step(root, current, -1);
+}
+function step(root, current, by) {
+    uiFocusOrder(root, ORDER);
+    if (ORDER.length === 0)
+        return null;
+    const at = current === null ? -1 : ORDER.indexOf(current);
+    /*
+     * A `current` that is not in the list — hidden since it was focused, or removed from the tree —
+     * lands here as -1 and starts from the beginning going forward, or the end going back. Better
+     * than refusing: a node that disappeared under the focus should not take the keyboard with it.
+     */
+    if (at < 0)
+        return (by > 0 ? ORDER[0] : ORDER[ORDER.length - 1]);
+    const next = (at + by + ORDER.length) % ORDER.length;
+    return ORDER[next];
+}

package/dist/uiInput.d.ts

@@ -0,0 +1,51 @@
+/** Routing: a pointer and a keyboard turned into hover, press, focus and one activation. */
+import type { UiNode } from './uiNode.ts';
+/**
+ * What the router remembers between calls.
+ *
+ * Held by the caller rather than by the tree, because a tree can be shown in two places — a HUD and
+ * an editor preview of the same tree — and each has its own pointer. It is also what makes the
+ * router testable without a tree at all.
+ */
+export interface UiInput {
+    hovered: UiNode | null;
+    /** The node the pointer went down on, until it comes up again. */
+    pressed: UiNode | null;
+    focused: UiNode | null;
+    /** Whether the pointer was down at the previous call, so an edge can be found. */
+    wasDown: boolean;
+}
+export declare function createUiInput(): UiInput;
+/**
+ * Route a pointer. Returns the node this call activated, or `null`.
+ *
+ * **An activation is a press and a release on the same node**, which is what every pointer
+ * convention worth copying does and what lets somebody who has pressed the wrong button slide off
+ * it and let go. A release somewhere else clears the press and activates nothing.
+ *
+ * Press moves focus to the node pressed when that node is focusable, and **leaves focus alone
+ * otherwise** — clicking the background should not silently take the keyboard away from a field.
+ *
+ * Allocates nothing, and is meant to be called once per frame with whatever the pointer is doing.
+ */
+export declare function routeUiPointer(input: UiInput, root: UiNode, x: number, y: number, down: boolean): UiNode | null;
+/** Move focus, clearing whatever had it. `null` focuses nothing. */
+export declare function setUiFocus(input: UiInput, node: UiNode | null): void;
+/**
+ * Route a key. Returns the node it activated, or `null`.
+ *
+ * Three keys and no more: `Tab` and `Shift+Tab` move focus, `Enter` and `' '` activate what has it.
+ * Everything else is the caller's — a text field's own characters, a game's own bindings — and is
+ * reported as unhandled by returning `null` so the caller can tell.
+ *
+ * `key` is a DOM `KeyboardEvent.key`, because that is what a consumer already has and inventing a
+ * second spelling of `Tab` would be a table to keep in step.
+ */
+export declare function routeUiKey(input: UiInput, root: UiNode, key: string, shift?: boolean): UiNode | null;
+/**
+ * Forget everything, and clear the flags this router set on the tree.
+ *
+ * For a tree going away or a pointer leaving the window. Without it a node keeps the `hovered` it
+ * had when the cursor left, and draws lit for ever.
+ */
+export declare function resetUiInput(input: UiInput): void;

package/dist/uiInput.js

@@ -0,0 +1,85 @@
+/** Routing: a pointer and a keyboard turned into hover, press, focus and one activation. */
+import { uiFocusNext, uiFocusPrevious, uiHitTest } from './uiFocus.js';
+export function createUiInput() {
+    return { hovered: null, pressed: null, focused: null, wasDown: false };
+}
+/**
+ * Route a pointer. Returns the node this call activated, or `null`.
+ *
+ * **An activation is a press and a release on the same node**, which is what every pointer
+ * convention worth copying does and what lets somebody who has pressed the wrong button slide off
+ * it and let go. A release somewhere else clears the press and activates nothing.
+ *
+ * Press moves focus to the node pressed when that node is focusable, and **leaves focus alone
+ * otherwise** — clicking the background should not silently take the keyboard away from a field.
+ *
+ * Allocates nothing, and is meant to be called once per frame with whatever the pointer is doing.
+ */
+export function routeUiPointer(input, root, x, y, down) {
+    const over = uiHitTest(root, x, y);
+    if (input.hovered !== over) {
+        if (input.hovered !== null)
+            input.hovered.hovered = false;
+        if (over !== null)
+            over.hovered = true;
+        input.hovered = over;
+    }
+    let activated = null;
+    if (down && !input.wasDown) {
+        input.pressed = over;
+        if (over !== null) {
+            over.pressed = true;
+            if (over.focusable)
+                setUiFocus(input, over);
+        }
+    }
+    else if (!down && input.wasDown) {
+        if (input.pressed !== null) {
+            input.pressed.pressed = false;
+            if (input.pressed === over)
+                activated = input.pressed;
+        }
+        input.pressed = null;
+    }
+    input.wasDown = down;
+    return activated;
+}
+/** Move focus, clearing whatever had it. `null` focuses nothing. */
+export function setUiFocus(input, node) {
+    input.focused = node;
+}
+/**
+ * Route a key. Returns the node it activated, or `null`.
+ *
+ * Three keys and no more: `Tab` and `Shift+Tab` move focus, `Enter` and `' '` activate what has it.
+ * Everything else is the caller's — a text field's own characters, a game's own bindings — and is
+ * reported as unhandled by returning `null` so the caller can tell.
+ *
+ * `key` is a DOM `KeyboardEvent.key`, because that is what a consumer already has and inventing a
+ * second spelling of `Tab` would be a table to keep in step.
+ */
+export function routeUiKey(input, root, key, shift = false) {
+    if (key === 'Tab') {
+        setUiFocus(input, shift ? uiFocusPrevious(root, input.focused) : uiFocusNext(root, input.focused));
+        return null;
+    }
+    if ((key === 'Enter' || key === ' ') && input.focused !== null)
+        return input.focused;
+    return null;
+}
+/**
+ * Forget everything, and clear the flags this router set on the tree.
+ *
+ * For a tree going away or a pointer leaving the window. Without it a node keeps the `hovered` it
+ * had when the cursor left, and draws lit for ever.
+ */
+export function resetUiInput(input) {
+    if (input.hovered !== null)
+        input.hovered.hovered = false;
+    if (input.pressed !== null)
+        input.pressed.pressed = false;
+    input.hovered = null;
+    input.pressed = null;
+    input.focused = null;
+    input.wasDown = false;
+}

package/dist/uiLayout.d.ts

@@ -0,0 +1,23 @@
+/** Two passes over an interface tree: measure what wants a size, then place what got one. */
+import type { UiNode } from './uiNode.ts';
+/**
+ * Lay a tree out into `x`, `y`, `w`, `h`.
+ *
+ * **Two passes, bottom-up then top-down, and no third.** The measure pass answers what every node
+ * comes to on its own; the place pass hands out the space that exists and distributes what is left
+ * over. A `fit` size that depended on the space it was given would need a third pass and a rule for
+ * when to stop, which is where a layout engine stops being explicable.
+ *
+ * **Allocates nothing.** Every number it produces is written into a `UiRect` the node already owns,
+ * so a tree laid out every frame costs no garbage. That is the rule this whole module is shaped by,
+ * and it is why the node is an object with fields rather than a description that gets resolved into
+ * one.
+ *
+ * **The box is what is *available*, and the root resolves its own size against it** like any other
+ * node: `grow` fills it, a number is that number, and `fit` — the default — comes to whatever its
+ * contents do. So the same call lays out a full-screen HUD and a tooltip, and a caller does not
+ * have to measure a menu itself before it can place one. Nothing is clamped to the box: a `fit`
+ * root with more in it than fits reports the size it really is, because a silently truncated
+ * layout is worse than one that visibly overflows.
+ */
+export declare function layoutUiTree(root: UiNode, x: number, y: number, w: number, h: number): void;

package/dist/uiLayout.js

@@ -0,0 +1,144 @@
+/** Two passes over an interface tree: measure what wants a size, then place what got one. */
+/**
+ * Lay a tree out into `x`, `y`, `w`, `h`.
+ *
+ * **Two passes, bottom-up then top-down, and no third.** The measure pass answers what every node
+ * comes to on its own; the place pass hands out the space that exists and distributes what is left
+ * over. A `fit` size that depended on the space it was given would need a third pass and a rule for
+ * when to stop, which is where a layout engine stops being explicable.
+ *
+ * **Allocates nothing.** Every number it produces is written into a `UiRect` the node already owns,
+ * so a tree laid out every frame costs no garbage. That is the rule this whole module is shaped by,
+ * and it is why the node is an object with fields rather than a description that gets resolved into
+ * one.
+ *
+ * **The box is what is *available*, and the root resolves its own size against it** like any other
+ * node: `grow` fills it, a number is that number, and `fit` — the default — comes to whatever its
+ * contents do. So the same call lays out a full-screen HUD and a tooltip, and a caller does not
+ * have to measure a menu itself before it can place one. Nothing is clamped to the box: a `fit`
+ * root with more in it than fits reports the size it really is, because a silently truncated
+ * layout is worse than one that visibly overflows.
+ */
+export function layoutUiTree(root, x, y, w, h) {
+    measure(root);
+    place(root, x, y, root.width === 'grow' ? w : root.measuredWidth, root.height === 'grow' ? h : root.measuredHeight);
+}
+/**
+ * What a node comes to on its own, written into `measuredWidth` and `measuredHeight`.
+ *
+ * A `grow` child measures as `fit` here, which is what lets a menu sized to its contents hold a row
+ * that fills it: at measure time there is nothing to take a share of, so the honest answer is the
+ * child's own natural size. The place pass is where `grow` means anything.
+ */
+function measure(node) {
+    let along = 0;
+    let across = 0;
+    let counted = 0;
+    const row = node.direction === 'row';
+    for (const child of node.children) {
+        if (child.hidden)
+            continue;
+        measure(child);
+        if (child.absolute)
+            continue;
+        const childAlong = row ? child.measuredWidth : child.measuredHeight;
+        const childAcross = row ? child.measuredHeight : child.measuredWidth;
+        along += childAlong;
+        if (childAcross > across)
+            across = childAcross;
+        counted += 1;
+    }
+    if (counted > 1)
+        along += node.gap * (counted - 1);
+    const padX = node.paddingLeft + node.paddingRight;
+    const padY = node.paddingTop + node.paddingBottom;
+    const contentAlong = counted === 0 ? (row ? node.contentWidth : node.contentHeight) : along;
+    const contentAcross = counted === 0 ? (row ? node.contentHeight : node.contentWidth) : across;
+    const fitWidth = (row ? contentAlong : contentAcross) + padX;
+    const fitHeight = (row ? contentAcross : contentAlong) + padY;
+    node.measuredWidth = typeof node.width === 'number' ? node.width : fitWidth;
+    node.measuredHeight = typeof node.height === 'number' ? node.height : fitHeight;
+}
+/** Put a node in a box, then put its children in what is left of it. */
+function place(node, x, y, w, h) {
+    node.rect.x = x;
+    node.rect.y = y;
+    node.rect.w = w;
+    node.rect.h = h;
+    const row = node.direction === 'row';
+    const contentX = x + node.paddingLeft;
+    const contentY = y + node.paddingTop;
+    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;
+    const contentAcross = row ? contentH : contentW;
+    /* What the flow children take before anything grows, and how many of them want to grow. */
+    let taken = 0;
+    let growers = 0;
+    let counted = 0;
+    for (const child of node.children) {
+        if (child.hidden || child.absolute)
+            continue;
+        const asked = row ? child.width : child.height;
+        if (asked === 'grow')
+            growers += 1;
+        else
+            taken += row ? child.measuredWidth : child.measuredHeight;
+        counted += 1;
+    }
+    const gaps = counted > 1 ? node.gap * (counted - 1) : 0;
+    const spare = Math.max(0, contentAlong - taken - gaps);
+    const share = growers > 0 ? spare / growers : 0;
+    /*
+     * `justify` spends what is left over, and there is nothing left over once something has grown —
+     * which is why a growing child and a `center` on the same node are not a contradiction: the
+     * growing child ate the leftover, so centring has nothing to move.
+     */
+    let cursor = 0;
+    let between = 0;
+    if (growers === 0) {
+        if (node.justify === 'center')
+            cursor = spare / 2;
+        else if (node.justify === 'end')
+            cursor = spare;
+        else if (node.justify === 'between' && counted > 1)
+            between = spare / (counted - 1);
+    }
+    for (const child of node.children) {
+        if (child.hidden)
+            continue;
+        if (child.absolute) {
+            placeAbsolute(child, contentX, contentY, contentW, contentH);
+            continue;
+        }
+        const askedAlong = row ? child.width : child.height;
+        const sizeAlong = askedAlong === 'grow' ? share : row ? child.measuredWidth : child.measuredHeight;
+        const askedAcross = row ? child.height : child.width;
+        const naturalAcross = row ? child.measuredHeight : child.measuredWidth;
+        const sizeAcross = node.align === 'stretch' || askedAcross === 'grow' ? contentAcross : naturalAcross;
+        let offAcross = 0;
+        if (node.align === 'center')
+            offAcross = (contentAcross - sizeAcross) / 2;
+        else if (node.align === 'end')
+            offAcross = contentAcross - sizeAcross;
+        if (row) {
+            place(child, contentX + cursor, contentY + offAcross, sizeAlong, sizeAcross);
+        }
+        else {
+            place(child, contentX + offAcross, contentY + cursor, sizeAcross, sizeAlong);
+        }
+        cursor += sizeAlong + node.gap + between;
+    }
+}
+/**
+ * A child taken out of the flow: at its own offset inside the parent's content box.
+ *
+ * Inside the content box rather than the border box, so an absolute badge in a padded panel sits
+ * 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.
+ */
+function placeAbsolute(child, contentX, contentY, contentW, contentH) {
+    const w = child.width === 'grow' ? contentW : child.measuredWidth;
+    const h = child.height === 'grow' ? contentH : child.measuredHeight;
+    place(child, contentX + child.x, contentY + child.y, w, h);
+}

package/dist/uiNode.d.ts

@@ -0,0 +1,105 @@
+/** A node of the retained interface tree: what it is, where it wants to be, and what it draws. */
+import type { SpriteFrame } from './spriteSheet.ts';
+/**
+ * How big a node asks to be along one axis.
+ *
+ * A number is that many units. `fit` is whatever its own contents come to. `grow` takes an equal
+ * share of what is left along the parent's main axis, and behaves as `fit` across it.
+ *
+ * **Three cases rather than a percentage or a flex factor**, and the omission is deliberate: a
+ * percentage of a parent that is itself `fit` is a cycle, and a weighted `grow` is a fourth case
+ * whose only caller so far would be a two-to-one split that two nested nodes already express.
+ */
+export type UiSize = number | 'fit' | 'grow';
+/** Where children sit across the parent's main axis. `stretch` gives them the whole cross extent. */
+export type UiAlign = 'start' | 'center' | 'end' | 'stretch';
+/** How the leftover along the main axis is spent when no child asked to `grow`. */
+export type UiJustify = 'start' | 'center' | 'end' | 'between';
+/** A resolved box, in whatever units the tree is laid out in. Written by `layoutUiTree`. */
+export interface UiRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface UiNodeOptions {
+    readonly direction?: 'row' | 'column';
+    readonly width?: UiSize;
+    readonly height?: UiSize;
+    /** One number for all four sides. Set the four fields for anything else. */
+    readonly padding?: number;
+    readonly gap?: number;
+    readonly align?: UiAlign;
+    readonly justify?: UiJustify;
+    /** Taken out of the flow and placed at `x`, `y` inside the parent's content box. */
+    readonly absolute?: boolean;
+    readonly x?: number;
+    readonly y?: number;
+    /** What a `fit` node measures when it has no children: a label's text, an icon's size. */
+    readonly contentWidth?: number;
+    readonly contentHeight?: number;
+    readonly hidden?: boolean;
+    readonly background?: ArrayLike<number> | null;
+    /** The sprite slot this node draws from, or `-1` for none. */
+    readonly texture?: number;
+    readonly frame?: SpriteFrame | null;
+    readonly tint?: ArrayLike<number> | null;
+    readonly text?: string;
+    readonly interactive?: boolean;
+    readonly focusable?: boolean;
+    /** For a caller to find its own node again. Not read by anything here. */
+    readonly name?: string;
+}
+/**
+ * A node.
+ *
+ * **An object with mutable fields rather than a row of typed arrays**, and this is the one place in
+ * this package where that is the right answer. An interface tree is tens or hundreds of nodes built
+ * once and mutated, not thousands rebuilt per frame — the case struct-of-arrays exists for. What
+ * the hot path needs is that laying one out and drawing it allocates nothing, and both write into
+ * fields that already exist.
+ */
+export interface UiNode {
+    readonly children: UiNode[];
+    parent: UiNode | null;
+    direction: 'row' | 'column';
+    width: UiSize;
+    height: UiSize;
+    paddingLeft: number;
+    paddingTop: number;
+    paddingRight: number;
+    paddingBottom: number;
+    gap: number;
+    align: UiAlign;
+    justify: UiJustify;
+    absolute: boolean;
+    x: number;
+    y: number;
+    contentWidth: number;
+    contentHeight: number;
+    hidden: boolean;
+    /** 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. */
+    measuredWidth: number;
+    measuredHeight: number;
+    background: Float32Array | null;
+    texture: number;
+    frame: SpriteFrame | null;
+    tint: Float32Array | null;
+    text: string;
+    interactive: boolean;
+    focusable: boolean;
+    hovered: boolean;
+    pressed: boolean;
+    name: string;
+}
+export declare function createUiNode(options?: UiNodeOptions): UiNode;
+/** Put `child` at the end of `parent`'s children, detaching it from wherever it was. */
+export declare function addUiChild(parent: UiNode, child: UiNode): UiNode;
+/** Take `child` out of `parent`. A child that is not there is left alone. */
+export declare function removeUiChild(parent: UiNode, child: UiNode): void;
+/** The node named, depth-first from `root`, or `null`. For a caller finding its own tree again. */
+export declare function uiNodeNamed(root: UiNode, name: string): UiNode | null;
+/** Whether a point is inside a node's resolved box. */
+export declare function uiRectHolds(node: UiNode, x: number, y: number): boolean;