@simon-says-build/demo-player 0.11.0 → 0.13.0

package/index.d.ts

@@ -45,3 +45,8 @@ export function navigationRoute(nav: unknown): string;
 export function navigationRouter(nav: unknown): { push: (path: string) => boolean };
 export function navigateArgs(path: string): [string] | [string, object] | null;
 export function pathOfState(state: unknown): string;
+
+/** While a review is collapsed (0.13.0): the function that resumes it, else null. */
+export function tuckedDemo(): (() => void) | null;
+/** The in-app SSB overlay says it is on screen, so a collapsed review leaves only its button. */
+export function announceOverlay(): void;

package/index.js

@@ -1,3 +1,3 @@
 export { DemoHost } from './src/DemoHost.js';
-export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint, playDemo, currentDemo, onDemo, reviewChangesOf, releaseOf, releaseReviewsOf, PLAYER_VERSION } from './src/core.js';
+export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint, playDemo, currentDemo, onDemo, reviewChangesOf, releaseOf, releaseReviewsOf, PLAYER_VERSION, tuckedDemo, announceOverlay } from './src/core.js';
 export { navigationRoute, navigationRouter, navigateArgs, pathOfState } from './src/navigation.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simon-says-build/demo-player",
-  "version": "0.11.0",
+  "version": "0.13.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

@@ -13,12 +13,13 @@
 //
 // 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 { Linking, NativeModules, Pressable, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions } from 'react-native';
 import { pageName } from './page-name.js';
-import { OVERLAY_ID, cardBox, currentDemo, demoConfig, findTarget, handlerFor, introBody, introOf, onDemo, phoneSteps, playDemo, releaseOf, reviewChangesOf, scalePoint, rescueNote, screenCandidates, stepTitle, targetOfKey } from './core.js';
+import { OVERLAY_ID, cardBox, pinnedBox, setTuckedDemo, overlayAnnounced, currentDemo, demoConfig, findTarget, handlerFor, introBody, introOf, 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';
+import { nativeRuntime, buildGap, needLinks, openNeed, staleBody } from './build-gate.js';
 
 const h = React.createElement;
 const FIND_FOR_MS = 8000;      // a step's element may appear after a navigation settles
@@ -83,11 +84,25 @@ function Player({ config, router, insets, onClose, children }) {
   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)
+  const [stale, setStale] = useState(null);       // { gap, links, appName }: this dev build is not the review's (build-gate.js)
 
   useEffect(() => {
     let live = true;
     api.load()
-      .then((d) => { if (live) { setSteps(phoneSteps(tourOf(d, { here: !!config.here })).concat()); setChanges(reviewChangesOf(d)); setRelease(releaseOf(d)); setIntro(introOf(d)); } })
+      .then((d) => {
+        if (!live) return;
+        // THE BUILD FIRST (0.12.0): a review made for another native build of
+        // this dev app never starts here — the person is sent to install the
+        // right one (build-gate.js). Nothing else runs: no sign-in, no steps.
+        const gap = config.here ? null : buildGap(d, nativeRuntime(globalThis.expo?.modules, NativeModules));
+        if (gap) {
+          const links = needLinks({ demo: d, gap, demoId: config.id, token: config.token });
+          setStale({ gap, links, appName: d.projectName || d.appName || 'the app' });
+          openNeed(links, (u) => Linking.openURL(u));
+          return;
+        }
+        setSteps(phoneSteps(tourOf(d, { here: !!config.here })).concat()); setChanges(reviewChangesOf(d)); setRelease(releaseOf(d)); setIntro(introOf(d));
+      })
       .catch((e) => { if (live) setError(e.message); });
     return () => { live = false; };
   }, [api]);
@@ -147,6 +162,24 @@ function Player({ config, router, insets, onClose, children }) {
     return () => { live = false; clearInterval(t); };
   }, [step, done, screen.width, screen.height, rescue?.status, index]);
 
+  // TRY IT (0.13.0): the viewer taps the ringed element; once it was on
+  // screen and is gone (the app moved on), that was the tap — said, and the
+  // tour carries on. "Show me" presses it for them; Skip moves on.
+  const triedSeen = useRef(false);
+  const [tried, setTried] = useState(false);
+  useEffect(() => { triedSeen.current = false; setTried(false); }, [index]);
+  useEffect(() => {
+    if (step?.kind !== 'try' || tried) return;
+    if (found) { triedSeen.current = true; return; }
+    if (triedSeen.current) setTried(true);
+  }, [found, step?.kind, tried]);
+
+  // Collapsed, the SSB button resumes it (core.js tuckedDemo).
+  useEffect(() => {
+    setTuckedDemo(tucked && !done ? () => setTucked(false) : null);
+    return () => setTuckedDemo(null);
+  }, [tucked, done]);
+
   const finish = useCallback(() => {
     setReviewing(false);
     setDone(true);
@@ -175,8 +208,16 @@ function Player({ config, router, insets, onClose, children }) {
     advance();
   }, [steps, step, router, advance, flash]);
 
+  useEffect(() => {
+    if (!tried) return undefined;
+    setFlash('✓ That\'s it');
+    const t = setTimeout(() => { setFlash(null); advance(); }, FLASH_MS);
+    return () => clearTimeout(t);
+  }, [tried]);
+
   const doIt = useCallback(() => {
     if (!step || !found) return;
+    if (step.kind === 'try') { handlerFor(found, 'onPress')?.({ nativeEvent: {}, preventDefault() {}, stopPropagation() {} }); return; }
     if (step.kind === 'click') handlerFor(found, 'onPress')?.({ nativeEvent: {}, preventDefault() {}, stopPropagation() {} });
     if (step.kind === 'fill' && step.value != null) handlerFor(found, 'onChangeText')?.(step.value);
     next();
@@ -184,7 +225,8 @@ function Player({ config, router, insets, onClose, children }) {
 
   // AND NOW… (an `event` step, 0.8.0): SSB runs the helper on the copy; its
   // outputs fill `{name}` in this person's later steps. A failure stays on the
-  // card, said, with Next; never a silent skip.
+  // card, said, with Try again (0.12.0: never Next — what follows depends on it).
+  const [eventTry, setEventTry] = useState(0);
   useEffect(() => {
     setEvent(null);
     if (step?.kind !== 'event' || done) return undefined;
@@ -197,11 +239,13 @@ function Player({ config, router, insets, onClose, children }) {
       else setIndex(index + 1);
     });
     return () => { live = false; };
-  }, [step?.kind, step?.helper, index, done]);
+  }, [step?.kind, step?.helper, index, done, eventTry]);
 
   // SIGN THIS PERSON IN FIRST (a `signin` step, tourOf): open the link, let
   // the app sign in and route, then start their part on that screen. A link
-  // that can't be had or opened leaves the card saying who to be (stage 1).
+  // that can't be had or opened, or a sign-in whose first screen never comes
+  // up, stops the tour with Try again (0.12.0).
+  const [signInTry, setSignInTry] = useState(0);  // "Try again" re-runs the sign-in
   useEffect(() => {
     setSignIn(null);
     if (step?.kind !== 'signin' || done) return undefined;
@@ -217,20 +261,27 @@ function Player({ config, router, insets, onClose, children }) {
       else setIndex(index + 1);
     });
     return () => { live = false; };
-  }, [step, done]);
+  }, [step, done, signInTry]);
 
   const overlay = (() => {
     if (error) return h(Card, { at: null, screen, insets, card, setCard, title: 'Demo', body: `The demo didn't load: ${error}` });
+    if (stale) {
+      return h(Card, {
+        at: null, screen, insets, card, setCard, title: 'Guided Review', body: staleBody(stale.gap, stale.appName),
+        actions: [{ label: 'Open SimonSays', onPress: () => openNeed(stale.links, (u) => Linking.openURL(u)), primary: true }],
+      });
+    }
     if (!steps) return null;
     if (intro && !tucked && !done) {
       return h(Card, {
-        at: null, screen, insets, card, setCard, title: 'Guided Review', body: introBody(intro),
+        at: null, screen, insets, card, setCard, onCollapse: () => setTucked(true), title: 'Guided Review', body: introBody(intro),
         actions: [{ label: 'Hide', onPress: () => setTucked(true) }, { label: 'Start the review', onPress: () => setIntro(null), primary: true }],
       });
     }
     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 && overlayAnnounced()) return null;   // the SSB button resumes it (0.13.0)
     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.
@@ -241,25 +292,41 @@ function Player({ config, router, insets, onClose, children }) {
     }
     if (!step && changes.length) return h(Review, { api, changes, release, screen, insets, onBack: null, onDone: finish, onHide: () => setTucked(true) });
     if (!step) return h(Card, { at: null, screen, insets, card, setCard, title: 'Demo', body: 'This demo has no steps a phone can play.' });
+    // A FAILED SETUP OR SIGN-IN STOPS THE TOUR (0.12.0, Michael 2026-11-05:
+    // "the tour is theoretically continuable… we need a way to make the tour
+    // aware that an important step failed"). What follows depends on it, so
+    // there is no Next: Try again, or Hide.
     if (step.kind === 'event') {
       return h(Card, {
-        at: null, screen, insets, card, setCard, title: `${index + 1} of ${steps.length}`,
-        body: event ? `The demo couldn't set this up: ${event.error}` : step.caption,
-        actions: event ? [{ label: 'Hide', onPress: () => setTucked(true) }, { label: 'Next', onPress: next, primary: true }] : [],
+        at: null, screen, insets, card, setCard, onCollapse: () => setTucked(true), title: `${index + 1} of ${steps.length}`,
+        body: event ? `The review couldn't set this up, and the rest of it depends on it: ${event.error}` : step.caption,
+        actions: event ? [{ label: 'Hide', onPress: () => setTucked(true) }, { label: 'Try again', onPress: () => setEventTry((n) => n + 1), primary: true }] : [],
       });
     }
     if (step.kind === 'signin') {
       return h(Card, {
-        at: null, screen, insets, card, setCard, title: `${index + 1} of ${steps.length}`,
-        body: signIn ? step.fallback : step.caption,
-        actions: signIn ? [{ label: 'Hide', onPress: () => setTucked(true) }, { label: 'Next', onPress: next, primary: true }] : [],
+        at: null, screen, insets, card, setCard, onCollapse: () => setTucked(true), title: `${index + 1} of ${steps.length}`,
+        body: signIn ? `SSB couldn't sign you in, and the review needs it: ${signIn.error}.` : step.caption,
+        actions: signIn ? [{ label: 'Hide', onPress: () => setTucked(true) }, { label: 'Try again', onPress: () => setSignInTry((n) => n + 1), primary: true }] : [],
       });
     }
+    if (step.kind === 'try') {
+      return h(React.Fragment, null,
+        rect ? h(View, { pointerEvents: 'none', style: [s.ring, s.tryRing, { left: rect.left - 6, top: rect.top - 6, width: rect.width + 12, height: rect.height + 12 }] }) : null,
+        h(Card, {
+          at: rect, screen, insets, card, setCard, onCollapse: () => setTucked(true),
+          title: `Try it · ${index + 1} of ${steps.length}`, body: rect ? step.caption : `${step.caption} (looking for it on this screen…)`,
+          actions: [
+            { label: 'Skip', onPress: next },
+            found && handlerFor(found, 'onPress') ? { label: 'Show me', onPress: doIt, primary: true } : null,
+          ].filter(Boolean),
+        }));
+    }
     const canDo = (step.kind === 'click' || step.kind === 'fill') && found && (step.kind === 'click' ? handlerFor(found, 'onPress') : handlerFor(found, 'onChangeText'));
     return h(React.Fragment, null,
       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,
+        at: rect, place: step.place, screen, insets, card, setCard, onCollapse: () => setTucked(true),
         title: stepTitle(step, index, steps.length), body: rescueNote(step.caption, rescue),
         actions: [
           { label: 'Hide', onPress: () => setTucked(true) },
@@ -394,17 +461,23 @@ const button = (label, onPress, primary = false) => h(Pressable, {
   style: ({ pressed }) => [s.button, primary && s.primary, pressed && s.pressed],
 }, h(Text, { style: [s.buttonText, primary && s.primaryText] }, label));
 
-function Card({ at, place, screen, insets, card, setCard, title, body, actions = [] }) {
-  const box = cardBox(place, at, screen, insets, card);
+// Pinned across the top (0.13.0, core.js pinnedBox), with a collapse control
+// in its corner when the player can be collapsed (`onCollapse`).
+function Card({ at, place, screen, insets, card, setCard, title, body, actions = [], onCollapse = null }) {
+  void place; void cardBox;
+  const box = pinnedBox(at, screen, insets, card);
   return h(View, {
-    style: [s.card, { left: box.left, top: box.top, maxWidth: screen.width - 32 }],
+    style: [s.card, { left: box.left, top: box.top, width: box.width }],
     onLayout: (e) => {
       const { width, height } = e.nativeEvent.layout;
       if (Math.abs(width - card.w) > 1 || Math.abs(height - card.h) > 1) setCard({ w: width, h: height });
     },
     accessibilityViewIsModal: false,
   },
-  h(Text, { style: s.title }, title),
+  h(View, { style: s.head },
+    h(Text, { style: [s.title, { flex: 1 }] }, title),
+    onCollapse ? h(Pressable, { testID: 'ssb-demo-collapse', onPress: onCollapse, hitSlop: 12, accessibilityRole: 'button', accessibilityLabel: 'Collapse the review',
+      style: ({ pressed }) => [s.collapse, pressed && s.pressed] }, h(Text, { style: s.collapseText }, '⌃')) : null),
   h(Text, { style: s.body }, body),
   actions.length ? h(View, { style: s.actions }, ...actions.map((a) => h(Pressable, {
     key: a.label, onPress: a.onPress, accessibilityRole: 'button', accessibilityLabel: a.label,
@@ -420,6 +493,10 @@ const s = StyleSheet.create({
   ring: { position: 'absolute', borderRadius: 12, borderWidth: 3, borderColor: '#FFFFFF', shadowColor: '#000', shadowOpacity: 0.6, shadowRadius: 8, shadowOffset: { width: 0, height: 0 } },
   card: { position: 'absolute', width: 320, padding: 16, borderRadius: 16, backgroundColor: '#1C1C1E', shadowColor: '#000', shadowOpacity: 0.35, shadowRadius: 16, shadowOffset: { width: 0, height: 6 } },
   title: { color: '#AEAEB2', fontSize: 12, fontWeight: '600', marginBottom: 6 },
+  head: { flexDirection: 'row', alignItems: 'flex-start' },
+  collapse: { marginLeft: 8, marginTop: -6, paddingHorizontal: 8, paddingVertical: 2, borderRadius: 8, backgroundColor: '#2C2C2E' },
+  collapseText: { color: '#FFFFFF', fontSize: 16, fontWeight: '700' },
+  tryRing: { borderColor: '#FFD60A', borderWidth: 4 },
   body: { color: '#FFFFFF', fontSize: 16, lineHeight: 22 },
   actions: { flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'flex-end', marginTop: 14, gap: 8 },
   button: { paddingVertical: 8, paddingHorizontal: 12, borderRadius: 10, backgroundColor: '#2C2C2E' },

package/src/build-gate.js

@@ -0,0 +1,62 @@
+// THE DEV BUILD MUST MATCH THE REVIEW (0.12.0, docs/TOUR-LINKS.md "6. The
+// bundle checks itself"). Pure, so node --test runs it.
+//
+// A phone review's copy is Metro serving the session's JS, made for ONE native
+// build of the app's dev client: `demo.preview.fingerprint`, the build SSB put
+// in the library for it. A dev client loads whatever JS it is pointed at, so
+// on an older build the review's code ran anyway and failed half-way: Michael's
+// phone (2026-11-05) opened Connie Ho's Profile photos review on a Walk2Gether
+// Dev build older than c316 and its sign-in died "auth/network-request-failed".
+// Every check before that point (the notification's install step, the
+// overlay's ssb-tour gate) was skipped — no install record, a dev-client link.
+//
+// The structural answer is the bundle itself: the player knows what native
+// build the review needs (the demo record) and what native build it is running
+// on (expo-updates' runtimeVersion — under the fingerprint policy, the native
+// fingerprint; the dev builds read it from EXUpdates.bundle/fingerprint). A
+// mismatch never starts the review: it hands the person to the SimonSays app's
+// "need" screen (`simonsays://need?…`, which offers the build SSB made), and
+// the website's /need page when the app is not there. A build that cannot say
+// its runtime, or a review that names none, plays as before.
+
+/** This build's native runtime (expo-updates' runtimeVersion), or null. */
+export function nativeRuntime(mods = globalThis.expo?.modules, nativeModules = {}) {
+  const u = mods?.ExpoUpdates || nativeModules?.ExpoUpdates || {};
+  return typeof u.runtimeVersion === 'string' && u.runtimeVersion && !u.runtimeVersion.startsWith('file:') ? u.runtimeVersion : null;
+}
+
+/** What the review needs that this build is not: null = play it, else { need, have }. */
+export function buildGap(demo, have) {
+  const need = demo?.platform === 'ios' && typeof demo?.preview?.fingerprint === 'string' ? demo.preview.fingerprint : null;
+  if (!need || !have) return null;
+  return need === have ? null : { need, have };
+}
+
+// The dev app's scheme, from the link the copy was opened with
+// (`walk2gether-dev://expo-development-client/?url=…`).
+const schemeOf = (url) => /^([a-z][a-z0-9+.-]*):\/\//i.exec(String(url || ''))?.[1] || undefined;
+const qs = (o) => Object.entries(o).filter(([, v]) => v !== undefined && v !== '').map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+
+/**
+ * Where to send the person: the SimonSays app's need screen, else the site's.
+ * The query is schemas/tour-link.mjs needUrl's (test/build-gate.test.mjs holds
+ * them equal): app, scheme, tour, rt, haveRt.
+ */
+export function needLinks({ demo = {}, gap, demoId, token, site = 'https://simonsays.build' }) {
+  const q = qs({
+    app: demo.appId, scheme: schemeOf(demo.preview?.url), tour: demoId && token ? `${demoId}.${token}` : undefined,
+    rt: gap?.need, haveRt: gap?.have || undefined,
+  });
+  return { app: `simonsays://need?${q}`, web: `${site.replace(/\/$/, '')}/need?${q}` };
+}
+
+/** Open the app's need screen, falling through to the site. `openURL` is Linking.openURL. */
+export async function openNeed(links, openURL) {
+  try { await openURL(links.app); return 'app'; } catch { /* no SimonSays app */ }
+  try { await openURL(links.web); return 'web'; } catch { return null; }
+}
+
+/** The card's words. */
+export function staleBody(gap, appName = 'the app') {
+  return `This review needs a newer ${appName} Dev build (it needs ${gap.need.slice(0, 7)}; this phone has ${gap.have.slice(0, 7)}). Opening the SimonSays app to install it.`;
+}

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.11.0';
+export const PLAYER_VERSION = '0.13.0';
 
 export const HOST = 5;
 export const TEXT = 6;
@@ -21,7 +21,7 @@ export const RECORDED_SCREEN = { width: 393, height: 852 };
 // What a phone can perform. `press` (a keyboard key), `select` (a web
 // <select>) and `run` (a terminal demo) have no phone equivalent. `signin` is
 // the player's own (tourOf, 0.6.0): sign this person in by link.
-const PHONE_KINDS = new Set(['say', 'goto', 'show', 'click', 'fill', 'signin', 'event']);
+const PHONE_KINDS = new Set(['say', 'goto', 'show', 'click', 'fill', 'signin', 'event', 'try']);
 
 const lower = (s) => String(s ?? '').trim().toLowerCase();
 const hiddenHost = (f) => {
@@ -59,6 +59,11 @@ const textOf = (f) => (typeof f.memoizedProps === 'string' ? f.memoizedProps : S
  */
 export function findTarget(root, target) {
   if (!target) return null;
+  // A LIST ITEM by the start of its testID (0.13.0): `walk-card-participant-`
+  // is the first walker's photo, whoever the copy's seed made them.
+  if (target.testIdPrefix) {
+    for (const f of walk(root)) if (f.tag === HOST && String(f.memoizedProps?.testID ?? '').startsWith(target.testIdPrefix)) return f;
+  }
   if (target.testId) {
     for (const f of walk(root)) if (f.tag === HOST && f.memoizedProps?.testID === target.testId) return f;
   }
@@ -174,6 +179,29 @@ export function cardBox(place, at, screen, insets, card) {
   return { left: box.left, top: box.top + insets.top };
 }
 
+// PINNED TO THE TOP (0.13.0, Michael 2026-11-05: "the demo should maybe be
+// pinned to the top by default, but with a collapse button"). The card sits
+// across the top of the screen; only when it would cover the ringed element
+// (`at`) does it move to the bottom. Pure.
+export function pinnedBox(at, screen, insets, card) {
+  const left = 12, width = screen.width - 24;
+  const top = insets.top + 8;
+  const bottom = screen.height - insets.bottom - card.h - 8;
+  const covers = at && at.top < top + card.h + 8 && at.bottom > top;
+  return { left, width, top: covers ? Math.max(top, bottom) : top };
+}
+
+// COLLAPSED, AND RESUMED FROM THE SSB BUTTON (0.13.0): collapsing leaves only
+// the in-app SSB button (packages/ssb-overlay), whose tap resumes the review.
+// The overlay says it is there (`announceOverlay`); without one the player
+// keeps its own pill. `tuckedDemo()` is the resume function while collapsed.
+let tuck = null;
+let overlayHere = false;
+export function setTuckedDemo(resume) { tuck = typeof resume === 'function' ? resume : null; }
+export const tuckedDemo = () => tuck;
+export function announceOverlay() { overlayHere = true; }
+export const overlayAnnounced = () => overlayHere;
+
 // A DEMO STARTED AT RUN TIME (2026-10-20, the in-app overlay's ▶ Demo, "Ready
 // is this build"): the bundle running IS the preview of the work, so nothing
 // is baked into it — SimonSays hands the overlay a demo's id and token, and

package/src/signin.js

@@ -6,7 +6,7 @@
 // only then starts the tour, on that screen. Pure, so node --test runs it.
 
 const SETTLE_MIN_MS = 1500;   // the app's handler signs in and routes before anything is looked for
-const SETTLE_MAX_MS = 12000;  // then the tour starts anyway: a step finds its own element for 8s more
+const SETTLE_MAX_MS = 12000;  // and then the sign-in has not taken: said, the tour stops (0.12.0)
 const POLL_MS = 250;
 
 const pause = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -38,8 +38,8 @@ export const signsIn = (demo, { here = false } = {}) => !here && demo?.platform
 /**
  * Sign `actorIndex` in, then resolve once the app has settled. `openURL` is
  * Linking.openURL; `settled()` says the first screen is up (its element is
- * found). → { ok: true } | { ok: false, error } (the player falls back to
- * saying who to sign in as).
+ * found). → { ok: true } | { ok: false, error } (the player stops the tour
+ * with Try again).
  */
 export async function signInFirst({ api, actorIndex, openURL, settled = () => true, sleep = pause, minMs = SETTLE_MIN_MS, maxMs = SETTLE_MAX_MS }) {
   let link;
@@ -51,6 +51,12 @@ export async function signInFirst({ api, actorIndex, openURL, settled = () => tr
     return { ok: false, error: e?.message || String(e) };
   }
   await sleep(minMs);
-  for (let waited = minMs; waited < maxMs && !settled(); waited += POLL_MS) await sleep(POLL_MS);
+  let ok = false;
+  for (let waited = minMs; waited < maxMs; waited += POLL_MS) { if ((ok = !!settled())) break; await sleep(POLL_MS); }
+  // CONFIRMED, NOT ASSUMED (0.12.0): the first screen past sign-in never came
+  // up, so the sign-in did not take — the app's own handler failed (2026-11-05:
+  // "Failed to verify token: [auth/network-request-failed]" while the tour
+  // carried on to Next and Take me there). Said, and the tour stops.
+  if (!ok) return { ok: false, error: "the app didn't sign in (its first screen never appeared)" };
   return { ok: true };
 }