simframe 0.7.2 → 0.8.0

package/README.md

@@ -37,6 +37,7 @@ Same four-tab navigation flow, on a real production app:
 | | Before | With simframe |
 | --- | --- | --- |
 | Look at the screen | ~130–400 ms, blocking | **~20 ms**, already captured |
+
 | "Did anything change?" | a full image | **~2 ms**, text only |
 | Finding a control | read tree (~570 ms) + reason | **~1 ms** from memory |
 | A 4-step flow, verified | 4+ model round trips | **1 call**, 3.6 s |
@@ -44,6 +45,13 @@ Same four-tab navigation flow, on a real production app:
 | A 10-step flow | 10 turns, 10 images (~16,000 tokens at best) | **1 turn, 0 images, ~1,650 characters** |
 | Reading a screen | an image: ~1,600 tokens, no tap points | **~330 tokens** of text, with tap points |
 
+Every figure above is the cost inside a live process — the MCP server, or the
+daemon answering a socket — which is how an agent actually uses simframe. A
+one-shot `simframe` command from a shell pays about 200 ms of Node startup on
+top, and a frame sitting on an idle screen can be older than 20 ms because the
+capture loop throttles when nothing moves. `~20 ms` is the read, not the
+process.
+
 The four-tab tour, three times back to back from a cleared memory:
 
 | Pass | Wall clock | Steps verified | Controls from memory |
@@ -67,10 +75,16 @@ npm install -g simframe
 simframe doctor
 ```
 
-The first `simframe start` builds a small Swift daemon from source — a few
-seconds, once. It needs the Xcode command line tools, which you already have if
-you have a simulator. Without them simframe falls back to the original
-`simctl` loop and says so.
+**Whichever of those two commands you run first** builds a small Swift daemon
+from source — including `doctor`, which is why a cold `doctor` takes around 15
+seconds and every later one takes two. It needs the Xcode command line tools,
+which you already have if you have a simulator. Without them simframe falls
+back to the original `simctl` loop and says so.
+
+If more than one simulator is booted, name the one you mean — `--device=<udid>`,
+or `export SIMFRAME_DEVICE=<udid>` once per shell. simframe refuses to choose
+for you, because the first booted device is nobody's idea of "yours" and the
+command that would act on it is a tap.
 
 `doctor` checks each capability separately and tells you what you have:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.7.2",
+  "version": "0.8.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/ci-memory.mjs

@@ -257,7 +257,14 @@ if (first) {
   // to defend — and it is how this check has failed twice.
   if (moved) {
     const stale = await cli(['find', `#${first.ref}`], { expectFail: true });
-    check(/different screen|read the screen/i.test(stale),
+    // Matched on prose, which is this check's weakness: simframe refused
+    // correctly with "#1 cannot be trusted here — simframe does not recognise
+    // this screen. Read it again", and the check failed because that wording was
+    // not one of the two it knew. The refusal is what matters, so the
+    // alternation covers how a refusal is actually phrased; the durable fix is a
+    // machine-readable reason on the failure, which `find --json` does not yet
+    // carry.
+    check(/different screen|read the screen|read it again|does not recognise this screen|cannot be trusted/i.test(stale),
       'a ref numbered on another screen refuses instead of tapping those coordinates',
       stale.trim().split('\n')[0]?.slice(0, 90));
   }
@@ -398,7 +405,13 @@ check(Array.isArray(nonsense.known) && nonsense.known.length > 0,
 
 const target = screens[0];
 const walked = await jsonRetry(['goto', target.hash], { allowFail: true });
-const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen'];
+// `no-identity` is new in 0.7.2 and belongs here: `goto` used to *throw*
+// `Cannot read properties of null (reading 'slice')` on a screen whose token set
+// was empty, because `hashTokens` returns null for one on purpose. A crash is
+// neither walking there nor naming why it cannot, so this check failed with an
+// empty detail — the reason was `undefined` — and the check was right to fail.
+// Now there is a name for it, and the list has to know the name.
+const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen', 'no-identity'];
 check(walked.ok === true || outcomes.includes(walked.reason),
   'and asked for a screen it knows, it either walks there or names why it cannot',
   walked.ok ? (walked.already ? 'already there' : `walked ${walked.ranSteps} step(s)`) : walked.reason);

package/src/cli.js

@@ -243,6 +243,11 @@ async function main() {
         `stopped ${stopped} daemon${stopped === 1 ? '' : 's'}` +
           (inUse ? `; left ${inUse} in use by another client (pass --force to stop anyway)` : ''),
       );
+      // Asked to stop one device, refused, and exited 0 — which is a success
+      // code for work not done, and a script checking `$?` could not tell the
+      // difference. `--all` is informational by nature, so it keeps exiting 0
+      // when it skips a device somebody else holds.
+      if (!flags.all && inUse && !stopped) process.exitCode = 1;
       return;
     }
 

package/src/platform/android.js

@@ -176,6 +176,18 @@ async function resolveDevice(query, opts) {
           : 'no booted emulator (start one with `emulator -avd <name>`)',
       );
     }
+    // See the same guard in ios.js: an arbitrary pick is a tap on the wrong
+    // device, and this backend can act too.
+    if (booted.length > 1) {
+      throw Object.assign(
+        new Error(
+          `${booted.length} emulators are running and none was named: ` +
+            `${booted.map((d) => `${d.name} (${d.udid})`).join(', ')} — name one with --device, ` +
+            'or set SIMFRAME_DEVICE to pick a default for this shell',
+        ),
+        { ambiguous: true },
+      );
+    }
     return booted[0];
   }
   const q = loose(query);

package/src/platform/ios.js

@@ -66,6 +66,29 @@ async function resolveDevice(query, opts) {
   const booted = all.filter((d) => d.state === 'Booted');
   if (!query) {
     if (booted.length === 0) throw new Error('no booted simulator (open Simulator.app or run `xcrun simctl boot <udid>`)');
+    // `booted[0]` was the wrong-device bug, and it was worse than it looked.
+    // simctl's order is not "yours" by any definition, so on a machine with
+    // more than one booted simulator a bare `simframe ui` read whichever came
+    // first — and a bare `simframe tap` would have *injected input* into it. A
+    // reviewer reproduced it deterministically against a colleague's simulator.
+    //
+    // `doctor` got a guard for its own fan-out and this default did not, which
+    // is how the same command set could pick two different devices in one
+    // moment. Refusing is the only safe answer here: the seam cannot see which
+    // device simframe is already driving (that is store state, above the
+    // boundary), and a backend must never guess when the cost of guessing wrong
+    // is a tap on somebody else's screen. `ambiguous` so that a second platform
+    // matching cleanly cannot override this — see resolveAcross.
+    if (booted.length > 1) {
+      throw Object.assign(
+        new Error(
+          `${booted.length} simulators are booted and none was named: ` +
+            `${booted.map((d) => `${d.name} (${d.udid})`).join(', ')} — name one with --device, ` +
+            'or set SIMFRAME_DEVICE to pick a default for this shell',
+        ),
+        { ambiguous: true },
+      );
+    }
     return booted[0];
   }
   const q = query.toLowerCase();