@simon-says-build/demo-player 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @simon-says-build/demo-player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The mobile half of SimonSays demos (docs/MOBILE-DEMO.md): a job's preview, opened in the app's dev client, walks the viewer through the change.
+
+```tsx
+import { router } from "expo-router";
+import { DemoHost } from "@simon-says-build/demo-player";
+
+<DemoHost
+  router={router}
+  demo={{
+    id: process.env.EXPO_PUBLIC_SSB_DEMO_ID,
+    token: process.env.EXPO_PUBLIC_SSB_DEMO_TOKEN,
+    api: process.env.EXPO_PUBLIC_SSB_API,
+  }}
+>
+  {/* the app */}
+</DemoHost>
+```
+
+Pass the `process.env.EXPO_PUBLIC_*` reads in the app's own code. Expo inlines them where the app references them, so the values only exist in a bundle a demo preview served.
+
+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.
+
+`npm test` runs the pure half.

package/index.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+/** The demo this bundle carries: pass the three EXPO_PUBLIC_SSB_DEMO_* values. Any missing = no demo. */
+export type DemoBundle = { id?: string; token?: string; api?: string };
+
+/**
+ * Wrap the app's root. Renders `children` unchanged unless `demo` is complete,
+ * so production and ordinary dev builds are unaffected.
+ * `router` (expo-router's) opens a step's in-app path; anything else goes to Linking.
+ */
+export function DemoHost(props: {
+  demo?: DemoBundle;
+  router?: { push: (path: string) => void };
+  /** Keep the card off the status bar (top) and tab bar + home indicator (bottom). Default {top: 60, bottom: 100}. */
+  insets?: { top?: number; bottom?: number };
+  children?: ReactNode;
+}): ReactNode;

package/index.js

@@ -0,0 +1,2 @@
+export { DemoHost } from './src/DemoHost.js';
+export { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint } from './src/core.js';

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@simon-says-build/demo-player",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": ["index.js", "index.d.ts", "src/", "README.md"],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.76"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "license": "UNLICENSED"
+}

package/src/DemoHost.js

@@ -0,0 +1,186 @@
+// <DemoHost>: the mobile demo player (docs/MOBILE-DEMO.md).
+//
+// Renders its children and nothing else unless the bundle carries a demo
+// (EXPO_PUBLIC_SSB_DEMO_ID / _TOKEN / _API, which only a preview Metro started
+// 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.
+//
+// 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 { demoApi, tourOf } from './api.js';
+
+const h = React.createElement;
+const FIND_FOR_MS = 8000;      // a step's element may appear after a navigation settles
+const TRACK_EVERY_MS = 400;    // follow scrolling and layout while a step is shown
+
+// React keeps the fiber on the host instance (Fabric: __internalInstanceHandle).
+const fiberOf = (instance) => instance?.__internalInstanceHandle ?? instance?._internalInstanceHandle ?? null;
+
+let publicInstanceOf = (fiber) => fiber?.stateNode?.canonical?.publicInstance ?? null;
+try {
+  // The renderer's own accessor creates the public instance when React has not yet.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const impl = require('react-native/Libraries/ReactNative/RendererImplementation');
+  if (typeof impl.getPublicInstanceFromInternalInstanceHandle === 'function') {
+    const fallback = publicInstanceOf;
+    publicInstanceOf = (fiber) => {
+      try { return impl.getPublicInstanceFromInternalInstanceHandle(fiber) ?? fallback(fiber); } catch { return fallback(fiber); }
+    };
+  }
+} catch { /* an older renderer: the fallback above */ }
+
+const measure = (fiber) => new Promise((resolve) => {
+  const inst = publicInstanceOf(fiber);
+  if (!inst?.measureInWindow) return resolve(null);
+  inst.measureInWindow((x, y, width, height) => resolve(width || height ? { left: x, top: y, width, height, right: x + width, bottom: y + height } : null));
+});
+
+// Where the card must not go: the status bar above, a tab bar and the home
+// indicator below. An app passes its real insets (useSafeAreaInsets plus its
+// tab bar); these defaults fit a notched iPhone with a tab bar.
+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]);
+  if (!config) return children ?? null;
+  return h(Player, { config, router, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
+}
+
+function Player({ config, router, insets, children }) {
+  const rootRef = useRef(null);
+  const screen = useWindowDimensions();
+  const api = useMemo(() => demoApi(config), [config]);
+  const [steps, setSteps] = useState(null);
+  const [error, setError] = useState(null);
+  const [index, setIndex] = useState(0);
+  const [rect, setRect] = useState(null);
+  const [found, setFound] = useState(null);       // the step's host fiber, for "Do it for me"
+  const [card, setCard] = useState({ w: 320, h: 140 });
+  const [tucked, setTucked] = useState(false);
+  const [done, setDone] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    api.load()
+      .then((d) => { if (live) setSteps(phoneSteps(tourOf(d)).concat()); })
+      .catch((e) => { if (live) setError(e.message); });
+    return () => { live = false; };
+  }, [api]);
+
+  const step = steps?.[index] ?? null;
+
+  // Find and follow the step's element.
+  useEffect(() => {
+    setRect(null); setFound(null);
+    if (!step || done) return undefined;
+    const target = step.target;
+    if (!target) return undefined;
+    if (target.point && !target.testId && !target.label && !target.text) {
+      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 });
+      return undefined;
+    }
+    let live = true;
+    const started = Date.now();
+    const tick = async () => {
+      const f = findTarget(fiberOf(rootRef.current), target);
+      const r = f ? await measure(f) : null;
+      if (!live) return;
+      setFound(f);
+      setRect(r);
+      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 });
+      }
+    };
+    tick();
+    const t = setInterval(tick, TRACK_EVERY_MS);
+    return () => { live = false; clearInterval(t); };
+  }, [step, done, screen.width, screen.height]);
+
+  const finish = useCallback(() => {
+    setDone(true);
+    api.progress({ status: 'done' }).catch(() => {});
+  }, [api]);
+
+  const next = useCallback(() => {
+    if (!steps) return;
+    if (step?.kind === 'goto' && step.path) {
+      if (step.path.startsWith('/') && router?.push) router.push(step.path);
+      else Linking.openURL(step.path).catch(() => {});
+    }
+    if (index + 1 >= steps.length) finish();
+    else setIndex(index + 1);
+  }, [steps, step, index, router, finish]);
+
+  const doIt = useCallback(() => {
+    if (!step || !found) return;
+    if (step.kind === 'click') handlerFor(found, 'onPress')?.({ nativeEvent: {}, preventDefault() {}, stopPropagation() {} });
+    if (step.kind === 'fill' && step.value != null) handlerFor(found, 'onChangeText')?.(step.value);
+    next();
+  }, [step, found, next]);
+
+  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 (tucked || done) {
+      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}`));
+    }
+    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,
+      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: `${index + 1} of ${steps.length}`, body: step.caption,
+        actions: [
+          { label: 'Hide', onPress: () => setTucked(true) },
+          index > 0 ? { 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),
+      }));
+  })();
+
+  return h(View, { ref: rootRef, style: s.root, collapsable: false },
+    children,
+    h(View, { pointerEvents: 'box-none', style: StyleSheet.absoluteFill }, overlay));
+}
+
+function Card({ at, place, screen, insets, card, setCard, title, body, actions = [] }) {
+  const box = cardBox(place, at, screen, insets, card);
+  return h(View, {
+    style: [s.card, { left: box.left, top: box.top, maxWidth: screen.width - 32 }],
+    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(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,
+    style: ({ pressed }) => [s.button, a.primary && s.primary, pressed && s.pressed],
+  }, h(Text, { style: [s.buttonText, a.primary && s.primaryText] }, a.label)))) : null);
+}
+
+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 } },
+  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 },
+  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' },
+  primary: { backgroundColor: '#FFFFFF' },
+  pressed: { opacity: 0.7 },
+  buttonText: { color: '#FFFFFF', fontSize: 14, fontWeight: '600' },
+  primaryText: { color: '#1C1C1E' },
+  pill: { position: 'absolute', right: 16, paddingVertical: 8, paddingHorizontal: 14, borderRadius: 18, backgroundColor: '#1C1C1E' },
+  pillText: { color: '#FFFFFF', fontSize: 13, fontWeight: '600' },
+});

package/src/api.js

@@ -0,0 +1,29 @@
+// 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) {
+  const call = async (path, init = {}) => {
+    const res = await fetchImpl(`${api}/api/demo/${encodeURIComponent(id)}${path}`, {
+      ...init,
+      headers: { 'content-type': 'application/json', 'x-demo-token': token, ...(init.headers || {}) },
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(json.error || `demo API ${res.status}`);
+    return json;
+  };
+  return {
+    load: () => call(''),
+    progress: (body) => call('/progress', { method: 'POST', body: JSON.stringify(body) }),
+  };
+}
+
+/** The tour a phone plays: every actor's steps, each actor introduced by who to be. */
+export function tourOf(demo) {
+  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 });
+    for (const s of steps) out.push({ ...s, actorIndex });
+  }
+  return out;
+}

package/src/core.js

@@ -0,0 +1,120 @@
+// The player's pure half: no React Native here, so node --test runs it.
+//
+// A step's element is found in React's own tree (fibers: child / sibling /
+// return, props on memoizedProps), the way docs/MOBILE-DEMO.md describes, so
+// no app component has to be wrapped. React's tags for the two host kinds a
+// phone renders: a host component (View, Pressable's view, TextInput…) and a
+// raw text node.
+import { bubbleBox } from './step-place.js';
+
+export const HOST = 5;
+export const TEXT = 6;
+
+// The screen the iOS drive records on (drivers/ios.sh refuses points off it).
+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']);
+
+const lower = (s) => String(s ?? '').trim().toLowerCase();
+const hiddenHost = (f) => {
+  const style = f.memoizedProps?.style;
+  const flat = Array.isArray(style) ? Object.assign({}, ...style.flat(Infinity).filter(Boolean)) : style;
+  return flat?.display === 'none';
+};
+
+function* walk(root) {
+  // Iterative depth-first, skipping a display:none host and everything in it.
+  const stack = root ? [root] : [];
+  while (stack.length) {
+    const f = stack.pop();
+    if (f.tag === HOST && hiddenHost(f)) continue;
+    yield f;
+    const kids = [];
+    for (let c = f.child; c; c = c.sibling) kids.push(c);
+    for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+  }
+}
+
+const nearestHost = (f) => {
+  for (let p = f; p; p = p.return) if (p.tag === HOST) return p;
+  return null;
+};
+
+const textOf = (f) => (typeof f.memoizedProps === 'string' ? f.memoizedProps : String(f.memoizedProps?.text ?? ''));
+
+/**
+ * The host fiber a step's target names, or null. Preference follows the
+ * contract: testID, then accessibility label (or aria-label), then visible
+ * text (the host that holds it). A `point` is not resolved here: the player
+ * draws it where it is.
+ */
+export function findTarget(root, target) {
+  if (!target) return null;
+  if (target.testId) {
+    for (const f of walk(root)) if (f.tag === HOST && f.memoizedProps?.testID === target.testId) return f;
+  }
+  if (target.label) {
+    const want = lower(target.label);
+    for (const f of walk(root)) {
+      if (f.tag !== HOST) continue;
+      const p = f.memoizedProps || {};
+      if (lower(p.accessibilityLabel) === want || lower(p['aria-label']) === want) return f;
+    }
+    // The iOS drive records the text it SEARCHED by, a case-insensitive
+    // substring of the label (drivers/ios-find.py), so an exact miss falls
+    // back to the first label that contains it.
+    for (const f of walk(root)) {
+      if (f.tag !== HOST) continue;
+      const p = f.memoizedProps || {};
+      if (lower(p.accessibilityLabel).includes(want) || lower(p['aria-label']).includes(want)) return f;
+    }
+  }
+  if (target.text) {
+    const want = lower(target.text);
+    // The host that holds the text (on a phone, its Text view): the ring sits
+    // on the words themselves, and "Do it for me" finds the press above them.
+    for (const f of walk(root)) if (f.tag === TEXT && lower(textOf(f)).includes(want)) return nearestHost(f.return);
+  }
+  return null;
+}
+
+/** 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) {
+    const h = p.memoizedProps?.[name];
+    if (typeof h === 'function') return h;
+  }
+  return null;
+}
+
+/** A recorded point, scaled from the recording screen to `screen`. */
+export function scalePoint(point, screen, from = RECORDED_SCREEN) {
+  return {
+    x: Math.round((point.x * screen.width) / from.width),
+    y: Math.round((point.y * screen.height) / from.height),
+  };
+}
+
+/** The steps of a tour a phone can play, in order. A step with no caption says nothing and is dropped. */
+export function phoneSteps(steps) {
+  return (steps || []).filter((s) => s && PHONE_KINDS.has(s.kind) && String(s.caption || '').trim());
+}
+
+/** The demo this bundle carries (EXPO_PUBLIC_SSB_DEMO_*), or null when it carries none. */
+export function demoConfig({ id, token, api } = {}) {
+  if (!id || !token || !api) return null;
+  return { id: String(id), token: String(token), api: String(api).replace(/\/+$/, '') };
+}
+
+// The card's box, inside the band between the insets. With no element and no
+// placement it sits in the middle of that band: a card pinned to an edge
+// covers the tab bar or a sheet's content, and the viewer may need either.
+export function cardBox(place, at, screen, insets, card) {
+  const band = { w: screen.width, h: Math.max(card.h + 32, screen.height - insets.top - insets.bottom) };
+  if (!at && !place) return { left: Math.max(16, (screen.width - card.w) / 2), top: insets.top + Math.max(16, (band.h - card.h) / 2) };
+  const el = at ? { ...at, top: at.top - insets.top, bottom: at.bottom - insets.top } : null;
+  const box = bubbleBox(place, el, band, { w: card.w, h: card.h });
+  return { left: box.left, top: box.top + insets.top };
+}

package/src/step-place.js

@@ -0,0 +1,55 @@
+// A COPY of schemas/step-place.mjs, so the package stands alone in an app.
+// test/parity.test.mjs fails if the two drift: change schemas/step-place.mjs
+// and copy it here.
+// WHERE A DEMO STEP'S WORDS SIT ON THE SCREEN (docs/LIVE-DEMO.md "Placement",
+// 2026-10-14). The tour's caption is a bubble beside the element it is about —
+// and a bubble can cover exactly what the step is showing. The rehearsal agent
+// SEES the screen when it records a step, so it says where the words go:
+//
+//   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)
+//
+// 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;
+
+/** A placement, cleaned; null when there is none (or it is not one). */
+export function cleanPlace(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const pinTo = String(raw.pinTo || '').toLowerCase();
+  if (!PIN_TO.includes(pinTo)) return null;
+  const n = Number(raw.offset);
+  const offset = Number.isFinite(n) ? Math.max(0, Math.min(MAX_OFFSET, Math.round(n))) : undefined;
+  return { pinTo, ...(offset !== undefined ? { offset } : {}) };
+}
+
+/**
+ * The bubble's box for a placement. Pure geometry the player and its test share.
+ *   el      the element's rect {left, top, right, bottom, width, height}, or null
+ *   view    {w, h} — the screen, less the card
+ *   bubble  {w, h} — the bubble's size
+ * → {left, top} in px, kept on screen.
+ */
+export function bubbleBox(place, el, view, bubble) {
+  const p = cleanPlace(place);
+  const clampX = (x) => Math.max(16, Math.min(x, view.w - bubble.w - 16));
+  const clampY = (y) => Math.max(16, Math.min(y, view.h - bubble.h - 16));
+  if (p?.pinTo === 'top' || p?.pinTo === 'bottom' || !el) {
+    const off = p?.offset ?? (el ? 24 : 48);
+    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 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) };
+  if (pin === 'left') return { left: clampX(el.left - off - bubble.w), top: clampY(el.top) };
+  return { left: clampX(el.right + off), top: clampY(el.top) };
+}
+
+/** Does the bubble sit away from its element (an edge pin), so an arrow should point? */
+export const pointsAt = (place) => ['top', 'bottom'].includes(cleanPlace(place)?.pinTo);