@simon-says-build/demo-player 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simon-says-build/demo-player",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "SimonSays mobile demo player: walks a preview's viewer through a job's change, inside the app. Renders nothing unless the bundle carries a demo.",
   "repository": {
     "type": "git",

package/src/DemoHost.js

@@ -14,7 +14,8 @@
 // No JSX, so it needs nothing from the app's Babel setup beyond React Native's.
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Linking, Pressable, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions } from 'react-native';
-import { cardBox, currentDemo, demoConfig, findTarget, handlerFor, onDemo, phoneSteps, playDemo, releaseOf, reviewChangesOf, scalePoint, stepTitle } from './core.js';
+import { pageName } from './page-name.js';
+import { OVERLAY_ID, cardBox, currentDemo, demoConfig, findTarget, handlerFor, onDemo, phoneSteps, playDemo, releaseOf, reviewChangesOf, scalePoint, rescueNote, screenCandidates, stepTitle, targetOfKey } from './core.js';
 import { demoApi, tourOf } from './api.js';
 import { signInFirst, openInApp } from './signin.js';
 import { runEvent, fillStep } from './events.js';
@@ -78,6 +79,9 @@ function Player({ config, router, insets, onClose, children }) {
   const [signIn, setSignIn] = useState(null);     // a `signin` step: null while it runs, else { ok, error }
   const [event, setEvent] = useState(null);       // an `event` step: null while it runs, else { ok, error }
   const [vars, setVars] = useState({});           // per person: what their events set up ({walkId} in later steps)
+  const [flash, setFlash] = useState(null);       // "Now navigating to the walk page", said before a goto opens it
+  const [rescued, setRescued] = useState(null);   // { for: index, status: asking|moved|gone, target?, why? }
+  const asked = useRef(new Set());                // steps already rescued once (by index)
 
   useEffect(() => {
     let live = true;
@@ -90,11 +94,34 @@ function Player({ config, router, insets, onClose, children }) {
   const step = useMemo(() => { const raw = steps?.[index] ?? null; return raw ? fillStep(raw, vars[raw.actorIndex]) : null; }, [steps, index, vars]);
 
 
+  // THE RESCUE (0.9.0, Michael 2026-11-01: "when the current UI differs
+  // substantially from the recorded one, maybe realtime AI should step in,
+  // instead of showing an error"): a step whose element never appears asks SSB
+  // once, with what IS on screen. It answers with one of those (renamed or
+  // moved: the step carries on there) or says what is different now, which the
+  // card says in SSB's words. The extension's rescue, on a phone.
+  const askRescue = useCallback(async (at, idx) => {
+    if (asked.current.has(idx) || at.stepIndex == null) return;
+    asked.current.add(idx);
+    setRescued({ for: idx, status: 'asking' });
+    try {
+      let r = await api.repair({ actorIndex: at.actorIndex, stepIndex: at.stepIndex, candidates: screenCandidates(fiberOf(rootRef.current)) });
+      for (let i = 0; r.status === 'pending' || r.status === 'running'; i++) {
+        if (i >= RESCUE_POLLS) throw new Error('no answer');
+        await new Promise((ok) => setTimeout(ok, 2500));
+        r = await api.repairStatus(r.id);
+      }
+      const target = r.pick != null ? targetOfKey(r.css) : null;
+      setRescued(target ? { for: idx, status: 'moved', target, why: r.why || '' } : { for: idx, status: 'gone', why: r.why || '' });
+    } catch { setRescued({ for: idx, status: 'gone', why: '' }); }
+  }, [api]);
+  const rescue = rescued?.for === index ? rescued : null;
+
   // Find and follow the step's element.
   useEffect(() => {
     setRect(null); setFound(null);
     if (!step || done) return undefined;
-    const target = step.target;
+    const target = rescue?.status === 'moved' ? rescue.target : step.target;
     if (!target) return undefined;
     if (target.point && !target.testId && !target.label && !target.text) {
       const p = scalePoint(target.point, screen);
@@ -112,12 +139,12 @@ function Player({ config, router, insets, onClose, children }) {
       if (!r && Date.now() - started > FIND_FOR_MS && target.point) {
         const p = scalePoint(target.point, screen);
         setRect({ left: p.x - 22, top: p.y - 22, width: 44, height: 44, right: p.x + 22, bottom: p.y + 22 });
-      }
+      } else if (!r && Date.now() - started > FIND_FOR_MS && !rescue) askRescue(step, index);
     };
     tick();
     const t = setInterval(tick, TRACK_EVERY_MS);
     return () => { live = false; clearInterval(t); };
-  }, [step, done, screen.width, screen.height]);
+  }, [step, done, screen.width, screen.height, rescue?.status, index]);
 
   const finish = useCallback(() => {
     setReviewing(false);
@@ -125,15 +152,27 @@ function Player({ config, router, insets, onClose, children }) {
     api.progress({ status: 'done' }).catch(() => {});
   }, [api]);
 
+  const advance = useCallback(() => {
+    if (index + 1 >= steps.length) { if (changes.length) setReviewing(true); else finish(); }
+    else setIndex(index + 1);
+  }, [steps, index, finish, changes]);
+  // SAID BEFORE IT GOES (2026-11-01, Michael): a goto flashes "Now navigating
+  // to the walk page" for a moment, then opens it (schemas/page-name.mjs).
   const next = useCallback(() => {
-    if (!steps) return;
+    if (!steps || flash) return;
     if (step?.kind === 'goto' && step.path) {
-      if (step.path.startsWith('/') && router?.push) router.push(step.path);
-      else Linking.openURL(step.path).catch(() => {});
+      const path = step.path;
+      setFlash(`Now navigating to ${pageName(path)}`);
+      setTimeout(() => {
+        if (path.startsWith('/') && router?.push) router.push(path);
+        else Linking.openURL(path).catch(() => {});
+        setFlash(null);
+        advance();
+      }, FLASH_MS);
+      return;
     }
-    if (index + 1 >= steps.length) { if (changes.length) setReviewing(true); else finish(); }
-    else setIndex(index + 1);
-  }, [steps, step, index, router, finish, changes]);
+    advance();
+  }, [steps, step, router, advance, flash]);
 
   const doIt = useCallback(() => {
     if (!step || !found) return;
@@ -183,6 +222,8 @@ function Player({ config, router, insets, onClose, children }) {
     if (error) return h(Card, { at: null, screen, insets, card, setCard, title: 'Demo', body: `The demo didn't load: ${error}` });
     if (!steps) return null;
     if (reviewing && !tucked) return h(Review, { api, changes, release, screen, insets, onBack: steps.length ? () => setReviewing(false) : null, onDone: finish, onHide: () => setTucked(true) });
+    if (flash) return h(View, { pointerEvents: 'none', style: [s.flash, { top: insets.top + screen.height * 0.4 }], testID: 'ssb-demo-flash' },
+      h(Text, { style: s.flashText, accessibilityLiveRegion: 'polite' }, flash));
     if (tucked || done) {
       // A demo started at run time closes when it is done (▶ Demo again replays it);
       // one baked into a preview stays, to be replayed from its pill.
@@ -212,7 +253,7 @@ function Player({ config, router, insets, onClose, children }) {
       rect ? h(View, { pointerEvents: 'none', style: [s.ring, { left: rect.left - 6, top: rect.top - 6, width: rect.width + 12, height: rect.height + 12 }] }) : null,
       h(Card, {
         at: rect, place: step.place, screen, insets, card, setCard,
-        title: stepTitle(step, index, steps.length), body: step.caption,
+        title: stepTitle(step, index, steps.length), body: rescueNote(step.caption, rescue),
         actions: [
           { label: 'Hide', onPress: () => setTucked(true) },
           index > 0 && steps[index - 1].kind !== 'signin' ? { label: 'Back', onPress: () => setIndex(index - 1) } : null,
@@ -224,7 +265,7 @@ function Player({ config, router, insets, onClose, children }) {
 
   return h(View, { ref: rootRef, style: s.root, collapsable: false },
     children,
-    h(View, { pointerEvents: 'box-none', style: StyleSheet.absoluteFill }, overlay));
+    h(View, { pointerEvents: 'box-none', style: StyleSheet.absoluteFill, testID: OVERLAY_ID }, overlay));
 }
 
 // The review card: every change of the demo, each approved here or discussed
@@ -307,6 +348,9 @@ function Card({ at, place, screen, insets, card, setCard, title, body, actions =
   }, h(Text, { style: [s.buttonText, a.primary && s.primaryText] }, a.label)))) : null);
 }
 
+const RESCUE_POLLS = 40;   // ~100 s for the daemon's fallback answer, as the extension waits
+const FLASH_MS = 1100;   // long enough to read "Now navigating to the walk page"
+
 const s = StyleSheet.create({
   root: { flex: 1 },
   ring: { position: 'absolute', borderRadius: 12, borderWidth: 3, borderColor: '#FFFFFF', shadowColor: '#000', shadowOpacity: 0.6, shadowRadius: 8, shadowOffset: { width: 0, height: 0 } },
@@ -327,6 +371,8 @@ const s = StyleSheet.create({
   changeState: { color: '#AEAEB2', fontSize: 13, marginTop: 4 },
   error: { color: '#FF6961', fontSize: 13, marginTop: 4 },
   input: { marginTop: 10, minHeight: 64, padding: 10, borderRadius: 10, backgroundColor: '#2C2C2E', color: '#FFFFFF', fontSize: 15 },
+  flash: { position: 'absolute', left: 32, right: 32, alignItems: 'center', paddingVertical: 14, paddingHorizontal: 18, borderRadius: 14, backgroundColor: 'rgba(28,28,30,0.92)' },
+  flashText: { color: '#FFFFFF', fontSize: 16, fontWeight: '600', textAlign: 'center' },
   pill: { position: 'absolute', right: 16, paddingVertical: 8, paddingHorizontal: 14, borderRadius: 18, backgroundColor: '#1C1C1E' },
   pillText: { color: '#FFFFFF', fontSize: 13, fontWeight: '600' },
 });

package/src/api.js

@@ -28,6 +28,11 @@ export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
     // A planned review (0.8.0): run a helper on the private copy, then read how it went.
     event: (actorIndex, helper, args) => call('/event', { method: 'POST', body: JSON.stringify({ actorIndex, helper, args }) }),
     eventStatus: (eventId) => call(`/event/${encodeURIComponent(eventId)}`),
+    // The rescue (0.9.0): a step whose element is not on screen asks where it
+    // went, with what IS on screen; the answer is an index into those, or why
+    // it is gone. The same route the extension calls.
+    repair: (body) => call('/repair', { method: 'POST', body: JSON.stringify(body) }),
+    repairStatus: (repairId) => call(`/repair/${encodeURIComponent(repairId)}`),
     discuss: (jobId, text) => call('/chat', { method: 'POST', body: JSON.stringify({ text, context: { about: jobId } }) }),
   };
 }
@@ -49,7 +54,9 @@ export function tourOf(demo, { here = false } = {}) {
     if (auto && hasState(a)) out.push({ kind: 'event', helper: '@state', caption: `Setting up ${a.label}'s part…`, actorIndex, intro: true });
     if (auto) out.push({ kind: 'signin', caption: `Signing you in as ${a.label}…`, fallback: ask, actorIndex, intro: true });
     else if (!here) out.push({ kind: 'say', caption: ask, actorIndex, intro: true });
-    for (const s of auto ? skipAuthSteps(steps) : steps) out.push({ ...s, actorIndex });
+    // stepIndex: the step's place in the person's recorded tour, which the
+    // rescue names (/repair reads actor.tour.steps[stepIndex]).
+    for (const s of auto ? skipAuthSteps(steps) : steps) out.push({ ...s, actorIndex, stepIndex: steps.indexOf(s) });
   }
   return out;
 }

package/src/core.js

@@ -10,7 +10,7 @@ import { bubbleBox } from './step-place.js';
 // What this player is, said when the app registers for "Ready to see"
 // (packages/ssb-overlay sends it; functions/in-app-notify.mjs clientOf). Kept
 // equal to package.json by test/core.test.mjs.
-export const PLAYER_VERSION = '0.8.1';
+export const PLAYER_VERSION = '0.9.0';
 
 export const HOST = 5;
 export const TEXT = 6;
@@ -30,12 +30,13 @@ const hiddenHost = (f) => {
   return flat?.display === 'none';
 };
 
-function* walk(root) {
-  // Iterative depth-first, skipping a display:none host and everything in it.
+function* walk(root, skip = null) {
+  // Iterative depth-first, skipping a display:none host and everything in it
+  // (and any host `skip` names, with everything in it).
   const stack = root ? [root] : [];
   while (stack.length) {
     const f = stack.pop();
-    if (f.tag === HOST && hiddenHost(f)) continue;
+    if (f.tag === HOST && (hiddenHost(f) || (skip && skip(f)))) continue;
     yield f;
     const kids = [];
     for (let c = f.child; c; c = c.sibling) kids.push(c);
@@ -86,6 +87,49 @@ export function findTarget(root, target) {
   return null;
 }
 
+// WHAT IS ON SCREEN, for the rescue (0.9.0, as the extension's candidates()):
+// every element a person could name, as the step's own target vocabulary. The
+// key is what comes back: the server's rescue answers with an INDEX into
+// these, never a target it wrote (functions/demo-rescue.mjs).
+const keyOf = (t) => (t.testId ? `testId:${t.testId}` : t.label ? `label:${t.label}` : `text:${t.text}`);
+/** The keyed target a rescue's answer names back ("label:Share" → { label: 'Share' }), or null. */
+export function targetOfKey(key) {
+  const m = /^(testId|label|text):(.+)$/s.exec(String(key || ''));
+  return m ? { [m[1]]: m[2] } : null;
+}
+// The card's words while a step is rescued: SSB's, never an error. Pure.
+export function rescueNote(caption, rescue) {
+  if (!rescue) return caption;
+  if (rescue.status === 'asking') return `${caption}\n\nSSB is looking for where this is now…`;
+  if (rescue.status === 'moved') return `${caption}\n\n${rescue.why ? `${rescue.why} ` : ''}SSB found it here.`;
+  return `${caption}\n\n${rescue.why || 'This screen has changed since the review was recorded.'} Tap Next to carry on, or look around yourself.`;
+}
+// The player's own layer: never a candidate (its card's words are not the app's).
+export const OVERLAY_ID = 'ssb-demo-overlay';
+/** Everything on screen a step could point at: [{ css: key, tag, name?, text? }], at most `max`. */
+export function screenCandidates(root, max = 60) {
+  const out = [];
+  const seen = new Set();
+  const add = (t, tag, name, text) => {
+    const css = keyOf(t);
+    if (seen.has(css) || out.length >= max) return;
+    seen.add(css);
+    out.push({ css, tag, ...(name ? { name: name.slice(0, 200) } : {}), ...(text ? { text: text.slice(0, 200) } : {}) });
+  };
+  for (const f of walk(root, (h) => h.memoizedProps?.testID === OVERLAY_ID)) {
+    if (out.length >= max) break;
+    const p = f.memoizedProps || {};
+    if (f.tag === HOST && (p.testID || p.accessibilityLabel)) {
+      const label = String(p.accessibilityLabel || p['aria-label'] || '').trim();
+      add(p.testID ? { testId: String(p.testID) } : { label }, p.accessibilityRole || (typeof p.onChangeText === 'function' ? 'input' : 'view'), label, '');
+    } else if (f.tag === TEXT) {
+      const text = textOf(f).trim();
+      if (text && text.length <= 80) add({ text }, 'text', '', text);
+    }
+  }
+  return out;
+}
+
 /** The nearest `name` handler at or above `f` (onPress, onChangeText), or null. */
 export function handlerFor(f, name) {
   for (let p = f; p; p = p.return) {

package/src/page-name.js

@@ -0,0 +1,23 @@
+// THE PAGE A STEP OPENS, in words (2026-11-01, Michael: "before any navigation,
+// can we show a brief flash showing 'Now navigating to [the X page]'"). Both
+// players say it before they navigate: the phone's (packages/demo-player/src/
+// page-name.js) and the extension's (extension/overlay.js) carry copies of
+// pageName, held equal by bin/page-name.test.mjs. Pure.
+//
+//   /walk/{walkId}          → the walk page     (an id or {placeholder} is not a name)
+//   /(app)/settings/profile → the profile page  (an Expo Router group is not a name)
+//   /MainStack/Tabs/Dashboard → the dashboard page (a React Navigation chain)
+//   walk2gether://walk/abc  → the walk page     (a deep link)
+//   /                       → the home page
+export function pageName(path) {
+  // A web address drops its host; a deep link's "host" is its first screen.
+  const rest = String(path || '').replace(/^https?:\/\/[^/]*/i, '').replace(/^[a-z][a-z0-9+.-]*:\/\//i, '/').split(/[?#]/)[0];
+  const isId = (s) => /^\{.*\}$/.test(s) || /^\[.*\]$/.test(s) || /^:/.test(s) || /^\(.*\)$/.test(s) || s === 'index'
+    || /^[0-9]+$/.test(s) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(s) || (s.length >= 16 && /[0-9]/.test(s) && /^[A-Za-z0-9_-]+$/.test(s));
+  const parts = rest.split('/').filter(Boolean).map((s) => { try { return decodeURIComponent(s); } catch { return s; } }).filter((s) => !isId(s));
+  const last = parts[parts.length - 1];
+  if (!last) return 'the home page';
+  const words = last.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_.]+/g, ' ').trim().toLowerCase();
+  return `the ${words || 'home'} page`;
+}
+// END pageName