@driftengine/ui2d 3.61.0

package/src/spritePass.ts

@@ -0,0 +1,231 @@
+/** The 2D layer as a pass a consumer registers: one batch of quads, drawn where the caller says. */
+
+import type { PassContext, PassDefinition, PassDevice } from '@driftengine/core';
+
+import { SPRITE_BINDINGS } from './shaders/generated/sprite.wgsl.ts';
+import { createAffine2D } from './camera2d.ts';
+import type { Affine2D } from './camera2d.ts';
+import { createSpriteBatch, resetSpriteBatch } from './spriteBatch.ts';
+import type { SpriteBatch } from './spriteBatch.ts';
+import {
+  createWebgl2Sprites,
+  disposeWebgl2Sprites,
+  drawWebgl2Sprites,
+  setWebgl2SpriteTexture,
+  setWebgl2WhiteTexture,
+  uploadWebgl2Instances,
+} from './spriteGl.ts';
+import type { Webgl2Sprites } from './spriteGl.ts';
+import {
+  createGpuSprites,
+  disposeGpuSprites,
+  drawGpuSprites,
+  setGpuSpriteTexture,
+  setGpuWhiteTexture,
+  uploadGpuInstances,
+} from './spriteGpu.ts';
+import type { GpuSprites } from './spriteGpu.ts';
+import { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.ts';
+import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+
+const VERT = SPRITE_BINDINGS.SPRITE_VERT;
+const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
+
+/** Identity, so a pass that is drawn before it is transformed puts its sprites in clip space. */
+const IDENTITY_CLIP = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+/** Sprites a frame, if the caller does not say. Four thousand quads is 224 KB of instance data. */
+export const DEFAULT_SPRITE_CAPACITY = 4096;
+
+/**
+ * Texture slots, if the caller does not say.
+ *
+ * Eight is a sheet for the world, one for the interface, and room to spare. It is not a GPU limit
+ * — each slot is its own bind group on WebGPU and its own object on WebGL2 — it is the number
+ * above which a caller should be asking why its 2D layer has that many atlases.
+ */
+export const DEFAULT_SPRITE_SLOTS = 8;
+
+export interface SpritePassOptions {
+  readonly capacity?: number;
+  readonly slots?: number;
+  readonly label?: string;
+}
+
+export interface SpritePass extends PassDefinition {
+  /**
+   * The quads for this frame. Reset it, fill it with `drawSprite`, then call `drawPass`.
+   *
+   * Held by the pass rather than handed in per frame, because its size is the pass's GPU buffer
+   * and the two must agree.
+   */
+  readonly batch: SpriteBatch;
+  /**
+   * A slot holding one opaque white texel, filled by the pass and not settable.
+   *
+   * White is the identity of the multiply the shader does, so a quad on this slot draws exactly its
+   * tint — which is what a solid rectangle is, and what `fillPanel` in core does with a whole
+   * program of its own. A caller drawing a filled box needs no sheet for it.
+   *
+   * **A background on this slot and an image from a sheet are two runs**, because a slot change is
+   * a run and the order may not be regrouped. A caller with many filled boxes and many images
+   * interleaved should pack a white texel into its *own* sheet and tint a frame of that instead:
+   * then the whole tree is one run. This slot is the convenience, and the sheet is the fast path.
+   */
+  readonly white: number;
+  /** Clear the batch. Call once at the top of a frame. */
+  reset(): void;
+  /**
+   * Where the batch's coordinates are, from `screenToNdc` or `worldToNdc`.
+   *
+   * Copied, so the caller may reuse its array; and read at draw time, so this can be called before
+   * the pass has a device.
+   */
+  setTransform(affine: Affine2D): void;
+  /** Fill a texture slot. Safe before the pass is registered; applied when it gets a device. */
+  setTexture(slot: number, source: SpriteImage, options?: SpriteTextureOptions): void;
+}
+
+interface PendingTexture {
+  readonly slot: number;
+  readonly source: SpriteImage;
+  readonly options: SpriteTextureOptions;
+}
+
+export function createSpritePass(options: SpritePassOptions = {}): SpritePass {
+  const capacity = options.capacity ?? DEFAULT_SPRITE_CAPACITY;
+  const slots = options.slots ?? DEFAULT_SPRITE_SLOTS;
+  const label = options.label ?? 'ui2d.sprites';
+  /* One past the caller's slots, so `setTexture` cannot reach it and it cannot be lost. */
+  const white = slots;
+  const batch = createSpriteBatch(capacity);
+  const toNdc = createAffine2D();
+  /* Identity as an affine: ndc = (x, y). A caller that never sets one draws in clip space. */
+  toNdc[0] = 1;
+  toNdc[3] = 1;
+
+  let gl: Webgl2Sprites | null = null;
+  let context: WebGL2RenderingContext | null = null;
+  let gpu: GpuSprites | null = null;
+  let device: GPUDevice | null = null;
+  let clipCorrection: Float32Array = IDENTITY_CLIP;
+  const pending: PendingTexture[] = [];
+
+  const applyTexture = (entry: PendingTexture): void => {
+    if (gl !== null && context !== null) {
+      setWebgl2SpriteTexture(context, gl, entry.slot, entry.source, entry.options);
+      return;
+    }
+    if (gpu !== null && device !== null) {
+      setGpuSpriteTexture(device, gpu, entry.slot, entry.source, entry.options);
+    }
+  };
+
+  return {
+    label,
+    batch,
+    white,
+
+    reset(): void {
+      resetSpriteBatch(batch);
+    },
+
+    setTransform(affine: Affine2D): void {
+      toNdc.set(affine);
+    },
+
+    setTexture(slot: number, source: SpriteImage, textureOptions?: SpriteTextureOptions): void {
+      if (slot < 0 || slot >= slots) {
+        throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+      }
+      const entry: PendingTexture = {
+        slot,
+        source,
+        options: textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS,
+      };
+      if (gl === null && gpu === null) {
+        pending.push(entry);
+        return;
+      }
+      applyTexture(entry);
+    },
+
+    init(passDevice: PassDevice): void {
+      /*
+       * The correction the *matrix* carries, because this stage builds its own clip position and
+       * never multiplies by a camera. Without it the generated WGSL's Y negation stands
+       * uncancelled and the whole 2D layer lands mirrored — `panel.ts` in core made the same
+       * mistake once and its comment is where the reason is written out.
+       */
+      clipCorrection = passDevice.clipCorrection;
+      if (passDevice.backend === 'webgl2') {
+        context = passDevice.gl;
+        gl = createWebgl2Sprites(passDevice.gl, capacity, slots + 1, label);
+      } else {
+        device = passDevice.device;
+        gpu = createGpuSprites(
+          passDevice.device,
+          passDevice.format,
+          passDevice.depthFormat,
+          passDevice.samples,
+          capacity,
+          slots + 1,
+          label,
+        );
+      }
+      if (gl !== null && context !== null) setWebgl2WhiteTexture(context, gl, white);
+      if (gpu !== null && device !== null) setGpuWhiteTexture(device, gpu, white);
+      for (const entry of pending) applyTexture(entry);
+      pending.length = 0;
+    },
+
+    draw(ctx: PassContext): void {
+      if (batch.count === 0) return;
+      if (ctx.backend === 'webgl2') {
+        if (gl === null) return;
+        uploadWebgl2Instances(ctx.gl, gl, batch);
+        drawWebgl2Sprites(
+          ctx.gl,
+          gl,
+          batch,
+          toNdc,
+          clipCorrection,
+          ctx.outputTransform,
+          ctx.outputExposure,
+        );
+        return;
+      }
+      if (gpu === null || device === null) return;
+      const f = gpu.vertexFloats;
+      f[VERT.fields.uToNdc0.offset / 4] = toNdc[0] as number;
+      f[VERT.fields.uToNdc0.offset / 4 + 1] = toNdc[1] as number;
+      f[VERT.fields.uToNdc0.offset / 4 + 2] = toNdc[2] as number;
+      f[VERT.fields.uToNdc0.offset / 4 + 3] = toNdc[3] as number;
+      f[VERT.fields.uToNdc1.offset / 4] = toNdc[4] as number;
+      f[VERT.fields.uToNdc1.offset / 4 + 1] = toNdc[5] as number;
+      f.set(clipCorrection, VERT.fields.uClipCorrection.offset / 4);
+      gpu.fragmentInts[FRAG.fields.uOutputTransform.offset / 4] = ctx.outputTransform;
+      gpu.fragmentFloats[FRAG.fields.uOutputExposure.offset / 4] = ctx.outputExposure;
+      /*
+       * Written from inside an open render pass, which is allowed and ordered: a queue write
+       * issued now lands before the command buffer this pass is being recorded into is submitted.
+       * What it does mean is **one `drawPass` a frame per pass** — a second would overwrite the
+       * first's instances before either had executed. A caller that wants the 2D layer in two
+       * places in the frame registers two passes, which is also how two splat captures work.
+       */
+      device.queue.writeBuffer(gpu.vertexUniforms, 0, gpu.vertexScratch);
+      device.queue.writeBuffer(gpu.fragmentUniforms, 0, gpu.fragmentScratch);
+      uploadGpuInstances(device, gpu, batch);
+      drawGpuSprites(ctx.pass, gpu, batch);
+    },
+
+    dispose(): void {
+      if (gl !== null && context !== null) disposeWebgl2Sprites(context, gl);
+      if (gpu !== null) disposeGpuSprites(gpu);
+      gl = null;
+      gpu = null;
+      context = null;
+      device = null;
+    },
+  };
+}

package/src/spriteSheet.ts

@@ -0,0 +1,147 @@
+/** A sheet: the rectangles of one texture that each hold a picture, addressed by index or name. */
+
+import type { UvRect } from './spriteBatch.ts';
+
+/** A `UvRect` a caller owns and refills, so reading a frame allocates nothing. */
+export interface SpriteFrame {
+  u0: number;
+  v0: number;
+  u1: number;
+  v1: number;
+}
+
+export function createSpriteFrame(): SpriteFrame {
+  return { u0: 0, v0: 0, u1: 1, v1: 1 };
+}
+
+/** One entry of an atlas, in texels, as a packer emits it. */
+export interface SheetEntry {
+  readonly name: string;
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+/**
+ * The frames of one texture.
+ *
+ * Two flat arrays and a name index rather than an array of objects: reading a frame in a draw loop
+ * is four `Float32Array` reads and no property lookups, and a tilemap does that per tile.
+ */
+export interface SpriteSheet {
+  /** The slot on the pass this sheet's texture was set into. */
+  readonly texture: number;
+  /** The texture's own size, in texels. */
+  readonly width: number;
+  readonly height: number;
+  readonly count: number;
+  /** Four per frame: u0, v0, u1, v1. */
+  readonly uvs: Float32Array;
+  /** Two per frame: width and height in texels, for drawing a frame at its own scale. */
+  readonly sizes: Float32Array;
+  readonly names: ReadonlyMap<string, number>;
+}
+
+function build(
+  texture: number,
+  width: number,
+  height: number,
+  entries: readonly SheetEntry[],
+): SpriteSheet {
+  const uvs = new Float32Array(entries.length * 4);
+  const sizes = new Float32Array(entries.length * 2);
+  const names = new Map<string, number>();
+  entries.forEach((entry, index) => {
+    uvs[index * 4] = entry.x / width;
+    uvs[index * 4 + 1] = entry.y / height;
+    uvs[index * 4 + 2] = (entry.x + entry.w) / width;
+    uvs[index * 4 + 3] = (entry.y + entry.h) / height;
+    sizes[index * 2] = entry.w;
+    sizes[index * 2 + 1] = entry.h;
+    names.set(entry.name, index);
+  });
+  return { texture, width, height, count: entries.length, uvs, sizes, names };
+}
+
+/**
+ * A sheet cut into equal cells, row-major: left to right, then down.
+ *
+ * **A cell that would run off the edge is not emitted.** A sheet 70 texels wide cut into sixteens
+ * has four whole cells and six texels of margin, and a fifth cell reading into that margin is a
+ * frame with a stripe of nothing down one side — which reads as a rendering bug rather than as a
+ * badly measured atlas.
+ *
+ * Frames are named `"0"`, `"1"` and so on, so `frameOf` works on a grid too.
+ */
+export function gridSheet(
+  texture: number,
+  width: number,
+  height: number,
+  cellWidth: number,
+  cellHeight: number,
+): SpriteSheet {
+  const columns = Math.floor(width / cellWidth);
+  const rows = Math.floor(height / cellHeight);
+  const entries: SheetEntry[] = [];
+  for (let row = 0; row < rows; row += 1) {
+    for (let column = 0; column < columns; column += 1) {
+      entries.push({
+        name: String(entries.length),
+        x: column * cellWidth,
+        y: row * cellHeight,
+        w: cellWidth,
+        h: cellHeight,
+      });
+    }
+  }
+  return build(texture, width, height, entries);
+}
+
+/** A sheet from an atlas description: whatever rectangles a packer put where. */
+export function namedSheet(
+  texture: number,
+  width: number,
+  height: number,
+  entries: readonly SheetEntry[],
+): SpriteSheet {
+  return build(texture, width, height, entries);
+}
+
+/** The index a name has, or `-1`. */
+export function frameOf(sheet: SpriteSheet, name: string): number {
+  return sheet.names.get(name) ?? -1;
+}
+
+/**
+ * Read a frame into a rectangle the caller owns. Allocates nothing.
+ *
+ * **An index this sheet does not have reads as the whole texture rather than throwing**, because
+ * this is called per sprite per frame and the rule is that nothing throws in the frame loop. What
+ * a caller then sees is the entire atlas drawn where one picture should be, which is unmistakable.
+ */
+export function sheetFrame(sheet: SpriteSheet, index: number, out: SpriteFrame): UvRect {
+  if (index < 0 || index >= sheet.count) {
+    out.u0 = 0;
+    out.v0 = 0;
+    out.u1 = 1;
+    out.v1 = 1;
+    return out;
+  }
+  const at = index * 4;
+  out.u0 = sheet.uvs[at] as number;
+  out.v0 = sheet.uvs[at + 1] as number;
+  out.u1 = sheet.uvs[at + 2] as number;
+  out.v1 = sheet.uvs[at + 3] as number;
+  return out;
+}
+
+/** A frame's width in texels, or 0 for an index the sheet does not have. */
+export function sheetFrameWidth(sheet: SpriteSheet, index: number): number {
+  return index < 0 || index >= sheet.count ? 0 : (sheet.sizes[index * 2] as number);
+}
+
+/** A frame's height in texels, or 0 for an index the sheet does not have. */
+export function sheetFrameHeight(sheet: SpriteSheet, index: number): number {
+  return index < 0 || index >= sheet.count ? 0 : (sheet.sizes[index * 2 + 1] as number);
+}

package/src/spriteTexture.ts

@@ -0,0 +1,42 @@
+/** What a caller hands over as a sprite texture, and what it says about it. */
+
+/**
+ * The three sources both backends take without a conversion.
+ *
+ * Narrower than `TexImageSource` on purpose. WebGPU's `copyExternalImageToTexture` refuses an
+ * `ImageData` outright, and an `HTMLImageElement` is accepted by only some implementations — so
+ * the union that is honestly portable is a bitmap and the two canvases. A caller with an `<img>`
+ * reaches this through one `createImageBitmap`, which is also where the decode's own orientation
+ * and premultiply options live, and those are decisions worth making in the open.
+ *
+ * All three carry their own `width` and `height`, which is the other reason: nothing here has to
+ * ask the caller how big the image it just handed over is.
+ */
+export type SpriteImage = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+
+export interface SpriteTextureOptions {
+  /**
+   * `srgb` is right for anything painted to be looked at, which is every sprite sheet — the
+   * sampler decodes and the pass's own output transform re-encodes, so the blend happens in
+   * linear light where it belongs. `linear` is for a sheet carrying data rather than colour: a
+   * mask, a height, a flow field.
+   *
+   * The same name and the same two values `SurfaceTexture` already takes, so a consumer that has
+   * uploaded a texture to the mesh path does not meet a second vocabulary here.
+   */
+  readonly colorSpace?: 'linear' | 'srgb';
+  /**
+   * `nearest` by default, and the default is the argument.
+   *
+   * A sprite sheet is usually pixel art, where linear filtering is the thing that makes it look
+   * wrong; and a sheet that is *not* pixel art is normally drawn near its authored size, where
+   * the two filters differ by very little. So the default costs the smooth case almost nothing
+   * and saves the sharp case from a blur nobody asked for.
+   */
+  readonly filter?: 'nearest' | 'linear';
+}
+
+export const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions = {
+  colorSpace: 'srgb',
+  filter: 'nearest',
+};

package/src/tilemap.ts

@@ -0,0 +1,114 @@
+/** A grid of sheet frames, drawn as sprites, culled to what the view can see. */
+
+import { drawSprite } from './spriteBatch.ts';
+import type { SpriteBatch } from './spriteBatch.ts';
+import { createSpriteFrame, sheetFrame } from './spriteSheet.ts';
+import type { SpriteSheet } from './spriteSheet.ts';
+
+/** A cell holding nothing. Negative, so it can never be a frame index. */
+export const TILE_EMPTY = -1;
+
+export interface Tilemap {
+  readonly columns: number;
+  readonly rows: number;
+  /** One frame index per cell, row-major. `TILE_EMPTY` for a cell with nothing in it. */
+  readonly tiles: Int32Array;
+  /** How big a cell is, in whatever units the batch's affine maps from. */
+  readonly tileWidth: number;
+  readonly tileHeight: number;
+  /**
+   * Where cell (0, 0)'s corner sits.
+   *
+   * Mutable, because scrolling a map is moving it and the alternative is rebuilding one.
+   */
+  x: number;
+  y: number;
+}
+
+/** What the view can see, in the same units the map is placed in. */
+export interface ViewRect {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+export function createTilemap(
+  columns: number,
+  rows: number,
+  tileWidth: number,
+  tileHeight: number,
+): Tilemap {
+  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: Tilemap, column: number, row: number): number {
+  if (column < 0 || column >= map.columns || row < 0 || row >= map.rows) return TILE_EMPTY;
+  return map.tiles[row * map.columns + column] as number;
+}
+
+/** Put a frame in a cell. A cell outside the map is ignored rather than wrapping into another row. */
+export function setTile(map: Tilemap, column: number, row: number, tile: number): void {
+  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: SpriteBatch,
+  map: Tilemap,
+  sheet: SpriteSheet,
+  view: ViewRect,
+  tint: ArrayLike<number> | null,
+): number {
+  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] as number;
+      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/src/uiDraw.ts

@@ -0,0 +1,63 @@
+/** Turn a laid-out interface tree into quads, parents first so children land on top. */
+
+import { drawSprite } from './spriteBatch.ts';
+import type { SpriteBatch, SpritePlacement } 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;
+}
+
+/* One placement, refilled per node. This is a per-frame path and it is the only object in it. */
+const PLACEMENT: SpritePlacement & { x: number; y: number; w: number; h: number } = {
+  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: SpriteBatch,
+  root: UiNode,
+  white: number,
+  sink: UiContentSink | null,
+): number {
+  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/src/uiFocus.ts

@@ -0,0 +1,80 @@
+/** Which node a point is on, and which node a keyboard should be talking to. */
+
+import { uiRectHolds } from './uiNode.ts';
+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 function uiHitTest(root: UiNode, x: number, y: number): UiNode | null {
+  if (root.hidden) return null;
+  for (let i = root.children.length - 1; i >= 0; i -= 1) {
+    const hit = uiHitTest(root.children[i] as UiNode, 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: UiNode, out: UiNode[]): UiNode[] {
+  out.length = 0;
+  gather(root, out);
+  return out;
+}
+
+function gather(node: UiNode, out: UiNode[]): void {
+  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: 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 function uiFocusNext(root: UiNode, current: UiNode | null): UiNode | null {
+  return step(root, current, 1);
+}
+
+/** The focusable node before `current`, wrapping. */
+export function uiFocusPrevious(root: UiNode, current: UiNode | null): UiNode | null {
+  return step(root, current, -1);
+}
+
+function step(root: UiNode, current: UiNode | null, by: number): UiNode | null {
+  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]) as UiNode;
+  const next = (at + by + ORDER.length) % ORDER.length;
+  return ORDER[next] as UiNode;
+}