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

package/README.md

@@ -22,6 +22,10 @@ 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.8.0: a planned review's events** (`event` steps, docs/PLANNED-REVIEW.md). The player asks SSB to run a helper on the review's private copy ("and now a walker arrives"), waits until it's done, and fills `{name}` in that person's later steps from its outputs. A person with a planned `state` has it set up (`@state`) before they're signed in, so their world is current every time the review opens. A failed setup stays on its card with the reason and a Next button.
+
+**0.7.0: the sign-in link opens through the app's router** (`openInApp`), not `Linking.openURL`. The link names app.json's scheme, and a review plays in the dev build, whose scheme can differ (Walk2Gether's is `walk2gether-dev`), so the OS opened the production app or nothing. Without a `router`, the OS opens it as before.
+
 **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/package.json

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

@@ -16,7 +16,8 @@ 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';
+import { signInFirst, openInApp } from './signin.js';
+import { runEvent, fillStep } from './events.js';
 
 const h = React.createElement;
 const FIND_FOR_MS = 8000;      // a step's element may appear after a navigation settles
@@ -75,6 +76,8 @@ function Player({ config, router, insets, onClose, children }) {
   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 }
+  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)
 
   useEffect(() => {
     let live = true;
@@ -84,7 +87,7 @@ function Player({ config, router, insets, onClose, children }) {
     return () => { live = false; };
   }, [api]);
 
-  const step = steps?.[index] ?? null;
+  const step = useMemo(() => { const raw = steps?.[index] ?? null; return raw ? fillStep(raw, vars[raw.actorIndex]) : null; }, [steps, index, vars]);
 
 
   // Find and follow the step's element.
@@ -139,6 +142,23 @@ function Player({ config, router, insets, onClose, children }) {
     next();
   }, [step, found, next]);
 
+  // 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.
+  useEffect(() => {
+    setEvent(null);
+    if (step?.kind !== 'event' || done) return undefined;
+    let live = true;
+    runEvent({ api, actorIndex: step.actorIndex, helper: step.helper, args: step.args || {} }).then((r) => {
+      if (!live) return;
+      if (!r.ok) { setEvent(r); return; }
+      setVars((v) => ({ ...v, [step.actorIndex]: { ...(v[step.actorIndex] || {}), ...r.outputs } }));
+      if (index + 1 >= steps.length) { if (changes.length) setReviewing(true); else finish(); }
+      else setIndex(index + 1);
+    });
+    return () => { live = false; };
+  }, [step?.kind, step?.helper, index, done]);
+
   // 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).
@@ -148,7 +168,7 @@ function Player({ config, router, insets, onClose, children }) {
     let live = true;
     const first = steps[index + 1];
     signInFirst({
-      api, actorIndex: step.actorIndex, openURL: (url) => Linking.openURL(url),
+      api, actorIndex: step.actorIndex, openURL: (url) => openInApp(url, { router, openURL: (u) => Linking.openURL(u) }),
       settled: () => !live || !first?.target || first.target.point || !!findTarget(fiberOf(rootRef.current), first.target),
     }).then((r) => {
       if (!live) return;
@@ -173,6 +193,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 === '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 }] : [],
+      });
+    }
     if (step.kind === 'signin') {
       return h(Card, {
         at: null, screen, insets, card, setCard, title: `${index + 1} of ${steps.length}`,

package/src/api.js

@@ -1,5 +1,6 @@
 import { skipAuthSteps } from './auth-steps.js';
 import { signsIn } from './signin.js';
+import { hasState } from './events.js';
 
 // The demo API the web extension already calls (functions/index.mjs
 // /api/demo/:id/*), authenticated by the demo's own token.
@@ -24,6 +25,9 @@ export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
     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 }) }),
+    // 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)}`),
     discuss: (jobId, text) => call('/chat', { method: 'POST', body: JSON.stringify({ text, context: { about: jobId } }) }),
   };
 }
@@ -41,6 +45,8 @@ export function tourOf(demo, { here = false } = {}) {
     const steps = a.tour?.steps || [];
     if (!steps.length) continue;
     const ask = `This part is as ${a.label}. Sign in as ${a.email} if you aren't already, then tap Next.`;
+    // A planned review sets this person's world up first (0.8.0): `@state`.
+    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 });

package/src/auth-steps.js

@@ -49,8 +49,8 @@ export function authStepsEnd(steps = []) {
   return end;
 }
 
-/** A person's steps without the walk's sign-in. A caption card (`say`) in it stays. */
+/** A person's steps without the walk's sign-in. A caption card (`say`) or an `event` in it stays. */
 export function skipAuthSteps(steps = []) {
   const end = authStepsEnd(steps);
-  return steps.filter((s, i) => i >= end || s?.kind === 'say');
+  return steps.filter((s, i) => i >= end || s?.kind === 'say' || s?.kind === 'event');
 }

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.6.0';
+export const PLAYER_VERSION = '0.8.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']);
+const PHONE_KINDS = new Set(['say', 'goto', 'show', 'click', 'fill', 'signin', 'event']);
 
 const lower = (s) => String(s ?? '').trim().toLowerCase();
 const hiddenHost = (f) => {

package/src/events.js

@@ -0,0 +1,41 @@
+// A PLANNED REVIEW'S EVENTS (0.8.0, docs/PLANNED-REVIEW.md). An `event` step is
+// "and now…": the player asks SSB to run a helper on the review's private copy
+// (POST /api/demo/:id/event), waits for the box serving the copy to say it's
+// done, and carries its outputs into later steps (`{walkId}` in a path).
+// `@state` is the person's own world, set up when their part opens, before
+// sign-in, so a walk "starting in 30 minutes" is always 30 minutes away.
+// Pure, so node --test runs it.
+
+const POLL_MS = 1000;
+const EVENT_MAX_MS = 60000;
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Run one event and wait for it. → { ok: true, outputs } | { ok: false, error }.
+ */
+export async function runEvent({ api, actorIndex, helper, args = {}, sleep = pause, maxMs = EVENT_MAX_MS }) {
+  let eventId;
+  try { ({ eventId } = await api.event(actorIndex, helper, args)); } catch (e) { return { ok: false, error: e?.message || String(e) }; }
+  if (!eventId) return { ok: false, error: 'SSB did not take the event' };
+  for (let waited = 0; waited < maxMs; waited += POLL_MS) {
+    await sleep(POLL_MS);
+    let e;
+    try { e = await api.eventStatus(eventId); } catch { continue; } // a dropped poll is not a failure
+    if (e?.status === 'done') return { ok: true, outputs: e.outputs || {} };
+    if (e?.status === 'failed') return { ok: false, error: e.why || 'the setup failed' };
+  }
+  return { ok: false, error: 'the setup took too long' };
+}
+
+/** `{name}` in a step's path, value, caption and args, from this person's outputs. Pure. */
+export function fillStep(step, vars = {}) {
+  if (!step || !vars || !Object.keys(vars).length) return step;
+  const fill = (v) => typeof v === 'string' ? v.replace(/\{([A-Za-z0-9_]+)\}/g, (m, k) => (vars[k] != null ? String(vars[k]) : m))
+    : Array.isArray(v) ? v.map(fill) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fill(x)])) : v;
+  const out = { ...step };
+  for (const k of ['path', 'value', 'caption', 'args', 'target']) if (out[k] != null) out[k] = fill(out[k]);
+  return out;
+}
+
+/** Whether a person has a world to set up when their part opens. Pure. */
+export const hasState = (actor) => Array.isArray(actor?.plan?.state) && actor.plan.state.length > 0;

package/src/signin.js

@@ -11,6 +11,27 @@ const POLL_MS = 250;
 
 const pause = (ms) => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * The app path of a link in the app's own deep-link form: `x://auth?token=…`
+ * → `/auth?token=…`. The player opens its sign-in through the app's ROUTER
+ * (0.7.0), never the OS: the link names the app's scheme as app.json says it,
+ * and a review plays in the DEV build, whose scheme differs (walk2gether-dev),
+ * so Linking.openURL opened the production app, or nothing (2026-10-31). The
+ * router is always the app the player runs in. Pure; null for anything else.
+ */
+export function inAppPath(link) {
+  const m = /^[a-z][a-z0-9+.-]*:\/\/(.*)$/i.exec(String(link || ''));
+  if (!m || /^https?:/i.test(String(link))) return null;
+  return `/${m[1].replace(/^\/+/, '')}`;
+}
+
+/** Open a sign-in link in THIS app: its router when it has one, else the OS. */
+export async function openInApp(link, { router, openURL }) {
+  const p = inAppPath(link);
+  if (p && router?.push) { router.push(p); return; }
+  await openURL(link);
+}
+
 /** 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';