@debuffjp/dev 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @debuffjp/dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dev-only inspection and control hooks that let browser tools, the `debuff` CLI and AI agents see and drive a running game.
+
+```ts
+import { devTools } from "@debuffjp/dev";
+
+if (import.meta.env.DEV) game.use(devTools({ input }));
+```
+
+Bundlers drop the call from production builds, and `debuff build` fails if it leaks.
+
+## `window.__DEBUFF_DEV__`
+
+All arguments and return values are JSON-serialisable.
+
+| Method | Returns |
+| --- | --- |
+| `state()` | `{ scene, tick, time, frozen, stats, state, pluginNames, plugins }`. `state` is the active scene's `inspect()`, and `plugins` holds `game.inspect` snapshots |
+| `step(n)` | pauses, advances `n` fixed steps, returns `state()` |
+| `pause()` / `resume()` / `speed(scale)` | live control; `state().pausedBy` says who paused |
+| `frames(n)` | the latest `n` frame breakdowns: interval, update and render ms, catch-up steps, quads, draw calls, long tasks |
+| `notes()` | moments flagged in the overlay, with state and frames |
+| `params()` / `setParam(group, key, value)` | typed parameter schemas and values |
+| `press(code)` / `release(code)` | keyboard |
+| `tap(x, y)` / `pointerDown` / `pointerMove` / `pointerUp` | pointer, in logical coordinates |
+| `errors()` | runtime errors since load, explained: `kind` (`your-code`, `debuff-usage`, `debuff-bug`, `outside`), source-mapped `where`, `hint`, `count` |
+| `capture()` | PNG data URL of the current frame |
+| `replay(toTick?)` | everything played since load (keys, pointer, param changes) up to `toTick`, as a scenario that replays it exactly, plus `warnings` for anything it can't reproduce. Needs `devTools({ input })` |
+
+## Overlay
+
+`devOverlay()` adds a panel. The backquote key hides it, and the ▾ button (or double-clicking the header) collapses it to a single bar with fps, an error count and the agent badge. The panel remembers whether it's collapsed and which tab is open.
+
+The toolbar has pause, step, speed (1×, ½×, ¼×), **snap** (download the current frame as a PNG) and **restart** (re-enter the current scene). Below it are four tabs:
+
+- **perf**: a frame graph coloured by health: lime is on time, amber is a little late (normal display jitter) and red is a dropped frame. Update and render time are stacked inside each bar. A summary shows your headroom and whether recent dropped frames came from the game's own work or from outside it (GC, the browser, other tabs). Click a bar to pause and inspect that frame with a plain-words diagnosis, or tick **pause on dropped frame**. Phases also appear as `debuff:update` and `debuff:render` in the browser profiler.
+- **tune**: sliders for every `game.params` group. Values you've changed from their defaults turn amber. Double-click a name to reset it, and **copy changes** copies just your changes, ready to paste into the param definitions.
+- **state**: your scene's `inspect()` data and plugin snapshots, updating live.
+- **log**: runtime errors, each labelled with whose problem it is (your code, a call debuff rejected, a debuff bug, or something outside the game), with a link that opens the exact source line in your editor, a hint, and a report link for debuff bugs. Also an activity log of who changed what (you, an agent or a scenario) with undo, and notes you can flag for agents. **save replay** and **copy replay** turn the session so far into a scenario that `debuff scenario` plays back exactly.
+
+## Agent link
+
+Under `debuff dev`, the page listens for commands from `@debuffjp/mcp` over the dev server, so agents work on the game you're looking at. Pass `agentLink: false` to opt out.
+
+Open the page with `?debuff-scenario` to stop the loop so time advances only through `step()`. `debuff scenario` uses this mode.

package/dist/explain.d.ts

@@ -0,0 +1,57 @@
+/** Whose problem an error is, so the fix starts in the right place. */
+export type ErrorKind = 
+/** Thrown from the game's own code. */
+"your-code"
+/** debuff rejected a call from the game's code (bad argument, unknown id…); the message says why. */
+ | "debuff-usage"
+/** An unexpected failure inside debuff itself: please report it. */
+ | "debuff-bug"
+/** No frame from this page: a browser extension, another script or the browser. */
+ | "outside";
+export interface SourceLocation {
+    /** Path relative to the dev server, e.g. `src/main.ts`. */
+    file: string;
+    line: number;
+    column: number;
+    /** The function name, when the stack has one. */
+    fn?: string;
+}
+/** A runtime error explained for humans and agents. JSON-serialisable. */
+export interface ExplainedError {
+    kind: ErrorKind;
+    name: string;
+    message: string;
+    /** Where in the game's code to look: the throwing frame, or the call into debuff that failed. */
+    where?: SourceLocation;
+    /** A plain-words next step. */
+    hint: string;
+    /** Loop phase and tick, when the game loop caught it. */
+    phase?: string;
+    scene?: string;
+    tick?: number;
+    /** How many times this same error happened. */
+    count: number;
+    stack: string;
+    /** For `debuff-bug`: a prefilled GitHub issue. */
+    reportUrl?: string;
+}
+/**
+ * Explain an error from its stack: whose code threw, where to look, and what to try.
+ * Heuristic but conservative: when unsure it says so instead of guessing.
+ */
+export declare function explainError(error: unknown, context?: {
+    phase?: string;
+    scene?: string | undefined;
+    tick?: number;
+}, origin?: string): ExplainedError;
+/** Same error, same place: used to collapse repeats (a broken update throws every frame). */
+export declare function errorKey(e: ExplainedError): string;
+export declare function loc(l: SourceLocation): string;
+/**
+ * Stacks point into the code the dev server serves (TypeScript already compiled). Map `e.where` back to
+ * the original source line via the module's source map. Resolves true if the location changed.
+ */
+export declare function mapLocation(e: ExplainedError, origin?: string): Promise<boolean>;
+/** @internal Base64 VLQ source-map mappings → absolute segments per generated line. */
+export declare function decodeMappings(mappings: string): string[][][];
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,MAAM,SAAS;AACnB,uCAAuC;AACrC,WAAW;AACb,qGAAqG;GACnG,cAAc;AAChB,oEAAoE;GAClE,YAAY;AACd,mFAAmF;GACjF,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,EAC3E,MAAM,SAAyD,GAC9D,cAAc,CAuEhB;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAElD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAE7C;AAiDD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,SAAyD,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBtI;AAwCD,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,CAsB7D"}

package/dist/explain.js

@@ -0,0 +1,243 @@
+const ISSUES = "https://github.com/debuffjp/debuff/issues/new";
+/**
+ * Explain an error from its stack: whose code threw, where to look, and what to try.
+ * Heuristic but conservative: when unsure it says so instead of guessing.
+ */
+export function explainError(error, context = {}, origin = typeof location === "undefined" ? "" : location.origin) {
+    const err = error instanceof Error ? error : undefined;
+    const name = err?.name ?? "Error";
+    const message = err?.message ?? String(error);
+    const stack = err?.stack ?? `${name}: ${message}`;
+    const frames = parseStack(stack, origin);
+    const top = frames.find((f) => f.sameOrigin);
+    const yours = frames.find((f) => f.sameOrigin && !f.debuff && !f.thirdParty);
+    const base = {
+        name,
+        message,
+        count: 1,
+        stack,
+        ...(context.phase === undefined ? {} : { phase: context.phase }),
+        ...(context.scene === undefined ? {} : { scene: context.scene }),
+        ...(context.tick === undefined ? {} : { tick: context.tick }),
+    };
+    const at = (f) => (f ? { where: strip(f) } : {});
+    if (!top) {
+        return {
+            ...base,
+            kind: "outside",
+            hint: "No frame from this game in the stack: likely a browser extension or another script. Try a private window.",
+        };
+    }
+    if (!top.debuff) {
+        if (top.thirdParty) {
+            return {
+                ...base,
+                kind: "your-code",
+                ...at(yours ?? top),
+                hint: `Thrown inside a dependency (${top.file}). Check what your code passed to it${yours ? ` at ${loc(yours)}` : ""}.`,
+            };
+        }
+        return { ...base, kind: "your-code", ...at(top), hint: hintFor(name, message, top) };
+    }
+    // Thrown inside debuff. Its deliberate errors are plain `Error`s with a message that says what to do;
+    // a TypeError/RangeError/ReferenceError from inside debuff is a bug in debuff.
+    const deliberate = name === "Error";
+    if (deliberate) {
+        return {
+            ...base,
+            kind: "debuff-usage",
+            ...at(yours),
+            hint: yours
+                ? `debuff rejected a call from ${loc(yours)}. The message says what it expected.`
+                : "debuff rejected a call. The message says what it expected.",
+        };
+    }
+    const title = `${name}: ${message}`.slice(0, 120);
+    const body = [
+        "**What happened**",
+        "",
+        `\`${name}: ${message}\`${context.phase ? ` during \`${context.phase}\`` : ""}`,
+        "",
+        "**Stack**",
+        "",
+        "```",
+        stack.split("\n").slice(0, 15).join("\n"),
+        "```",
+        "",
+        `**Browser**: ${typeof navigator === "undefined" ? "unknown" : navigator.userAgent}`,
+    ].join("\n");
+    return {
+        ...base,
+        kind: "debuff-bug",
+        ...at(yours ?? top),
+        hint: `This looks like a bug in debuff (${top.file}), not in your code. Please report it.`,
+        reportUrl: `${ISSUES}?${new URLSearchParams({ title, body, labels: "bug" })}`,
+    };
+}
+/** Same error, same place: used to collapse repeats (a broken update throws every frame). */
+export function errorKey(e) {
+    return `${e.name}|${e.message}|${e.where ? loc(e.where) : ""}`;
+}
+export function loc(l) {
+    return `${l.file}:${l.line}:${l.column}`;
+}
+function strip(f) {
+    return { file: f.file, line: f.line, column: f.column, ...(f.fn ? { fn: f.fn } : {}) };
+}
+/** Parse V8 (`at fn (url:1:2)`) and Firefox/Safari (`fn@url:1:2`) stack lines. */
+function parseStack(stack, origin) {
+    const frames = [];
+    for (const raw of stack.split("\n")) {
+        const lineText = raw.trim();
+        const m = /^at (?:(.*?) \()?(.+?):(\d+):(\d+)\)?$/.exec(lineText) ?? /^(?:(.*?)@)?(.+?):(\d+):(\d+)$/.exec(lineText);
+        if (!m?.[2])
+            continue;
+        const url = m[2];
+        let path = url;
+        let sameOrigin = false;
+        try {
+            const u = new URL(url);
+            sameOrigin = origin !== "" && u.origin === origin;
+            path = decodeURIComponent(u.pathname);
+        }
+        catch {
+            // Not a URL (node paths in tests): keep as is.
+            sameOrigin = origin === "";
+        }
+        const file = path.replace(/^\/(@fs\/)?/, "");
+        const debuff = /(^|\/)@debuffjp[/_]|\.vite\/deps\/@debuffjp|\/packages\/(core|dev|input|audio|assets|tilemap|juice|ui)\//.test(path);
+        const thirdParty = !debuff && /node_modules\//.test(path);
+        frames.push({ file, line: Number(m[3]), column: Number(m[4]), debuff, thirdParty, sameOrigin, ...(m[1] ? { fn: m[1] } : {}) });
+    }
+    return frames;
+}
+function hintFor(name, message, where) {
+    const read = /(?:reading|setting) '([^']+)'|undefined \(evaluating '([^']+)'\)|can't access property "([^"]+)"/.exec(message);
+    if (name === "TypeError" && read) {
+        const prop = read[1] ?? read[2] ?? read[3];
+        return `Something at ${loc(where)} is undefined when its \`${prop}\` is used. Common causes: an asset, map object or scene field that doesn't exist (yet), or a typo in an id. Check the state tab when it happens.`;
+    }
+    if (name === "TypeError" && /is not a function/.test(message)) {
+        return `A value called as a function at ${loc(where)} isn't one. Check the name and that it's defined before this runs.`;
+    }
+    if (name === "ReferenceError")
+        return `A name used at ${loc(where)} isn't defined. Check for typos or a missing import.`;
+    if (name === "RangeError" && /call stack/i.test(message))
+        return `Infinite recursion at ${loc(where)}: a function keeps calling itself (or a setter sets itself).`;
+    return `Thrown from your code at ${loc(where)}.`;
+}
+const maps = new Map();
+/**
+ * Stacks point into the code the dev server serves (TypeScript already compiled). Map `e.where` back to
+ * the original source line via the module's source map. Resolves true if the location changed.
+ */
+export async function mapLocation(e, origin = typeof location === "undefined" ? "" : location.origin) {
+    const where = e.where;
+    if (!where || !origin)
+        return false;
+    const frame = rawFrames(e.stack).find((f) => f.file === where.file && f.line === where.line && f.column === where.column);
+    if (!frame)
+        return false;
+    const mappings = await loadMappings(frame.url);
+    const segments = mappings?.[where.line - 1];
+    if (!segments?.length)
+        return false;
+    let best;
+    for (const seg of segments) {
+        if (Number(seg[0]) <= where.column - 1)
+            best = seg;
+        else
+            break;
+    }
+    best ??= segments[0];
+    if (!best || best.length < 4)
+        return false;
+    const before = loc(where);
+    e.where = { ...where, line: Number(best[2]) + 1, column: Number(best[3]) + 1 };
+    e.hint = e.hint.split(before).join(loc(e.where));
+    return true;
+}
+function rawFrames(stack) {
+    const out = [];
+    for (const raw of stack.split("\n")) {
+        const t = raw.trim();
+        const m = /^at (?:(.*?) \()?(.+?):(\d+):(\d+)\)?$/.exec(t) ?? /^(?:(.*?)@)?(.+?):(\d+):(\d+)$/.exec(t);
+        if (!m?.[2])
+            continue;
+        try {
+            const u = new URL(m[2]);
+            out.push({ url: m[2], file: decodeURIComponent(u.pathname).replace(/^\/(@fs\/)?/, ""), line: Number(m[3]), column: Number(m[4]) });
+        }
+        catch {
+            // not a URL
+        }
+    }
+    return out;
+}
+/** Decoded mappings as [genColumn, source, origLine, origColumn] per generated line (absolute values). */
+function loadMappings(url) {
+    let p = maps.get(url);
+    if (!p) {
+        p = (async () => {
+            try {
+                const code = await (await fetch(url)).text();
+                const ref = /\/\/# sourceMappingURL=(\S+)\s*$/.exec(code)?.[1];
+                if (!ref)
+                    return undefined;
+                const json = ref.startsWith("data:") ? atob(ref.slice(ref.indexOf(",") + 1)) : await (await fetch(new URL(ref, url))).text();
+                return decodeMappings(JSON.parse(json).mappings);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        maps.set(url, p);
+    }
+    return p;
+}
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** @internal Base64 VLQ source-map mappings → absolute segments per generated line. */
+export function decodeMappings(mappings) {
+    const lines = [];
+    let src = 0;
+    let origLine = 0;
+    let origCol = 0;
+    for (const lineText of mappings.split(";")) {
+        let genCol = 0;
+        const segs = [];
+        for (const seg of lineText.split(",")) {
+            if (!seg)
+                continue;
+            const v = vlq(seg);
+            genCol += v[0] ?? 0;
+            if (v.length >= 4) {
+                src += v[1] ?? 0;
+                origLine += v[2] ?? 0;
+                origCol += v[3] ?? 0;
+                segs.push([String(genCol), String(src), String(origLine), String(origCol)]);
+            }
+            else
+                segs.push([String(genCol)]);
+        }
+        lines.push(segs);
+    }
+    return lines;
+}
+function vlq(s) {
+    const out = [];
+    let value = 0;
+    let shift = 0;
+    for (const ch of s) {
+        const digit = B64.indexOf(ch);
+        value += (digit & 31) << shift;
+        if (digit & 32)
+            shift += 5;
+        else {
+            out.push(value & 1 ? -(value >>> 1) : value >>> 1);
+            value = 0;
+            shift = 0;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import type { Game, ParamDescription, ParamValue, Plugin } from "@debuffjp/core";
+import type { ExplainedError } from "./explain.js";
+import type { Replay } from "./replay.js";
+import { type FrameSample, type Note } from "./session.js";
+/** The parts of `@debuffjp/input`'s `Input` the hooks drive. Structural, so `dev` does not depend on `input`. */
+export interface DrivableInput {
+    keys: {
+        press(code: string): void;
+        release(code: string): void;
+    };
+    pointer: {
+        press(x: number, y: number): void;
+        move(x: number, y: number): void;
+        release(): void;
+    };
+}
+export interface DevState {
+    scene: string | undefined;
+    tick: number;
+    time: number;
+    frozen: boolean;
+    /** Who paused the game ("you", "agent", "spike"…), or null while running. */
+    pausedBy: string | null;
+    timeScale: number;
+    /** Active rendering backend. */
+    renderer: "webgl2" | "2d";
+    stats: ReturnType<Game["stats"]["summary"]>;
+    /** Whatever the active scene's `inspect()` returns. */
+    state: unknown;
+    /** Installed plugin names, in install order. */
+    pluginNames: readonly string[];
+    /** Snapshots from `game.inspect` providers, keyed by name. */
+    plugins: Record<string, unknown>;
+    /** Number of notes the human has flagged (read them with `notes()`). */
+    notes: number;
+}
+/**
+ * The dev inspection and control surface, available as `window.__DEBUFF_DEV__` in dev builds.
+ * Every method takes and returns JSON-serialisable values so browsers, CLIs and agents can call it.
+ */
+export interface DevHooks {
+    readonly version: 2;
+    /** True when the page was opened with `?debuff-scenario`: the loop is stopped and time only advances via `step`. */
+    readonly controlled: boolean;
+    /** Advance `steps` fixed simulation steps (pausing first) and return the new state. */
+    step(steps?: number): DevState;
+    state(): DevState;
+    pause(): DevState;
+    resume(): DevState;
+    /** Simulation speed multiplier (1 = normal). */
+    speed(scale: number): void;
+    press(code: string): void;
+    release(code: string): void;
+    /** Press and release the primary pointer at logical coordinates across one step. */
+    tap(x: number, y: number): void;
+    pointerDown(x: number, y: number): void;
+    pointerMove(x: number, y: number): void;
+    pointerUp(): void;
+    params(): Record<string, ParamDescription>;
+    setParam(group: string, key: string, value: ParamValue): void;
+    /** The latest `n` frame breakdowns (update/render ms, steps, quads, draw calls, long tasks), oldest first. */
+    frames(n?: number): FrameSample[];
+    /**
+     * Everything played since page load (keys, pointer, param changes) up to `toTick` (default: now), as a
+     * scenario that replays it exactly. Pass a note's `tick` to get the session leading up to that note.
+     */
+    replay(toTick?: number): Replay;
+    /** Moments the human flagged in the overlay, with the game state at that tick. */
+    notes(): Note[];
+    /**
+     * Runtime errors since load, explained: `kind` says whose problem it is ("your-code", "debuff-usage",
+     * "debuff-bug", "outside"), `where` points at the game's source, `hint` suggests a next step. Repeats are counted.
+     */
+    errors(): ExplainedError[];
+    /** PNG data URL of the current frame. */
+    capture(): string;
+    /** Names of the commands the game registered with `devTools({ commands })`. */
+    commands(): string[];
+    /** Run a game command, e.g. to start a scenario at a checkpoint. Recorded in replays. */
+    command(name: string, ...args: unknown[]): unknown;
+}
+declare global {
+    interface Window {
+        __DEBUFF_DEV__?: DevHooks;
+    }
+}
+export interface DevHooksOptions {
+    input?: DrivableInput;
+    /**
+     * Accept commands from agents through the dev server (`debuff dev` + `@debuffjp/mcp`), so an agent
+     * works on this live game and its actions show in the overlay. Default true.
+     */
+    agentLink?: boolean;
+    /**
+     * Game-defined commands that scenarios (`{ "command": "warp", "args": ["hollow"] }`) and agents can run,
+     * e.g. jumping to a checkpoint or granting an item. Keeps test shortcuts out of the game's own code paths.
+     */
+    commands?: Record<string, (...args: never[]) => unknown>;
+}
+/** Dev-server endpoints for the agent link (see `@debuffjp/cli`). */
+export declare const AGENT_EVENTS = "/__debuff/agent/events";
+export declare const AGENT_RESULT = "/__debuff/agent/result";
+/**
+ * The dev tools as a runtime plugin. Installs `window.__DEBUFF_DEV__` and removes it on `game.dispose()`.
+ * Use inside `if (import.meta.env.DEV)` so bundlers drop it; `debuff build` fails if it leaks.
+ */
+export declare function devTools(options?: DevHooksOptions): Plugin;
+/** Shorthand for `game.use(devTools(options))`; returns the installed hooks. */
+export declare function exposeDevHooks(game: Game, options?: DevHooksOptions): DevHooks;
+export { type ErrorKind, type ExplainedError, explainError, type SourceLocation } from "./explain.js";
+export { type DevOverlayOptions, devOverlay } from "./overlay.js";
+export { InputRecording, type Replay, type ReplayStep } from "./replay.js";
+export { type Activity, DevSession, diagnose, FrameRecorder, type FrameSample, type FrameSummary, HITCH, type Note, summarize, } from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,157 @@
+import { DevSession } from "./session.js";
+/** Dev-server endpoints for the agent link (see `@debuffjp/cli`). */
+export const AGENT_EVENTS = "/__debuff/agent/events";
+export const AGENT_RESULT = "/__debuff/agent/result";
+/**
+ * The dev tools as a runtime plugin. Installs `window.__DEBUFF_DEV__` and removes it on `game.dispose()`.
+ * Use inside `if (import.meta.env.DEV)` so bundlers drop it; `debuff build` fails if it leaks.
+ */
+export function devTools(options = {}) {
+    return {
+        name: "dev-tools",
+        install(game) {
+            const session = DevSession.acquire(game);
+            if (options.input)
+                session.attachInput(options.input);
+            const errors = session.errors;
+            const hooks = createHooks(game, session, options, errors, () => (hooks.controlled ? "scenario" : "agent"));
+            window.__DEBUFF_DEV__ = hooks;
+            const unlink = options.agentLink === false || hooks.controlled ? undefined : linkAgent(game, session, options, errors);
+            return () => {
+                unlink?.();
+                delete window.__DEBUFF_DEV__;
+                session.release();
+            };
+        },
+    };
+}
+/** Shorthand for `game.use(devTools(options))`; returns the installed hooks. */
+export function exposeDevHooks(game, options = {}) {
+    game.use(devTools(options));
+    if (!window.__DEBUFF_DEV__)
+        throw new Error("dev-tools plugin did not install");
+    return window.__DEBUFF_DEV__;
+}
+function createHooks(game, session, options, errors, who) {
+    const controlled = new URLSearchParams(location.search).has("debuff-scenario");
+    if (controlled) {
+        game.pauseWhenHidden = false;
+        game.stop();
+    }
+    const input = () => {
+        if (!options.input)
+            throw new Error("exposeDevHooks: pass { input } to drive input");
+        return options.input;
+    };
+    const state = () => ({
+        scene: game.scene?.id,
+        tick: game.clock.tick,
+        time: game.clock.time,
+        frozen: game.frozen,
+        pausedBy: session.pausedBy ?? null,
+        timeScale: game.timeScale,
+        renderer: game.draw.kind,
+        stats: game.stats.summary(),
+        state: game.scene?.inspect?.(),
+        pluginNames: game.plugins,
+        plugins: game.inspect.snapshot(),
+        notes: session.notes.length,
+    });
+    return {
+        version: 2,
+        controlled,
+        step(steps = 1) {
+            // Scenarios own the clock already; elsewhere, stepping pauses the live loop first.
+            if (controlled)
+                game.step(steps);
+            else
+                session.step(steps, who());
+            return state();
+        },
+        state,
+        pause() {
+            session.pause(who());
+            return state();
+        },
+        resume() {
+            session.resume(who());
+            return state();
+        },
+        speed: (scale) => session.setSpeed(scale, who()),
+        press: (code) => input().keys.press(code),
+        release: (code) => input().keys.release(code),
+        tap(x, y) {
+            input().pointer.press(x, y);
+            game.step(1);
+            input().pointer.release();
+        },
+        pointerDown: (x, y) => input().pointer.press(x, y),
+        pointerMove: (x, y) => input().pointer.move(x, y),
+        pointerUp: () => input().pointer.release(),
+        params: () => game.params.describe(),
+        setParam: (group, key, value) => session.setParam(group, key, value, who()),
+        frames: (n = 60) => session.recorder.recent(n),
+        replay: (toTick) => {
+            if (!session.recording)
+                throw new Error("Replays need input: use devTools({ input })");
+            return session.recording.toReplay(toTick);
+        },
+        notes: () => session.notes.map((n) => ({ ...n })),
+        errors: () => errors.map((e) => ({ ...e })),
+        commands: () => Object.keys(options.commands ?? {}),
+        command: (name, ...args) => {
+            const fn = options.commands?.[name];
+            if (!fn)
+                throw new Error(`Unknown command "${name}". Registered: ${Object.keys(options.commands ?? {}).join(", ") || "none"}`);
+            session.recording?.command(name, args);
+            session.log(who(), "command", name);
+            return fn(...args);
+        },
+        capture: () => {
+            // Re-render without advancing time: WebGL clears its buffer after presenting, so read in the same task.
+            game.redraw();
+            return game.canvas.toDataURL("image/png");
+        },
+    };
+}
+/**
+ * Agent link (page side): listen for commands from the dev server over Server-Sent Events, run them
+ * on the dev hooks as "agent", and post results back. Silent when the page isn't served by `debuff dev`.
+ */
+function linkAgent(game, session, options, errors) {
+    if (typeof EventSource === "undefined" || !/^https?:$/.test(location.protocol))
+        return undefined;
+    const hooks = createHooks(game, session, options, errors, () => "agent");
+    const events = new EventSource(AGENT_EVENTS);
+    events.addEventListener("error", () => {
+        // 404 (not served by debuff dev) closes the stream for good; nothing else to do.
+        if (events.readyState === EventSource.CLOSED)
+            events.close();
+    });
+    events.addEventListener("presence", (e) => session.setAgentsAttached(JSON.parse(e.data).agents));
+    events.addEventListener("command", (e) => {
+        const { id, method, args } = JSON.parse(e.data);
+        session.agentSeen();
+        let body;
+        try {
+            const fn = hooks[method];
+            if (typeof fn !== "function")
+                throw new Error(`Unknown dev hook "${String(method)}"`);
+            body = { id, ok: true, result: fn(...args) };
+            if (method === "capture")
+                session.log("agent", "captured a frame");
+            else if (method === "press" || method === "release" || method === "tap")
+                session.log("agent", method, String(args[0] ?? ""));
+        }
+        catch (err) {
+            body = { id, ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+        void fetch(AGENT_RESULT, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    });
+    return () => events.close();
+}
+export { explainError } from "./explain.js";
+export { devOverlay } from "./overlay.js";
+export { InputRecording } from "./replay.js";
+export { DevSession, diagnose, FrameRecorder, HITCH, summarize, } from "./session.js";
+//# sourceMappingURL=index.js.map