dotframe 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0
+
+From Craft Ones' asks (rounds 7 and 8).
+
+- Native textures grow without a cap (it was 256, and iOS aborted with no message past it); `gpu.destroyTexture(texture)` frees one and the bind groups that sample it.
+- iOS: build ios wraps init and frame so a TypeScript throw prints its message and stack before scriptc's trap aborts; `dotframe device logs <target>` copies the newest crash report from the device and summarizes it.
+- Native online play: `dotframe/src/native/relay` (`connectRelayNative`, the same RelayLink as the web, polled per frame) over a WebSocket client in C (NSURLSession on macOS and iOS, WinHTTP on Windows), and `shareText` (share sheet on iOS, clipboard on desktop). `play --online --native` runs a web peer against the macOS build. Inside a scriptc executable, hostnames and TLS do not connect yet (reported to scriptc); IP addresses and localhost do.
+- iOS library callbacks stay under scriptc's 32: the glue registers only the host functions the entry reaches, music and volume are one call, and networking is two.
+- `dotframe/src/ui`: buttons and arrow rows laid out once for drawing and hit-testing, focus, taps from mouse and touch, and a release gate so the press that starts a match does not reach gameplay.
+- Web: `run(window, setup, { fit: "window" })` fills and follows the browser window; `Draw2D.resize`; templates refit on shape changes and use it.
+- `doctor` compile-checks each native target with scriptc (no C, no link), so patterns that only fail natively show up before building for the phone.
+- `deploy init --site <dir> [--path /play/]` serves a static folder at / with the game at a subpath.
+- `dotframe config set vendor <dir>` stores the vendor dir per machine (~/.dotframe/config.json).
+- Fixed: the native templates trapped at startup since 0.1.7 (a setup function passed to run() with a narrower parameter type, and, since 0.1.9, the probe assigning globalThis). The probe no longer touches globalThis (`publishProbe` from `dotframe/src/probe-web` does, on the web), and CI now runs each template binary.
+
 ## 0.1.9
 
 The rest of round 7, which missed the 0.1.8 merge.

package/cli/commands/config.ts

@@ -1,10 +1,28 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { CONFIG_FILE, CliError, type Ctx, formatJson, loadConfig, print } from "../lib";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONFIG_FILE, CliError, type Ctx, formatJson, home, loadConfig, loadUserConfig, print, saveUserConfig, USER_KEYS, userConfigPath } from "../lib";
 
 // Dotted keys: targets.web.deploy.project
 export async function configCmd(ctx: Ctx, args: string[]): Promise<void> {
   const [op, key, value] = args;
+  // Machine paths go to ~/.dotframe/config.json, never into the repo.
+  if (key && (USER_KEYS as readonly string[]).includes(key)) {
+    const user = loadUserConfig();
+    if (op === "get") {
+      print(ctx, { key, value: user.vendor ?? null, file: userConfigPath() }, (): string => user.vendor ?? "(not set)");
+      return;
+    }
+    if (op !== "set" || value === undefined) throw new CliError("MISSING_ARG", `config set ${key} needs a value`, `dotframe config set ${key} ~/Programming/crafter-games/dotframe/vendor`);
+    const dir = resolve(home(value));
+    if (!existsSync(dir)) throw new CliError("BAD_ARG", `${dir} does not exist`, "point at a vendor dir that holds wgpu/ and SDL3-*/");
+    if (ctx.dryRun) {
+      print(ctx, { dryRun: true, key, value: dir, file: userConfigPath() }, (): string => `would set ${key} = ${dir} in ${userConfigPath()}`);
+      return;
+    }
+    saveUserConfig({ ...user, vendor: dir });
+    print(ctx, { key, value: dir, file: userConfigPath() }, (): string => `${key} = ${dir} (${userConfigPath()})`);
+    return;
+  }
   const config = loadConfig();
   const file = join(config.root, CONFIG_FILE);
   const raw = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;

package/cli/commands/docker.ts

@@ -39,7 +39,13 @@ function versions(gameRoot: string, repo: string): Versions {
 }
 
 // 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> {
+// site: a static folder (relative to the game root) served at /, with the game at gamePath (for example "/play/").
+interface Layout {
+  site?: string;
+  gamePath: string;
+}
+
+function files(config: Config, game: string, out: string, context: string, v: Versions, layout: Layout): 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;
@@ -52,7 +58,8 @@ RUN cd ${at} && bun install --frozen-lockfile && bun node_modules/dotframe/cli/m
 
 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
+${layout.site ? `COPY ${join(at, layout.site)} /usr/share/nginx/html
+` : ""}COPY --from=build ${join("/app", at, out)} ${join("/usr/share/nginx/html", layout.gamePath)}
 EXPOSE 80
 `,
     "Dockerfile.relay": `# Netplay relay for ${config.name}: dotframe relay serve. Generated by dotframe deploy init.
@@ -64,20 +71,7 @@ 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"; }
-}
-`,
+    "nginx.conf": nginx(layout),
     "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:
@@ -102,7 +96,28 @@ services:
   };
 }
 
-export async function deployInit(ctx: Ctx, name: string | undefined, provider: string | undefined, compose: string | undefined): Promise<void> {
+function nginx(layout: Layout): string {
+  const sub = layout.gamePath !== "/";
+  const base = layout.gamePath.replace(/\/$/, "");
+  return `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;
+  # Bundles are content-hashed; HTML must never be cached (Discord caches aggressively).
+  location ~ \\.html$ { add_header Cache-Control "no-cache"; }
+${sub ? `  location = ${base} { return 301 ${base}/$is_args$args; }
+  location ${base}/ { try_files $uri $uri/ ${base}/index.html; }
+` : ""}  location / { try_files $uri $uri/ /index.html; }
+  location ~* \\.(png|mp3|js|json|css|woff2|webp|jpg|ico)$ { expires 7d; add_header Cache-Control "public"; }
+}
+`;
+}
+
+export async function deployInit(ctx: Ctx, name: string | undefined, provider: string | undefined, compose: string | undefined, site?: string, path?: string): 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();
@@ -111,7 +126,9 @@ export async function deployInit(ctx: Ctx, name: string | undefined, provider: s
   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));
+  if (site && !existsSync(join(config.root, site))) throw new CliError("BAD_ARG", `--site ${site} does not exist under the game root`, "pass a folder with an index.html, relative to the game root", "export-web");
+  const gamePath = path ? `/${path.replace(/^\/+|\/+$/g, "")}/`.replace("//", "/") : site ? "/play/" : "/";
+  const generated = files(config, game, t.out, relative(join(config.root, DIR), repo) || ".", versions(config.root, repo), { site, gamePath });
   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)));
@@ -125,7 +142,7 @@ export async function deployInit(ctx: Ctx, name: string | undefined, provider: s
   // 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 };
+  raw.targets[name].deploy = { provider: "dokploy", compose: compose ?? "", dir: DIR, ...(site ? { site } : {}), ...(gamePath !== "/" ? { path: gamePath } : {}) };
   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"),

package/cli/commands/doctor.ts

@@ -1,10 +1,10 @@
 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 { CliError, type Config, type Ctx, findRoot, home, loadConfig, print, type Target, which } from "../lib";
 import type { Draw2D } from "../../src/draw2d";
 import type { Sim } from "../../src/sim";
-import { importGraph, vendorFix, vendorStatus } from "../native";
-import { iosPackFix, iosRuntimePack } from "../ios";
+import { buildNative, importGraph, vendorFix, vendorStatus } from "../native";
+import { buildIos, iosPackFix, iosRuntimePack } from "../ios";
 import { dockerCheck } from "./docker";
 import { firstDifference, flatten, headlessRun, loadSim } from "../simkit";
 
@@ -59,6 +59,7 @@ export async function doctor(ctx: Ctx, fix: boolean, docker = false): Promise<vo
     }
     for (const [name, t] of Object.entries(config.targets)) {
       if (!t.native) continue;
+      checks.push(await nativeCheck(ctx, config, name, t.native));
       const v = vendorStatus(t.native.platform);
       checks.push({ check: `vendor:${name}`, ok: v.missing.length === 0, detail: v.missing.length === 0 ? `${v.dir} (${v.sdl})` : `missing in ${v.dir}: ${v.missing.join(", ")}`, fix: v.missing.length === 0 ? "" : vendorFix(t.native.platform), skill: t.native.platform });
       checks.push(tool("scriptc", "native builds", "npm i -g scriptc", t.native.platform));
@@ -196,3 +197,23 @@ function mathCheck(simFile: string): Check {
     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",
   };
 }
+
+// Compiles a native target's TypeScript the way the real build does (staging plus scriptc; for iOS the library),
+// without C or linking: as const tuples and other patterns that work on the web fail here, not on the phone.
+async function nativeCheck(ctx: Ctx, config: Config, name: string, native: NonNullable<Target["native"]>): Promise<Check> {
+  const base = { check: `native:${name}`, skill: native.platform };
+  if (!which("scriptc")) return { ...base, ok: false, detail: "scriptc not found", fix: "npm i -g scriptc" };
+  const quiet = { ...ctx, json: true, dryRun: false };
+  try {
+    const started = performance.now();
+    if (native.platform === "ios") await buildIos(quiet, config.root, config.name, name, native, true);
+    else await buildNative(quiet, config.root, config.name, name, native, true);
+    return { ...base, ok: true, detail: `${native.entry} compiles with scriptc (${Math.round(performance.now() - started)} ms)`, fix: "" };
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    // Missing tools or packs have their own checks; this one is about the code.
+    if (error.code !== "STEP_FAILED") return { ...base, ok: false, detail: error.message.split("\n")[0], fix: error.fix };
+    const first = error.message.split("\n").find((l: string): boolean => /error SC\d+/.test(l)) ?? error.message.split("\n")[0];
+    return { ...base, ok: false, detail: `scriptc rejects ${native.entry}: ${first.replace(/^.*?\.dotframe\/check\/[^/]+\/(game|tree)\//, "")}`, fix: `read ${error.log}; the macos skill lists what scriptc rejects` };
+  }
+}

package/cli/commands/online.ts

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CliError, type Ctx, exec, loadConfig, num, print, runSteps, target, which } from "../lib";
+import { buildNative, type NativeTarget } from "../native";
 import { startRelay } from "../relay";
 
 interface Probe {
@@ -13,7 +14,7 @@ interface Probe {
 // 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; seeds?: string }): Promise<void> {
+export async function playOnline(ctx: Ctx, room: string | undefined, args: { frames?: string; out?: string; seeds?: string; native?: boolean }): Promise<void> {
   const skill = "netplay";
   const config = loadConfig();
   const t = target(config, "web");
@@ -27,6 +28,15 @@ export async function playOnline(ctx: Ctx, room: string | undefined, args: { fra
   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");
+  // --native: peer 1 is the macOS build, launched with DOTFRAME_ROOM, DOTFRAME_RELAY, DOTFRAME_MASH and DOTFRAME_PROBE.
+  let nativeBinary = "";
+  if (args.native) {
+    const entry = Object.entries(config.targets).find(([, target]) => target.native?.platform === "macos");
+    if (!entry) throw new CliError("UNKNOWN_TARGET", "play --native needs a target with native.platform macos", "add \"macos\": {\"native\": {\"platform\": \"macos\", \"entry\": \"main.native.ts\"}}", skill);
+    const [nativeName, nativeTarget] = entry;
+    const built = await buildNative({ ...ctx, json: true }, config.root, config.name, nativeName, nativeTarget.native as NativeTarget);
+    nativeBinary = built.binary;
+  }
   const web = resolve(config.root, t.out);
   const relay = startRelay(0);
   const server = Bun.serve({
@@ -37,7 +47,9 @@ export async function playOnline(ctx: Ctx, room: string | undefined, args: { fra
       return existsSync(file) ? new Response(Bun.file(file)) : new Response("not found", { status: 404 });
     },
   });
-  const sessions = ["dotframe-play-0", "dotframe-play-1"];
+  const sessions = args.native ? ["dotframe-play-0"] : ["dotframe-play-0", "dotframe-play-1"];
+  const probeFile = join(outDir, "native-probe.json");
+  let nativeProcess: ReturnType<typeof Bun.spawn> | null = null;
   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)");
@@ -54,13 +66,30 @@ export async function playOnline(ctx: Ctx, room: string | undefined, args: { fra
       const opened = await ab(session, "open", url);
       if (opened.code !== 0) throw new CliError("BROWSER_FAILED", opened.tail, "agent-browser install", skill);
     }
+    if (args.native) {
+      mkdirSync(outDir, { recursive: true });
+      rmSync(probeFile, { force: true });
+      nativeProcess = Bun.spawn([nativeBinary], {
+        cwd: config.root,
+        env: { ...process.env, DOTFRAME_ROOM: name, DOTFRAME_RELAY: `ws://localhost:${relay.port}`, DOTFRAME_MASH: String(seeds[1]), DOTFRAME_PROBE: probeFile },
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+    }
+    const readNative = (): Probe | null => {
+      try {
+        return JSON.parse(readFileSync(probeFile, "utf8")) as Probe;
+      } catch {
+        return null;
+      }
+    };
     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])];
+      probes = [await read(sessions[0]), args.native ? readNative() : await read(sessions[1])];
       const confirmed = Math.min(...probes.map((p) => p?.confirmed ?? 0));
       if (confirmed >= frames) break;
       if (confirmed !== last) {
@@ -76,20 +105,22 @@ export async function playOnline(ctx: Ctx, room: string | undefined, args: { fra
     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`));
+    // The native peer's window is not captured; its checksums are the comparison.
     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, seeds, frames: Math.min(a.confirmed, b.confirmed), compared: compared.length, firstMismatch: mismatch ?? null, seconds: Math.round((Date.now() - started) / 1000), screenshots: shots }, (): string =>
+    print(ctx, { ok, room: name, seeds, peers: args.native ? ["web", "native macOS"] : ["web", "web"], 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",
+        ok ? `in sync${args.native ? " (web vs native macOS)" : ""}: ${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 {
+    nativeProcess?.kill();
     for (const session of sessions) await ab(session, "close");
     server.stop(true);
     relay.stop(true);

package/cli/commands/ship.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { buildIos } from "../ios";
 import { deployDokploy } from "./docker";
@@ -142,3 +142,59 @@ export async function vendor(ctx: Ctx, platform: string | undefined): Promise<vo
   if (after.missing.length > 0) throw new CliError("VENDOR_MISSING", `vendor.sh finished but ${after.missing.join(", ")} is still missing`, "", "macos");
   print(ctx, { platform: p, dir, ready: true }, (): string => `vendor for ${p} ready in ${dir}`);
 }
+
+interface CrashFile {
+  name: string;
+  metadata: { lastModDate: string };
+}
+
+// The newest crash report of a target's app on the device, summarized: exception, termination, and the crashed
+// thread's frames. iOS keeps reports as <Process>-<date>.ips under systemCrashLogs. Read-only on the device.
+export async function deviceLogs(ctx: Ctx, name: string): Promise<void> {
+  const config = loadConfig();
+  const t = target(config, name);
+  if (!t.device) throw new CliError("NO_DEVICE", `target "${name}" needs "device" in dotframe.json`, "xcrun devicectl list devices", "ios");
+  const builtApp = existsSync(join(config.root, "dist", name)) ? readdirSync(join(config.root, "dist", name)).find((f: string): boolean => f.endsWith(".app")) : undefined;
+  const processName = (t.app ? t.app.split("/").pop() : builtApp)?.replace(/\.app$/, "");
+  if (!processName) throw new CliError("NOT_BUILT", "no built app to name the process", `dotframe build ${name}`, "ios");
+  const logDir = join(config.root, ".dotframe", "logs");
+  mkdirSync(logDir, { recursive: true });
+  const listing = join(logDir, "device-crashes.json");
+  const list = await exec({ ...ctx, json: true }, config.root, { label: "devicectl files", argv: ["xcrun", "devicectl", "device", "info", "files", "--device", t.device, "--domain-type", "systemCrashLogs", "--json-output", listing] });
+  if (list.code !== 0) throw new CliError("DEVICE_UNAVAILABLE", list.tail, "connect and unlock the device; xcrun devicectl list devices", "ios");
+  const files = (JSON.parse(readFileSync(listing, "utf8")) as { result: { files: CrashFile[] } }).result.files;
+  const reports = files
+    .filter((f: CrashFile): boolean => f.name.startsWith(`${processName}-`) && f.name.endsWith(".ips"))
+    .sort((a: CrashFile, b: CrashFile): number => b.metadata.lastModDate.localeCompare(a.metadata.lastModDate));
+  if (reports.length === 0) {
+    print(ctx, { process: processName, crashes: 0 }, (): string => `no crash reports for ${processName} on the device`);
+    return;
+  }
+  const newest = reports[0];
+  const local = join(logDir, newest.name);
+  const copy = await exec({ ...ctx, json: true }, config.root, { label: "devicectl copy", argv: ["xcrun", "devicectl", "device", "copy", "from", "--device", t.device, "--domain-type", "systemCrashLogs", "--source", newest.name, "--destination", local] });
+  if (copy.code !== 0) throw new CliError("DEVICE_UNAVAILABLE", copy.tail, "", "ios");
+  const [, body] = readFileSync(local, "utf8").split(/\n(.*)/s);
+  const report = JSON.parse(body) as {
+    exception?: { type?: string; signal?: string };
+    termination?: { indicator?: string };
+    faultingThread?: number;
+    threads?: { frames: { symbol?: string; imageIndex: number }[] }[];
+    usedImages?: { name?: string }[];
+  };
+  const frames = (report.threads?.[report.faultingThread ?? 0]?.frames ?? [])
+    .slice(0, 12)
+    .map((f) => `${report.usedImages?.[f.imageIndex]?.name ?? "?"}  ${f.symbol ?? "?"}`);
+  const summary = {
+    process: processName,
+    report: local,
+    when: newest.metadata.lastModDate,
+    crashes: reports.length,
+    exception: `${report.exception?.type ?? "?"} ${report.exception?.signal ?? ""}`.trim(),
+    termination: report.termination?.indicator ?? null,
+    frames,
+  };
+  print(ctx, summary, (): string =>
+    [`${processName} crashed ${newest.metadata.lastModDate} (${reports.length} reports on the device)`, `${summary.exception}${summary.termination ? `, ${summary.termination}` : ""}`, ...frames.map((f) => `  ${f}`), `full report: ${local}`, "a dotframe: ... threw line in the device log names a TypeScript error (build ios wraps init and frame)"].join("\n"),
+  );
+}

package/cli/ios.ts

@@ -1,8 +1,8 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, relative, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { CliError, type Ctx, exec, print, type RunResult, which } from "./lib";
-import { ENGINE, sdlLibrary, stageGame, vendorFix, vendorStatus } from "./native";
+import { ENGINE, importGraph, sdlLibrary, stageGame, vendorFix, vendorStatus } from "./native";
 
 export interface IosTarget {
   platform: "ios";
@@ -158,6 +158,7 @@ targets:
       - path: ${o.id}_glue.c
       - path: ${join(ENGINE, "native", "df_native.c")}
       - path: ${join(ENGINE, "native", "df_audio.c")}
+      - path: ${join(ENGINE, "native", "df_ws_apple.m")}
       - path: game
         type: folder
         buildPhase: resources
@@ -178,6 +179,7 @@ ${o.icon ? "        ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon\n" : ""}
           - ${join(o.vendor, "wgpu", "ios", "lib", "libwgpu_native.a")}
           - -lc++
           - -liconv
+        CLANG_ENABLE_OBJC_ARC: YES
         GCC_WARN_INHIBIT_ALL_WARNINGS: YES
         ENABLE_BITCODE: NO
     dependencies:
@@ -185,8 +187,20 @@ ${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"]) {
+// check: stop after the scriptc library (library mode is stricter than an executable build), for doctor.
+// The df* host functions the code reachable from the entry calls (engine files included, since staged imports are
+// relative): only those become library callbacks, because scriptc caps them at 32.
+function usedHostFunctions(entry: string): string[] {
+  const used = new Set<string>();
+  for (const file of importGraph(entry).files) {
+    if (!file.endsWith(".ts") || file.endsWith(`${sep}ffi.ts`)) continue;
+    for (const m of readFileSync(file, "utf8").matchAll(/\b(df[A-Z]\w*)\(/g)) used.add(m[1]);
+  }
+  return [...used].sort();
+}
+
+export async function buildIos(ctx: Ctx, root: string, gameName: string, targetName: string, t: IosTarget, check = false): Promise<{ app: string; log: string; steps: RunResult[] }> {
+  for (const tool of check ? ["scriptc"] : ["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) {
@@ -194,7 +208,7 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
   }
   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);
+  if (vendor.missing.length > 0 && !check) 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);
@@ -203,11 +217,11 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
   const display = t.displayName ?? gameName;
   const id = identifier(gameName);
   const name = scheme(display);
-  const stage = join(root, ".dotframe", "native", targetName);
+  const stage = join(root, ".dotframe", check ? "check" : "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`);
+  const log = join(logDir, `${check ? "check" : "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: [] };
@@ -218,9 +232,41 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
   const engineStage = join(stage, "dotframe");
   cpSync(join(ENGINE, "src"), join(engineStage, "src"), { recursive: true });
   const gameStage = stageGame(root, t.entry, join(stage, "tree"), engineStage);
+  // A throw in library mode becomes a trap that aborts with no message (SIGABRT in SDL_AppInit). The wrapper prints
+  // the error and its stack to stderr, which the device log keeps, before rethrowing.
+  const wrapper = join(gameStage, "dotframe-entry.ts");
+  const gameEntry = `./${t.entry.replace(/\.ts$/, "")}`;
+  writeFileSync(
+    wrapper,
+    `import { frame as gameFrame, init as gameInit } from ${JSON.stringify(gameEntry)};
+
+function report(where: string, error: unknown): void {
+  const detail = error instanceof Error ? \`\${error.message}\\n\${error.stack ?? ""}\` : String(error);
+  console.error(\`dotframe: \${where} threw: \${detail}\`);
+}
+
+export function init(base: string): void {
+  try {
+    gameInit(base);
+  } catch (error) {
+    report("init", error);
+    throw error;
+  }
+}
+
+export function frame(time: number): boolean {
+  try {
+    return gameFrame(time);
+  } catch (error) {
+    report("frame", error);
+    throw error;
+  }
+}
+`,
+  );
   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),
+    JSON.stringify({ name: id, entry: relative(stage, wrapper), 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"));
@@ -232,7 +278,7 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
   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) {
+  if (t.icon && !check) {
     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');
@@ -240,7 +286,7 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
     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: "library glue", argv: ["bun", join(ENGINE, "tools", "gen-library-glue.ts"), join(stage, "app.json"), stage, join(ENGINE, "native", "ffi.macos.json"), usedHostFunctions(wrapper).join(",")] },
     { 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[] = [];
@@ -257,6 +303,7 @@ export async function buildIos(ctx: Ctx, root: string, gameName: string, targetN
     }
   };
   for (const step of steps) await run(step);
+  if (check) return { app, log, steps: results };
   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 }));

package/cli/lib.ts

@@ -57,7 +57,7 @@ export interface Target {
   out?: string;
   app?: string;
   device?: string;
-  deploy?: { provider: "vercel"; project: string; scope: string } | { provider: "dokploy"; compose: string; dir?: string };
+  deploy?: { provider: "vercel"; project: string; scope: string } | { provider: "dokploy"; compose: string; dir?: string; site?: string; path?: string };
 }
 
 export interface Config {
@@ -191,3 +191,31 @@ export function formatJson(value: unknown, indent = "", width = 100): string {
   const entries = Object.entries(value as Record<string, unknown>);
   return `{\n${entries.map(([k, v]) => `${next}${JSON.stringify(k)}: ${formatJson(v, next, width)}`).join(",\n")}\n${indent}}`;
 }
+
+// Per-machine settings (paths that must not go into a repo), in ~/.dotframe/config.json.
+export interface UserConfig {
+  vendor?: string;
+}
+
+export function userConfigPath(): string {
+  return join(process.env.HOME ?? "", ".dotframe", "config.json");
+}
+
+export function loadUserConfig(): UserConfig {
+  const path = userConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as UserConfig;
+  } catch {
+    throw new CliError("BAD_CONFIG", `${path} is not valid JSON`, `fix or delete ${path}`);
+  }
+}
+
+export function saveUserConfig(config: UserConfig): void {
+  const path = userConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+// Keys stored per machine rather than in dotframe.json.
+export const USER_KEYS = ["vendor"] as const;