@driftengine/tools 4.0.0 → 4.1.1

package/README.md

@@ -1,9 +1,10 @@
 # `@driftengine/tools`
 
 The editor's panels, as something a shipped game can carry: an inspector, a console, a profiler and
-a network panel, with the command stack that makes their edits undoable.
+a network panel, with the command stack that makes their edits undoable, and the overlay that puts
+them on screen on a key.
 
-**3,395 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
+**5,391 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
 `scripts/fixtures/size/tools-only.ts`. Optional — nothing in `@driftengine/core` imports it, so a
 game that never asks for these pays nothing.
 
@@ -37,6 +38,67 @@ const command = inspectorPanel.route(world, view, event);
 if (command !== null) undo.push(command);
 ```
 
+## The overlay, because a panel that nothing mounts is a tree nobody sees
+
+Every panel above builds a `UiNode` tree and stops there. For 4.0.0 the half that turns a tree into
+something a person can look at — geometry, event routing, painting — lived only in the editor
+application, which is private and ships to nobody, so a game wanting an in-game inspector had to
+write it again. `createToolsOverlay` is that half.
+
+A **column rather than a dock**: 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 are given.
+
+The **painter is supplied**. Four calls — a rectangle, a line of text, a clip and its close — which
+is every operation the overlay makes. A host with a 2D context writes four lines; a host drawing
+through `@driftengine/ui2d` writes them over a sprite batch; a host with no screen writes them into
+an array, which is what this package's own tests do. Nothing here needs a graphics device, which is
+what makes the whole of it assertable.
+
+```ts
+import { bindPanel, createToolsOverlay, paintOverlay, profilerPanel } from '@driftengine/tools';
+
+const overlay = createToolsOverlay({
+  panels: [bindPanel(profilerPanel, () => profilerWorld, profilerView)],
+  key: 'F3',
+});
+
+// once, and whenever the surface changes size
+overlay.resize(canvas.width, canvas.height);
+
+// every frame, after the scene
+overlay.invalidate();
+overlay.frame(now);
+paintOverlay(painter, overlay);
+
+// wherever input arrives; true means the overlay took it and the game should not
+if (overlay.route(keyEvent(event.key, event.shiftKey, event.ctrlKey))) event.preventDefault();
+```
+
+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.
+
+## Two adapters, because every consumer was about to write the same ones
+
+A panel needs its world in the shape the panel reads. Two of those shapes are the same in every
+game that has the thing behind them, so they are here rather than in each of them.
+
+`entitiesInspectable(world, types)` turns an entity world into an `InspectableWorld`: the inspector
+addresses a component by name because that is what a row carries, and a world addresses it by the
+type object because that is what indexes its stores. A name with no type behind it does nothing
+rather than guessing, so a row built from a stale schema cannot write a field into a component the
+world does not have and report success.
+
+`createSessionRecorder` plus `observeSession` and `sessionReadout` turn a lockstep session into a
+`NetworkReadout`. The watching is the part worth having written once: `session.desync` is **latched
+rather than an event**, so it keeps answering with the same disagreement every frame until the next
+one arrives, and a recorder that appended what it read would turn one divergence into sixty a
+second. `snapshotBytes` is the caller's, because `RewindLoop` is generic over the state it
+snapshots and cannot know the size of one.
+
+**Both are typed structurally**, the way `@driftengine/drft` takes DTEX types that
+`@driftengine/texture` satisfies, so this package depends on nothing new and anything shaped right
+can be read — including a consumer whose state is not an entity world at all.
+
 ## Building it in or leaving it out
 
 Import it and it is in the bundle; do not and it is not. There is no flag, because a flag would be a

package/dist/index.d.ts

@@ -25,10 +25,14 @@ export type { Selection } from './selection.ts';
 export { addToSelection, clearSelection, createSelection, isSelected, primarySelection, selectOnly, selectRange, selectedEntities, toggleSelection, } from './selection.ts';
 export { divergenceIsUnaccounted, divergentComponents } from './divergence.ts';
 export type { InspectableWorld, InspectorRow, InspectorView, InspectorWorld, RowKind, } from './inspector.ts';
-export { MIXED, addComponentCommand, createInspectorView, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.ts';
+export type { EntityWorldLike, InspectableComponentType } from './inspector.ts';
+export { MIXED, addComponentCommand, createInspectorView, entitiesInspectable, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.ts';
 export type { ConsoleView, ConsoleWorld, LogEntry, LogFilter, LogRing, Severity, SourceCursor, } from './console.ts';
 export { DISPLAY_LIMIT, appendLog, consolePanel, createConsoleView, createLogFilter, createLogRing, displayText, filteredEntries, jumpToSourceCommand, logEntries, } from './console.ts';
 export type { FrameHistory, ProfilerRow, ProfilerView, ProfilerWorld } from './profiler.ts';
-export { createFrameHistory, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, } from './profiler.ts';
+export { createFrameHistory, createGpuPassTimings, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, recordGpuSample, } from './profiler.ts';
 export type { NetworkReadout, NetworkView, NetworkWorld, RollbackHistory } from './network.ts';
-export { componentDivergence, createNetworkView, createRollbackHistory, networkPanel, pushRollback, rollbackValues, } from './network.ts';
+export type { SessionLike, SessionRecorder } from './network.ts';
+export { componentDivergence, createNetworkView, createRollbackHistory, createSessionRecorder, networkPanel, observeSession, pushRollback, rollbackValues, sessionReadout, } from './network.ts';
+export type { OverlayPainter, OverlaySite, PanelBinding, ToolsOverlay, ToolsOverlayOptions, } from './overlay.ts';
+export { bindPanel, createToolsOverlay, paintOverlay } from './overlay.ts';

package/dist/index.js

@@ -3,7 +3,8 @@ export { createUndoStack } from './command.js';
 export { PANEL_PREFIX, createPanelRoot, emptyPanel, keyEvent, panelIdOf, pointerEvent, treeShape, wheelEvent, } from './panel.js';
 export { addToSelection, clearSelection, createSelection, isSelected, primarySelection, selectOnly, selectRange, selectedEntities, toggleSelection, } from './selection.js';
 export { divergenceIsUnaccounted, divergentComponents } from './divergence.js';
-export { MIXED, addComponentCommand, createInspectorView, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.js';
+export { MIXED, addComponentCommand, createInspectorView, entitiesInspectable, fieldEditable, inspectorPanel, inspectorRows, removeComponentCommand, rowText, setFieldCommand, } from './inspector.js';
 export { DISPLAY_LIMIT, appendLog, consolePanel, createConsoleView, createLogFilter, createLogRing, displayText, filteredEntries, jumpToSourceCommand, logEntries, } from './console.js';
-export { createFrameHistory, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, } from './profiler.js';
-export { componentDivergence, createNetworkView, createRollbackHistory, networkPanel, pushRollback, rollbackValues, } from './network.js';
+export { createFrameHistory, createGpuPassTimings, createProfilerView, formatMs, historyValues, occupancy, profilerPanel, profilerRows, pushFrame, recordGpuSample, } from './profiler.js';
+export { componentDivergence, createNetworkView, createRollbackHistory, createSessionRecorder, networkPanel, observeSession, pushRollback, rollbackValues, sessionReadout, } from './network.js';
+export { bindPanel, createToolsOverlay, paintOverlay } from './overlay.js';

package/dist/inspector.d.ts

@@ -84,3 +84,45 @@ export declare function createInspectorView(options: {
 /** What a row shows to the right of its label. `—` is the mark for a disagreement. */
 export declare function rowText(row: InspectorRow): string;
 export declare const inspectorPanel: Panel<InspectorWorld, InspectorView>;
+/**
+ * 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 declare function entitiesInspectable<T extends InspectableComponentType>(world: EntityWorldLike<T>, types: readonly T[]): InspectableWorld;

package/dist/inspector.js

@@ -263,3 +263,58 @@ export const inspectorPanel = {
         return null;
     },
 };
+/**
+ * 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(world, types) {
+    const byName = new Map();
+    for (const type of types)
+        byName.set(type.name, type);
+    return {
+        componentsOf(entity) {
+            const out = [];
+            for (const type of types)
+                if (world.has(entity, type))
+                    out.push(type.name);
+            return out;
+        },
+        schemaOf(component) {
+            return byName.get(component)?.schema.fields ?? [];
+        },
+        read(entity, component, field) {
+            const type = byName.get(component);
+            return type === undefined ? undefined : world.read(entity, type, field);
+        },
+        write(entity, component, field, value) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.write(entity, type, field, value);
+        },
+        hasComponent(entity, component) {
+            const type = byName.get(component);
+            return type !== undefined && world.has(entity, type);
+        },
+        addComponent(entity, component) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.add(entity, type);
+        },
+        removeComponent(entity, component) {
+            const type = byName.get(component);
+            if (type !== undefined)
+                world.remove(entity, type);
+        },
+    };
+}

package/dist/network.d.ts

@@ -56,3 +56,45 @@ export declare function createNetworkView(options: {
     historyLength?: number;
 }): NetworkView;
 export declare const networkPanel: Panel<NetworkWorld, NetworkView>;
+/**
+ * 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 declare function createSessionRecorder(limit?: number): SessionRecorder;
+/**
+ * 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 declare function observeSession(recorder: SessionRecorder, session: SessionLike): void;
+/**
+ * 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 declare function sessionReadout(session: SessionLike, recorder: SessionRecorder, snapshotBytes: number, componentHashes?: NetworkReadout['componentHashes']): NetworkReadout;

package/dist/network.js

@@ -118,3 +118,46 @@ export const networkPanel = {
         return null;
     },
 };
+export function createSessionRecorder(limit = 32) {
+    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, session) {
+    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, recorder, snapshotBytes, componentHashes = null) {
+    return {
+        inputDelay: session.inputDelay,
+        participants: session.participants,
+        snapshotBytes,
+        snapshotCount: session.loop.depth,
+        desyncs: recorder.desyncs,
+        componentHashes,
+    };
+}

package/dist/overlay.d.ts

@@ -0,0 +1,70 @@
+import type { UiNode } from '@driftengine/ui2d';
+import { type Command, type UndoStack } from './command.ts';
+import { 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 declare function bindPanel<W, V>(panel: Panel<W, V>, world: () => Readonly<W>, view: V): PanelBinding;
+/** 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;
+}
+export declare function createToolsOverlay(options: ToolsOverlayOptions): ToolsOverlay;
+/**
+ * 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 declare function paintOverlay(painter: OverlayPainter, overlay: ToolsOverlay): void;

package/dist/overlay.js

@@ -0,0 +1,275 @@
+/**
+ * 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 { createUndoStack } from './command.js';
+import { createPanelRoot } from './panel.js';
+export function bindPanel(panel, world, view) {
+    return {
+        id: panel.id,
+        title: panel.title,
+        build: (root) => panel.build(world(), view, root),
+        route: (event) => panel.route(world(), view, event),
+    };
+}
+const DEFAULT_WIDTH = 320;
+const DEFAULT_KEY = 'F3';
+export function createToolsOverlay(options) {
+    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();
+    /* Pooled and refilled: this is read every frame the overlay is open and must not allocate. */
+    const sites = [];
+    let width = 0;
+    let height = 0;
+    let visible = options.visible ?? false;
+    let dirty = true;
+    let disposed = false;
+    let layoutCount = 0;
+    let focused = null;
+    const relayout = () => {
+        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() {
+            return visible;
+        },
+        get layoutCount() {
+            return layoutCount;
+        },
+        sites() {
+            if (visible && dirty)
+                relayout();
+            return sites;
+        },
+        setVisible(next) {
+            if (disposed || next === visible)
+                return;
+            visible = next;
+            dirty = true;
+        },
+        toggle() {
+            this.setVisible(!visible);
+        },
+        resize(next, nextHeight) {
+            if (disposed)
+                return;
+            if (next === width && nextHeight === height)
+                return;
+            width = next;
+            height = nextHeight;
+            dirty = true;
+        },
+        frame(_now) {
+            if (disposed || !visible)
+                return;
+            if (dirty)
+                relayout();
+        },
+        route(event) {
+            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() {
+            dirty = true;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            visible = false;
+            undo.clear();
+            root.children.length = 0;
+            roots.clear();
+            sites.length = 0;
+            focused = null;
+        },
+    };
+    function panelWith(id) {
+        if (id === null)
+            return null;
+        for (const panel of panels)
+            if (panel.id === id)
+                return panel;
+        return null;
+    }
+    function siteAt(x, y) {
+        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) {
+        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, dx, dy) {
+    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, overlay) {
+    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, node) {
+    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) {
+    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;
+}