@simon-says-build/demo-player 0.4.0 → 0.6.0

package/README.md

@@ -22,4 +22,6 @@ Pass the `process.env.EXPO_PUBLIC_*` reads in the app's own code. Expo inlines t
 
 Without all three it renders its children and nothing else. Elements are found by `testID`, then `accessibilityLabel`, then visible text, by walking React's tree. No component needs wrapping.
 
+**0.6.0: SSB signs the viewer in** on a phone's private, seeded copy (docs/MOBILE-DEMO.md "Sign-in (stage 2: SSB signs in)"). Before each person's part the player asks the demo API for their sign-in link (`POST /api/demo/:id/signin`), opens it with `Linking.openURL`, waits for the app to settle, and starts on the screen the link opened. The walk's own sign-in steps are skipped. The app must handle `<scheme>://auth?token=<custom token>&next=<path>`: sign in with the custom token, then route to `next`. Where there is no link (the app's real backend, no URL scheme, the copy not up), the card says who to sign in as, as before.
+
 `npm test` runs the pure half.

package/index.d.ts

@@ -31,3 +31,13 @@ export const PLAYER_VERSION: string;
 export function reviewChangesOf(demo: unknown): { jobId: string; title: string }[];
 /** A release's demo (0.4.0): the session merge its review card releases, or null. */
 export function releaseOf(demo: unknown): { jobId: string; label: string; note: string } | null;
+
+/**
+ * React Navigation (an app without expo-router): a path is the chain of route
+ * names to the focused screen, "/MainStack/Tabs/Dashboard". `nav` is the
+ * NavigationContainer's ref (or the container), read at call time.
+ */
+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;

package/index.js

@@ -1,2 +1,3 @@
 export { DemoHost } from './src/DemoHost.js';
 export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint, playDemo, currentDemo, onDemo, reviewChangesOf, releaseOf, PLAYER_VERSION } 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.4.0",
+  "version": "0.6.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

@@ -8,12 +8,15 @@
 // A demo of CHANGES ends on a review card (0.3.0): ✓ Approve or 💬 Discuss
 // (a RELEASE's demo, 0.4.0: one Approve & release for all of them)
 // each one, the extension's guided review on the phone (docs/GUIDED-REVIEW.md).
+// On a phone's private copy (0.6.0) it signs each person in first, by the
+// app's own auth deep link, and starts their part on the screen it opens.
 //
 // 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 } from './core.js';
 import { demoApi, tourOf } from './api.js';
+import { signInFirst } from './signin.js';
 
 const h = React.createElement;
 const FIND_FOR_MS = 8000;      // a step's element may appear after a navigation settles
@@ -71,6 +74,7 @@ function Player({ config, router, insets, onClose, children }) {
   const [changes, setChanges] = useState([]);     // what the last card reviews (reviewChangesOf)
   const [release, setRelease] = useState(null);   // a release's demo ends on releasing it (releaseOf)
   const [reviewing, setReviewing] = useState(false);
+  const [signIn, setSignIn] = useState(null);     // a `signin` step: null while it runs, else { ok, error }
 
   useEffect(() => {
     let live = true;
@@ -82,6 +86,7 @@ function Player({ config, router, insets, onClose, children }) {
 
   const step = steps?.[index] ?? null;
 
+
   // Find and follow the step's element.
   useEffect(() => {
     setRect(null); setFound(null);
@@ -134,6 +139,26 @@ function Player({ config, router, insets, onClose, children }) {
     next();
   }, [step, found, next]);
 
+  // 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).
+  useEffect(() => {
+    setSignIn(null);
+    if (step?.kind !== 'signin' || done) return undefined;
+    let live = true;
+    const first = steps[index + 1];
+    signInFirst({
+      api, actorIndex: step.actorIndex, openURL: (url) => Linking.openURL(url),
+      settled: () => !live || !first?.target || first.target.point || !!findTarget(fiberOf(rootRef.current), first.target),
+    }).then((r) => {
+      if (!live) return;
+      if (!r.ok) { setSignIn(r); return; }
+      if (index + 1 >= steps.length) { if (changes.length) setReviewing(true); else finish(); }
+      else setIndex(index + 1);
+    });
+    return () => { live = false; };
+  }, [step, done]);
+
   const overlay = (() => {
     if (error) return h(Card, { at: null, screen, insets, card, setCard, title: 'Demo', body: `The demo didn't load: ${error}` });
     if (!steps) return null;
@@ -148,6 +173,13 @@ 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.' });
+    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 }] : [],
+      });
+    }
     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,
@@ -156,7 +188,7 @@ function Player({ config, router, insets, onClose, children }) {
         title: `${index + 1} of ${steps.length}`, body: step.caption,
         actions: [
           { label: 'Hide', onPress: () => setTucked(true) },
-          index > 0 ? { label: 'Back', onPress: () => setIndex(index - 1) } : null,
+          index > 0 && steps[index - 1].kind !== 'signin' ? { label: 'Back', onPress: () => setIndex(index - 1) } : null,
           canDo ? { label: step.kind === 'fill' ? 'Type it for me' : 'Do it for me', onPress: doIt } : null,
           { label: index + 1 >= steps.length ? 'Finish' : step.kind === 'goto' ? 'Take me there' : 'Next', onPress: next, primary: true },
         ].filter(Boolean),

package/src/api.js

@@ -1,3 +1,6 @@
+import { skipAuthSteps } from './auth-steps.js';
+import { signsIn } from './signin.js';
+
 // The demo API the web extension already calls (functions/index.mjs
 // /api/demo/:id/*), authenticated by the demo's own token.
 export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
@@ -19,6 +22,8 @@ export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
     // A release's demo (0.4.0): approve and release the session, as the person
     // the demo was made for, after the five-minute cool-off.
     release: () => call('/release', { method: 'POST', body: '{}' }),
+    // A phone's private copy (0.6.0): the link that signs this person in.
+    signin: (actorIndex) => call('/signin', { method: 'POST', body: JSON.stringify({ actorIndex }) }),
     discuss: (jobId, text) => call('/chat', { method: 'POST', body: JSON.stringify({ text, context: { about: jobId } }) }),
   };
 }
@@ -26,13 +31,19 @@ export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
 /** The tour a phone plays: every actor's steps, each actor introduced by who to be. */
 // A demo played in the build the viewer is already using, signed in as
 // themselves (`here`, the overlay's ▶ Demo), is not told who to sign in as.
+// One that SIGNS IN ITSELF (0.6.0, `signsIn`: a phone's private copy) opens
+// each person with a `signin` step instead — the player signs them in, the
+// card saying who to be only if that fails — and drops the walk's own sign-in.
 export function tourOf(demo, { here = false } = {}) {
+  const auto = signsIn(demo, { here });
   const out = [];
   for (const [actorIndex, a] of (demo?.actors || []).entries()) {
     const steps = a.tour?.steps || [];
     if (!steps.length) continue;
-    if (!here) out.push({ kind: 'say', caption: `This part is as ${a.label}. Sign in as ${a.email} if you aren't already, then tap Next.`, actorIndex, intro: true });
-    for (const s of steps) out.push({ ...s, actorIndex });
+    const ask = `This part is as ${a.label}. Sign in as ${a.email} if you aren't already, then tap Next.`;
+    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 });
   }
   return out;
 }

package/src/auth-steps.js

@@ -0,0 +1,56 @@
+// THE WALK'S OWN SIGN-IN, SKIPPED (0.6.0, docs/MOBILE-DEMO.md "Sign-in (stage
+// 2: SSB signs in)"): a player that signs the viewer in by link has no use for
+// the taps and typing the recording made to sign in or up. They are found by
+// what they ARE — the screen's path, the element's testID / label / text, the
+// credential typed — never by a caption's wording, and only at the head of a
+// person's steps, before the first screen past sign-in.
+
+// Kept equal to functions/sandbox-signin.mjs AUTH_PATH (the server's `next`
+// skips the same screens): expo-router's `(auth)` group, a sign-in, sign-up,
+// login, register or verify-code screen.
+export const AUTH_PATH = /(^|[/(])(auth|sign-?in|sign-?up|log-?in|register|verify(-[a-z]+)?|otp)([/)?#]|$)/i;
+// An element of a sign-in screen, by its testID / accessibility label / text.
+const AUTH_TARGET = /sign[\s_-]?in|sign[\s_-]?up|log[\s_-]?in|register|password|passcode|otp|verif|\bauth|phone|\bcode\b/i;
+// What a sign-in types: an email, a phone number, a texted code (the walk's
+// recorded credential, as schemas/verify-walk.mjs signInOf reads an email).
+const CREDENTIAL = /^([^\s@]+@[^\s@]+\.[^\s@]+|\+?[\d\s().-]{7,}|\d{4,8})$/;
+
+const pathOf = (s) => (typeof s?.path === 'string' ? s.path.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '/') : '');
+const targetWords = (t) => (t && typeof t === 'object' ? [t.testId, t.label, t.text, t.name, t.placeholder].filter((v) => typeof v === 'string').join(' ') : '');
+
+/** A step that signs in or up: on an auth screen, at an auth element, or typing a credential. */
+export function isAuthStep(s) {
+  if (!s) return false;
+  if (pathOf(s) && AUTH_PATH.test(pathOf(s))) return true;
+  if (AUTH_TARGET.test(targetWords(s.target))) return true;
+  return s.kind === 'fill' && CREDENTIAL.test(String(s.value ?? '').trim());
+}
+
+/**
+ * The index of the first step past the walk's sign-in (0 when it has none).
+ * The head ends at the first screen past sign-in: a `show` of the change, or a
+ * `goto` to a screen that is not an auth one. A tap or key right after the
+ * last credential typed is its submit.
+ */
+export function authStepsEnd(steps = []) {
+  let end = 0;
+  let typedAt = -1;
+  for (let i = 0; i < steps.length; i++) {
+    const s = steps[i];
+    if (!s || s.kind === 'show') break;
+    if (s.kind === 'goto' && !isAuthStep(s)) break;
+    if (isAuthStep(s)) {
+      end = i + 1;
+      if (s.kind === 'fill') typedAt = i;
+    } else if ((s.kind === 'click' || s.kind === 'press') && typedAt >= 0 && typedAt === i - 1) {
+      end = i + 1;
+    }
+  }
+  return end;
+}
+
+/** A person's steps without the walk's sign-in. A caption card (`say`) in it stays. */
+export function skipAuthSteps(steps = []) {
+  const end = authStepsEnd(steps);
+  return steps.filter((s, i) => i >= end || s?.kind === 'say');
+}

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.4.0';
+export const PLAYER_VERSION = '0.6.0';
 
 export const HOST = 5;
 export const TEXT = 6;
@@ -19,8 +19,9 @@ export const TEXT = 6;
 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.
-const PHONE_KINDS = new Set(['say', 'goto', 'show', 'click', 'fill']);
+// <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']);
 
 const lower = (s) => String(s ?? '').trim().toLowerCase();
 const hiddenHost = (f) => {

package/src/navigation.js

@@ -0,0 +1,52 @@
+// REACT NAVIGATION, for an app without expo-router (2026-10-22, SuperSub's
+// Center and Sub apps). A demo's `goto` step carries an in-app PATH, and the
+// in-app overlay reports the screen a person is on as one. For an
+// expo-router app that is its URL path. For a React Navigation app it is the
+// chain of route NAMES from the root to the focused screen:
+//
+//     /MainStack/Tabs/Dashboard
+//
+// navigationRoute() reads that off the navigation container, and
+// navigationRouter() replays it with nested navigate() calls, so a path the
+// overlay recorded is one the demo player can open. Both take the container
+// (or a ref to it, read at call time). Pure apart from the container.
+
+const containerOf = (nav) => (nav && 'current' in nav ? nav.current : nav);
+
+/** The focused route's path, "/A/B/C", from a navigation state; "" when there is none. */
+export function pathOfState(state) {
+  const names = [];
+  for (let s = state; s && Array.isArray(s.routes) && s.routes.length;) {
+    const r = s.routes[Number.isInteger(s.index) ? s.index : s.routes.length - 1];
+    if (!r?.name) break;
+    names.push(r.name);
+    s = r.state;
+  }
+  return names.length ? `/${names.map(encodeURIComponent).join('/')}` : '';
+}
+
+/** What navigate() is called with to open a path: [name, params], or null for a path that names nothing. */
+export function navigateArgs(path) {
+  const names = String(path || '').split('?')[0].split('/').filter(Boolean).map((n) => { try { return decodeURIComponent(n); } catch { return n; } });
+  if (!names.length) return null;
+  let params;
+  for (let i = names.length - 1; i >= 1; i--) params = params ? { screen: names[i], params } : { screen: names[i] };
+  return params ? [names[0], params] : [names[0]];
+}
+
+/** The current screen's path on a React Navigation container ("" before it is ready). */
+export function navigationRoute(nav) {
+  try { return pathOfState(containerOf(nav)?.getRootState?.()); } catch { return ''; }
+}
+
+/** A `router` for <DemoHost> on a React Navigation app: push(path) opens it. */
+export function navigationRouter(nav) {
+  return {
+    push(path) {
+      const c = containerOf(nav);
+      const args = navigateArgs(path);
+      if (!c?.navigate || !args) return false;
+      try { c.navigate(...args); return true; } catch { return false; }
+    },
+  };
+}

package/src/signin.js

@@ -0,0 +1,35 @@
+// SSB SIGNS THE VIEWER IN (0.6.0, docs/MOBILE-DEMO.md "Sign-in (stage 2)").
+// On a private, seeded copy the demo API answers a person's sign-in link,
+// `<scheme>://auth?token=…&next=<first screen>` (functions/sandbox-signin.mjs).
+// The player opens it FIRST; the app's own auth deep-link handler signs in
+// with the token and routes to `next`; the player waits for that to settle and
+// 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 POLL_MS = 250;
+
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Whether a demo signs its people in itself: a phone's private copy, not a build the viewer is already in. */
+export const signsIn = (demo, { here = false } = {}) => !here && demo?.platform === 'ios' && demo?.backend === 'sandbox';
+
+/**
+ * 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).
+ */
+export async function signInFirst({ api, actorIndex, openURL, settled = () => true, sleep = pause, minMs = SETTLE_MIN_MS, maxMs = SETTLE_MAX_MS }) {
+  let link;
+  try {
+    ({ link } = await api.signin(actorIndex));
+    if (typeof link !== 'string' || !link) throw new Error('no sign-in link');
+    await openURL(link);
+  } catch (e) {
+    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);
+  return { ok: true };
+}

package/src/step-place.js

@@ -9,13 +9,18 @@
 //   pinTo   below | above | left | right   beside the element, `offset` px away
 //           top | bottom                   pinned to that edge of the screen,
 //                                          `offset` px in (an arrow points at the element)
-//   offset  0–600 px (default 14 beside an element, 24 at an edge)
+//   offset  0–600 px (default 44 beside an element, 24 at an edge)
+//
+// Beside an element the bubble stands OFF it by default, far enough that the
+// player draws its arrow to the ring (2026-10-26, Simon's budget guide: a
+// bubble flush against a drag handle sat on the track he was dragging along).
 //
 // No placement is the old rule: below the element when it fits, else above.
 // Pure and browser-safe: demo-step writes it, the rehearsal keeps it, the
 // player (extension/overlay.js) reads it.
 export const PIN_TO = ['below', 'above', 'left', 'right', 'top', 'bottom'];
 export const MAX_OFFSET = 600;
+export const BESIDE_OFFSET = 44;
 
 /** A placement, cleaned; null when there is none (or it is not one). */
 export function cleanPlace(raw) {
@@ -43,7 +48,7 @@ export function bubbleBox(place, el, view, bubble) {
     const left = clampX(el ? el.left + el.width / 2 - bubble.w / 2 : (view.w - bubble.w) / 2);
     return { left, top: p?.pinTo === 'top' ? clampY(off) : clampY(view.h - bubble.h - off) };
   }
-  const off = p?.offset ?? 14;
+  const off = p?.offset ?? BESIDE_OFFSET;
   const pin = p?.pinTo || (el.bottom + off + bubble.h <= view.h - 16 ? 'below' : 'above');
   if (pin === 'below') return { left: clampX(el.left), top: clampY(el.bottom + off) };
   if (pin === 'above') return { left: clampX(el.left), top: clampY(el.top - off - bubble.h) };