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

package/index.d.ts

@@ -30,7 +30,11 @@ 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 }[];
 /** 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;
+export function releaseOf(demo: unknown): { jobId: string; label: string; note: string; reviews: ReleaseReviews } | null;
+/** A release's review requests (0.11.0), read for the demo's person. */
+export type ReleaseReviewRequest = { to: string; by: string; status: 'pending' | 'approved' | 'discussed' | 'withdrawn'; at?: string; note?: string; decisionNote?: string; revisedAt?: string; release?: boolean };
+export type ReleaseReviews = { mode: 'off' | 'optional' | 'required'; requests: ReleaseReviewRequest[]; mine: ReleaseReviewRequest | null; waiting: string[]; candidates: string[]; canAsk: boolean; mustAsk: boolean; last: boolean };
+export function releaseReviewsOf(demo: unknown): ReleaseReviews;
 
 /**
  * React Navigation (an app without expo-router): a path is the chain of route

package/index.js

@@ -1,3 +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 { demoConfig, findTarget, handlerFor, phoneSteps, scalePoint, playDemo, currentDemo, onDemo, reviewChangesOf, releaseOf, releaseReviewsOf, 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.9.0",
+  "version": "0.11.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

@@ -15,7 +15,7 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Linking, Pressable, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions } from 'react-native';
 import { pageName } from './page-name.js';
-import { OVERLAY_ID, cardBox, currentDemo, demoConfig, findTarget, handlerFor, onDemo, phoneSteps, playDemo, releaseOf, reviewChangesOf, scalePoint, rescueNote, screenCandidates, stepTitle, targetOfKey } from './core.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 { demoApi, tourOf } from './api.js';
 import { signInFirst, openInApp } from './signin.js';
 import { runEvent, fillStep } from './events.js';
@@ -76,6 +76,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 [intro, setIntro] = useState(null);       // the first screen: who asked, what, signed in as (introOf)
   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)
@@ -86,7 +87,7 @@ function Player({ config, router, insets, onClose, children }) {
   useEffect(() => {
     let live = true;
     api.load()
-      .then((d) => { if (live) { setSteps(phoneSteps(tourOf(d, { here: !!config.here })).concat()); setChanges(reviewChangesOf(d)); setRelease(releaseOf(d)); } })
+      .then((d) => { if (live) { 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]);
@@ -221,6 +222,12 @@ function Player({ config, router, insets, onClose, 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 (intro && !tucked && !done) {
+      return h(Card, {
+        at: null, screen, insets, card, setCard, 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));
@@ -294,11 +301,66 @@ function Review({ api, changes, release, screen, insets, onBack, onDone, onHide
     api.discuss(id, text).then(() => set(id, { state: 'sent' })).catch((e) => set(id, { state: 'discussing', error: e.message }));
   };
   const left = release ? 0 : changes.filter((c) => !['approved', 'sent'].includes(rows[c.jobId]?.state)).length;
+  // REVIEW REQUESTS (0.11.0, docs/REVIEW-REQUESTS.md): asked to review it, the
+  // person answers here — Approve, or Discuss with a note, which holds the
+  // release until it is revised; otherwise they may approve and ask someone
+  // else first. `rq.state`: idle | picking | asking | discussing | sending | done.
+  const rv = release?.reviews || null;
+  const [rq, setRq] = useState({ state: 'idle', picked: [], note: '', error: null, said: '' });
+  const rqSet = (patch) => setRq((r) => ({ ...r, ...patch }));
+  const answer = (decision) => {
+    rqSet({ state: 'sending', error: null });
+    api.answerReview(decision, decision === 'discuss' ? rq.note.trim() : '')
+      .then((r) => rqSet({ state: 'done', said: decision === 'discuss' ? 'Sent — it waits for the revision and your approval.' : r?.released ? 'Approved — it is releasing now.' : r?.waiting ? `Approved. ${r.waiting}` : 'Approved.' }))
+      .catch((e) => rqSet({ state: decision === 'discuss' ? 'discussing' : 'idle', error: e.message }));
+  };
+  const askFor = () => {
+    if (!rq.picked.length) return;
+    rqSet({ state: 'sending', error: null });
+    api.approveAndAsk(rq.picked, rq.note.trim())
+      .then(() => rqSet({ state: 'done', said: `Approved — it goes live once ${rq.picked.join(', ')} ${rq.picked.length === 1 ? 'approves' : 'approve'}.` }))
+      .catch((e) => rqSet({ state: 'picking', error: e.message }));
+  };
+  const toggle = (e) => rqSet({ picked: rq.picked.includes(e) ? rq.picked.filter((x) => x !== e) : [...rq.picked, e] });
+  const reviewsBlock = !rv ? null : rq.state === 'done' ? h(Text, { style: s.changeState, testID: 'ssb-review-request-done' }, rq.said)
+    : rv.mine ? h(View, { style: s.change, testID: 'ssb-review-mine' },
+      h(Text, { style: s.changeTitle }, `${rv.mine.by} asked you to review this release.`),
+      rv.mine.note ? h(Text, { style: s.body }, `“${rv.mine.note}”`) : null,
+      rv.mine.status === 'discussed' && rv.mine.revisedAt ? h(Text, { style: s.body }, 'It was revised since you asked for changes.') : null,
+      rq.state === 'discussing' || (rq.state === 'sending' && rq.note) ? h(View, null,
+        h(TextInput, { style: s.input, value: rq.note, onChangeText: (note) => rqSet({ note }), placeholder: 'What should change before it goes live?', placeholderTextColor: '#8E8E93', multiline: true, autoFocus: true, accessibilityLabel: 'What should change before it goes live', testID: 'ssb-review-discuss-note' }),
+        h(View, { style: s.actions }, button('Cancel', () => rqSet({ state: 'idle', note: '' })), button(rq.state === 'sending' ? 'Sending…' : 'Send', rq.note.trim() && rq.state !== 'sending' ? () => answer('discuss') : () => {}, true))) : null)
+    : rv.waiting.length ? h(Text, { style: s.body, testID: 'ssb-review-waiting' }, `Waiting on ${rv.waiting.join(', ')}'s review before it goes live.`)
+    : rq.state === 'picking' || (rq.state === 'sending' && rq.picked.length) ? h(View, { style: s.change, testID: 'ssb-review-ask' },
+      h(Text, { style: s.changeTitle }, 'Request a review from…'),
+      ...rv.candidates.map((e) => h(Pressable, { key: e, onPress: () => toggle(e), accessibilityRole: 'checkbox', accessibilityState: { checked: rq.picked.includes(e) }, accessibilityLabel: e, style: s.pick },
+        h(Text, { style: s.body }, `${rq.picked.includes(e) ? '☑' : '☐'} ${e}`))),
+      h(TextInput, { style: s.input, value: rq.note, onChangeText: (note) => rqSet({ note }), placeholder: 'A note for them (optional)', placeholderTextColor: '#8E8E93', multiline: true, accessibilityLabel: 'A note for the reviewer' }),
+      h(View, { style: s.actions }, button('Cancel', () => rqSet({ state: 'idle', picked: [] })), button(rq.state === 'sending' ? 'Asking…' : 'Approve & ask', rq.picked.length && rq.state !== 'sending' ? askFor : () => {}, true)))
+    : rv.mustAsk ? h(Text, { style: s.body }, 'This project needs a review before every release — request one.') : null;
+  // What the foot's main button does on a release.
+  // What the foot's buttons are on a release, beside Hide (flat: one row).
+  const releaseMain = !release || rel.state === 'released' ? []
+    : rq.state === 'done' ? [button(left ? `Done (${left} undecided)` : 'Done', onDone, true)]
+    : rv?.mine ? (rq.state === 'discussing' ? [] : [
+        button('💬 Discuss', () => rqSet({ state: 'discussing' })),
+        button(rq.state === 'sending' ? 'Approving…' : rv.last ? release.label : 'Approve', rq.state === 'sending' ? () => {} : () => answer('approve'), true)])
+    : rv?.waiting.length ? [button('Done', onDone, true)]
+    : rq.state === 'picking' ? []
+    : [
+        rv?.canAsk ? button('Request a review', () => rqSet({ state: 'picking' }), !!rv?.mustAsk) : null,
+        rv?.mustAsk ? null : button(rel.state === 'releasing' ? 'Approving…' : release.label, rel.state === 'releasing' ? () => {} : doRelease, true),
+      ].filter(Boolean);
+  // The card's lead line, for where the release stands.
+  const lead = !release ? 'Approve what looks right. Anything that should be different, say so — SSB revises it.'
+    : rv?.mine ? 'Approve it, or say what should change — the release waits for your answer.'
+    : rv?.waiting.length ? 'It goes out once the review is in. Anything that should be different, say so — SSB revises it.'
+    : rv?.mustAsk ? 'This project needs a review before it goes out. Anything that should be different, say so — SSB revises it.'
+    : `Happy with it? ${release.label} sends them out together. Anything that should be different, say so — SSB revises it.`;
   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 }, release ? (changes.length === 1 ? 'The next release: 1 change' : `The next release: ${changes.length} changes`)
       : changes.length === 1 ? 'Review the change' : `Review ${changes.length} changes`),
-    h(Text, { style: s.body }, release ? `Happy with it? ${release.label} sends them out together. Anything that should be different, say so — SSB revises it.`
-      : 'Approve what looks right. Anything that should be different, say so — SSB revises it.'),
+    h(Text, { style: s.body }, lead),
     h(ScrollView, { style: s.changes, keyboardShouldPersistTaps: 'handled' }, ...changes.map((c) => {
       const r = rows[c.jobId] || {};
       const state = r.state || 'idle';
@@ -311,18 +373,20 @@ function Review({ api, changes, release, screen, insets, onBack, onDone, onHide
           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 },
+        state === 'idle' && !rv?.mine ? h(View, { style: s.actions },
           button('💬 Discuss', () => set(c.jobId, { state: 'discussing' })),
           release ? null : button('✓ Approve', () => approve(c.jobId), true)) : null);
     })),
+    reviewsBlock,
+    rq.error ? h(Text, { style: s.error }, rq.error) : null,
     release && rel.state === 'released' ? h(Text, { style: s.changeState, testID: 'ssb-release-done' }, 'Approved — it goes out in 5 minutes. Undo it on the release page in SimonSays if you need to.') : null,
     release && rel.error ? h(Text, { style: s.error }, rel.error) : null,
     h(View, { style: [s.actions, s.reviewFoot] },
       button('Hide', onHide),
       onBack ? button('Back', onBack) : null,
-      release && rel.state !== 'released'
-        ? button(rel.state === 'releasing' ? 'Approving…' : release.label, rel.state === 'releasing' ? () => {} : doRelease, true)
-        : button(left ? `Done (${left} undecided)` : 'Done', onDone, !left)));
+      ...(release && rel.state !== 'released'
+        ? releaseMain
+        : [button(left ? `Done (${left} undecided)` : 'Done', onDone, !left)])));
 }
 
 const button = (label, onPress, primary = false) => h(Pressable, {
@@ -366,6 +430,7 @@ const s = StyleSheet.create({
   review: { width: 360 },
   changes: { flexGrow: 0 },
   reviewFoot: { marginTop: 16 },
+  pick: { flexDirection: 'row', paddingVertical: 6 },
   change: { marginTop: 14, paddingTop: 12, borderTopWidth: StyleSheet.hairlineWidth, borderTopColor: '#3A3A3C' },
   changeTitle: { color: '#FFFFFF', fontSize: 15, fontWeight: '600' },
   changeState: { color: '#AEAEB2', fontSize: 13, marginTop: 4 },

package/src/api.js

@@ -23,6 +23,11 @@ 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: '{}' }),
+    // REVIEW REQUESTS (0.11.0, docs/REVIEW-REQUESTS.md): approve and ask others
+    // to review it first (the last approval releases it); or, asked yourself,
+    // answer — approve, or discuss with a note, which holds it until revised.
+    approveAndAsk: (to, note) => call('/approve', { method: 'POST', body: JSON.stringify({ requestReview: { to, ...(note ? { note } : {}), release: true } }) }),
+    answerReview: (decision, note) => call('/review-requests/decide', { method: 'POST', body: JSON.stringify({ decision, ...(note ? { note } : {}) }) }),
     // 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.

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.9.0';
+export const PLAYER_VERSION = '0.11.0';
 
 export const HOST = 5;
 export const TEXT = 6;
@@ -217,5 +217,57 @@ export function reviewChangesOf(demo) {
 export function releaseOf(demo) {
   const sm = demo?.sessionMerge;
   if (!sm || typeof sm.jobId !== 'string' || !sm.jobId) return null;
-  return { jobId: sm.jobId, label: String(sm.label || 'Approve & release'), note: String(sm.note || '') };
+  return { jobId: sm.jobId, label: String(sm.label || 'Approve & release'), note: String(sm.note || ''), reviews: releaseReviewsOf(demo) };
+}
+
+// REVIEW REQUESTS ON A RELEASE (0.11.0, docs/REVIEW-REQUESTS.md): the demo's
+// `sessionMerge.reviews` (functions/review-requests.mjs releaseReviewsForDemo),
+// read for the person the demo was made for (`createdBy`). Pure.
+//   mine      the request addressed to them that is still theirs to answer, or null
+//   waiting   others whose review it still waits on
+//   canAsk    they may request a review (the setting is not off, someone to ask)
+//   mustAsk   the project requires a review and none is approved: no release without one
+//   last      their approval would be the last one, and a release was asked for
+export function releaseReviewsOf(demo) {
+  const rv = demo?.sessionMerge?.reviews;
+  const me = String(demo?.createdBy || '').trim().toLowerCase();
+  const requests = Array.isArray(rv?.requests) ? rv.requests.filter((r) => r && typeof r.to === 'string') : [];
+  const open = requests.filter((r) => r.status === 'pending' || r.status === 'discussed');
+  const mine = open.find((r) => r.to === me) || null;
+  const waiting = open.filter((r) => r.to !== me).map((r) => r.to);
+  const candidates = (Array.isArray(rv?.candidates) ? rv.candidates : []).filter((e) => typeof e === 'string' && e !== me && !open.some((r) => r.to === e));
+  const mode = rv?.mode === 'off' || rv?.mode === 'required' ? rv.mode : 'optional';
+  return {
+    mode, requests, mine, waiting, candidates,
+    canAsk: mode !== 'off' && candidates.length > 0,
+    mustAsk: mode === 'required' && !requests.some((r) => r.status === 'approved') && !open.length,
+    last: !!mine && waiting.length === 0 && requests.some((r) => r.release),
+  };
+}
+
+// THE FIRST SCREEN OF A REVIEW (0.10.0, Michael 2026-11-03): a very brief
+// outline before anything plays — who asked for it, what they asked for, and
+// who the review signs in as — then a button to start. Pure.
+//   → { requestedBy: [string], asks: [{ title, asked }], as: [string] } | null
+const firstSentence = (t) => { const x = String(t || '').replace(/\s+/g, ' ').trim(); const m = /^(.{20,160}?[.!?])(\s|$)/.exec(x); return (m ? m[1] : x.slice(0, 140) + (x.length > 140 ? '…' : '')); };
+export function introOf(demo) {
+  const asks = [], by = new Set(), as = [];
+  for (const a of demo?.actors || []) {
+    if (a?.label && !as.includes(a.label)) as.push(String(a.label));
+    for (const sec of a.sections || []) for (const f of sec.features || []) {
+      if (f?.requestedBy) by.add(String(f.requestedBy).trim());
+      if (!asks.some((x) => x.title === f.title)) asks.push({ title: String(f.title || 'This change'), ...(f.tryIt?.steps ? { asked: firstSentence(f.tryIt.steps) } : {}) });
+    }
+  }
+  return asks.length || as.length ? { requestedBy: [...by], asks, as } : null;
+}
+export function introBody(intro) {
+  if (!intro) return '';
+  const lines = [];
+  if (intro.requestedBy.length) lines.push(`Requested by ${intro.requestedBy.join(', ')}`);
+  const shown = intro.asks.slice(0, 3);
+  for (const a of shown) lines.push(`• ${a.title}`);
+  if (intro.asks.length > shown.length) lines.push(`…and ${intro.asks.length - shown.length} more`);
+  if (intro.as.length) lines.push(`Signed in as ${intro.as.join(', then ')}`);
+  return lines.join('\n');
 }