@simon-says-build/ssb-overlay 0.1.0 → 0.5.1

package/index.d.ts

@@ -33,6 +33,12 @@ export function SsbHost(props: {
     addNotificationResponseReceivedListener(fn: (r: unknown) => void): { remove(): void };
     getLastNotificationResponseAsync?(): Promise<unknown>;
   };
+  /**
+   * 🎙 Talk: SSB by voice, which can draft and start jobs. The app's own LiveKit client:
+   * `{ Room }` from livekit-client, and @livekit/react-native's AudioSession start/stop.
+   * Without it there is no Talk button.
+   */
+  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 };
   children?: ReactNode;

package/index.js

@@ -1,2 +1,2 @@
 export { SsbHost } from './src/SsbHost.js';
-export { overlayConfig, inAppApi, markOf, sendBody, ssbLinkOf } from './src/core.js';
+export { overlayConfig, inAppApi, drawingMark, sendBody, ssbLinkOf } from './src/core.js';

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,32 @@
 {
   "name": "@simon-says-build/ssb-overlay",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "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/", "README.md"],
+  "bin": {
+    "ssb-overlay": "install/cli.mjs"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "assets/",
+    "install/",
+    "README.md"
+  ],
   "peerDependencies": {
     "react": ">=18",
     "react-native": ">=0.76"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "license": "UNLICENSED"
 }