simframe 0.10.0 → 0.12.0

package/src/view.js

@@ -12,6 +12,8 @@
 // app published and one OCR read off the pixels deserve different amounts of
 // trust.
 import * as api from './index.js';
+import * as regions from './regions.js';
+import * as wrote from './wrote.js';
 import * as graph from './graph.js';
 import { writeRefs } from './refs.js';
 import * as matching from './matching.js';
@@ -20,10 +22,10 @@ import * as matching from './matching.js';
 const REGION_ORDER = ['nav-bar', 'content', 'tab-bar', 'keyboard', 'status-bar'];
 
 /**
- * The status bar says the time and the battery level. It is on every screen,
- * it is never what anybody wants to tap, and it costs a row every time.
+ * Which regions the map will not offer now lives in `regions.js`, because it is
+ * not only a presentation rule — see `regions.offerable`. A target this hides
+ * must also be one nothing resolves onto behind the caller's back.
  */
-const HIDDEN_REGIONS = new Set(['status-bar']);
 
 /** A keyboard is 30-odd keys nobody refers to by name. One line says it. */
 const COLLAPSE_REGIONS = new Set(['keyboard']);
@@ -160,13 +162,94 @@ const trim = (text) => {
   return one.length > MAX_LABEL ? `${one.slice(0, MAX_LABEL - 1)}…` : one;
 };
 
-/** Rank and number what is on screen. */
+/**
+ * Why no row is dropped for being long — reverted 2026-09-10, same day.
+ *
+ * There was a rule here that dropped non-interactive rows whose label ran past
+ * 45 characters, on the evidence that four of sixteen rows on a Settings screen
+ * were the explanatory paragraph under each switch: 31% of that map's
+ * characters describing things nobody can tap. Across fourteen recorded screens
+ * it cut the map 15%.
+ *
+ * It was wrong, and the counter-example is decisive. A React Native list card
+ * exposes all of its children as one concatenated accessibility label —
+ * `Anaheim | Store # 1020, , 1234 Main St, … | Quick Casual Restaurant`, 105
+ * characters, type `GenericElement`, region `content`. Every property my rule
+ * tested is identical to the Settings caption's, and that card is *the only
+ * tappable thing on the screen*.
+ *
+ * Nothing became untappable — `locate`, `assert` and `waitFor` read
+ * `entry.targets`, so the rows are a view and the data survived. What was lost
+ * is **discovery**: the map stopped saying what was on screen, so an agent
+ * could only tap labels it already knew, and the fallback on a screen of
+ * unknown data is a ~1600-token screenshot. It saved characters on
+ * settings-shaped screens and spent an image on list-shaped ones, which is the
+ * exact cost the phase existed to remove. Blast radius: every data list in
+ * every RN app.
+ *
+ * The lesson is not "find a better discriminator". It is that this was a
+ * threshold shipped with no harness case that could catch its failure, in the
+ * same session as building the harness. So `expect.discoverable` now exists,
+ * and there is a fixture of the reported shape — a rule like this may return
+ * only when it can be gated.
+ *
+ * What survives is what the reporter suggested instead: truncate, do not drop.
+ * Position and tappability are the valuable parts of a row, not the full text.
+ * See `MAX_LABEL`.
+ */
+
+/**
+ * Whether a target in the keyboard band really is a key.
+ *
+ * Region bands are positional, and this was the fourth and fifth bug they
+ * produced. With the keyboard up, the bottom band is collapsed to one line —
+ * thirty keys nobody names — and a primary action pinned above the keyboard was
+ * collapsed with them: four reads running printed `keyboard: 6 keys` and **no
+ * forward control**, while the hint said "nothing ambiguous — chain the next
+ * steps without looking again". That it was an emission bug and not a
+ * perception one was proved by the next call, which hit the button instantly at
+ * a coordinate the map had never printed.
+ *
+ * Delegates to `regions.looksLikeKey`, which is the canonical test. These two
+ * having separate copies is what let a phantom keyboard survive in the
+ * fingerprint after it had already been fixed in the map — and there it was
+ * deleting screens' content from their own identity.
+ */
+export const isKey = regions.looksLikeKey;
+
+/**
+ * Whether a target can be acted on, by role *or* by evidence.
+ *
+ * The role alone was wrong twice on real forms. A React Native composite select
+ * surfaces as a generic element, and a text input shows only its placeholder as
+ * `StaticText` — so `--interactive` answered "1 element" on a form with two
+ * visible, bordered, *required* inputs and an agent concluded there was nothing
+ * to fill in.
+ *
+ * Evidence is used rather than a longer list of role names, because the roles
+ * are what the tree got wrong. Only a control carries a `value`, only a
+ * focusable thing is `focused`, and `enabled` is a state a caption never
+ * declares. A generic element that is none of those really is a container.
+ *
+ * The case this still cannot see: an empty, unfocused input whose placeholder is
+ * its only text. Nothing in the tree distinguishes it from a caption, which is
+ * why a filtered view now says it is filtered rather than implying it is the
+ * whole screen.
+ */
+export function actsInteractive(t) {
+  if (INTERACTIVE.test(t?.type || '')) return true;
+  if (t?.value != null && t.value !== '') return true;
+  if (t?.focused) return true;
+  if (t?.enabled === false) return true;
+  return false;
+}
+
 export function rowsFor(entry, { screen, filter, interactive, all = false, limit = DEFAULT_LIMIT } = {}) {
   let kept = (entry?.targets ?? []).map((t) => ({ ...t })).filter((t) => {
     if (!isNum(t.x) || !isNum(t.y)) return false;
     // Off-screen elements are real in the tree and untappable in fact.
-    if (screen?.height && (t.y < 0 || t.y > screen.height)) return false;
-    if (!all && HIDDEN_REGIONS.has(t.region)) return false;
+    if (regions.offViewport(t, screen)) return false;
+    if (!all && !regions.offerable(t.region)) return false;
     if (!all && isNoise(t)) return false;
     return true;
   });
@@ -181,7 +264,7 @@ export function rowsFor(entry, { screen, filter, interactive, all = false, limit
     kept = kept.filter((t) =>
       [t.label, ...(t.aliases ?? [])].filter(Boolean).join(' ').toLowerCase().includes(q));
   }
-  if (interactive) kept = kept.filter((t) => INTERACTIVE.test(t.type || ''));
+  if (interactive) kept = kept.filter(actsInteractive);
 
   const order = (t) => {
     const i = REGION_ORDER.indexOf(t.region ?? 'content');
@@ -189,11 +272,25 @@ export function rowsFor(entry, { screen, filter, interactive, all = false, limit
   };
   kept.sort((a, b) => order(a) - order(b) || a.y - b.y || a.x - b.x);
 
+  // A band is only the keyboard if there is a keyboard in it.
+  //
+  // Region bands are positional, so on a screen with no keyboard at all the
+  // bottom band was still called `keyboard` and review-summary rows were filed
+  // under it, followed by `keyboard: 1 keys (tap by label or type directly)` —
+  // advice that is actively wrong about page content. Reported as noise on
+  // every map of two screens. Relabelled from the contents rather than the
+  // position, which is the only evidence available here.
+  const keysPresent = kept.some((t) => COLLAPSE_REGIONS.has(t.region ?? '') && isKey(t));
+  const bandOf = (t) => {
+    const region = t.region ?? 'content';
+    return COLLAPSE_REGIONS.has(region) && !keysPresent ? 'content' : region;
+  };
+
   const rows = [];
   const collapsed = new Map();
   for (const t of kept) {
-    const region = t.region ?? 'content';
-    if (COLLAPSE_REGIONS.has(region)) {
+    const region = bandOf(t);
+    if (COLLAPSE_REGIONS.has(region) && isKey(t)) {
       collapsed.set(region, (collapsed.get(region) ?? 0) + 1);
       continue;
     }
@@ -232,6 +329,28 @@ export function recalledNote(identity, now = Date.now()) {
   return `elements recalled from ${ago} ago — pass refresh for what is there now`;
 }
 
+/**
+ * How old the frame behind this reading is, and whether that is a problem.
+ *
+ * Two thresholds, because "slightly behind" and "possibly a different screen"
+ * are different messages. Under `FRAME_FRESH_MS` nothing is said: a map that
+ * announced "42ms old" on every call would train a reader to skip the line that
+ * matters. Over `FRAME_STALE_MS` it shouts, because at that age the app may have
+ * moved on entirely and the whole element list is then a description of the past.
+ */
+export const FRAME_FRESH_MS = 1500;
+export const FRAME_STALE_MS = 4000;
+
+export function frameAgeNote(identity, now = Date.now()) {
+  const at = identity?.state?.capturedAt;
+  if (!Number.isFinite(at)) return null;
+  const age = Math.max(0, now - at);
+  if (age < FRAME_FRESH_MS) return null;
+  if (age < FRAME_STALE_MS) return `frame ${(age / 1000).toFixed(1)}s old`;
+  return `WARNING this frame is ${(age / 1000).toFixed(1)}s old — the screen may have moved on `
+    + 'since, so treat the elements below as a description of the past and pass refresh';
+}
+
 /**
  * What a control *contains*, from the sensor that actually knows.
  *
@@ -356,6 +475,41 @@ export async function screenMap(deviceQuery, {
   // screen is what the agent can actually use: it says how much of this screen
   // the graph can navigate from without being told.
   const exits = node ? node.edges.length : null;
+  // Not just how many — which. The graph has always known what worked here and
+  // only ever reported a count, so an agent on a screen simframe had driven ten
+  // times still read it to learn what was tappable.
+  const remembered = node ? graph.exitsOf(node) : [];
+  // Memory intersected with what is actually here, never memory alone.
+  //
+  // This is the correction to the feature above, and it was reported with the
+  // consequence spelled out. A wizard's read-only *review* screen had been given
+  // the same identity as its step 1, so it inherited step 1's entire vocabulary:
+  // the map offered `tap "APPLY"`, `tap "No Power"`, `tap "PLACE A SERVICE
+  // REQUEST"` — **not one of which exists on it** — while the hint said "nothing
+  // ambiguous, chain the next steps without looking again". The only control on
+  // that screen files a real work order. Confident advice pointed at a
+  // destructive button on a screen it had misidentified.
+  //
+  // The line was right and the identity was wrong, so the line now checks. A
+  // remembered action is only offered when its label is on the screen in front
+  // of us; the rest are counted and reported as a disagreement, because memory
+  // that does not match what is here is itself the most useful thing to say.
+  const { exitList, stale: staleExits } = presentOnly(remembered, rows);
+  // Values simframe wrote itself and can no longer see. Computed from the same
+  // rows the map is about to print, so it costs nothing, and it is the only
+  // thing that can notice a form being cleared underneath a caller — six `ok`
+  // calls in a row hid exactly that.
+  const cleared = wrote.missingLine(wrote.missing(device?.udid, rows));
+  // One layer covering another, detected where it shows: an ax element and an
+  // OCR word at one coordinate disagreeing about what is there. Reported by a
+  // peer who had to fall back to a screenshot to count five radio options
+  // through a sheet, which is the case the text map exists to remove.
+  const layered = (identity?.entry?.occluded ?? []).length;
+  const overlay = layered
+    ? `${layered} element(s) on this screen overlap and disagree about what is there`
+      + ' — a sheet or overlay is probably covering the screen behind it, so treat anything'
+      + ' you did not expect to see as belonging to the layer underneath'
+    : null;
 
   return {
     device,
@@ -363,14 +517,202 @@ export async function screenMap(deviceQuery, {
     rows,
     truncated,
     collapsed,
+    // A filtered view is not the screen, and the hint used to report its count
+    // as though it were: `--interactive` on a form said "1 element; nothing
+    // ambiguous — chain the next steps" while two required inputs sat unseen
+    // below it. The over-claim was the harmful half, not the filter.
+    filtered: Boolean(filter || interactive),
     screen,
     name,
     exits,
-    text: render({ device, identity, rows, truncated, collapsed, screen, name, exits }),
+    exitList,
+    staleExits,
+    cleared,
+    overlay,
+    text: render({ device, identity, rows, truncated, collapsed, screen, name, exits, exitList, staleExits, cleared, overlay }),
   };
 }
 
-export function render({ device, identity, rows, truncated, collapsed, screen, name, exits, verdictLine, ambiguities }) {
+/**
+ * One line saying whether the model needs to stop and think.
+ *
+ * The measured loop in a real session is observe → think → tap → observe →
+ * think, and the thinking dominates wall time. Phases 11–16 reduce how *often*
+ * a decision has to reach the model; this reduces how often the model *believes*
+ * it has to decide. Measured: 48 of 62 real calls were three steps or fewer, so
+ * a twelve-step flow arrived as four or five calls and every boundary was a
+ * think — not because anything was ambiguous, but because nothing said it was
+ * not.
+ *
+ * Everything here is already in hand when the result is assembled: whether the
+ * flow stopped, whether the screen settled, whether the graph recognises it,
+ * how many elements there are, and whether any two of them answer to the same
+ * label. No perception pass, no model call, no new state.
+ *
+ * The order is deliberate. It reports the *strongest reason to think* first,
+ * and only says "keep going" when it can rule all of them out — a hint that
+ * 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 } = {}) {
+  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.';
+  }
+  // A stopped flow and a completed flow carrying a soft verdict are different
+  // things, and conflating them printed `flow completed — 16/16 steps` directly
+  // above `next: the flow stopped here` on a run where nothing stopped.
+  //
+  // The conflation was load-bearing, not cosmetic. `no-visible-change` is an
+  // escalating verdict and it fires falsely — reported three rounds running —
+  // so **one** wrong verdict anywhere in a clean flow told the agent to abandon
+  // batching and re-read. That is the exact failure this hint exists to
+  // prevent, caused by the hint.
+  //
+  // A completed flow with an unconfirmed step is worth one targeted look, not a
+  // re-plan, so the hint says which and keeps the horizon open.
+  if (escalated) {
+    return 'next: every step ran, but at least one could not be confirmed — check that one thing landed (re-read the field, or assert it) rather than re-planning the flow.';
+  }
+  // A screen awaiting a network call is *settled* — nothing is moving — and
+  // incomplete. Reported: a settle returned satisfied while a list was still
+  // loading, the map showed an empty content region, and an empty region and a
+  // still-loading one produced identical output. A person sees a spinner.
+  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) {
+    return 'next: the screen is still moving. sim_state polls it for a fraction of a map; do not act on this reading yet.';
+  }
+  if (known === false) {
+    return 'next: new screen, nothing predicted here yet — read it before acting on a label you have not seen on it.';
+  }
+  if (ambiguous > 0) {
+    return ambiguous === 1
+      ? 'next: one label repeats on this screen — address that one by #ref, and the rest can go in one sim_do.'
+      : `next: ${ambiguous} labels repeat on this screen — address those by #ref, and the rest can go in one sim_do.`;
+  }
+  const known_ = hash ? `known (${hash.slice(0, 8)}${exits ? `, ${exits} known exit${exits === 1 ? '' : 's'}` : ''})` : 'known';
+  if (filtered) {
+    // The count belongs to the filter, not to the screen. An agent that reads
+    // it as the screen concludes a form has nothing to fill in.
+    return `next: settled; screen ${known_}; ${elements} element${elements === 1 ? '' : 's'} **matching your filter** — this is not the whole screen, and an empty text input can look like a caption. Read it unfiltered before concluding something is absent.`;
+  }
+  // Memory that contradicts the screen outranks "carry on", because the reason
+  // it contradicts is usually that this screen has been confused with another —
+  // and a confident "chain without looking again" on a misidentified screen is
+  // how remembered advice ends up pointing at a control that files a work order.
+  const offerable = (exitList ?? []).filter((e) => e.label);
+  if (!offerable.length && staleExits) {
+    return `next: this screen is recognised but ${staleExits} remembered control${staleExits === 1 ? ' is' : 's are'} not on it,`
+      + ' so the identity is probably wrong — two screens sharing one hash. Act only on the element list, and re-read before anything irreversible.';
+  }
+  // Naming the vocabulary is what makes "chain" actionable. A hint that says
+  // "chain the next steps" without saying what the steps could be is asking the
+  // agent to plan from a map it has to keep re-reading.
+  const vocab = offerable.slice(0, 6)
+    .map((e) => `${e.action} ${JSON.stringify(String(e.label).slice(0, 28))}`).join(', ');
+  return `next: settled; screen ${known_}; ${elements} element${elements === 1 ? '' : 's'}; nothing ambiguous — chain the next steps in one sim_do without looking again.`
+    + (vocab ? ` Known to work here: ${vocab}.` : '')
+    + (staleExits ? ` (${staleExits} other remembered control${staleExits === 1 ? '' : 's'} not on this screen — the graph may be conflating it with another.)` : '');
+}
+
+/**
+ * The hint for a rendered map, from the map itself.
+ *
+ * Lives here rather than in the MCP server because it was only reachable from
+ * there, and the MCP server is a long-lived process: a session that started
+ * before a change is running the old code, so the headline change of a phase
+ * could not be exercised at all. Reported, correctly, as the first finding
+ * against Phase 11.5. In `view.js` both front ends share one implementation and
+ * a unit test can reach it.
+ */
+export function hintFor(map, { flowOk = true, escalated = false } = {}) {
+  return nextHint({
+    ok: flowOk !== false,
+    escalated: Boolean(escalated),
+    filtered: map?.filtered === true,
+    settled: map?.identity?.settled !== false,
+    loading: map?.identity?.loading === true,
+    known: map?.exits != null,
+    hash: map?.identity?.hash ?? null,
+    exits: map?.exits ?? 0,
+    exitList: map?.exitList ?? [],
+    staleExits: map?.staleExits ?? 0,
+    elements: map?.rows?.length ?? 0,
+    ambiguous: ambiguousLabels(map?.rows),
+  });
+}
+
+/**
+ * Keep only the remembered actions whose control is actually on this screen.
+ *
+ * @returns {{exitList: Array, stale: number}} what can be offered, and how many
+ *   remembered actions found nothing here — which is evidence the screen has
+ *   been misidentified, and worth saying out loud.
+ */
+export function presentOnly(remembered, rows) {
+  const here = new Set();
+  for (const r of rows ?? []) {
+    for (const name of [r.label, ...(r.aliases ?? [])]) {
+      const k = alnum(name);
+      if (k) here.add(k);
+    }
+  }
+  const has = (label) => {
+    const k = alnum(label);
+    if (!k) return false;
+    if (here.has(k)) return true;
+    // A row may carry the label inside a longer one — a list card concatenates
+    // its children, and truncation adds an ellipsis.
+    for (const seen of here) if (seen.includes(k) || k.includes(seen)) return true;
+    return false;
+  };
+  const exitList = (remembered ?? []).filter((e) => has(e.label));
+  return { exitList, stale: (remembered ?? []).length - exitList.length };
+}
+
+/**
+ * What has worked from this screen before, printed rather than counted.
+ *
+ * The map said `(known, 3 known exits)` and stopped there, so the graph's own
+ * vocabulary never reached the caller. A flow whose labels were known in
+ * advance ran 16 steps in one call; the same agent on screens the graph also
+ * knew, but whose labels it had to rediscover, spent 25 calls on 31 steps.
+ *
+ * Deliberately terse and deliberately *not* a promise. These are actions that
+ * previously worked here, with how often — evidence for a plan, not a
+ * guarantee, and the destructive-label rules apply to them exactly as before.
+ */
+export function exitsLine(exitList, { limit = 6, stale = 0 } = {}) {
+  const list = (exitList ?? []).filter((e) => e.label).slice(0, limit);
+  if (!list.length) {
+    // Everything remembered here is missing. That is not "no memory" — it is
+    // memory that contradicts the screen, which usually means two screens have
+    // collapsed into one identity, and it is the most useful thing to say.
+    return stale
+      ? `memory disagrees with this screen: ${stale} remembered control${stale === 1 ? '' : 's'} not present`
+      + ' — this screen has probably been confused with another. Trust the element list, not the graph.'
+      : null;
+  }
+  const parts = list.map((e) => {
+    const label = String(e.label).length > 28 ? `${String(e.label).slice(0, 28)}…` : String(e.label);
+    return `${e.action} ${JSON.stringify(label)}${e.count > 1 ? ` (${e.count}x)` : ''}`;
+  });
+  return `worked here before: ${parts.join(', ')}`;
+}
+
+/** How many labels are worn by more than one element a caller could act on. */
+export function ambiguousLabels(rows) {
+  const seen = new Map();
+  for (const r of rows ?? []) {
+    const key = alnum(r.label);
+    if (!key) continue;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+  }
+  return [...seen.values()].filter((n) => n > 1).length;
+}
+
+export function render({ device, identity, rows, truncated, collapsed, screen, name, exits, exitList, staleExits, verdictLine, ambiguities, cleared, overlay }) {
   const head = [
     device?.name,
     screen?.width ? `${screen.width}x${screen.height}pt` : null,
@@ -380,11 +722,33 @@ export function render({ device, identity, rows, truncated, collapsed, screen, n
       : 'screen unidentified',
     identity?.keyboard ? 'keyboard up' : null,
     identity?.settled === false ? '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.
+    //
+    // `sim_look` and `sim_state` have printed this since they existed, and this
+    // map never has — so the one tool an agent is told to start with was the one
+    // that could not say how old its evidence was. Reported from the field: a
+    // complete 20-element map of a screen the app was not on, and *"a wrong
+    // answer is worse than an error here, because nothing downstream knows to
+    // doubt it"*. `ensureDaemon` will hand back a frame up to 30s old, so this
+    // was reachable without anything being broken.
+    //
+    // `recalledNote` below is a different claim — that the *element map* came
+    // from memory — and having one was what made the absence of the other easy
+    // to miss.
+    frameAgeNote(identity),
     recalledNote(identity),
   ].filter(Boolean).join(' · ');
 
   const lines = [head];
   if (verdictLine) lines.push(verdictLine);
+  // Above the element list, not below it: it contradicts something the caller
+  // already believes, which is the one kind of news that must not be scrolled to.
+  if (cleared) lines.push(cleared);
+  if (overlay) lines.push(overlay);
+  const worked = exitsLine(exitList, { stale: staleExits });
+  if (worked) lines.push(worked);
 
   let region = null;
   for (const r of rows) {

package/src/vocabulary.js

@@ -0,0 +1,134 @@
+/**
+ * The words simframe may not act on by itself.
+ *
+ * CLAUDE.md has required this since the human-parity series was written — *"a
+ * reflex never taps anything whose label matches the destructive vocabulary
+ * (Delete, Remove, Pay, Send, Sign out, Reset…). Add the list to the same data
+ * file."* — and several of my own comments already talk about "the destructive
+ * vocabulary" as though it existed. It did not. This is it.
+ *
+ * **What it gates, precisely.** This restricts what simframe does *on its own
+ * initiative*: a retry, an alternative selector, an exploration step, a reflex,
+ * a speculative tap. It never restricts what the caller explicitly asked for.
+ * `{"tap": "DELETE ACCOUNT"}` is a request and is honoured; substituting
+ * "DELETE ACCOUNT" for a "Done" that did not resolve is not, and that is the
+ * whole distinction. Getting it backwards would make the tool refuse the thing
+ * a tester most needs to test.
+ *
+ * Data, not code, and locale-keyed, so another language is a file rather than a
+ * release.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DATA = path.join(HERE, '..', 'data', 'vocabulary');
+
+const cache = new Map();
+
+/** The vocabulary for a locale, falling back to English. */
+export function load(locale = process.env.SIMFRAME_LOCALE || 'en') {
+  const key = String(locale).toLowerCase().split(/[-_]/)[0];
+  if (cache.has(key)) return cache.get(key);
+  let data = null;
+  for (const candidate of [key, 'en']) {
+    try {
+      data = JSON.parse(fs.readFileSync(path.join(DATA, `${candidate}.json`), 'utf8'));
+      break;
+    } catch { /* try the fallback */ }
+  }
+  // A missing file must not silently disable the barrier. An empty vocabulary
+  // would make every label safe, which is the wrong direction to fail in, so
+  // this throws rather than returning nothing.
+  if (!data) throw new Error(`no vocabulary for "${locale}" and no en fallback in ${DATA}`);
+  cache.set(key, data);
+  return data;
+}
+
+const alnum = (s) => String(s ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+
+/**
+ * Does this phrase occur in the label as whole words?
+ *
+ * Word boundaries, not substrings, and the reason is a real screen: an app's
+ * "Work Orders" tab contains the letters of "order", and a substring match would
+ * make its main navigation untouchable by anything local. Matching whole words
+ * means "order" does not match "orders", which is the behaviour wanted here —
+ * an exact tappable word is the signal, and a longer word is a different word.
+ */
+function saysPhrase(label, phrase) {
+  const l = ` ${alnum(label)} `;
+  const p = alnum(phrase);
+  if (!p) return false;
+  return l.includes(` ${p} `);
+}
+
+/**
+ * May simframe act on this label on its own initiative?
+ *
+ * `purpose` matters, and conflating two purposes cost a real run. The default,
+ * `substitute`, answers *"may a retry aim at this instead?"* and permits
+ * "Cancel", deliberately, so a local tier can decline a dialog rather than
+ * stranding on every confirmation it meets.
+ *
+ * `explore` answers a different question — *"may I open this as a door and see
+ * what is behind it?"* — and there "Cancel" is the abandon-this-task control.
+ * `seek` asked the first question and got the first answer: it opened CANCEL
+ * first, then AI TROUBLESHOOTING, then pressed "YES, THIS FIXED MY PROBLEM",
+ * ending five screens deep in a live support chat with a half-built service
+ * request destroyed. One label further along was SUBMIT SERVICE REQUEST.
+ *
+ * So exploration has its own list and it errs toward refusing. A door missed
+ * costs one step of a bounded budget; a door taken wrongly costs the run, and
+ * can cost the thing being tested.
+ *
+ * @returns {{allowed: boolean, reason?: string, matched?: string}}
+ */
+export function mayActLocally(label, { locale, purpose = 'substitute' } = {}) {
+  const text = String(label ?? '').trim();
+  if (!text) return { allowed: purpose !== 'explore' };
+  const vocab = load(locale);
+
+  if (purpose === 'explore') {
+    // Checked before the "listed as safe" exemption below, which exists for
+    // declining dialogs and must never make something a door.
+    for (const word of vocab.exploration?.neverOpen ?? []) {
+      if (saysPhrase(text, word)) {
+        return { allowed: false, reason: 'not a door — it commits, abandons or answers', matched: word };
+      }
+    }
+    for (const pattern of vocab.exploration?.neverOpenPatterns ?? []) {
+      if (new RegExp(pattern, 'i').test(alnum(text)) || new RegExp(pattern, 'i').test(text.toLowerCase())) {
+        return { allowed: false, reason: 'not a door — it reads as an instruction or an answer', matched: pattern };
+      }
+    }
+  }
+
+  // Exceptions first, and matched against the **whole** label rather than as a
+  // phrase inside it. "Cancel" is how you *decline* a dialog and a barrier that
+  // refused it would strand a local tier on every confirmation it met — but
+  // "Cancel order" is a different act, and a phrase match would have waved it
+  // through on the strength of its first word.
+  const whole = alnum(text);
+  for (const ok of vocab.destructive?.notWords?.words ?? []) {
+    if (whole === alnum(ok)) return { allowed: true, reason: 'listed as safe', matched: ok };
+  }
+  for (const word of vocab.destructive?.words ?? []) {
+    if (saysPhrase(text, word)) {
+      return { allowed: false, reason: 'destructive vocabulary', matched: word };
+    }
+  }
+  for (const word of vocab.leavesTheApp?.words ?? []) {
+    if (saysPhrase(text, word)) {
+      return { allowed: false, reason: 'leaves the app', matched: word };
+    }
+  }
+  return { allowed: true };
+}
+
+/** Convenience for a filter: keep only what a local tier may act on. */
+export const actableLocally = (label, options) => mayActLocally(label, options).allowed;
+
+/** May exploration open this as a door? Stricter than substitution, on purpose. */
+export const openableAsDoor = (label, options) => mayActLocally(label, { ...options, purpose: 'explore' }).allowed;