dotframe 0.1.5 → 0.1.7

package/cli/ios.ts

@@ -0,0 +1,271 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { CliError, type Ctx, exec, print, type RunResult, which } from "./lib";
+import { ENGINE, sdlLibrary, stageGame, vendorFix, vendorStatus } from "./native";
+
+export interface IosTarget {
+  platform: "ios";
+  // Entry module exporting init(base: string): void and frame(time: number): boolean (see the ios skill).
+  entry: string;
+  bundleId: string;
+  team: string;
+  // PNG, any size; scaled to the 1024 px App Store icon.
+  icon?: string;
+  orientation?: "landscape" | "portrait";
+  // Folder bundled under <app>/game/<assets>; the engine fonts go under <app>/game/dotframe/assets/fonts.
+  assets?: string;
+  // Home screen name; defaults to the game name.
+  displayName?: string;
+}
+
+const SKILL = "ios";
+
+async function scriptcVersion(ctx: Ctx, root: string): Promise<string> {
+  const r = await exec({ ...ctx, json: true }, root, { label: "scriptc version", argv: ["scriptc", "--version"] });
+  return r.output.trim();
+}
+
+// scriptc's iOS runtime pack must match the compiler. Looked up in the game, the engine, then ~/.dotframe/scriptc-ios.
+export async function iosRuntimePack(ctx: Ctx, root: string): Promise<{ path: string | null; want: string; found: string | null }> {
+  const want = await scriptcVersion(ctx, root);
+  const dirs = [root, ENGINE, join(homedir(), ".dotframe", "scriptc-ios")];
+  for (const dir of dirs) {
+    const pack = join(dir, "node_modules", "@scriptc", "runtime-ios-arm64");
+    if (!existsSync(join(pack, "package.json"))) continue;
+    const found = (JSON.parse(await Bun.file(join(pack, "package.json")).text()) as { version: string }).version;
+    return { path: found === want ? pack : null, want, found };
+  }
+  return { path: null, want, found: null };
+}
+
+export function iosPackFix(want: string): string {
+  // Fresh scriptc releases trip bun's minimum release age for a couple of days.
+  return `mkdir -p ~/.dotframe/scriptc-ios && cd ~/.dotframe/scriptc-ios && bun add @scriptc/runtime-ios-arm64@${want} --minimum-release-age 0`;
+}
+
+function identifier(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "") || "game";
+}
+
+function scheme(name: string): string {
+  return name.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("") || "Game";
+}
+
+function hostC(id: string, display: string): string {
+  return `// iOS host for ${display}, generated by dotframe build ios. SDL3 owns the app lifecycle through main callbacks
+// and drives the scriptc library: init once with the bundle's game folder, then frame per display refresh.
+#define SDL_MAIN_USE_CALLBACKS 1
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+#include <stdint.h>
+#include <string.h>
+
+void ${id}_runtime_init(void);
+int32_t ${id}_register_callbacks(void);
+void ${id}_init(const uint8_t *base, int64_t base_len);
+uint8_t ${id}_frame(double time);
+void df_handle_event(const SDL_Event *event);
+void df_close(void);
+
+static Uint64 g_start;
+
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char **argv) {
+  (void)appstate;
+  (void)argc;
+  (void)argv;
+  ${id}_runtime_init();
+  int32_t failed = ${id}_register_callbacks();
+  if (failed != 0) {
+    SDL_Log("${id}: %d callbacks failed to register", failed);
+    return SDL_APP_FAILURE;
+  }
+  const char *bundle = SDL_GetBasePath();
+  if (!bundle) return SDL_APP_FAILURE;
+  char base[4096];
+  SDL_snprintf(base, sizeof base, "%sgame", bundle);
+  ${id}_init((const uint8_t *)base, (int64_t)strlen(base));
+  g_start = SDL_GetTicksNS();
+  return SDL_APP_CONTINUE;
+}
+
+SDL_AppResult SDL_AppIterate(void *appstate) {
+  (void)appstate;
+  double time = (double)(SDL_GetTicksNS() - g_start) / 1e9;
+  return ${id}_frame(time) ? SDL_APP_CONTINUE : SDL_APP_SUCCESS;
+}
+
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event) {
+  (void)appstate;
+  df_handle_event(event);
+  return event->type == SDL_EVENT_QUIT ? SDL_APP_SUCCESS : SDL_APP_CONTINUE;
+}
+
+void SDL_AppQuit(void *appstate, SDL_AppResult result) {
+  (void)appstate;
+  (void)result;
+  df_close();
+}
+
+// scriptc library mode references the promise runtime from bytes IO but ships none; library mode has no async.
+void scr_promise_settled_ref(void) { SDL_assert_always(!"scriptc promise in library mode"); }
+void scr_promise_settled_void(void) { SDL_assert_always(!"scriptc promise in library mode"); }
+`;
+}
+
+function infoPlist(display: string, orientation: "landscape" | "portrait"): string {
+  const orientations =
+    orientation === "portrait"
+      ? ["UIInterfaceOrientationPortrait"]
+      : ["UIInterfaceOrientationLandscapeLeft", "UIInterfaceOrientationLandscapeRight"];
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDisplayName</key><string>${display}</string>
+  <key>CFBundleExecutable</key><string>$(EXECUTABLE_NAME)</string>
+  <key>CFBundleIdentifier</key><string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+  <key>CFBundleName</key><string>$(PRODUCT_NAME)</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>0.1</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>LSRequiresIPhoneOS</key><true/>
+  <key>UIRequiresFullScreen</key><true/>
+  <key>UIStatusBarHidden</key><true/>
+  <key>UIViewControllerBasedStatusBarAppearance</key><false/>
+  <key>UILaunchScreen</key><dict/>
+  <key>UISupportedInterfaceOrientations</key>
+  <array>
+${orientations.map((o) => `    <string>${o}</string>`).join("\n")}
+  </array>
+</dict>
+</plist>
+`;
+}
+
+function projectYml(o: { name: string; id: string; bundleId: string; team: string; vendor: string; sdl: string; lib: string; icon: boolean }): string {
+  const frameworks = ["UIKit", "Foundation", "Metal", "QuartzCore", "AVFoundation", "AudioToolbox", "CoreAudio", "CoreBluetooth", "CoreGraphics", "CoreHaptics", "CoreMotion", "GameController", "IOSurface", "UniformTypeIdentifiers", "CoreMedia", "CoreVideo", "OpenGLES"];
+  return `name: ${o.name}
+options:
+  deploymentTarget:
+    iOS: "17.0"
+targets:
+  ${o.name}:
+    type: application
+    platform: iOS
+    sources:
+      - path: host/main.c
+      - path: ${o.id}_glue.c
+      - path: ${join(ENGINE, "native", "df_native.c")}
+      - path: ${join(ENGINE, "native", "df_audio.c")}
+      - path: game
+        type: folder
+        buildPhase: resources
+${o.icon ? "      - path: Assets.xcassets\n" : ""}    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: ${o.bundleId}
+        DEVELOPMENT_TEAM: ${o.team}
+        CODE_SIGN_STYLE: Automatic
+        INFOPLIST_FILE: host/Info.plist
+${o.icon ? "        ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon\n" : ""}        TARGETED_DEVICE_FAMILY: "1,2"
+        HEADER_SEARCH_PATHS:
+          - ${join(o.vendor, o.sdl, "include")}
+          - ${join(o.vendor, "wgpu", "ios", "include")}
+          - ${join(ENGINE, "native")}
+        OTHER_LDFLAGS:
+          - ${o.lib}
+          - ${join(o.vendor, sdlLibrary("ios"))}
+          - ${join(o.vendor, "wgpu", "ios", "lib", "libwgpu_native.a")}
+          - -lc++
+          - -liconv
+        GCC_WARN_INHIBIT_ALL_WARNINGS: YES
+        ENABLE_BITCODE: NO
+    dependencies:
+${frameworks.map((f) => `      - sdk: ${f}.framework`).join("\n")}
+`;
+}
+
+export async function buildIos(ctx: Ctx, root: string, gameName: string, targetName: string, t: IosTarget): Promise<{ app: string; log: string; steps: RunResult[] }> {
+  for (const tool of ["scriptc", "xcodegen", "xcodebuild", "sips"]) {
+    if (!which(tool)) throw new CliError("TOOL_MISSING", `${tool} not found`, tool === "xcodegen" ? "brew install xcodegen" : tool === "scriptc" ? "npm i -g scriptc" : "install Xcode", SKILL);
+  }
+  for (const key of ["entry", "bundleId", "team"] as const) {
+    if (!t[key]) throw new CliError("BAD_CONFIG", `targets.${targetName}.native.${key} is required for iOS`, `dotframe config set targets.${targetName}.native.${key} '"..."'`, SKILL);
+  }
+  if (!existsSync(join(root, t.entry))) throw new CliError("ENTRY_MISSING", `iOS entry ${t.entry} does not exist`, "add it (see the ios skill: export init and frame)", SKILL);
+  const vendor = vendorStatus("ios");
+  if (vendor.missing.length > 0) throw new CliError("VENDOR_MISSING", `iOS needs SDL3 and wgpu-native in ${vendor.dir}; missing ${vendor.missing.join(", ")}`, vendorFix("ios"), SKILL);
+  const pack = await iosRuntimePack(ctx, root);
+  if (!pack.path) {
+    throw new CliError("TOOL_MISSING", pack.found ? `scriptc iOS runtime pack is ${pack.found}, scriptc is ${pack.want}` : `scriptc iOS runtime pack ${pack.want} not found`, iosPackFix(pack.want), SKILL);
+  }
+
+  const display = t.displayName ?? gameName;
+  const id = identifier(gameName);
+  const name = scheme(display);
+  const stage = join(root, ".dotframe", "native", targetName);
+  const out = join(root, "dist", targetName);
+  const app = join(out, `${name}.app`);
+  const logDir = join(root, ".dotframe", "logs");
+  const log = join(logDir, `build-${targetName}.log`);
+  if (ctx.dryRun) {
+    print(ctx, { dryRun: true, platform: "ios", stage, app, scheme: name, bundleId: t.bundleId, team: t.team, runtimePack: pack.path }, (): string => `would stage ${t.entry} in ${stage} and build ${app}`);
+    return { app, log, steps: [] };
+  }
+  rmSync(stage, { recursive: true, force: true });
+  mkdirSync(join(stage, "host"), { recursive: true });
+  mkdirSync(logDir, { recursive: true });
+  const engineStage = join(stage, "dotframe");
+  cpSync(join(ENGINE, "src"), join(engineStage, "src"), { recursive: true });
+  const gameStage = stageGame(root, t.entry, join(stage, "tree"), engineStage);
+  writeFileSync(
+    join(stage, "app.json"),
+    JSON.stringify({ name: id, entry: relative(stage, join(gameStage, t.entry)), exports: [{ export: "init", params: ["string"], returns: "void" }, { export: "frame", params: ["f64"], returns: "bool" }] }, null, 2),
+  );
+  writeFileSync(join(stage, "host", "main.c"), hostC(id, display));
+  writeFileSync(join(stage, "host", "Info.plist"), infoPlist(display, t.orientation ?? "landscape"));
+  // Bundle resources: the game's assets and the engine fonts, under <app>/game.
+  const bundle = join(stage, "game");
+  mkdirSync(bundle, { recursive: true });
+  const assets = t.assets ?? "assets";
+  if (existsSync(join(root, assets))) cpSync(join(root, assets), join(bundle, assets), { recursive: true });
+  cpSync(join(ENGINE, "assets", "fonts"), join(bundle, "dotframe", "assets", "fonts"), { recursive: true });
+
+  const steps: { label: string; argv: string[]; cwd?: string; env?: Record<string, string> }[] = [];
+  if (t.icon) {
+    const icons = join(stage, "Assets.xcassets", "AppIcon.appiconset");
+    mkdirSync(icons, { recursive: true });
+    writeFileSync(join(stage, "Assets.xcassets", "Contents.json"), '{"info":{"author":"xcode","version":1}}\n');
+    writeFileSync(join(icons, "Contents.json"), '{"images":[{"filename":"icon-1024.png","idiom":"universal","platform":"ios","size":"1024x1024"}],"info":{"author":"xcode","version":1}}\n');
+    steps.push({ label: "icon", argv: ["sips", "-z", "1024", "1024", resolve(root, t.icon), "--out", join(icons, "icon-1024.png")] });
+  }
+  steps.push(
+    { label: "library glue", argv: ["bun", join(ENGINE, "tools", "gen-library-glue.ts"), join(stage, "app.json"), stage] },
+    { label: "scriptc library", argv: ["scriptc", "build", "--lib", "--profile", `${id}.profile.json`], cwd: stage, env: { SCRIPTC_TARGET: "aarch64-apple-ios", SCRIPTC_RUNTIME_PACK: pack.path } },
+  );
+  const results: RunResult[] = [];
+  const full: string[] = [];
+  const run = async (step: { label: string; argv: string[]; cwd?: string; env?: Record<string, string> }): Promise<void> => {
+    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);
+    }
+  };
+  for (const step of steps) await run(step);
+  const lib = readdirSync(join(stage, ".scriptc")).find((f: string): boolean => f.endsWith(".lib.a"));
+  if (!lib) throw new CliError("STEP_FAILED", "scriptc produced no .lib.a", `read ${log}`, SKILL, 1, log);
+  writeFileSync(join(stage, "project.yml"), projectYml({ name, id, bundleId: t.bundleId, team: t.team, vendor: vendor.dir, sdl: vendor.sdl ?? "", lib: join(stage, ".scriptc", lib), icon: !!t.icon }));
+  await run({ label: "xcodegen", argv: ["xcodegen", "generate"], cwd: stage });
+  await run({ label: "xcodebuild", argv: ["xcodebuild", "-scheme", name, "-destination", "generic/platform=iOS", "-allowProvisioningUpdates", "-derivedDataPath", join(stage, "derived"), "build", "-quiet"], cwd: stage });
+  const built = join(stage, "derived", "Build", "Products", "Debug-iphoneos", `${name}.app`);
+  if (!existsSync(built)) throw new CliError("STEP_FAILED", `xcodebuild finished but ${built} is missing`, `read ${log}`, SKILL, 1, log);
+  rmSync(app, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+  cpSync(built, app, { recursive: true });
+  return { app, log, steps: results };
+}

package/cli/lib.ts

@@ -53,11 +53,11 @@ export interface Command {
 export interface Target {
   steps?: Command[];
   // Native targets built by the CLI itself (staged engine, vendored SDL3 and wgpu-native).
-  native?: import("./native").NativeTarget;
+  native?: import("./native").NativeTarget | import("./ios").IosTarget;
   out?: string;
   app?: string;
   device?: string;
-  deploy?: { provider: "vercel"; project: string; scope: string };
+  deploy?: { provider: "vercel"; project: string; scope: string } | { provider: "dokploy"; compose: string; dir?: string };
 }
 
 export interface Config {
@@ -68,6 +68,8 @@ export interface Config {
   relay?: { provider: "dokploy"; compose: string } | { provider: "fly"; app: string; config: string; region?: string };
   links?: { path: string; target: string }[];
   assets?: { localOnly?: string[] };
+  // Tools the build needs besides bun (for example ffmpeg); doctor checks them and docker images install them.
+  requires?: string[];
 }
 
 export const CONFIG_FILE = "dotframe.json";

package/cli/main.ts

@@ -3,12 +3,15 @@ import { parseArgs } from "node:util";
 import pkg from "../package.json" with { type: "json" };
 import { build, deploy, device, relay, vendor } from "./commands/ship";
 import { doctor } from "./commands/doctor";
+import { deployInit } from "./commands/docker";
 import { configCmd } from "./commands/config";
 import { desync, record, sim, verify } from "./commands/play";
 import { snap } from "./commands/snap";
+import { playOnline } from "./commands/online";
 import { skills } from "./commands/skills";
 import { create, dev } from "./commands/new";
-import { CliError, type Ctx, fail, num } from "./lib";
+import { CliError, type Ctx, fail, num, print } from "./lib";
+import { startRelay } from "./relay";
 
 const HELP = `dotframe ${pkg.version}: build, test, and export dotframe games
 
@@ -18,15 +21,18 @@ Play (headless, deterministic)
   sim      [--inputs f.jsonl | --mash <seed>] [--frames 600] [--seed 1] [--options json] [--every n]
   snap     --frame <n> [--out frame.png] [--inputs f | --mash <seed>] [--seed 1] [--options json]
   replay   record <file> | verify <file...>
+  play     --online [room] [--frames 600]   two browsers, local relay, scripted match
   desync   [--latency 100ms] [--jitter 0ms] [--delay 2] [--frames 1800] [--renders 3]
 
 Build and ship
   build    <target> [--release]         targets come from dotframe.json
   deploy   <target> [--prod]            gated: --yes, preview with --dry-run
+  deploy   init <target> --provider dokploy [--compose id]   Dockerfiles, nginx, compose
+  relay    serve [--port 8787]          local netplay relay (same protocol as production)
   relay    deploy [--region eze]        gated
   device   install <target>             gated
   vendor   <macos|windows>              SDL3 + wgpu-native for native builds (~/.dotframe/vendor)
-  doctor   [--fix]                      toolchain, vendor, links, config, sim render
+  doctor   [--fix] [--docker]           toolchain, vendor, links, config, sim render and math
   config   get [key] | set <key> <json>
 
 Project
@@ -68,6 +74,11 @@ Compares checksums every frame and the full inspect() state every --every frames
 Warns when rollbacks exceed the sim's rollbackWindow.
 
   dotframe desync --latency 474ms --jitter 40ms --mash 42 --json`,
+  play: `dotframe play --online [room] [--frames 600] [--out .dotframe/play] [--json]
+
+Builds the web target, starts a local relay, and opens two agent-browser sessions on ?room=<room>&relay=...&mash=1|2.
+Waits until both confirm --frames frames, compares their checksums every 30 frames, and saves a screenshot of each.
+The web entry must honor ?room=, ?relay=, ?mash= and publish globalThis.__dotframe (templates do).`,
   build: `dotframe build <target> [--release] [--dry-run] [--json]
 
 Runs targets.<target>.steps from dotframe.json, or for a native target ({"native": {"platform": "macos",
@@ -77,14 +88,23 @@ Failures keep the full output in .dotframe/logs and return its path. --release r
   dotframe build web
   dotframe build ios --release`,
   deploy: `dotframe deploy <target> [--prod] [--dry-run] [--yes] [--json]
+dotframe deploy init <target> --provider dokploy [--compose <id>] [--yes]
+
+provider vercel: uploads targets.<target>.out. provider dokploy: redeploys the compose stack (it builds from the
+pushed branch), waits for the result, and on failure returns the build log. Without --yes it stops with
+APPROVAL_REQUIRED (exit 2); show the --dry-run plan to a human first.
 
-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.
+init writes deploy/Dockerfile.web (installs "requires" tools, builds with dotframe), deploy/Dockerfile.relay
+(dotframe relay serve), deploy/nginx.conf (no-cache index.html) and deploy/compose.yaml (web at /, relay at /relay).
 
-  dotframe deploy web --prod --dry-run`,
-  relay: `dotframe relay deploy [--region eze] [--dry-run] [--yes]
+  dotframe deploy web --prod --dry-run
+  dotframe deploy init web --provider dokploy`,
+  relay: `dotframe relay serve [--port 8787]
+dotframe relay deploy [--region eze] [--dry-run] [--yes]
 
-Redeploys the netplay relay (dokploy) or deploys it to a region (fly). Gated like deploy.`,
+serve runs the netplay relay locally (PORT env or --port): it pairs two clients per ?room= and forwards their
+messages, the protocol connectRelay in dotframe/src/netplay speaks. deploy redeploys the production 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.`,
@@ -92,10 +112,11 @@ Installs targets.<target>.app on targets.<target>.device with devicectl. Gated l
 
 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]
+  doctor: `dotframe doctor [--fix] [--docker] [--json]
 
-Checks tools, dotframe.json, the sim (loads, renders with a stub Draw2D), placeholders, and vendor links.
---fix creates missing vendor symlinks.`,
+Checks tools (including "requires" in dotframe.json), vendor, links, placeholders, the sim (render with a stub
+Draw2D leaves state alone) and platform-dependent math in code the sim reaches. --fix creates missing vendor
+symlinks; --docker builds the dokploy web image locally, as the server would.`,
   config: `dotframe config get [key]
 dotframe config set <key> <json> [--dry-run]
 
@@ -145,6 +166,10 @@ const { values, positionals } = parseArgs({
     port: { type: "string" },
     "no-install": { type: "boolean" },
     "through-over": { type: "boolean" },
+    docker: { type: "boolean" },
+    online: { type: "boolean" },
+    provider: { type: "string" },
+    compose: { type: "string" },
   },
 });
 
@@ -156,17 +181,25 @@ 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 === "play" && values.online === true) await playOnline(ctx, rest[0], { frames: v.frames, out: v.out });
   else if (command === "sim") await sim(ctx, v);
   else if (command === "snap") await snap(ctx, v);
   else if (command === "replay" && rest[0] === "record") await record(ctx, rest[1], v);
   else if (command === "replay" && rest[0] === "verify") await verify(ctx, rest.slice(1));
   else if (command === "desync") await desync(ctx, v);
   else if (command === "build") await build(ctx, rest[0], values.release === true);
+  else if (command === "deploy" && rest[0] === "init") await deployInit(ctx, rest[1], v.provider, v.compose);
   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 === "relay" && rest[0] === "serve") {
+    const port = num("port", v.port, Number(process.env.PORT ?? "8787"), 1);
+    const server = startRelay(port, (line: string): void => console.error(line));
+    print(ctx, { relay: `ws://localhost:${server.port}`, port: server.port }, (): string => `relay listening on ws://localhost:${server.port} (Ctrl+C to stop)`);
+    await new Promise((): void => {});
+  }
   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 === "doctor") await doctor(ctx, values.fix === true, values.docker === 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);

package/cli/native.ts

@@ -6,10 +6,10 @@ import { CliError, type Ctx, exec, home, print, type RunResult, which } from "./
 // 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 type NativePlatform = "macos" | "windows" | "ios";
 
 export interface NativeTarget {
-  platform: NativePlatform;
+  platform: "macos" | "windows";
   // Entry module, relative to the game root.
   entry: string;
   // Binary name; defaults to the game name.
@@ -34,12 +34,17 @@ export interface VendorStatus {
 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 need = [`wgpu/${platform}/lib/libwgpu_native.a`, sdlLibrary(platform)];
   const missing = need.filter((p: string): boolean => !existsSync(join(dir, p)));
   if (!sdl) missing.push("SDL3-<version> (headers)");
   return { dir, missing, sdl };
 }
 
+// Relative to the vendor dir; iOS builds with the Xcode generator.
+export function sdlLibrary(platform: NativePlatform): string {
+  return platform === "ios" ? "build/sdl-ios/Release-iphoneos/libSDL3.a" : `build/sdl-${platform}/libSDL3.a`;
+}
+
 export function vendorFix(platform: NativePlatform): string {
   return `dotframe vendor ${platform}`;
 }
@@ -83,7 +88,7 @@ interface Graph {
 
 // Every source file the entry reaches: relative imports (including ones that leave the game root) and workspace
 // packages. "dotframe/..." is the engine, staged separately.
-function importGraph(entry: string): Graph {
+export function importGraph(entry: string): Graph {
   const files: string[] = [];
   const links = new Map<string, Map<string, string>>();
   const queue = [realpathSync(entry)];
@@ -123,7 +128,7 @@ function rel(fromFile: string, to: string): string {
 // 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 every reached game file side by side, keeping their relative
 // layout, and rewrites "dotframe/..." and workspace imports to relative paths.
-function stageGame(root: string, entry: string, tree: string, engineStage: string): string {
+export function stageGame(root: string, entry: string, tree: string, engineStage: string): string {
   const graph = importGraph(join(root, entry));
   const base = commonDir([realpathSync(root) + sep + "x", ...graph.files]);
   const staged = (file: string): string => join(tree, relative(base, file));

package/cli/relay.ts

@@ -0,0 +1,65 @@
+import type { Server, ServerWebSocket } from "bun";
+
+// Netplay relay: pairs two clients per room and forwards every message to the other one, untouched. Rooms come
+// from the URL (?room=...); in Discord the room is the Activity instance id. Same protocol as connectRelay.
+interface Peer {
+  room: string;
+  slot: number;
+}
+
+export function startRelay(port: number, log: (line: string) => void = (): void => {}): Server<Peer> {
+  const rooms = new Map<string, (ServerWebSocket<Peer> | null)[]>();
+  const send = (ws: ServerWebSocket<Peer> | null, message: object): void => {
+    if (ws) ws.send(JSON.stringify(message));
+  };
+  return Bun.serve<Peer>({
+    port,
+    fetch(request, server) {
+      const url = new URL(request.url);
+      if (url.pathname.endsWith("/health")) return new Response("ok");
+      const room = url.searchParams.get("room") ?? "";
+      if (room === "" || room.length > 128) return new Response("room required", { status: 400 });
+      const peers = rooms.get(room) ?? [null, null];
+      const slot = peers[0] === null ? 0 : peers[1] === null ? 1 : -1;
+      if (slot < 0) return new Response("room full", { status: 409 });
+      if (server.upgrade(request, { data: { room, slot } })) return undefined;
+      return new Response("websocket only", { status: 426 });
+    },
+    websocket: {
+      open(ws) {
+        const peers = rooms.get(ws.data.room) ?? [null, null];
+        // Two sockets can race for the same free slot between fetch and open.
+        if (peers[ws.data.slot] !== null) {
+          const other = peers[1 - ws.data.slot] === null ? 1 - ws.data.slot : -1;
+          if (other < 0) {
+            ws.close(4009, "room full");
+            return;
+          }
+          ws.data.slot = other;
+        }
+        peers[ws.data.slot] = ws;
+        rooms.set(ws.data.room, peers);
+        log(`join room=${ws.data.room} slot=${ws.data.slot}`);
+        send(ws, { t: "hello", slot: ws.data.slot });
+        const other = peers[1 - ws.data.slot];
+        if (other) {
+          send(ws, { t: "peer", here: true });
+          send(other, { t: "peer", here: true });
+        }
+      },
+      message(ws, message) {
+        const peers = rooms.get(ws.data.room);
+        const other = peers ? peers[1 - ws.data.slot] : null;
+        if (other) other.send(message);
+      },
+      close(ws) {
+        const peers = rooms.get(ws.data.room);
+        if (!peers || peers[ws.data.slot] !== ws) return;
+        peers[ws.data.slot] = null;
+        log(`leave room=${ws.data.room} slot=${ws.data.slot}`);
+        send(peers[1 - ws.data.slot], { t: "peer", here: false });
+        if (peers[0] === null && peers[1] === null) rooms.delete(ws.data.room);
+      },
+    },
+  });
+}

package/native/df_native.c

@@ -117,6 +117,9 @@ int32_t df_open(int32_t width, int32_t height, const uint8_t *title, size_t titl
   memcpy(title_buf, title, n);
   title_buf[n] = 0;
 
+  // Touches stay touches: games read input.touches() for them, and a synthesized mouse would also put a phantom
+  // pointer under the finger (on iOS, at the release point), which breaks games that read both.
+  SDL_SetHint(SDL_HINT_TOUCH_MOUSE_EVENTS, "0");
   if (!SDL_Init(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD)) return -1;
   SDL_WindowFlags flags = SDL_WINDOW_HIGH_PIXEL_DENSITY | SDL_WINDOW_RESIZABLE;
 #if defined(__APPLE__)
@@ -227,6 +230,8 @@ static void mouse_relative(double *nx, double *ny) {
 // Field 0 x, 1 y (normalized), 2 buttons (bit 0 left, bit 1 middle, bit 2 right).
 double df_mouse(int32_t field) {
   if (field == 2) {
+    // Clicks in other apps must not reach the game: buttons count only while the window has input focus.
+    if (!(SDL_GetWindowFlags(g_window) & SDL_WINDOW_INPUT_FOCUS)) return 0;
     SDL_MouseButtonFlags flags = SDL_GetGlobalMouseState(NULL, NULL);
     return (flags & SDL_BUTTON_LMASK ? 1 : 0) | (flags & SDL_BUTTON_MMASK ? 2 : 0) | (flags & SDL_BUTTON_RMASK ? 4 : 0);
   }

package/package.json

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

package/scripts/vendor.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# Downloads wgpu-native prebuilts and builds SDL3 static for a target. Usage: scripts/vendor.sh <macos|windows>
+# Downloads wgpu-native prebuilts and builds SDL3 static for a target. Usage: scripts/vendor.sh <macos|windows|ios>
 # DOTFRAME_VENDOR picks the directory (the dotframe CLI uses ~/.dotframe/vendor); default is this checkout's vendor/.
 set -e
 target=$1
@@ -13,7 +13,8 @@ mkdir -p "$vendor/build"
 case $target in
   macos) wgpu_asset=wgpu-macos-aarch64-release ;;
   windows) wgpu_asset=wgpu-windows-x86_64-gnu-release ;;
-  *) echo "usage: $0 <macos|windows>" >&2; exit 2 ;;
+  ios) wgpu_asset=wgpu-ios-aarch64-release ;;
+  *) echo "usage: $0 <macos|windows|ios>" >&2; exit 2 ;;
 esac
 
 if [ ! -f "$vendor/wgpu/$target/lib/libwgpu_native.a" ]; then
@@ -27,12 +28,17 @@ if [ ! -d "$vendor/SDL3-$sdl_version" ]; then
   curl -fsSL "https://github.com/libsdl-org/SDL/releases/download/release-$sdl_version/SDL3-$sdl_version.tar.gz" | tar xz -C "$vendor"
 fi
 
-if [ ! -f "$vendor/build/sdl-$target/libSDL3.a" ]; then
+# iOS builds through the Xcode generator, which puts the archive under Release-iphoneos/.
+sdl_lib="$vendor/build/sdl-$target/libSDL3.a"
+[ "$target" = ios ] && sdl_lib="$vendor/build/sdl-ios/Release-iphoneos/libSDL3.a"
+if [ ! -f "$sdl_lib" ]; then
+  generator=""
   case $target in
     macos) extra="-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0" ;;
     windows) extra="-DCMAKE_TOOLCHAIN_FILE=$toolchain/zig-windows.cmake" ;;
+    ios) extra="-DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=17.0"; generator="-G Xcode" ;;
   esac
-  cmake -S "$vendor/SDL3-$sdl_version" -B "$vendor/build/sdl-$target" -DCMAKE_BUILD_TYPE=Release \
+  cmake -S "$vendor/SDL3-$sdl_version" -B "$vendor/build/sdl-$target" $generator -DCMAKE_BUILD_TYPE=Release \
     -DSDL_SHARED=OFF -DSDL_STATIC=ON -DSDL_TEST_LIBRARY=OFF $extra
-  cmake --build "$vendor/build/sdl-$target" -j 4
+  cmake --build "$vendor/build/sdl-$target" --config Release -j 4
 fi

package/skill-data/core/SKILL.md

@@ -56,6 +56,12 @@ Prove a check can fail before trusting its green: make render change one field o
 
 Pass `--json` and read `ok`. Errors look like `{"ok": false, "error": {"code", "message", "fix", "skill"}}`. Apply `fix`, and when it is not obvious run `dotframe skills get <skill>`. Exit codes: 0 ok, 1 failure, 2 approval required. Full list: `dotframe skills get core --full`.
 
+## Engine modules agents reach for
+
+- `dotframe/src/detmath`: deterministic sin, cos, tan, atan, atan2, exp, log, pow, hypot for simulation code.
+- `dotframe/src/checksum`: a fixed-order checksum over numbers.
+- `dotframe/src/netplay` and `dotframe/src/relay-client`: rollback netplay and the relay connection (see netplay).
+
 ## Other guides
 
 `dotframe skills list`. Load the one that matches the task: netplay, export-web, discord, ios, macos, relay, game-design, assets.

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

@@ -19,3 +19,17 @@ dotframe deploy web --prod --yes     # only after the human approved the plan
 - 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.
+
+## Docker and Dokploy (VPS)
+
+```sh
+dotframe deploy init web --provider dokploy     # deploy/Dockerfile.web, Dockerfile.relay, nginx.conf, compose.yaml
+dotframe doctor --docker                        # builds the web image locally, as the server will
+dotframe config set targets.web.deploy.compose '"<compose id>"'   # vps compose list
+dotframe deploy web --dry-run && dotframe deploy web --yes
+```
+
+- The web image installs the tools in `requires` (dotframe.json, for example `["ffmpeg"]`) and builds with dotframe; the relay image runs `dotframe relay serve`. The build context is the repo root, so monorepo ports see workspace code.
+- In Dokploy, route the domain's `/` to service `web` (port 80) and `/relay` to service `relay` (port 8787). For Discord, map `/` and `/relay` to that host.
+- Dokploy builds the pushed branch, not your working tree: deploy warns about unpushed or uncommitted work. On failure it returns the build log (through `vps compose logs`).
+- Hash bundles with a tool that exists in the image: `shasum` is missing on Debian images (use `sha256sum` or Bun's hashing, as `scripts/build-web.ts` does).