@simon-says-build/demo-player 0.1.0 → 0.3.0

package/index.d.ts

@@ -15,3 +15,17 @@ export function DemoHost(props: {
   insets?: { top?: number; bottom?: number };
   children?: ReactNode;
 }): ReactNode;
+
+/**
+ * Play a demo now, in the bundle already running (the in-app SSB overlay's
+ * ▶ Demo hands SimonSays' answer here). `null` stops it. A demo baked into
+ * the bundle (`<DemoHost demo>`) outranks it. Returns false for an incomplete demo.
+ */
+export function playDemo(demo: DemoBundle | null): boolean;
+export function currentDemo(): { id: string; token: string; api: string } | null;
+export function onDemo(fn: (demo: { id: string; token: string; api: string } | null) => void): () => void;
+
+/** This player's version (0.3.0+), sent by the SSB overlay when it registers for pushes. */
+export const PLAYER_VERSION: string;
+/** The changes a demo's last card offers to approve or discuss: one per `job:<id>` feature. */
+export function reviewChangesOf(demo: unknown): { jobId: string; title: string }[];

package/index.js

@@ -1,2 +1,2 @@
 export { DemoHost } from './src/DemoHost.js';
-export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint } from './src/core.js';
+export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint, playDemo, currentDemo, onDemo, reviewChangesOf, PLAYER_VERSION } from './src/core.js';

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@simon-says-build/demo-player",
-  "version": "0.1.0",
+  "version": "0.3.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",
+    "url": "git+https://github.com/simon-says-studio/simon-says-build.git",
+    "directory": "packages/demo-player"
+  },
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
-  "files": ["index.js", "index.d.ts", "src/", "README.md"],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "README.md"
+  ],
   "peerDependencies": {
     "react": ">=18",
     "react-native": ">=0.76"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "license": "UNLICENSED"
 }

package/src/DemoHost.js

@@ -5,11 +5,13 @@
 // for a demo sets). With one, it loads the demo's tour from SimonSays and walks
 // the viewer through it: a ring on each step's element, a caption card with
 // Back / Next, "Do it for me" on taps and typing, and a pill to tuck it away.
+// A demo of CHANGES ends on a review card (0.3.0): ✓ Approve or 💬 Discuss
+// each one, the extension's guided review on the phone (docs/GUIDED-REVIEW.md).
 //
 // 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, StyleSheet, Text, View, useWindowDimensions } from 'react-native';
-import { cardBox, demoConfig, findTarget, handlerFor, phoneSteps, scalePoint } from './core.js';
+import { Linking, Pressable, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions } from 'react-native';
+import { cardBox, currentDemo, demoConfig, findTarget, handlerFor, onDemo, phoneSteps, playDemo, reviewChangesOf, scalePoint } from './core.js';
 import { demoApi, tourOf } from './api.js';
 
 const h = React.createElement;
@@ -44,12 +46,16 @@ const measure = (fiber) => new Promise((resolve) => {
 const DEFAULT_INSETS = { top: 60, bottom: 100 };
 
 export function DemoHost({ demo, router, insets, children }) {
-  const config = useMemo(() => demoConfig(demo || {}), [demo?.id, demo?.token, demo?.api]);
+  const baked = useMemo(() => demoConfig(demo || {}), [demo?.id, demo?.token, demo?.api]);
+  const [started, setStarted] = useState(currentDemo);
+  useEffect(() => onDemo(setStarted), []);
+  const config = baked || started;
   if (!config) return children ?? null;
-  return h(Player, { config, router, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
+  // Keyed by the demo: a second ▶ Demo starts its own tour from the first step.
+  return h(Player, { key: config.id, config, router, insets: { ...DEFAULT_INSETS, ...(insets || {}) }, onClose: baked ? null : () => playDemo(null) }, children);
 }
 
-function Player({ config, router, insets, children }) {
+function Player({ config, router, insets, onClose, children }) {
   const rootRef = useRef(null);
   const screen = useWindowDimensions();
   const api = useMemo(() => demoApi(config), [config]);
@@ -61,11 +67,13 @@ function Player({ config, router, insets, children }) {
   const [card, setCard] = useState({ w: 320, h: 140 });
   const [tucked, setTucked] = useState(false);
   const [done, setDone] = useState(false);
+  const [changes, setChanges] = useState([]);     // what the last card reviews (reviewChangesOf)
+  const [reviewing, setReviewing] = useState(false);
 
   useEffect(() => {
     let live = true;
     api.load()
-      .then((d) => { if (live) setSteps(phoneSteps(tourOf(d)).concat()); })
+      .then((d) => { if (live) { setSteps(phoneSteps(tourOf(d, { here: !!config.here })).concat()); setChanges(reviewChangesOf(d)); } })
       .catch((e) => { if (live) setError(e.message); });
     return () => { live = false; };
   }, [api]);
@@ -102,6 +110,7 @@ function Player({ config, router, insets, children }) {
   }, [step, done, screen.width, screen.height]);
 
   const finish = useCallback(() => {
+    setReviewing(false);
     setDone(true);
     api.progress({ status: 'done' }).catch(() => {});
   }, [api]);
@@ -112,9 +121,9 @@ function Player({ config, router, insets, children }) {
       if (step.path.startsWith('/') && router?.push) router.push(step.path);
       else Linking.openURL(step.path).catch(() => {});
     }
-    if (index + 1 >= steps.length) finish();
+    if (index + 1 >= steps.length) { if (changes.length) setReviewing(true); else finish(); }
     else setIndex(index + 1);
-  }, [steps, step, index, router, finish]);
+  }, [steps, step, index, router, finish, changes]);
 
   const doIt = useCallback(() => {
     if (!step || !found) return;
@@ -126,10 +135,16 @@ function Player({ config, router, insets, children }) {
   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;
+    if (reviewing && !tucked) return h(Review, { api, changes, screen, insets, onBack: steps.length ? () => setReviewing(false) : null, onDone: finish, onHide: () => setTucked(true) });
     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.
+      if (done && onClose) return h(Pressable, { style: [s.pill, { bottom: insets.bottom + 12 }], onPress: onClose, accessibilityRole: 'button', accessibilityLabel: 'Close the demo', testID: 'ssb-demo-close' },
+        h(Text, { style: s.pillText }, 'Demo done · close'));
       return h(Pressable, { style: [s.pill, { bottom: insets.bottom + 12 }], onPress: () => { setTucked(false); if (done) { setDone(false); setIndex(0); } }, accessibilityRole: 'button', accessibilityLabel: 'Open the demo' },
-        h(Text, { style: s.pillText }, done ? 'Demo done · replay' : `Demo ${index + 1}/${steps.length}`));
+        h(Text, { style: s.pillText }, done ? 'Demo done · replay' : reviewing ? 'Review the changes' : `Demo ${index + 1}/${steps.length}`));
     }
+    if (!step && changes.length) return h(Review, { api, changes, 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.' });
     const canDo = (step.kind === 'click' || step.kind === 'fill') && found && (step.kind === 'click' ? handlerFor(found, 'onPress') : handlerFor(found, 'onChangeText'));
     return h(React.Fragment, null,
@@ -151,6 +166,55 @@ function Player({ config, router, insets, children }) {
     h(View, { pointerEvents: 'box-none', style: StyleSheet.absoluteFill }, overlay));
 }
 
+// The review card: every change of the demo, each approved here or discussed
+// with SSB. A word on a change is said in the conversation it came from, so
+// SSB revises THAT change (functions/demo.mjs reviewRef). Nothing here holds
+// the tour: Done closes it whatever is left undecided.
+const ROW = { idle: null, approving: 'Approving…', approved: '✓ Approved', sending: 'Sending…', sent: 'Sent to SSB — it will revise this' };
+function Review({ api, changes, screen, insets, onBack, onDone, onHide }) {
+  const [rows, setRows] = useState({});           // jobId → { state, error, text }
+  const set = (id, patch) => setRows((r) => ({ ...r, [id]: { ...(r[id] || {}), ...patch } }));
+  const approve = (id) => {
+    set(id, { state: 'approving', error: null });
+    api.approve(id).then(() => set(id, { state: 'approved' })).catch((e) => set(id, { state: 'idle', error: e.message }));
+  };
+  const send = (id) => {
+    const text = String(rows[id]?.text || '').trim();
+    if (!text) return;
+    set(id, { state: 'sending', error: null });
+    api.discuss(id, text).then(() => set(id, { state: 'sent' })).catch((e) => set(id, { state: 'discussing', error: e.message }));
+  };
+  const left = changes.filter((c) => !['approved', 'sent'].includes(rows[c.jobId]?.state)).length;
+  return h(View, { style: [s.card, s.review, { top: insets.top + 12, maxHeight: screen.height - insets.top - insets.bottom - 24, maxWidth: screen.width - 32, left: Math.max(16, (screen.width - Math.min(360, screen.width - 32)) / 2) }], testID: 'ssb-demo-review' },
+    h(Text, { style: s.title }, changes.length === 1 ? 'Review the change' : `Review ${changes.length} changes`),
+    h(Text, { style: s.body }, 'Approve what looks right. Anything that should be different, say so — SSB revises it.'),
+    h(ScrollView, { style: s.changes, keyboardShouldPersistTaps: 'handled' }, ...changes.map((c) => {
+      const r = rows[c.jobId] || {};
+      const state = r.state || 'idle';
+      return h(View, { key: c.jobId, style: s.change },
+        h(Text, { style: s.changeTitle }, c.title),
+        ROW[state] ? h(Text, { style: s.changeState }, ROW[state]) : null,
+        r.error ? h(Text, { style: s.error }, r.error) : null,
+        state === 'discussing' ? h(View, null,
+          h(TextInput, { style: s.input, value: r.text || '', onChangeText: (text) => set(c.jobId, { text }), placeholder: 'What should be different?', placeholderTextColor: '#8E8E93', multiline: true, autoFocus: true, accessibilityLabel: `What should be different about ${c.title}`, testID: `ssb-review-note-${c.jobId}` }),
+          h(View, { style: s.actions },
+            button('Cancel', () => set(c.jobId, { state: 'idle', error: null })),
+            button('Send', () => send(c.jobId), true))) : null,
+        state === 'idle' ? h(View, { style: s.actions },
+          button('💬 Discuss', () => set(c.jobId, { state: 'discussing' })),
+          button('✓ Approve', () => approve(c.jobId), true)) : null);
+    })),
+    h(View, { style: [s.actions, s.reviewFoot] },
+      button('Hide', onHide),
+      onBack ? button('Back', onBack) : null,
+      button(left ? `Done (${left} undecided)` : 'Done', onDone, !left)));
+}
+
+const button = (label, onPress, primary = false) => h(Pressable, {
+  key: label, onPress, accessibilityRole: 'button', accessibilityLabel: label,
+  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);
   return h(View, {
@@ -181,6 +245,14 @@ const s = StyleSheet.create({
   pressed: { opacity: 0.7 },
   buttonText: { color: '#FFFFFF', fontSize: 14, fontWeight: '600' },
   primaryText: { color: '#1C1C1E' },
+  review: { width: 360 },
+  changes: { flexGrow: 0 },
+  reviewFoot: { marginTop: 16 },
+  change: { marginTop: 14, paddingTop: 12, borderTopWidth: StyleSheet.hairlineWidth, borderTopColor: '#3A3A3C' },
+  changeTitle: { color: '#FFFFFF', fontSize: 15, fontWeight: '600' },
+  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 },
   pill: { position: 'absolute', right: 16, paddingVertical: 8, paddingHorizontal: 14, borderRadius: 18, backgroundColor: '#1C1C1E' },
   pillText: { color: '#FFFFFF', fontSize: 13, fontWeight: '600' },
 });

package/src/api.js

@@ -13,16 +13,22 @@ export function demoApi({ api, id, token }, fetchImpl = globalThis.fetch) {
   return {
     load: () => call(''),
     progress: (body) => call('/progress', { method: 'POST', body: JSON.stringify(body) }),
+    // Guided review (0.3.0): approve one change of this demo, or say something
+    // about it in the conversation it came from — SSB revises the change.
+    approve: (jobId) => call('/review', { method: 'POST', body: JSON.stringify({ jobId }) }),
+    discuss: (jobId, text) => call('/chat', { method: 'POST', body: JSON.stringify({ text, context: { about: jobId } }) }),
   };
 }
 
 /** The tour a phone plays: every actor's steps, each actor introduced by who to be. */
-export function tourOf(demo) {
+// 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.
+export function tourOf(demo, { here = false } = {}) {
   const out = [];
   for (const [actorIndex, a] of (demo?.actors || []).entries()) {
     const steps = a.tour?.steps || [];
     if (!steps.length) continue;
-    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 });
+    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 });
   }
   return out;

package/src/core.js

@@ -7,6 +7,11 @@
 // raw text node.
 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.3.0';
+
 export const HOST = 5;
 export const TEXT = 6;
 
@@ -103,9 +108,9 @@ export function phoneSteps(steps) {
 }
 
 /** The demo this bundle carries (EXPO_PUBLIC_SSB_DEMO_*), or null when it carries none. */
-export function demoConfig({ id, token, api } = {}) {
+export function demoConfig({ id, token, api, here } = {}) {
   if (!id || !token || !api) return null;
-  return { id: String(id), token: String(token), api: String(api).replace(/\/+$/, '') };
+  return { id: String(id), token: String(token), api: String(api).replace(/\/+$/, ''), ...(here ? { here: true } : {}) };
 }
 
 // The card's box, inside the band between the insets. With no element and no
@@ -118,3 +123,38 @@ export function cardBox(place, at, screen, insets, card) {
   const box = bubbleBox(place, el, band, { w: card.w, h: card.h });
   return { left: box.left, top: box.top + insets.top };
 }
+
+// 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
+// the overlay hands them here. <DemoHost> plays a baked demo first, else this.
+let runtime = null;
+const listeners = new Set();
+/** Play this demo now ({ id, token, api }); null stops it. */
+export function playDemo(demo) {
+  runtime = demo ? demoConfig(demo) : null;
+  for (const fn of listeners) fn(runtime);
+  return !!runtime || !demo;
+}
+export const currentDemo = () => runtime;
+export function onDemo(fn) { listeners.add(fn); return () => listeners.delete(fn); }
+
+// GUIDED REVIEW ON A PHONE (0.3.0, docs/GUIDED-REVIEW.md "On a phone"): the
+// tour's last card lists the demo's CHANGES — each `job:<id>` feature, once,
+// in the order the tour met them — to approve, or to discuss with SSB. A
+// demo of no jobs (a feature demo) has nothing to review and just finishes.
+export function reviewChangesOf(demo) {
+  const out = [];
+  const seen = new Set();
+  for (const a of demo?.actors || []) {
+    for (const sec of a.sections || []) {
+      for (const f of sec.features || []) {
+        const m = /^job:(.+)$/.exec(String(f?.featureId || ''));
+        if (!m || seen.has(m[1])) continue;
+        seen.add(m[1]);
+        out.push({ jobId: m[1], title: String(f.title || 'This change') });
+      }
+    }
+  }
+  return out;
+}