dotframe 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.8
+
+From dogfood round 7 (Craft Ones on 0.1.7).
+
+- `doctor` sim:math skips files marked `// dotframe-allow-math-file`, for render-only files the sim reaches because it builds the renderer.
+- `deploy init` pins images: bun from `packageManager` (game or repo root, else the local bun) and the relay's dotframe from the version installed in the game.
+- The vendor fix (doctor and native builds) names `DOTFRAME_VENDOR` for reusing an existing vendor dir.
+
+## 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.

package/cli/commands/docker.ts

@@ -0,0 +1,204 @@
+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();
+}
+
+interface Versions {
+  bun: string;
+  dotframe: string;
+}
+
+// Pinned versions, so an image built tomorrow is the image built today: bun from packageManager (the game's
+// package.json, then the repo root's), else the bun running this CLI; dotframe as installed in the game.
+function versions(gameRoot: string, repo: string): Versions {
+  let bun = Bun.version;
+  for (const dir of [gameRoot, repo]) {
+    const file = join(dir, "package.json");
+    if (!existsSync(file)) continue;
+    const manager = (JSON.parse(readFileSync(file, "utf8")) as { packageManager?: string }).packageManager ?? "";
+    const match = manager.match(/^bun@(\d+\.\d+\.\d+)/);
+    if (match) {
+      bun = match[1];
+      break;
+    }
+  }
+  const installed = join(gameRoot, "node_modules", "dotframe", "package.json");
+  const dotframe = existsSync(installed) ? (JSON.parse(readFileSync(installed, "utf8")) as { version: string }).version : pkg.version;
+  return { bun, dotframe };
+}
+
+// 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, v: Versions): 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:${v.bun} 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:${v.bun}-alpine
+WORKDIR /app
+# The dotframe version the game has installed; bump it together with the game's.
+RUN bun add dotframe@${v.dotframe}
+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) || ".", versions(config.root, 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,51 @@ 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`, or a whole render-only file with `// dotframe-allow-math-file`. (The sim module builds the
+// renderer for desync's purity check, so render files are reachable and a static scan cannot tell them apart.)
+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;
+    const text = readFileSync(file, "utf8");
+    if (text.includes("dotframe-allow-math-file")) continue;
+    text
+      .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, or a render-only file with // dotframe-allow-math-file",
+  };
+}

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");