@driftengine/ui2d 3.63.0 → 4.1.0

package/src/a11y.ts

@@ -0,0 +1,73 @@
+/**
+ * The interface tree in the shape assistive technology needs, and the seam that publishes it.
+ *
+ * **A seam, because whether anything can receive this is the host's business.** A browser host can
+ * mirror the tree into a hidden structure that a screen reader walks. A native host may have a
+ * platform accessibility service, or may have nothing — and `createNullA11yHost` is the honest
+ * answer in that case rather than an absence nobody noticed.
+ */
+import type { UiNode } from './uiNode.ts';
+
+export interface A11yNode {
+  role: string;
+  label: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  focused: boolean;
+}
+
+export interface A11yHost {
+  publish(nodes: readonly A11yNode[], count: number): void;
+}
+
+/** A host that accepts a tree and does nothing with it. See the header. */
+export function createNullA11yHost(): A11yHost {
+  return { publish() {} };
+}
+
+/**
+ * What role this node plays, derived rather than declared.
+ *
+ * Derived, because a role a caller has to set is a role most callers will not set, and an
+ * accessibility tree that is mostly unlabelled is worse than none: it reads as though the interface
+ * has been described when it has not.
+ */
+function roleOf(node: UiNode): string {
+  if (node.focusable && node.children.length === 0) return 'button';
+  if (node.clip && (node.contentSpanX > node.rect.w || node.contentSpanY > node.rect.h)) {
+    return 'scrollable';
+  }
+  return 'text';
+}
+
+function contributes(node: UiNode): boolean {
+  return node.interactive || node.focusable || node.text.length > 0;
+}
+
+function gather(node: UiNode, out: A11yNode[], at: number): number {
+  if (node.hidden) return at;
+  let next = at;
+  if (contributes(node)) {
+    const slot = out[next] ?? { role: '', label: '', x: 0, y: 0, w: 0, h: 0, focused: false };
+    slot.role = roleOf(node);
+    slot.label = node.text;
+    slot.x = node.rect.x;
+    slot.y = node.rect.y;
+    slot.w = node.rect.w;
+    slot.h = node.rect.h;
+    slot.focused = false;
+    out[next] = slot;
+    next += 1;
+  }
+  for (const child of node.children) next = gather(child, out, next);
+  return next;
+}
+
+/** Fill `out` with every node worth describing, in tree order. Returns how many. */
+export function a11yTree(root: UiNode, out: A11yNode[]): number {
+  const count = gather(root, out, 0);
+  out.length = count;
+  return count;
+}

package/src/index.ts

@@ -53,3 +53,57 @@ export { uiFocusNext, uiFocusOrder, uiFocusPrevious, uiHitTest } from './uiFocus
 
 export { createUiInput, resetUiInput, routeUiKey, routeUiPointer, setUiFocus } from './uiInput.ts';
 export type { UiInput } from './uiInput.ts';
+
+/*
+ * The interface framework: what an editor needs from a 2D layer and a game's interface wants too.
+ *
+ * Every platform touch below is a capability the caller supplies — `TextHost` for composition and
+ * the clipboard, `A11yHost` for assistive technology — because this has to run under a host with
+ * no document object model. That is the same rule `AGENTS.md` already applies to persistence.
+ */
+export { clipRectFor, intersectClip } from './uiClip.ts';
+export { clampScroll, routeScrollWheel, scrollBy, scrollExtent } from './uiScroll.ts';
+export { layerOrder } from './uiLayer.ts';
+export { SLICE_STRIDE, sliceInto } from './uiSlice.ts';
+export type { SliceInset } from './uiSlice.ts';
+export {
+  createTextModel,
+  deleteBackward,
+  deleteForward,
+  insertText,
+  moveCaret,
+  moveToLineEdge,
+  selectAll,
+  selectedText,
+  selectionRange,
+} from './textModel.ts';
+export type { TextModel } from './textModel.ts';
+export { applyComposition, createNullTextHost } from './textHost.ts';
+export type { TextHost } from './textHost.ts';
+export { runsFor } from './richText.ts';
+export type { TextRun } from './richText.ts';
+export { visibleRange, visibleRangeVariable } from './virtualList.ts';
+export type { RowWindow } from './virtualList.ts';
+export {
+  createTheme,
+  deriveTheme,
+  themeColour,
+  themeRgba,
+  themeSize,
+  unpackRgba,
+} from './theme.ts';
+export type { Theme } from './theme.ts';
+export { clearDirty, createDirtyTracker, diffTree, dirtyBounds, markDirty } from './uiDirty.ts';
+export type { DirtyTracker } from './uiDirty.ts';
+export {
+  beginDrag,
+  capturePointer,
+  createPointerState,
+  dropTarget,
+  endDrag,
+  pointerTarget,
+  releasePointer,
+} from './uiPointer.ts';
+export type { PointerState } from './uiPointer.ts';
+export { a11yTree, createNullA11yHost } from './a11y.ts';
+export type { A11yHost, A11yNode } from './a11y.ts';

package/src/richText.ts

@@ -0,0 +1,69 @@
+/**
+ * Overlapping style runs, normalised into disjoint ones that cover every character once.
+ *
+ * **The normalisation is the whole job.** A syntax highlighter emits overlapping runs — a rule for
+ * the string, a more specific one for the escape inside it — and a renderer needs disjoint runs in
+ * order with no gaps. Every consumer that skips this step draws a character twice or not at all,
+ * and both look like a font problem.
+ *
+ * **Later wins the overlap**, because a later rule is the more specific one in every highlighter
+ * that emits them in that order.
+ */
+export interface TextRun {
+  from: number;
+  to: number;
+  colour: number;
+  bold: boolean;
+  italic: boolean;
+}
+
+/* Reused across calls: this runs per frame for a visible document. */
+const BOUNDS: number[] = [];
+
+/**
+ * Fill `out` with disjoint, ordered, gap-free runs covering `[0, text.length)`.
+ *
+ * Returns how many were written. With no input runs the answer is one run covering everything,
+ * which is what a plain string is.
+ */
+export function runsFor(text: string, runs: readonly TextRun[], out: TextRun[]): number {
+  const end = text.length;
+  if (end === 0) return 0;
+
+  BOUNDS.length = 0;
+  BOUNDS.push(0, end);
+  for (const run of runs) {
+    const from = Math.max(0, Math.min(end, run.from));
+    const to = Math.max(0, Math.min(end, run.to));
+    if (to > from) BOUNDS.push(from, to);
+  }
+  BOUNDS.sort((a, b) => a - b);
+
+  let count = 0;
+  let previous = -1;
+  for (let i = 0; i < BOUNDS.length - 1; i += 1) {
+    const from = BOUNDS[i] as number;
+    const to = BOUNDS[i + 1] as number;
+    if (from === to || from === previous) continue;
+    previous = from;
+
+    /* Last covering run wins; none covering means the default, which is what index -1 encodes. */
+    let chosen = -1;
+    for (let r = 0; r < runs.length; r += 1) {
+      const run = runs[r] as TextRun;
+      if (run.from <= from && run.to >= to) chosen = r;
+    }
+    const style = chosen === -1 ? null : (runs[chosen] as TextRun);
+
+    const slot = out[count] ?? { from: 0, to: 0, colour: 0xffffffff, bold: false, italic: false };
+    slot.from = from;
+    slot.to = to;
+    slot.colour = style?.colour ?? 0xffffffff;
+    slot.bold = style?.bold ?? false;
+    slot.italic = style?.italic ?? false;
+    out[count] = slot;
+    count += 1;
+  }
+  out.length = count;
+  return count;
+}

package/src/textHost.ts

@@ -0,0 +1,66 @@
+/**
+ * The platform services text entry needs, taken as a parameter.
+ *
+ * **Composition — the multi-keystroke entry every language that is not typed one character at a
+ * time depends on — is a platform service.** The browser has one, a native host has a different
+ * one, and a test has none. `AGENTS.md` requires a capability be taken as a parameter with a
+ * browser implementation shipped as the default; this is that rule applied to text, and it is why
+ * this package can run under a host with no document object model at all.
+ */
+import type { TextModel } from './textModel.ts';
+import { selectionRange } from './textModel.ts';
+
+export interface TextHost {
+  /** Tell the host a field is focused at this rectangle, so it can place a composition window. */
+  focusField(x: number, y: number, w: number, h: number): void;
+  /** Tell the host nothing is focused. */
+  blurField(): void;
+  /** Read the clipboard, if the host has one. Asynchronous everywhere one exists. */
+  readClipboard(): Promise<string>;
+  /** Write the clipboard, if the host has one. */
+  writeClipboard(text: string): Promise<void>;
+}
+
+/**
+ * A host that focuses nothing and whose clipboard is empty.
+ *
+ * What a test uses, and what a headless build uses. **An empty clipboard rather than a missing
+ * one**, so a caller never has to branch on whether it has a host.
+ */
+export function createNullTextHost(): TextHost {
+  return {
+    focusField() {},
+    blurField() {},
+    readClipboard: async () => '',
+    writeClipboard: async () => {},
+  };
+}
+
+/**
+ * Fold one composition update into the model.
+ *
+ * An update replaces whatever the previous update of this composition put there, rather than the
+ * whole field — which is what makes a five-keystroke entry produce one word instead of five.
+ *
+ * **`done` clears the range, and that is the step everyone forgets.** A finished composition that
+ * leaves its range set means the *next* keystroke overwrites the text that was just committed,
+ * which presents as characters vanishing one word behind the caret.
+ */
+export function applyComposition(model: TextModel, state: { text: string; done: boolean }): void {
+  if (model.composeFrom === -1) {
+    const { from, to } = selectionRange(model);
+    model.text = model.text.slice(0, from) + state.text + model.text.slice(to);
+    model.composeFrom = from;
+    model.composeTo = from + state.text.length;
+  } else {
+    model.text =
+      model.text.slice(0, model.composeFrom) + state.text + model.text.slice(model.composeTo);
+    model.composeTo = model.composeFrom + state.text.length;
+  }
+  model.caret = model.composeTo;
+  model.anchor = model.caret;
+  if (state.done) {
+    model.composeFrom = -1;
+    model.composeTo = -1;
+  }
+}

package/src/textModel.ts

@@ -0,0 +1,126 @@
+/**
+ * A caret, a selection, and the operations that move them.
+ *
+ * **Pure, and it is pure on purpose.** Every editing defect anybody has met lives here rather than
+ * in the platform: a caret inside a character, a right-to-left selection that deletes the wrong
+ * end, a backspace that removes half an emoji. Pure, each of those is a test that runs in under a
+ * millisecond. Wired to a host, none of them is.
+ *
+ * **Offsets are into the string and are always on a code-point boundary.** JavaScript strings are
+ * UTF-16, so an astral character is two units and a caret between them is a caret inside a
+ * character — which renders as a replacement glyph and deletes as a lone surrogate. Every move and
+ * every delete steps over the pair.
+ *
+ * `anchor` is where a selection started and `caret` is where it is now, so `anchor > caret` is an
+ * ordinary right-to-left selection rather than an error. `selectionRange` is the only thing that
+ * orders them and everything else goes through it.
+ */
+export interface TextModel {
+  text: string;
+  /** Where the caret is, as a UTF-16 offset on a code-point boundary. */
+  caret: number;
+  /** Where the current selection began. Equal to `caret` when nothing is selected. */
+  anchor: number;
+  /**
+   * The range an in-progress composition occupies, or -1 when none is in progress.
+   *
+   * Written only by `applyComposition` in `textHost.ts`. It lives on the model rather than in the
+   * host because the range is a property of the text, and a host that crashed mid-composition
+   * would otherwise leave the field permanently convinced it was still composing.
+   */
+  composeFrom: number;
+  composeTo: number;
+}
+
+export function createTextModel(text = ''): TextModel {
+  return { text, caret: text.length, anchor: text.length, composeFrom: -1, composeTo: -1 };
+}
+
+export function selectionRange(model: TextModel): { from: number; to: number } {
+  return model.anchor <= model.caret
+    ? { from: model.anchor, to: model.caret }
+    : { from: model.caret, to: model.anchor };
+}
+
+export function selectedText(model: TextModel): string {
+  const { from, to } = selectionRange(model);
+  return model.text.slice(from, to);
+}
+
+/** Whether the unit at `at` is the low half of a surrogate pair, so `at` is mid-character. */
+function insidePair(text: string, at: number): boolean {
+  if (at <= 0 || at >= text.length) return false;
+  const low = text.charCodeAt(at);
+  const high = text.charCodeAt(at - 1);
+  return low >= 0xdc00 && low <= 0xdfff && high >= 0xd800 && high <= 0xdbff;
+}
+
+function stepRight(text: string, at: number): number {
+  const next = Math.min(text.length, at + 1);
+  return insidePair(text, next) ? Math.min(text.length, next + 1) : next;
+}
+
+function stepLeft(text: string, at: number): number {
+  const next = Math.max(0, at - 1);
+  return insidePair(text, next) ? Math.max(0, next - 1) : next;
+}
+
+function replaceSelection(model: TextModel, s: string): void {
+  const { from, to } = selectionRange(model);
+  model.text = model.text.slice(0, from) + s + model.text.slice(to);
+  model.caret = from + s.length;
+  model.anchor = model.caret;
+}
+
+export function insertText(model: TextModel, s: string): void {
+  replaceSelection(model, s);
+}
+
+export function deleteBackward(model: TextModel): void {
+  if (model.anchor !== model.caret) {
+    replaceSelection(model, '');
+    return;
+  }
+  const from = stepLeft(model.text, model.caret);
+  model.text = model.text.slice(0, from) + model.text.slice(model.caret);
+  model.caret = from;
+  model.anchor = from;
+}
+
+export function deleteForward(model: TextModel): void {
+  if (model.anchor !== model.caret) {
+    replaceSelection(model, '');
+    return;
+  }
+  const to = stepRight(model.text, model.caret);
+  model.text = model.text.slice(0, model.caret) + model.text.slice(to);
+  model.anchor = model.caret;
+}
+
+export function moveCaret(model: TextModel, delta: number, select: boolean): void {
+  let at = model.caret;
+  const steps = Math.abs(delta);
+  for (let i = 0; i < steps; i += 1) {
+    at = delta > 0 ? stepRight(model.text, at) : stepLeft(model.text, at);
+  }
+  model.caret = at;
+  if (!select) model.anchor = at;
+}
+
+export function moveToLineEdge(model: TextModel, forward: boolean, select: boolean): void {
+  let at: number;
+  if (forward) {
+    const found = model.text.indexOf('\n', model.caret);
+    at = found === -1 ? model.text.length : found;
+  } else {
+    const found = model.text.lastIndexOf('\n', Math.max(0, model.caret - 1));
+    at = found === -1 ? 0 : found + 1;
+  }
+  model.caret = at;
+  if (!select) model.anchor = at;
+}
+
+export function selectAll(model: TextModel): void {
+  model.anchor = 0;
+  model.caret = model.text.length;
+}

package/src/theme.ts

@@ -0,0 +1,57 @@
+/**
+ * Named colours and sizes, so an interface stops repeating its own constants.
+ *
+ * **Flattened at derivation rather than chained at lookup.** A token is read per node per frame, so
+ * a chain of parent themes would be a walk on every one of those reads. Spreading once when a
+ * theme is derived costs a record and makes every lookup a single property access.
+ */
+export interface Theme {
+  readonly values: Readonly<Record<string, number>>;
+}
+
+export function createTheme(values: Record<string, number>): Theme {
+  return { values: { ...values } };
+}
+
+/** A new theme with `overrides` applied over `base`. `base` is not modified. */
+export function deriveTheme(base: Theme, overrides: Record<string, number>): Theme {
+  return { values: { ...base.values, ...overrides } };
+}
+
+export function themeColour(theme: Theme, name: string, fallback: number): number {
+  return theme.values[name] ?? fallback;
+}
+
+export function themeSize(theme: Theme, name: string, fallback: number): number {
+  return theme.values[name] ?? fallback;
+}
+
+/**
+ * A packed `0xRRGGBBAA` token as the four floats a node's `background` and `tint` are.
+ *
+ * **Two of this package's own APIs did not meet**: a theme token is one number and a `UiNode`
+ * colour is a `Float32Array`, so every consumer wrote the same four shifts. The editor found it by
+ * being the first thing to build widgets on both, which is what a consumer outside `packages/` is
+ * for.
+ *
+ * `>>>` rather than `>>`, because a token with red at or above `0x80` has the sign bit set and an
+ * arithmetic shift returns it negative — a red that turns the whole colour into a large negative
+ * number, which is exactly the shape of bug that survives review.
+ */
+export function unpackRgba(packed: number, out: Float32Array): Float32Array {
+  out[0] = ((packed >>> 24) & 0xff) / 255;
+  out[1] = ((packed >>> 16) & 0xff) / 255;
+  out[2] = ((packed >>> 8) & 0xff) / 255;
+  out[3] = (packed & 0xff) / 255;
+  return out;
+}
+
+/** `themeColour` and `unpackRgba` in one call, which is how a widget uses both. */
+export function themeRgba(
+  theme: Theme,
+  name: string,
+  fallback: number,
+  out: Float32Array,
+): Float32Array {
+  return unpackRgba(themeColour(theme, name, fallback), out);
+}

package/src/uiClip.ts

@@ -0,0 +1,69 @@
+/**
+ * How far a node may draw, given the clipping ancestors above it.
+ *
+ * **A rectangle rather than a stack of them.** Successive clips intersect, and the intersection of
+ * any number of rectangles is one rectangle, so the whole history above a node collapses into four
+ * numbers. That is what makes this cheap enough to compute per node per frame rather than
+ * maintained as state that can go stale.
+ *
+ * **An empty result is reported, not encoded.** A node clipped entirely away would otherwise
+ * produce a negative width, which every consumer would then have to remember to check; instead
+ * `clipRectFor` returns false and the caller skips the subtree. The rectangle it leaves behind is
+ * degenerate but never negative, because a negative size reaching a scissor call is a validation
+ * error on one backend and a silent full-screen draw on the other.
+ *
+ * **A clipping node does not clip itself.** It bounds its descendants; cutting it to its own
+ * rectangle is a no-op in the ordinary case and wrong in the case where a caller has given it a
+ * border that draws outside its content box.
+ */
+import type { UiNode, UiRect } from './uiNode.ts';
+
+/** Write the overlap of two rectangles into `out`. Never negative; see the header. */
+export function intersectClip(out: UiRect, parent: UiRect, child: UiRect): void {
+  const left = Math.max(parent.x, child.x);
+  const top = Math.max(parent.y, child.y);
+  const right = Math.min(parent.x + parent.w, child.x + child.w);
+  const bottom = Math.min(parent.y + parent.h, child.y + child.h);
+  out.x = left;
+  out.y = top;
+  out.w = Math.max(0, right - left);
+  out.h = Math.max(0, bottom - top);
+}
+
+/* Reused across calls: this runs per node per frame and the chain is its only allocation. */
+const CHAIN: UiNode[] = [];
+
+/**
+ * The rectangle `node` may draw into, cut by every clipping ancestor between it and `root`.
+ *
+ * Returns false when nothing of it survives, which is the caller's signal to skip the subtree
+ * rather than issue a draw that covers no pixels.
+ */
+export function clipRectFor(root: UiNode, node: UiNode, out: UiRect): boolean {
+  out.x = node.rect.x;
+  out.y = node.rect.y;
+  out.w = node.rect.w;
+  out.h = node.rect.h;
+
+  /*
+   * Collected on the way up and applied on the way down, because the intersection has to run
+   * outermost-first: an inner clip can only narrow an outer one, so the wrong order happens to be
+   * right for nested rectangles and is wrong for offset ones.
+   */
+  let depth = 0;
+  let walk: UiNode | null = node.parent;
+  while (walk !== null) {
+    CHAIN[depth] = walk;
+    depth += 1;
+    if (walk === root) break;
+    walk = walk.parent;
+  }
+
+  for (let i = depth - 1; i >= 0; i -= 1) {
+    const ancestor = CHAIN[i] as UiNode;
+    if (!ancestor.clip) continue;
+    intersectClip(out, ancestor.rect, out);
+  }
+
+  return out.w > 0 && out.h > 0;
+}

package/src/uiDirty.ts

@@ -0,0 +1,164 @@
+/**
+ * What changed since last frame, and therefore what has to be redrawn.
+ *
+ * An editor is idle most of the time. A framework that redraws the whole window every frame
+ * because a caret is blinking keeps a laptop fan running, which is the difference between a tool
+ * somebody uses all day and one they close.
+ *
+ * **A node that became hidden marks where it used to be.** That is the bug every dirty-rectangle
+ * implementation ships with first: the thing that disappeared leaves its pixels behind, because
+ * nothing thought to dirty a rectangle belonging to a node that is no longer drawn.
+ *
+ * **Keyed by traversal index, with the node identity checked.** A tree that changed shape makes
+ * every index past the change compare against a different node, which reports dirty — conservative
+ * and correct. A map keyed by node would be exact and would allocate on the frame path.
+ *
+ * **One union rather than a list of rectangles.** A union over-draws and is right; a list needs
+ * merging logic that is itself a source of defects, and an editor's redraws are overwhelmingly one
+ * panel anyway.
+ */
+import type { UiNode, UiRect } from './uiNode.ts';
+
+export interface DirtyTracker {
+  /** The node seen at each traversal index last frame. */
+  nodes: (UiNode | null)[];
+  /** Six numbers per index: x, y, w, h, and the visual state packed into two. */
+  state: Float64Array;
+  /** How many indices the previous walk filled. */
+  count: number;
+  /** The union of everything marked this frame, and whether anything was. */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  any: boolean;
+}
+
+const STRIDE = 6;
+
+export function createDirtyTracker(capacity: number): DirtyTracker {
+  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: DirtyTracker): void {
+  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: DirtyTracker, rect: UiRect): void {
+  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: DirtyTracker, out: UiRect): boolean {
+  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: UiNode): number {
+  return (
+    (node.hidden ? 1 : 0) |
+    (node.hovered ? 2 : 0) |
+    (node.pressed ? 4 : 0) |
+    ((node.texture + 1) * 8)
+  );
+}
+
+const SCRATCH: UiRect = { x: 0, y: 0, w: 0, h: 0 };
+
+function visit(tracker: DirtyTracker, node: UiNode, at: number): number {
+  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: DirtyTracker, root: UiNode): boolean {
+  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;
+}