simframe 0.19.0 → 0.19.1

package/README.md

@@ -17,12 +17,23 @@ a screenshot, a model round trip and a re-read for every single step.
 You need a Mac with Xcode (you have one if you have a simulator) and Node 18+.
 Nothing else — no idb, no Appium, no Python.
 
-**Claude Code**
+**Claude Code** — as a plugin, which brings the MCP server and the
+[skill](skills/simframe/SKILL.md) that teaches the protocol in one install:
+
+```bash
+claude plugin marketplace add lvlrSajjad/simframe
+claude plugin install simframe@simframe
+```
+
+or the MCP server alone:
 
 ```bash
 claude mcp add --scope user simframe -- npx -y simframe mcp
 ```
 
+Pick one, not both: two installs mean two servers driving the same device. If
+you added it with `claude mcp add` before, `claude mcp remove simframe` first.
+
 **Claude Desktop** — Settings → Developer → Edit Config, then add:
 
 ```json

package/native/simframed/Sources/simframed/main.swift

@@ -186,6 +186,18 @@ case "run":
 
         let minInterval = Double(flag("min-interval-ms") ?? "") ?? 80      // coalesce bursts
         let idleInterval = Double(flag("idle-interval-ms") ?? "") ?? 2000  // keep state fresh
+        // How soon to look again while the last frame said "not settled".
+        //
+        // Settling needs two still frames after the last change, and a still
+        // screen produces no damage, so those frames used to come from the idle
+        // cadence: a change that landed in one frame with nothing after it — a
+        // React Native tab switch, which does not animate — read as moving for
+        // up to two idle intervals, four seconds, on a screen that had stopped.
+        // Reported from the field as `STILL MOVING · frame 2.4s old` over a map
+        // of a screen that had finished. Two probes at this spacing clear
+        // `Motion.stillDurationRequired`, so a finished screen settles ~300ms
+        // after its last change instead.
+        let settleProbeInterval = Double(flag("settle-probe-ms") ?? "") ?? 150
         let idleExitMs = Double(flag("idle-exit-ms") ?? "") ?? 15 * 60_000
 
         let lock = NSLock()
@@ -195,6 +207,7 @@ case "run":
         /// Said once per stall episode, not once per failed read.
         var announcedExhausted = false
         var lastCapture = 0.0
+        var lastSettled = true
         var frames = 0
         var lastReport = Date().timeIntervalSince1970
         var latencies: [Double] = []
@@ -465,7 +478,9 @@ case "run":
             let isDirty = dirty
             lock.unlock()
 
-            let due = (isDirty && now - lastCapture >= minInterval) || (now - lastCapture >= idleInterval)
+            let due = (isDirty && now - lastCapture >= minInterval)
+                || (!lastSettled && now - lastCapture >= settleProbeInterval)
+                || (now - lastCapture >= idleInterval)
             if due {
                 lock.lock(); dirty = false; lock.unlock()
                 let t0 = DispatchTime.now().uptimeNanoseconds
@@ -495,7 +510,8 @@ case "run":
                             return (scaled, native)
                         }
                         let ms = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6
-                        try store.record(bmp, fullBitmap: full, captureMs: ms)
+                        let recorded = try store.record(bmp, fullBitmap: full, captureMs: ms)
+                        lastSettled = (recorded["settled"] as? Bool) ?? true
                         latencies.append(Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6)
                         frames += 1
                         lastCapture = now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "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/smithery-bundle.mjs

@@ -70,7 +70,10 @@ const manifest = {
 fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
 const out = path.join(root, `simframe-${pkg.version}.mcpb`);
-fs.rmSync(out, { force: true });
+// One bundle at a time. A stale one from the previous version sitting next to
+// the new one got published in its place once, by a command line that named
+// the old file.
+for (const f of fs.readdirSync(root)) if (/^simframe-.*\.mcpb$/.test(f)) fs.rmSync(path.join(root, f), { force: true });
 execFileSync('zip', ['-qr', out, '.', '-x', '*.DS_Store'], { cwd: dir });
 fs.rmSync(work, { recursive: true, force: true });
 console.log(`${path.relative(root, out)}: ${tools.length} tools, ${(fs.statSync(out).size / 1e6).toFixed(1)} MB`);

package/scripts/smithery-metadata.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Sets the simframe listing's metadata on Smithery — description, links,
+// license and icon — which the bundle publish does not carry.
+//   node scripts/smithery-metadata.mjs
+//
+// The API key is the one `npx @smithery/cli` stored when it asked for it;
+// SMITHERY_API_KEY in the environment wins if set. Nothing is printed but
+// the server's answers.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const server = 'lvlr-xaus/simframe';
+
+function apiKey() {
+  if (process.env.SMITHERY_API_KEY) return process.env.SMITHERY_API_KEY;
+  const dir = process.env.SMITHERY_CONFIG_PATH
+    ?? (process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'smithery') : path.join(os.homedir(), '.config', 'smithery'));
+  const file = path.join(dir, 'settings.json');
+  const key = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')).apiKey : null;
+  if (!key) throw new Error(`no Smithery API key: set SMITHERY_API_KEY or run any \`npx @smithery/cli mcp publish\` once so it stores one in ${file}`);
+  return key;
+}
+
+const headers = { Authorization: `Bearer ${apiKey()}` };
+const base = `https://api.smithery.ai/servers/${encodeURIComponent(server)}`;
+
+const meta = await fetch(base, {
+  method: 'PATCH',
+  headers: { ...headers, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    displayName: 'simframe',
+    description: 'Eyes, hands and memory for a coding agent driving the iOS Simulator or an Android emulator. Reads the screen as text with tap points, runs whole flows in one call with every step verified, and remembers screens so repeated flows need no model calls.',
+    homepage: 'https://lvlrsajjad.github.io/simframe/',
+    repositoryUrl: 'https://github.com/lvlrSajjad/simframe',
+    backlinkUrl: 'https://lvlrsajjad.github.io/simframe/agents-shouldnt-blink.html',
+    license: 'MIT',
+  }),
+});
+console.log(`metadata: ${meta.status} ${await meta.text()}`);
+
+const icon = new FormData();
+icon.append('icon', new Blob([fs.readFileSync(path.join(root, 'scripts/smithery/icon.png'))], { type: 'image/png' }), 'icon.png');
+const up = await fetch(`${base}/icon`, { method: 'PUT', headers, body: icon });
+console.log(`icon: ${up.status} ${await up.text()}`);

package/scripts/sync-server-version.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// Keep server.json's version in step with package.json's.
+// Keep server.json's and the Claude Code plugin's versions in step with
+// package.json's.
 //
 // `npm version` only knows about package.json, and the MCP registry manifest
 // carries the version twice — once at the top level and once inside the package
@@ -8,7 +9,12 @@
 // the workflow's own agreement check.
 //
 // npm runs this as the `version` lifecycle script: after the bump, before the
-// commit. It stages server.json so the version commit contains both files.
+// commit. It stages both files so the version commit contains all three.
+//
+// The plugin manifest is the second file for the same reason server.json is:
+// a `version` in .claude-plugin/plugin.json pins every installed copy to it, so
+// a manifest left behind by one release would hold plugin users on the
+// previous release's skill forever, with nothing failing.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -30,10 +36,17 @@ server.packages[0].version = pkg.version;
 fs.writeFileSync(file, `${JSON.stringify(server, null, 2)}\n`);
 console.log(`server.json ${before.top} / ${before.pkg} -> ${pkg.version} / ${pkg.version}`);
 
-// Stage it, so `npm version` commits both files together. Harmless when run
-// with --no-git-tag-version; the file is still correct either way.
+const pluginFile = path.join(ROOT, '.claude-plugin', 'plugin.json');
+const plugin = JSON.parse(fs.readFileSync(pluginFile, 'utf8'));
+const pluginBefore = plugin.version;
+plugin.version = pkg.version;
+fs.writeFileSync(pluginFile, `${JSON.stringify(plugin, null, 2)}\n`);
+console.log(`.claude-plugin/plugin.json ${pluginBefore} -> ${pkg.version}`);
+
+// Stage them, so `npm version` commits every file together. Harmless when run
+// with --no-git-tag-version; the files are still correct either way.
 try {
-  execFileSync('git', ['add', '--', file], { cwd: ROOT, stdio: 'pipe' });
+  execFileSync('git', ['add', '--', file, pluginFile], { cwd: ROOT, stdio: 'pipe' });
 } catch {
-  console.log('(could not stage server.json — commit it yourself)');
+  console.log('(could not stage server.json and plugin.json — commit them yourself)');
 }

package/skills/simframe/SKILL.md

@@ -18,6 +18,13 @@ and CV alone. Tapping by label works; screen recognition is thinner, so prefer
 naming a device explicitly and re-reading the screen after a step you are unsure
 about.
 
+Commands are written here as the CLI (`simframe ui`, `simframe do`), which is
+the cheapest path. If `simframe` is not on your PATH — installed as a Claude Code
+plugin, say — the MCP server is already connected and the screen and flow
+commands are its tools under the same names (`sim_ui`, `sim_do`, `sim_state`,
+`sim_goto`…). Use those; for `doctor` and the other diagnostics, ask the user
+to run `npm install -g simframe`.
+
 ## The protocol: plan once, execute once, think only when told to
 
 The expensive thing in a simulator session is not the tapping. It is you —

package/src/actions.js

@@ -939,6 +939,10 @@ export async function runScript(
         action: step.action,
         verification,
         ok: true,
+        // Either sensor saying nothing moved, and no state change explaining
+        // it. The verdict alone missed the case where only the settle
+        // detector saw it: `ok … [no visible change] (never settled)`.
+        unconfirmed: wentNowhere,
         ms: Date.now() - stepStart,
         detail: `${detail}${note}${wrongTurn ? ` [${verification.verdict}: ${verification.detail}]` : ''}`,
         settled,
@@ -3034,6 +3038,9 @@ async function runStep(deviceQuery, udid, step, ctx) {
       const points = { width: geo.pointWidth, height: geo.pointHeight };
       let dir = asked ?? 'down';
       let reversed = false;
+      // Whether any scroll in this step changed what was showing. A step whose
+      // every scroll moved nothing is not evidence about the target at all.
+      let movedOnce = false;
       // Where the target is, when the tree knows. `null` means no evidence, and
       // that distinction is load bearing: guessing "up" without it scrolls to
       // the top of a web page, which **triggers pull-to-refresh**, reloads the
@@ -3155,7 +3162,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
           }
         }
         const { says: evidence, signature: wasShowing } = await lookAround();
-        if (evidence) dir = evidence;
+        // Not after a reversal. The stall that caused it is a measurement that
+        // this direction is exhausted, and letting the tree's hint overrule it
+        // sent the step back the way it had just failed — reported on 0.19.0 as
+        // `it stopped moving both ways (down, down)`, a message naming two
+        // attempts in one direction and claiming both.
+        if (evidence && !reversed) dir = evidence;
         scrolled.push(dir);
         await runStep(deviceQuery, udid, { action: 'scroll', value: dir }, ctx);
         // A scroll either moves immediately or not at all, so it does not need a
@@ -3181,6 +3193,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
         // a scroll as before it, the scroll achieved nothing, whatever the
         // framebuffer did.
         const { signature: nowShowing } = await lookAround();
+        if (wasShowing && nowShowing && wasShowing !== nowShowing) movedOnce = true;
         if (wasShowing && nowShowing && wasShowing === nowShowing) {
           // Before believing the hash, look. See `nowInView` — an unchanged
           // whole-frame hash is weak evidence about a strip, and this step has
@@ -3215,8 +3228,14 @@ async function runStep(deviceQuery, udid, step, ctx) {
               // reversal, so "there is no direction to try" (which it used to
               // say when the tree was silent) is no longer true and would be
               // the same kind of unchecked assertion as the sentence below it.
-              `${query} is not reachable by scrolling: it stopped moving both ways`
+              `${query} is not reachable by scrolling: it stopped moving`
+              + (new Set(scrolled).size > 1 ? ' both ways' : ` scrolling ${scrolled[0]}`)
               + ` (${scrolled.join(', ')}) after ${i + 1} attempt(s).`
+              // Reported on 0.19.0: a React Native ScrollView that a plain swipe
+              // from another tool scrolled at once, and that none of these moved.
+              + (movedOnce ? '' : ' No scroll moved the screen at all, so this says nothing about'
+                + ' where the target is — if this view does scroll, the gesture is not reaching it'
+                + ' (try sim_do with a swipe that starts inside the list, or check input with sim_state).')
               // Say what was established, not what would be convenient. This
               // used to assert "It may not be in the accessibility tree at all"
               // in every case — a claim the function never checks, and one the
@@ -3597,6 +3616,25 @@ export function settleEvidence(w) {
     + (m ? `\n${m.map}` : '');
 }
 
+/**
+ * The mark a step result is printed under: `ok  `, `WARN` or `FAIL`.
+ *
+ * `ok` used to mean only "nothing threw". A tap whose own verdict was
+ * `no-visible-change` printed `ok … [no visible change]`, and a field report
+ * (0.19.0) counted three such taps in a row that had not landed, each caught
+ * only by an outside screenshot, while the escalation log recorded every one
+ * of them as a mis-tap. The verdict was right and the mark contradicted it.
+ *
+ * WARN rather than FAIL, and no automatic retry. `no-visible-change` also
+ * fires on changes too small to register — a field gaining focus was measured
+ * reading as no change on 2026-10-01 — and retrying on a false one is how a
+ * tap fires twice, which the verify barrier forbids.
+ */
+export function stepMark(r) {
+  if (!r?.ok) return 'FAIL';
+  return r.unconfirmed || metrics.ESCALATING_VERDICTS.has(r.verification?.verdict) ? 'WARN' : 'ok  ';
+}
+
 /**
  * The one-line flow summary, so `ok` and `FAIL` each mean exactly one thing.
  *
@@ -3621,7 +3659,15 @@ export function flowSummary(res, { withTime = true } = {}) {
   const skips = skipped
     ? ` (${skipped} optional step${skipped === 1 ? '' : 's'} skipped as absent)`
     : '';
-  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
+  if (res.ok) {
+    // "Completed" over a step that did nothing visible is the same one word
+    // arguing with its numbers that the failure branch below was fixed for.
+    const unconfirmed = (res.results ?? []).filter((r) => stepMark(r) === 'WARN').length;
+    if (unconfirmed) {
+      return `flow ran — ${res.ranSteps}/${res.totalSteps} steps, ${unconfirmed} not confirmed to have landed${time}${skips}`;
+    }
+    return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
+  }
   const failed = (res.results ?? []).filter((r) => r.ok === false).length || 1;
   const worked = Math.max(0, res.ranSteps - failed);
   const unattempted = Math.max(0, res.totalSteps - res.ranSteps);

package/src/cli.js

@@ -268,7 +268,7 @@ async function lineReader() {
 const stepLine = (r) => {
   const settle = r.settled ? (r.settled.ok ? ` (settled ${r.settled.waitedMs}ms)` : ' (never settled)') : '';
   const verdict = r.verification && r.verification.verdict !== 'ok' ? ` [${r.verification.verdict}]` : '';
-  return `${r.ok ? 'ok  ' : 'FAIL'} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}${verdict}`;
+  return `${actions.stepMark(r)} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}${verdict}`;
 };
 
 async function main() {

package/src/index.js

@@ -1989,7 +1989,7 @@ export async function screenIdentity(deviceQuery, { options, confirmNovel = true
     // calling a screen unsettled while the flow was still happily waiting for
     // it — and an unsettled screen records no edge, so the graph learned
     // nothing and every later step read `unverified`.
-    const { state: settledFrame, settled } = await settledState(udid, {
+    const { state: settledFrame, settled, stillnessPredatesAction } = await settledState(udid, {
       settleMs,
       timeoutMs: Math.min(timeoutMs ?? IDENTITY_SETTLE_TIMEOUT_MS, IDENTITY_SETTLE_TIMEOUT_MS),
     });
@@ -2012,6 +2012,10 @@ export async function screenIdentity(deviceQuery, { options, confirmNovel = true
       keyboard: Boolean(entry.keyboard),
       layoutHash: current.layoutHash,
       settled,
+      // Unsettled for the opposite reason to moving: nothing has changed since
+      // the action at all. Both used to render as `STILL MOVING`, which told an
+      // agent to wait for a screen that a missed tap had left perfectly still.
+      unmoved: !settled && Boolean(stillnessPredatesAction),
       // Settled and incomplete are different states and used to render
       // identically. A screen awaiting a network call is perfectly still; a
       // person sees a spinner and knows to wait. The classifier already says

package/src/mcp.js

@@ -1010,7 +1010,7 @@ function stepLines(res) {
         : ` · WARNING: ${r.settled.stalled ? 'capture stalled' : 'never settled'} after ${r.settled.waitedMs}ms`
       : '';
     lines.push(
-      `  ${r.ok ? 'ok  ' : 'FAIL'} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}`,
+      `  ${actions.stepMark(r)} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}${settle}`,
     );
   }
   if (!res.ok) lines.push('later steps were not run; the screen is left wherever the failing step stopped');
@@ -1153,7 +1153,7 @@ async function goto(target, args, options) {
     ? [`already on "${res.screen}"`]
     : [
         `${res.ok ? 'arrived at' : 'DID NOT REACH'} "${res.screen}" in ${res.ranSteps}/${res.steps.length} remembered steps`,
-        ...(res.results ?? []).map((r) => `  ${r.ok ? 'ok  ' : 'FAIL'} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}`),
+        ...(res.results ?? []).map((r) => `  ${actions.stepMark(r)} [${r.index}] ${r.action}: ${r.ok ? r.detail : r.error}`),
       ];
   lines.push('', await mapFrom(target, options, null));
   return { content: [text(lines.join('\n'))], isError: !res.ok };

package/src/refs.js

@@ -145,10 +145,27 @@ export function resolveRef(udid, n, { structuralHash, layoutHash, screenKnown, s
     throw staleError(`this is a different screen (${table.structuralHash.slice(0, 8)}`
       + ` → ${structuralHash.slice(0, 8)})`, 'identity');
   }
+  // Computed before the recognition check, because it is also the evidence that
+  // check was missing. See the drift refusal below for what it measures.
+  const drift = layoutHash && table.layoutHash && informative(table.layoutHash) && informative(layoutHash)
+    ? hashDistance(table.layoutHash, layoutHash)
+    : null;
   // Nothing recognises the screen we are on, so nothing can vouch for the
   // numbers. Refusing costs a re-read; guessing taps whatever is at those
   // coordinates now.
-  if (screenKnown === false) {
+  //
+  // Except the refs table itself. A read that never settled numbers the
+  // elements and persists no map (`persist: settled`), so the very next call
+  // found screen memory empty and refused refs issued one second earlier on
+  // the same screen — `integration (memory)` went red on that twice running on
+  // an unchanged tree, a runner slow enough to miss the settle timeout being
+  // all it took. Screen memory recalls by the same layout distance and the same
+  // tolerance, so an informative hash this close to the table's is the test
+  // memory would have passed had it been allowed to remember; when the table's
+  // screen *was* remembered, recall would already have found it, and this
+  // changes nothing.
+  const vouchedByTable = drift != null && drift <= tolerance;
+  if (screenKnown === false && !vouchedByTable) {
     // Flagged, like every other refusal in this function, and it was the one
     // that was not.
     //
@@ -178,9 +195,6 @@ export function resolveRef(udid, n, { structuralHash, layoutHash, screenKnown, s
   // routinely while the hashes differ. So this says the distance, and says that
   // it is pixels rather than identity — a different thing from the branch above,
   // which had been wearing the same sentence.
-  const drift = layoutHash && table.layoutHash && informative(table.layoutHash) && informative(layoutHash)
-    ? hashDistance(table.layoutHash, layoutHash)
-    : null;
   if (drift != null && drift > tolerance) {
     throw staleError(`the screen has moved too far from where these refs were numbered`
       + ` (layout distance ${drift}, tolerance ${tolerance}) — the identity may be unchanged;`

package/src/view.js

@@ -628,7 +628,7 @@ export async function screenMap(deviceQuery, {
  * cheerfully says "carry on" into an unknown screen would be worse than no hint
  * at all.
  */
-export function nextHint({ ok, escalated, settled, loading, known, hash, exits, elements, ambiguous, filtered, exitList, staleExits } = {}) {
+export function nextHint({ ok, escalated, settled, unmoved, loading, known, hash, exits, elements, ambiguous, filtered, exitList, staleExits } = {}) {
   if (ok === false) {
     return 'next: the flow stopped here — this is the moment to think. sim_recall shows how you got here; sim_ui re-reads the screen.';
   }
@@ -654,6 +654,9 @@ export function nextHint({ ok, escalated, settled, loading, known, hash, exits,
   if (loading) {
     return 'next: settled, but the transition classifier still sees loading — an empty-looking region may be a list that has not arrived. waitFor a string you expect rather than acting on this.';
   }
+  if (settled === false && unmoved) {
+    return 'next: nothing on the screen has changed since the last action. If that action should have changed it, it did not land — re-read with sim_ui before acting again, and do not assume the step worked.';
+  }
   if (settled === false) {
     return 'next: the screen is still moving. sim_state polls it for a fraction of a map; do not act on this reading yet.';
   }
@@ -706,6 +709,7 @@ export function hintFor(map, { flowOk = true, escalated = false } = {}) {
     escalated: Boolean(escalated),
     filtered: map?.filtered === true,
     settled: map?.identity?.settled !== false,
+    unmoved: map?.identity?.unmoved === true,
     loading: map?.identity?.loading === true,
     known: map?.exits != null,
     hash: map?.identity?.hash ?? null,
@@ -795,7 +799,7 @@ export function render({ device, identity, rows, truncated, collapsed, screen, n
         (exits == null ? ' (new to simframe)' : ` (known, ${exits} known exit${exits === 1 ? '' : 's'})`)
       : 'screen unidentified',
     identity?.keyboard ? 'keyboard up' : null,
-    identity?.settled === false ? 'STILL MOVING' : null,
+    identity?.settled === false ? (identity?.unmoved ? 'NOT MOVED SINCE THE ACTION' : 'STILL MOVING') : null,
     // Still and finished are not the same thing.
     identity?.loading === true ? 'STILL LOADING' : null,
     // How old the *frame* this map was read from is.