dotframe 0.1.0

package/cli/commands/play.ts

@@ -0,0 +1,244 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Draw2D } from "../../src/draw2d";
+import type { Sim, SimRun } from "../../src/sim";
+import { CliError, type Ctx, loadConfig, print } from "../lib";
+import { firstDifference, flatten, headlessRun, type InputSource, inputSource, lcg, loadSim, parseOptions } from "../simkit";
+
+export interface PlayArgs {
+  inputs?: string;
+  mash?: string;
+  frames?: string;
+  seed?: string;
+  options?: string;
+  every?: string;
+}
+
+interface Played {
+  frames: number;
+  over: boolean;
+  checksum: number;
+  trace: { frame: number; checksum: number }[];
+  state: unknown;
+  ms: number;
+}
+
+function play(run: SimRun, source: InputSource, frames: number, every: number): Played {
+  const t0 = performance.now();
+  const trace: { frame: number; checksum: number }[] = [];
+  let f = 0;
+  for (; f < frames && !run.over(); f++) {
+    run.step(source.at(f));
+    if (every > 0 && (f + 1) % every === 0) trace.push({ frame: f + 1, checksum: run.checksum() });
+  }
+  return { frames: f, over: run.over(), checksum: run.checksum(), trace, state: run.state(), ms: Math.round(performance.now() - t0) };
+}
+
+async function setup(args: PlayArgs): Promise<{ sim: Sim; run: SimRun; source: InputSource; seed: number; options: Record<string, unknown>; root: string }> {
+  const config = loadConfig();
+  const sim = await loadSim(config);
+  const seed = Number(args.seed ?? "1");
+  const options = parseOptions(sim, args.options);
+  const source = inputSource(sim, config.root, args.inputs, args.mash);
+  const run = await headlessRun(sim, config.root);
+  run.start(seed, options);
+  return { sim, run, source, seed, options, root: config.root };
+}
+
+export async function sim(ctx: Ctx, args: PlayArgs): Promise<void> {
+  const { run, source, seed } = await setup(args);
+  const r = play(run, source, Number(args.frames ?? "600"), Number(args.every ?? "0"));
+  print(ctx, { seed, inputs: source.describe, ...r }, (): string =>
+    [`${r.frames} frames in ${r.ms} ms (${source.describe}, seed ${seed})${r.over ? ", match over" : ""}`, `checksum ${r.checksum}`, JSON.stringify(r.state, null, 2)].join("\n"),
+  );
+}
+
+interface Replay {
+  version: 1;
+  seed: number;
+  options: Record<string, unknown>;
+  // Encoded inputs as change points.
+  inputs: { frame: number; inputs: number[] }[];
+  frames: number;
+  checksums: { frame: number; checksum: number }[];
+  final: number;
+}
+
+export async function record(ctx: Ctx, file: string, args: PlayArgs): Promise<void> {
+  if (!file) throw new CliError("MISSING_ARG", "replay record needs an output file", "dotframe replay record replays/smoke.json --mash 7 --frames 1800");
+  const { run, source, seed, options } = await setup(args);
+  const frames = Number(args.frames ?? "1800");
+  const r = play(run, source, frames, 60);
+  const inputs: Replay["inputs"] = [];
+  for (let f = 0; f < r.frames; f++) {
+    const cur = source.at(f);
+    const last = inputs[inputs.length - 1];
+    if (!last || last.inputs.some((v: number, i: number): boolean => v !== cur[i])) inputs.push({ frame: f, inputs: cur.slice() });
+  }
+  const replay: Replay = { version: 1, seed, options, inputs, frames: r.frames, checksums: r.trace, final: r.checksum };
+  writeFileSync(resolve(process.cwd(), file), `${JSON.stringify(replay)}\n`);
+  print(ctx, { file, frames: r.frames, final: r.checksum, checkpoints: r.trace.length }, (): string => `recorded ${r.frames} frames to ${file} (final checksum ${r.checksum})`);
+}
+
+export async function verify(ctx: Ctx, files: string[]): Promise<void> {
+  if (files.length === 0) throw new CliError("MISSING_ARG", "replay verify needs one or more replay files", "dotframe replay verify replays/*.json");
+  const config = loadConfig();
+  const sim = await loadSim(config);
+  const results: { file: string; ok: boolean; firstMismatch: number | null; expected: number; got: number }[] = [];
+  for (const file of files) {
+    const path = resolve(process.cwd(), file);
+    if (!existsSync(path)) throw new CliError("REPLAY_MISSING", `${file} does not exist`, "record one with dotframe replay record");
+    const replay = JSON.parse(readFileSync(path, "utf8")) as Replay;
+    const run = await headlessRun(sim, config.root);
+    run.start(replay.seed, replay.options);
+    const source: InputSource = {
+      describe: file,
+      at: (frame: number): number[] => {
+        let cur = replay.inputs[0]?.inputs ?? [];
+        for (const k of replay.inputs) {
+          if (k.frame > frame) break;
+          cur = k.inputs;
+        }
+        return cur;
+      },
+    };
+    const r = play(run, source, replay.frames, 60);
+    const mismatch = replay.checksums.find((c, i): boolean => r.trace[i]?.checksum !== c.checksum);
+    results.push({ file, ok: !mismatch && r.checksum === replay.final, firstMismatch: mismatch ? mismatch.frame : r.checksum === replay.final ? null : r.frames, expected: replay.final, got: r.checksum });
+  }
+  const failed = results.filter((r): boolean => !r.ok);
+  print(ctx, { results, failed: failed.length }, (): string =>
+    results.map((r): string => (r.ok ? `ok   ${r.file}` : `FAIL ${r.file}: diverges by frame ${r.firstMismatch}`)).join("\n"),
+  );
+  if (failed.length > 0) process.exit(1);
+}
+
+// A Draw2D that accepts every call and draws nothing, so render paths run headless.
+const stubDraw: Draw2D = new Proxy({} as Draw2D, {
+  get: (_t: Draw2D, key: string | symbol): unknown => {
+    if (key === "measureText") return (): { width: number } => ({ width: 10 });
+    if (key === "getGlobalAlpha") return (): number => 1;
+    return (): void => {};
+  },
+});
+
+export interface DesyncArgs extends PlayArgs {
+  latency?: string;
+  jitter?: string;
+  delay?: string;
+  renders?: string;
+}
+
+// Each peer runs its own rollback loop against a deterministic arrival schedule, one after the other, so peers never
+// share module state. Peer 1 also renders between steps: rendering must not change the simulation.
+export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
+  const config = loadConfig();
+  const sim = await loadSim(config);
+  if (sim.players !== 2) throw new CliError("UNSUPPORTED", "desync simulates two peers; this sim has " + sim.players + " players", "", "netplay");
+  const frames = Number(args.frames ?? "1800");
+  const seed = Number(args.seed ?? "1");
+  const latency = Math.round(Number((args.latency ?? "100ms").replace("ms", "")) / (1000 / 60));
+  const jitter = Math.round(Number((args.jitter ?? "0ms").replace("ms", "")) / (1000 / 60));
+  const delay = Number(args.delay ?? "2");
+  const renders = Number(args.renders ?? "3");
+  const every = Number(args.every ?? "30");
+  const options = parseOptions(sim, args.options);
+  const source = inputSource(sim, config.root, args.inputs, args.mash ?? (args.inputs ? undefined : "7"));
+  // Input a player presses at frame f applies at frame f + delay, on both peers.
+  const applied = (frame: number, player: number): number => (frame < delay ? sim.neutral : source.at(frame - delay)[player]);
+
+  const reference = await headlessRun(sim, config.root);
+  reference.start(seed, options);
+  const truth: number[] = [];
+  const truthState = new Map<number, Map<string, unknown>>();
+  for (let f = 0; f < frames; f++) {
+    reference.step([applied(f, 0), applied(f, 1)]);
+    truth.push(reference.checksum());
+    if (reference.inspect && f % every === 0) truthState.set(f, flatten(reference.inspect()));
+  }
+
+  const peer = async (self: number): Promise<{ checksums: number[]; states: Map<number, string>; rollbacks: number; maxDepth: number }> => {
+    const other = 1 - self;
+    const noise = lcg(seed * 31 + other);
+    // Arrival tick of the remote input for each frame, in order, as the link test does.
+    const arrival: number[] = [];
+    let last = 0;
+    for (let f = 0; f < frames; f++) {
+      const sent = Math.max(0, f - delay);
+      last = Math.max(last, sent + latency + (jitter > 0 ? Math.floor(noise() * (jitter + 1)) : 0));
+      arrival.push(last);
+    }
+    const run = await headlessRun(sim, config.root);
+    run.start(seed, options);
+    const snaps: unknown[] = [];
+    const used: number[] = [];
+    const known: (number | undefined)[] = [];
+    const checksums: number[] = [];
+    // First differing path per checkpoint frame; overwritten when a rollback resimulates the frame.
+    const states = new Map<number, string>();
+    let rollbacks = 0;
+    let maxDepth = 0;
+    let next = 0;
+    let lastKnown = sim.neutral;
+    const stepFrame = (f: number): void => {
+      snaps[f] = run.save();
+      const remote = known[f] ?? lastKnown;
+      used[f] = remote;
+      const inputs = [sim.neutral, sim.neutral];
+      inputs[self] = applied(f, self);
+      inputs[other] = remote;
+      run.step(inputs);
+      checksums[f] = run.checksum();
+      if (self === 1 && run.render) for (let r = 0; r < renders; r++) run.render(stubDraw);
+      const want = truthState.get(f);
+      if (want && run.inspect) states.set(f, firstDifference(want, flatten(run.inspect())));
+    };
+    for (let t = 0; t < frames + latency + jitter + 1; t++) {
+      let rollbackFrom = -1;
+      while (next < frames && arrival[next] <= t) {
+        const value = applied(next, other);
+        known[next] = value;
+        lastKnown = value;
+        if (next < checksums.length && used[next] !== value && rollbackFrom < 0) rollbackFrom = next;
+        next += 1;
+      }
+      const simulated = checksums.length;
+      if (rollbackFrom >= 0) {
+        rollbacks += 1;
+        maxDepth = Math.max(maxDepth, simulated - rollbackFrom);
+        run.restore(snaps[rollbackFrom]);
+        for (let f = rollbackFrom; f < simulated; f++) stepFrame(f);
+      }
+      if (t < frames) stepFrame(t);
+    }
+    return { checksums, states, rollbacks, maxDepth };
+  };
+
+  const peers = [await peer(0), await peer(1)];
+  const firstDiff = (a: number[]): number => a.findIndex((c: number, f: number): boolean => c !== truth[f]);
+  const firstState = (states: Map<number, string>): { frame: number; path: string } | null => {
+    for (const [frame, path] of [...states].sort((a, b): number => a[0] - b[0])) if (path !== "") return { frame, path };
+    return null;
+  };
+  const report = peers.map((p, i) => ({
+    peer: i,
+    rendersBetweenSteps: i === 1 ? renders : 0,
+    firstDivergentFrame: firstDiff(p.checksums),
+    // State differences the checksum may miss; null when the sim has no inspect().
+    firstStateDifference: reference.inspect ? firstState(p.states) : null,
+    rollbacks: p.rollbacks,
+    maxRollbackFrames: p.maxDepth,
+  }));
+  const ok = report.every((r): boolean => r.firstDivergentFrame < 0 && r.firstStateDifference === null);
+  print(ctx, { ok, frames, latencyFrames: latency, jitterFrames: jitter, delay, inputs: source.describe, peers: report }, (): string =>
+    [
+      `${frames} frames, latency ${latency}f, jitter ${jitter}f, delay ${delay}f (${source.describe})`,
+      ...report.map((r): string => {
+        const sync = r.firstDivergentFrame >= 0 ? `DESYNC (checksum) at frame ${r.firstDivergentFrame}` : r.firstStateDifference ? `STATE DIFFERS at frame ${r.firstStateDifference.frame}: ${r.firstStateDifference.path}` : "in sync";
+        return `peer ${r.peer}${r.rendersBetweenSteps ? " (renders)" : ""}: ${sync}, ${r.rollbacks} rollbacks, max ${r.maxRollbackFrames}f`;
+      }),
+      reference.inspect ? "" : "note: the sim has no inspect(), so only the checksum is compared",
+    ].filter(Boolean).join("\n"),
+  );
+  if (!ok) process.exit(1);
+}

package/cli/commands/ship.ts

@@ -0,0 +1,94 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CliError, type Command, type Ctx, exec, gate, loadConfig, print, runSteps, target, which } from "../lib";
+
+const skillFor = (t: string): string => (t === "web" ? "export-web" : t);
+
+// Paths marked local-only (unlicensed for distribution) that would ship with a release build.
+function licenseBlockers(root: string, paths: string[]): string[] {
+  return paths.filter((p: string): boolean => {
+    const full = resolve(root, p);
+    return existsSync(full) && (!statSync(full).isDirectory() || readdirSync(full).length > 0);
+  });
+}
+
+export async function build(ctx: Ctx, name: string | undefined, release: boolean): Promise<void> {
+  if (!name) throw new CliError("MISSING_ARG", "build needs a target", "dotframe build web");
+  const config = loadConfig();
+  const t = target(config, name);
+  if (release) {
+    const blocked = licenseBlockers(config.root, config.assets?.localOnly ?? []);
+    if (blocked.length > 0) throw new CliError("ASSETS_LOCAL_ONLY", `release build would ship assets marked local-only: ${blocked.join(", ")}`, "replace them with licensed assets, then remove them from assets.localOnly", "assets");
+  }
+  const steps = await runSteps(ctx, config.root, t.steps, skillFor(name));
+  const artifact = t.out ?? t.app;
+  print(ctx, { target: name, dryRun: ctx.dryRun, steps, artifact: artifact ? resolve(config.root, artifact) : null }, (): string =>
+    [...steps.map((s): string => (ctx.dryRun ? s.tail : `ok ${s.label} (${s.ms} ms)`)), artifact ? `artifact: ${artifact}` : ""].filter(Boolean).join("\n"),
+  );
+}
+
+export async function deploy(ctx: Ctx, name: string | undefined, prod: boolean): Promise<void> {
+  if (!name) throw new CliError("MISSING_ARG", "deploy needs a target", "dotframe deploy web --prod --dry-run");
+  const config = loadConfig();
+  const t = target(config, name);
+  const skill = skillFor(name);
+  if (!t.deploy || !t.out) throw new CliError("NO_DEPLOY", `target "${name}" has no deploy provider or out dir`, `add "out" and "deploy": {"provider": "vercel", ...} to the target`, skill);
+  const out = resolve(config.root, t.out);
+  // The 2026-10-03 incident: deploying the repo root put the wrong game in production.
+  if (out === config.root || existsSync(join(out, "dotframe.json")) || existsSync(join(out, ".git"))) {
+    throw new CliError("DEPLOY_SOURCE_DIR", `${t.out} looks like source, not a build`, "point out at the built folder (e.g. port/dist/web)", skill);
+  }
+  if (!existsSync(join(out, "index.html"))) throw new CliError("NOT_BUILT", `${t.out}/index.html is missing`, `dotframe build ${name}`, skill);
+  if (t.deploy.scope === "your-vercel-team") throw new CliError("CONFIG_PLACEHOLDER", `targets.${name}.deploy.scope is still the template placeholder`, `dotframe config set targets.${name}.deploy.scope '"<team>"'`, skill);
+  const argv = ["vercel", "deploy", ...(prod ? ["--prod"] : []), "--yes", "--scope", t.deploy.scope, "--name", t.deploy.project];
+  const plan = { target: name, provider: t.deploy.provider, project: `${t.deploy.scope}/${t.deploy.project}`, dir: out, production: prod, files: readdirSync(out).length, command: argv.join(" ") };
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, ...plan }, (): string => `would deploy ${out} to ${plan.project}${prod ? " (production)" : " (preview)"}\n  ${plan.command}`);
+    return;
+  }
+  gate(ctx, `deploy ${name}${prod ? " to production" : ""}`, skill);
+  if (!which("vercel")) throw new CliError("TOOL_MISSING", "vercel CLI not found", "npm i -g vercel", skill);
+  const r = await exec(ctx, config.root, { label: "vercel deploy", argv, cwd: out });
+  if (r.code !== 0) throw new CliError("DEPLOY_FAILED", r.tail, "vercel whoami; vercel switch " + t.deploy.scope, skill);
+  const url = r.tail.match(/https:\/\/\S+\.vercel\.app/g)?.pop() ?? null;
+  print(ctx, { ...plan, url, ms: r.ms }, (): string => `deployed ${url ?? "(url not found in output)"}`);
+}
+
+export async function relay(ctx: Ctx, region: string | undefined): Promise<void> {
+  const config = loadConfig();
+  const r = config.relay;
+  if (!r) throw new CliError("NO_RELAY", `dotframe.json has no "relay"`, `add {"provider": "dokploy", "compose": "<id>"} or {"provider": "fly", "app": "...", "config": "fly.toml"}`, "relay");
+  let command: Command;
+  if (r.provider === "dokploy") {
+    if (region) throw new CliError("UNSUPPORTED", "dokploy runs on one fixed VPS; --region needs the fly provider", "", "relay");
+    command = { label: "dokploy redeploy", argv: ["vps", "-y", "compose", "redeploy", r.compose] };
+  } else {
+    command = { label: "fly deploy", argv: ["fly", "deploy", "--config", r.config, "--app", r.app, "--primary-region", region ?? r.region ?? "eze", "--yes"] };
+  }
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, provider: r.provider, command: command.argv.join(" ") }, (): string => `would run: ${command.argv.join(" ")}`);
+    return;
+  }
+  gate(ctx, "relay deploy", "relay");
+  if (!which(command.argv[0])) throw new CliError("TOOL_MISSING", `${command.argv[0]} not found`, r.provider === "fly" ? "brew install flyctl && fly auth login" : "bun add -g vps CLI and log in", "relay");
+  const res = await exec(ctx, config.root, command);
+  if (res.code !== 0) throw new CliError("DEPLOY_FAILED", res.tail, "", "relay");
+  print(ctx, { provider: r.provider, ms: res.ms }, (): string => `relay deployed via ${r.provider}`);
+}
+
+export async function device(ctx: Ctx, name: string): Promise<void> {
+  const config = loadConfig();
+  const t = target(config, name);
+  if (!t.app || !t.device) throw new CliError("NO_DEVICE", `target "${name}" needs "app" and "device" in dotframe.json`, "xcrun devicectl list devices", "ios");
+  const app = resolve(config.root, t.app);
+  const argv = ["xcrun", "devicectl", "device", "install", "app", "--device", t.device, app];
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, command: argv.join(" ") }, (): string => `would run: ${argv.join(" ")}`);
+    return;
+  }
+  gate(ctx, `install ${name} on device ${t.device}`, "ios");
+  if (!existsSync(app)) throw new CliError("NOT_BUILT", `${t.app} is missing`, `dotframe build ${name}`, "ios");
+  const r = await exec(ctx, config.root, { label: "devicectl install", argv });
+  if (r.code !== 0) throw new CliError("INSTALL_FAILED", r.tail, "unlock the phone, trust this Mac, enable Developer Mode", "ios");
+  print(ctx, { device: t.device, app, ms: r.ms }, (): string => `installed ${app} on ${t.device}`);
+}

package/cli/commands/skills.ts

@@ -0,0 +1,66 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CliError, type Ctx, print } from "../lib";
+
+// Skills ship inside the dotframe package, so the guide always matches the installed CLI.
+export function skillsDir(): string {
+  return resolve(process.env.DOTFRAME_SKILLS_DIR ?? join(import.meta.dir, "../../skills"));
+}
+
+interface Skill {
+  name: string;
+  description: string;
+  path: string;
+}
+
+function frontmatter(text: string, key: string): string {
+  return text.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1].trim() ?? "";
+}
+
+function all(): Skill[] {
+  const dir = skillsDir();
+  if (!existsSync(dir)) throw new CliError("SKILLS_MISSING", `skills directory ${dir} not found`, "reinstall dotframe or unset DOTFRAME_SKILLS_DIR");
+  return readdirSync(dir)
+    .filter((n: string): boolean => existsSync(join(dir, n, "SKILL.md")))
+    .sort((a: string, b: string): number => (a === "core" ? -1 : b === "core" ? 1 : a.localeCompare(b)))
+    .map((name: string): Skill => {
+      const text = readFileSync(join(dir, name, "SKILL.md"), "utf8");
+      return { name, description: frontmatter(text, "description"), path: join(dir, name) };
+    });
+}
+
+function files(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((n: string): string[] => (statSync(join(dir, n)).isDirectory() ? files(join(dir, n)) : [join(dir, n)])).sort();
+}
+
+function content(skill: Skill, full: boolean): string {
+  const parts = [readFileSync(join(skill.path, "SKILL.md"), "utf8").trim()];
+  if (full) {
+    for (const sub of ["references", "templates"]) {
+      for (const f of files(join(skill.path, sub))) parts.push(`--- ${f.slice(skill.path.length + 1)} ---\n${readFileSync(f, "utf8").trim()}`);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+export async function skills(ctx: Ctx, args: string[], full: boolean, everything: boolean): Promise<void> {
+  const [op = "list", ...names] = args;
+  const list = all();
+  const find = (name: string): Skill => {
+    const s = list.find((k: Skill): boolean => k.name === name);
+    if (!s) throw new CliError("UNKNOWN_SKILL", `no skill named "${name}"`, `available: ${list.map((k: Skill): string => k.name).join(", ")}`);
+    return s;
+  };
+  if (op === "list") {
+    const width = Math.max(...list.map((s: Skill): number => s.name.length)) + 2;
+    print(ctx, list.map(({ name, description }) => ({ name, description })), (): string => list.map((s: Skill): string => `${s.name.padEnd(width)}${s.description}`).join("\n"));
+  } else if (op === "get") {
+    if (!everything && names.length === 0) throw new CliError("MISSING_ARG", "skills get needs a name or --all", "dotframe skills get core");
+    const chosen = everything ? list : names.map(find);
+    print(ctx, chosen.map((s: Skill) => ({ name: s.name, content: content(s, full || everything) })), (): string => chosen.map((s: Skill): string => content(s, full || everything)).join("\n\n"));
+  } else if (op === "path") {
+    const path = names[0] ? find(names[0]).path : skillsDir();
+    print(ctx, { path }, (): string => path);
+  } else throw new CliError("UNKNOWN_COMMAND", `skills ${op}`, "dotframe skills list | get <name> | path");
+}

package/cli/commands/snap.ts

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CliError, type Ctx, exec, loadConfig, print, which } from "../lib";
+import { inputSource, loadSim, parseOptions, simPath } from "../simkit";
+import type { PlayArgs } from "./play";
+
+const ENGINE = resolve(import.meta.dir, "../../src");
+
+// Renders one frame with the real WebGPU renderer: bundles a page that steps the sim to --frame with the given
+// inputs, serves the game root, and screenshots it with agent-browser.
+export async function snap(ctx: Ctx, args: PlayArgs & { frame?: string; out?: string }): Promise<void> {
+  const config = loadConfig();
+  const sim = await loadSim(config);
+  const frame = Number(args.frame ?? "0");
+  const out = resolve(process.cwd(), args.out ?? `snap-${frame}.png`);
+  const seed = Number(args.seed ?? "1");
+  const options = parseOptions(sim, args.options);
+  const source = inputSource(sim, config.root, args.inputs, args.mash);
+  const inputs = Array.from({ length: frame }, (_: unknown, f: number): number[] => source.at(f));
+  if (!which("agent-browser")) throw new CliError("TOOL_MISSING", "agent-browser not found (snap drives a real browser)", "npm i -g agent-browser && agent-browser install");
+
+  const work = join(config.root, ".dotframe", "snap");
+  mkdirSync(work, { recursive: true });
+  const entry = join(work, "entry.ts");
+  writeFileSync(
+    entry,
+    `import sim from ${JSON.stringify(simPath(config))};
+import { createDraw2D } from ${JSON.stringify(join(ENGINE, "draw2d"))};
+import { loadBytes, run } from ${JSON.stringify(join(ENGINE, "web/run"))};
+const plan = ${JSON.stringify({ seed, options, inputs })};
+const done = (data) => { const el = document.createElement("pre"); el.id = data.error ? "dotframe-error" : "dotframe-ready"; el.style.display = "none"; el.textContent = JSON.stringify(data); document.body.appendChild(el); };
+run(sim.window, (p) => {
+  const draw = createDraw2D(p.gpu, sim.window.width, sim.window.height);
+  const r = sim.create({ gpu: p.gpu, load: loadBytes, headless: false, draw });
+  let ready = false;
+  let shown = 0;
+  r.ready.then(() => {
+    r.start(plan.seed, plan.options);
+    for (const i of plan.inputs) r.step(i);
+    ready = true;
+  }).catch((e) => done({ error: String(e) }));
+  return () => {
+    draw.begin();
+    if (ready && r.render) r.render(draw);
+    draw.end({ r: 0, g: 0, b: 0 });
+    if (ready && ++shown === 3) done({ frame: plan.inputs.length, checksum: r.checksum(), state: r.state() });
+    return true;
+  };
+}).catch((e) => done({ error: String(e) }));
+`,
+  );
+  const built = await Bun.build({ entrypoints: [entry], target: "browser" });
+  if (!built.success) throw new CliError("SNAP_BUILD_FAILED", built.logs.map(String).join("\n"), "the sim module must bundle for the browser");
+  const bundle = await built.outputs[0].text();
+  const html = `<!doctype html><meta charset="utf-8"><style>html,body{margin:0;background:#000;overflow:hidden}</style><body><script type="module" src="/__dotframe/snap.js"></script>`;
+  const server = Bun.serve({
+    port: 0,
+    fetch: (req: Request): Response => {
+      const path = decodeURIComponent(new URL(req.url).pathname);
+      if (path === "/") return new Response(html, { headers: { "content-type": "text/html" } });
+      if (path === "/__dotframe/snap.js") return new Response(bundle, { headers: { "content-type": "text/javascript" } });
+      const file = join(config.root, path);
+      return existsSync(file) ? new Response(Bun.file(file)) : new Response("not found", { status: 404 });
+    },
+  });
+  const ab = (...a: string[]) => exec({ ...ctx, json: true }, config.root, { label: `agent-browser ${a[0]}`, argv: ["agent-browser", "--session", "dotframe-snap", ...a] });
+  try {
+    await ab("set", "viewport", String(sim.window.width), String(sim.window.height));
+    const opened = await ab("open", `http://localhost:${server.port}/`);
+    if (opened.code !== 0) throw new CliError("BROWSER_FAILED", opened.tail, "agent-browser install");
+    // Loading plus stepping can take a while for long inputs; poll for the marker.
+    let result: { frame?: number; checksum?: number; state?: unknown; error?: string } | null = null;
+    for (let i = 0; i < 120 && !result; i++) {
+      const r = await ab("eval", `(document.getElementById("dotframe-ready") || document.getElementById("dotframe-error") || {}).textContent || ""`);
+      const text = r.tail.trim().replace(/^"|"$/g, "").replace(/\\"/g, '"');
+      if (text.startsWith("{")) result = JSON.parse(text);
+      else await Bun.sleep(500);
+    }
+    if (!result) throw new CliError("SNAP_TIMEOUT", "the page never reported ready after 60 s", "open the page with agent-browser --headed and read the console; WebGPU may be unavailable", "core");
+    if (result.error) throw new CliError("SNAP_PAGE_ERROR", result.error, "WebGPU unavailable? try AGENT_BROWSER_ARGS=--enable-unsafe-webgpu", "core");
+    const shot = await ab("screenshot", out);
+    if (shot.code !== 0) throw new CliError("BROWSER_FAILED", shot.tail);
+    print(ctx, { out, ...result }, (): string => `frame ${result?.frame} -> ${out} (checksum ${result?.checksum})`);
+  } finally {
+    await ab("close");
+    server.stop(true);
+  }
+}

package/cli/lib.ts

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export class CliError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly fix = "",
+    readonly skill = "core",
+    readonly exit = 1,
+  ) {
+    super(message);
+  }
+}
+
+export interface Ctx {
+  json: boolean;
+  yes: boolean;
+  dryRun: boolean;
+}
+
+export function print(ctx: Ctx, data: unknown, human: () => string): void {
+  if (ctx.json) console.log(JSON.stringify({ ok: true, data }));
+  else console.log(human());
+}
+
+export function fail(ctx: Ctx, error: unknown): never {
+  const e = error instanceof CliError ? error : new CliError("INTERNAL", error instanceof Error ? error.message : String(error));
+  if (ctx.json) console.log(JSON.stringify({ ok: false, error: { code: e.code, message: e.message, fix: e.fix, skill: e.skill } }));
+  else {
+    console.error(`error ${e.code}: ${e.message}`);
+    if (e.fix) console.error(`fix: ${e.fix}`);
+    console.error(`guide: dotframe skills get ${e.skill}`);
+  }
+  process.exit(e.exit);
+}
+
+// External writes (deploys, installs, publishes) need --yes. --dry-run always wins.
+export function gate(ctx: Ctx, action: string, skill: string): void {
+  if (!ctx.yes) throw new CliError("APPROVAL_REQUIRED", `${action} changes something outside this machine`, "review with --dry-run, then rerun with --yes", skill, 2);
+}
+
+export interface Command {
+  label: string;
+  argv: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface Target {
+  steps: Command[];
+  out?: string;
+  app?: string;
+  device?: string;
+  deploy?: { provider: "vercel"; project: string; scope: string };
+}
+
+export interface Config {
+  root: string;
+  name: string;
+  sim?: string;
+  targets: Record<string, Target>;
+  relay?: { provider: "dokploy"; compose: string } | { provider: "fly"; app: string; config: string; region?: string };
+  links?: { path: string; target: string }[];
+  assets?: { localOnly?: string[] };
+}
+
+export const CONFIG_FILE = "dotframe.json";
+
+export function findRoot(from = process.cwd()): string | null {
+  let dir = resolve(from);
+  for (;;) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+export function home(path: string): string {
+  return path.startsWith("~/") ? join(process.env.HOME ?? "", path.slice(2)) : path;
+}
+
+export function loadConfig(): Config {
+  const root = findRoot();
+  if (!root) throw new CliError("NO_CONFIG", `no ${CONFIG_FILE} in this directory or any parent`, "cd into a game repo, or run dotframe new <name>");
+  try {
+    return { ...(JSON.parse(readFileSync(join(root, CONFIG_FILE), "utf8")) as Omit<Config, "root">), root };
+  } catch (error) {
+    throw new CliError("BAD_CONFIG", `${CONFIG_FILE}: ${error instanceof Error ? error.message : "unreadable"}`, "fix the JSON syntax");
+  }
+}
+
+export function target(config: Config, name: string): Target {
+  const t = config.targets[name];
+  if (!t) throw new CliError("UNKNOWN_TARGET", `target "${name}" is not in ${CONFIG_FILE}`, `known targets: ${Object.keys(config.targets).join(", ") || "none"}`, "core");
+  return t;
+}
+
+export function which(bin: string): string | null {
+  return Bun.which(bin);
+}
+
+export interface RunResult {
+  label: string;
+  code: number;
+  ms: number;
+  tail: string;
+}
+
+// Runs a command to completion. Output streams to stderr in human mode and is captured (tail kept) in JSON mode.
+export async function exec(ctx: Ctx, root: string, command: Command): Promise<RunResult> {
+  const t0 = performance.now();
+  const proc = Bun.spawn(command.argv, {
+    cwd: command.cwd ? resolve(root, command.cwd) : root,
+    env: { ...process.env, ...command.env },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const chunks: string[] = [];
+  const pump = async (stream: ReadableStream<Uint8Array>): Promise<void> => {
+    const decoder = new TextDecoder();
+    for await (const chunk of stream) {
+      const text = decoder.decode(chunk);
+      chunks.push(text);
+      if (!ctx.json) process.stderr.write(text);
+    }
+  };
+  await Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+  const code = await proc.exited;
+  const tail = chunks.join("").split("\n").slice(-20).join("\n").trim();
+  return { label: command.label, code, ms: Math.round(performance.now() - t0), tail };
+}
+
+export async function runSteps(ctx: Ctx, root: string, steps: Command[], skill: string): Promise<RunResult[]> {
+  const results: RunResult[] = [];
+  for (const step of steps) {
+    if (ctx.dryRun) {
+      results.push({ label: step.label, code: 0, ms: 0, tail: `would run: ${step.argv.join(" ")} (cwd ${step.cwd ?? "."})` });
+      continue;
+    }
+    if (!ctx.json) console.error(`> ${step.label}`);
+    const r = await exec(ctx, root, step);
+    results.push(r);
+    if (r.code !== 0) throw new CliError("STEP_FAILED", `step "${step.label}" exited ${r.code}\n${r.tail}`, "read the output above; dotframe doctor checks the toolchain", skill);
+  }
+  return results;
+}