simframe 0.17.0 → 0.19.0

package/native/simframed/Sources/PrivateAPI/CoreSimulatorPlatform.swift

@@ -45,13 +45,19 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
     private static func loadFrameworks() throws {
         guard !loaded else { return }
         let developerDir = Self.developerDir()
-        let candidates = [
-            ("CoreSimulator", "/Library/Developer/PrivateFrameworks/CoreSimulator.framework/CoreSimulator"),
-            ("SimulatorKit", "\(developerDir)/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit"),
+        let candidates: [(String, [String])] = [
+            ("CoreSimulator", ["/Library/Developer/PrivateFrameworks/CoreSimulator.framework/CoreSimulator"]),
+            ("SimulatorKit", [
+                "\(developerDir)/Library/PrivateFrameworks/SimulatorKit.framework/SimulatorKit",
+                // Xcode moved this out of Contents/Developer into the top-level
+                // Contents/SharedFrameworks at some point around Xcode 16-27;
+                // keep the old path first since it's still what older Xcodes use.
+                "\(developerDir)/../SharedFrameworks/SimulatorKit.framework/SimulatorKit",
+            ]),
         ]
-        for (name, path) in candidates {
-            guard FileManager.default.fileExists(atPath: path) else {
-                throw PrivateAPIError.frameworksUnavailable("\(name) not found at \(path)")
+        for (name, paths) in candidates {
+            guard let path = paths.first(where: { FileManager.default.fileExists(atPath: $0) }) else {
+                throw PrivateAPIError.frameworksUnavailable("\(name) not found at \(paths.joined(separator: " or "))")
             }
             guard let handle = dlopen(path, RTLD_NOW) else {
                 let reason = String(cString: dlerror())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/article-md.mjs

@@ -21,9 +21,17 @@
 // anything it does not recognise rather than dropping it — a converter that
 // silently skips an unfamiliar tag produces a document that looks complete and
 // is not, which is the failure mode this whole file exists to prevent.
+//
+// That promise had a hole in it for as long as it existed, and the hole was
+// not an unfamiliar tag but the space between two familiar ones. The scanner
+// matched a list of constructs and stepped over everything in between without
+// looking, so the colophon's body — a text node the page puts straight inside
+// its container, with no `<p>` around it — was not unhandled, it was unseen,
+// and the document ended on a bare **On the numbers** label. Refusing what you
+// do not recognise is only half of it; you have to look everywhere first.
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SOURCE = path.join(ROOT, 'docs', 'agents-shouldnt-blink.html');
@@ -81,12 +89,36 @@ function table(html) {
   ];
 }
 
-/** Everything inside one `<section>`, in order. */
+/**
+ * Tags that hold blocks without being one. The scanner walks through these; a
+ * tag in a gap that is *not* one of them is content, and `inline` throws on it.
+ */
+const CONTAINER = /<\/?(?:div|ul|ol|section|header|figure)\b[^>]*>/g;
+
+/**
+ * What the scanner stepped over between two blocks. Containers are expected.
+ * Anything left is a text node the page put straight inside a container rather
+ * than in a `<p>` — the colophon's body is one — and it is content like any
+ * other. Nothing looked in the gaps before, so every generated copy of this
+ * document ended on a dangling **On the numbers** label with its paragraph
+ * gone: exactly the silent-drop failure the rest of this file refuses.
+ */
+function gap(html) {
+  return html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .split(CONTAINER)
+    .map((piece) => piece.trim())
+    .filter(Boolean)
+    .map((text) => ({ kind: 'p', text: inline(text) }));
+}
+
+/** Everything inside one `<section>` (or the `<header>`), in order. */
 function blocks(html) {
   const out = [];
   // One pass over the constructs the article actually uses. `lastIndex`
   // walking rather than nested parsing, because the document is flat inside a
-  // section and a real parser here would be a dependency.
+  // section and a real parser here would be a dependency. What the pass does
+  // *not* match is handed to `gap` rather than skipped.
   const re = new RegExp([
     '<h([123])>([\\s\\S]*?)<\\/h\\1>',
     '<p class="sec-label">([\\s\\S]*?)<\\/p>',
@@ -96,10 +128,15 @@ function blocks(html) {
     '<table>([\\s\\S]*?)<\\/table>',
     '<pre>([\\s\\S]*?)<\\/pre>',
     '<li>([\\s\\S]*?)<\\/li>',
+    '<figcaption>([\\s\\S]*?)<\\/figcaption>',
+    '<svg\\b([^>]*)>[\\s\\S]*?<\\/svg>',
   ].join('|'), 'g');
   let m;
+  let cursor = 0;
   while ((m = re.exec(html)) !== null) {
-    const [, level, heading, sec, panel, amend, para, tbl, pre, li] = m;
+    out.push(...gap(html.slice(cursor, m.index)));
+    cursor = re.lastIndex;
+    const [, level, heading, sec, panel, amend, para, tbl, pre, li, caption, svg] = m;
     if (heading != null) out.push({ kind: 'h', level: Number(level), text: inline(heading) });
     else if (sec != null) out.push({ kind: 'kicker', text: inline(sec) });
     else if (panel != null) out.push({ kind: 'label', text: inline(panel) });
@@ -108,17 +145,65 @@ function blocks(html) {
     else if (tbl != null) out.push({ kind: 'table', lines: table(tbl) });
     else if (pre != null) out.push({ kind: 'pre', text: decode(stripTagsPreserving(pre)) });
     else if (li != null) out.push({ kind: 'li', text: inline(li) });
+    else if (caption != null) out.push({ kind: 'p', text: inline(caption) });
+    // A diagram cannot be projected into Markdown, but its `aria-label` is
+    // already the prose a screen reader gets, so that is what a reader of the
+    // Markdown gets too. An undescribed diagram is content this cannot carry,
+    // so it throws rather than quietly becoming nothing.
+    else if (svg != null) {
+      const label = svg.match(/aria-label="([^"]*)"/);
+      if (!label) throw new Error('<svg> with no aria-label — nothing to project');
+      out.push({ kind: 'figure', text: inline(label[1]) });
+    }
   }
+  out.push(...gap(html.slice(cursor)));
   return out;
 }
 
 /** `<pre>` keeps its newlines; only tags come out. */
 const stripTagsPreserving = (s) => s.replace(/<[^>]+>/g, '').replace(/^\n/, '').replace(/\s+$/, '');
 
+/** One section's or the header's blocks, appended to the document. */
+function emit(lines, bs) {
+  let pendingKicker = null;
+  let inList = false;
+  for (const b of bs) {
+    if (b.kind !== 'li' && inList) { lines.push(''); inList = false; }
+    switch (b.kind) {
+      // The kicker precedes its heading on the page and reads as a label for
+      // it, so it is held until the heading arrives rather than emitted where
+      // it was found.
+      case 'kicker': pendingKicker = b.text; break;
+      case 'h':
+        if (pendingKicker) { lines.push(`*${pendingKicker}*`, ''); pendingKicker = null; }
+        // `<h1>` is the title, already emitted above, so the page's `<h2>`
+        // sections are the document's second level and not its third.
+        lines.push(`${'#'.repeat(b.level)} ${b.text}`, '');
+        break;
+      case 'label': lines.push(`**${b.text}**`, ''); break;
+      case 'p': lines.push(b.text, ''); break;
+      case 'figure': lines.push(`*Figure — ${b.text}*`, ''); break;
+      case 'li': lines.push(`- ${b.text}`); inList = true; break;
+      case 'table': lines.push(...b.lines, ''); break;
+      case 'pre': lines.push('```', b.text, '```', ''); break;
+      default: throw new Error(`unhandled block ${b.kind}`);
+    }
+  }
+  if (inList) lines.push('');
+}
+
 export function render(html) {
   const title = stripTags(html.match(/<h1>([\s\S]*?)<\/h1>/)[1]);
   const kicker = stripTags(html.match(/<p class="kicker">([\s\S]*?)<\/p>/)[1]);
-  const standfirst = html.match(/<p class="standfirst">([\s\S]*?)<\/p>/);
+  // The rest of the header: the deck, the figure, the provenance line. This
+  // used to look for `<p class="standfirst">`, a class the page does not have,
+  // so the match was always null and the branch that emitted it never ran —
+  // the same silent drop as the colophon, arrived at from the other end. The
+  // header is walked with the section machinery now, minus the two blocks
+  // emitted by hand above.
+  const header = (html.match(/<header>([\s\S]*?)<\/header>/)?.[1] ?? '')
+    .replace(/<h1>[\s\S]*?<\/h1>/, '')
+    .replace(/<p class="kicker">[\s\S]*?<\/p>/, '');
 
   const lines = [
     `# ${title}`,
@@ -134,52 +219,33 @@ export function render(html) {
     '> in [`EXPERIMENTS.md`](EXPERIMENTS.md).',
     '',
   ];
-  if (standfirst) lines.push(inline(standfirst[1]), '');
+  emit(lines, blocks(header));
   lines.push('---', '');
 
-  for (const section of html.match(/<section>[\s\S]*?<\/section>/g) ?? []) {
-    let pendingKicker = null;
-    let inList = false;
-    for (const b of blocks(section)) {
-      if (b.kind !== 'li' && inList) { lines.push(''); inList = false; }
-      switch (b.kind) {
-        // The kicker precedes its heading on the page and reads as a label for
-        // it, so it is held until the heading arrives rather than emitted where
-        // it was found.
-        case 'kicker': pendingKicker = b.text; break;
-        case 'h':
-          if (pendingKicker) { lines.push(`*${pendingKicker}*`, ''); pendingKicker = null; }
-          // `<h1>` is the title, already emitted above, so the page's `<h2>`
-          // sections are the document's second level and not its third.
-          lines.push(`${'#'.repeat(b.level)} ${b.text}`, '');
-          break;
-        case 'label': lines.push(`**${b.text}**`, ''); break;
-        case 'p': lines.push(b.text, ''); break;
-        case 'li': lines.push(`- ${b.text}`); inList = true; break;
-        case 'table': lines.push(...b.lines, ''); break;
-        case 'pre': lines.push('```', b.text, '```', ''); break;
-        default: throw new Error(`unhandled block ${b.kind}`);
-      }
-    }
-    if (inList) lines.push('');
-  }
+  for (const section of html.match(/<section>[\s\S]*?<\/section>/g) ?? []) emit(lines, blocks(section));
 
   return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`;
 }
 
-const html = fs.readFileSync(SOURCE, 'utf8');
-const md = render(html);
+// Only as a command. This used to run on import, which meant the test that
+// asserts the page and the Markdown are one document regenerated the Markdown
+// before reading it back and compared the output to itself. It could not fail,
+// and it did not — the colophon's missing paragraph sat under a green suite
+// for as long as it existed. `--check` in CI was the only real gate.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const md = render(fs.readFileSync(SOURCE, 'utf8'));
 
-if (process.argv.includes('--check')) {
-  const current = fs.existsSync(TARGET) ? fs.readFileSync(TARGET, 'utf8') : '';
-  if (current === md) {
-    console.log(`docs/ARTICLE.md is in step with the page (${md.split('\n').length} lines)`);
-    process.exit(0);
+  if (process.argv.includes('--check')) {
+    const current = fs.existsSync(TARGET) ? fs.readFileSync(TARGET, 'utf8') : '';
+    if (current === md) {
+      console.log(`docs/ARTICLE.md is in step with the page (${md.split('\n').length} lines)`);
+      process.exit(0);
+    }
+    console.error('docs/ARTICLE.md is out of date with docs/agents-shouldnt-blink.html.');
+    console.error('Run: node scripts/article-md.mjs');
+    process.exit(1);
   }
-  console.error('docs/ARTICLE.md is out of date with docs/agents-shouldnt-blink.html.');
-  console.error('Run: node scripts/article-md.mjs');
-  process.exit(1);
-}
 
-fs.writeFileSync(TARGET, md);
-console.log(`wrote docs/ARTICLE.md — ${md.split('\n').length} lines from ${SOURCE.split('/').pop()}`);
+  fs.writeFileSync(TARGET, md);
+  console.log(`wrote docs/ARTICLE.md — ${md.split('\n').length} lines from ${SOURCE.split('/').pop()}`);
+}

package/scripts/bench-hpi.mjs

@@ -21,6 +21,7 @@ import { runScript } from '../src/actions.js';
 import * as api from '../src/index.js';
 import * as baseline from '../src/baseline.js';
 import * as metrics from '../src/metrics.js';
+import * as wedge from '../src/wedge.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const arg = (name, fallback = null) => {
@@ -55,8 +56,22 @@ const passes = Math.max(1, Number(arg('passes', gate ? '3' : '1')));
  * asked to do it degrades and then stops rendering. The suite paces itself so
  * the numbers describe simframe rather than the simulator's tolerance for
  * being hammered.
+ *
+ * **1500 was not enough, and that is measured rather than argued.** Same flow,
+ * same device, same afternoon, varying only this number: at 1500 ms the device
+ * stopped being readable after 4, 4 and 5 runs across three separate attempts;
+ * at 4000-5000 ms a full 8-run pass finished with `diagnose` still saying
+ * `healthy`. That is a large part of item 173 — "the bench suite wedges the
+ * device it measures" — and it means the suite has never once completed a full
+ * pass on a hosted runner.
+ *
+ * Raising it is a measurement change, not a tuning tweak: **every HPI number in
+ * this repo recorded before 2026-09-18 was taken at 1500**, including the
+ * committed reference, so numbers across that line are not comparable. The
+ * reference was re-recorded at the new default for exactly that reason, and
+ * `docs/BENCHMARKS.md` says so.
  */
-const cooldownMs = Math.max(0, Number(arg('cooldown', '1500')));
+const cooldownMs = Math.max(0, Number(arg('cooldown', '4000')));
 
 const suite = baseline.loadSuite(arg('suite', baseline.SUITE_FILE)).filter((f) => !only || f.name === only);
 if (!suite.length) {
@@ -101,6 +116,35 @@ outer: for (let pass = 1; pass <= passes; pass += 1) {
   const thisPass = new Set();
   passSets.push(thisPass);
   if (passes > 1) console.log(`pass ${pass}/${passes}`);
+  // **Recover between passes, not only after a failure.**
+  //
+  // Measured 2026-09-18: this device tolerates roughly 8-10 app launches before
+  // it stops being readable, and it degrades *within* a pass — the suite's own
+  // second flow went 9 s, 18 s, 30 s, then two incompletes, on a device that had
+  // run the same flow five times cleanly minutes earlier. `passes x runs` is 30
+  // runs at the default and 18 in CI, both far past that, with no recovery in
+  // between. So a multi-pass suite has never been physically completable and the
+  // gate has never produced a hosted-runner reading in this whole series.
+  //
+  // DEFERRED 173 listed this as worth trying. Nothing had tried it.
+  //
+  // Diagnosed first, revived only if needed: a revive is ~40 s and paying it
+  // when the device is fine would be spending the budget on superstition. The
+  // diagnosis is also the honest record of what state each pass started in —
+  // without it, a pass that began on a half-dead device is indistinguishable
+  // from one that did not.
+  if (pass > 1) {
+    const before = wedge.classify(await wedge.snapshot(dev.udid).catch(() => null));
+    console.log(`  device before pass ${pass}: ${before?.state ?? 'unreadable'}`);
+    if (before?.state !== 'healthy') {
+      const revived = await wedge.revive(dev.udid, { device: dev });
+      console.log(`  revived between passes — now ${revived.state}`);
+      if (!revived.usable) {
+        abort = { kind: 'the device could not be revived between passes', message: revived.verdict?.detail ?? '' };
+        break outer;
+      }
+    }
+  }
   for (const flow of suite) {
     for (let run = 1; run <= runs; run += 1) {
     // The same start state the human baseline was recorded from: app not
@@ -191,6 +235,14 @@ for (const f of report.flows) {
 report.overall.hpi_time_median_of_passes = passTimes.length ? Number(metrics.median(passTimes).toFixed(3)) : null;
 const o = report.overall;
 console.log(`\nHPI_accuracy ${o.hpi_accuracy}   HPI_time ${o.hpi_time ?? '—'}   HPI ${o.hpi ?? '—'}   step_ratio ${o.step_ratio ?? '—'}`);
+if (o.runs_lost_to_device) {
+  // Measured on a full local suite: 5 of 17 runs failed because the guest's
+  // SpringBoard crashed or simctl stopped answering. They used to lower
+  // HPI_accuracy, which is the number this job gates on.
+  console.log(`  over ${o.runs} measurable run(s); ${o.runs_lost_to_device} left the denominator`
+    + ' because the DEVICE failed, not the code (item 173):');
+  for (const c of o.device_causes ?? []) console.log(`    ${c}`);
+}
 if (passTimes.length > 1) {
   console.log(`HPI_time per pass: ${passTimes.join(', ')} — median ${o.hpi_time_median_of_passes} (what the gate reads)`);
 }

package/scripts/ci-device-guard.mjs

@@ -59,6 +59,25 @@ if (!cause) {
   process.exit(first.code ?? 1);
 }
 
+// Diagnose BEFORE reviving, because reviving is what destroys the evidence.
+//
+// This guard has been recognising wedges from the shape of the failure text
+// since 126, and then immediately power-cycling the device — so item 173 has
+// accumulated a dozen occurrences and not one observation of what the device
+// was doing at the time. `cause` above names a *consequence* ("a launched app
+// never came to the front"); this names what the two sensors actually saw, and
+// the difference decides between a stale framebuffer, a screen that is not the
+// app, and capture being down. Its cost is one read on a path that is already
+// failing.
+const diagnose = async (when) => {
+  const d = await run(['node', 'src/cli.js', 'diagnose', `--device=${udid}`]);
+  console.error(`\n     (diagnosis ${when} — for DEFERRED 173)`);
+  const verdict = /— (\S+)\n/.exec(d.out)?.[1] ?? 'unreadable';
+  summary(`  - diagnosis ${when}: \`${verdict}\``);
+  return verdict;
+};
+const before = await diagnose('before the revive');
+
 console.error(`\n     (${cause} — DEFERRED 126. Reviving once and running again.)`);
 await run(['node', 'src/cli.js', 'revive', `--device=${udid}`], { capture: false });
 const second = await run(cmd);
@@ -70,4 +89,12 @@ if (second.code === 0) {
 const again = deviceCause(second.out);
 summary(`- \`${cmd.join(' ')}\` — **${again ? 'device unavailable' : 'check failed'}** after a revive${again ? ` (${again})` : ''}`);
 if (again) console.error(`\nFAIL the simulator is still in a bad state after a revive: ${again}`);
+// Twice is the interesting case: a revive cured it and it came back, or the
+// revive did not cure it at all. Those are different faults and the pair of
+// diagnoses says which.
+const after = await diagnose('after the revive');
+if (before !== after) {
+  console.error(`\n     (the device changed state across the revive: ${before} -> ${after})`);
+  summary(`  - state changed across the revive: \`${before}\` -> \`${after}\``);
+}
 process.exit(second.code ?? 1);

package/scripts/ci-memory.mjs

@@ -678,23 +678,50 @@ if (contradicted) {
 // --force is the deliberate override, and it is what lets the replay machinery
 // be tested without waiting on a screen that may never settle into one shape.
 const forced = await jsonRetry(['do', LOOP, `--save=${FLOW_NAME}`, '--force'], { allowFail: true });
-if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.saved?.steps} steps`)) {
+if (check(forced.saved?.ok === true, 'and --force saves it anyway',
+  `${forced.saved?.steps} steps, provisional=${forced.saved?.provisional}`)) {
   const listed = await jsonRetry(['flow', 'list']);
-  check(listed.some((f) => f.name === FLOW_NAME), 'the saved flow is listed');
+  const before = listed.find((f) => f.name === FLOW_NAME);
+  check(Boolean(before), 'the saved flow is listed');
+  // Whether there is anything to promote is a fact about *this* save, not the
+  // first attempt's. The forced save is another traversal of the same loop,
+  // and by then the graph has seen every edge in it: measured on the bench
+  // device, the first run saved `provisional=true` and every run after it
+  // saved confirmed outright. Both checks below used to assume a provisional
+  // flow — so the positive one passed on a flow that had never been
+  // provisional, and the negative one failed CI on it — main was red on a
+  // precondition the harness never established, while the product did exactly
+  // what it should.
+  const wasProvisional = before?.provisional === true;
   const replayed = await jsonRetry(['flow', 'run', FLOW_NAME], { allowFail: true });
+  // A replay that stopped early says which step stopped it and why. 1dcce18's
+  // red run printed `1/2 steps` and nothing else, so the one fact that would
+  // say whether the replay itself is broken was never on the page.
+  const stoppedAt = (replayed.results ?? []).find((r) => !r.ok);
   check(replayed.ranSteps >= 1 && Array.isArray(replayed.results),
     'and replays from disk with no model in the loop',
-    `${replayed.ranSteps}/${replayed.totalSteps} steps`);
+    `${replayed.ranSteps}/${replayed.totalSteps} steps`
+      + (stoppedAt ? `; stopped at [${stoppedAt.index}] ${stoppedAt.action}: ${String(stoppedAt.detail ?? '').slice(0, 160)}` : ''));
   // The other half of the bootstrap, and the reason "provisional" is not a
   // state nothing ever leaves: a clean replay is the confirmation a first
   // traversal could not give. Only asserted when the replay actually ran to
   // the end — a partial replay promotes nothing, deliberately.
   const after = await jsonRetry(['flow', 'list']);
   const entry = after.find((f) => f.name === FLOW_NAME);
-  if (replayed.ok) {
+  // Whatever the replay did, it must not lose the flow. Neither branch below
+  // could say this: an entry that vanished and an entry without the field both
+  // read `undefined`.
+  check(Boolean(entry), 'a replay leaves the flow it replayed on disk',
+    entry ? '' : 'the entry is gone from the listing');
+  if (!wasProvisional) {
+    skip(replayed.ok
+      ? 'and a clean replay confirms a provisional flow'
+      : 'and a replay that failed does NOT confirm the flow it just disproved',
+    'the forced save verified every step, so the flow was confirmed before the replay and there was nothing to promote');
+  } else if (replayed.ok) {
     check(entry && !entry.provisional,
       'and a clean replay confirms a provisional flow',
-      `provisional=${entry?.provisional ?? 'gone'}`);
+      `provisional=${entry ? entry.provisional : 'gone'}`);
   } else {
     // The other direction, and it is the one that was silently wrong: promotion
     // keyed on `ranSteps === steps.length`, which a failure on the *last* step
@@ -703,7 +730,7 @@ if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.sa
     // confirmation, so the negative case has to be checked too.
     check(entry?.provisional === true,
       'and a replay that failed does NOT confirm the flow it just disproved',
-      `ok=${replayed.ok}, provisional=${entry?.provisional}`);
+      `ok=${replayed.ok}, provisional=${entry ? entry.provisional : 'gone'}`);
   }
   const unknown = await cli(['flow', 'run', 'no-such-flow'], { expectFail: true });
   check(/no flow/i.test(unknown), 'an unknown flow name is refused with what is known');

package/scripts/demo-gif/README.md

@@ -0,0 +1,36 @@
+# The README GIF, and how to remake it
+
+`docs/simframe-demo.gif` is a `simctl` recording of the benchmark simulator
+composed with the flow's own JSON verdicts. No dependency was added: the
+compositor is one Swift file on AVFoundation, CoreText and ImageIO.
+
+1. Boot a simulator, launch Settings so the flow starts at its root, then
+   record while the flow runs and keep the wall-clock bounds:
+
+   ```bash
+   D=<udid>
+   xcrun simctl launch $D com.apple.Preferences; sleep 4
+   xcrun simctl io $D recordVideo --codec h264 --force take.mp4 & REC=$!; sleep 4
+   T0=$(python3 -c 'import time;print(int(time.time()*1000))')
+   simframe do scripts/demo-gif/flow.json --device=$D --json > do.json
+   T1=$(python3 -c 'import time;print(int(time.time()*1000))')
+   sleep 2; kill -INT $REC; wait $REC
+   ```
+
+   Record with the app already launched: a `launch` step inside the recording
+   took 8–10 s on two takes because the launch did not front on the first
+   attempt while `recordVideo` was attached, against 89 ms without it.
+
+2. Build `events.json` from `do.json`, `T0` and `T1` — the shape is in
+   `events.example.json`: every `t` is an epoch millisecond, and
+   `videoEndEpochMs` is `T1 + 2000`, which is how the compositor finds where
+   the recording starts without a timestamp from `simctl`.
+
+3. Compose:
+
+   ```bash
+   swift scripts/demo-gif/compose.swift take.mp4 events.json docs/simframe-demo.gif
+   ```
+
+   760×560, 10 fps, the last frame held two seconds; the example take is
+   85 frames and 336 KB.

package/scripts/demo-gif/compose.swift

@@ -0,0 +1,106 @@
+// Composes a README GIF: simulator recording on the left, a terminal panel on
+// the right whose lines appear at the moments the flow printed them.
+// usage: swift gif.swift <video.mp4> <events.json> <out.gif>
+// events.json: {"startMs":..,"endMs":..,"fps":..,"lines":[{"t":ms,"text":".."}]}
+// Times are milliseconds from the start of the video. No dependencies.
+import Foundation
+import AVFoundation
+import ImageIO
+import CoreText
+import UniformTypeIdentifiers
+
+struct Line: Decodable { let t: Double; let text: String; let color: String? }
+struct Events: Decodable { let startMs: Double; let endMs: Double; let fps: Double; let lines: [Line]; let title: String?; let videoEndEpochMs: Double }
+
+let args = CommandLine.arguments
+let video = URL(fileURLWithPath: args[1])
+let raw = try! JSONDecoder().decode(Events.self, from: Data(contentsOf: URL(fileURLWithPath: args[2])))
+let asset0 = AVURLAsset(url: video)
+let durMs = CMTimeGetSeconds(asset0.duration) * 1000
+let vstart = raw.videoEndEpochMs - durMs
+struct Ev { let startMs: Double; let endMs: Double; let fps: Double; let lines: [Line]; let title: String? }
+let events = Ev(startMs: max(0, raw.startMs - vstart), endMs: min(durMs, raw.endMs - vstart), fps: raw.fps,
+  lines: raw.lines.map { Line(t: $0.t - vstart, text: $0.text, color: $0.color) }, title: raw.title)
+print("video \(durMs) ms, window \(events.startMs)...\(events.endMs)")
+let out = URL(fileURLWithPath: args[3])
+
+let asset = AVURLAsset(url: video)
+let gen = AVAssetImageGenerator(asset: asset)
+gen.requestedTimeToleranceBefore = .zero
+gen.requestedTimeToleranceAfter = CMTime(value: 1, timescale: 30)
+gen.appliesPreferredTrackTransform = true
+
+let W = 760, H = 560, pad = 16
+let simH = H - 2 * pad
+let firstFrame = try! gen.copyCGImage(at: CMTime(seconds: events.startMs / 1000, preferredTimescale: 600), actualTime: nil)
+let simW = Int(Double(simH) * Double(firstFrame.width) / Double(firstFrame.height))
+let termX = pad + simW + pad
+let termW = W - termX - pad
+
+func color(_ hex: String) -> CGColor {
+  var v: UInt64 = 0; Scanner(string: String(hex.dropFirst())).scanHexInt64(&v)
+  return CGColor(srgbRed: CGFloat((v >> 16) & 0xff) / 255, green: CGFloat((v >> 8) & 0xff) / 255, blue: CGFloat(v & 0xff) / 255, alpha: 1)
+}
+let bg = color("#0b0f14"), termBg = color("#111820"), fg = color("#d8dee6"), dim = color("#7d8590"), ok = color("#3fb950"), accent = color("#79c0ff")
+let font = CTFontCreateWithName("Menlo" as CFString, 12.5, nil)
+let boldFont = CTFontCreateWithName("Menlo-Bold" as CFString, 12.5, nil)
+
+func wrap(_ s: String, width: CGFloat, font: CTFont) -> [String] {
+  // greedy word wrap measured with the real font
+  var lines: [String] = []; var cur = ""
+  for word in s.split(separator: " ", omittingEmptySubsequences: false) {
+    let cand = cur.isEmpty ? String(word) : cur + " " + word
+    let l = CTLineCreateWithAttributedString(NSAttributedString(string: cand, attributes: [kCTFontAttributeName as NSAttributedString.Key: font]))
+    if CTLineGetTypographicBounds(l, nil, nil, nil) > Double(width) && !cur.isEmpty { lines.append(cur); cur = String(word) } else { cur = cand }
+  }
+  if !cur.isEmpty { lines.append(cur) }
+  return lines
+}
+
+func draw(ctx: CGContext, text: String, x: CGFloat, y: CGFloat, color: CGColor, font: CTFont) {
+  let l = CTLineCreateWithAttributedString(NSAttributedString(string: text, attributes: [kCTFontAttributeName as NSAttributedString.Key: font, kCTForegroundColorAttributeName as NSAttributedString.Key: color]))
+  ctx.textPosition = CGPoint(x: x, y: y); CTLineDraw(l, ctx)
+}
+
+func render(at ms: Double) -> CGImage {
+  let cs = CGColorSpace(name: CGColorSpace.sRGB)!
+  let ctx = CGContext(data: nil, width: W, height: H, bitsPerComponent: 8, bytesPerRow: 0, space: cs, bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue)!
+  ctx.setFillColor(bg); ctx.fill(CGRect(x: 0, y: 0, width: W, height: H))
+  // simulator frame, rounded corners
+  let frame = (try? gen.copyCGImage(at: CMTime(seconds: ms / 1000, preferredTimescale: 600), actualTime: nil)) ?? firstFrame
+  let simRect = CGRect(x: pad, y: pad, width: simW, height: simH)
+  ctx.saveGState()
+  ctx.addPath(CGPath(roundedRect: simRect, cornerWidth: 22, cornerHeight: 22, transform: nil)); ctx.clip()
+  ctx.draw(frame, in: simRect)
+  ctx.restoreGState()
+  // terminal panel
+  let termRect = CGRect(x: termX, y: pad, width: termW, height: simH)
+  ctx.setFillColor(termBg); ctx.addPath(CGPath(roundedRect: termRect, cornerWidth: 10, cornerHeight: 10, transform: nil)); ctx.fillPath()
+  var y = CGFloat(H - pad - 28)
+  let lx = CGFloat(termX + 14), lw = CGFloat(termW - 28)
+  if let t = events.title { draw(ctx: ctx, text: t, x: lx, y: y, color: dim, font: font); y -= 26 }
+  for line in events.lines where line.t <= ms {
+    let c: CGColor = line.color == "ok" ? ok : line.color == "accent" ? accent : line.color == "dim" ? dim : fg
+    let f = line.color == "accent" ? boldFont : font
+    for (i, piece) in wrap(line.text, width: lw, font: f).enumerated() {
+      draw(ctx: ctx, text: piece, x: lx + (i > 0 ? 28 : 0), y: y, color: c, font: f); y -= 18
+    }
+    y -= 6
+  }
+  // cursor
+  let blink = Int(ms / 500) % 2 == 0
+  if blink { ctx.setFillColor(fg); ctx.fill(CGRect(x: lx, y: y + 2, width: 8, height: 14)) }
+  return ctx.makeImage()!
+}
+
+let n = Int((events.endMs - events.startMs) / 1000 * events.fps)
+let dest = CGImageDestinationCreateWithURL(out as CFURL, UTType.gif.identifier as CFString, n, nil)!
+CGImageDestinationSetProperties(dest, [kCGImagePropertyGIFDictionary: [kCGImagePropertyGIFLoopCount: 0]] as CFDictionary)
+for i in 0..<n {
+  let ms = events.startMs + Double(i) * 1000 / events.fps
+  let img = render(at: ms)
+  let delay = (i == n - 1) ? 2.0 : 1 / events.fps
+  CGImageDestinationAddImage(dest, img, [kCGImagePropertyGIFDictionary: [kCGImagePropertyGIFDelayTime: delay, kCGImagePropertyGIFUnclampedDelayTime: delay]] as CFDictionary)
+}
+CGImageDestinationFinalize(dest)
+print("wrote \(out.path) \(n) frames \(W)x\(H)")

package/scripts/demo-gif/events.example.json

@@ -0,0 +1,74 @@
+{
+ "startMs": 1790339118840,
+ "endMs": 1790339128578,
+ "fps": 10,
+ "videoEndEpochMs": 1790339127378,
+ "title": "iPhone 17 Pro \u00b7 iOS 26.5 \u00b7 one call from the agent",
+ "lines": [
+  {
+   "t": 1790339119740,
+   "text": "$ simframe do flow.json",
+   "color": "accent"
+  },
+  {
+   "t": 1790339122213,
+   "text": "ok   [0] tap: tapped \"Accessibility\" at 201,380",
+   "color": "ok"
+  },
+  {
+   "t": 1790339123369,
+   "text": "ok   [1] tap: tapped \"Display & Text Size\" at 201,504",
+   "color": "ok"
+  },
+  {
+   "t": 1790339124840,
+   "text": "ok   [2] tap: tapped \"Larger Text\" at 201,216",
+   "color": "ok"
+  },
+  {
+   "t": 1790339125080,
+   "text": "ok   [3] assert: Larger Text is on screen at 201,84",
+   "color": "ok"
+  },
+  {
+   "t": 1790339125528,
+   "text": "flow completed \u2014 4/4 steps in 4645ms",
+   "color": "fg"
+  },
+  {
+   "t": 1790339125878,
+   "text": "iPhone 17 Pro \u00b7 402x874pt \u00b7 screen f0509d55 (known)",
+   "color": "dim"
+  },
+  {
+   "t": 1790339125938,
+   "text": "content:",
+   "color": "fg"
+  },
+  {
+   "t": 1790339125998,
+   "text": "\u00a0\u00a0#1 button    38,84      Display & Text Size",
+   "color": "fg"
+  },
+  {
+   "t": 1790339126058,
+   "text": "\u00a0\u00a0#2 heading   201,84     Larger Text",
+   "color": "fg"
+  },
+  {
+   "t": 1790339126118,
+   "text": "\u00a0\u00a0#3 switch    337,161    Larger Accessibility Sizes = 0",
+   "color": "fg"
+  },
+  {
+   "t": 1790339126178,
+   "text": "\u00a0\u00a0#5 slider    200,783    DYNAMIC_TYPE_SLIDER = 50%",
+   "color": "fg"
+  },
+  {
+   "t": 1790339126238,
+   "text": "next: settled; nothing ambiguous \u2014 chain the next steps in one call",
+   "color": "dim"
+  }
+ ]
+}