dotframe 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.7
+
+From dogfood rounds 5 and 6 (Craft Ones on iOS, online, and on the VPS).
+
+- Engine: `src/detmath` (sin, cos, tan, atan, atan2, exp, log, pow, hypot from + - * / and sqrt with fdlibm kernels; the same bits on macOS, Linux arm64 and Linux x64) and `src/checksum` (fixed-order number hash).
+- Engine: `src/netplay`, a game-agnostic rollback engine over the Sim contract's shape, and `src/relay-client` (web) for the relay.
+- `relay serve` runs the netplay relay locally; `play --online` drives a scripted match in two browsers through it and compares checksums.
+- `deploy init <target> --provider dokploy` writes the Docker files (web, relay, nginx, compose); `deploy` redeploys through vps and returns the build log on failure. `requires` in dotframe.json lists build tools; `doctor --docker` builds the image locally.
+- Native iOS target: `{"native": {"platform": "ios", ...}}` generates the host, plist, project, glue and icon and runs xcodegen and xcodebuild. `vendor ios`; doctor checks the scriptc iOS runtime pack.
+- `doctor` warns about platform-dependent math in code the sim reaches (`sim:math`).
+- `desync` reports restore cost and warns when it grows with the frame.
+- Native: touches no longer synthesize a mouse (phantom pointer on iOS).
+- Templates: online play through the relay (`?room=`), `main.ios.ts`, an aspect-filling canvas, and snapshot and restore without structuredClone or Object.assign.
+
+## 0.1.6
+
+From the Craft Ones native port.
+
+- Native: mouse buttons read 0 while the window lacks input focus, so clicks in other apps no longer reach the game. The pointer position stays global, so aiming is unchanged.
+- Templates: `src/setup.ts` reads the pointer and touches with a hold-to-charge, release-to-act pattern (a charge meter while holding, a tone on release), on web and native. Each `game.ts` declares the `POINTER_BIT` a release sets.
+- Skills: the macos guide gains "Porting existing TypeScript" (what scriptc rejects and the fix for each, plus runtime traps such as structural coercion copying and out-of-range reads) and "Debugging a native crash" with lldb. Netplay warns against checksums built on `JSON.stringify`.
+
 ## 0.1.5
 
 - Native builds follow the entry's import graph instead of copying the game folder: relative imports that leave the game root and workspace packages that resolve to source are staged with their relative layout and rewritten to relative paths, so ports inside monorepos compile.

package/cli/commands/docker.ts

@@ -0,0 +1,179 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import pkg from "../../package.json" with { type: "json" };
+import { CliError, CONFIG_FILE, type Config, type Ctx, exec, formatJson, gate, loadConfig, print, target, which } from "../lib";
+
+// Web plus relay as a docker compose stack (Dokploy builds it from the git repo): the game at / and the relay at
+// /relay on the same host. Generated once by `deploy init`, then committed and edited like any other source.
+
+const DIR = "deploy";
+
+async function gitRoot(ctx: Ctx, root: string): Promise<string> {
+  const r = await exec({ ...ctx, json: true }, root, { label: "git root", argv: ["git", "rev-parse", "--show-toplevel"] });
+  if (r.code !== 0) throw new CliError("NOT_A_REPO", "Dokploy builds from a git repository, and this game is not in one", "git init, commit, and push to GitHub first", "export-web");
+  return r.output.trim();
+}
+
+// game: the game's path inside the repo ("" at the root); context: the repo root, relative to deploy/.
+function files(config: Config, game: string, out: string, context: string): Record<string, string> {
+  const requires = (config.requires ?? []).filter((t: string): boolean => t !== "bun");
+  const apt = requires.length > 0 ? `RUN apt-get update && apt-get install -y --no-install-recommends ${requires.join(" ")} && rm -rf /var/lib/apt/lists/*\n` : "";
+  const at = game === "" ? "." : game;
+  return {
+    "Dockerfile.web": `# Static web build of ${config.name}, served by nginx. Generated by dotframe deploy init; edit freely.
+FROM oven/bun:1 AS build
+${apt}WORKDIR /app
+COPY . .
+RUN cd ${at} && bun install --frozen-lockfile && bun node_modules/dotframe/cli/main.ts build web
+
+FROM nginx:1.27-alpine
+COPY ${join(at, DIR, "nginx.conf")} /etc/nginx/conf.d/default.conf
+COPY --from=build ${join("/app", at, out)} /usr/share/nginx/html
+EXPOSE 80
+`,
+    "Dockerfile.relay": `# Netplay relay for ${config.name}: dotframe relay serve. Generated by dotframe deploy init.
+FROM oven/bun:1-alpine
+WORKDIR /app
+RUN bun add dotframe@${pkg.version}
+ENV PORT=8787
+EXPOSE 8787
+CMD ["bun", "node_modules/dotframe/cli/main.ts", "relay", "serve"]
+`,
+    "nginx.conf": `server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+  gzip on;
+  gzip_types text/css application/javascript application/json image/svg+xml;
+  gzip_min_length 1024;
+  # The bundle name is content-hashed; index.html must never be cached (Discord caches aggressively).
+  location = /index.html { add_header Cache-Control "no-cache"; }
+  location / { try_files $uri $uri/ /index.html; }
+  location ~* \\.(png|mp3|js|json)$ { expires 7d; add_header Cache-Control "public"; }
+}
+`,
+    "compose.yaml": `# ${config.name}: the game at / and the netplay relay at /relay on the same host. In Dokploy, point the domain's
+# / at service web (port 80) and /relay at service relay (port 8787).
+services:
+  web:
+    build:
+      context: ${context}
+      dockerfile: ${join(at, DIR, "Dockerfile.web")}
+    restart: unless-stopped
+    expose:
+      - "80"
+  relay:
+    build:
+      context: .
+      dockerfile: Dockerfile.relay
+    restart: unless-stopped
+    environment:
+      PORT: "8787"
+    expose:
+      - "8787"
+`,
+    ".dockerignore": "**/node_modules\n**/dist\n**/.dotframe\n.git\n",
+  };
+}
+
+export async function deployInit(ctx: Ctx, name: string | undefined, provider: string | undefined, compose: string | undefined): Promise<void> {
+  if (!name) throw new CliError("MISSING_ARG", "deploy init needs a target", "dotframe deploy init web --provider dokploy", "export-web");
+  if (provider !== "dokploy") throw new CliError("UNSUPPORTED", `deploy init supports --provider dokploy (got ${provider ?? "none"}); vercel needs no files`, "dotframe deploy init web --provider dokploy", "export-web");
+  const config = loadConfig();
+  const t = target(config, name);
+  if (!t.out) throw new CliError("NO_OUT", `target "${name}" needs an out dir`, "", "export-web");
+  const repo = await gitRoot(ctx, config.root);
+  const game = relative(repo, config.root);
+  // compose.yaml sits in <game>/deploy; the web build context is the repo root, so workspace code is visible.
+  const generated = files(config, game, t.out, relative(join(config.root, DIR), repo) || ".");
+  const dir = join(config.root, DIR);
+  const written = Object.keys(generated).map((f: string): string => join(DIR, f));
+  const existing = written.filter((f: string): boolean => existsSync(join(config.root, f)));
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, files: written, existing }, (): string => `would write ${written.join(", ")}${existing.length ? ` (overwrites ${existing.join(", ")})` : ""}`);
+    return;
+  }
+  if (existing.length > 0 && !ctx.yes) throw new CliError("EXISTS", `${existing.join(", ")} already exist`, "rerun with --yes to overwrite, or edit them by hand", "export-web");
+  mkdirSync(dir, { recursive: true });
+  for (const [f, text] of Object.entries(generated)) writeFileSync(join(dir, f), text);
+  // The repo-root .dockerignore is the one docker reads for a repo-root context.
+  if (!existsSync(join(repo, ".dockerignore"))) writeFileSync(join(repo, ".dockerignore"), generated[".dockerignore"]);
+  const raw = JSON.parse(readFileSync(join(config.root, CONFIG_FILE), "utf8")) as { targets: Record<string, { deploy?: unknown }> };
+  raw.targets[name].deploy = { provider: "dokploy", compose: compose ?? "", dir: DIR };
+  writeFileSync(join(config.root, CONFIG_FILE), `${formatJson(raw)}\n`);
+  print(ctx, { files: written, next: ["git add deploy dotframe.json && git commit && git push", "create the compose in Dokploy from this repo (compose path below)", `dotframe config set targets.${name}.deploy.compose '"<compose id>"'`] }, (): string =>
+    [`wrote ${written.join(", ")}`, `compose path for Dokploy: ${join(game, DIR, "compose.yaml")}`, `then: dotframe config set targets.${name}.deploy.compose '"<compose id>"' and dotframe deploy ${name}`].join("\n"),
+  );
+}
+
+interface Deployment {
+  id: string;
+  status: string;
+  created: string;
+}
+
+async function vpsJson<T>(ctx: Ctx, root: string, args: string[]): Promise<T> {
+  const r = await exec({ ...ctx, json: true }, root, { label: `vps ${args.join(" ")}`, argv: ["vps", ...args, "--json"] });
+  if (r.code !== 0) throw new CliError("DEPLOY_FAILED", r.tail, "vps doctor; check the profile and API key", "export-web");
+  return JSON.parse(r.output) as T;
+}
+
+export async function deployDokploy(ctx: Ctx, config: Config, name: string, compose: string): Promise<void> {
+  const skill = "export-web";
+  if (!compose) throw new CliError("CONFIG_PLACEHOLDER", `targets.${name}.deploy.compose is empty`, `dotframe config set targets.${name}.deploy.compose '"<compose id>"' (vps compose list)`, skill);
+  for (const f of ["compose.yaml", "Dockerfile.web", "nginx.conf"]) {
+    if (!existsSync(join(config.root, DIR, f))) throw new CliError("NOT_BUILT", `${DIR}/${f} is missing`, `dotframe deploy init ${name} --provider dokploy`, skill);
+  }
+  // Dokploy builds what is on the remote branch, not this working tree.
+  const status = await exec({ ...ctx, json: true }, config.root, { label: "git status", argv: ["git", "status", "--porcelain", "--branch"] });
+  const unpushed = /\[ahead \d+/.test(status.output.split("\n")[0] ?? "");
+  const dirty = status.output.split("\n").slice(1).some((l: string): boolean => l.trim() !== "");
+  const plan = { target: name, provider: "dokploy", compose, command: `vps -y compose redeploy ${compose}`, unpushedCommits: unpushed, uncommittedChanges: dirty };
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, ...plan }, (): string =>
+      [`would redeploy compose ${compose} from the remote branch`, unpushed ? "warning: local commits are not pushed; Dokploy will not see them" : "", dirty ? "warning: uncommitted changes will not deploy" : ""].filter(Boolean).join("\n"),
+    );
+    return;
+  }
+  gate(ctx, `deploy ${name} to Dokploy`, skill);
+  if (!which("vps")) throw new CliError("TOOL_MISSING", "vps CLI not found", "install crafter-station/vps-cli and log in", skill);
+  const before = await vpsJson<Deployment[]>(ctx, config.root, ["compose", "deployments", compose]);
+  const known = new Set(before.map((d: Deployment): string => d.id));
+  const started = await exec({ ...ctx, json: true }, config.root, { label: "vps redeploy", argv: ["vps", "-y", "compose", "redeploy", compose, "--json"] });
+  if (started.code !== 0) throw new CliError("DEPLOY_FAILED", started.tail, "", skill);
+  if (!ctx.json) console.error("> waiting for the Dokploy deployment");
+  // Wait for the new deployment to reach a terminal state; a build failure carries its log.
+  for (;;) {
+    await Bun.sleep(5000);
+    const now = await vpsJson<Deployment[]>(ctx, config.root, ["compose", "deployments", compose]);
+    const fresh = now.find((d: Deployment): boolean => !known.has(d.id));
+    if (!fresh || fresh.status === "running" || fresh.status === "queued") continue;
+    if (fresh.status === "done") {
+      print(ctx, { ...plan, deployment: fresh.id, status: fresh.status }, (): string => `deployed: compose ${compose}, deployment ${fresh.id}`);
+      return;
+    }
+    const logs = await vpsJson<{ log: string }>(ctx, config.root, ["compose", "logs", compose, "--deployment", fresh.id, "--tail", "60"]);
+    const logDir = join(config.root, ".dotframe", "logs");
+    mkdirSync(logDir, { recursive: true });
+    const log = join(logDir, `deploy-${name}.log`);
+    writeFileSync(log, logs.log);
+    throw new CliError("DEPLOY_FAILED", `Dokploy deployment ${fresh.id} ended ${fresh.status}:\n${logs.log.split("\n").slice(-15).join("\n")}`, `read ${log}; reproduce with dotframe doctor --docker`, skill, 1, log);
+  }
+}
+
+// Builds the web image locally: what Dokploy would run, minus the network round trip.
+export async function dockerCheck(ctx: Ctx, config: Config): Promise<{ check: string; ok: boolean; detail: string; fix: string; skill: string }> {
+  const base = { check: "docker:web", skill: "export-web" };
+  const dockerfile = join(config.root, DIR, "Dockerfile.web");
+  if (!existsSync(dockerfile)) return { ...base, ok: false, detail: `${DIR}/Dockerfile.web is missing`, fix: "dotframe deploy init web --provider dokploy" };
+  if (!which("docker")) return { ...base, ok: false, detail: "docker not found", fix: "install Docker Desktop or OrbStack" };
+  const repo = await gitRoot(ctx, config.root);
+  const r = await exec({ ...ctx, json: true }, repo, { label: "docker build", argv: ["docker", "build", "-f", dockerfile, "-t", `${config.name}-web:check`, "."] });
+  if (r.code === 0) return { ...base, ok: true, detail: `${DIR}/Dockerfile.web builds`, fix: "" };
+  const logDir = join(config.root, ".dotframe", "logs");
+  mkdirSync(logDir, { recursive: true });
+  writeFileSync(join(logDir, "docker-web.log"), r.output);
+  const cause = r.output.split("\n").filter((l: string): boolean => /error|not found/i.test(l)).slice(-3).join(" | ");
+  return { ...base, ok: false, detail: `docker build failed: ${cause || "see log"}`, fix: `read ${join(".dotframe", "logs", "docker-web.log")}; missing binaries go in "requires" in dotframe.json` };
+}

package/cli/commands/doctor.ts

@@ -1,14 +1,18 @@
-import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { type Config, type Ctx, findRoot, home, loadConfig, print, which } from "../lib";
 import type { Draw2D } from "../../src/draw2d";
 import type { Sim } from "../../src/sim";
-import { vendorFix, vendorStatus } from "../native";
+import { importGraph, vendorFix, vendorStatus } from "../native";
+import { iosPackFix, iosRuntimePack } from "../ios";
+import { dockerCheck } from "./docker";
 import { firstDifference, flatten, headlessRun, loadSim } from "../simkit";
 
 interface Check {
   check: string;
   ok: boolean;
+  // A finding worth reading that does not fail doctor.
+  warn?: boolean;
   detail: string;
   fix: string;
   skill: string;
@@ -19,7 +23,7 @@ const tool = (bin: string, why: string, fix: string, skill: string): Check => {
   return { check: `tool:${bin}`, ok: path !== null, detail: path ?? `missing (${why})`, fix: path ? "" : fix, skill };
 };
 
-export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
+export async function doctor(ctx: Ctx, fix: boolean, docker = false): Promise<void> {
   const checks: Check[] = [tool("bun", "runs the CLI and the web build", "curl -fsSL https://bun.sh/install | bash", "core")];
   let config: Config | null = null;
   if (!findRoot()) checks.push({ check: "config", ok: false, detail: "no dotframe.json here or above", fix: "cd into a game repo or dotframe new <name>", skill: "core" });
@@ -37,12 +41,16 @@ export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
         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));
+        checks.push(mathCheck(resolve(config.root, config.sim as string)));
       } 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") {
+      if (t.native?.platform === "ios" && t.native.team === "YOUR_TEAM_ID") {
+        checks.push({ check: `ios:${name}`, ok: false, detail: "the iOS team is still the template placeholder", fix: `dotframe config set targets.${name}.native.team '"<Apple team id>"'`, skill: "ios" });
+      }
+      if (t.deploy?.provider === "vercel" && 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" });
       }
     }
@@ -52,6 +60,16 @@ export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
       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"));
+      if (t.native.platform === "ios") {
+        checks.push(tool("xcodegen", "iOS project", "brew install xcodegen", "ios"));
+        const pack = await iosRuntimePack(ctx, config.root);
+        checks.push({ check: `ios-runtime:${name}`, ok: pack.path !== null, detail: pack.path ? `@scriptc/runtime-ios-arm64 ${pack.want}` : pack.found ? `runtime pack ${pack.found} does not match scriptc ${pack.want}` : `@scriptc/runtime-ios-arm64 ${pack.want} not installed`, fix: pack.path ? "" : iosPackFix(pack.want), skill: "ios" });
+      }
+    }
+    for (const bin of config.requires ?? []) checks.push(tool(bin, "listed in requires", `brew install ${bin}`, "export-web"));
+    if (docker) {
+      const dockerized = Object.values(config.targets).some((t) => t.deploy?.provider === "dokploy");
+      checks.push(dockerized ? await dockerCheck(ctx, config) : { check: "docker:web", ok: false, detail: "no target deploys with provider dokploy", fix: "dotframe deploy init web --provider dokploy", skill: "export-web" });
     }
     const targets = Object.keys(config.targets);
     if (targets.some((t: string): boolean => t === "web" || t === "discord")) {
@@ -79,9 +97,9 @@ export async function doctor(ctx: Ctx, fix: boolean): Promise<void> {
       checks.push({ check: `link:${link.path}`, ok, detail, fix: ok ? "" : existsSync(want) ? "dotframe doctor --fix" : `${want} does not exist: run dotframe's scripts/vendor.sh first`, skill: "ios" });
     }
   }
-  const failed = checks.filter((c: Check): boolean => !c.ok);
+  const failed = checks.filter((c: Check): boolean => !c.ok && !c.warn);
   print(ctx, { ok: failed.length === 0, checks }, (): string =>
-    checks.map((c: Check): string => `${c.ok ? "ok  " : "FAIL"} ${c.check}: ${c.detail}${c.fix ? `\n     fix: ${c.fix}` : ""}`).join("\n"),
+    checks.map((c: Check): string => `${c.ok ? "ok  " : c.warn ? "WARN" : "FAIL"} ${c.check}: ${c.detail}${c.fix ? `\n     fix: ${c.fix}` : ""}`).join("\n"),
   );
   if (failed.length > 0) process.exit(1);
 }
@@ -127,3 +145,48 @@ async function renderCheck(sim: Sim, root: string): Promise<Check> {
   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: "" };
 }
+
+// Math.sin and friends differ in the last bits between engines and OSes, so simulation code that calls them drifts
+// between netplay peers and breaks replays on another machine. Render code may use them; mark a line with
+// `dotframe-allow-math` to silence it.
+const NONDETERMINISTIC = /\bMath\.(sin|cos|tan|asin|acos|atan|atan2|sinh|cosh|tanh|asinh|acosh|atanh|exp|expm1|log|log1p|log2|log10|pow|cbrt|hypot)\b|[\w)\]]\s*\*\*\s*[\w(]/;
+
+// The engine's own files (draw2d's arcs, raster2d) are render code, however the game imports them: a vendored
+// submodule, node_modules, or a relative path.
+function engineFile(file: string, cache: Map<string, boolean>): boolean {
+  for (let dir = dirname(file); dirname(dir) !== dir; dir = dirname(dir)) {
+    const known = cache.get(dir);
+    if (known !== undefined) return known;
+    const pkg = join(dir, "package.json");
+    if (existsSync(pkg)) {
+      const isEngine = (JSON.parse(readFileSync(pkg, "utf8")) as { name?: string }).name === "dotframe";
+      cache.set(dir, isEngine);
+      return isEngine;
+    }
+  }
+  return false;
+}
+
+function mathCheck(simFile: string): Check {
+  const base = { check: "sim:math", skill: "netplay" };
+  const hits: string[] = [];
+  const engine = new Map<string, boolean>();
+  for (const file of importGraph(simFile).files) {
+    if (!/\.tsx?$/.test(file) || file.includes(`${sep}node_modules${sep}`) || engineFile(file, engine)) continue;
+    readFileSync(file, "utf8")
+      .split("\n")
+      .forEach((line: string, i: number): void => {
+        const code = line.replace(/\/\/.*$/, "");
+        if (NONDETERMINISTIC.test(code) && !line.includes("dotframe-allow-math")) hits.push(`${relative(process.cwd(), file)}:${i + 1}`);
+      });
+  }
+  if (hits.length === 0) return { ...base, ok: true, detail: "no Math.sin/cos/exp/pow or ** in code the sim reaches", fix: "" };
+  const shown = hits.slice(0, 8).join(", ") + (hits.length > 8 ? `, and ${hits.length - 8} more` : "");
+  return {
+    ...base,
+    ok: false,
+    warn: true,
+    detail: `${hits.length} platform-dependent math call(s) in code the sim reaches: ${shown}`,
+    fix: "use dotframe/src/detmath (dsin, dcos, datan2, dexp, dpow, ...) in simulation code; mark render-only lines with // dotframe-allow-math",
+  };
+}

package/cli/commands/online.ts

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CliError, type Ctx, exec, loadConfig, num, print, runSteps, target, which } from "../lib";
+import { startRelay } from "../relay";
+
+interface Probe {
+  frame: number;
+  confirmed: number;
+  status: string;
+  sums: Record<string, number>;
+}
+
+// Two browsers play one online match through a local relay, each with a scripted masher, and their checksums at
+// every 30th confirmed frame must agree. The game's web entry honors ?room=, ?relay= and ?mash=, and publishes
+// globalThis.__dotframe = { frame, confirmed, status, sums } (the templates do; see the netplay skill).
+export async function playOnline(ctx: Ctx, room: string | undefined, args: { frames?: string; out?: string }): Promise<void> {
+  const skill = "netplay";
+  const config = loadConfig();
+  const t = target(config, "web");
+  if (!t.out) throw new CliError("NO_OUT", "the web target needs an out dir", "", "export-web");
+  if (!which("agent-browser")) throw new CliError("TOOL_MISSING", "agent-browser not found (play drives two browsers)", "npm i -g agent-browser && agent-browser install", skill);
+  const frames = num("frames", args.frames, 600, 60);
+  const name = room ?? `play-${Date.now().toString(36)}`;
+  const outDir = resolve(process.cwd(), args.out ?? ".dotframe/play");
+  await runSteps({ ...ctx, json: true }, config.root, t.steps ?? [], "export-web");
+  const web = resolve(config.root, t.out);
+  const relay = startRelay(0);
+  const server = Bun.serve({
+    port: 0,
+    fetch: (req: Request): Response => {
+      const path = decodeURIComponent(new URL(req.url).pathname);
+      const file = join(web, path === "/" ? "index.html" : path);
+      return existsSync(file) ? new Response(Bun.file(file)) : new Response("not found", { status: 404 });
+    },
+  });
+  const sessions = ["dotframe-play-0", "dotframe-play-1"];
+  const ab = (session: string, ...a: string[]) => exec({ ...ctx, json: true }, config.root, { label: `agent-browser ${a[0]}`, argv: ["agent-browser", "--session", session, ...a] });
+  const read = async (session: string): Promise<Probe | null> => {
+    const r = await ab(session, "eval", "JSON.stringify(globalThis.__dotframe ?? null)");
+    try {
+      const text = JSON.parse(r.tail.trim()) as string;
+      return JSON.parse(text) as Probe | null;
+    } catch {
+      return null;
+    }
+  };
+  try {
+    for (const [i, session] of sessions.entries()) {
+      const url = `http://localhost:${server.port}/?room=${encodeURIComponent(name)}&relay=${encodeURIComponent(`ws://localhost:${relay.port}`)}&mash=${i + 1}`;
+      const opened = await ab(session, "open", url);
+      if (opened.code !== 0) throw new CliError("BROWSER_FAILED", opened.tail, "agent-browser install", skill);
+    }
+    let probes: (Probe | null)[] = [null, null];
+    const started = Date.now();
+    // Wait until both peers confirm `frames` frames, or stop making progress.
+    let last = -1;
+    let lastChange = Date.now();
+    for (;;) {
+      probes = [await read(sessions[0]), await read(sessions[1])];
+      const confirmed = Math.min(...probes.map((p) => p?.confirmed ?? 0));
+      if (confirmed >= frames) break;
+      if (confirmed !== last) {
+        last = confirmed;
+        lastChange = Date.now();
+      }
+      if (Date.now() - lastChange > 20000) {
+        throw new CliError("PLAY_STALLED", `no progress for 20 s: peers at ${probes.map((p) => (p ? `${p.status} ${p.confirmed}` : "no __dotframe")).join(" / ")}`, "the web entry must honor ?room=, ?relay=, ?mash= and publish globalThis.__dotframe (see the netplay skill)", skill);
+      }
+      await Bun.sleep(500);
+    }
+    const [a, b] = probes as Probe[];
+    const compared = Object.keys(a.sums).filter((f: string): boolean => b.sums[f] !== undefined).map(Number).sort((x, y) => x - y);
+    const mismatch = compared.find((f: number): boolean => a.sums[f] !== b.sums[f]);
+    const shots = sessions.map((_s, i) => join(outDir, `peer-${i}.png`));
+    mkdirSync(outDir, { recursive: true });
+    for (const [i, session] of sessions.entries()) {
+      const shot = await ab(session, "screenshot", shots[i]);
+      if (shot.code !== 0 || !existsSync(shots[i])) throw new CliError("BROWSER_FAILED", `screenshot of peer ${i} failed: ${shot.tail}`, "", skill);
+    }
+    const ok = mismatch === undefined && compared.length > 0;
+    print(ctx, { ok, room: name, frames: Math.min(a.confirmed, b.confirmed), compared: compared.length, firstMismatch: mismatch ?? null, seconds: Math.round((Date.now() - started) / 1000), screenshots: shots }, (): string =>
+      [
+        ok ? `in sync: ${compared.length} checksums compared over ${Math.min(a.confirmed, b.confirmed)} confirmed frames` : mismatch !== undefined ? `DESYNC at frame ${mismatch}` : "no checksums to compare",
+        `screenshots: ${shots.join(", ")} (open them and look)`,
+      ].join("\n"),
+    );
+    if (!ok) process.exit(1);
+  } finally {
+    for (const session of sessions) await ab(session, "close");
+    server.stop(true);
+    relay.stop(true);
+  }
+}

package/cli/commands/play.ts

@@ -160,7 +160,7 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
     if (reference.inspect && f % every === 0) truthState.set(f, flatten(reference.inspect()));
   }
 
-  const peer = async (self: number): Promise<{ checksums: number[]; states: Map<number, string>; rollbacks: number; maxDepth: number }> => {
+  const peer = async (self: number): Promise<{ checksums: number[]; states: Map<number, string>; rollbacks: number; maxDepth: number; restores: { frame: number; ms: number }[] }> => {
     const other = 1 - self;
     const noise = lcg(seed * 31 + other);
     // Arrival tick of the remote input for each frame, in order, as the link test does.
@@ -181,6 +181,8 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
     const states = new Map<number, string>();
     let rollbacks = 0;
     let maxDepth = 0;
+    // Time per restore by the frame it restores to: a restore that replays from frame 0 grows with the match.
+    const restores: { frame: number; ms: number }[] = [];
     let next = 0;
     let lastKnown = sim.neutral;
     const stepFrame = (f: number): void => {
@@ -209,12 +211,14 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
       if (rollbackFrom >= 0) {
         rollbacks += 1;
         maxDepth = Math.max(maxDepth, simulated - rollbackFrom);
+        const t0 = performance.now();
         run.restore(snaps[rollbackFrom]);
+        restores.push({ frame: rollbackFrom, ms: performance.now() - t0 });
         for (let f = rollbackFrom; f < simulated; f++) stepFrame(f);
       }
       if (t < frames) stepFrame(t);
     }
-    return { checksums, states, rollbacks, maxDepth };
+    return { checksums, states, rollbacks, maxDepth, restores };
   };
 
   const peers = [await peer(0), await peer(1)];
@@ -239,7 +243,17 @@ export async function desync(ctx: Ctx, args: DesyncArgs): Promise<void> {
     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 =>
+  // Restore cost early vs late in the run (first and last tenth of the rollbacks). Heuristic: when late restores cost
+  // more than twice the early ones, restore probably replays from an earlier point, and real rollbacks will stall
+  // late in a match even though desync passes.
+  const restores = peers[0].restores;
+  const tenth = Math.max(1, Math.floor(restores.length / 10));
+  const mean = (xs: { ms: number }[]): number => xs.reduce((a, r) => a + r.ms, 0) / Math.max(1, xs.length);
+  const restoreMs = { early: mean(restores.slice(0, tenth)), late: mean(restores.slice(-tenth)) };
+  if (restores.length >= 20 && restoreMs.late > 2 * restoreMs.early) {
+    warnings.push(`restore cost grows with the frame: ${restoreMs.early.toFixed(3)} ms early vs ${restoreMs.late.toFixed(3)} ms late; restore should copy a snapshot, not replay`);
+  }
+  print(ctx, { ok, warnings, restoreMs, 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 => {

package/cli/commands/ship.ts

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { buildIos } from "../ios";
+import { deployDokploy } from "./docker";
 import { buildNative, ENGINE, type NativePlatform, vendorDir, vendorStatus } from "../native";
 import { CliError, type Command, type Ctx, exec, gate, loadConfig, print, runSteps, target, which } from "../lib";
 
@@ -25,6 +27,12 @@ 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");
   }
+  if (t.native?.platform === "ios") {
+    const r = await buildIos(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.app, log: r.log }, (): string => `artifact: ${r.app}\nlog: ${r.log}`);
+    return;
+  }
   if (t.native) {
     const r = await buildNative(ctx, config.root, config.name, name, t.native);
     if (ctx.dryRun) return;
@@ -44,16 +52,19 @@ export async function deploy(ctx: Ctx, name: string | undefined, prod: boolean):
   const config = loadConfig();
   const t = target(config, name);
   const skill = skillFor(name);
-  if (!t.deploy || !t.out) throw new CliError("NO_DEPLOY", `target "${name}" has no deploy provider or out dir`, `add "out" and "deploy": {"provider": "vercel", ...} to the target`, skill);
+  if (!t.deploy || !t.out) throw new CliError("NO_DEPLOY", `target "${name}" has no deploy provider or out dir`, `add "out" and "deploy": {"provider": "vercel", ...}, or run dotframe deploy init ${name} --provider dokploy`, skill);
+  // Dokploy builds the image from the repo, so there is no local build folder to check.
+  if (t.deploy.provider === "dokploy") return deployDokploy(ctx, config, name, t.deploy.compose);
+  const vercel = t.deploy;
   const out = resolve(config.root, t.out);
   // The 2026-10-03 incident: deploying the repo root put the wrong game in production.
   if (out === config.root || existsSync(join(out, "dotframe.json")) || existsSync(join(out, ".git"))) {
     throw new CliError("DEPLOY_SOURCE_DIR", `${t.out} looks like source, not a build`, "point out at the built folder (e.g. port/dist/web)", skill);
   }
   if (!existsSync(join(out, "index.html"))) throw new CliError("NOT_BUILT", `${t.out}/index.html is missing`, `dotframe build ${name}`, skill);
-  if (t.deploy.scope === "your-vercel-team") throw new CliError("CONFIG_PLACEHOLDER", `targets.${name}.deploy.scope is still the template placeholder`, `dotframe config set targets.${name}.deploy.scope '"<team>"'`, skill);
-  const argv = ["vercel", "deploy", ...(prod ? ["--prod"] : []), "--yes", "--scope", t.deploy.scope, "--name", t.deploy.project];
-  const plan = { target: name, provider: t.deploy.provider, project: `${t.deploy.scope}/${t.deploy.project}`, dir: out, production: prod, files: countFiles(out), command: argv.join(" ") };
+  if (vercel.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", vercel.scope, "--name", vercel.project];
+  const plan = { target: name, provider: vercel.provider, project: `${vercel.scope}/${vercel.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;
@@ -61,7 +72,7 @@ export async function deploy(ctx: Ctx, name: string | undefined, prod: boolean):
   gate(ctx, `deploy ${name}${prod ? " to production" : ""}`, skill);
   if (!which("vercel")) throw new CliError("TOOL_MISSING", "vercel CLI not found", "npm i -g vercel", skill);
   const r = await exec(ctx, config.root, { label: "vercel deploy", argv, cwd: out });
-  if (r.code !== 0) throw new CliError("DEPLOY_FAILED", r.tail, "vercel whoami; vercel switch " + t.deploy.scope, skill);
+  if (r.code !== 0) throw new CliError("DEPLOY_FAILED", r.tail, "vercel whoami; vercel switch " + vercel.scope, skill);
   const url = r.tail.match(/https:\/\/\S+\.vercel\.app/g)?.pop() ?? null;
   print(ctx, { ...plan, url, ms: r.ms }, (): string => `deployed ${url ?? "(url not found in output)"}`);
 }
@@ -91,8 +102,11 @@ export async function relay(ctx: Ctx, region: string | undefined): Promise<void>
 export async function device(ctx: Ctx, name: string): Promise<void> {
   const config = loadConfig();
   const t = target(config, name);
-  if (!t.app || !t.device) throw new CliError("NO_DEVICE", `target "${name}" needs "app" and "device" in dotframe.json`, "xcrun devicectl list devices", "ios");
-  const app = resolve(config.root, t.app);
+  // Native iOS targets build into dist/<target>/<Scheme>.app; others name the app explicitly.
+  const builtApp = t.native?.platform === "ios" && existsSync(join(config.root, "dist", name)) ? readdirSync(join(config.root, "dist", name)).find((f: string): boolean => f.endsWith(".app")) : undefined;
+  const appPath = t.app ?? (builtApp ? join("dist", name, builtApp) : undefined);
+  if (!appPath || !t.device) throw new CliError("NO_DEVICE", `target "${name}" needs "device" in dotframe.json${appPath ? "" : " and a built app (dotframe build ios)"}`, "xcrun devicectl list devices", "ios");
+  const app = resolve(config.root, appPath);
   const argv = ["xcrun", "devicectl", "device", "install", "app", "--device", t.device, app];
   if (ctx.dryRun) {
     print(ctx, { dryRun: true, command: argv.join(" ") }, (): string => `would run: ${argv.join(" ")}`);
@@ -107,7 +121,7 @@ export async function device(ctx: Ctx, name: string): Promise<void> {
 
 // 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");
+  if (platform !== "macos" && platform !== "windows" && platform !== "ios") throw new CliError("MISSING_ARG", "vendor needs macos, windows or ios", "dotframe vendor macos", "macos");
   const p = platform as NativePlatform;
   const dir = vendorDir(p);
   const before = vendorStatus(p);
@@ -120,7 +134,7 @@ export async function vendor(ctx: Ctx, platform: string | undefined): Promise<vo
     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"] : [])]) {
+  for (const tool of ["curl", "cmake", "unzip", ...(p === "windows" ? ["zig"] : []), ...(p === "ios" ? ["xcodebuild"] : [])]) {
     if (!which(tool)) throw new CliError("TOOL_MISSING", `${tool} not found`, `brew install ${tool}`, "macos");
   }
   await runSteps(ctx, ENGINE, [command], "macos");