@driftengine/tools 4.0.0

package/dist/panel.d.ts

@@ -0,0 +1,79 @@
+import type { UiNode } from '@driftengine/ui2d';
+import type { Command } from './command.ts';
+/**
+ * What a panel is asked to deal with.
+ *
+ * Positions are in the panel's own space — the caller has already subtracted the dock site's
+ * origin — so a panel never knows where on screen it is, and a panel moved to another dock behaves
+ * identically. `button` is 0 for the primary; a context menu is 2, as every platform spells it.
+ */
+export type UiEvent = {
+    readonly kind: 'pointer';
+    readonly phase: 'down' | 'move' | 'up';
+    readonly x: number;
+    readonly y: number;
+    readonly button: number;
+} | {
+    readonly kind: 'key';
+    readonly key: string;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+} | {
+    readonly kind: 'wheel';
+    readonly x: number;
+    readonly y: number;
+    readonly dx: number;
+    readonly dy: number;
+};
+export declare function pointerEvent(phase: 'down' | 'move' | 'up', x: number, y: number, button?: number): UiEvent;
+export declare function keyEvent(key: string, shift?: boolean, ctrl?: boolean): UiEvent;
+export declare function wheelEvent(x: number, y: number, dx: number, dy: number): UiEvent;
+export interface Panel<W, V> {
+    /** Stable for the life of the panel. What the dock layout stores. */
+    readonly id: string;
+    /** What the dock tab says. */
+    readonly title: string;
+    /** Fill `root` from the world and the view. Called whenever either may have changed. */
+    build(world: Readonly<W>, view: V, root: UiNode): void;
+    /**
+     * What this event asks of the *world*, or nothing.
+     *
+     * May write `view` — a drag has to be recorded somewhere, and so do a scroll and a hover. May
+     * not write `world`, which is what the command it returns is for.
+     */
+    route(world: Readonly<W>, view: V, event: UiEvent): Command | null;
+}
+/** The prefix a panel root's name carries, so the dock can recognise one. */
+export declare const PANEL_PREFIX = "panel:";
+/**
+ * The node a panel builds into.
+ *
+ * The identifier lives on the root rather than in a map beside the tree, so the dock reads it off
+ * whatever node it is holding and there is nothing to keep in step. It takes the identifier alone
+ * rather than a `Panel<S>`, so a caller need not name the state type to make a root. `clip`,
+ * because a panel's content is
+ * routinely taller than its site, and a panel drawing outside its dock is the first thing anybody
+ * notices.
+ */
+export declare function createPanelRoot(panel: {
+    readonly id: string;
+}): UiNode;
+/** Which panel a node is the root of, or null. */
+export declare function panelIdOf(node: UiNode | null): string | null;
+/**
+ * Replace a panel's contents with one line saying why there is nothing.
+ *
+ * Not interactive, because a message is not a control and a person who clicks it and gets a
+ * selection has learnt something untrue about the panel.
+ */
+export declare function emptyPanel(root: UiNode, message: string): void;
+/**
+ * A tree as a comparable string: structure, text, geometry and name, but never identity.
+ *
+ * **What it deliberately leaves out is object identity**, because a panel that reuses its pooled
+ * rows and one that rebuilt them are the same panel as far as the contract is concerned — the
+ * whole point of pooling is that nobody downstream can tell. What it deliberately includes is
+ * `hidden`, because a pooled row that is not showing is exactly how a panel shrinks, and two trees
+ * differing only there are showing different things.
+ */
+export declare function treeShape(node: UiNode, depth?: number): string;

package/dist/panel.js

@@ -0,0 +1,90 @@
+/**
+ * The shape every panel shares.
+ *
+ * **`route` is handed the world read-only and returns a command or nothing.** That one signature is
+ * what makes "a panel mutates only through commands" enforceable rather than aspirational: a panel
+ * physically cannot change the world, because it is given no way to. The undo stack is only as good
+ * as its worst offender, and this is how there is no worst offender.
+ *
+ * **The world and the view are two parameters, and the plan had them as one.** Writing the scene
+ * tree found out why they cannot be: a drag in progress, which row is hovered, how far the list is
+ * scrolled and which branches are open are all things `route` must write, and none of them belongs
+ * to the world. With one state object, "never mutates state" is either false or the panel cannot
+ * record a drag. Split, the claim is exact — `Readonly<W>` for what the world owns, `V` for what
+ * the panel owns — and the frozen-state test below is meaningful rather than true by construction.
+ * `Readonly` is shallow and so is not a proof; it is a statement of intent in the place a reader
+ * will look, which is the same standing every other rule in this repository has.
+ *
+ * **`build` is a function of both.** Building twice over the same world and view reaches the same
+ * tree, so a panel can be rebuilt whenever anything changes without anybody reasoning about what it
+ * was showing before. `treeShape` is how a test says that, and every panel's test uses it.
+ *
+ * **Nothing to show is a state and not a failure.** A panel with no selection, an asset browser
+ * before the project has loaded and a profiler before the first frame all reach `emptyPanel`. An
+ * empty dock with an exception behind it is the least useful thing an editor can show.
+ */
+import { addUiChild, createUiNode } from '@driftengine/ui2d';
+export function pointerEvent(phase, x, y, button = 0) {
+    return { kind: 'pointer', phase, x, y, button };
+}
+export function keyEvent(key, shift = false, ctrl = false) {
+    return { kind: 'key', key, shift, ctrl };
+}
+export function wheelEvent(x, y, dx, dy) {
+    return { kind: 'wheel', x, y, dx, dy };
+}
+/** The prefix a panel root's name carries, so the dock can recognise one. */
+export const PANEL_PREFIX = 'panel:';
+/**
+ * The node a panel builds into.
+ *
+ * The identifier lives on the root rather than in a map beside the tree, so the dock reads it off
+ * whatever node it is holding and there is nothing to keep in step. It takes the identifier alone
+ * rather than a `Panel<S>`, so a caller need not name the state type to make a root. `clip`,
+ * because a panel's content is
+ * routinely taller than its site, and a panel drawing outside its dock is the first thing anybody
+ * notices.
+ */
+export function createPanelRoot(panel) {
+    return createUiNode({
+        direction: 'column',
+        width: 'grow',
+        height: 'grow',
+        clip: true,
+        name: `${PANEL_PREFIX}${panel.id}`,
+    });
+}
+/** Which panel a node is the root of, or null. */
+export function panelIdOf(node) {
+    if (node === null || !node.name.startsWith(PANEL_PREFIX))
+        return null;
+    const id = node.name.slice(PANEL_PREFIX.length);
+    return id.length > 0 ? id : null;
+}
+/**
+ * Replace a panel's contents with one line saying why there is nothing.
+ *
+ * Not interactive, because a message is not a control and a person who clicks it and gets a
+ * selection has learnt something untrue about the panel.
+ */
+export function emptyPanel(root, message) {
+    root.children.length = 0;
+    addUiChild(root, createUiNode({ width: 'grow', height: 18, text: message, name: 'empty', interactive: false }));
+}
+/**
+ * A tree as a comparable string: structure, text, geometry and name, but never identity.
+ *
+ * **What it deliberately leaves out is object identity**, because a panel that reuses its pooled
+ * rows and one that rebuilt them are the same panel as far as the contract is concerned — the
+ * whole point of pooling is that nobody downstream can tell. What it deliberately includes is
+ * `hidden`, because a pooled row that is not showing is exactly how a panel shrinks, and two trees
+ * differing only there are showing different things.
+ */
+export function treeShape(node, depth = 0) {
+    const pad = '  '.repeat(depth);
+    const size = `${String(node.width)}x${String(node.height)}`;
+    const flags = `${node.hidden ? 'h' : '-'}${node.interactive ? 'i' : '-'}${node.clip ? 'c' : '-'}`;
+    const own = `${pad}${node.name || '(unnamed)'} ${size} ${flags} ${node.layer} ${JSON.stringify(node.text)}`;
+    const children = node.children.map((child) => treeShape(child, depth + 1));
+    return [own, ...children].join('\n');
+}

package/dist/profiler.d.ts

@@ -0,0 +1,56 @@
+import type { UiNode } from '@driftengine/ui2d';
+import { type PassTimings } from '@driftengine/core';
+import { type ResidencyTable } from '@driftengine/texture';
+import { type Panel } from './panel.ts';
+export interface ProfilerRow {
+    label: string;
+    /** Milliseconds, or null where nothing measured this pass. Null is not zero. */
+    ms: number | null;
+}
+/** `—` for unmeasured. Two decimals, because a pass under a hundredth is not the one to look at. */
+export declare function formatMs(ms: number | null): string;
+/**
+ * One row per *labelled* pass, oldest index first, written into `out`.
+ *
+ * A pass with no label was never part of this frame's composition, so it is not a row — as against
+ * a pass that has a label and no sample, which is a row reading `—`.
+ */
+export declare function profilerRows(timings: PassTimings, out: ProfilerRow[]): ProfilerRow[];
+/**
+ * A fixed window of frame times, oldest first.
+ *
+ * A ring rather than a growing array, because this is pushed once a frame forever and the window
+ * is the only part anybody looks at.
+ */
+export interface FrameHistory {
+    readonly ms: Float64Array;
+    /** Where the next frame goes. */
+    head: number;
+    /** How many of `ms` are live, up to its length. */
+    filled: number;
+}
+export declare function createFrameHistory(capacity: number): FrameHistory;
+export declare function pushFrame(history: FrameHistory, ms: number): void;
+/** The window, oldest first. Allocates, so it is for a reader rather than for a frame. */
+export declare function historyValues(history: FrameHistory): number[];
+/**
+ * How full the page cache is, or null where there is no cache to be full.
+ *
+ * **Null rather than zero for a capacity of nothing.** A cache that is not there is not an empty
+ * cache, and a bar reading 0% would say the streamer had failed rather than that it was absent.
+ */
+export declare function occupancy(table: ResidencyTable | null): number | null;
+export interface ProfilerWorld {
+    readonly timings: PassTimings;
+    readonly history: FrameHistory;
+    readonly residency: ResidencyTable | null;
+}
+export interface ProfilerView {
+    readonly root: UiNode;
+    rows: ProfilerRow[];
+    rowHeight: number;
+}
+export declare function createProfilerView(options: {
+    rowHeight?: number;
+}): ProfilerView;
+export declare const profilerPanel: Panel<ProfilerWorld, ProfilerView>;

package/dist/profiler.js

@@ -0,0 +1,142 @@
+/**
+ * Where the frame's milliseconds went, per pass.
+ *
+ * **Unmeasured is not zero, and this panel is the reason Wave 1A drew that line.** `passMs` returns
+ * null where nothing sampled a pass, and this renders it as `—`. A profiler that showed 0.00 there
+ * could not be told apart from a pass that genuinely ran in no time, and the person reading it
+ * would go and optimise a pass that never ran. A *measured* zero still reads as `0.00`, because
+ * that one is a fact.
+ *
+ * **A pass that did nothing this frame keeps its row.** That is what Wave 1A's labels persisting
+ * while its timings reset buys: the rows stop jumping about as quality settings toggle passes on
+ * and off, which is exactly when somebody is reading them.
+ *
+ * **Nothing here allocates on a rebuild.** This panel is rebuilt every frame by definition, so the
+ * rows and the nodes are both pooled and refilled; a profiler that allocated would be reporting on
+ * a frame it was making worse.
+ */
+import { addUiChild, createUiNode } from '@driftengine/ui2d';
+import { passLabel, passMs } 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. */
+export function formatMs(ms) {
+    return ms === null ? '—' : ms.toFixed(2);
+}
+/**
+ * One row per *labelled* pass, oldest index first, written into `out`.
+ *
+ * A pass with no label was never part of this frame's composition, so it is not a row — as against
+ * a pass that has a label and no sample, which is a row reading `—`.
+ */
+export function profilerRows(timings, out) {
+    let at = 0;
+    for (let pass = 0; pass < timings.labels.length; pass += 1) {
+        const label = passLabel(timings, pass);
+        if (label === '')
+            continue;
+        const row = out[at] ?? { label: '', ms: null };
+        row.label = label;
+        row.ms = passMs(timings, pass);
+        out[at] = row;
+        at += 1;
+    }
+    out.length = at;
+    return out;
+}
+export function createFrameHistory(capacity) {
+    return { ms: new Float64Array(Math.max(0, capacity)), head: 0, filled: 0 };
+}
+export function pushFrame(history, ms) {
+    const capacity = history.ms.length;
+    if (capacity === 0)
+        return;
+    history.ms[history.head] = ms;
+    history.head = (history.head + 1) % capacity;
+    if (history.filled < capacity)
+        history.filled += 1;
+}
+/** The window, oldest first. Allocates, so it is for a reader rather than for a frame. */
+export function historyValues(history) {
+    const capacity = history.ms.length;
+    const out = [];
+    const first = history.filled < capacity ? 0 : history.head;
+    for (let at = 0; at < history.filled; at += 1) {
+        out.push(history.ms[(first + at) % capacity]);
+    }
+    return out;
+}
+/**
+ * How full the page cache is, or null where there is no cache to be full.
+ *
+ * **Null rather than zero for a capacity of nothing.** A cache that is not there is not an empty
+ * cache, and a bar reading 0% would say the streamer had failed rather than that it was absent.
+ */
+export function occupancy(table) {
+    if (table === null || table.capacity <= 0)
+        return null;
+    return residentCount(table) / table.capacity;
+}
+export function createProfilerView(options) {
+    return {
+        root: createPanelRoot(profilerPanel),
+        rows: [],
+        rowHeight: options.rowHeight ?? 18,
+    };
+}
+/** A pooled row, shown; rows past the end are hidden rather than removed, so the pool survives. */
+function lineAt(root, index, text, height) {
+    const existing = root.children[index];
+    if (existing !== undefined) {
+        existing.hidden = false;
+        existing.text = text;
+        return;
+    }
+    addUiChild(root, createUiNode({ width: 'grow', height, text, interactive: false, name: `line:${index}` }));
+}
+function hideFrom(root, index) {
+    for (let at = index; at < root.children.length; at += 1) {
+        root.children[at].hidden = true;
+    }
+}
+/** The mean of the window, which is the number worth showing beside the current frame. */
+function meanOf(history) {
+    if (history.filled === 0)
+        return null;
+    let total = 0;
+    for (let at = 0; at < history.filled; at += 1)
+        total += history.ms[at];
+    return total / history.filled;
+}
+export const profilerPanel = {
+    id: 'profiler',
+    title: 'Profiler',
+    build(world, view, root) {
+        view.rows = profilerRows(world.timings, view.rows);
+        /*
+         * **Nothing at all, rather than no *passes*.** A host with no device still knows how long its
+         * frames took, and this returned before the frame line was ever added — so a panel holding
+         * sixty samples said `No timings yet`. Reporting nothing where there is something is the same
+         * fault as reporting a zero where there is nothing, which the row formatter exists to avoid.
+         */
+        if (view.rows.length === 0 && world.history.filled === 0) {
+            emptyPanel(root, 'No timings yet');
+            return;
+        }
+        let at = 0;
+        for (const row of view.rows) {
+            lineAt(root, at, `${row.label}  ${formatMs(row.ms)}`, view.rowHeight);
+            at += 1;
+        }
+        lineAt(root, at, `frame  ${formatMs(meanOf(world.history))} mean of ${world.history.filled}`, view.rowHeight);
+        at += 1;
+        const full = occupancy(world.residency);
+        lineAt(root, at, `residency  ${full === null ? '—' : `${(full * 100).toFixed(0)}%`}`, view.rowHeight);
+        at += 1;
+        hideFrom(root, at);
+    },
+    route() {
+        /* A profiler reads. There is nothing here a person could ask the world to change. */
+        return null;
+    },
+};

package/dist/selection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What is selected, which of it is primary, and in what order.
+ *
+ * **Order is kept, and that is not cosmetic.** A multi-entity gizmo pivots on the primary
+ * selection; if the order drifts between frames the pivot jumps, and a drag that started around one
+ * object finishes around another. Insertion order with the primary as the most recent addition is
+ * both what a person expects and what keeps the pivot still.
+ */
+export interface Selection {
+    /** Selected entities, in the order they were added. */
+    entities: number[];
+}
+export declare function createSelection(): Selection;
+export declare function selectOnly(selection: Selection, entity: number): void;
+export declare function addToSelection(selection: Selection, entity: number): void;
+export declare function toggleSelection(selection: Selection, entity: number): void;
+/**
+ * Select everything between two entities in a caller-supplied order.
+ *
+ * The order is the caller's because only the caller knows it — a scene tree's order is its own
+ * flattening, and an asset browser's is its filter and sort. Inclusive at both ends, and the same
+ * set whichever end is given first.
+ */
+export declare function selectRange(selection: Selection, from: number, to: number, order: readonly number[]): void;
+export declare function clearSelection(selection: Selection): void;
+export declare function selectedEntities(selection: Selection): readonly number[];
+export declare function isSelected(selection: Selection, entity: number): boolean;
+/** The most recently added, which is what an inspector shows and what a gizmo pivots on. */
+export declare function primarySelection(selection: Selection): number | null;

package/dist/selection.js

@@ -0,0 +1,52 @@
+export function createSelection() {
+    return { entities: [] };
+}
+export function selectOnly(selection, entity) {
+    selection.entities.length = 0;
+    selection.entities.push(entity);
+}
+export function addToSelection(selection, entity) {
+    if (selection.entities.includes(entity))
+        return;
+    selection.entities.push(entity);
+}
+export function toggleSelection(selection, entity) {
+    const at = selection.entities.indexOf(entity);
+    if (at === -1)
+        selection.entities.push(entity);
+    else
+        selection.entities.splice(at, 1);
+}
+/**
+ * Select everything between two entities in a caller-supplied order.
+ *
+ * The order is the caller's because only the caller knows it — a scene tree's order is its own
+ * flattening, and an asset browser's is its filter and sort. Inclusive at both ends, and the same
+ * set whichever end is given first.
+ */
+export function selectRange(selection, from, to, order) {
+    const a = order.indexOf(from);
+    const b = order.indexOf(to);
+    if (a === -1 || b === -1)
+        return;
+    const lo = Math.min(a, b);
+    const hi = Math.max(a, b);
+    selection.entities.length = 0;
+    for (let i = lo; i <= hi; i += 1)
+        selection.entities.push(order[i]);
+}
+export function clearSelection(selection) {
+    selection.entities.length = 0;
+}
+export function selectedEntities(selection) {
+    return selection.entities;
+}
+export function isSelected(selection, entity) {
+    return selection.entities.includes(entity);
+}
+/** The most recently added, which is what an inspector shows and what a gizmo pivots on. */
+export function primarySelection(selection) {
+    return selection.entities.length === 0
+        ? null
+        : selection.entities[selection.entities.length - 1];
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@driftengine/tools",
+  "version": "4.0.0",
+  "description": "The editor panels a shipped game can carry, and the command stack that makes their edits undoable",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "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"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/tools"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "editor",
+    "tools",
+    "debugging"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs @driftengine/tools"
+  }
+}

package/src/command.ts

@@ -0,0 +1,103 @@
+/**
+ * Every change to the world, as an object that can be undone.
+ *
+ * **Built before any panel exists, and that order is the point.** An undo stack added after the
+ * panels is an undo stack with holes in it, and the holes are found by users rather than by tests:
+ * one panel mutated directly, once, and now a particular sequence of actions cannot be taken back.
+ * Built first, every panel is written against it.
+ *
+ * **A panel is never handed the world.** `Panel.route` returns a `Command` or nothing, so a panel
+ * physically cannot change anything — the rule is enforced by the signature rather than by review.
+ *
+ * **Merging is what makes a drag usable.** A gizmo emits a command per frame; sixty of them in the
+ * undo stack means sixty presses of undo to take back one movement. `merge` lets a command absorb
+ * the next of its kind, so a drag is one entry.
+ */
+export interface Command {
+  /** Shown in the undo menu and in the palette. */
+  readonly label: string;
+  apply(): void;
+  revert(): void;
+  /**
+   * Absorb a following command of the same kind. Return true if it was absorbed.
+   *
+   * **Called after the stack has already applied `next`, and an implementation must not apply it
+   * again.** Apply happens exactly once, by the stack, for every command — the alternative splits
+   * that responsibility between the stack and each mergeable command, and the first implementation
+   * of this got it wrong in exactly that way: the change ran twice and a drag moved twice as far
+   * as the pointer.
+   *
+   * What absorbing means is that the *earlier* command's `revert` now takes back both.
+   */
+  merge?(next: Command): boolean;
+}
+
+export interface UndoStack {
+  push(command: Command): void;
+  undo(): boolean;
+  redo(): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  undoLabel(): string | null;
+  redoLabel(): string | null;
+  clear(): void;
+}
+
+export function createUndoStack(limit: number): UndoStack {
+  /* Entries below `at` are done; entries from `at` up are the redo branch. */
+  let entries: Command[] = [];
+  let at = 0;
+
+  return {
+    push(command: Command): void {
+      command.apply();
+
+      const previous = at > 0 ? entries[at - 1] : undefined;
+      if (previous?.merge !== undefined && previous.merge(command)) {
+        /*
+         * Absorbed. `command` has already been applied above and must not be applied again; what
+         * changed is that `previous.revert` now takes back both. The redo branch still dies.
+         */
+        entries.length = at;
+        return;
+      }
+
+      /* A new command after an undo discards the redo branch, which is what every editor does. */
+      entries.length = at;
+      entries.push(command);
+      at += 1;
+
+      if (entries.length > limit) {
+        /*
+         * The oldest is forgotten, never reverted. Reverting it on the way out would undo a change
+         * the user made and kept, which is the ring-buffer bug this comment exists to prevent.
+         */
+        entries = entries.slice(entries.length - limit);
+        at = entries.length;
+      }
+    },
+
+    undo(): boolean {
+      if (at === 0) return false;
+      at -= 1;
+      (entries[at] as Command).revert();
+      return true;
+    },
+
+    redo(): boolean {
+      if (at >= entries.length) return false;
+      (entries[at] as Command).apply();
+      at += 1;
+      return true;
+    },
+
+    canUndo: () => at > 0,
+    canRedo: () => at < entries.length,
+    undoLabel: () => (at > 0 ? (entries[at - 1] as Command).label : null),
+    redoLabel: () => (at < entries.length ? (entries[at] as Command).label : null),
+    clear(): void {
+      entries = [];
+      at = 0;
+    },
+  };
+}