simframe 0.11.0 → 0.12.1

package/src/view.js

@@ -22,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']);
@@ -249,7 +249,7 @@ export function rowsFor(entry, { screen, filter, interactive, all = false, limit
     if (!isNum(t.x) || !isNum(t.y)) return false;
     // Off-screen elements are real in the tree and untappable in fact.
     if (regions.offViewport(t, screen)) return false;
-    if (!all && HIDDEN_REGIONS.has(t.region)) return false;
+    if (!all && !regions.offerable(t.region)) return false;
     if (!all && isNoise(t)) return false;
     return true;
   });
@@ -329,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.
  *
@@ -702,6 +724,20 @@ export function render({ device, identity, rows, truncated, collapsed, screen, n
     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(' · ');