dotframe 0.1.5 → 0.1.7

package/skill-data/ios/SKILL.md

@@ -1,19 +1,54 @@
 ---
 name: ios
-description: Build and install the iOS target of a dotframe game. Use when building for iPhone, fixing vendor links, signing, or installing on a device.
+description: Build and install the iOS target of a dotframe game. Use when building for iPhone or iPad, writing the iOS entry, setting the bundle id, team, icon or orientation, installing on a device, or debugging touch input on iOS.
 ---
 # ios
 
 ```sh
-dotframe doctor --json               # vendor links, scriptc, xcodegen, xcodebuild
-dotframe doctor --fix                # creates missing vendor symlinks
-dotframe build ios --json            # glue, scriptc library, xcodegen, xcodebuild
+dotframe vendor ios                  # once per machine: SDL3 (Xcode generator) and wgpu-native for iOS
+dotframe doctor                      # vendor:ios, ios-runtime (scriptc pack matching the compiler), team placeholder
+dotframe build ios --json            # dist/ios/<Scheme>.app
 dotframe device install ios --dry-run
-dotframe device install ios --yes    # after approval; phone unlocked and trusted
+dotframe device install ios --yes    # after the human approves; phone unlocked and trusted
 ```
 
-- The iOS build needs SDL3 and wgpu-native iOS builds under `vendor/dotframe/vendor/`. They are local symlinks (`links` in dotframe.json), not in git. `doctor --fix` creates them when the targets exist.
-- Signing uses the team in the Xcode project; `-allowProvisioningUpdates` lets xcodebuild fetch profiles. A locked password manager can fail signing with `failed to fill whole buffer`: ask the human to unlock it and retry.
-- `targets.ios.app` is the built `.app`; `targets.ios.device` comes from `xcrun devicectl list devices`.
-- `build ios --release` refuses assets marked local-only (see `assets`). Debug builds for your own phone are fine.
-- Confirm on the device by asking the human, or with a screenshot if available. A successful install is not a working game.
+## The target
+
+```json
+"ios": { "native": { "platform": "ios", "entry": "main.ios.ts", "bundleId": "run.crafter.mygame", "team": "ABCDE12345",
+                     "icon": "assets/icon.png", "orientation": "landscape", "assets": "assets", "displayName": "My Game" },
+         "device": "<udid from xcrun devicectl list devices>" }
+```
+
+The CLI stages the entry's import graph (like macOS), generates the library glue and profile, builds the scriptc library, generates the SDL3 host (`main.c`), `Info.plist` and `project.yml`, scales `icon` to 1024 px (iOS derives every other size; without `icon` the app has none), copies `assets` to `<app>/game/<assets>` and the engine fonts to `<app>/game/dotframe/assets/fonts`, and runs xcodegen and xcodebuild. Everything generated lives in `.dotframe/native/ios/`; nothing to commit.
+
+## The entry
+
+scriptc library mode: the host calls `init(base)` once with the bundle's game folder and `frame(time)` every refresh. There are no promises, so load assets synchronously with the library platform's `readFile`, `image` and `sound`.
+
+```ts
+import type { Frame } from "dotframe/src/gpu";
+import { openLibraryPlatform } from "dotframe/src/native/library";
+
+let tick: Frame | null = null;
+export function init(base: string): void {
+  const platform = openLibraryPlatform(WINDOW);
+  const png = platform.readFile(`${base}/assets/hero.png`);
+  tick = createSetup(/* ... */)(platform);
+}
+export function frame(time: number): boolean {
+  return tick ? tick(time) : true;
+}
+```
+
+Templates ship this as `main.ios.ts` over the same `src/setup.ts` web and macOS use. A game with async loaders adds a sync variant that takes a `(path) => Uint8Array` reader, or writes one loader against that reader for every target.
+
+## Notes
+
+- The scriptc runtime pack (`@scriptc/runtime-ios-arm64`) must match `scriptc --version`. Right after a scriptc release, bun's minimum release age blocks it; doctor prints the install command with `--minimum-release-age 0`.
+- Touches never synthesize a mouse (SDL_HINT_TOUCH_MOUSE_EVENTS is off), so read `input.touches()` for fingers; `input.pointer()` stays the mouse.
+- Size the logical canvas from `gpu.aspect()` (templates do): a 1280x720 canvas on a 2.16 phone stretches otherwise.
+- Library mode has no `WebSocket`; online play is web only for now (`dotframe/src/relay-client` is web only).
+- Signing is automatic with `team`; a locked password manager can fail signing with `failed to fill whole buffer`: ask the human to unlock it and retry.
+- `build ios --release` refuses assets marked local-only (see `assets`).
+- Confirm on the device by asking the human. A successful install is not a working game.

package/skill-data/macos/SKILL.md

@@ -39,6 +39,33 @@ scriptc compiles a subset of TypeScript. What tripped the templates:
 
 Run `dotframe build macos` early and after each feature: one scriptc error is a quick fix, ninety are a port.
 
+## Porting existing TypeScript
+
+What a real port (Craft Ones, 66 errors) hit, and the fix for each:
+
+| scriptc rejects | Do instead |
+|---|---|
+| `Object.assign(target, ...)` | Assign fields one by one |
+| `ArrayLike<T>` / `Iterable<T>` parameters | Take `T[]` |
+| `readonly T[]`, `.find`/`.filter` on readonly tuples, `for...of` over tuples | Plain arrays (`T[]`), indexed loops |
+| Destructuring an `unknown` network payload | Narrow field by field with `typeof` checks |
+| Non-literal index into a tuple | Make it an array |
+| Dynamic keyed reads on a record whose entries have different shapes | Give every entry the same shape (optional fields), or a `switch` |
+| `string[i]` | `s.charAt(i)` or `s.charCodeAt(i)` |
+| `Number.parseInt` in a static build | `parseInt` or `Math.trunc(Number(s))` |
+| `++`/`--` inside an expression | Its own statement |
+| `satisfies Record<K, Record<string, T>>` | A plain type annotation |
+
+Runtime traps (compile clean, fail when run):
+
+- **Structural coercion copies.** Passing a class instance, or a wider record, to a parameter typed as a narrower structural type passes a copy: the callee's writes to scalar fields are lost (arrays inside still alias). In Craft Ones every projectile froze mid-flight. Pass the exact type, or return the updated record and copy it back. Reported to scriptc.
+- **Out-of-range reads.** `rows[y - 1]?.[x]` typed as `string` but `undefined` at runtime crashes with "undefined is not representable in the target union". Bounds-check before reading.
+- **`JSON.stringify` key order** differed from JavaScript in Craft Ones (not reproduced in a minimal case). Never build checksums or netplay comparisons from it.
+
+## Debugging a native crash
+
+`--optimization dev` builds failed to link in Craft Ones (undefined `_main`; a template game links fine). When that happens, debug the release binary with lldb: `lldb ./dist/macos/<name>`, `breakpoint set -n scr_error_new`, `run`, then `bt` shows the TypeScript call site of a runtime error.
+
 ## Other notes
 
 - Benchmarks mean nothing while other processes load the machine. Check `top` first and say what else was running.

package/skill-data/netplay/SKILL.md

@@ -4,6 +4,19 @@ description: Rollback netplay for dotframe games. Use when building or debugging
 ---
 # netplay
 
+## The engine
+
+`dotframe/src/netplay` is a game-agnostic rollback engine: `createRollback({ sim, transport, localPort, neutral, inputDelay, maxRollback, resimulating })`, where `sim` is anything with `step(inputs)`, `save()`, `restore(s)` and `checksum()` (the Sim contract's shape). Call `tick(localInput)` once per fixed step; it returns whether a frame was simulated. `stats()` has rollbacks, stalls, round trip and the first desynced frame; `sumAt(frame)` gives this peer's checksum.
+
+`dotframe/src/relay-client` (web only) connects to a relay: `connectRelay(url, room)` gives `status()`, `slot()`, game messages (`send`/`receive`) and the `transport` for createRollback. Use `dotframe/src/checksum` for checksums and `dotframe/src/detmath` for any trig, exp, log or pow in simulation code.
+
+```sh
+dotframe relay serve                  # local relay on :8787, same protocol as production
+dotframe play --online --frames 900   # two browsers, scripted match, checksums compared, screenshots saved
+```
+
+`play --online` needs the web entry to honor `?room=`, `?relay=` and `?mash=<seed>` and to publish `globalThis.__dotframe = { frame, confirmed, status, sums }` (sums: checksum per 30th confirmed frame). The templates show it.
+
 dotframe online play is rollback netcode: each peer predicts the remote input (repeat the last one), simulates ahead, and when the real input arrives and differs, restores a snapshot and resimulates. It only works if every peer computes bit-identical state from the same inputs.
 
 ## Test before going online
@@ -30,6 +43,10 @@ Run several seeds and a high latency (474 ms is what a transatlantic relay measu
 
 ## Rules
 
+- Simulation code uses `dotframe/src/detmath` (dsin, dcos, datan2, dexp, dlog, dpow, ...), never `Math.sin` and friends or `**`: those differ in the last bits between engines and operating systems, so peers and replays drift (Craft Ones' replays diverged between macOS and Linux at frame 120). `dotframe doctor` warns about them (`sim:math`); mark render-only lines with `// dotframe-allow-math`. A replay passing on one machine proves nothing about another: run CI on a second OS.
+- `desync` reports `restoreMs` early vs late; it warns when late restores cost more than twice the early ones (a heuristic for restore that replays from an earlier frame, which passes desync but stalls real rollbacks late in a match).
+- Build checksums from numbers in a fixed order, never from `JSON.stringify`: native builds can order keys differently from JavaScript, so a web peer and a native peer would report false desyncs.
+
 - The camera, effects, and HUD timers are simulation state if the simulation ever reads them. Update them once per step, never per drawn frame.
 - Render must restore any random state it uses, or use a separate visual generator.
 - Input delay (`--delay`, default 2) trades latency for fewer rollbacks.

package/src/checksum.ts

@@ -0,0 +1,22 @@
+// A checksum over simulation numbers in a fixed order. Netplay peers compare it every few frames, so it must not
+// depend on object key order (JSON.stringify differs between JavaScript and scriptc builds) or on float printing.
+export interface Checksum {
+  // Adds a number, rounded to `scale` (default 1e-6 resolution) so harmless float noise does not count.
+  add: (value: number) => Checksum;
+  value: () => number;
+}
+
+export function createChecksum(scale = 1e6): Checksum {
+  let h = 2166136261;
+  const sum: Checksum = {
+    add: (value: number): Checksum => {
+      const v = Number.isNaN(value) ? 0x7ff8 : Math.round(value * scale);
+      // Low and high 32 bits, so large values still change the hash.
+      h = Math.imul(h ^ (v | 0), 16777619);
+      h = Math.imul(h ^ Math.floor(v / 4294967296), 16777619);
+      return sum;
+    },
+    value: (): number => h >>> 0,
+  };
+  return sum;
+}

package/src/detmath.ts

@@ -0,0 +1,217 @@
+// Deterministic math for simulation code (from Craft Ones' packages/shared, extended). Math.sin, Math.cos, Math.exp and Math.hypot are not specified to the
+// last bit, and engines differ (JavaScriptCore on macOS and on Linux disagreed and broke the golden replays), so
+// two peers on different platforms would drift apart. These use only +, -, *, / and Math.sqrt, which IEEE 754
+// fixes exactly, with fdlibm's kernels. Accuracy is within a couple of ulps, far below anything a player sees.
+
+const PIO2_HI = 1.5707963267341256; // first 33 bits of pi/2
+const PIO2_LO = 6.077100506506192e-11; // pi/2 - PIO2_HI
+const TWO_OVER_PI = 0.6366197723675814;
+
+// fdlibm __kernel_sin and __kernel_cos on [-pi/4, pi/4].
+function kernelSin(x: number): number {
+  const z = x * x;
+  const v = z * x;
+  const r =
+    0.00833333333332249 +
+    z *
+      (-0.0001984126982985795 +
+        z *
+          (2.7557313707070068e-6 +
+            z * (-2.5050760253406863e-8 + z * 1.58969099521155e-10)));
+  return x + v * (-0.16666666666666632 + z * r);
+}
+
+function kernelCos(x: number): number {
+  const z = x * x;
+  const r =
+    z *
+    (0.0416666666666666 +
+      z *
+        (-0.001388888888887411 +
+          z *
+            (2.480158728947673e-5 +
+              z *
+                (-2.7557314351390663e-7 +
+                  z * (2.087572321298175e-9 + z * -1.1359647557788195e-11)))));
+  const hz = 0.5 * z;
+  const w = 1 - hz;
+  return w + (1 - w - hz + z * r);
+}
+
+// Cody-Waite reduction; game angles stay within a few turns, where it is exact enough.
+function reduce(x: number): { r: number; q: number } {
+  const k = Math.round(x * TWO_OVER_PI);
+  const r = x - k * PIO2_HI - k * PIO2_LO;
+  return { r, q: ((k % 4) + 4) % 4 };
+}
+
+export function dsin(x: number): number {
+  const { r, q } = reduce(x);
+  return q === 0
+    ? kernelSin(r)
+    : q === 1
+      ? kernelCos(r)
+      : q === 2
+        ? -kernelSin(r)
+        : -kernelCos(r);
+}
+
+export function dcos(x: number): number {
+  const { r, q } = reduce(x);
+  return q === 0
+    ? kernelCos(r)
+    : q === 1
+      ? -kernelSin(r)
+      : q === 2
+        ? -kernelCos(r)
+        : kernelSin(r);
+}
+
+// fdlibm exp: x = k*ln2 + r, |r| <= ln2/2, then a rational approximation of e^r.
+const LN2_HI = 0.6931471803691238;
+const LN2_LO = 1.9082149292705877e-10;
+const INV_LN2 = Math.LOG2E;
+export function dexp(x: number): number {
+  if (x > 709) return Number.POSITIVE_INFINITY;
+  if (x < -745) return 0;
+  const k = Math.round(x * INV_LN2);
+  const hi = x - k * LN2_HI;
+  const lo = k * LN2_LO;
+  const r = hi - lo;
+  const t = r * r;
+  const c =
+    r -
+    t *
+      (0.16666666666666602 +
+        t *
+          (-0.0027777777777015593 +
+            t *
+              (6.613756321437934e-5 +
+                t * (-1.6533902205465252e-6 + t * 4.1381367970572385e-8))));
+  let y = 1 - (lo - (r * c) / (2 - c) - hi);
+  // Scale by 2^k with exact multiplications.
+  let n = k;
+  while (n > 0) {
+    y *= 2;
+    n -= 1;
+  }
+  while (n < 0) {
+    y *= 0.5;
+    n += 1;
+  }
+  return y;
+}
+
+export function dtan(x: number): number {
+  const { r, q } = reduce(x);
+  const s = kernelSin(r);
+  const c = kernelCos(r);
+  return q % 2 === 0 ? s / c : -c / s;
+}
+
+// fdlibm log: x = 2^k * (1 + f) with sqrt(2)/2 <= 1 + f < sqrt(2), then a polynomial in s = f / (2 + f).
+export function dlog(x: number): number {
+  if (Number.isNaN(x) || x < 0) return Number.NaN;
+  if (x === 0) return Number.NEGATIVE_INFINITY;
+  if (x === Number.POSITIVE_INFINITY) return x;
+  let m = x;
+  let k = 0;
+  // Exact power-of-two scaling, no bit access.
+  while (m >= 2) {
+    m *= 0.5;
+    k += 1;
+  }
+  while (m < 1) {
+    m *= 2;
+    k -= 1;
+  }
+  if (m > Math.SQRT2) {
+    m *= 0.5;
+    k += 1;
+  }
+  const f = m - 1;
+  const s = f / (2 + f);
+  const z = s * s;
+  const w = z * z;
+  const t1 = w * (0.3999999999940942 + w * (0.22222198432149784 + w * 0.15313837699209373));
+  const t2 = z * (0.6666666666666735 + w * (0.2857142874366239 + w * (0.1818357216161805 + w * 0.14798198605116586)));
+  const hfsq = 0.5 * f * f;
+  return k * LN2_HI - (hfsq - (s * (hfsq + t1 + t2) + k * LN2_LO) - f);
+}
+
+// fdlibm atan: reduce |x| to a small argument around 0, 0.5, 1, 1.5 or infinity, then a polynomial.
+const ATAN_HI = [0.4636476090008061, 0.7853981633974483, 0.982793723247329, 1.5707963267948966];
+const ATAN_LO = [2.2698777452961687e-17, 3.061616997868383e-17, 1.3903311031230998e-17, 6.123233995736766e-17];
+export function datan(x: number): number {
+  if (Number.isNaN(x)) return x;
+  const negative = x < 0;
+  let t = negative ? -x : x;
+  let id = -1;
+  if (t >= 0.4375) {
+    if (t < 0.6875) {
+      id = 0;
+      t = (2 * t - 1) / (2 + t);
+    } else if (t < 1.1875) {
+      id = 1;
+      t = (t - 1) / (t + 1);
+    } else if (t < 2.4375) {
+      id = 2;
+      t = (t - 1.5) / (1 + 1.5 * t);
+    } else {
+      id = 3;
+      t = -1 / t;
+    }
+  }
+  const z = t * t;
+  const w = z * z;
+  const s1 =
+    z *
+    (0.3333333333333293 +
+      w * (0.14285714272503466 + w * (0.09090887133436507 + w * (0.06661073137387531 + w * (0.049768779946159324 + w * 0.016285820115365782)))));
+  const s2 = w * (-0.19999999999876483 + w * (-0.11111110405462356 + w * (-0.0769187620504483 + w * (-0.058335701337905735 + w * -0.036531572744216916))));
+  const result = id < 0 ? t - t * (s1 + s2) : ATAN_HI[id] - (t * (s1 + s2) - ATAN_LO[id] - t);
+  return negative ? -result : result;
+}
+
+const PI_LO = 1.2246467991473532e-16;
+export function datan2(y: number, x: number): number {
+  if (Number.isNaN(x) || Number.isNaN(y)) return Number.NaN;
+  if (x === 0) return y === 0 ? (1 / x < 0 ? (1 / y < 0 ? -Math.PI : Math.PI) : y) : y > 0 ? Math.PI / 2 : -Math.PI / 2;
+  const z = datan(Math.abs(y / x));
+  const angle = x > 0 ? z : Math.PI - (z - PI_LO);
+  return y < 0 || (y === 0 && 1 / y < 0) ? -angle : angle;
+}
+
+// Integer exponents multiply exactly; anything else goes through dexp and dlog (deterministic, a few ulps).
+export function dpow(x: number, y: number): number {
+  if (Number.isInteger(y) && Math.abs(y) <= 64) {
+    let result = 1;
+    let base = y < 0 ? 1 / x : x;
+    let n = Math.abs(y);
+    while (n > 0) {
+      if (n % 2 === 1) result *= base;
+      base *= base;
+      n = Math.floor(n / 2);
+    }
+    return result;
+  }
+  if (x === 0) return y > 0 ? 0 : Number.POSITIVE_INFINITY;
+  if (x < 0) return Number.isInteger(y) ? (y % 2 === 0 ? 1 : -1) * dexp(y * dlog(-x)) : Number.NaN;
+  return dexp(y * dlog(x));
+}
+
+export function dhypot(x: number, y: number): number {
+  return Math.sqrt(x * x + y * y);
+}
+
+// An angle wrapped to (-pi, pi], without atan2.
+const TAU = 6.283185307179586;
+export function wrapAngle(a: number): number {
+  let w = a - TAU * Math.round(a / TAU);
+  if (w <= -Math.PI) w += TAU;
+  return w;
+}
+
+export function sq(x: number): number {
+  return x * x;
+}

package/src/netplay.ts

@@ -0,0 +1,232 @@
+// Rollback netplay for two peers, game-agnostic (generalized from Crafter Smash). Each peer simulates every frame
+// immediately, predicting the remote input as "same as the last one seen". When the real input arrives and differs,
+// it restores the snapshot taken before that frame and re-simulates to the present. Local input is delayed a few
+// frames to hide most of the latency, so rollbacks stay short.
+//
+// The relay client (web only) is in src/relay-client.
+//
+// The simulation is anything with the shape of the CLI's SimRun: step, save, restore, checksum. `dotframe desync`
+// tests the same contract.
+
+export interface NetSim<S = unknown> {
+  step: (inputs: number[]) => void;
+  save: () => S;
+  restore: (snapshot: S) => void;
+  checksum: () => number;
+}
+
+export interface InputMessage {
+  t: "input";
+  // The sender's current frame, and the latest `now` it has received from us (an echo, to measure the round trip).
+  now: number;
+  ack: number;
+  // Consecutive inputs starting at frame `from`.
+  from: number;
+  inputs: number[];
+}
+
+export interface SumMessage {
+  t: "sum";
+  frame: number;
+  sum: number;
+}
+
+export type NetMessage = InputMessage | SumMessage;
+
+export interface Transport {
+  send: (message: NetMessage) => void;
+  // Messages received since the last call, in order.
+  receive: () => NetMessage[];
+}
+
+export interface RollbackOptions<S = unknown> {
+  sim: NetSim<S>;
+  transport: Transport;
+  // 0 or 1: which player this peer controls.
+  localPort: number;
+  // The encoded "nothing pressed" input.
+  neutral: number;
+  inputDelay: number;
+  // Past this many unconfirmed frames the peer waits instead of predicting further.
+  maxRollback: number;
+  // Called around re-simulation, so the game can mute sound and skip effects that should play once.
+  resimulating?: (active: boolean) => void;
+}
+
+export interface RollbackStats {
+  frame: number;
+  rollbacks: number;
+  longestRollback: number;
+  stalls: number;
+  // First frame whose checksum differed from the peer's, or -1.
+  desync: number;
+  // Smoothed round trip and lead over the peer, in frames.
+  rtt: number;
+  ahead: number;
+  // Time spent in the last tick (rollback, re-simulation and the new frame), in ms.
+  tickMs: number;
+}
+
+export interface Rollback {
+  // One display tick: sends local input, applies remote input, rolls back if needed, then advances a frame unless
+  // too far ahead of the peer. Returns whether a frame was simulated.
+  tick: (localInput: number) => boolean;
+  // Applies received input and rolls back without advancing.
+  settle: () => void;
+  // Highest frame below which both peers' inputs are known (the state there is final).
+  confirmedFrame: () => number;
+  // This peer's checksum after simulating `frame`, final once frame < confirmedFrame().
+  sumAt: (frame: number) => number | undefined;
+  stats: () => RollbackStats;
+}
+
+const SUM_EVERY = 30;
+// Weight of each new sample in the round-trip and lead averages (an exponential moving average over about 10 ticks).
+const SMOOTHING = 0.1;
+// Inputs resent with every message so a late peer catches up without acknowledgments.
+const RESEND = 8;
+
+export function createRollback<S>(options: RollbackOptions<S>): Rollback {
+  const { sim, transport, localPort, neutral, inputDelay, maxRollback } = options;
+  const remotePort = 1 - localPort;
+  const local: number[] = [];
+  const remote: number[] = [];
+  // Remote input each simulated frame actually used, to detect mispredictions.
+  const used: number[] = [];
+  const snapshots: (S | undefined)[] = [];
+  const sums: number[] = [];
+  const peerSums = new Map<number, number>();
+  let frame = 0;
+  // Every remote input below this frame is known.
+  let confirmed = inputDelay;
+  let peerNow = 0;
+  let rtt = 0;
+  let ahead = 0;
+  let sentSums = 0;
+  const stats: RollbackStats = { frame: 0, rollbacks: 0, longestRollback: 0, stalls: 0, desync: -1, rtt: 0, ahead: 0, tickMs: 0 };
+
+  for (let f = 0; f < inputDelay; f++) {
+    local[f] = neutral;
+    remote[f] = neutral;
+  }
+
+  const remoteFor = (f: number): number => {
+    if (f < confirmed) return remote[f];
+    return confirmed > 0 ? remote[confirmed - 1] : neutral;
+  };
+
+  const simulate = (f: number): void => {
+    snapshots[f] = sim.save();
+    const inputs = [neutral, neutral];
+    inputs[localPort] = local[f] ?? neutral;
+    const r = remoteFor(f);
+    inputs[remotePort] = r;
+    used[f] = r;
+    sim.step(inputs);
+    sums[f] = sim.checksum();
+    // Old snapshots are never rolled back to.
+    const drop = f - maxRollback - 2;
+    if (drop >= 0) snapshots[drop] = undefined;
+  };
+
+  const compareSums = (): void => {
+    for (const [f, sum] of peerSums) {
+      if (f >= confirmed || f >= frame) continue;
+      if (sums[f] !== sum && stats.desync < 0) stats.desync = f;
+      peerSums.delete(f);
+    }
+  };
+
+  const settle = (): void => {
+    let rollbackTo = frame;
+    for (const message of transport.receive()) {
+      if (message.t === "sum") {
+        peerSums.set(message.frame, message.sum);
+        continue;
+      }
+      if (message.now >= peerNow) {
+        peerNow = message.now;
+        rtt = rtt * (1 - SMOOTHING) + Math.max(0, frame - message.ack) * SMOOTHING;
+      }
+      for (let i = 0; i < message.inputs.length; i++) {
+        const f = message.from + i;
+        if (f < confirmed) continue;
+        if (f !== confirmed) break;
+        remote[f] = message.inputs[i];
+        confirmed = f + 1;
+        if (f < frame && used[f] !== remote[f] && f < rollbackTo) rollbackTo = f;
+      }
+    }
+    // Frames after the last confirmed one were predicted from it; a new confirmation can change them too.
+    for (let f = confirmed; f < frame && rollbackTo === frame; f++) if (used[f] !== remoteFor(f)) rollbackTo = f;
+
+    if (rollbackTo < frame) {
+      const snapshot = snapshots[rollbackTo];
+      if (snapshot !== undefined) {
+        stats.rollbacks += 1;
+        stats.longestRollback = Math.max(stats.longestRollback, frame - rollbackTo);
+        sim.restore(snapshot);
+        options.resimulating?.(true);
+        for (let f = rollbackTo; f < frame; f++) simulate(f);
+        options.resimulating?.(false);
+      }
+    }
+  };
+
+  const step = (localInput: number): boolean => {
+    settle();
+    // Wait rather than predict too far, or run ahead of a slower peer. The peer's last reported frame is one trip
+    // old; its current frame is about that plus half the round trip. Waiting on the raw gap instead would make both
+    // peers wait for each other and play at round-trip speed.
+    ahead = ahead * (1 - SMOOTHING) + (frame - (peerNow + rtt / 2)) * SMOOTHING;
+    if (frame - confirmed >= maxRollback || ahead > 1) {
+      stats.stalls += 1;
+      const from = Math.max(0, frame + inputDelay - RESEND);
+      transport.send({ t: "input", now: frame, ack: peerNow, from, inputs: local.slice(from, frame + inputDelay) });
+      return false;
+    }
+    local[frame + inputDelay] = localInput;
+    const from = Math.max(0, frame + inputDelay + 1 - RESEND);
+    transport.send({ t: "input", now: frame, ack: peerNow, from, inputs: local.slice(from, frame + inputDelay + 1) });
+    simulate(frame);
+    frame += 1;
+    while (sentSums + SUM_EVERY < confirmed && sentSums + SUM_EVERY < frame) {
+      sentSums += SUM_EVERY;
+      transport.send({ t: "sum", frame: sentSums, sum: sums[sentSums] });
+    }
+    compareSums();
+    stats.frame = frame;
+    return true;
+  };
+
+  return {
+    tick: (localInput: number): boolean => {
+      const started = performance.now();
+      const advanced = step(localInput);
+      stats.tickMs = performance.now() - started;
+      stats.rtt = rtt;
+      stats.ahead = ahead;
+      return advanced;
+    },
+    settle,
+    confirmedFrame: (): number => Math.min(confirmed, frame),
+    sumAt: (f: number): number | undefined => sums[f],
+    stats: (): RollbackStats => stats,
+  };
+}
+
+// --- Relay client ---------------------------------------------------------------------------------------------
+
+export interface RelayLink<A = unknown> {
+  room: string;
+  // "connecting", "waiting" (alone in the room), "paired", "closed".
+  status: () => string;
+  // 0 or 1 once the relay answers, -1 before.
+  slot: () => number;
+  // Game messages (lobby, picks, match start): anything that is not netplay traffic.
+  send: (message: A) => void;
+  receive: () => A[];
+  // Netplay traffic for createRollback.
+  transport: Transport;
+  close: () => void;
+}

package/src/relay-client.ts

@@ -0,0 +1,42 @@
+// Web only: a WebSocket to a `dotframe relay serve` relay. Native and iOS builds have no WebSocket, so this lives
+// apart from src/netplay, which every target compiles.
+import type { NetMessage, RelayLink } from "./netplay";
+
+// Splits relay traffic into game messages and netplay messages.
+export function connectRelay<A = unknown>(url: string, room: string): RelayLink<A> {
+  const socket = new WebSocket(`${url}${url.includes("?") ? "&" : "?"}room=${encodeURIComponent(room)}`);
+  let status = "connecting";
+  let slot = -1;
+  const app: A[] = [];
+  const net: NetMessage[] = [];
+  socket.onmessage = (event: MessageEvent): void => {
+    const message = JSON.parse(String(event.data)) as { t?: string; slot?: number; here?: boolean };
+    if (message.t === "hello") {
+      slot = message.slot ?? -1;
+      status = "waiting";
+    } else if (message.t === "peer") {
+      status = message.here ? "paired" : "waiting";
+      // A peer leaving drops whatever netplay traffic was in flight.
+      if (!message.here) net.length = 0;
+    } else if (message.t === "input" || message.t === "sum") net.push(message as NetMessage);
+    else app.push(message as A);
+  };
+  socket.onclose = (): void => {
+    status = "closed";
+  };
+  const send = (message: unknown): void => {
+    if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message));
+  };
+  return {
+    room,
+    status: (): string => status,
+    slot: (): number => slot,
+    send: (message: A): void => send(message),
+    receive: (): A[] => app.splice(0, app.length),
+    transport: {
+      send: (message: NetMessage): void => send(message),
+      receive: (): NetMessage[] => net.splice(0, net.length),
+    },
+    close: (): void => socket.close(),
+  };
+}

package/templates/_base/dotframe.json

@@ -8,7 +8,16 @@
       "deploy": { "provider": "vercel", "project": "__NAME__", "scope": "__SCOPE__" }
     },
     "macos": { "native": { "platform": "macos", "entry": "main.native.ts" } },
-    "windows": { "native": { "platform": "windows", "entry": "main.native.ts" } }
+    "windows": { "native": { "platform": "windows", "entry": "main.native.ts" } },
+    "ios": {
+      "native": {
+        "platform": "ios",
+        "entry": "main.ios.ts",
+        "bundleId": "com.example.__NAME__",
+        "team": "YOUR_TEAM_ID",
+        "orientation": "landscape"
+      }
+    }
   },
   "assets": { "localOnly": [] }
 }