simframe 0.9.0 → 0.11.0

package/src/analyze.js

@@ -35,6 +35,42 @@ export function signatureDiff(a, b) {
   return sum / a.length / 255;
 }
 
+/**
+ * A change small enough that the whole-screen mean cannot see it.
+ *
+ * `changed` in both daemons is `signatureDiff > 0.004`, a mean over a 4x8 grid
+ * of gray means. Measured on this device, an iOS switch flipping:
+ *
+ *   mean diff        0.001348   — a third of the threshold, so: not a change
+ *   max cell delta   0.043137   — one cell of thirty-two, in row 1
+ *
+ * So the entire class of small binary controls — switches, radio dots,
+ * checkboxes, segment highlights — changes nothing as far as the daemon is
+ * concerned, and a step that flips one reports `no-visible-change`, which is a
+ * verdict that escalates.
+ *
+ * The threshold sits in a measured gap rather than being chosen. Eighty seconds
+ * of a *static* screen gave a largest per-cell delta of 0.003922, in row 0,
+ * which is the status-bar clock ticking over — the only thing moving. So the
+ * separation is 0.0039 against 0.0431, eleven times, and 0.012 is three times
+ * the noise and three and a half times under the signal. No row is excluded:
+ * the clock does not reach the threshold, which is a better reason to ignore it
+ * than a structural exclusion that would also blind the nav bar.
+ *
+ * What this deliberately does **not** do is feed stillness. `stableForMs` stays
+ * on the mean, because a blinking text caret is a small localised change and a
+ * screen with a cursor in it would otherwise never settle. The two signals are
+ * independent by design: this one answers "did the action do anything", and the
+ * mean answers "has the screen finished moving".
+ */
+export const CELL_CHANGE = 0.012;
+
+/** The largest single-region change between two signatures, 0-1. */
+export function maxCellDelta(a, b) {
+  const deltas = regionDeltas(a, b);
+  return deltas.length ? Math.max(...deltas) : 0;
+}
+
 /** Per-region change fractions, so callers can tell a toast from a screen push. */
 export function regionDeltas(a, b) {
   if (!a || !b || a.length !== b.length) return a ? a.map(() => 1) : [];
@@ -69,6 +105,40 @@ export function signatureToHex(sig) {
   return sig.map((v) => v.toString(16).padStart(2, '0')).join('');
 }
 
+/**
+ * Is this frame black — not dark, black?
+ *
+ * The capture wedge (docs/BENCHMARKS.md) leaves `simctl io screenshot`
+ * succeeding and returning 0 non-black pixels of 3,162,132, and simframe's own
+ * frames go the same way: the display pipeline stops rendering while
+ * everything about the capture path keeps reporting success. It self-recovers
+ * most times and a device restart cures the rest, so the useful thing is to
+ * notice early — before a settle spends its whole budget deciding a black
+ * screen is a calm one.
+ *
+ * The signature is already computed for every frame, so this costs 32 integer
+ * comparisons and no decode. A real screen does not come close: measured on
+ * this device's Settings root, the 32 bytes ran 191–245.
+ *
+ * The threshold is a level, not a fraction, and it is on the *maximum*: one
+ * cell with anything in it is enough to say the display is rendering. That
+ * matters because a dark-mode screen, a video, or a splash on black are all
+ * legitimately near-zero in most cells and this must not call them faults.
+ *
+ * And it says "the frames are black", never "the simulator is wedged". A
+ * screen can be black because the app drew black. What makes it a wedge is
+ * that it stays black while input is being delivered, and only the caller
+ * knows that.
+ */
+export const BLACK_LEVEL = 8;
+
+export function isBlackFrame(sig, { level = BLACK_LEVEL } = {}) {
+  const bytes = typeof sig === 'string' ? hexToSignature(sig) : sig;
+  if (!bytes?.length) return false;
+  for (const b of bytes) if (b > level) return false;
+  return true;
+}
+
 export function hexToSignature(hex) {
   const out = [];
   for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));

package/src/cli.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { runDaemon, DEFAULTS } from './daemon.js';
 import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, screenshot, toolchainChecks } from './platform/index.js';
 import * as actions from './actions.js';
+import * as analyze from './analyze.js';
 import * as api from './index.js';
 import * as input from './input.js';
 import * as baseline from './baseline.js';
@@ -20,6 +21,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe start   [device]          start the capture loop in the background
   simframe stop    [device|--all]    stop the capture loop
   simframe status  [device]          show daemon and newest-frame status
+  simframe input   reset             rebuild the HID session (see doctor)
   simframe frame   [device]          write the newest frame to a file
   simframe state   [device]          print frame metadata and the change map
   simframe mark    [device]          print the current frame hash, to use as --since
@@ -45,6 +47,10 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe baseline list             recorded runs per flow, and what is committed
   simframe hpi     [device]          Human Parity Index, per flow and overall
   simframe escalations [device]      why simframe handed decisions back, by reason
+                                     (--session=<id> narrows to one agent; the
+                                     ids are listed in the output. SIMFRAME_SESSION
+                                     names one, but only at process start — an
+                                     already-running MCP server cannot pick it up)
   simframe devices                   list simulators
   simframe doctor                    check that this machine can capture
                                      (--strict, or SIMFRAME_STRICT=1, makes any
@@ -160,6 +166,25 @@ const num = (v, fallback) => (v == null ? fallback : Number(v));
  * script that has to parse one command's prose and another's JSON will parse
  * the prose wrong exactly once and then be trusted anyway.
  */
+/**
+ * The machine-readable half of a failure.
+ *
+ * A refusal recognisable only by reading its prose is a refusal nobody can
+ * depend on. Our own CI asserted the stale-ref guard by matching three
+ * phrasings and went red when a fourth arrived — a *better* one, naming the
+ * label the number stood for. The sentence is for a person; these fields are
+ * the contract, and they live in one function because `find` reports its own
+ * failures and the top-level handler reports the rest.
+ */
+function failureJson(err) {
+  return {
+    ok: false,
+    error: err.message,
+    reason: metrics.escalationOf(err)?.reason ?? null,
+    ...(err.staleRef ? { staleRef: true, staleKind: err.staleKind ?? null, staleLabel: err.staleLabel ?? null } : {}),
+  };
+}
+
 function emit(flags, json, lines) {
   if (flags.json) {
     console.log(JSON.stringify(json, null, 2));
@@ -169,11 +194,26 @@ function emit(flags, json, lines) {
   if (body != null) console.log(Array.isArray(body) ? body.filter((l) => l != null).join('\n') : body);
 }
 
-/** The end-state screen map, rendered from a reading the flow already took. */
-async function mapText(device, options, identity) {
+/**
+ * The end-state screen map, re-read rather than recalled, with its hint.
+ *
+ * Both halves were reported against Phase 11.5 and both were right. The map was
+ * rendered from whatever reading the flow already had, which is memory-first —
+ * so a trailing map could describe the screen as it was seconds ago, and the
+ * remedy in practice was a `ui --refresh` after nearly every call, which is a
+ * whole extra turn to save a few hundred milliseconds. Wrong way round.
+ *
+ * And the hint was only ever printed by the MCP server, so no CLI user could
+ * see it and no CLI run could test it.
+ */
+async function mapText(device, options, identity, { flowOk = true, escalated = false, refresh = true } = {}) {
   try {
-    const m = await view.screenMap(device, { options, identity: identity?.entry ? identity : undefined });
-    return m.text;
+    const m = await view.screenMap(device, {
+      options,
+      refresh,
+      identity: refresh ? undefined : (identity?.entry ? identity : undefined),
+    });
+    return `${m.text}\n${view.hintFor(m, { flowOk, escalated })}`;
   } catch (err) {
     return `(could not read the screen: ${err.message})`;
   }
@@ -229,6 +269,11 @@ async function main() {
   if (flags.maxDim) options.maxDim = num(flags.maxDim);
   if (flags.ringSize) options.ringSize = num(flags.ringSize);
   if (flags.engine) options.engine = String(flags.engine);
+  // Per-command overrides for the two experiment knobs, so an A/B is an
+  // argument rather than a restart. `--sensor=ax-first`, `--planner=apple`.
+  if (flags.sensor) options.sensor = String(flags.sensor);
+  if (flags.planner) options.planner = String(flags.planner);
+  if (flags.supervisor) options.supervisor = String(flags.supervisor);
 
   switch (command) {
     case undefined:
@@ -310,6 +355,29 @@ async function main() {
       return;
     }
 
+    // Rebuild the daemon's HID session, and nothing else.
+    //
+    // The narrow remedy for the narrow fault. Restarting the daemon also cures
+    // a stale session and throws away the frame ring and every warm cache to do
+    // it, which is the difference between a fix and a power cycle.
+    case 'input': {
+      const what = positional[0];
+      if (what !== 'reset') throw new Error('usage: simframe input reset [--device <udid>]');
+      const dev = await resolveDevice(device);
+      const before = await input.sessionHealth(dev.udid);
+      const reset = await input.resetSession(dev.udid);
+      if (!reset) {
+        // Said plainly rather than as a success: there is no daemon holding a
+        // session to rebuild, so nothing was wrong and nothing was done.
+        console.log(`no simframed session to rebuild for ${dev.name} — the daemon is not running, or this device is not driven by it`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(`rebuilt the HID session for ${dev.name}`
+        + (before.stale ? `\n  it was stale: ${before.reason}` : '\n  it did not report stale; rebuilt anyway, as asked'));
+      return;
+    }
+
     case 'status': {
       const udids = device
         ? [(await resolveDevice(device)).udid]
@@ -508,6 +576,7 @@ async function main() {
         all: Boolean(flags.all),
         refresh: Boolean(flags.refresh),
       });
+      m.text = `${m.text}\n${view.hintFor(m)}`;
       emit(
         flags,
         {
@@ -560,6 +629,7 @@ async function main() {
         stableMs: num(flags.stableMs, 500),
         timeoutMs: num(flags.timeoutMs, 8000),
         continueOnError: Boolean(flags.continueOnError),
+        supervise: flags.supervise ? String(flags.supervise) : undefined,
         options,
       });
       const saved = flags.save
@@ -567,7 +637,16 @@ async function main() {
         : null;
       // `--map=false` arrives as the string "false"; `--no-map` as true.
       const wantMap = !flags.json && flags.noMap !== true && String(flags.map ?? 'true') !== 'false';
-      const map = wantMap ? await mapText(flags.device, options, res.endScreen) : null;
+      // Every local ruling, so a wrong one is correctable rather than
+      // mysterious — and the model's stated reason is shown as its claim.
+      for (const s_ of res.supervisions ?? []) {
+        console.log(`supervisor at step ${s_.index}: ${s_.decision} — ${s_.outcome}`
+          + (s_.reason ? ` (it said: "${s_.reason}")` : ''));
+      }
+      const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));
+      const map = wantMap
+        ? await mapText(flags.device, options, res.endScreen, { flowOk: res.ok, escalated })
+        : null;
       emit(
         flags,
         {
@@ -787,7 +866,7 @@ async function main() {
           ],
         );
       } catch (err) {
-        emit(flags, { ok: false, error: err.message }, err.message);
+        emit(flags, failureJson(err), err.message);
         process.exitCode = 1;
       }
       return;
@@ -951,23 +1030,52 @@ async function main() {
     case 'escalations': {
       const dev = await resolveDevice(flags.device);
       const records = metrics.readEscalations(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
-      const b = metrics.breakdown(records);
+      const b = metrics.breakdown(records, {
+        session: flags.session === true ? metrics.sessionId() : (flags.session ? String(flags.session) : null),
+        flow: flags.flow ? String(flags.flow) : null,
+      });
       if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify(b, null, 2)}\n`);
       emit(flags, b, [
         `${b.total} escalation${b.total === 1 ? '' : 's'} on ${dev.name}`,
         ...metrics.REASONS
           .filter((r) => b.by_reason[r])
           .sort((a, c) => b.by_reason[c] - b.by_reason[a])
-          .map((r) => `  ${r.padEnd(20)} ${String(b.by_reason[r]).padStart(4)}   would be removed by: ${metrics.FACULTY[r]}`),
+          .map((r) => `  ${r.padEnd(20)} ${String(b.by_reason[r]).padStart(4)}   `
+            + (metrics.BUILT_FACULTIES.has(metrics.FACULTY[r])
+              ? `not removed by: ${metrics.FACULTY[r]} [built]`
+              : `would be removed by: ${metrics.FACULTY[r]}`)),
         b.total ? '' : null,
         b.total ? `avoidable ${b.avoidable}/${b.total} (${b.avoidable_escalation_rate})` : null,
         // Said out loud rather than left for someone to discover: the rate is
         // 1.0 while no faculty exists, so the breakdown above is the number
         // that decides the next phase.
         b.total && b.avoidable_escalation_rate === 1
-          ? '  every reason maps to a faculty that is not built yet, so this rate is 1.0 by construction. The per-reason counts are the steering wheel.'
+          ? (metrics.REASONS.some((r) => b.by_reason[r] && metrics.BUILT_FACULTIES.has(metrics.FACULTY[r]))
+            ? '  the rate is 1.0 because nothing resolves locally yet. A reason marked [built] is not a queue waiting on a phase — it is evidence the phase that shipped is not sufficient.'
+            : '  every reason maps to a faculty that is not built yet, so this rate is 1.0 by construction. The per-reason counts are the steering wheel.')
           : null,
         b.total ? `model turns spent on escalations: ${b.model_turns_spent}` : null,
+        // The log is per-device and shared. Said before the counts are used,
+        // not after: two agents on one booted simulator write one interleaved
+        // file, and CLAUDE.md makes these counts the thing that picks the next
+        // faculty. A pooled breakdown errs toward whichever session made more
+        // mistakes, which is a different question.
+        b.pooled
+          ? 'WARNING these counts may pool more than one agent\'s work: '
+            + [
+              b.session_count > 1 ? `${b.session_count} sessions` : null,
+              b.unattributed ? `${b.unattributed} record(s) written before sessions were logged` : null,
+            ].filter(Boolean).join(', ')
+            + '. Narrow with --session (this process), --session=<id>, or --flow=<name>.'
+          : null,
+        b.session_count > 1 ? 'sessions:' : null,
+        ...(b.session_count > 1
+          ? b.sessions.map((x) => `  ${x.session_id.padEnd(22)} ${String(x.count).padStart(4)}  ${x.client}`)
+          : []),
+        Object.keys(b.by_flow).length > 1 ? 'flows:' : null,
+        ...(Object.keys(b.by_flow).length > 1
+          ? Object.entries(b.by_flow).slice(0, 10).map(([n, c]) => `  ${n.padEnd(28)} ${String(c).padStart(4)}`)
+          : []),
         b.top_screens.length ? 'top screens:' : null,
         ...b.top_screens.map((s) => `  ${s.fingerprint.slice(0, 16).padEnd(18)} ${s.count}`),
         metrics.writeError() ? `WARNING a log write failed: ${metrics.writeError()}` : null,
@@ -993,6 +1101,10 @@ async function main() {
         json: Boolean(flags.json),
         strict: Boolean(flags.strict) || process.env.SIMFRAME_STRICT === '1',
         device: flags.device,
+        // So `doctor --sensor=ax-first --planner=apple` reports the mode the
+        // caller is about to use, not the one the environment happens to hold.
+        // Confirming the mode before a run is the whole reason to read this.
+        options,
       });
       return;
     }
@@ -1069,7 +1181,7 @@ async function blackScreenProbe(udid) {
   }
 }
 
-async function doctor({ json = false, strict = false, device } = {}) {
+async function doctor({ json = false, strict = false, device, options = {} } = {}) {
   const checks = [];
   // `level` is 'ok' | 'warn' | 'fail'. A warn means it works but not the way it
   // should — the exact state that used to be invisible.
@@ -1118,6 +1230,55 @@ async function doctor({ json = false, strict = false, device } = {}) {
     add('on-device OCR', 'warn', err.message, { key: 'ocr.available', value: false });
   }
 
+  // Which sensors a read asks for, and what the recognition-level flag can and
+  // cannot reach. Stated because `SIMFRAME_OCR` looks like it configures the
+  // OCR everyone uses and does not: the daemon reads text in-process off the
+  // framebuffer and owns its own recognition level, so the flag only reaches
+  // the no-daemon fallback in `native/ocr.swift`.
+  try {
+    const api = await import('./index.js');
+    const ocrMod = await import('./ocr.js');
+    const mode = api.sensorMode(options);
+    add('sensor mode', 'ok',
+      mode === 'ax-first'
+        ? 'ax-first — the tree alone (~50ms), paying for OCR only when a resolve fails'
+        : 'full — accessibility and OCR fused on every read (~164ms)',
+      { key: 'sensor.mode', value: mode });
+    add('OCR level', 'ok', `${ocrMod.level()} (fallback helper only; the daemon owns its own)`, {
+      key: 'ocr.level',
+      value: ocrMod.level(),
+    });
+  } catch { /* reported by the layers above */ }
+
+  // The local supervisor. Behind the hands and in front of the reasoner, and
+  // able to say only wait/retry/stop.
+  try {
+    const supervisor = await import('./supervisor.js');
+    const st = await supervisor.status(options);
+    add('local supervisor', 'ok', `${st.supervisor} — ${st.detail}`, {
+      key: 'supervisor.backend',
+      value: st.supervisor,
+    });
+    supervisor.close();
+  } catch (err) {
+    add('local supervisor', 'ok', `none — ${err.message}`, { key: 'supervisor.backend', value: 'none' });
+  }
+
+  // The local planner tier. `none` is the normal answer and not a fault: it is
+  // off unless SIMFRAME_PLANNER asks for it, and it only ever reorders
+  // candidates that exploration was going to try anyway.
+  try {
+    const planner = await import('./planner.js');
+    const st = await planner.status(options);
+    add('local planner', 'ok', `${st.planner} — ${st.detail}`, {
+      key: 'planner.backend',
+      value: st.planner,
+    });
+    planner.close();
+  } catch (err) {
+    add('local planner', 'ok', `none — ${err.message}`, { key: 'planner.backend', value: 'none' });
+  }
+
   try {
     let booted = await bootedDevices();
     // Respect --device. Without this, doctor reports on every booted simulator,
@@ -1228,7 +1389,18 @@ async function doctor({ json = false, strict = false, device } = {}) {
       // dispatched successfully and moved nothing, five runs in a row.
       const session = await input.sessionHealth(d.udid);
       if (session.stale) {
-        add(`input session (${d.name})`, 'warn', `stale — ${session.reason}. The next action rebuilds it automatically; simframe stop && simframe start does it now`,
+        // The remedy used to read "the next action rebuilds it automatically;
+        // simframe stop && simframe start does it now", and both halves were
+        // wrong. The first was false wherever it mattered, because the rebuild
+        // check was gated once per process and the MCP server is one process
+        // for a whole session. The second names a command that fails twice:
+        // `stop` needs `--device` when two simulators are booted, and then
+        // refuses because a client holds the daemon, so the sequence that
+        // actually works is `stop --device <udid> --force && start --device
+        // <udid>` — a daemon restart, to fix a session, when rebuilding the
+        // session is a thing the daemon can already do on request. It just had
+        // no way in from outside. It does now.
+        add(`input session (${d.name})`, 'warn', `stale — ${session.reason}. The next action rebuilds it; simframe input reset --device ${d.udid} does it now`,
           { key: 'input.session', value: 'stale' });
       } else if (caps.input.supported) {
         add(`input session (${d.name})`, 'ok', session.reason ?? 'current with this device session',
@@ -1252,8 +1424,20 @@ async function doctor({ json = false, strict = false, device } = {}) {
     if (probed.length) {
       const t0 = Date.now();
       const res = await api.getFrame(probed[0].udid);
-      add('capture', 'ok',
-        `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`,
+      // The wedge's whole signature is that everything here reports success.
+      // A black frame is 32 integer comparisons on a signature already
+      // computed, and it is what separates "captured a frame" from "captured
+      // a frame of a display that has stopped rendering".
+      const dark = analyze.isBlackFrame(
+        (res.state.history ?? []).find((h) => h.seq === res.state.seq)?.sig ?? null,
+      );
+      add('capture', dark ? 'warn' : 'ok',
+        `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`
+        + (dark
+          ? ' — and every pixel of it is black. If the device is not showing a black screen on purpose,'
+            + ' this is the display pipeline having stopped rendering; it usually recovers on its own,'
+            + ` and ${'xcrun simctl shutdown'} / boot is the cure that always works.`
+          : ''),
         { key: 'capture.frames', value: res.state.seq });
       // A wedged device produces the same nothing as a quiet one, so doctor has
       // to ask the capture loop rather than look at the frames. `fail`, not
@@ -1321,13 +1505,28 @@ async function doctor({ json = false, strict = false, device } = {}) {
   process.exitCode = failed.length || (strict && warned.length) ? 1 : 0;
 }
 
-main().catch((err) => {
+// A long-lived local helper must not decide when the CLI exits. It is closed
+// after every command, whether or not one was ever started — `close()` on an
+// unopened planner is a no-op, and leaving it open made a finished flow hang.
+const closeHelpers = async () => {
+  try {
+    const planner = await import('./planner.js');
+    planner.close();
+    const supervisor = await import('./supervisor.js');
+    supervisor.close();
+  } catch { /* nothing to close */ }
+};
+
+main().then(closeHelpers, async (err) => {
+  await closeHelpers();
+  throw err;
+}).catch((err) => {
   // A caller that asked for JSON gets JSON, failures included. Printing prose
   // here handed `JSON.parse` a SyntaxError instead of a reason, so a script
   // could not tell "the daemon lost the display" from "simframe is broken" —
   // which is the whole point of a machine-readable interface.
   if (process.argv.includes('--json')) {
-    process.stdout.write(`${JSON.stringify({ ok: false, error: err.message }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(failureJson(err), null, 2)}\n`);
   } else {
     process.stderr.write(`simframe: ${err.message}\n`);
   }

package/src/control.js

@@ -65,6 +65,7 @@ export const swipe = (udid, from, to, opts = {}) =>
 export const type = (udid, text) => request(udid, { action: 'type', text });
 export const paste = (udid, text) => request(udid, { action: 'paste', text });
 export const press = (udid, button) => request(udid, { action: 'press', button });
+export const key = (udid, usage, modifiers = []) => request(udid, { action: 'key', usage, modifiers });
 export const status = (udid) => request(udid, { action: 'status' });
 export const resetInput = (udid) => request(udid, { action: 'resetInput' });
 export const longPress = (udid, x, y, opts = {}) => request(udid, { action: 'longPress', x, y, ...opts });

package/src/fingerprint.js

@@ -30,8 +30,26 @@ import * as regions from './regions.js';
  *     list screen. Same rules, different input, therefore different hashes —
  *     and a stored hash that can never match again is the quietest kind of
  *     wrong, which is what this counter exists to prevent.
+ * 5 — a phantom keyboard was deleting screens' content from their identity. A
+ *     dozen short text rows of uniform height stacked low on a read-only
+ *     summary satisfied every size-and-uniformity test for a keyboard, and
+ *     `tokens` discards everything below `keyboardTop` — so two screens of one
+ *     wizard, sharing a nav title and a step indicator, collapsed onto a single
+ *     hash. `detectKeyboardTop` now requires the small uniform boxes to be
+ *     key-shaped. Every screen with content in its lower half hashes
+ *     differently, so the stored graph and maps must go.
+ * 6 — the opposite half of the same bug, and it took a recorded screen to see.
+ *     `KEYBOARD_MIN_FRACTION` is a *detection window*, not a keyboard's height,
+ *     and its edge was being used as the boundary — so on an iPhone 17 Pro with
+ *     the software keyboard up, the window starts at y=629 while the `q`–`p`
+ *     row's frame top is **590**, and that whole row fell outside it. Ten
+ *     keyboard keys were reported as page content and counted into the screen's
+ *     identity, in the same map that said `keyboard up`. The boundary now
+ *     extends upward while the rows above keep being key-shaped, which page
+ *     content is not. Any screen fingerprinted with a keyboard up hashes
+ *     differently, so the stored graph and maps must go again.
  */
-export const TOKEN_RULES_VERSION = 4;
+export const TOKEN_RULES_VERSION = 6;
 
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;