dotframe 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.1.4
+
+Fixes from rounds 2 and 3 of the Craft Ones dogfood.
+
+- Native builds work from the npm package. `build` on a target with `"native": {"platform", "entry"}` stages the engine and the game in `.dotframe/native/<target>`, rewrites `dotframe/...` imports to relative paths, and writes `dist/<target>/<name>`. Templates ship `main.native.ts`, `src/setup.ts`, and macos and windows targets, and compile on both.
+- `dotframe vendor <macos|windows>` puts SDL3 and wgpu-native in `~/.dotframe/vendor` (or `DOTFRAME_VENDOR`), outside `node_modules`. `doctor` checks it per native target.
+- Failed build steps keep the full output in `.dotframe/logs/` and return its path as `error.log`, with the compiler's error count in the message.
+- `doctor` `sim:render` fails when render changes simulation state (checksum or any `inspect()` field), not only when it draws nothing.
+- `sim` and `replay` take `--through-over` to keep stepping after the match ends.
+- `snap` sets the viewport after opening the page and fails with `SNAP_SIZE` when the screenshot does not match the window.
+- Skills: the macos guide covers native targets, vendor, logs, and scriptc-compatible code; core covers `--through-over` and agent-browser sessions; netplay covers `--renders 0`.
+
+## 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,10 @@
 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 { vendorFix, vendorStatus } from "../native";
+import { firstDifference, flatten, headlessRun, loadSim } from "../simkit";
 
 interface Check {
   check: string;
@@ -33,10 +36,23 @@ 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" });
+      }
+    }
+    for (const [name, t] of Object.entries(config.targets)) {
+      if (!t.native) continue;
+      const v = vendorStatus(t.native.platform);
+      checks.push({ check: `vendor:${name}`, ok: v.missing.length === 0, detail: v.missing.length === 0 ? `${v.dir} (${v.sdl})` : `missing in ${v.dir}: ${v.missing.join(", ")}`, fix: v.missing.length === 0 ? "" : vendorFix(t.native.platform), skill: t.native.platform });
+      checks.push(tool("scriptc", "native builds", "npm i -g scriptc", t.native.platform));
+      if (t.native.platform === "windows") checks.push(tool("zig", "windows cross builds", "brew install zig", "macos"));
+    }
     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 +85,45 @@ 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. Two failure modes are checked here,
+// instantly: a render that draws nothing with the stub (desync's check would be blind), and a render that
+// changes simulation state (checksum or, with inspect(), any field).
+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 });
+  let next = 1;
+  const random = (): number => {
+    next = (Math.imul(next, 1103515245) + 12345) >>> 0;
+    return next / 4294967296;
+  };
+  // Mashed inputs, so effects, projectiles, and HUD state exist when render runs.
+  let impure = "";
+  for (let f = 0; f < 3000 && impure === "" && !run.over(); f++) {
+    run.step(Array.from({ length: sim.players }, (): number => sim.random(random)));
+    if (f % 10 !== 0) continue;
+    const sum = run.checksum();
+    const before = run.inspect ? flatten(run.inspect()) : null;
+    run.render(draw);
+    if (run.checksum() !== sum) impure = `frame ${f}: checksum changed`;
+    else if (before && run.inspect) {
+      const diff = firstDifference(before, flatten(run.inspect()));
+      if (diff) impure = `frame ${f}: ${diff}`;
+    }
+  }
+  if (calls === 0) return { ...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" };
+  if (impure) return { ...base, ok: false, detail: `render() changed simulation state at ${impure}`, fix: "move that write into step(); render must only read", skill: "netplay" };
+  return { ...base, ok: true, detail: `render() drew ${calls} calls with a stub Draw2D and left state unchanged${run.inspect ? "" : " (checksum only; add inspect() for every field)"}`, fix: "" };
+}

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.
@@ -42,12 +54,16 @@ export async function dev(ctx: Ctx, port: number): Promise<void> {
   const t = target(config, "web");
   if (!t.out) throw new CliError("NO_OUT", "the web target needs an out dir", "", "export-web");
   const out = resolve(config.root, t.out);
-  await runSteps(ctx, config.root, t.steps, "export-web");
+  await runSteps(ctx, config.root, t.steps ?? [], "export-web");
   const server = Bun.serve({
     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}`);
@@ -56,7 +72,7 @@ export async function dev(ctx: Ctx, port: number): Promise<void> {
     if (!file || /(^|\/)(node_modules|dist|\.dotframe|\.git)\//.test(`${file}/`) || file.startsWith(t.out ?? "dist")) return;
     if (pending) clearTimeout(pending);
     pending = setTimeout((): void => {
-      runSteps(ctx, config.root, t.steps, "export-web").then(
+      runSteps(ctx, config.root, t.steps ?? [], "export-web").then(
         (): void => console.error(`rebuilt (${file})`),
         (e: unknown): void => console.error(e instanceof Error ? e.message : e),
       );

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 {
@@ -12,6 +12,8 @@ export interface PlayArgs {
   seed?: string;
   options?: string;
   every?: string;
+  // Keep stepping after over(), for rematch and results flows.
+  throughOver?: boolean;
 }
 
 interface Played {
@@ -23,11 +25,11 @@ interface Played {
   ms: number;
 }
 
-function play(run: SimRun, source: InputSource, frames: number, every: number): Played {
+function play(run: SimRun, source: InputSource, frames: number, every: number, throughOver = false): Played {
   const t0 = performance.now();
   const trace: { frame: number; checksum: number }[] = [];
   let f = 0;
-  for (; f < frames && !run.over(); f++) {
+  for (; f < frames && (throughOver || !run.over()); f++) {
     run.step(source.at(f));
     if (every > 0 && (f + 1) % every === 0) trace.push({ frame: f + 1, checksum: run.checksum() });
   }
@@ -37,7 +39,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 +49,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), args.throughOver === true);
   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"),
   );
@@ -60,6 +62,7 @@ interface Replay {
   // Encoded inputs as change points.
   inputs: { frame: number; inputs: number[] }[];
   frames: number;
+  throughOver?: boolean;
   checksums: { frame: number; checksum: number }[];
   final: number;
 }
@@ -67,15 +70,15 @@ 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 r = play(run, source, frames, 60);
+  const frames = num("frames", args.frames, 1800, 1);
+  const r = play(run, source, frames, 60, args.throughOver === true);
   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 };
+  const replay: Replay = { version: 1, seed, options, inputs, frames: r.frames, ...(args.throughOver ? { throughOver: true } : {}), 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})`);
 }
@@ -102,7 +105,7 @@ export async function verify(ctx: Ctx, files: string[]): Promise<void> {
         return cur;
       },
     };
-    const r = play(run, source, replay.frames, 60);
+    const r = play(run, source, replay.frames, 60, replay.throughOver === true);
     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 });
   }
@@ -135,13 +138,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 +233,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 +247,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

@@ -1,9 +1,14 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { buildNative, ENGINE, type NativePlatform, vendorDir, vendorStatus } from "../native";
 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);
 
+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 => {
@@ -20,7 +25,14 @@ export async function build(ctx: Ctx, name: string | undefined, release: boolean
     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));
+  if (t.native) {
+    const r = await buildNative(ctx, config.root, config.name, name, t.native);
+    if (ctx.dryRun) return;
+    print(ctx, { target: name, steps: r.steps.map(({ output: _o, ...s }) => s), artifact: r.binary, log: r.log }, (): string => `artifact: ${r.binary}\nlog: ${r.log}`);
+    return;
+  }
+  if (!t.steps) throw new CliError("BAD_CONFIG", `target "${name}" needs "steps" or "native"`, "see dotframe skills get macos", skillFor(name));
+  const steps = (await runSteps(ctx, config.root, t.steps, skillFor(name))).map(({ output: _o, ...s }) => s);
   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"),
@@ -41,7 +53,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;
@@ -92,3 +104,27 @@ export async function device(ctx: Ctx, name: string): Promise<void> {
   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}`);
 }
+
+// Downloads wgpu-native and builds SDL3 into the vendor dir (default ~/.dotframe/vendor). Local only, slow once.
+export async function vendor(ctx: Ctx, platform: string | undefined): Promise<void> {
+  if (platform !== "macos" && platform !== "windows") throw new CliError("MISSING_ARG", "vendor needs macos or windows", "dotframe vendor macos", "macos");
+  const p = platform as NativePlatform;
+  const dir = vendorDir(p);
+  const before = vendorStatus(p);
+  if (before.missing.length === 0) {
+    print(ctx, { platform: p, dir, ready: true }, (): string => `vendor for ${p} is ready in ${dir}`);
+    return;
+  }
+  const command = { label: `vendor ${p}`, argv: ["sh", join(ENGINE, "scripts", "vendor.sh"), p], env: { DOTFRAME_VENDOR: dir } };
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, platform: p, dir, missing: before.missing }, (): string => `would download and build ${before.missing.join(", ")} into ${dir}`);
+    return;
+  }
+  for (const tool of ["curl", "cmake", "unzip", ...(p === "windows" ? ["zig"] : [])]) {
+    if (!which(tool)) throw new CliError("TOOL_MISSING", `${tool} not found`, `brew install ${tool}`, "macos");
+  }
+  await runSteps(ctx, ENGINE, [command], "macos");
+  const after = vendorStatus(p);
+  if (after.missing.length > 0) throw new CliError("VENDOR_MISSING", `vendor.sh finished but ${after.missing.join(", ")} is still missing`, "", "macos");
+  print(ctx, { platform: p, dir, ready: true }, (): string => `vendor for ${p} ready in ${dir}`);
+}

package/cli/commands/snap.ts

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, 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,
@@ -65,9 +67,10 @@ run(sim.window, (p) => {
   });
   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");
+    // After open: agent-browser's daemon is shared, and a viewport set before open can be lost to another session.
+    await ab("set", "viewport", String(sim.window.width), String(sim.window.height));
     // 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++) {
@@ -78,11 +81,32 @@ run(sim.window, (p) => {
     }
     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);
+    let shot = await ab("screenshot", out);
     if (shot.code !== 0) throw new CliError("BROWSER_FAILED", shot.tail);
+    let size = pngSize(out);
+    if (!matches(size, sim.window)) {
+      await ab("set", "viewport", String(sim.window.width), String(sim.window.height));
+      shot = await ab("screenshot", out);
+      size = pngSize(out);
+    }
+    if (!matches(size, sim.window)) {
+      throw new CliError("SNAP_SIZE", `screenshot is ${size.width}x${size.height}, expected ${sim.window.width}x${sim.window.height} (or a device-pixel multiple)`, "close other agent-browser sessions and retry; check agent-browser session list", "core");
+    }
     print(ctx, { out, ...result }, (): string => `frame ${result?.frame} -> ${out} (checksum ${result?.checksum})`);
   } finally {
     await ab("close");
     server.stop(true);
+    rmSync(work, { recursive: true, force: true });
   }
 }
+
+// Width and height from a PNG's IHDR chunk.
+function pngSize(path: string): { width: number; height: number } {
+  const head = readFileSync(path).subarray(16, 24);
+  return { width: head.readUInt32BE(0), height: head.readUInt32BE(4) };
+}
+
+function matches(size: { width: number; height: number }, window: { width: number; height: number }): boolean {
+  const scale = size.width / window.width;
+  return Number.isInteger(scale) && scale >= 1 && size.height === window.height * scale;
+}

package/cli/lib.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
 export class CliError extends Error {
@@ -8,6 +8,8 @@ export class CliError extends Error {
     readonly fix = "",
     readonly skill = "core",
     readonly exit = 1,
+    // Full output of a failed step, when it was too long for the message.
+    readonly log = "",
   ) {
     super(message);
   }
@@ -26,10 +28,11 @@ export function print(ctx: Ctx, data: unknown, human: () => string): void {
 
 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 } }));
+  if (ctx.json) console.log(JSON.stringify({ ok: false, error: { code: e.code, message: e.message, fix: e.fix, skill: e.skill, ...(e.log ? { log: e.log } : {}) } }));
   else {
     console.error(`error ${e.code}: ${e.message}`);
     if (e.fix) console.error(`fix: ${e.fix}`);
+    if (e.log) console.error(`log: ${e.log}`);
     console.error(`guide: dotframe skills get ${e.skill}`);
   }
   process.exit(e.exit);
@@ -48,7 +51,9 @@ export interface Command {
 }
 
 export interface Target {
-  steps: Command[];
+  steps?: Command[];
+  // Native targets built by the CLI itself (staged engine, vendored SDL3 and wgpu-native).
+  native?: import("./native").NativeTarget;
   out?: string;
   app?: string;
   device?: string;
@@ -106,6 +111,8 @@ export interface RunResult {
   code: number;
   ms: number;
   tail: string;
+  // Everything the command printed; kept out of --json output.
+  output: string;
 }
 
 // Runs a command to completion. Output streams to stderr in human mode and is captured (tail kept) in JSON mode.
@@ -128,21 +135,57 @@ export async function exec(ctx: Ctx, root: string, command: Command): Promise<Ru
   };
   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 };
+  const output = chunks.join("");
+  const tail = output.split("\n").slice(-20).join("\n").trim();
+  return { label: command.label, code, ms: Math.round(performance.now() - t0), tail, output };
 }
 
 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 ?? "."})` });
+      results.push({ label: step.label, code: 0, ms: 0, tail: `would run: ${step.argv.join(" ")} (cwd ${step.cwd ?? "."})`, output: "" });
       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);
+    if (r.code !== 0) {
+      // The message keeps the tail; the whole output goes to a log an agent can read.
+      const log = join(root, ".dotframe", "logs", `${step.label.replace(/[^a-z0-9]+/gi, "-")}.log`);
+      mkdirSync(dirname(log), { recursive: true });
+      writeFileSync(log, r.output);
+      const count = r.output.match(/(\d+) errors?/)?.[1];
+      throw new CliError("STEP_FAILED", `step "${step.label}" exited ${r.code}${count ? ` with ${count} errors` : ""}; full output in ${log}\n${r.tail}`, `read ${log}; dotframe doctor checks the toolchain`, skill, 1, log);
+    }
   }
   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}}`;
+}