dotframe 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.3
+
+Fixes from the Craft Ones port dogfood.
+
+- Numeric and duration flags are validated: `--latency abc`, `--frames abc` and friends fail with `BAD_ARG` instead of a false green.
+- `snap` requires `--frame` and builds in a temp directory, never in the repo.
+- `new` skips `git init` inside an existing repo, copies template subfolders, and names the real cause when bun's minimum release age blocks a fresh dotframe.
+- `deploy --dry-run` counts every file in the build, not the top-level entries.
+- `dev` serves `index.html` with `Cache-Control: no-cache`, like production.
+- Templates: content-hashed web build with a no-cache `vercel.json`, `tsconfig.json` with `@webgpu/types`, and a declared `rollbackWindow`.
+- Engine: `src/web/run.ts` typechecks on TypeScript 5.9 and with Bun's types loaded.
+- `doctor` fails when the deploy scope is a template placeholder, and when `render()` draws nothing with a stub Draw2D (which makes `desync` blind).
+- `desync` warns when rollbacks exceed the sim's new optional `rollbackWindow`.
+- Per-command help (`dotframe <command> --help`); `config set` keeps short objects and arrays on one line.
+- Skills: render purity with a stub Draw2D and the forced-red check (core), rollback window (netplay), SVG rasterizing (assets).
+
 ## 0.1.2
 
 - `npx skills add crafter-games/dotframe` installs a `dotframe` discovery skill that points agents at `dotframe skills get core`. The guides served by the CLI moved to `skill-data/`, so they are not installed as separate skills.

package/cli/commands/config.ts

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { CONFIG_FILE, CliError, type Ctx, loadConfig, print } from "../lib";
+import { CONFIG_FILE, CliError, type Ctx, formatJson, loadConfig, print } from "../lib";
 
 // Dotted keys: targets.web.deploy.project
 export async function configCmd(ctx: Ctx, args: string[]): Promise<void> {
@@ -30,6 +30,6 @@ export async function configCmd(ctx: Ctx, args: string[]): Promise<void> {
     print(ctx, { dryRun: true, key, value: parsed }, (): string => `would set ${key} = ${JSON.stringify(parsed)}`);
     return;
   }
-  writeFileSync(file, `${JSON.stringify(raw, null, 2)}\n`);
+  writeFileSync(file, `${formatJson(raw)}\n`);
   print(ctx, { key, value: parsed }, (): string => `${key} = ${JSON.stringify(parsed)}`);
 }

package/cli/commands/doctor.ts

@@ -1,7 +1,9 @@
 import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { type Config, type Ctx, findRoot, home, loadConfig, print, which } from "../lib";
-import { loadSim } from "../simkit";
+import type { Draw2D } from "../../src/draw2d";
+import type { Sim } from "../../src/sim";
+import { headlessRun, loadSim } from "../simkit";
 
 interface Check {
   check: string;
@@ -33,10 +35,16 @@ export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
       try {
         const sim = await loadSim(config);
         checks.push({ check: "sim", ok: true, detail: `${config.sim} (${sim.players} players)`, fix: "", skill: "core" });
+        checks.push(await renderCheck(sim, config.root));
       } catch (error) {
         checks.push({ check: "sim", ok: false, detail: error instanceof Error ? error.message : "failed to load", fix: "dotframe skills get core (Sim contract)", skill: "core" });
       }
     }
+    for (const [name, t] of Object.entries(config.targets)) {
+      if (t.deploy?.scope === "your-vercel-team") {
+        checks.push({ check: `deploy:${name}`, ok: false, detail: "deploy scope is still the template placeholder", fix: `dotframe config set targets.${name}.deploy.scope '"<vercel team>"'`, skill: "export-web" });
+      }
+    }
     const targets = Object.keys(config.targets);
     if (targets.some((t: string): boolean => t === "web" || t === "discord")) {
       checks.push(tool("vercel", "deploy web", "npm i -g vercel", "export-web"), tool("agent-browser", "dotframe snap", "npm i -g agent-browser && agent-browser install", "core"));
@@ -69,3 +77,27 @@ export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
   );
   if (failed.length > 0) process.exit(1);
 }
+
+// desync proves rendering is pure by calling render() with a stub Draw2D. A render that draws nothing in that
+// case (for example, one that waits for a real renderer) makes the check pass without checking anything.
+async function renderCheck(sim: Sim, root: string): Promise<Check> {
+  const base = { check: "sim:render", skill: "netplay" };
+  const run = await headlessRun(sim, root);
+  if (!run.render) return { ...base, ok: false, detail: "the sim has no render(); desync cannot check render purity", fix: "add render: (draw) => ... to the SimRun", skill: "core" };
+  let calls = 0;
+  const draw = 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 => {
+        calls += 1;
+      };
+    },
+  });
+  run.start(1, { ...sim.options });
+  for (let f = 0; f < 30; f++) run.step(new Array(sim.players).fill(sim.neutral));
+  run.render(draw);
+  return calls > 0
+    ? { ...base, ok: true, detail: `render() drew ${calls} calls with a stub Draw2D`, fix: "" }
+    : { ...base, ok: false, detail: "render() made no draw calls with a stub Draw2D, so desync never exercises it", fix: "render with whatever Draw2D it is given; do not skip when platform.draw is missing" };
+}

package/cli/commands/new.ts

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CliError, type Ctx, exec, loadConfig, print, runSteps, target } from "../lib";
 
@@ -11,7 +11,9 @@ export async function create(ctx: Ctx, name: string | undefined, template: strin
   const dir = resolve(process.cwd(), name);
   if (existsSync(dir)) throw new CliError("EXISTS", `${dir} already exists`, "pick another name or delete it", "game-design");
   const files: [string, string][] = [
-    ...readdirSync(join(TEMPLATES, "_base")).map((f: string): [string, string] => [join(TEMPLATES, "_base", f), f === "gitignore" ? ".gitignore" : f]),
+    ...(readdirSync(join(TEMPLATES, "_base"), { recursive: true }) as string[])
+      .filter((f: string): boolean => statSync(join(TEMPLATES, "_base", f)).isFile())
+      .map((f: string): [string, string] => [join(TEMPLATES, "_base", f), f === "gitignore" ? ".gitignore" : f]),
     [join(TEMPLATES, template, "game.ts"), "src/game.ts"],
   ];
   if (ctx.dryRun) {
@@ -25,15 +27,25 @@ export async function create(ctx: Ctx, name: string | undefined, template: strin
   mkdirSync(join(dir, ".agents/skills/dotframe"), { recursive: true });
   cpSync(resolve(import.meta.dir, "../../skills/dotframe/SKILL.md"), join(dir, ".agents/skills/dotframe/SKILL.md"));
   mkdirSync(join(dir, "replays"), { recursive: true });
+  // Inside an existing repo (porting a game on a branch), the new folder is part of that repo.
+  const insideRepo = (await exec({ ...ctx, json: true }, process.cwd(), { label: "git check", argv: ["git", "rev-parse", "--is-inside-work-tree"] })).code === 0;
   const steps = [
-    { label: "git init", argv: ["git", "init", "-q"] },
+    ...(insideRepo ? [] : [{ label: "git init", argv: ["git", "init", "-q"] }]),
     ...(install ? [{ label: "install", argv: ["bun", "install"] }] : []),
   ];
   for (const step of steps) {
     const r = await exec(ctx, dir, step);
-    if (r.code !== 0) throw new CliError("STEP_FAILED", `${step.label}: ${r.tail}`, "on a machine with a private registry, run bun install --registry https://registry.npmjs.org", "game-design");
+    if (r.code !== 0) {
+      // bun's minimum release age hides versions published in the last N seconds, including a fresh dotframe.
+      const fix = /minimum.?release.?age|minimumReleaseAge/i.test(r.tail)
+        ? `cd ${name} && bun install --minimum-release-age 0`
+        : /registry|401|403|ENOTFOUND/i.test(r.tail)
+          ? `cd ${name} && bun install --registry https://registry.npmjs.org`
+          : `cd ${name} && bun install, then read its output`;
+      throw new CliError("STEP_FAILED", `${step.label}: ${r.tail}`, fix, "game-design");
+    }
   }
-  print(ctx, { dir, template, next: [`cd ${name}`, "dotframe sim --mash 7 --json", "dotframe dev"] }, (): string => `created ${dir} (${template})\nnext: cd ${name} && dotframe sim --mash 7 && dotframe dev`);
+  print(ctx, { dir, template, gitInit: !insideRepo, next: [`cd ${name}`, "dotframe sim --mash 7 --json", "dotframe dev"] }, (): string => `created ${dir} (${template})\nnext: cd ${name} && dotframe sim --mash 7 && dotframe dev`);
 }
 
 // Builds the web target, serves it, and rebuilds when source changes. For humans; agents use sim and snap.
@@ -47,7 +59,11 @@ export async function dev(ctx: Ctx, port: number): Promise<void> {
     port,
     fetch: (req: Request): Response => {
       const path = decodeURIComponent(new URL(req.url).pathname);
-      return new Response(Bun.file(join(out, path === "/" ? "index.html" : path)));
+      const file = join(out, path === "/" ? "index.html" : path);
+      if (!existsSync(file)) return new Response("not found", { status: 404 });
+      // Same caching as production: the page is never cached, hashed bundles can be.
+      const headers = file.endsWith(".html") ? { "Cache-Control": "no-cache" } : undefined;
+      return new Response(Bun.file(file), { headers });
     },
   });
   console.error(`serving ${out} at http://localhost:${server.port}`);

package/cli/commands/play.ts

@@ -2,7 +2,7 @@ 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 { CliError, type Ctx, frames60, loadConfig, num, print } from "../lib";
 import { firstDifference, flatten, headlessRun, type InputSource, inputSource, lcg, loadSim, parseOptions } from "../simkit";
 
 export interface PlayArgs {
@@ -37,7 +37,7 @@ function play(run: SimRun, source: InputSource, frames: number, every: number):
 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 seed = num("seed", 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);
@@ -47,7 +47,7 @@ async function setup(args: PlayArgs): Promise<{ sim: Sim; run: SimRun; source: I
 
 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"));
+  const r = play(run, source, num("frames", args.frames, 600, 1), num("every", 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"),
   );
@@ -67,7 +67,7 @@ interface Replay {
 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 frames = num("frames", args.frames, 1800, 1);
   const r = play(run, source, frames, 60);
   const inputs: Replay["inputs"] = [];
   for (let f = 0; f < r.frames; f++) {
@@ -135,13 +135,13 @@ 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 frames = num("frames", args.frames, 1800, 1);
+  const seed = num("seed", args.seed, 1);
+  const latency = frames60("latency", args.latency, 100);
+  const jitter = frames60("jitter", args.jitter, 0);
+  const delay = num("delay", args.delay, 2);
+  const renders = num("renders", args.renders, 3);
+  const every = num("every", args.every, 30, 1);
   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.
@@ -230,7 +230,13 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
     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 =>
+  const deepest = Math.max(...report.map((r): number => r.maxRollbackFrames));
+  const warnings: string[] = [];
+  if (sim.rollbackWindow !== undefined && deepest > sim.rollbackWindow) {
+    warnings.push(`this link needed ${deepest}-frame rollbacks but the game's window is ${sim.rollbackWindow}: real play would stall`);
+  }
+  if (!sim.rollbackWindow) warnings.push("the sim declares no rollbackWindow, so rollback depth is not checked against the game");
+  print(ctx, { ok, warnings, 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 => {
@@ -238,6 +244,7 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
         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",
+      ...warnings.map((w: string): string => `warning: ${w}`),
     ].filter(Boolean).join("\n"),
   );
   if (!ok) process.exit(1);

package/cli/commands/ship.ts

@@ -4,6 +4,10 @@ import { CliError, type Command, type Ctx, exec, gate, loadConfig, print, runSte
 
 const skillFor = (t: string): string => (t === "web" ? "export-web" : t);
 
+function countFiles(dir: string): number {
+  return readdirSync(dir, { withFileTypes: true }).reduce((n, e) => n + (e.isDirectory() ? countFiles(join(dir, e.name)) : 1), 0);
+}
+
 // 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 => {
@@ -41,7 +45,7 @@ export async function deploy(ctx: Ctx, name: string | undefined, prod: boolean):
   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(" ") };
+  const plan = { target: name, provider: t.deploy.provider, project: `${t.deploy.scope}/${t.deploy.project}`, dir: out, production: prod, files: countFiles(out), 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;

package/cli/commands/snap.ts

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { CliError, type Ctx, exec, loadConfig, print, which } from "../lib";
+import { CliError, type Ctx, exec, loadConfig, num, print, which } from "../lib";
 import { inputSource, loadSim, parseOptions, simPath } from "../simkit";
 import type { PlayArgs } from "./play";
 
@@ -11,16 +12,17 @@ const ENGINE = resolve(import.meta.dir, "../../src");
 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");
+  if (args.frame === undefined) throw new CliError("MISSING_ARG", "snap needs --frame <n>", "dotframe snap --frame 300 --mash 7");
+  const frame = num("frame", args.frame, 0);
   const out = resolve(process.cwd(), args.out ?? `snap-${frame}.png`);
-  const seed = Number(args.seed ?? "1");
+  const seed = num("seed", 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 });
+  // Outside the repo, so a snap never leaves files to commit.
+  const work = mkdtempSync(join(tmpdir(), "dotframe-snap-"));
   const entry = join(work, "entry.ts");
   writeFileSync(
     entry,
@@ -84,5 +86,6 @@ run(sim.window, (p) => {
   } finally {
     await ab("close");
     server.stop(true);
+    rmSync(work, { recursive: true, force: true });
   }
 }

package/cli/lib.ts

@@ -146,3 +146,31 @@ export async function runSteps(ctx: Ctx, root: string, steps: Command[], skill:
   }
   return results;
 }
+
+// Numeric flags: a bad value is an error, never a silent NaN that runs zero frames.
+export function num(flag: string, raw: string | undefined, fallback: number, min = 0): number {
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (raw.trim() === "" || !Number.isInteger(value) || value < min) {
+    throw new CliError("BAD_ARG", `--${flag} must be an integer >= ${min}, got "${raw}"`, `--${flag} ${Math.max(min, fallback)}`);
+  }
+  return value;
+}
+
+// Durations in milliseconds ("120ms" or "120"), converted to 60 Hz frames.
+export function frames60(flag: string, raw: string | undefined, fallbackMs: number): number {
+  const text = raw ?? `${fallbackMs}ms`;
+  const match = text.trim().match(/^(\d+(?:\.\d+)?)(ms)?$/);
+  if (!match) throw new CliError("BAD_ARG", `--${flag} must be a duration like 120ms, got "${text}"`, `--${flag} ${fallbackMs}ms`);
+  return Math.round(Number(match[1]) / (1000 / 60));
+}
+
+// JSON with short objects and arrays kept on one line, so `config set` does not explode a hand-written file.
+export function formatJson(value: unknown, indent = "", width = 100): string {
+  const inline = JSON.stringify(value, null, 1).replace(/\n\s*/g, " ").replace(/\[ /g, "[").replace(/ \]/g, "]").replace(/\{ /g, "{ ").replace(/ \}/g, " }");
+  if (value === null || typeof value !== "object" || indent.length + inline.length <= width) return inline;
+  const next = `${indent}  `;
+  if (Array.isArray(value)) return `[\n${value.map((v) => next + formatJson(v, next, width)).join(",\n")}\n${indent}]`;
+  const entries = Object.entries(value as Record<string, unknown>);
+  return `{\n${entries.map(([k, v]) => `${next}${JSON.stringify(k)}: ${formatJson(v, next, width)}`).join(",\n")}\n${indent}}`;
+}

package/cli/main.ts

@@ -8,7 +8,7 @@ import { desync, record, sim, verify } from "./commands/play";
 import { snap } from "./commands/snap";
 import { skills } from "./commands/skills";
 import { create, dev } from "./commands/new";
-import { CliError, type Ctx, fail } from "./lib";
+import { CliError, type Ctx, fail, num } from "./lib";
 
 const HELP = `dotframe ${pkg.version}: build, test, and export dotframe games
 
@@ -35,6 +35,77 @@ Project
 
 Global: --json  --yes  --dry-run  --help  --version`;
 
+const INPUTS = `Inputs: --mash <seed> (random players) or --inputs f.jsonl (one [p0, p1] per frame, or {"frame": n, "inputs": [...]} held until the next line). --seed <n> seeds the sim, --options '<json>' overrides match options.`;
+
+const COMMAND_HELP: Record<string, string> = {
+  sim: `dotframe sim [--mash <seed> | --inputs f.jsonl] [--frames 600] [--seed 1] [--options json] [--every n] [--json]
+
+Runs the game headless and prints the final state and checksum. --every n adds a checksum trace.
+${INPUTS}
+
+  dotframe sim --mash 7 --frames 600 --json
+  dotframe sim --inputs combo.jsonl --options '{"stocks": 1}'`,
+  snap: `dotframe snap --frame <n> [--out snap-<n>.png] [--mash <seed> | --inputs f.jsonl] [--seed 1] [--options json] [--json]
+
+Steps the sim to frame n in a real browser (WebGPU, through agent-browser) and screenshots it. Open the PNG and look.
+${INPUTS}
+
+  dotframe snap --frame 300 --mash 7 --out /tmp/f300.png`,
+  replay: `dotframe replay record <file> [--mash <seed> | --inputs f.jsonl] [--frames 1800] [--seed 1] [--options json]
+dotframe replay verify <file...>
+
+record stores seed, options, inputs, and a checksum every 60 frames. verify replays them and exits 1 with the
+first divergent frame.
+
+  dotframe replay record replays/smoke.json --mash 7
+  dotframe replay verify replays/*.json`,
+  desync: `dotframe desync [--latency 100ms] [--jitter 0ms] [--delay 2] [--frames 1800] [--renders 3] [--every 30] [--mash <seed> | --inputs f]
+
+Runs a reference sim and two rollback peers over a simulated link. Peer 1 renders --renders times per step.
+Compares checksums every frame and the full inspect() state every --every frames; exits 1 on any difference.
+Warns when rollbacks exceed the sim's rollbackWindow.
+
+  dotframe desync --latency 474ms --jitter 40ms --mash 42 --json`,
+  build: `dotframe build <target> [--release] [--dry-run] [--json]
+
+Runs targets.<target>.steps from dotframe.json. --release refuses assets listed in assets.localOnly.
+
+  dotframe build web
+  dotframe build ios --release`,
+  deploy: `dotframe deploy <target> [--prod] [--dry-run] [--yes] [--json]
+
+Deploys targets.<target>.out with its deploy provider. Without --yes it stops with APPROVAL_REQUIRED (exit 2).
+Show the --dry-run plan to a human first.
+
+  dotframe deploy web --prod --dry-run`,
+  relay: `dotframe relay deploy [--region eze] [--dry-run] [--yes]
+
+Redeploys the netplay relay (dokploy) or deploys it to a region (fly). Gated like deploy.`,
+  device: `dotframe device install <target> [--dry-run] [--yes]
+
+Installs targets.<target>.app on targets.<target>.device with devicectl. Gated like deploy.`,
+  doctor: `dotframe doctor [--fix] [--json]
+
+Checks tools, dotframe.json, the sim (loads, renders with a stub Draw2D), placeholders, and vendor links.
+--fix creates missing vendor symlinks.`,
+  config: `dotframe config get [key]
+dotframe config set <key> <json> [--dry-run]
+
+Dotted keys. Values are JSON (strings need inner quotes). set rewrites dotframe.json with 2-space indent and short
+objects and arrays on one line.
+
+  dotframe config set targets.web.deploy.scope '"my-team"'`,
+  new: `dotframe new <name> [--template fighter|platformer|blank] [--no-install] [--json]
+
+Scaffolds a game. Inside an existing git repo it does not run git init.`,
+  dev: `dotframe dev [--port 5173]
+
+Builds the web target, serves it (index.html with no-cache, as in production), and rebuilds on change.`,
+  skills: `dotframe skills list | get <name...> [--full] | get --all | path [name]
+
+Guides bundled with this CLI version. Start with: dotframe skills get core`,
+};
+
 const { values, positionals } = parseArgs({
   allowPositionals: true,
   strict: false,
@@ -74,6 +145,7 @@ const [command, ...rest] = positionals;
 
 try {
   if (values.version) console.log(pkg.version);
+  else if (command && values.help && COMMAND_HELP[command]) console.log(COMMAND_HELP[command]);
   else if (!command || values.help) console.log(HELP);
   else if (command === "sim") await sim(ctx, v);
   else if (command === "snap") await snap(ctx, v);
@@ -88,7 +160,7 @@ try {
   else if (command === "config") await configCmd(ctx, rest);
   else if (command === "skills") await skills(ctx, rest, values.full === true, values.all === true);
   else if (command === "new") await create(ctx, rest[0], v.template ?? "blank", values["no-install"] !== true);
-  else if (command === "dev") await dev(ctx, Number(v.port ?? "5173"));
+  else if (command === "dev") await dev(ctx, num("port", v.port, 5173, 1));
   else throw new CliError("UNKNOWN_COMMAND", `unknown command: ${positionals.join(" ")}`, "dotframe --help");
 } catch (error) {
   fail(ctx, error);

package/cli/simkit.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import type { Sim, SimRun } from "../src/sim";
 import type { RenderGpu, Texture } from "../src/gpu";
-import { CliError, type Config } from "./lib";
+import { CliError, type Config, num } from "./lib";
 
 let nextTexture = 1;
 // Texture ids restart per run so two runs of the same game have identical state graphs.
@@ -105,7 +105,7 @@ export function mash(sim: Sim, seed: number): InputSource {
 
 export function inputSource(sim: Sim, root: string, inputs: string | undefined, mashSeed: string | undefined): InputSource {
   if (inputs) return inputsFromFile(sim, resolve(process.cwd(), inputs));
-  if (mashSeed !== undefined) return mash(sim, Number(mashSeed));
+  if (mashSeed !== undefined) return mash(sim, num("mash", mashSeed, 0));
   return { describe: "neutral", at: (): number[] => new Array(sim.players).fill(sim.neutral) };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotframe",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "TS-first game engine and agent-first CLI: one codebase for web, Discord, iOS and native binaries",
   "license": "MIT",
   "type": "module",

package/skill-data/assets/SKILL.md

@@ -9,3 +9,4 @@ description: Asset licensing and loading for dotframe games. Use when adding spr
 - Fonts render through SDF atlases baked by `tools/bake-font.c`. Keep the font license (for example SIL OFL) with the atlas.
 - Headless runs (`sim`, `replay`, `desync`) skip asset loading. If gameplay depends on asset data (sprite boxes, frame counts), load that data in headless too, or the sim will differ from the real game.
 - `snap` loads assets from the game root over HTTP, so asset paths must be relative to the repo root.
+- The engine loads PNG, not SVG. Rasterize SVGs at build time (for example with sharp in a build step) at the largest size the game draws them, and commit or generate the PNGs.

package/skill-data/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core
-description: Core dotframe usage. Read before running any dotframe command: the edit, sim, snap, replay loop, the Sim contract, the trust ladder, and how to read errors.
+description: Core dotframe usage. Read before running any dotframe command. Covers the edit, sim, snap, replay loop, the Sim contract, the trust ladder, and how to read errors.
 ---
 # dotframe core
 
@@ -31,6 +31,10 @@ Never claim a visual change works from the JSON alone. Snap it and look.
 - All simulation state changes only inside `step`. `render` reads, never writes (no spawning particles or texts from draw code).
 - Randomness comes from a seeded generator that `save`/`restore` capture.
 - `inspect` returns the whole state graph so `desync` can name the exact field that differs.
+- `render` must draw with whatever Draw2D it receives, including a stub that renders nothing. `desync` calls `render(stubDraw)` to prove rendering leaves state alone; a render that skips itself when there is no real renderer makes that check pass without checking anything. `dotframe doctor` fails `sim:render` when render makes no draw calls.
+- Declare `rollbackWindow` (the most frames your netplay rolls back) so `desync` warns when a link needs more.
+
+Prove a check can fail before trusting its green: make render change one field on purpose, run `desync`, and confirm it fails on peer 1 and names that field. Then revert.
 
 ## Trust ladder
 

package/skill-data/export-web/SKILL.md

@@ -15,6 +15,7 @@ dotframe deploy web --prod --yes     # only after the human approved the plan
 
 - Deploy only the built folder (`targets.web.out`). The CLI refuses a folder that looks like source (repo root, `.git`, `dotframe.json`): that mistake once put the wrong game in production.
 - Do not connect the repo to Vercel's Git integration for these games. A push deploys the repo root.
+- Templates ship `scripts/build-web.ts`, which does both of the next points. Keep it when you change the build.
 - Content-hash the bundle (`main.<hash>.js`) and serve `index.html` with `Cache-Control: no-cache`, so browsers and Discord's proxy never run a stale build.
 - `deploy` without `--prod` makes a preview. Prefer it for checks.
 - Verify a deploy by opening the URL with agent-browser and taking a screenshot, not by the exit code.

package/skill-data/netplay/SKILL.md

@@ -16,7 +16,7 @@ It runs a reference simulation and two peers over a deterministic simulated link
 
 - `firstDivergentFrame`: the checksum differed. A rollback or determinism bug.
 - `firstStateDifference`: `{frame, path}` of the first field that differs at a checkpoint (`--every 30`). Catches state the checksum does not cover. Needs `inspect()` in the sim.
-- `rollbacks`, `maxRollbackFrames`: how hard the link worked. Keep max under the game's rollback window.
+- `rollbacks`, `maxRollbackFrames`: how hard the link worked. With `rollbackWindow` in the sim, `warnings` says when a link needs deeper rollbacks than the game allows (real play would stall).
 
 Run several seeds and a high latency (474 ms is what a transatlantic relay measured). A pass on one seed proves little.
 

package/skills/dotframe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dotframe
-description: Agent-first CLI for the dotframe game engine. Use when building, testing, or exporting a dotframe game: creating a game from a template, simulating or replaying frames headless, rendering a frame to check what a player sees, debugging rollback netplay desyncs, or building and deploying for web, Discord Activities, iOS, and native macOS or Windows. Triggers include "make a game", "dotframe", "simulate the match", "snap a frame", "replay", "desync", "netplay", "build for iOS", "deploy the game", or any repo with a dotframe.json.
+description: Agent-first CLI for the dotframe game engine. Use when building, testing, or exporting a dotframe game, such as creating a game from a template, simulating or replaying frames headless, rendering a frame to check what a player sees, debugging rollback netplay desyncs, or building and deploying for web, Discord Activities, iOS, and native macOS or Windows. Triggers include "make a game", "dotframe", "simulate the match", "snap a frame", "replay", "desync", "netplay", "build for iOS", "deploy the game", or any repo with a dotframe.json.
 allowed-tools: Bash(dotframe:*), Bash(npx dotframe:*), Bash(bunx dotframe:*)
 hidden: true
 ---

package/src/sim.ts

@@ -33,7 +33,9 @@ export interface SimRun {
   // Optional: the whole simulation state as a plain object graph. desync walks it at checkpoints and reports the
   // first differing path, which catches state the checksum does not cover.
   inspect?: () => unknown;
-  // Optional: draws the current frame; must not change simulation state.
+  // Optional: draws the current frame; must not change simulation state. It must also draw with a stub Draw2D
+  // that renders nothing: desync calls it that way to prove rendering leaves the simulation alone, so a render
+  // that skips itself without a real draw makes that check blind.
   render?: (draw: Draw2D) => void;
 }
 
@@ -49,6 +51,8 @@ export interface Sim {
   // A random input, for mashing scripts. next() returns [0, 1).
   random: (next: () => number) => number;
   create: (platform: SimPlatform) => SimRun;
+  // Optional: the most frames the game's netplay can roll back. desync warns when a link needs more.
+  rollbackWindow?: number;
 }
 
 export function defineSim(sim: Sim): Sim {

package/src/web/run.ts

@@ -12,6 +12,8 @@ import type { Audio } from "../audio";
 import { type Input, keyCodes, type Pointer, type Touch } from "../input";
 import type { Storage } from "../storage";
 
+// Engine buffers are always plain ArrayBuffer-backed; the casts below satisfy TS 5.9+ WebGPU typings, which reject
+// Uint8Array<ArrayBufferLike> (it could be a SharedArrayBuffer).
 const vertexFormats: GPUVertexFormat[] = ["float32x2", "float32x3", "float32x4", "float32", "unorm8x4"];
 
 export async function loadBytes(path: string): Promise<Uint8Array> {
@@ -78,13 +80,13 @@ export async function run(options: WindowOptions, setup: Setup): Promise<void> {
       if (usage & BufferUsage.Index) flags |= GPUBufferUsage.INDEX;
       if (usage & BufferUsage.Uniform) flags |= GPUBufferUsage.UNIFORM;
       const buffer = device.createBuffer({ size: Math.ceil(data.byteLength / 4) * 4, usage: flags });
-      device.queue.writeBuffer(buffer, 0, data);
+      device.queue.writeBuffer(buffer, 0, data as Uint8Array<ArrayBuffer>);
       buffers.push(buffer);
       return buffers.length - 1;
     },
     writeBuffer: (buffer: number, data: Uint8Array): void => {
       const target = buffers[buffer];
-      if (target) device.queue.writeBuffer(target, 0, data);
+      if (target) device.queue.writeBuffer(target, 0, data as Uint8Array<ArrayBuffer>);
     },
     destroyBuffer: (buffer: number): void => {
       buffers[buffer]?.destroy();
@@ -144,7 +146,7 @@ export async function run(options: WindowOptions, setup: Setup): Promise<void> {
     },
     createTexture: (width: number, height: number, rgba: Uint8Array, smooth: boolean): Texture =>
       uploadTexture(width, height, smooth, (texture) =>
-        device.queue.writeTexture({ texture }, rgba, { bytesPerRow: width * 4, rowsPerImage: height }, [width, height]),
+        device.queue.writeTexture({ texture }, rgba as Uint8Array<ArrayBuffer>, { bytesPerRow: width * 4, rowsPerImage: height }, [width, height]),
       ),
     createImage: async (png: Uint8Array, smooth: boolean): Promise<Texture> => {
       const bitmap = await createImageBitmap(new Blob([new Uint8Array(png)], { type: "image/png" }), { premultiplyAlpha: "none" });
@@ -189,12 +191,13 @@ export async function run(options: WindowOptions, setup: Setup): Promise<void> {
   };
 
   const pressed = new Set<string>();
-  globalThis.addEventListener("keydown", (event) => {
+  // window, not globalThis: with Bun's types loaded, globalThis listeners receive a plain Event.
+  window.addEventListener("keydown", (event: KeyboardEvent) => {
     if (keyCodes.includes(event.code)) event.preventDefault();
     pressed.add(event.code);
   });
-  globalThis.addEventListener("keyup", (event) => pressed.delete(event.code));
-  globalThis.addEventListener("blur", () => pressed.clear());
+  window.addEventListener("keyup", (event: KeyboardEvent) => pressed.delete(event.code));
+  window.addEventListener("blur", () => pressed.clear());
   const pointer: Pointer = { x: 0, y: 0, buttons: 0 };
   const trackPointer = (event: PointerEvent): void => {
     const rect = canvas.getBoundingClientRect();

package/templates/_base/dotframe.json

@@ -3,10 +3,7 @@
   "sim": "sim.ts",
   "targets": {
     "web": {
-      "steps": [
-        { "label": "bundle", "argv": ["bun", "build", "main.web.ts", "--outfile", "dist/web/main.js", "--target", "browser", "--minify"] },
-        { "label": "page", "argv": ["cp", "index.html", "dist/web/index.html"] }
-      ],
+      "steps": [{ "label": "bundle (hashed)", "argv": ["bun", "scripts/build-web.ts"] }],
       "out": "dist/web",
       "deploy": { "provider": "vercel", "project": "__NAME__", "scope": "__SCOPE__" }
     }

package/templates/_base/package.json

@@ -4,9 +4,15 @@
   "type": "module",
   "scripts": {
     "dev": "dotframe dev",
-    "test": "dotframe replay verify replays/*.json"
+    "test": "dotframe replay verify replays/*.json",
+    "typecheck": "tsc"
   },
   "dependencies": {
     "dotframe": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "@webgpu/types": "^0.1.74",
+    "typescript": "^5.9.0"
   }
 }

package/templates/_base/scripts/build-web.ts

@@ -0,0 +1,21 @@
+// Builds the web target into dist/web with a content-hashed bundle (main.<hash>.js) and a never-cached
+// index.html, so browsers and Discord's proxy never run a stale build.
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+
+const out = "dist/web";
+rmSync(out, { recursive: true, force: true });
+mkdirSync(out, { recursive: true });
+const built = await Bun.build({ entrypoints: ["main.web.ts"], target: "browser", minify: true, naming: "main.[hash].[ext]", outdir: out });
+if (!built.success) {
+  for (const log of built.logs) console.error(log);
+  process.exit(1);
+}
+const bundle = built.outputs[0].path.split("/").pop() ?? "main.js";
+const html = await Bun.file("index.html").text();
+writeFileSync(`${out}/index.html`, html.replace("./main.js", `./${bundle}`));
+writeFileSync(
+  `${out}/vercel.json`,
+  `${JSON.stringify({ headers: [{ source: "/index.html", headers: [{ key: "Cache-Control", value: "no-cache" }] }, { source: "/", headers: [{ key: "Cache-Control", value: "no-cache" }] }] }, null, 2)}\n`,
+);
+if (existsSync("assets")) cpSync("assets", `${out}/assets`, { recursive: true });
+console.log(`${out}/${bundle}`);

package/templates/_base/sim.ts

@@ -7,6 +7,8 @@ export default defineSim({
   window: WINDOW,
   options: {},
   neutral: 0,
+  // Frames your netplay may roll back; desync warns when a link needs more. Match it when you add online play.
+  rollbackWindow: 20,
   encode,
   random: randomInput,
   create: (_platform: SimPlatform): SimRun => {

package/templates/_base/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "types": ["@webgpu/types", "bun"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts", "src", "scripts"]
+}