@sprid/cli 0.1.2

package/src/post/screen/sim.mjs

@@ -0,0 +1,443 @@
+// The simulator half of the `screen` recipe: boot it, dress it, drive it,
+// record it, and write down when everything happened.
+//
+// **The timeline is the output that matters**, not the .mov. A caption is
+// written against a MARK in the script ("when the log opens"), never against a
+// second, because the same script run in seven languages produces seven
+// different sets of timings and only the marks survive that. `compose` reads
+// the timeline back and does the arithmetic.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+const sh = (cmd, args, opts = {}) => spawnSync(cmd, args, { encoding: "utf8", ...opts });
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------------------
+// simkit, compiled on demand
+// ---------------------------------------------------------------------------
+
+/**
+ * The Swift helper is compiled into a cache keyed by the source's mtime, so a
+ * checkout costs one 3-second build and never thinks about it again. Shipping a
+ * binary in the package would mean shipping an unsigned Mach-O through npm,
+ * which is somebody's security review; shipping 400 lines of Swift does not.
+ */
+export function simkit() {
+  const src = new URL("./simkit.swift", import.meta.url).pathname;
+  const stamp = String(Math.floor(statSync(src).mtimeMs));
+  const out = join(tmpdir(), `sprid-simkit-${stamp}`);
+  if (!existsSync(out)) {
+    const r = sh("swiftc", ["-O", "-o", out, src]);
+    if (r.status !== 0) throw new Error(`Could not build simkit:\n${r.stderr}`);
+  }
+  return out;
+}
+
+export function kit(args) {
+  const r = sh(simkit(), args);
+  if (r.status !== 0) throw new Error(`simkit ${args[0]} failed: ${r.stderr.trim()}`);
+  return r.stdout.trim();
+}
+
+// ---------------------------------------------------------------------------
+// the device
+// ---------------------------------------------------------------------------
+
+/**
+ * A name resolves to a UDID, and **a booted device wins.**
+ *
+ * Xcode keeps one simulator per name per runtime, so "iPhone 17" matched three
+ * devices here and the first in the list was an iOS 26.3 one with nothing
+ * installed on it. Taking the first match is how a run spends four minutes
+ * driving an empty springboard. Preferring the booted device makes the
+ * behaviour match what the person watching the screen expects; failing that,
+ * the newest runtime.
+ */
+export function resolveDevice(name) {
+  if (/^[0-9A-F-]{36}$/i.test(name)) return name;
+  const lines = sh("xcrun", ["simctl", "list", "devices", "available"]).stdout.split("\n");
+  const esc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^\\s+${esc} \\(([0-9A-F-]{36})\\)(.*)$`);
+  const hits = lines.map((l) => re.exec(l)).filter(Boolean);
+  if (!hits.length) throw new Error(`No simulator called "${name}".`);
+  return (hits.find((m) => m[2].includes("Booted")) ?? hits[hits.length - 1])[1];
+}
+
+/**
+ * A killed run leaves the host recorder registered with CoreSimulator, and the
+ * next `recordVideo` gets *"Resource busy … Host recording is already in
+ * progress"* and writes nothing. No process is left to kill - the state lives
+ * in the service - so the only way out is to cycle the device.
+ */
+export async function clearStuckRecorder(udid) {
+  sh("xcrun", ["simctl", "shutdown", udid]);
+  await sleep(2500);
+  sh("xcrun", ["simctl", "boot", udid]);
+  sh("xcrun", ["simctl", "bootstatus", udid, "-b"]);
+  await sleep(3000);
+}
+
+export function boot(udid) {
+  const booted = sh("xcrun", ["simctl", "list", "devices"]).stdout
+    .split("\n").some((l) => l.includes(udid) && l.includes("Booted"));
+  if (!booted) {
+    sh("xcrun", ["simctl", "boot", udid]);
+    sh("xcrun", ["simctl", "bootstatus", udid, "-b"]);
+  }
+  sh("open", ["-a", "Simulator"]);
+}
+
+/**
+ * The status bar, dressed.
+ *
+ * A real 22:47 with 61% battery and no signal is the single clearest tell that
+ * a demo was filmed on a machine rather than a phone, and it costs one command
+ * to remove.
+ */
+export function dressStatusBar(udid, { time = "now", battery = { level: 76, state: "discharging" } } = {}) {
+  // **9:41 is the STORE convention and it is wrong for a reel.** A screenshot
+  // is an advertisement and 9:41 reads as one; a reel is meant to look like
+  // somebody's phone, and the app's own content gives the real time away
+  // anyway - a decision logged during the recording carries the wall clock, so
+  // a 9:41 status bar over a row stamped 23:20 is a tell. Default to the host
+  // clock; pass a literal "HH:MM" to pin one.
+  const clock = time === "now"
+    ? new Date().toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" })
+    : time;
+  sh("xcrun", ["simctl", "status_bar", udid, "override",
+    "--time", clock,
+    "--dataNetwork", "wifi", "--wifiMode", "active", "--wifiBars", "3",
+    "--cellularMode", "active", "--cellularBars", "4",
+    // A phone at 100% and charging is the store screenshot. Something in the
+    // seventies, discharging, is what a phone in a hand looks like.
+    "--batteryState", battery.state, "--batteryLevel", String(battery.level)]);
+}
+export const clearStatusBar = (udid) => sh("xcrun", ["simctl", "status_bar", udid, "clear"]);
+
+export function screenshot(udid, path, { type = "png" } = {}) {
+  mkdirSync(dirname(path), { recursive: true });
+  sh("xcrun", ["simctl", "io", udid, "screenshot", `--type=${type}`, path]);
+  return path;
+}
+
+/**
+ * A cheap frame, for comparing against another cheap frame.
+ *
+ * **Nothing reads these probes but a PSNR**, so they run at a quarter scale
+ * through baguette: 302x656 and 49KB against `simctl`'s 1206x2622 and 464KB,
+ * which is a twentieth of the pixels for ffmpeg to decode twice a second while
+ * the recorder is trying to keep up. The recorder's own clock is the thing that
+ * suffers when it cannot - a run that dropped 29% of its elapsed time came back
+ * playing 1.4x fast, on top of the speed-up it was asked for.
+ */
+export function probe(udid, path) {
+  mkdirSync(dirname(path), { recursive: true });
+  if (probe.baguette ?? (probe.baguette = spawnSync("baguette", ["--version"]).status === 0)) {
+    const r = sh("baguette", ["screenshot", "--udid", udid, "--scale", "4", "--format", "jpeg", "-o", path]);
+    if (r.status === 0) return path;
+  }
+  return screenshot(udid, path, { type: "jpeg" });
+}
+
+export function deviceSize(udid, tmp) {
+  const p = join(tmp, "probe.png");
+  screenshot(udid, p);
+  const r = sh("sips", ["-g", "pixelWidth", "-g", "pixelHeight", p]).stdout;
+  return { w: Number(/pixelWidth: (\d+)/.exec(r)?.[1]), h: Number(/pixelHeight: (\d+)/.exec(r)?.[1]) };
+}
+
+// ---------------------------------------------------------------------------
+// where the screen is on the desktop
+// ---------------------------------------------------------------------------
+
+/**
+ * **Calibrate rather than assume.** The first version of this read the device
+ * as 874 points tall and was wrong: a single-distance drag test cannot tell a
+ * scale error from UIScrollView's pan slop, because a constant loss fits any
+ * scale. Three distances separate them - see the note in simkit.swift - and the
+ * numbers came out 910 points of screen and 9.2 points of slop.
+ *
+ * The default model (aspect-fit below a 21-point title bar) reproduces that on
+ * this machine, so calibration is a check rather than a step. It is worth
+ * re-running whenever the window is resized or the Simulator is updated.
+ */
+export function deviceRect(aspect) {
+  const out = kit(["window", "--aspect", String(aspect), "--no-activate"]);
+  const line = out.split("\n").find((l) => l.startsWith("device"));
+  const [, x, y, w, h] = line.split(/\s+/).map(Number);
+  return { x, y, w, h };
+}
+
+// ---------------------------------------------------------------------------
+// recording
+// ---------------------------------------------------------------------------
+
+/**
+ * `simctl io recordVideo` writes a VARIABLE frame rate .mov and stops on
+ * SIGINT. Both facts bite later: SIGKILL leaves a file with no moov atom and
+ * nothing can read it, and a VFR source dropped into a filtergraph without a
+ * `-r` drifts against the caption times by whole seconds over a 20-second reel.
+ */
+export function startRecording(udid, path) {
+  mkdirSync(dirname(path), { recursive: true });
+  rmSync(path, { force: true });
+  const p = spawn("xcrun", ["simctl", "io", udid, "recordVideo", "--codec", "h264", "--force", path],
+    { stdio: ["ignore", "ignore", "pipe"] });
+  let err = "";
+  p.stderr.on("data", (d) => { err += d.toString(); });
+
+  return {
+    proc: p,
+    path,
+    /**
+     * **Fail here or fail sixty seconds later.**
+     *
+     * `simctl io recordVideo` can refuse and keep running, and the first
+     * version ignored its stderr: a killed run leaves the host recorder
+     * registered with CoreSimulator, the next one gets *"Resource busy … Host
+     * recording is already in progress"*, writes no file at all, and the
+     * failure surfaces only at the end - after the app has been driven through
+     * the whole script for nothing. Waiting for the first bytes costs a second
+     * and turns that into an error with the fix in it.
+     */
+    async ready({ graceMs = 1800, timeoutMs = 6000 } = {}) {
+      const t0 = Date.now();
+      while (Date.now() - t0 < timeoutMs) {
+        if (/error|busy/i.test(err))
+          throw new Error(
+            `simctl could not start recording:\n  ${err.trim().split("\n").filter(Boolean).slice(-2).join("\n  ")}\n` +
+              (/already in progress/i.test(err)
+                ? `  A previous run was killed and left the recorder registered. Clear it with:\n` +
+                  `    xcrun simctl shutdown ${udid} && xcrun simctl boot ${udid}`
+                : ""),
+          );
+        // **The file stays 0 bytes for the whole recording** - simctl buffers
+        // and writes on SIGINT ("Recording completed. Writing to disk"), so
+        // waiting for it to GROW never returns. Its existence is the signal
+        // that the recorder took the device; a refusal leaves no file at all.
+        if (Date.now() - t0 > graceMs && existsSync(path)) return;
+        await sleep(120);
+      }
+      throw new Error(`simctl created no file at ${path} within ${timeoutMs}ms. ${err.trim()}`);
+    },
+    async stop() {
+      p.kill("SIGINT");
+      await new Promise((r) => { p.on("exit", r); setTimeout(r, 8000); });
+      await sleep(400);
+    },
+  };
+}
+
+/**
+ * The clapperboard.
+ *
+ * Nothing reports when `recordVideo` actually opened the capture stream, and
+ * the gap between spawning it and the first frame measured 0.4-1.6s here - more
+ * than enough to put a caption on the wrong screen. So the run flashes the
+ * screen before it does anything else and `compose` finds the flash in the
+ * video.
+ *
+ * Flash the springboard after terminating the app. Apps with custom themes
+ * may ignore system appearance changes, making a full-frame marker unreliable.
+ *
+ * Terminating costs a relaunch, which is why the launch belongs to the recipe
+ * and not to the repo's `prepare`: the app has to come up AFTER the anchor.
+ */
+export async function clapper(udid, { bundleId } = {}) {
+  if (bundleId) {
+    sh("xcrun", ["simctl", "terminate", udid, bundleId]);
+    await sleep(1600);
+  }
+  sh("xcrun", ["simctl", "ui", udid, "appearance", "dark"]);
+  const at = Date.now();
+  await sleep(900);
+  sh("xcrun", ["simctl", "ui", udid, "appearance", "light"]);
+  await sleep(700);
+  return at;
+}
+
+// ---------------------------------------------------------------------------
+// settling
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for the screen to become something else, and then to stop changing.
+ *
+ * A fixed `sleep` is the reason scripted demos look scripted: it is either too
+ * short, and the finger arrives during a push transition, or too long, and the
+ * reel pays four dead seconds for the worst case.
+ *
+ * **`since` is the whole thing, and it took three failures to get here.** The
+ * first version waited only for quiet, which cannot tell *the transition has
+ * finished* from *it has not started*. The second added "wait for any motion
+ * first", which is still not enough: a Debug build behind Metro can run SECONDS
+ * behind the script, and while it is behind, the screen it is still showing is
+ * perfectly quiet. Every settle then returned on a stale frame, every following
+ * tap landed on a screen that was about to be replaced, and a reel came back
+ * with the app stuck on one screen for its last ten seconds.
+ *
+ * With `since` - a frame captured before the gesture that caused the change -
+ * the question becomes *is this a different screen yet*, which is the one worth
+ * asking. `maxMs` can then be generous, because it returns the moment the app
+ * catches up rather than sleeping the worst case.
+ */
+export async function settle(udid, tmp, { maxMs = 6000, quietMs = 300, threshold = 42, graceMs = 1500, since = null } = {}) {
+  // JPEG probes reduce capture overhead while recordVideo is running.
+  // Full-resolution PNG probes can starve the recorder and distort timing.
+  const a = join(tmp, "settle-a.jpg"), b = join(tmp, "settle-b.jpg");
+  const t0 = Date.now();
+  if (since && existsSync(since)) sh("cp", [since, a]);
+  else probe(udid, a);
+
+  let quiet = 0;
+  let moved = false;
+  while (Date.now() - t0 < maxMs) {
+    const before = Date.now();
+    probe(udid, b);
+    const psnr = compare(a, b);
+    // With a `since` reference the first phase asks *has the screen become
+    // something else yet*, so the reference must NOT advance until it has.
+    if (!(since && !moved)) sh("cp", [b, a]);
+    const spent = Date.now() - before;
+    // Persistent background animation can be quiet without becoming identical.
+    const busy = psnr <= threshold;
+    if (busy) {
+      if (since && !moved) sh("cp", [b, a]);
+      moved = true;
+      quiet = 0;
+      continue;
+    }
+    if (!moved && Date.now() - t0 < graceMs) continue;
+    quiet += spent;
+    if (quiet >= quietMs) return Date.now() - t0;
+  }
+  return Date.now() - t0;
+}
+
+/**
+ * PSNR between two frames, in dB, and **`Infinity` when they are identical**.
+ *
+ * ffmpeg prints `average:inf` for identical input, which `/[\d.]+/` does not
+ * match. Defaulting that to 0 - which the first version did - inverts the
+ * meaning of the number it feeds: two identical frames come back as maximally
+ * different, every settle reads as busy, and every settle in a run then sits
+ * until its ceiling. The reel came out 39.7s instead of 19s.
+ */
+export function compare(a, b, { region = null } = {}) {
+  const graph = region
+    ? `[0:v]crop=${region}[a];[1:v]crop=${region}[b];[a][b]psnr`
+    : "psnr";
+  const r = sh("ffmpeg", ["-hide_banner", "-nostats", "-i", a, "-i", b,
+    "-filter_complex", graph, "-f", "null", "-"]);
+  const m = /average:([\d.]+|inf)/.exec(r.stderr ?? "");
+  if (!m || m[1] === "inf") return Infinity;
+  return Number(m[1]);
+}
+
+// ---------------------------------------------------------------------------
+// running a script
+// ---------------------------------------------------------------------------
+
+const nowRel = (t0) => Date.now() - t0;
+
+/**
+ * Run the gesture script and write down what happened when.
+ *
+ * **The script carries no words.** It is the finger's path through the app and
+ * nothing else, which is exactly what makes the seven-language version cheap:
+ * one script, seven caption files, seven runs of the same steps.
+ */
+export async function runScript(script, ctx) {
+  const { udid, tmp, input, t0, log = () => {} } = ctx;
+  const timeline = { marks: {}, gestures: [], steps: [] };
+  // The frame as it was before the last gesture. A `settle` uses it to ask
+  // *has the screen become something else yet*, which is a different and much
+  // more useful question than *has it stopped moving*.
+  const pre = join(tmp, "pre-gesture.jpg");
+  let sinceGesture = null;
+  const note = (kind, extra = {}) => {
+    const t = nowRel(t0);
+    timeline.steps.push({ t, kind, ...extra });
+    return t;
+  };
+
+  for (const step of script.steps) {
+    if (step.mark) {
+      timeline.marks[step.mark] = nowRel(t0);
+      log(`    ${String(nowRel(t0)).padStart(6)}ms  mark ${step.mark}`);
+      continue;
+    }
+    if (step.wait != null) { note("wait", { ms: step.wait }); await sleep(step.wait); continue; }
+    if (step.settle != null) {
+      const took = await settle(udid, tmp, {
+        maxMs: step.settle === true ? 8000 : step.settle,
+        since: sinceGesture,
+      });
+      sinceGesture = null;
+      note("settle", { ms: took });
+      log(`    ${String(nowRel(t0)).padStart(6)}ms  settled after ${took}ms`);
+      continue;
+    }
+    if (step.tap) {
+      const [x, y] = step.tap;
+      const t = note("tap", { x, y, note: step.note });
+      timeline.gestures.push({ kind: "tap", t, points: [[x, y]], durationMs: 240 });
+      probe(udid, pre);
+      sinceGesture = pre;
+      await input.tap(x, y, { holdMs: step.hold });
+      log(`    ${String(t).padStart(6)}ms  tap ${x},${y}${step.note ? `  (${step.note})` : ""}`);
+      // Retry can handle a tap swallowed by an unfinished transition.
+      // Stop once the target region changes to avoid repeated navigation.
+      if (step.retry) {
+        // Observe a stable region so continuous background motion does not
+        // masquerade as navigation. The default covers the bottom tab-bar area.
+        const region = step.retryRegion ?? "iw:ih/10:0:ih*9/10";
+        for (let i = 0; i < (step.retry === true ? 4 : step.retry); i++) {
+          await sleep(step.retryEveryMs ?? 900);
+          probe(udid, post);
+          if (compare(pre, post, { region }) <= 42) break;
+          log(`            tap ignored, trying again (${i + 1})`);
+          await input.tap(x, y, { holdMs: step.hold });
+        }
+      }
+      continue;
+    }
+    if (step.swipe) {
+      const [x1, y1, x2, y2] = step.swipe;
+      const dur = step.duration ?? 280;
+      const t = note("swipe", { x1, y1, x2, y2, durationMs: dur, note: step.note });
+      timeline.gestures.push({ kind: "swipe", t, points: [[x1, y1], [x2, y2]], durationMs: dur + 260 });
+      probe(udid, pre);
+      sinceGesture = pre;
+      await input.swipe(x1, y1, x2, y2, { durationMs: dur, flick: !step.precise, ...(step.bow != null ? { bow: step.bow } : {}) });
+      log(`    ${String(t).padStart(6)}ms  swipe ${x1},${y1} -> ${x2},${y2}${step.note ? `  (${step.note})` : ""}`);
+      continue;
+    }
+    if (step.launch) {
+      note("launch", { bundleId: step.launch });
+      sh("xcrun", ["simctl", "launch", udid, step.launch]);
+      continue;
+    }
+    if (step.terminate) { sh("xcrun", ["simctl", "terminate", udid, step.terminate]); continue; }
+    if (step.shell) {
+      // **`<locale>` is why a shell step does not break the one-script rule.**
+      // An app that picks its language through a deep link needs the locale in
+      // the command, and putting it there literally would fork the script per
+      // language - which is the whole thing this recipe exists not to do.
+      const cmd = Object.entries(ctx.vars ?? {}).reduce((c, [k, v]) => c.replaceAll(`<${k}>`, String(v)), step.shell);
+      note("shell", { cmd });
+      log(`    ${String(nowRel(t0)).padStart(6)}ms  sh ${cmd}`);
+      sh("/bin/sh", ["-c", cmd], { cwd: ctx.root, stdio: "inherit" });
+      continue;
+    }
+    throw new Error(`Unknown script step: ${JSON.stringify(step)}`);
+  }
+  timeline.endedAt = nowRel(t0);
+  return timeline;
+}
+
+export function readJson(p) { return JSON.parse(readFileSync(p, "utf8")); }
+export function writeJson(p, v) { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, JSON.stringify(v, null, 2) + "\n"); }