@simon-says-build/ssb-overlay 0.4.0 → 0.6.0

package/index.d.ts

@@ -41,5 +41,11 @@ export function SsbHost(props: {
   voice?: { Room: new (opts?: object) => any; startAudio?: () => Promise<void> | void; stopAudio?: () => Promise<void> | void };
   /** Keep the button off the home indicator / tab bar. Default {top: 60, bottom: 40}. */
   insets?: { top?: number; bottom?: number };
+  /**
+   * Which build this is: the origin the app's JS bundle was loaded from (a
+   * SimonSays preview's tunnel). Read off the bundle when omitted; Ready lists
+   * only what this build holds, and ▶ Demo plays it here.
+   */
+  bundle?: string;
   children?: ReactNode;
 }): ReactNode;

package/install/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// npx @simon-says-build/ssb-overlay install <appDir> --app-id <id> [--no-install] [--json]
+// (install/install.mjs; docs/IN-APP-SSB.md "Installing it in an app")
+import path from 'node:path';
+import { install } from './install.mjs';
+
+const args = process.argv.slice(2);
+const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : undefined; };
+if (args[0] !== 'install') {
+  console.error('usage: ssb-overlay install <appDir> --app-id <ssb app id> [--no-install] [--json]');
+  process.exit(64);
+}
+const dir = path.resolve(args[1] && !args[1].startsWith('--') ? args[1] : '.');
+try {
+  const r = install(dir, { appId: opt('--app-id'), npmInstall: !args.includes('--no-install') });
+  if (args.includes('--json')) console.log(JSON.stringify(r, null, 2));
+  else {
+    for (const d of r.done) console.log(`✓ ${d}`);
+    for (const t of r.todo) console.log(`! ${t}`);
+    console.log(`SSB settings for this app (inAppSsb): ${JSON.stringify(r.settings)}`);
+  }
+  process.exit(0);
+} catch (e) {
+  console.error(`ssb-overlay install: ${e.message}`);
+  process.exit(1);
+}

package/install/install.mjs

@@ -0,0 +1,343 @@
+// INSTALL SSB IN AN APP (docs/IN-APP-SSB.md "Installing it in an app",
+// 2026-10-20, the product owner: "we just need SSB to reliably be able to
+// install the package").
+//
+//   npx @simon-says-build/ssb-overlay install <appDir> --app-id <ssb app id> [--no-install] [--json]
+//
+// Reads the app's facts off its repo, adds the packages, writes ONE component
+// (`SsbOverlay`) wired to what the app already has, wraps the root layout in
+// it, and says what SSB should record about the app (`inAppSsb`). Anything it
+// cannot do safely it does NOT guess: it says so by name (`todo[]`), so the
+// job that ran it — or a person — finishes that part. Never throws on a fact
+// it cannot find; exits non-zero only when it changed nothing it was asked to.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
+const json = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
+const exists = (p) => fs.existsSync(p);
+
+/** The packages an install adds (react-native-view-shot through `expo install`, so its version fits the SDK). */
+export const PACKAGES = ['@simon-says-build/ssb-overlay', '@simon-says-build/demo-player', 'react-native-view-shot'];
+
+// ---- what the app is ----------------------------------------------------------
+/** Every fact the install decides by, read off the repo. Pure apart from reading files. */
+export function detect(dir) {
+  const pkg = json(path.join(dir, 'package.json')) || {};
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const has = (n) => Object.prototype.hasOwnProperty.call(deps, n);
+  const ts = exists(path.join(dir, 'tsconfig.json'));
+  const layout = ['app/_layout.tsx', 'app/_layout.jsx', 'app/_layout.js', 'src/app/_layout.tsx', 'src/app/_layout.js']
+    .map((p) => path.join(dir, p)).find(exists) || null;
+
+  // How people sign in: the app's own backend, which SSB checks their token against.
+  let auth = null, backend = null, firebaseProject = null, supabaseClient = null;
+  if (has('@react-native-firebase/auth')) auth = 'rn-firebase';
+  else if (has('firebase')) auth = 'firebase-js';
+  else if (has('@supabase/supabase-js')) auth = 'supabase';
+  if (auth === 'rn-firebase' || auth === 'firebase-js') {
+    firebaseProject = firebaseProjectOf(dir);
+    backend = firebaseProject ? `firebase:${firebaseProject}` : null;
+  }
+  if (auth === 'supabase') {
+    supabaseClient = supabaseClientOf(dir);
+    backend = 'process.env.EXPO_PUBLIC_SUPABASE_URL';
+  }
+  // The claim the app's own code marks its admins with (`claims.admin`, `admin?: boolean`).
+  const adminClaim = auth && auth !== 'supabase' && grepSource(dir, /\bclaims\??\.admin\b|\badmin\?\s*:\s*boolean/) ? 'admin' : null;
+
+  return {
+    dir, ts, layout,
+    expo: deps.expo || null,
+    router: has('expo-router'),
+    auth, backend, firebaseProject, supabaseClient, adminClaim,
+    voice: has('livekit-client') && has('@livekit/react-native'),
+    notifications: has('expo-notifications'),
+    asyncStorage: has('@react-native-async-storage/async-storage'),
+    constants: has('expo-constants'),
+    // The app already plays SSB's demos itself (Impulse wraps its root in <DemoHost>): keep its own.
+    demoHost: !!(layout && /<DemoHost[\s>]/.test(read(layout) || '')),
+    installed: PACKAGES.filter(has),
+    componentsDir: ['components', 'src/components'].map((p) => path.join(dir, p)).find(exists) || path.join(dir, 'components'),
+  };
+}
+
+export function firebaseProjectOf(dir) {
+  for (const p of ['GoogleService-Info.plist', 'ios/GoogleService-Info.plist']) {
+    const t = read(path.join(dir, p));
+    const m = t && /<key>PROJECT_ID<\/key>\s*<string>([^<]+)<\/string>/.exec(t);
+    if (m) return m[1].trim();
+  }
+  for (const p of ['google-services.json', 'android/app/google-services.json']) {
+    const j = json(path.join(dir, p));
+    if (j?.project_info?.project_id) return j.project_info.project_id;
+  }
+  return null;
+}
+
+/** The module that makes the app's Supabase client (`createClient(` … `export const supabase`), as an import path from `dir`. */
+export function supabaseClientOf(dir) {
+  for (const f of sourceFiles(dir)) {
+    const t = read(f) || '';
+    if (/createClient\s*\(/.test(t) && /export\s+(const|let)\s+supabase\b/.test(t)) return f;
+  }
+  return null;
+}
+
+function sourceFiles(dir) {
+  const out = [];
+  const walk = (d, depth) => {
+    if (depth > 6) return;
+    let es = [];
+    try { es = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of es) {
+      if (['node_modules', '.git', 'ios', 'android', '.expo', 'dist', 'build'].includes(e.name)) continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (/\.(tsx?|jsx?|mjs)$/.test(e.name)) out.push(p);
+    }
+  };
+  walk(dir, 0);
+  return out;
+}
+const grepSource = (dir, re) => sourceFiles(dir).some((f) => re.test(read(f) || ''));
+
+// ---- the component ------------------------------------------------------------
+/** The relative import of `to` from the folder of `from`, without extension. */
+export function importPath(from, to) {
+  let r = path.relative(path.dirname(from), to).replace(/\\/g, '/').replace(/\.(tsx?|jsx?|mjs)$/, '');
+  if (!r.startsWith('.')) r = `./${r}`;
+  return r;
+}
+
+/**
+ * `SsbOverlay`, written for THIS app: its backend and how its session is read,
+ * its LiveKit for 🎙 Talk, its expo-notifications for "ready to see", its
+ * storage. Returns { file, source }.
+ */
+export function component(facts, { appId }) {
+  const ext = facts.ts ? 'tsx' : 'js';
+  const file = path.join(facts.componentsDir, `SsbOverlay.${ext}`);
+  const T = facts.ts;
+  const lines = [];
+  const imp = [];
+  imp.push(`import { SsbHost } from "@simon-says-build/ssb-overlay";`);
+  if (!facts.demoHost) imp.push(`import { DemoHost } from "@simon-says-build/demo-player";`);
+  imp.push(facts.demoHost ? `import { usePathname } from "expo-router";` : `import { router, usePathname } from "expo-router";`);
+  imp.push(`import ${T ? 'React, { type ReactNode, useEffect, useState }' : 'React, { useEffect, useState }'} from "react";`);
+  imp.push(`import { captureScreen } from "react-native-view-shot";`);
+  if (facts.asyncStorage) imp.push(`import AsyncStorage from "@react-native-async-storage/async-storage";`);
+  if (facts.notifications) imp.push(`import * as Notifications from "expo-notifications";`);
+  if (facts.notifications && facts.constants) imp.push(`import Constants from "expo-constants";`);
+  if (facts.voice) { imp.push(`import { AudioSession } from "@livekit/react-native";`); imp.push(`import { Room } from "livekit-client";`); }
+
+  // How the overlay reads the session — the app's own sign-in, never a new one.
+  let session;
+  if (facts.auth === 'rn-firebase') {
+    imp.push(`import { getAuth, onAuthStateChanged } from "@react-native-firebase/auth";`);
+    session = [
+      `// The signed-in user, from the app's own Firebase sign-in.`,
+      `function useSession()${T ? ': { uid: string | null; token: () => Promise<string | null> }' : ''} {`,
+      `  const [uid, setUid] = useState${T ? '<string | null>' : ''}(getAuth().currentUser?.uid ?? null);`,
+      `  useEffect(() => onAuthStateChanged(getAuth(), (u) => setUid(u?.uid ?? null)), []);`,
+      `  return { uid, token: async () => (getAuth().currentUser ? getAuth().currentUser${T ? '!' : ''}.getIdToken() : null) };`,
+      `}`,
+    ];
+  } else if (facts.auth === 'firebase-js') {
+    imp.push(`import { getAuth, onAuthStateChanged } from "firebase/auth";`);
+    session = [
+      `// The signed-in user, from the app's own Firebase sign-in.`,
+      `function useSession()${T ? ': { uid: string | null; token: () => Promise<string | null> }' : ''} {`,
+      `  const [uid, setUid] = useState${T ? '<string | null>' : ''}(getAuth().currentUser?.uid ?? null);`,
+      `  useEffect(() => onAuthStateChanged(getAuth(), (u) => setUid(u?.uid ?? null)), []);`,
+      `  return { uid, token: async () => (getAuth().currentUser ? getAuth().currentUser${T ? '!' : ''}.getIdToken() : null) };`,
+      `}`,
+    ];
+  } else if (facts.auth === 'supabase' && facts.supabaseClient) {
+    imp.push(`import { supabase } from "${importPath(file, facts.supabaseClient)}";`);
+    session = [
+      `// The signed-in user, from the app's own Supabase sign-in.`,
+      `function useSession()${T ? ': { uid: string | null; token: () => Promise<string | null> }' : ''} {`,
+      `  const [uid, setUid] = useState${T ? '<string | null>' : ''}(null);`,
+      `  useEffect(() => {`,
+      `    if (!supabase) return undefined;`,
+      `    supabase.auth.getSession().then(({ data }) => setUid(data.session?.user.id ?? null));`,
+      `    const { data } = supabase.auth.onAuthStateChange((_e, s) => setUid(s?.user.id ?? null));`,
+      `    return () => data.subscription.unsubscribe();`,
+      `  }, []);`,
+      `  return { uid, token: async () => (supabase ? (await supabase.auth.getSession()).data.session?.access_token ?? null : null) };`,
+      `}`,
+    ];
+  } else {
+    session = [
+      `// TODO(ssb): the app's sign-in could not be read off the repo. Return the`,
+      `// signed-in user's id and their session token from the app's own auth.`,
+      `function useSession()${T ? ': { uid: string | null; token: () => Promise<string | null> }' : ''} {`,
+      `  return { uid: null, token: async () => null };`,
+      `}`,
+    ];
+  }
+
+  const backend = facts.backend?.startsWith('process.env.') ? facts.backend : JSON.stringify(facts.backend || '');
+  lines.push(
+    `// SimonSays inside the app (written by \`npx @simon-says-build/ssb-overlay install\`;`,
+    `// docs: https://github.com/simon-says-studio/simon-says-build/blob/main/docs/IN-APP-SSB.md).`,
+    `//`,
+    `// <SsbHost> draws SSB's button ONLY for a login SimonSays lets in — checked by`,
+    `// SimonSays against this app's own backend with the user's own session token;`,
+    ...(facts.demoHost ? [`// everyone else sees nothing. The app's own demo player plays SSB's demos.`] : [
+      `// everyone else sees nothing. <DemoHost> plays a change's demo, and renders the`,
+      `// app unchanged in any build that does not carry one.`,
+    ]),
+    ...imp, ``,
+    `// This app in SimonSays, and where its people sign in.`,
+    `const SSB_APP_ID = ${JSON.stringify(appId)};`,
+    `const SSB_BACKEND = ${backend};`, ``,
+  );
+  if (facts.voice) {
+    lines.push(
+      `// 🎙 Talk, on the app's own LiveKit. If the app manages its audio session itself`,
+      `// (calls, recording), start and stop it here through that code instead.`,
+      `const SSB_VOICE = {`,
+      `  Room,`,
+      `  startAudio: () => AudioSession.startAudioSession(),`,
+      `  stopAudio: () => AudioSession.stopAudioSession(),`,
+      `};`, ``,
+    );
+  }
+  if (facts.notifications) {
+    lines.push(
+      `// The device, for "it's done, tap to see it" — asked only once SimonSays lets the`,
+      `// login in, and only when the app already has notification permission.`,
+      `async function pushToken() {`,
+      `  ${facts.constants ? 'const projectId = Constants.expoConfig?.extra?.eas?.projectId;' : 'const projectId = undefined;'}`,
+      `  if (!projectId) return null;`,
+      `  const { status } = await Notifications.getPermissionsAsync();`,
+      `  if (status !== "granted") return null;`,
+      `  return (await Notifications.getExpoPushTokenAsync({ projectId })).data;`,
+      `}`, ``,
+    );
+  }
+  if (!facts.demoHost) lines.push(
+    `// The demo player opens a step's in-app path by plain string.`,
+    `const DEMO_ROUTER = { push: (path${T ? ': string' : ''}) => router.push(path${T ? ' as never' : ''}) };`, ``,
+  );
+  lines.push(
+    ...session, ``,
+    `export function SsbOverlay({ children }${T ? ': { children: ReactNode }' : ''}) {`,
+    `  const session = useSession();`,
+    `  const route = usePathname();`,
+    `  return (`,
+    `    <SsbHost`,
+    `      appId={SSB_APP_ID}`,
+    `      backend={SSB_BACKEND}`,
+    `      getToken={session.token}`,
+    `      sessionKey={session.uid}`,
+    `      route={route}`,
+    `      capture={() => captureScreen({ format: "jpg", quality: 0.6, result: "data-uri" })}`,
+    ...(facts.asyncStorage ? [`      storage={AsyncStorage}`] : []),
+    ...(facts.notifications ? [`      pushToken={pushToken}`, `      notifications={Notifications}`] : []),
+    ...(facts.voice ? [`      voice={SSB_VOICE}`] : []),
+    `    >`,
+    ...(facts.demoHost ? [`      {children}`] : [
+      `      <DemoHost`,
+      `        router={DEMO_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,`,
+      `        }}`,
+      `      >`,
+      `        {children}`,
+      `      </DemoHost>`,
+    ]),
+    `    </SsbHost>`,
+    `  );`,
+    `}`, ``,
+  );
+  return { file, source: lines.join('\n') };
+}
+
+// ---- the root layout ------------------------------------------------------------
+/**
+ * The layout with its default export's returned JSX wrapped in <SsbOverlay>,
+ * or { error } when its shape is not the one this can wrap safely: an
+ * `export default function` whose body returns `( … )`.
+ */
+export function wrapLayout(source, importFrom) {
+  if (/<SsbOverlay[\s>]/.test(source)) return { source, already: true };
+  const fn = /export\s+default\s+function\s+[A-Za-z0-9_]*\s*\([^)]*\)\s*(:\s*[^{]+)?\{/.exec(source);
+  if (!fn) return { error: 'the root layout does not `export default function` — wrap its returned JSX in <SsbOverlay> by hand' };
+  // The function body, by brace depth (strings and comments are rare enough in a layout's braces to accept).
+  const bodyStart = fn.index + fn[0].length;
+  let depth = 1, i = bodyStart;
+  for (; i < source.length && depth > 0; i++) {
+    if (source[i] === '{') depth++;
+    else if (source[i] === '}') depth--;
+  }
+  const bodyEnd = i - 1;
+  // The LAST `return (` at the body's own depth: the layout's main render.
+  let d = 0, ret = -1;
+  for (let j = bodyStart; j < bodyEnd; j++) {
+    const c = source[j];
+    if (c === '{') d++;
+    else if (c === '}') d--;
+    else if (d === 0 && source.startsWith('return', j) && /^return\s*\(/.test(source.slice(j, j + 20))) ret = j;
+  }
+  if (ret < 0) return { error: 'the root layout does not `return ( … )` at its top level — wrap its returned JSX in <SsbOverlay> by hand' };
+  const open = source.indexOf('(', ret);
+  let p = 1, k = open + 1;
+  for (; k < bodyEnd && p > 0; k++) {
+    if (source[k] === '(') p++;
+    else if (source[k] === ')') p--;
+  }
+  const close = k - 1;
+  const inner = source.slice(open + 1, close);
+  if (!inner.trim().startsWith('<')) return { error: 'the root layout returns something other than JSX — wrap it in <SsbOverlay> by hand' };
+  const wrapped = `${source.slice(0, open + 1)}\n    <SsbOverlay>${inner.replace(/\s+$/, '')}\n    </SsbOverlay>\n  ${source.slice(close)}`;
+  // The import, after the last import line.
+  const imports = [...wrapped.matchAll(/^import[\s\S]*?from\s+["'][^"']+["'];?[ \t]*$/gm)];
+  const at = imports.length ? imports.at(-1).index + imports.at(-1)[0].length : 0;
+  const line = `\nimport { SsbOverlay } from "${importFrom}";`;
+  return { source: wrapped.slice(0, at) + line + wrapped.slice(at) };
+}
+
+// ---- what SSB records about the app ------------------------------------------------
+export function settingsFor(facts) {
+  const s = {};
+  if (facts.firebaseProject) s.firebaseProjects = [facts.firebaseProject];
+  if (facts.adminClaim) s.adminClaims = [facts.adminClaim];
+  return s;
+}
+
+// ---- the install ------------------------------------------------------------------
+export function install(dir, { appId, npmInstall = true, run = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: 'inherit' }) } = {}) {
+  if (!appId) throw new Error('--app-id is required (the app\'s id in SimonSays)');
+  const facts = detect(dir);
+  const done = [], todo = [];
+  if (!facts.expo) todo.push('this is not an Expo app (no `expo` dependency) — the overlay is for Expo apps');
+  if (!facts.router) todo.push('no expo-router: pass the current route to <SsbHost route> from the app\'s own navigation');
+  if (!facts.backend) todo.push(facts.auth ? `could not find the ${facts.auth === 'supabase' ? 'Supabase URL' : 'Firebase project id (GoogleService-Info.plist / google-services.json)'} — set SSB_BACKEND by hand` : 'could not tell how the app signs in — fill in useSession() and SSB_BACKEND by hand');
+  if (facts.auth === 'supabase' && !facts.supabaseClient) todo.push('could not find the module exporting the Supabase client — fill in useSession() by hand');
+
+  if (npmInstall) {
+    run('npx', ['--yes', 'expo', 'install', ...PACKAGES], dir);
+    done.push(`added ${PACKAGES.join(', ')}`);
+  }
+
+  const { file, source } = component(facts, { appId });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, source);
+  done.push(`wrote ${path.relative(dir, file)}`);
+
+  if (facts.layout) {
+    const r = wrapLayout(fs.readFileSync(facts.layout, 'utf8'), importPath(facts.layout, file));
+    if (r.error) todo.push(`${path.relative(dir, facts.layout)}: ${r.error}`);
+    else if (r.already) done.push(`${path.relative(dir, facts.layout)} already wraps <SsbOverlay>`);
+    else { fs.writeFileSync(facts.layout, r.source); done.push(`wrapped ${path.relative(dir, facts.layout)} in <SsbOverlay>`); }
+  } else todo.push('no root layout (app/_layout) — wrap the app\'s root component in <SsbOverlay> by hand');
+
+  if (facts.voice) todo.push('🎙 Talk uses @livekit/react-native\'s AudioSession; if the app manages its own audio session (calls, recording), route SSB_VOICE.startAudio/stopAudio through that code');
+  return { facts: { ...facts, dir: undefined }, settings: settingsFor(facts), done, todo };
+}

package/package.json

@@ -1,17 +1,33 @@
 {
   "name": "@simon-says-build/ssb-overlay",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The SSB button inside a native app SimonSays controls: screenshot the screen, mark it, and ask SSB for a change. Renders nothing for anyone SSB does not let in.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simon-says-studio/simon-says-build.git",
+    "directory": "packages/ssb-overlay"
+  },
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
-  "files": ["index.js", "index.d.ts", "src/", "assets/", "README.md"],
+  "bin": {
+    "ssb-overlay": "install/cli.mjs"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "assets/",
+    "install/",
+    "README.md"
+  ],
   "peerDependencies": {
+    "@simon-says-build/demo-player": ">=0.1.0",
     "react": ">=18",
     "react-native": ">=0.76"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "license": "UNLICENSED"
 }

package/src/SsbHost.js

@@ -21,11 +21,14 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   ActivityIndicator, Image, Keyboard, KeyboardAvoidingView, Linking, PanResponder, Platform, Pressable,
-  ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions,
+  NativeModules, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions,
 } from 'react-native';
+// The app's demo player (a peer): ▶ Demo hands it the demo to play in this
+// build. An older player has no playDemo, and the button is not offered.
+import { playDemo } from '@simon-says-build/demo-player';
 import {
   FAB, addPoint, clampFab, demoBanner, fabHome, isDrag, describeHost, draftsOf, fieldTop, inAppApi, namedHosts, newReply, offerOf,
-  STATE_WORD, boxItem, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
+  STATE_WORD, boxItem, bundleOriginOf, elsewhereLine, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
 } from './core.js';
 
 const h = React.createElement;
@@ -65,11 +68,16 @@ const frames = (n = 2) => new Promise((resolve) => {
   step(n);
 });
 
-export function SsbHost({ appId, backend, api, getToken, sessionKey, route, capture, storage, pushToken, notifications, voice, insets, children }) {
+// Where this app's JS was loaded from: a preview's tunnel, or a file.
+const scriptURL = () => {
+  try { const sc = NativeModules.SourceCode; return sc?.getConstants?.()?.scriptURL ?? sc?.scriptURL ?? ''; } catch { return ''; }
+};
+
+export function SsbHost({ appId, backend, api, getToken, sessionKey, route, capture, storage, pushToken, notifications, voice, insets, bundle, children }) {
   const config = useMemo(() => overlayConfig({ appId, backend, api }), [appId, backend, api]);
   useSsbLinks(notifications);
   if (!config || typeof getToken !== 'function') return children ?? null;
-  return h(Host, { config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
+  return h(Host, { config, getToken, sessionKey, route, capture, storage, pushToken, voice, bundle, insets: { ...DEFAULT_INSETS, ...(insets || {}) } }, children);
 }
 
 // A tapped "Ready to see" notification (functions/in-app-notify.mjs) opens
@@ -85,7 +93,12 @@ function useSsbLinks(notifications) {
   }, [notifications]);
 }
 
-function Host({ config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets, children }) {
+function Host({ config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets, bundle, children }) {
+  // WHICH BUILD THIS IS (docs/IN-APP-SSB.md "Ready is this build"): Ready is
+  // only what this bundle holds. `bundle` overrides (the harness); else the
+  // origin the JS came from.
+  const here = useMemo(() => (bundle !== undefined ? String(bundle || '') : bundleOriginOf(scriptURL())), [bundle]);
+  const [elsewhere, setElsewhere] = useState([]);
   const screen = useWindowDimensions();
   const tokenRef = useRef(getToken);
   tokenRef.current = getToken;
@@ -181,7 +194,18 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
   const open = mode !== 'idle';
   useEffect(() => { if (open) load(); }, [open, chatId]);
   // The top of the panel: the app's work, asked when it opens and while it stays open.
-  const loadWork = useCallback(async () => { try { setWork((await ssb.work())?.inFlight || []); } catch { /* the last list stands */ } }, [ssb]);
+  const loadWork = useCallback(async () => {
+    try { const r = await ssb.work(here); setWork(r?.inFlight || []); setElsewhere(r?.readyElsewhere || []); } catch { /* the last list stands */ }
+  }, [ssb, here]);
+  // ▶ Demo: one demo of everything Ready in this build, played by this build.
+  const startDemo = useCallback(async () => {
+    setBusy(true); setError(null);
+    try {
+      const r = await ssb.demo(here);
+      if (!playDemo({ id: r.demoId, token: r.token, api: config.api, here: true })) throw new Error('the demo could not start');
+      Keyboard.dismiss(); setMode('idle');
+    } catch (e) { setError(e.message); } finally { setBusy(false); }
+  }, [ssb, here, config.api]);
   useEffect(() => {
     if (mode !== 'sheet' || !gate) return undefined;
     loadWork();
@@ -217,7 +241,10 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
 
   // A demo opens IN the app (or the dev client): SSB steps aside first, or the
   // full-screen panel would sit on top of what it opened.
-  const openLink = useCallback((url) => { if (!url) return; Keyboard.dismiss(); setMode('idle'); Linking.openURL(url).catch(() => {}); }, []);
+  const openLink = useCallback((url, fallback) => {
+    if (!url) return; Keyboard.dismiss(); setMode('idle');
+    Linking.openURL(url).catch(() => (fallback ? Linking.openURL(fallback).catch(() => {}) : null));
+  }, []);
   const openRef = useRef(openSheet);
   openRef.current = openSheet;
   const close = useCallback(() => {
@@ -442,7 +469,8 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
           h(Pressable, { testID: 'ssb-draw-send', onPress: sendDrawing, disabled: !note.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.sendRound, (!note.trim() || busy) && s.disabled] }, h(Text, { style: s.sendRoundText }, '→'))) : null);
     }
     if (mode === 'sheet') return h(Panel, {
-      gate, chat, work, screen, insets, draft, setDraft, busy, error,
+      gate, chat, work, screen, insets, draft, setDraft, busy, error, elsewhere,
+      onDemo: typeof playDemo === 'function' ? startDemo : null,
       onSend: sendDraft, onDraw: () => { Keyboard.dismiss(); setMode('drawing'); }, onClose: close,
       canTalk: !!voice?.Room, talk, onTalk: startTalk, onEndTalk: endTalk, onMute: toggleMute,
       onNew: () => { rememberChat(null); setChat(null); }, onDecide: decide, onStartAll: startAll, onOpenLink: openLink,
@@ -455,14 +483,16 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
     h(View, { ref: chromeRef, collapsable: false, pointerEvents: 'box-none', style: StyleSheet.absoluteFill }, chrome));
 }
 
-function Panel({ gate, chat, work, screen, insets, draft, setDraft, busy, error, onSend, onDraw, onClose, onNew, onDecide, onStartAll, onOpenLink, canTalk, talk, onTalk, onEndTalk, onMute }) {
+function Panel({ gate, chat, work, elsewhere, onDemo, screen, insets, draft, setDraft, busy, error, onSend, onDraw, onClose, onNew, onDecide, onStartAll, onOpenLink, canTalk, talk, onTalk, onEndTalk, onMute }) {
   const scroll = useRef(null);
   const [open, setOpen] = useState(null);            // the draft whose detail is shown
   const { flying, waiting, sent } = workView({ inFlight: work, chat });
   const offer = offerOf(chat);
   const banner = demoBanner(chat);
   const msgs = chat?.messages || [];
-  const hasWork = flying.length || waiting.length || sent.length || banner;
+  const ready = flying.filter((x) => x.state === 'ready');
+  const away = elsewhereLine(elsewhere);
+  const hasWork = flying.length || waiting.length || sent.length || banner || away;
   const showMe = (x) => (x.state === 'ready' && banner?.url ? banner.url : null);
   return h(View, { style: [s.panel, { paddingTop: insets.top }], testID: 'ssb-panel' },
     h(KeyboardAvoidingView, { behavior: Platform.OS === 'ios' ? 'padding' : undefined, style: { flex: 1 } },
@@ -473,23 +503,28 @@ function Panel({ gate, chat, work, screen, insets, draft, setDraft, busy, error,
           h(Text, { style: s.sub, numberOfLines: 1 }, `${gate.app?.name || 'this app'} · as ${gate.person?.label || 'you'}`)),
         chat ? h(Pressable, { onPress: onNew, accessibilityRole: 'button', accessibilityLabel: 'New conversation', style: s.quiet }, h(Text, { style: s.quietText }, 'New')) : null,
         h(Pressable, { onPress: onClose, accessibilityRole: 'button', accessibilityLabel: 'Close SSB', style: s.iconBtn }, h(Text, { style: s.iconText }, '✕'))),
-      talk ? h(View, { style: s.talkBar, testID: 'ssb-talk-bar' },
-        h(View, { style: [s.talkDot, talk.status !== 'live' && { backgroundColor: MUTED }] }),
-        h(Text, { style: s.talkText }, talkLine(talk)),
-        h(Pressable, { onPress: onMute, accessibilityRole: 'button', accessibilityLabel: talk.muted ? 'Unmute' : 'Mute', style: s.talkBtn }, h(Text, { style: s.talkBtnText }, talk.muted ? 'Unmute' : 'Mute')),
-        h(Pressable, { onPress: onEndTalk, accessibilityRole: 'button', accessibilityLabel: 'End the talk', style: [s.talkBtn, s.talkEnd] }, h(Text, { style: [s.talkBtnText, { color: '#fff' }] }, 'End'))) : null,
       // THE WORK, at the top: in flight, then drafts to start, then what this chat started.
       hasWork ? h(ScrollView, { style: [s.work, { maxHeight: Math.round(screen.height * 0.42) }], testID: 'ssb-work', keyboardShouldPersistTaps: 'handled' },
         banner ? h(Pressable, {
           testID: 'ssb-demo', disabled: !banner.url, onPress: () => onOpenLink(banner.url),
           accessibilityRole: banner.url ? 'button' : 'text', style: [s.demo, banner.url && s.demoReady],
         }, h(Text, { style: [s.demoText, banner.url && { color: '#fff' }] }, banner.text), banner.url ? h(Text, { style: s.demoGo }, '▶ See it') : null) : null,
-        flying.length ? h(Text, { style: s.section, testID: 'ssb-section-flight' }, 'In flight') : null,
-        ...flying.map((x) => h(View, { key: `f${x.id}`, style: s.workRow, testID: `ssb-flight-${x.id}` },
-          h(Text, { style: s.workTitle, numberOfLines: 2 }, x.title),
+        flying.length ? h(View, { style: s.sectionRow },
+          h(Text, { style: [s.section, { flex: 1 }], testID: 'ssb-section-flight' }, 'In flight'),
+          ready.length && onDemo ? h(Pressable, { testID: 'ssb-demo-ready', onPress: onDemo, disabled: busy, accessibilityRole: 'button', accessibilityLabel: `Demo what is ready in this build (${ready.length})`, style: [s.primary, s.small, busy && s.disabled] },
+            h(Text, { style: s.primaryText }, `▶ Demo (${ready.length})`)) : null) : null,
+        // A row opens its job in the SimonSays app, the console when that app
+        // is not on the phone (functions/in-app.mjs jobLinksFor) — for those
+        // who can open it there; anyone else's rows stay plain.
+        ...flying.map((x) => h(x.links ? Pressable : View, {
+          key: `f${x.id}`, style: s.workRow, testID: `ssb-flight-${x.id}`,
+          ...(x.links ? { onPress: () => onOpenLink(x.links.app, x.links.web), accessibilityRole: 'link', accessibilityLabel: `Open in SimonSays: ${x.title}` } : {}),
+        },
+          h(Text, { style: s.workTitle, numberOfLines: 2 }, x.links ? `${x.title} ›` : x.title),
           showMe(x)
             ? h(Pressable, { onPress: () => onOpenLink(showMe(x)), accessibilityRole: 'button', accessibilityLabel: `Show me: ${x.title}`, style: [s.primary, s.small] }, h(Text, { style: s.primaryText }, '▶ Show me'))
             : h(Text, { style: [s.state, s[`state_${x.state}`]] }, STATE_WORD[x.state] || x.state))),
+        away ? h(Text, { style: [s.draftBody, { paddingHorizontal: 16, paddingVertical: 8 }], testID: 'ssb-ready-elsewhere' }, away) : null,
         waiting.length ? h(View, { style: s.sectionRow },
           h(Text, { style: [s.section, { flex: 1 }] }, 'Drafts'),
           waiting.length > 1 ? h(Pressable, { testID: 'ssb-start-all', onPress: onStartAll, disabled: busy, accessibilityRole: 'button', accessibilityLabel: 'Start all', style: [s.primary, s.small, busy && s.disabled] }, h(Text, { style: s.primaryText }, `Start all (${waiting.length})`)) : null) : null,
@@ -513,17 +548,24 @@ function Panel({ gate, chat, work, screen, insets, draft, setDraft, busy, error,
           m.id === offer ? h(Pressable, { onPress: onStartAll, disabled: busy, style: [s.primary, { marginTop: 8, alignSelf: 'flex-start' }] }, h(Text, { style: s.primaryText }, 'Confirm and start work')) : null)),
         chat?.thinking ? h(View, { style: [s.bubble, s.theirs, s.row] }, h(ActivityIndicator, { size: 'small', color: MUTED }), h(Text, { style: [s.theirsText, { marginLeft: 8 }] }, 'SSB is thinking…')) : null),
       error ? h(Text, { style: s.error }, error) : null,
+      // THE COMPOSER, or while talking the voice controls in its place: voice is
+      // the other way to say it, so Hang up sits where Send does.
       h(View, { style: [s.composer, { paddingBottom: Math.max(12, insets.bottom > 60 ? 16 : insets.bottom) }] },
-        h(TextInput, {
+        talk ? h(View, { style: s.talkBar, testID: 'ssb-talk-bar' },
+          h(View, { style: [s.talkDot, talk.status !== 'live' && { backgroundColor: MUTED }] }),
+          h(Text, { style: s.talkText }, talkLine(talk))) : h(TextInput, {
           testID: 'ssb-composer', value: draft, onChangeText: setDraft, multiline: true, placeholder: 'Ask SSB, or say what should change…',
           placeholderTextColor: MUTED, keyboardAppearance: 'dark', style: s.input,
         }),
         h(View, { style: s.row },
           h(Pressable, { testID: 'ssb-draw', onPress: onDraw, accessibilityRole: 'button', accessibilityLabel: 'Draw on the screen', style: s.chip }, h(Text, { style: s.chipText }, '✎ Draw')),
           canTalk && !talk ? h(Pressable, { testID: 'ssb-talk', onPress: onTalk, accessibilityRole: 'button', accessibilityLabel: 'Talk to SSB', style: s.chip }, h(Text, { style: s.chipText }, '🎙 Talk')) : null,
+          talk ? h(Pressable, { testID: 'ssb-mute', onPress: onMute, accessibilityRole: 'button', accessibilityLabel: talk.muted ? 'Unmute' : 'Mute', style: s.chip }, h(Text, { style: s.chipText }, talk.muted ? 'Unmute' : 'Mute')) : null,
           h(View, { style: { flex: 1 } }),
-          h(Pressable, { testID: 'ssb-send', onPress: onSend, disabled: !draft.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.primary, (!draft.trim() || busy) && s.disabled] },
-            busy ? h(ActivityIndicator, { size: 'small', color: '#fff' }) : h(Text, { style: s.primaryText }, 'Send'))))));
+          talk
+            ? h(Pressable, { testID: 'ssb-hangup', onPress: onEndTalk, accessibilityRole: 'button', accessibilityLabel: 'End the talk', style: [s.primary, s.hangup] }, h(Text, { style: s.primaryText }, 'Hang up'))
+            : h(Pressable, { testID: 'ssb-send', onPress: onSend, disabled: !draft.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.primary, (!draft.trim() || busy) && s.disabled] },
+              busy ? h(ActivityIndicator, { size: 'small', color: '#fff' }) : h(Text, { style: s.primaryText }, 'Send'))))));
 }
 
 const shadow = { shadowColor: '#000', shadowOpacity: 0.45, shadowRadius: 18, shadowOffset: { width: 0, height: 8 }, elevation: 12 };
@@ -560,12 +602,12 @@ const s = StyleSheet.create({
   headLogo: { width: 40, height: 40, borderRadius: 20 },
   title: { fontSize: 17, fontWeight: '800', color: TEXT, letterSpacing: 0.3 },
   sub: { fontSize: 12, color: MUTED, marginTop: 2 },
-  talkBar: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 8, backgroundColor: 'rgba(47,210,122,0.08)', borderBottomWidth: 1, borderBottomColor: LINE },
+  // While talking, in the composer's place.
+  talkBar: { minHeight: 44, flexDirection: 'row', alignItems: 'center', paddingHorizontal: 13, borderRadius: 14, borderWidth: 1, borderColor: 'rgba(47,210,122,0.45)', backgroundColor: 'rgba(47,210,122,0.08)' },
   talkDot: { width: 10, height: 10, borderRadius: 5, backgroundColor: GREEN, marginRight: 8, ...glow(GREEN, 6) },
-  talkText: { flex: 1, fontSize: 14, fontWeight: '600', color: TEXT },
-  talkBtn: { paddingVertical: 6, paddingHorizontal: 12, borderRadius: 10, borderWidth: 1, borderColor: LINE, backgroundColor: RAISED, marginLeft: 6 },
+  talkText: { flex: 1, fontSize: 15, fontWeight: '600', color: TEXT },
   talkEnd: { backgroundColor: RED, borderColor: RED },
-  talkBtnText: { fontSize: 13, fontWeight: '700', color: TEXT },
+  hangup: { backgroundColor: RED, ...glow(RED, 10) },
   // The work, at the top.
   work: { flexGrow: 0, borderBottomWidth: 1, borderBottomColor: LINE, backgroundColor: SURFACE },
   section: { fontSize: 11, fontWeight: '800', letterSpacing: 1.4, textTransform: 'uppercase', color: MUTED, paddingHorizontal: 16, paddingTop: 12, paddingBottom: 6 },

package/src/core.js

@@ -43,7 +43,10 @@ export function inAppApi(config, getToken, fetchImpl = globalThis.fetch) {
     decide: (chatId, proposalId, action, body) => post(`/chats/${encodeURIComponent(chatId)}/proposals/${encodeURIComponent(proposalId)}/${action}`, body),
     pushToken: (token, platform) => post('/push-token', { token, platform }),
     voice: (body) => post('/voice', body),
-    work: () => call('/work'),
+    // `bundle`: where this app's JS came from (a preview's tunnel), so SSB
+    // scopes Ready to this build; undefined = the whole list, as before.
+    work: (bundle) => call(bundle === undefined ? '/work' : `/work?bundle=${encodeURIComponent(bundle)}`),
+    demo: (bundle) => post('/demo', { bundle }),
   };
 }
 
@@ -308,3 +311,17 @@ export function workView({ inFlight = [], chat = null } = {}) {
   const { waiting, sent } = draftsOf(chat);
   return { flying, waiting, sent: sent.filter((p) => !p.jobId || !flyingIds.has(p.jobId)) };
 }
+
+// READY IS THIS BUILD (2026-10-20, docs/IN-APP-SSB.md): the origin the app's
+// JS bundle was loaded from — a preview's tunnel — or "" for a build that
+// loads from a file (a store or local build, which holds no SSB preview).
+export function bundleOriginOf(scriptURL) {
+  const m = /^(https?:\/\/[^/?#]+)/i.exec(String(scriptURL || ''));
+  return m ? m[1] : '';
+}
+// What the overlay says about Ready work this build does not hold.
+export function elsewhereLine(readyElsewhere = []) {
+  const n = (readyElsewhere || []).reduce((t, x) => t + (Number(x?.count) || 0), 0);
+  if (!n) return '';
+  return `${n === 1 ? '1 more change is' : `${n} more changes are`} ready in another build — open its preview to see ${n === 1 ? 'it' : 'them'}.`;
+}