dotframe 0.1.2 → 0.1.4

package/cli/main.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env bun
 import { parseArgs } from "node:util";
 import pkg from "../package.json" with { type: "json" };
-import { build, deploy, device, relay } from "./commands/ship";
+import { build, deploy, device, relay, vendor } from "./commands/ship";
 import { doctor } from "./commands/doctor";
 import { configCmd } from "./commands/config";
 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
 
@@ -25,7 +25,8 @@ Build and ship
   deploy   <target> [--prod]            gated: --yes, preview with --dry-run
   relay    deploy [--region eze]        gated
   device   install <target>             gated
-  doctor   [--fix]                      toolchain, links, config, signing
+  vendor   <macos|windows>              SDL3 + wgpu-native for native builds (~/.dotframe/vendor)
+  doctor   [--fix]                      toolchain, vendor, links, config, sim render
   config   get [key] | set <key> <json>
 
 Project
@@ -35,6 +36,84 @@ 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] [--through-over] [--json]
+
+Runs the game headless and prints the final state and checksum. It stops when the match is over unless
+--through-over (rematch and results flows). --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] [--through-over]
+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, or for a native target ({"native": {"platform": "macos",
+"entry": "main.native.ts"}}) stages the engine and game in .dotframe/native/<target> and writes dist/<target>/<name>.
+Failures keep the full output in .dotframe/logs and return its path. --release refuses 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.`,
+  vendor: `dotframe vendor <macos|windows> [--dry-run]
+
+Downloads wgpu-native and builds SDL3 for native targets into DOTFRAME_VENDOR (default ~/.dotframe/vendor), which
+survives reinstalling dotframe and is shared by every game.`,
+  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,
@@ -65,15 +144,17 @@ const { values, positionals } = parseArgs({
     template: { type: "string" },
     port: { type: "string" },
     "no-install": { type: "boolean" },
+    "through-over": { type: "boolean" },
   },
 });
 
 const ctx: Ctx = { json: values.json === true, yes: values.yes === true, dryRun: values["dry-run"] === true };
-const v = values as Record<string, string | undefined>;
+const v = { ...(values as Record<string, string | undefined>), throughOver: values["through-over"] === true } as Record<string, string | undefined> & { throughOver: boolean };
 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);
@@ -84,11 +165,12 @@ try {
   else if (command === "deploy") await deploy(ctx, rest[0], values.prod === true);
   else if (command === "relay" && rest[0] === "deploy") await relay(ctx, v.region);
   else if (command === "device" && rest[0] === "install") await device(ctx, rest[1] ?? "ios");
+  else if (command === "vendor") await vendor(ctx, rest[0]);
   else if (command === "doctor") await doctor(ctx, values.fix === true);
   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/native.ts

@@ -0,0 +1,152 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { CliError, type Ctx, exec, home, print, type RunResult, which } from "./lib";
+
+// The engine this CLI belongs to: a git checkout or node_modules/dotframe.
+export const ENGINE = resolve(import.meta.dir, "..");
+
+export type NativePlatform = "macos" | "windows";
+
+export interface NativeTarget {
+  platform: NativePlatform;
+  // Entry module, relative to the game root.
+  entry: string;
+  // Binary name; defaults to the game name.
+  name?: string;
+}
+
+// Vendored SDL3 and wgpu-native: DOTFRAME_VENDOR, else a checkout's own vendor/ when it is populated, else a
+// per-user cache that survives reinstalling the package.
+export function vendorDir(platform: NativePlatform): string {
+  if (process.env.DOTFRAME_VENDOR) return resolve(home(process.env.DOTFRAME_VENDOR));
+  const local = join(ENGINE, "vendor");
+  if (existsSync(join(local, "wgpu", platform))) return local;
+  return join(homedir(), ".dotframe", "vendor");
+}
+
+export interface VendorStatus {
+  dir: string;
+  missing: string[];
+  sdl: string | null;
+}
+
+export function vendorStatus(platform: NativePlatform): VendorStatus {
+  const dir = vendorDir(platform);
+  const sdl = existsSync(dir) ? (readdirSync(dir).find((d: string): boolean => d.startsWith("SDL3-")) ?? null) : null;
+  const need = [`wgpu/${platform}/lib/libwgpu_native.a`, `build/sdl-${platform}/libSDL3.a`];
+  const missing = need.filter((p: string): boolean => !existsSync(join(dir, p)));
+  if (!sdl) missing.push("SDL3-<version> (headers)");
+  return { dir, missing, sdl };
+}
+
+export function vendorFix(platform: NativePlatform): string {
+  return `dotframe vendor ${platform}`;
+}
+
+const SKIP = new Set(["node_modules", ".git", ".dotframe", "dist", "build", ".vercel"]);
+
+function copyTs(from: string, to: string): number {
+  let n = 0;
+  for (const name of readdirSync(from)) {
+    if (SKIP.has(name)) continue;
+    const src = join(from, name);
+    if (statSync(src).isDirectory()) n += copyTs(src, join(to, name));
+    else if (name.endsWith(".ts") || name.endsWith(".json")) {
+      mkdirSync(to, { recursive: true });
+      cpSync(src, join(to, name));
+      n += 1;
+    }
+  }
+  return n;
+}
+
+// scriptc's static build takes relative imports only, and treats anything under node_modules as package code
+// for its dynamic engine. Staging copies the engine and the game side by side and rewrites "dotframe/..."
+// imports to relative paths.
+function rewriteImports(dir: string, engineRoot: string): void {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      rewriteImports(path, engineRoot);
+      continue;
+    }
+    if (!name.endsWith(".ts")) continue;
+    const text = readFileSync(path, "utf8");
+    const next = text.replace(/(from\s+|import\s*\(\s*)(["'])dotframe\/([^"']+)\2/g, (_m: string, head: string, q: string, rest: string): string => {
+      let rel = relative(dirname(path), join(engineRoot, rest));
+      if (!rel.startsWith(".")) rel = `./${rel}`;
+      return `${head}${q}${rel}${q}`;
+    });
+    if (next !== text) writeFileSync(path, next);
+  }
+}
+
+export async function buildNative(ctx: Ctx, root: string, gameName: string, targetName: string, t: NativeTarget): Promise<{ binary: string; log: string; steps: RunResult[] }> {
+  const platform = t.platform;
+  const skill = platform;
+  const tools = platform === "macos" ? ["clang", "scriptc"] : ["zig", "scriptc"];
+  for (const tool of tools) if (!which(tool)) throw new CliError("TOOL_MISSING", `${tool} not found`, tool === "scriptc" ? "npm i -g scriptc" : tool === "zig" ? "brew install zig" : "xcode-select --install", skill);
+  const vendor = vendorStatus(platform);
+  if (vendor.missing.length > 0) throw new CliError("VENDOR_MISSING", `native ${platform} needs SDL3 and wgpu-native in ${vendor.dir}; missing ${vendor.missing.join(", ")}`, vendorFix(platform), skill);
+
+  const stage = join(root, ".dotframe", "native", targetName);
+  const logDir = join(root, ".dotframe", "logs");
+  const log = join(logDir, `build-${targetName}.log`);
+  const out = join(root, "dist", targetName);
+  const binary = join(out, `${t.name ?? gameName}${platform === "windows" ? ".exe" : ""}`);
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, platform, stage, vendor: vendor.dir, binary }, (): string => `would stage the engine and game in ${stage} and build ${binary}`);
+    return { binary, log, steps: [] };
+  }
+  rmSync(stage, { recursive: true, force: true });
+  mkdirSync(logDir, { recursive: true });
+  mkdirSync(out, { recursive: true });
+  const engineStage = join(stage, "dotframe");
+  cpSync(join(ENGINE, "src"), join(engineStage, "src"), { recursive: true });
+  const gameStage = join(stage, "game");
+  copyTs(root, gameStage);
+  rewriteImports(gameStage, engineStage);
+
+  const inc = [`-I${join(vendor.dir, vendor.sdl ?? "", "include")}`, `-I${join(vendor.dir, "wgpu", platform, "include")}`];
+  const lib = join(stage, "lib");
+  mkdirSync(lib, { recursive: true });
+  const cc = platform === "macos" ? ["clang", "-O2", "-mmacosx-version-min=14.0"] : ["zig", "cc", "-target", "x86_64-windows-gnu", "-O2"];
+  const ar = platform === "macos" ? ["ar", "rcs"] : ["zig", "ar", "rcs"];
+  const steps = [
+    ...["df_native", "df_audio"].map((unit) => ({ label: `cc ${unit}`, argv: [...cc, "-c", join(ENGINE, "native", `${unit}.c`), ...inc, "-o", join(lib, `${unit}.o`)] })),
+    { label: "ar libdf_native", argv: [...ar, join(lib, "libdf_native.a"), join(lib, "df_native.o"), join(lib, "df_audio.o")] },
+  ];
+  const ffi = JSON.parse(readFileSync(join(ENGINE, "native", `ffi.${platform}.json`), "utf8")) as { libraries: string[] };
+  ffi.libraries = [join(lib, "libdf_native.a"), join(vendor.dir, "build", `sdl-${platform}`, "libSDL3.a"), join(vendor.dir, "wgpu", platform, "lib", "libwgpu_native.a")];
+  writeFileSync(join(stage, "ffi.json"), JSON.stringify(ffi, null, 2));
+  const entry = join(gameStage, t.entry);
+  if (!existsSync(entry)) throw new CliError("ENTRY_MISSING", `native entry ${t.entry} does not exist`, `add ${t.entry} (see the macos skill) or fix targets.${targetName}.native.entry`, skill);
+  let env: Record<string, string> = {};
+  if (platform === "windows") {
+    // A devDependency of dotframe, so an npm install of dotframe does not bring it; the game can.
+    const pack = [ENGINE, root].map((dir: string): string => join(dir, "node_modules", "@scriptc", "runtime-win32-x64-msvc")).find((p: string): boolean => existsSync(p));
+    if (!pack) throw new CliError("TOOL_MISSING", "the scriptc Windows runtime pack is not installed", "bun add -d @scriptc/runtime-win32-x64-msvc", skill);
+    env = { SCRIPTC_TARGET: "x86_64-windows-gnu", SCRIPTC_RUNTIME_PACK: pack };
+  }
+  const scriptc = {
+    label: "scriptc",
+    argv: ["scriptc", "build", t.entry, "--ffi", join(stage, "ffi.json"), ...(platform === "windows" ? ["--windows-subsystem", "gui"] : []), "-o", binary],
+    cwd: gameStage,
+    env,
+  };
+  const results: RunResult[] = [];
+  const full: string[] = [];
+  for (const step of [...steps, scriptc]) {
+    if (!ctx.json) console.error(`> ${step.label}`);
+    const r = await exec(ctx, root, step);
+    full.push(`> ${step.label}: ${step.argv.join(" ")}\n${r.output}`);
+    writeFileSync(log, full.join("\n"));
+    results.push(r);
+    if (r.code !== 0) {
+      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}`, skill, 1, log);
+    }
+  }
+  return { binary, log, steps: results };
+}

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.4",
   "description": "TS-first game engine and agent-first CLI: one codebase for web, Discord, iOS and native binaries",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,8 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "skills"
+    "skills",
+    "vendor/toolchain"
   ],
   "repository": {
     "type": "git",

package/scripts/vendor.sh

@@ -1,11 +1,13 @@
 #!/bin/sh
 # Downloads wgpu-native prebuilts and builds SDL3 static for a target. Usage: scripts/vendor.sh <macos|windows>
+# DOTFRAME_VENDOR picks the directory (the dotframe CLI uses ~/.dotframe/vendor); default is this checkout's vendor/.
 set -e
 target=$1
 root=$(cd "$(dirname "$0")/.." && pwd)
 wgpu_version=v29.0.1.1
 sdl_version=3.4.16
-vendor="$root/vendor"
+vendor=${DOTFRAME_VENDOR:-$root/vendor}
+toolchain="$root/vendor/toolchain"
 mkdir -p "$vendor/build"
 
 case $target in
@@ -28,7 +30,7 @@ fi
 if [ ! -f "$vendor/build/sdl-$target/libSDL3.a" ]; then
   case $target in
     macos) extra="-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0" ;;
-    windows) extra="-DCMAKE_TOOLCHAIN_FILE=$vendor/toolchain/zig-windows.cmake" ;;
+    windows) extra="-DCMAKE_TOOLCHAIN_FILE=$toolchain/zig-windows.cmake" ;;
   esac
   cmake -S "$vendor/SDL3-$sdl_version" -B "$vendor/build/sdl-$target" -DCMAKE_BUILD_TYPE=Release \
     -DSDL_SHARED=OFF -DSDL_STATIC=ON -DSDL_TEST_LIBRARY=OFF $extra

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
 
@@ -17,6 +17,12 @@ dotframe is a TypeScript game engine. One codebase runs on the web (WebGPU), in
 
 Never claim a visual change works from the JSON alone. Snap it and look.
 
+`sim` and `replay` stop when `over()` turns true. Pass `--through-over` to keep stepping into results and rematch flows.
+
+## agent-browser
+
+`snap` drives agent-browser in its own session (`dotframe-snap`), writes to an absolute path, and checks the PNG size. When you drive agent-browser yourself, always pass `--session <name>` and absolute output paths: one daemon serves the whole machine, so a relative `screenshot out.png` lands in whatever directory the daemon started in (often another repo), and viewports can leak between sessions.
+
 ## Inputs
 
 - `--mash <seed>`: random mashing players, new input every 6 frames. Good default for smoke tests.
@@ -31,6 +37,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/core/references/errors.md

@@ -8,7 +8,7 @@
 | INPUTS_MISSING / BAD_INPUTS | Inputs file missing or a line has the wrong shape | One JSON array or `{frame, inputs}` per line, one input per player |
 | BAD_OPTIONS | `--options` is not a JSON object | Quote it: `--options '{"stocks": 1}'` |
 | UNKNOWN_TARGET | Target not in dotframe.json | Use a listed target or add one |
-| STEP_FAILED | A build step exited non-zero | Read the step output; `dotframe doctor` |
+| STEP_FAILED | A build step exited non-zero | Read the file in `log` (full output); `dotframe doctor` |
 | ASSETS_LOCAL_ONLY | A release would ship unlicensed assets | See `assets` |
 | APPROVAL_REQUIRED (exit 2) | External action without `--yes` | Show the `--dry-run` plan to the human |
 | DEPLOY_SOURCE_DIR | Deploy dir looks like source (repo root, .git, dotframe.json) | Point `out` at the build folder |
@@ -17,6 +17,10 @@
 | DEPLOY_FAILED / INSTALL_FAILED | Provider command failed | Message carries the provider output |
 | TOOL_MISSING | A required CLI is not installed | `dotframe doctor` lists the install command |
 | SNAP_TIMEOUT / SNAP_PAGE_ERROR / BROWSER_FAILED | The snap page did not report ready | Usually no WebGPU in the browser; see message |
+| BAD_ARG / MISSING_ARG | A flag value is not a valid number or duration, or a required flag is missing | Use the value in `fix` |
+| VENDOR_MISSING | Native build without SDL3 or wgpu-native | `dotframe vendor <platform>` |
+| ENTRY_MISSING | The native entry module does not exist | Add `main.native.ts` or fix `native.entry` |
+| SNAP_SIZE | The screenshot size does not match the game window | Close other agent-browser sessions and retry |
 | UNSUPPORTED | The command does not apply (e.g. desync on a 1-player sim) | |
 | REPLAY_MISSING | Replay file not found | `dotframe replay record` |
 | UNKNOWN_SKILL / UNKNOWN_TEMPLATE / UNKNOWN_COMMAND | Typo | Read the `fix` list |

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/macos/SKILL.md

@@ -1,16 +1,45 @@
 ---
 name: macos
-description: Build and run native macOS (and Windows) binaries of a dotframe game with scriptc. Use when compiling natively, benchmarking, or debugging the native backend.
+description: Build and run native macOS (and Windows) binaries of a dotframe game with scriptc. Use when compiling natively, setting up the vendored SDL3 and wgpu-native, reading a native build failure, benchmarking, or debugging the native backend.
 ---
 # macos
 
 ```sh
-dotframe build macos --json
+dotframe vendor macos          # once per machine: wgpu-native + SDL3 into ~/.dotframe/vendor (about 1 minute)
+dotframe doctor                # vendor:<target>, scriptc, zig for windows
+dotframe build macos --json    # dist/macos/<name>
+./dist/macos/<name>            # run from the game root: asset paths are relative to it
 ```
 
-The step runs dotframe's `scripts/build-native.sh macos <entry> <name>`: it compiles the C shim (SDL3 + wgpu-native) and the game with scriptc into one binary with no JavaScript engine. Windows cross-builds with zig (`build-native.sh windows`).
+## Native targets
+
+A target with `"native"` is built by the CLI itself:
+
+```json
+"macos": { "native": { "platform": "macos", "entry": "main.native.ts" } },
+"windows": { "native": { "platform": "windows", "entry": "main.native.ts" } }
+```
+
+The CLI copies the engine (`src/`) and the game's `.ts` and `.json` files into `.dotframe/native/<target>/`, rewrites `dotframe/...` imports to relative paths, compiles the C shim against the vendored SDL3 and wgpu-native, and runs scriptc. This is why it works from `node_modules`: scriptc treats code under `node_modules` as package code for its dynamic engine and takes only relative imports in a static build, so building in place fails.
+
+- Vendor lives in `DOTFRAME_VENDOR`, else a dotframe git checkout's `vendor/` when populated, else `~/.dotframe/vendor`. It survives reinstalling dotframe and is shared by every game.
+- Output goes to the game's `dist/<target>/`, never into `node_modules`.
+- On failure, `error.log` (and the message) points at `.dotframe/logs/build-<target>.log` with the full compiler output. Read it; the message only carries the tail.
+- Windows cross-builds with zig (`brew install zig`), needs `dotframe vendor windows`, and needs scriptc's Windows runtime pack in the game (`bun add -d @scriptc/runtime-win32-x64-msvc`, about 63 MB, so templates leave it out).
+- A target with `"steps"` instead (like Crafter Smash, which vendors dotframe as a submodule) runs its own scripts.
+
+## Code that compiles natively
+
+scriptc compiles a subset of TypeScript. What tripped the templates:
+
+- No `Object.assign` on an existing object: assign fields one by one.
+- Object spread needs every field to have an earlier source: `{ ...c, taken: false }` over a mapped literal fails; build the records explicitly.
+- Structural types become record copies, so engine backends are plain objects of functions, not classes behind interfaces.
+- Keep native-only code in `main.native.ts`; share the rest (see the templates' `src/setup.ts`).
+
+Run `dotframe build macos` early and after each feature: one scriptc error is a quick fix, ninety are a port.
+
+## Other notes
 
-- Games may need env vars at run time (Crafter Smash: `CHARS=railly,anthony SMASH_ROOT=<repo> DOTFRAME=<repo>/vendor/dotframe`).
 - Benchmarks mean nothing while other processes load the machine. Check `top` first and say what else was running.
 - Hidden or occluded windows skip frames and can spin a core. Keep test windows visible.
-- scriptc compiles a subset of TypeScript: structural types become record copies, so engine backends are plain objects of functions, not classes behind interfaces.

package/skill-data/netplay/SKILL.md

@@ -16,7 +16,9 @@ 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).
+
+Long runs: rendering on the stub costs whatever the game's render costs. `--renders 0` speeds desync up but turns off the render purity half of the check; use it for rollback depth or latency sweeps, and keep at least one run with renders. `dotframe doctor` also checks render purity on its own, in about a second.
 
 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,13 +3,12 @@
   "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__" }
-    }
+    },
+    "macos": { "native": { "platform": "macos", "entry": "main.native.ts" } },
+    "windows": { "native": { "platform": "windows", "entry": "main.native.ts" } }
   },
   "assets": { "localOnly": [] }
 }

package/templates/_base/main.native.ts

@@ -0,0 +1,6 @@
+// Native entry for dotframe build macos|windows. The CLI stages it with the engine and compiles it with scriptc.
+import { run } from "dotframe/src/native/run";
+import { WINDOW } from "./src/game";
+import { createSetup } from "./src/setup";
+
+await run(WINDOW, createSetup());

package/templates/_base/main.web.ts

@@ -1,27 +1,5 @@
-import { createDraw2D } from "dotframe/src/draw2d";
-import type { Frame } from "dotframe/src/gpu";
-import { Key } from "dotframe/src/input";
-import type { Platform } from "dotframe/src/platform";
 import { run } from "dotframe/src/web/run";
-import { createGame, keyInput, PLAYERS, render, step, WINDOW } from "./src/game";
+import { WINDOW } from "./src/game";
+import { createSetup } from "./src/setup";
 
-const STEP = 1 / 60;
-
-await run(WINDOW, ({ gpu, input }: Platform): Frame => {
-  const draw = createDraw2D(gpu, WINDOW.width, WINDOW.height);
-  const game = createGame(Math.floor(Math.random() * 1e9));
-  let simulated = -1;
-  return (time: number): boolean => {
-    if (simulated < 0) simulated = time;
-    // Fixed 60 Hz steps, so the browser plays exactly what dotframe sim simulates.
-    for (let n = 0; simulated + STEP <= time && n < 5; n++) {
-      const keys = [keyInput(input, [Key.A, Key.D, Key.W, Key.J]), keyInput(input, [Key.Left, Key.Right, Key.Up, Key.L])];
-      step(game, keys.slice(0, PLAYERS));
-      simulated += STEP;
-    }
-    draw.begin();
-    render(game, draw);
-    draw.end({ r: 0, g: 0, b: 0 });
-    return true;
-  };
-});
+await run(WINDOW, createSetup());