@driftengine/tools 4.0.0 → 4.1.1

package/dist/profiler.d.ts

@@ -1,5 +1,5 @@
 import type { UiNode } from '@driftengine/ui2d';
-import { type PassTimings } from '@driftengine/core';
+import { type GpuSample, type PassTimings } from '@driftengine/core';
 import { type ResidencyTable } from '@driftengine/texture';
 import { type Panel } from './panel.ts';
 export interface ProfilerRow {
@@ -54,3 +54,31 @@ export declare function createProfilerView(options: {
     rowHeight?: number;
 }): ProfilerView;
 export declare const profilerPanel: Panel<ProfilerWorld, ProfilerView>;
+/**
+ * A `PassTimings` labelled with the engine's own GPU brackets.
+ *
+ * **The engine fills no timings for anybody.** `PassTimings` is a container and
+ * `RendererApi.gpuTimer` is a source, and joining the two is the same twenty lines wherever it is
+ * written — the slots are `GPU_SLOTS` and never the game's, because a second backend measuring the
+ * same frame owes the same three numbers. So it is written here once rather than in every consumer
+ * that wants a frame readout, which is the argument that put the overlay in this package.
+ *
+ * Labelled and unsampled, so every row shows `—` until a frame resolves. That is the distinction
+ * `profilerRows` exists to keep: a bracket nothing has measured yet is not a bracket that ran in no
+ * time.
+ */
+export declare function createGpuPassTimings(): PassTimings;
+/**
+ * Write one resolved sample over the three rows.
+ *
+ * **It resets first, and the first draft did not.** `recordPassSample` accumulates on purpose,
+ * because a pass may be sampled several times in one frame — a shadow pass runs per cascade — and
+ * the row a reader wants is what that pass cost altogether. A `GpuSample` is the opposite: it is
+ * one resolved frame's three totals, already summed by the timer. Adding it to what was there left
+ * the rows climbing forever, which reads as a leak in whatever the game last changed rather than as
+ * a defect in the readout. `resetPassTimings` is how the engine's own frame starts, and the labels
+ * survive it, which is why the rows do not flicker.
+ *
+ * A caller wanting an average across frames has `FrameHistory` for it.
+ */
+export declare function recordGpuSample(timings: PassTimings, sample: GpuSample): void;

package/dist/profiler.js

@@ -16,7 +16,7 @@
  * a frame it was making worse.
  */
 import { addUiChild, createUiNode } from '@driftengine/ui2d';
-import { passLabel, passMs } from '@driftengine/core';
+import { GPU_SLOTS, createPassTimings, passLabel, passMs, recordPassLabel, recordPassSample, resetPassTimings, } from '@driftengine/core';
 import { residentCount } from '@driftengine/texture';
 import { createPanelRoot, emptyPanel } from './panel.js';
 /** `—` for unmeasured. Two decimals, because a pass under a hundredth is not the one to look at. */
@@ -140,3 +140,42 @@ export const profilerPanel = {
         return null;
     },
 };
+/**
+ * A `PassTimings` labelled with the engine's own GPU brackets.
+ *
+ * **The engine fills no timings for anybody.** `PassTimings` is a container and
+ * `RendererApi.gpuTimer` is a source, and joining the two is the same twenty lines wherever it is
+ * written — the slots are `GPU_SLOTS` and never the game's, because a second backend measuring the
+ * same frame owes the same three numbers. So it is written here once rather than in every consumer
+ * that wants a frame readout, which is the argument that put the overlay in this package.
+ *
+ * Labelled and unsampled, so every row shows `—` until a frame resolves. That is the distinction
+ * `profilerRows` exists to keep: a bracket nothing has measured yet is not a bracket that ran in no
+ * time.
+ */
+export function createGpuPassTimings() {
+    const timings = createPassTimings(GPU_SLOTS.length);
+    for (let slot = 0; slot < GPU_SLOTS.length; slot += 1) {
+        recordPassLabel(timings, slot, GPU_SLOTS[slot] ?? '');
+    }
+    return timings;
+}
+/**
+ * Write one resolved sample over the three rows.
+ *
+ * **It resets first, and the first draft did not.** `recordPassSample` accumulates on purpose,
+ * because a pass may be sampled several times in one frame — a shadow pass runs per cascade — and
+ * the row a reader wants is what that pass cost altogether. A `GpuSample` is the opposite: it is
+ * one resolved frame's three totals, already summed by the timer. Adding it to what was there left
+ * the rows climbing forever, which reads as a leak in whatever the game last changed rather than as
+ * a defect in the readout. `resetPassTimings` is how the engine's own frame starts, and the labels
+ * survive it, which is why the rows do not flicker.
+ *
+ * A caller wanting an average across frames has `FrameHistory` for it.
+ */
+export function recordGpuSample(timings, sample) {
+    resetPassTimings(timings);
+    recordPassSample(timings, 0, sample.shadows);
+    recordPassSample(timings, 1, sample.reflection);
+    recordPassSample(timings, 2, sample.rest);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/tools",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "The editor panels a shipped game can carry, and the command stack that makes their edits undoable",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,11 +27,11 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "4.0.0",
-    "@driftengine/editor": "4.0.0",
-    "@driftengine/network": "4.0.0",
-    "@driftengine/texture": "4.0.0",
-    "@driftengine/ui2d": "4.0.0"
+    "@driftengine/core": "4.1.1",
+    "@driftengine/editor": "4.1.1",
+    "@driftengine/network": "4.1.1",
+    "@driftengine/texture": "4.1.1",
+    "@driftengine/ui2d": "4.1.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/index.ts

@@ -58,10 +58,12 @@ export type {
   InspectorWorld,
   RowKind,
 } from './inspector.ts';
+export type { EntityWorldLike, InspectableComponentType } from './inspector.ts';
 export {
   MIXED,
   addComponentCommand,
   createInspectorView,
+  entitiesInspectable,
   fieldEditable,
   inspectorPanel,
   inspectorRows,
@@ -95,6 +97,7 @@ export {
 export type { FrameHistory, ProfilerRow, ProfilerView, ProfilerWorld } from './profiler.ts';
 export {
   createFrameHistory,
+  createGpuPassTimings,
   createProfilerView,
   formatMs,
   historyValues,
@@ -102,14 +105,41 @@ export {
   profilerPanel,
   profilerRows,
   pushFrame,
+  recordGpuSample,
 } from './profiler.ts';
 
 export type { NetworkReadout, NetworkView, NetworkWorld, RollbackHistory } from './network.ts';
+export type { SessionLike, SessionRecorder } from './network.ts';
 export {
   componentDivergence,
   createNetworkView,
   createRollbackHistory,
+  createSessionRecorder,
   networkPanel,
+  observeSession,
   pushRollback,
   rollbackValues,
+  sessionReadout,
 } from './network.ts';
+
+/*
+ * What mounts the four panels over a running game, on a key.
+ *
+ * **The panels shipped in 4.0.0 with nothing to show them**, which is the gap this closes: every
+ * panel above builds a `UiNode` tree and stops there, and the dock, layout, painting and routing
+ * that turn a tree into something a person sees lived only in the editor application, which is
+ * private. A consumer wanting an in-game inspector had to write that half again, and the six
+ * writing it six times is the drift `AGENTS.md` opens by describing.
+ *
+ * `OverlayPainter` is four calls, so a host with a 2D context, a host drawing through a sprite
+ * pass and a host with no screen at all each satisfy it — which is the platform rule applied to
+ * drawing, and what keeps this testable with no graphics device anywhere near it.
+ */
+export type {
+  OverlayPainter,
+  OverlaySite,
+  PanelBinding,
+  ToolsOverlay,
+  ToolsOverlayOptions,
+} from './overlay.ts';
+export { bindPanel, createToolsOverlay, paintOverlay } from './overlay.ts';

package/src/inspector.ts

@@ -348,3 +348,80 @@ export const inspectorPanel: Panel<InspectorWorld, InspectorView> = {
     return null;
   },
 };
+
+/**
+ * The shape of a component type, as this package needs it.
+ *
+ * **Structural rather than imported.** `@driftengine/entities`' `ComponentType` satisfies it, and
+ * so does anything else a consumer describes its state with — which is the arrangement
+ * `@driftengine/drft` already has with `@driftengine/texture`'s DTEX types across a boundary the
+ * one package must not depend across. This package gains no dependency for the adapter below, so
+ * the release's place count does not move.
+ */
+export interface InspectableComponentType {
+  readonly name: string;
+  readonly schema: { readonly fields: readonly { readonly name: string; readonly type: string }[] };
+}
+
+/** The five methods the adapter forwards to. `World` has all of them. */
+export interface EntityWorldLike<T> {
+  has(entity: number, type: T): boolean;
+  add(entity: number, type: T): void;
+  remove(entity: number, type: T): boolean;
+  read(entity: number, type: T, field: string): unknown;
+  write(entity: number, type: T, field: string, value: unknown): void;
+}
+
+/**
+ * An entity world, as something the inspector can read and edit.
+ *
+ * **Written once here because every consumer with a world was about to write it.** The inspector
+ * addresses a component by name, since a name is what a row carries; a world addresses it by the
+ * type object, since that is what indexes its stores. Bridging the two is seven forwarding methods
+ * and a lookup, identical wherever it is written.
+ *
+ * **A name with no type behind it does nothing rather than guessing.** A row built against a stale
+ * schema would otherwise write a field into a component the world does not have and report
+ * success, which is a silent loss of the edit a person just made and watched apply.
+ *
+ * `componentsOf` answers in the order the types were given, so a panel's rows do not reorder
+ * between frames.
+ */
+export function entitiesInspectable<T extends InspectableComponentType>(
+  world: EntityWorldLike<T>,
+  types: readonly T[],
+): InspectableWorld {
+  const byName = new Map<string, T>();
+  for (const type of types) byName.set(type.name, type);
+
+  return {
+    componentsOf(entity: number): readonly string[] {
+      const out: string[] = [];
+      for (const type of types) if (world.has(entity, type)) out.push(type.name);
+      return out;
+    },
+    schemaOf(component: string): readonly { readonly name: string; readonly type: string }[] {
+      return byName.get(component)?.schema.fields ?? [];
+    },
+    read(entity: number, component: string, field: string): unknown {
+      const type = byName.get(component);
+      return type === undefined ? undefined : world.read(entity, type, field);
+    },
+    write(entity: number, component: string, field: string, value: unknown): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.write(entity, type, field, value);
+    },
+    hasComponent(entity: number, component: string): boolean {
+      const type = byName.get(component);
+      return type !== undefined && world.has(entity, type);
+    },
+    addComponent(entity: number, component: string): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.add(entity, type);
+    },
+    removeComponent(entity: number, component: string): void {
+      const type = byName.get(component);
+      if (type !== undefined) world.remove(entity, type);
+    },
+  };
+}

package/src/network.ts

@@ -183,3 +183,71 @@ export const networkPanel: Panel<NetworkWorld, NetworkView> = {
     return null;
   },
 };
+
+/**
+ * A session, as this package needs it.
+ *
+ * Structural rather than imported, so nothing here loads `@driftengine/network` at run time and a
+ * consumer whose session is its own shape can still be read.
+ */
+export interface SessionLike {
+  readonly participants: number;
+  readonly inputDelay: number;
+  /** The disagreement the session is currently holding, or null. Latched, not an event. */
+  readonly desync: Desync | null;
+  readonly loop: { readonly depth: number };
+}
+
+/** What a recorder keeps: the disagreements it has seen, oldest first. */
+export interface SessionRecorder {
+  readonly desyncs: Desync[];
+  readonly limit: number;
+}
+
+export function createSessionRecorder(limit = 32): SessionRecorder {
+  return { desyncs: [], limit: Math.max(1, limit) };
+}
+
+/**
+ * Watch a session for one frame.
+ *
+ * **`desync` is latched rather than an event**, which is the whole reason this is not one line at
+ * the call site. A session keeps answering with the same disagreement on every frame until the
+ * next one arrives, so appending what it reads turns one divergence into sixty a second and buries
+ * the tick somebody is looking for under copies of itself. A disagreement is new when its tick and
+ * peer differ from the last one kept.
+ *
+ * Bounded, because a session that desyncs every tick would otherwise grow an array forever behind
+ * a panel nobody has open.
+ */
+export function observeSession(recorder: SessionRecorder, session: SessionLike): void {
+  const seen = session.desync;
+  if (seen === null) return;
+  const last = recorder.desyncs[recorder.desyncs.length - 1];
+  if (last !== undefined && last.tick === seen.tick && last.peer === seen.peer) return;
+  recorder.desyncs.push(seen);
+  if (recorder.desyncs.length > recorder.limit) recorder.desyncs.shift();
+}
+
+/**
+ * The session and what has been seen of it, as the panel's readout.
+ *
+ * **`snapshotBytes` is the caller's, because the engine cannot know it.** `RewindLoop` is generic
+ * over the state it snapshots, so its depth is knowable here and the size of one is not. A caller
+ * passing zero is saying it has not measured, which the panel renders as such.
+ */
+export function sessionReadout(
+  session: SessionLike,
+  recorder: SessionRecorder,
+  snapshotBytes: number,
+  componentHashes: NetworkReadout['componentHashes'] = null,
+): NetworkReadout {
+  return {
+    inputDelay: session.inputDelay,
+    participants: session.participants,
+    snapshotBytes,
+    snapshotCount: session.loop.depth,
+    desyncs: recorder.desyncs,
+    componentHashes,
+  };
+}

package/src/overlay.ts

@@ -0,0 +1,342 @@
+/**
+ * The panels, on a key, over a running game.
+ *
+ * **The panels shipped without anything to mount them, and that was the gap.** `@driftengine/tools`
+ * exported an inspector, a console, a profiler and a network panel, each of which builds a `UiNode`
+ * tree and nothing more. What turned a tree into something a person could see lived in the editor
+ * application — a dock, a layout, a painter and the event routing — and that workspace is private
+ * and ships to nobody. So every consumer wanting an in-game inspector had to write that half again,
+ * and six of them writing it six times is the drift `AGENTS.md` opens by describing.
+ *
+ * **A column, not a dock.** The editor's dock splits, drags and persists because somebody arranges
+ * an editor and then keeps that arrangement. Nobody arranges a debug overlay: they press a key,
+ * read a number and press it again. So the panels stack down one edge in the order they were
+ * given, and what a dock would have bought is not bought.
+ *
+ * **The painter is supplied, never reached for.** Four calls — a rectangle, a line of text, a clip
+ * and its close — which is every operation `paintOverlay` makes. A host with a 2D context
+ * implements them in four lines, a host drawing through `@driftengine/ui2d`'s sprite pass
+ * implements them over a batch, and a host with no screen at all implements them into an array,
+ * which is what this module's own tests do. That is `AGENTS.md`'s platform rule applied to
+ * drawing: take the capability as a parameter, and let the consumer decide what it is.
+ *
+ * **Nothing here needs a graphics device**, which is the property that makes the whole of it
+ * testable. The geometry is arithmetic over a tree, the routing is arithmetic over rectangles, and
+ * the drawing is somebody else's four functions. An overlay that could only run against a live
+ * adapter is an overlay whose behaviour nobody can assert.
+ *
+ * **Hidden costs a frame nothing.** While it is closed, `frame` returns before it builds anything
+ * and `route` refuses every event but the one that opens it, so a game that never presses the key
+ * pays for a boolean.
+ */
+import { createUiNode, layoutUiTree } from '@driftengine/ui2d';
+import type { UiNode } from '@driftengine/ui2d';
+import { createUndoStack, type Command, type UndoStack } from './command.ts';
+import { createPanelRoot, type Panel, type UiEvent } from './panel.ts';
+
+/**
+ * A panel with its world and its view already attached.
+ *
+ * **The generics are closed here rather than carried by the host.** `Panel<W, V>` is two type
+ * parameters per panel, and a host holding several at once cannot express them in one list without
+ * erasing to `unknown` and casting on the way out. Binding closes them where both types are known
+ * and hands back something with no parameters at all, so the host never casts and the panel keeps
+ * the signature that makes its own rules checkable.
+ */
+export interface PanelBinding {
+  readonly id: string;
+  readonly title: string;
+  build(root: UiNode): void;
+  route(event: UiEvent): Command | null;
+}
+
+export function bindPanel<W, V>(
+  panel: Panel<W, V>,
+  world: () => Readonly<W>,
+  view: V,
+): PanelBinding {
+  return {
+    id: panel.id,
+    title: panel.title,
+    build: (root: UiNode): void => panel.build(world(), view, root),
+    route: (event: UiEvent): Command | null => panel.route(world(), view, event),
+  };
+}
+
+/** Where one panel came out. Read rather than recomputed, so a hit test cannot disagree with a draw. */
+export interface OverlaySite {
+  readonly id: string;
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+/** What a host draws with. Colours are CSS, `#rrggbb` or `#rrggbbaa`. */
+export interface OverlayPainter {
+  rect(x: number, y: number, w: number, h: number, colour: string): void;
+  /** Text on a baseline at `y`, twelve pixels tall. */
+  text(content: string, x: number, y: number, colour: string): void;
+  clip(x: number, y: number, w: number, h: number): void;
+  unclip(): void;
+}
+
+export interface ToolsOverlayOptions {
+  readonly panels: readonly PanelBinding[];
+  /** `KeyboardEvent.key` of the key that opens and closes it. Defaults to `F3`. */
+  readonly key?: string;
+  readonly side?: 'left' | 'right';
+  readonly width?: number;
+  readonly undoLimit?: number;
+  readonly visible?: boolean;
+}
+
+export interface ToolsOverlay {
+  /** The tree the whole overlay is in. One absolutely placed child per panel. */
+  readonly root: UiNode;
+  readonly undo: UndoStack;
+  readonly visible: boolean;
+  /** How many times the tree has been rebuilt and laid out. Read by tests, and by nothing else. */
+  readonly layoutCount: number;
+  sites(): readonly OverlaySite[];
+  setVisible(visible: boolean): void;
+  toggle(): void;
+  resize(width: number, height: number): void;
+  frame(now: number): void;
+  /** Deliver one event. True where the overlay took it, so a host knows not to pass it on. */
+  route(event: UiEvent): boolean;
+  /** Say the world changed, so the next frame rebuilds. A profiler calls this every frame. */
+  invalidate(): void;
+  dispose(): void;
+}
+
+const DEFAULT_WIDTH = 320;
+const DEFAULT_KEY = 'F3';
+
+export function createToolsOverlay(options: ToolsOverlayOptions): ToolsOverlay {
+  const root = createUiNode({ name: 'tools-overlay', width: 'grow', height: 'grow' });
+  const undo = createUndoStack(options.undoLimit ?? 100);
+  const key = options.key ?? DEFAULT_KEY;
+  const side = options.side ?? 'right';
+  const columnWidth = options.width ?? DEFAULT_WIDTH;
+
+  const panels = options.panels;
+  const roots = new Map<string, UiNode>();
+  /* Pooled and refilled: this is read every frame the overlay is open and must not allocate. */
+  const sites: OverlaySite[] = [];
+
+  let width = 0;
+  let height = 0;
+  let visible = options.visible ?? false;
+  let dirty = true;
+  let disposed = false;
+  let layoutCount = 0;
+  let focused: string | null = null;
+
+  const relayout = (): void => {
+    const x = side === 'left' ? 0 : Math.max(0, width - columnWidth);
+    const w = Math.min(columnWidth, width);
+    const each = panels.length === 0 ? 0 : Math.floor(height / panels.length);
+
+    root.absolute = true;
+    root.x = x;
+    root.y = 0;
+    root.width = w;
+    root.height = height;
+    root.children.length = 0;
+    sites.length = 0;
+
+    for (let at = 0; at < panels.length; at += 1) {
+      const panel = panels[at];
+      if (panel === undefined) continue;
+      /* The last panel takes the remainder, so a height that does not divide leaves no gap. */
+      const top = each * at;
+      const tall = at === panels.length - 1 ? height - top : each;
+
+      let panelRoot = roots.get(panel.id);
+      if (panelRoot === undefined) {
+        panelRoot = createPanelRoot(panel);
+        roots.set(panel.id, panelRoot);
+      }
+      panelRoot.absolute = true;
+      panelRoot.x = 0;
+      panelRoot.y = top;
+      panelRoot.width = w;
+      panelRoot.height = tall;
+      panel.build(panelRoot);
+      root.children.push(panelRoot);
+      sites.push({ id: panel.id, x: 0, y: top, w, h: tall });
+    }
+
+    layoutUiTree(root, x, 0, w, height);
+    layoutCount += 1;
+    dirty = false;
+  };
+
+  return {
+    root,
+    undo,
+    get visible(): boolean {
+      return visible;
+    },
+    get layoutCount(): number {
+      return layoutCount;
+    },
+
+    sites(): readonly OverlaySite[] {
+      if (visible && dirty) relayout();
+      return sites;
+    },
+
+    setVisible(next: boolean): void {
+      if (disposed || next === visible) return;
+      visible = next;
+      dirty = true;
+    },
+
+    toggle(): void {
+      this.setVisible(!visible);
+    },
+
+    resize(next: number, nextHeight: number): void {
+      if (disposed) return;
+      if (next === width && nextHeight === height) return;
+      width = next;
+      height = nextHeight;
+      dirty = true;
+    },
+
+    frame(_now: number): void {
+      if (disposed || !visible) return;
+      if (dirty) relayout();
+    },
+
+    route(event: UiEvent): boolean {
+      if (disposed) return false;
+      /*
+       * The key is answered whether the overlay is open or closed, and it is the only thing that
+       * is. A host that had to know which state it was in to decide whether to forward a press
+       * would be holding the same boolean twice.
+       */
+      if (event.kind === 'key' && event.key === key && !event.ctrl) {
+        visible = !visible;
+        dirty = true;
+        return true;
+      }
+      if (!visible) return false;
+
+      if (event.kind === 'key') {
+        if (event.ctrl && event.key === 'z') {
+          const moved = event.shift ? undo.redo() : undo.undo();
+          if (moved) dirty = true;
+          return moved;
+        }
+        if (event.ctrl && event.key === 'y') {
+          const moved = undo.redo();
+          if (moved) dirty = true;
+          return moved;
+        }
+        const target = panelWith(focused);
+        return target === null ? false : take(target.route(event));
+      }
+
+      if (dirty) relayout();
+      const site = siteAt(event.x, event.y);
+      if (site === null) return false;
+      if (event.kind === 'pointer' && event.phase === 'down') focused = site.id;
+      const panel = panelWith(site.id);
+      if (panel === null) return false;
+      /* In the panel's own space: a panel never learns where on screen it is. */
+      return take(panel.route(shift(event, -(root.rect.x + site.x), -site.y)));
+    },
+
+    invalidate(): void {
+      dirty = true;
+    },
+
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      visible = false;
+      undo.clear();
+      root.children.length = 0;
+      roots.clear();
+      sites.length = 0;
+      focused = null;
+    },
+  };
+
+  function panelWith(id: string | null): PanelBinding | null {
+    if (id === null) return null;
+    for (const panel of panels) if (panel.id === id) return panel;
+    return null;
+  }
+
+  function siteAt(x: number, y: number): OverlaySite | null {
+    const localX = x - root.rect.x;
+    if (localX < 0 || localX >= root.rect.w) return null;
+    for (const site of sites) {
+      if (y >= site.y && y < site.y + site.h) return site;
+    }
+    return null;
+  }
+
+  /*
+   * **`push` applies, so this must not.** `createUndoStack.push` calls `apply` on the way in — and
+   * on the merge path it says in so many words that an absorbed command has already been applied
+   * and must not be applied again. Applying here as well ran every panel edit twice, which the
+   * row panel's test saw as two rows added by one press and a real inspector would have shown as a
+   * field moved twice as far as the pointer.
+   */
+  function take(command: Command | null): boolean {
+    if (command === null) return false;
+    undo.push(command);
+    dirty = true;
+    return true;
+  }
+}
+
+/** The same event moved by a vector. Returns the event itself where there is nothing to move. */
+function shift(event: UiEvent, dx: number, dy: number): UiEvent {
+  if (event.kind === 'pointer' || event.kind === 'wheel') {
+    return { ...event, x: event.x + dx, y: event.y + dy };
+  }
+  return event;
+}
+
+/**
+ * Draw the overlay, or draw nothing because it is closed.
+ *
+ * A free function rather than a method, so the overlay itself never holds a painter and a host may
+ * draw the same overlay into two surfaces — a screen and a capture — without either knowing.
+ */
+export function paintOverlay(painter: OverlayPainter, overlay: ToolsOverlay): void {
+  if (!overlay.visible) return;
+  paintNode(painter, overlay.root);
+}
+
+/** Where a twelve-pixel line sits inside a row. Rows here are sixteen to eighteen pixels tall. */
+const TEXT_BASELINE = 12;
+
+function paintNode(painter: OverlayPainter, node: UiNode): void {
+  if (node.hidden) return;
+  const { x, y, w, h } = node.rect;
+  if (node.background !== null) painter.rect(x, y, w, h, cssColour(node.background));
+  if (node.text.length > 0) {
+    painter.text(node.text, x, y + TEXT_BASELINE, cssColour(node.tint));
+  }
+  if (node.children.length === 0) return;
+  if (node.clip) painter.clip(x, y, w, h);
+  for (const child of node.children) paintNode(painter, child);
+  if (node.clip) painter.unclip();
+}
+
+function cssColour(rgba: Float32Array | null): string {
+  if (rgba === null) return '#ffffff';
+  let out = '#';
+  for (let at = 0; at < 3; at += 1) {
+    const channel = Math.round(Math.min(1, Math.max(0, rgba[at] ?? 0)) * 255);
+    out += channel.toString(16).padStart(2, '0');
+  }
+  return out;
+}