@simon-says-build/ssb-overlay 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @simon-says-build/ssb-overlay
 
-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 SSB button inside a native app SimonSays controls (docs/IN-APP-SSB.md). A
+member of the app's organization, an SSB operator, or an allowed cast login
+(the super-admin by default) gets a small **SSB** button; it opens Tell SSB on
+the phone: the screen's picture, a mark on it, the conversation, SSB's drafts
+and **Start working**. Everyone else sees nothing.
+
+```tsx
+import { SsbHost } from "@simon-says-build/ssb-overlay";
+import { captureScreen } from "react-native-view-shot";
+
+<SsbHost
+  appId={Constants.expoConfig?.extra?.ssb?.appId}
+  backend={process.env.EXPO_PUBLIC_SUPABASE_URL}
+  getToken={async () => (await supabase.auth.getSession()).data.session?.access_token}
+  sessionKey={session?.user.id}
+  route={usePathname()}
+  capture={() => captureScreen({ format: "jpg", quality: 0.6, result: "data-uri" })}
+  storage={AsyncStorage}
+>
+  {/* the app */}
+</SsbHost>
+```
+
+Nothing secret goes in the bundle: the app's own session token is checked by
+SSB against the app's backend (functions/in-app.mjs).
+
+`npm test` runs the pure half.

package/index.d.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Wrap the app's root. Renders `children` unchanged unless SSB lets the
+ * signed-in login in (a member of the app's organization, an SSB operator, or
+ * an allowed cast login — the super-admin by default); then an SSB button
+ * floats bottom-right. docs/IN-APP-SSB.md.
+ */
+/** The link an SSB notification opens, or null: for an app that handles its own notification taps. */
+export function ssbLinkOf(response: unknown): string | null;
+
+export function SsbHost(props: {
+  /** The app's SSB id (app.json `extra.ssb.appId`). Missing = no overlay. */
+  appId?: string;
+  /** Where the app signs in: its Supabase URL, or `firebase:<projectId>`. Missing = no overlay. */
+  backend?: string;
+  /** SSB's origin. Default https://simonsays.build. */
+  api?: string;
+  /** The app's CURRENT session token (Supabase access token / Firebase ID token), or null when signed out. */
+  getToken: () => Promise<string | null | undefined>;
+  /** Anything that changes when the login does (the user id): SSB is asked again. */
+  sessionKey?: string | null;
+  /** The current route (expo-router's usePathname()). */
+  route?: string;
+  /** A picture of the screen as a JPEG/PNG data URL, e.g. react-native-view-shot's captureScreen({ result: 'data-uri' }). Without it, sends carry words and marks only. */
+  capture?: () => Promise<string>;
+  /** Remembers the conversation across launches (AsyncStorage fits). */
+  storage?: { getItem(k: string): Promise<string | null> | string | null; setItem(k: string, v: string): unknown; removeItem?(k: string): unknown };
+  /** This device's Expo push token (Notifications.getExpoPushTokenAsync), so SSB can say "it's done, tap to see it" in this app. */
+  pushToken?: () => Promise<string | null | undefined>;
+  /** The app's expo-notifications module: a tapped SSB notification then opens the demo's preview in the dev client. */
+  notifications?: {
+    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;
+}): ReactNode;

package/index.js

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

package/package.json

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

package/src/SsbHost.js

@@ -0,0 +1,615 @@
+// <SsbHost>: the SSB button inside a native app (docs/IN-APP-SSB.md).
+//
+// Renders its children and nothing else until SSB says the signed-in login
+// may use it (GET /api/in-app/me: a member of the app's organization, an SSB
+// operator, or a cast login on the app's allowed list, by default the
+// super-admin). Then SSB's logo floats on the screen (drag it anywhere).
+// Tapping it takes a picture of the screen as it is and opens SSB FULL SCREEN
+// (2026-10-20, the product owner: "abandon the idea of a partial overlaying
+// sheet … like a full-screen overlay, unless you're in draw / box mode, or
+// voice mode"): the WORK at the top — what is in flight on this app, this
+// chat's drafts to start — the way the extension's card has it, and the
+// conversation with SSB below (Tell SSB's, functions/annotate.mjs). Every send carries
+// the screen (2026-10-19, the product owner: "always send the screen, don't
+// make it an option"). **Draw** puts a pencil and a box on the live screen:
+// scribble on or box what should change (as much as it takes, Undo), say what,
+// send — the drawing is captured ON the screen, with the field and our chrome
+// hidden. (It was **Mark**, one pin or one box, until 0.2.0.) SSB replies on the thread and proposes jobs; the drafts bar
+// starts them. The same conversation is on the console.
+//
+// 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 {
+  ActivityIndicator, Image, Keyboard, KeyboardAvoidingView, Linking, PanResponder, Platform, Pressable,
+  ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions,
+} from 'react-native';
+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,
+} from './core.js';
+
+const h = React.createElement;
+// THE LOOK (2026-10-20, the product owner: "a futuristic look … dark,
+// matching the 'real-object' look of our logo"): the toy's black chassis, and
+// its four pads for meaning — blue to act, green for ready and talking,
+// yellow for a draft waiting on you, red to draw and to end. What is live glows.
+const BG = '#0b0d12', SURFACE = '#141821', RAISED = '#1b2030', LINE = '#232a3a';
+const TEXT = '#eef2fa', MUTED = '#8a93a8';
+const BLUE = '#3d7bff', GREEN = '#2fd27a', YELLOW = '#f6c544', RED = '#ff4d5a';
+const INK = BG;                                      // the drawing hint and the talk pill: the chassis
+const DEFAULT_INSETS = { top: 60, bottom: 40 };
+const INK_W = 4;               // the pencil's line, in points
+// The button IS SSB's logo, the round Simon toy (web/public/logo-192.png, 156px: 3x of 52pt).
+const LOGO = require('../assets/ssb-logo.png');
+
+// 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 {
+  // 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 } : null));
+});
+const frames = (n = 2) => new Promise((resolve) => {
+  const step = (k) => (k <= 0 ? resolve() : requestAnimationFrame(() => step(k - 1)));
+  step(n);
+});
+
+export function SsbHost({ appId, backend, api, getToken, sessionKey, route, capture, storage, pushToken, notifications, voice, insets, 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);
+}
+
+// A tapped "Ready to see" notification (functions/in-app-notify.mjs) opens
+// the demo's preview in the app's dev client. Heard whoever is signed in,
+// and on a cold start too: the tap may be what launched the app.
+function useSsbLinks(notifications) {
+  useEffect(() => {
+    if (!notifications?.addNotificationResponseReceivedListener) return undefined;
+    const open = (r) => { const url = ssbLinkOf(r); if (url) Linking.openURL(url).catch(() => {}); };
+    Promise.resolve(notifications.getLastNotificationResponseAsync?.()).then(open).catch(() => {});
+    const sub = notifications.addNotificationResponseReceivedListener(open);
+    return () => sub?.remove?.();
+  }, [notifications]);
+}
+
+function Host({ config, getToken, sessionKey, route, capture, storage, pushToken, voice, insets, children }) {
+  const screen = useWindowDimensions();
+  const tokenRef = useRef(getToken);
+  tokenRef.current = getToken;
+  const ssb = useMemo(() => inAppApi(config, () => tokenRef.current()), [config]);
+  const rootRef = useRef(null);
+  const screenRef = useRef(screen);
+  screenRef.current = screen;
+  const insetsRef = useRef(insets);
+  insetsRef.current = insets;
+  const chromeRef = useRef(null);
+  const storeKey = `ssb-overlay:chat:${config.appId}`;
+
+  const [gate, setGate] = useState(null);            // {show, person, app, canJob} once SSB has answered
+  const [mode, setMode] = useState('idle');          // idle | sheet | drawing | capturing
+  const [shot, setShot] = useState(null);            // the screen as it was when the button was tapped
+  const [items, setItems] = useState([]);            // what is drawn: strokes and boxes, in screen points (core.js)
+  const [live, setLive] = useState(null);            // the item under the finger
+  const liveRef = useRef(null);
+  const [tool, setTool] = useState('pencil');        // pencil | box
+  // 🎙 Talk: a LiveKit room with SSB's voice agent (the host's livekit-client Room).
+  const [talk, setTalk] = useState(null);            // null | { status: connecting | waiting | live, muted }
+  const roomRef = useRef(null);
+  const toolRef = useRef(tool);
+  toolRef.current = tool;
+  // The button goes wherever it is dragged (2026-10-19), remembered per app on this phone.
+  const fabKey = `ssb-overlay:fab:${config.appId}`;
+  const [fab, setFab] = useState(null);
+  const fabRef = useRef(null);
+  fabRef.current = fab;
+  const [note, setNote] = useState('');
+  const [draft, setDraft] = useState('');
+  const [chatId, setChatId] = useState(null);
+  const [chat, setChat] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const [work, setWork] = useState([]);              // the app's work in flight (GET /api/in-app/work)
+  const [seen, setSeen] = useState(null);
+  const [kbTop, setKbTop] = useState(screen.height);
+
+  // ---- the gate: ask once per login --------------------------------------
+  useEffect(() => {
+    let live = true;
+    setGate(null);
+    setMode('idle');
+    ssb.me().then((g) => {
+      if (!live) return;
+      setGate(g?.show ? g : null);
+      // This device, for "it's done, tap to see it" — only for someone SSB let in.
+      if (g?.show && pushToken) Promise.resolve(pushToken()).then((t) => (t ? ssb.pushToken(t, Platform.OS) : null)).catch(() => {});
+    }).catch(() => { if (live) setGate(null); });
+    return () => { live = false; };
+  }, [ssb, sessionKey]);
+
+  useEffect(() => {
+    if (!storage?.getItem) return;
+    Promise.resolve(storage.getItem(fabKey)).then((v) => { try { const p = JSON.parse(v); if (Number.isFinite(p?.x) && Number.isFinite(p?.y)) setFab(p); } catch { /* none kept */ } }).catch(() => {});
+  }, [fabKey]);
+  useEffect(() => {
+    if (!storage?.getItem) return;
+    Promise.resolve(storage.getItem(storeKey)).then((id) => { if (id) setChatId(id); }).catch(() => {});
+  }, [storeKey]);
+  const rememberChat = useCallback((id) => {
+    setChatId(id);
+    if (storage?.setItem) Promise.resolve(id ? storage.setItem(storeKey, id) : storage.removeItem?.(storeKey)).catch(() => {});
+  }, [storage, storeKey]);
+
+  useEffect(() => {
+    const show = Keyboard.addListener(Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow', (e) => setKbTop(e.endCoordinates.screenY));
+    const hide = Keyboard.addListener(Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide', () => setKbTop(screen.height));
+    return () => { show.remove(); hide.remove(); };
+  }, [screen.height]);
+
+  // A new screen makes the drawing and the picture stale (the extension's
+  // rule): the scribbles are dropped and their words move to the composer.
+  const lastRoute = useRef(route);
+  useEffect(() => {
+    if (lastRoute.current === route) return;
+    lastRoute.current = route;
+    setShot(null);
+    if (mode === 'drawing') {
+      if (note.trim()) setDraft((d) => (d ? `${d}\n${note}` : note));
+      setItems([]); setNote(''); setMode('sheet');
+    }
+  }, [route]);
+
+  // ---- the thread ----------------------------------------------------------
+  const load = useCallback(async () => {
+    if (!chatId) return;
+    try { setChat(await ssb.chat(chatId)); }
+    catch (e) { if (e.status === 404) { rememberChat(null); setChat(null); } }
+  }, [ssb, chatId, rememberChat]);
+
+  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]);
+  useEffect(() => {
+    if (mode !== 'sheet' || !gate) return undefined;
+    loadWork();
+    const t = setInterval(loadWork, 10000);
+    return () => clearInterval(t);
+  }, [mode, gate, loadWork]);
+  useEffect(() => {
+    if (!gate || !chatId) return undefined;
+    const every = talk ? 2000 : pollEvery({ open, thinking: !!chat?.thinking || chat?.demo?.status === 'preparing' });
+    if (!every) return undefined;
+    const t = setInterval(load, every);
+    return () => clearInterval(t);
+  }, [gate, chatId, open, chat?.thinking, load, !!talk]);
+
+  const lastReplyId = (c) => [...(c?.messages || [])].reverse().find((m) => m.role !== 'user' && !m.streaming)?.id ?? null;
+  const [seenDemo, setSeenDemo] = useState(null);
+  const unread = !open && chat && (newReply(chat, seen) || (chat.demo?.status === 'ready' && chat.demo.url !== seenDemo));
+
+  // ---- open, draw, send ----------------------------------------------------
+  const grab = useCallback(async () => {
+    if (!capture) return null;
+    await frames(2);
+    try { return await capture(); } catch { return null; }
+  }, [capture]);
+
+  const openSheet = useCallback(async () => {
+    setError(null);
+    setMode('capturing');
+    const pic = await grab();
+    setShot(pic);
+    setMode('sheet');
+  }, [grab]);
+
+  // 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 openRef = useRef(openSheet);
+  openRef.current = openSheet;
+  const close = useCallback(() => {
+    Keyboard.dismiss();
+    setSeen(lastReplyId(chat));
+    setSeenDemo(chat?.demo?.url ?? null);
+    setItems([]); setNote('');
+    setMode('idle');
+  }, [chat]);
+
+  const deliver = useCallback(async (body) => {
+    setBusy(true); setError(null);
+    try {
+      const r = await ssb.send(body);
+      rememberChat(r.chatId);
+      const c = await ssb.chat(r.chatId).catch(() => null);
+      if (c) setChat(c);
+      return true;
+    } catch (e) {
+      setError(e.message);
+      return false;
+    } finally { setBusy(false); }
+  }, [ssb, rememberChat]);
+
+  const sendDraft = useCallback(async () => {
+    const text = draft.trim();
+    if (!text || busy) return;
+    // Always the screen: the picture taken when the button was tapped.
+    const ok = await deliver(sendBody({ chatId, text, route, platform: Platform.OS, screen, screenshot: shot }));
+    if (ok) setDraft('');
+  }, [draft, busy, deliver, chatId, route, screen, shot]);
+
+  // What the app has under the scribbles, named the way the app names it.
+  const elementUnder = useCallback(async (pt) => {
+    if (!pt) return null;
+    try {
+      const hosts = namedHosts(fiberOf(rootRef.current), fiberOf(chromeRef.current));
+      const cands = await Promise.all(hosts.map(async (fiber) => ({ fiber, rect: await measure(fiber) })));
+      const hit = smallestAt(cands, pt);
+      return hit ? describeHost(hit.fiber) : null;
+    } catch { return null; }
+  }, []);
+
+  const sendDrawing = useCallback(async () => {
+    const text = note.trim();
+    if (!text || busy || !items.length) return;
+    Keyboard.dismiss();
+    const element = await elementUnder(drawingPoint(items));
+    setMode('capturing');                            // only the drawing stays on screen
+    const pic = await grab();
+    setMode('sheet');
+    const ok = await deliver(sendBody({ chatId, text, route, platform: Platform.OS, screen, mark: drawingMark(items, screen), element, screenshot: pic || shot }));
+    if (ok) { setItems([]); setNote(''); }
+    else setDraft((d) => d || text);
+  }, [note, busy, items, elementUnder, grab, deliver, chatId, route, screen, shot]);
+
+  // ---- 🎙 Talk ------------------------------------------------------------------
+  const endTalk = useCallback(async () => {
+    const room = roomRef.current;
+    roomRef.current = null;
+    setTalk(null);
+    try { await room?.disconnect(); } catch { /* gone */ }
+    try { await voice?.stopAudio?.(); } catch { /* not ours */ }
+    load();
+  }, [voice, load]);
+
+  const startTalk = useCallback(async () => {
+    if (!voice?.Room || roomRef.current || talk) return;
+    setError(null);
+    setTalk({ status: 'connecting', muted: false });
+    try {
+      const r = await ssb.voice({ chatId, route, platform: Platform.OS, page: { title: `In the app (${Platform.OS}): ${route || '/'}` }, ...(shot ? { screenshot: shot } : {}) });
+      if (r.chatId) rememberChat(r.chatId);
+      if (!r.configured) { setTalk(null); setError(r.say || 'Voice is not set up yet.'); return; }
+      await voice.startAudio?.();
+      const room = new voice.Room({ adaptiveStream: true, dynacast: true });
+      roomRef.current = room;
+      let shown = false;
+      const show = () => {
+        if (shown || !roomRef.current) return;
+        shown = true;
+        room.localParticipant.sendText(snapshotOf({ route, screenshot: shot, first: true }), { topic: SNAPSHOT_TOPIC }).catch(() => {});
+        setTalk((t) => (t ? { ...t, status: 'live' } : t));
+      };
+      room.on('participantConnected', show);
+      room.on('disconnected', () => { if (roomRef.current === room) endTalk(); });
+      await room.connect(r.url, r.token);
+      await room.localParticipant.setMicrophoneEnabled(true);
+      if (room.remoteParticipants?.size) show(); else setTalk((t) => (t ? { ...t, status: 'waiting' } : t));
+      // VOICE MODE shows the app: SSB steps aside to a pill, so they can move
+      // around while they talk (and SSB is told each screen they reach).
+      Keyboard.dismiss();
+      setMode('idle');
+    } catch (e) {
+      setError(`Could not start talking: ${String(e.message || e).split('\n')[0]}`);
+      endTalk();
+    }
+  }, [voice, talk, ssb, chatId, route, shot, rememberChat, endTalk]);
+
+  const toggleMute = useCallback(async () => {
+    const room = roomRef.current;
+    if (!room || !talk) return;
+    const muted = !talk.muted;
+    try { await room.localParticipant.setMicrophoneEnabled(!muted); setTalk({ ...talk, muted }); } catch { /* left as it was */ }
+  }, [talk]);
+
+  // A new screen while talking: SSB is told where they went.
+  useEffect(() => {
+    const room = roomRef.current;
+    if (room && talk?.status === 'live') room.localParticipant.sendText(snapshotOf({ route }), { topic: SNAPSHOT_TOPIC }).catch(() => {});
+  }, [route]);
+  // The person leaves (signs out, the gate closes, the host unmounts): the talk ends.
+  useEffect(() => () => { const room = roomRef.current; roomRef.current = null; room?.disconnect?.(); voice?.stopAudio?.(); }, []);
+  useEffect(() => { if (!gate && roomRef.current) endTalk(); }, [gate]);
+
+  const decide = useCallback(async (p, action) => {
+    setBusy(true); setError(null);
+    try {
+      await ssb.decide(chatId, p.id, action, action === 'raise' ? { kind: p.kind, title: p.title, detail: p.detail, severity: p.severity } : {});
+      await load();
+      loadWork();
+      return true;
+    } catch (e) { setError(`${p.title}: ${e.message}`); return false; }
+    finally { setBusy(false); }
+  }, [ssb, chatId, load, loadWork]);
+
+  const startAll = useCallback(async () => {
+    for (const p of draftsOf(chat).waiting) if (!(await decide(p, 'raise'))) break;
+  }, [chat, decide]);
+
+  // The pencil and the box. The item lives in a ref (a move must not wait on a render); state only draws it.
+  const finish = () => {
+    const it = liveRef.current; liveRef.current = null; setLive(null);
+    const done = it?.kind === 'box' ? boxItem(it) : it?.points?.length ? it : null;
+    if (done) setItems((all) => [...all, done]);
+  };
+  const pan = useMemo(() => PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onMoveShouldSetPanResponder: () => true,
+    onPanResponderGrant: (e) => {
+      const { pageX: x, pageY: y } = e.nativeEvent;
+      liveRef.current = toolRef.current === 'box' ? { kind: 'box', x0: x, y0: y, x1: x, y1: y } : { kind: 'stroke', points: [{ x, y }] };
+      setLive(liveRef.current);
+    },
+    onPanResponderMove: (e) => {
+      const it = liveRef.current;
+      if (!it) return;
+      const p = { x: e.nativeEvent.pageX, y: e.nativeEvent.pageY };
+      if (it.kind === 'box') { liveRef.current = { ...it, x1: p.x, y1: p.y }; setLive(liveRef.current); return; }
+      const points = addPoint(it.points, p);
+      if (points !== it.points) { liveRef.current = { ...it, points }; setLive(liveRef.current); }
+    },
+    onPanResponderRelease: finish,
+    onPanResponderTerminate: finish,
+  }), []);
+
+  // The button: a drag moves it, a tap opens SSB. Its start is kept for the gesture.
+  const fabStart = useRef(null);
+  const fabPan = useMemo(() => PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onPanResponderGrant: () => { fabStart.current = fabRef.current ?? fabHome(screenRef.current, insetsRef.current); },
+    onPanResponderMove: (_e, g) => {
+      if (!fabStart.current || !isDrag(g.dx, g.dy)) return;
+      setFab(clampFab({ x: fabStart.current.x + g.dx, y: fabStart.current.y + g.dy }, screenRef.current, insetsRef.current));
+    },
+    onPanResponderRelease: (_e, g) => {
+      fabStart.current = null;
+      if (!isDrag(g.dx, g.dy)) { openRef.current(); return; }
+      const at = fabRef.current;
+      if (at && storage?.setItem) Promise.resolve(storage.setItem(fabKey, JSON.stringify(at))).catch(() => {});
+    },
+    onPanResponderTerminate: () => { fabStart.current = null; },
+  }), [fabKey, storage]);
+
+  // ---- drawing ------------------------------------------------------------
+  const drawingViews = (list) => list.flatMap((it, i) => (it.kind === 'box'
+    ? [h(View, { key: `b${i}`, pointerEvents: 'none', style: [s.box, itemRect(it)] })]
+    : segmentsOf(it.points, INK_W).map((g, j) => h(View, {
+      key: `${i}-${j}`, pointerEvents: 'none',
+      style: [s.ink, { left: g.left, top: g.top, width: g.width, transform: [{ rotate: `${g.angle}rad` }] }],
+    }))));
+
+  const chrome = (() => {
+    if (!gate) return null;
+    if (mode === 'capturing') return items.length ? h(View, { style: StyleSheet.absoluteFill, pointerEvents: 'none' }, ...drawingViews(items)) : null;
+    if (mode === 'idle' && talk) {
+      return h(View, { style: [s.pill, { top: insets.top + 8 }], testID: 'ssb-talk-pill' },
+        h(View, { style: [s.talkDot, talk.status !== 'live' && { backgroundColor: MUTED }] }),
+        h(Text, { style: s.pillText }, talkLine(talk)),
+        h(Pressable, { onPress: toggleMute, accessibilityRole: 'button', accessibilityLabel: talk.muted ? 'Unmute' : 'Mute', style: s.pillBtn }, h(Text, { style: s.pillBtnText }, talk.muted ? 'Unmute' : 'Mute')),
+        h(Pressable, { testID: 'ssb-talk-open', onPress: () => setMode('sheet'), accessibilityRole: 'button', accessibilityLabel: 'Open SSB', style: s.pillBtn }, h(Text, { style: s.pillBtnText }, 'Open')),
+        h(Pressable, { testID: 'ssb-talk-end', onPress: endTalk, accessibilityRole: 'button', accessibilityLabel: 'End the talk', style: [s.pillBtn, s.talkEnd] }, h(Text, { style: [s.pillBtnText, { color: '#fff' }] }, 'End')));
+    }
+    if (mode === 'idle') {
+      const at = clampFab(fab ?? fabHome(screen, insets), screen, insets);   // a rotation can strand a kept spot
+      return h(View, {
+        testID: 'ssb-button', accessible: true, accessibilityRole: 'button', accessibilityLabel: 'Ask SSB about this screen',
+        accessibilityHint: 'Drag to move it', onAccessibilityTap: openSheet,
+        style: [s.fab, { left: at.x, top: at.y }, talk && s.fabTalking], ...fabPan.panHandlers,
+      }, h(Image, { source: LOGO, style: s.fabLogo }), unread ? h(View, { style: s.dot }) : null);
+    }
+    if (mode === 'drawing') {
+      const box = drawingBox(items);
+      const top = box ? fieldTop({ rect: box, screen, keyboardTop: kbTop, insets }) : null;
+      return h(View, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none' },
+        // The surface first, so the hint and the field above it still take their own taps.
+        h(View, { style: StyleSheet.absoluteFill, ...pan.panHandlers, testID: 'ssb-draw-surface' },
+          ...drawingViews(live ? [...items, live] : items)),
+        h(View, { style: [s.hint, { top: insets.top + 8 }] },
+          ...['pencil', 'box'].map((t) => h(Pressable, {
+            key: t, onPress: () => setTool(t), accessibilityRole: 'button', accessibilityState: { selected: tool === t },
+            accessibilityLabel: t === 'box' ? 'Box: drag a box round it' : 'Pencil: scribble on it', style: [s.toolBtn, tool === t && s.toolOn],
+          }, h(Text, { style: [s.toolText, tool === t && s.toolTextOn] }, t === 'box' ? '▭ Box' : '✎ Pencil'))),
+          h(View, { style: s.hintSep }),
+          items.length ? h(Pressable, { onPress: () => setItems((all) => all.slice(0, -1)), accessibilityRole: 'button', accessibilityLabel: 'Undo the last one', style: s.hintBtn }, h(Text, { style: s.hintLink }, 'Undo')) : null,
+          h(Pressable, { onPress: () => { Keyboard.dismiss(); setItems([]); setMode('sheet'); }, accessibilityRole: 'button', accessibilityLabel: 'Stop drawing', style: s.hintBtn }, h(Text, { style: s.hintLink }, 'Cancel'))),
+        top != null ? h(View, { style: [s.field, { top }] },
+          h(TextInput, {
+            testID: 'ssb-draw-note', value: note, onChangeText: setNote, placeholder: 'What should change here?',
+            placeholderTextColor: MUTED, keyboardAppearance: 'dark', style: s.fieldInput, returnKeyType: 'send', onSubmitEditing: sendDrawing, blurOnSubmit: false,
+          }),
+          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,
+      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,
+    });
+    return null;
+  })();
+
+  return h(View, { ref: rootRef, style: s.root, collapsable: false },
+    children,
+    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 }) {
+  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 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 } },
+      h(View, { style: s.header },
+        h(View, { style: s.headLogoRing }, h(Image, { source: LOGO, style: s.headLogo, accessibilityLabel: 'SSB' })),
+        h(View, { style: { flex: 1 } },
+          h(Text, { style: s.title }, 'Tell SSB'),
+          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),
+          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))),
+        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,
+        ...waiting.map((p) => h(View, { key: `d${p.id}`, style: s.draftRow, testID: `ssb-draft-${p.id}` },
+          h(View, { style: s.workLine },
+            h(Pressable, { onPress: () => setOpen(open === p.id ? null : p.id), style: { flex: 1 }, accessibilityRole: 'button', accessibilityLabel: p.title },
+              h(Text, { style: s.workTitle, numberOfLines: open === p.id ? undefined : 2 }, p.title)),
+            h(Pressable, { testID: `ssb-draft-start-${p.id}`, onPress: () => onDecide(p, 'raise'), disabled: busy, accessibilityRole: 'button', accessibilityLabel: `Start: ${p.title}`, style: [s.primary, s.small, busy && s.disabled] }, h(Text, { style: s.primaryText }, 'Start'))),
+          open === p.id ? h(View, null,
+            p.detail ? h(Text, { style: s.draftBody }, p.detail) : null,
+            h(Pressable, { onPress: () => onDecide(p, 'dismiss'), disabled: busy, accessibilityRole: 'button', accessibilityLabel: `Dismiss: ${p.title}`, style: [s.quiet, { alignSelf: 'flex-start' }] }, h(Text, { style: s.quietText }, 'Dismiss'))) : null)),
+        ...sent.map((p) => h(View, { key: `s${p.id}`, style: s.workRow, testID: `ssb-sent-${p.id}` },
+          h(Text, { style: s.workTitle, numberOfLines: 2 }, `✓ ${p.title}`),
+          p.jobUrl ? h(Pressable, { onPress: () => Linking.openURL(p.jobUrl).catch(() => {}), accessibilityRole: 'link' }, h(Text, { style: s.link }, 'Started →')) : h(Text, { style: s.state }, 'Started')))) : null,
+      // THE CONVERSATION, below.
+      h(ScrollView, { ref: scroll, style: s.thread, contentContainerStyle: { paddingVertical: 8 }, keyboardShouldPersistTaps: 'handled', onContentSizeChange: () => scroll.current?.scrollToEnd({ animated: true }) },
+        msgs.length ? null : h(Text, { style: s.empty }, 'Say what should change on this screen, or tap Draw to scribble on it.'),
+        ...msgs.map((m) => h(View, { key: m.id, style: [s.bubble, m.role === 'user' ? s.mine : s.theirs] },
+          m.image ? h(Image, { source: { uri: m.image }, style: s.thumb, resizeMode: 'contain' }) : null,
+          h(Text, { style: m.role === 'user' ? s.mineText : s.theirsText }, m.text),
+          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,
+      h(View, { style: [s.composer, { paddingBottom: Math.max(12, insets.bottom > 60 ? 16 : insets.bottom) }] },
+        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,
+          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'))))));
+}
+
+const shadow = { shadowColor: '#000', shadowOpacity: 0.45, shadowRadius: 18, shadowOffset: { width: 0, height: 8 }, elevation: 12 };
+const glow = (c, r = 12) => ({ shadowColor: c, shadowOpacity: 0.55, shadowRadius: r, shadowOffset: { width: 0, height: 0 } });
+const s = StyleSheet.create({
+  root: { flex: 1 },
+  pressed: { opacity: 0.7 },
+  disabled: { opacity: 0.45 },
+  fab: { position: 'absolute', width: FAB, height: FAB, borderRadius: FAB / 2, alignItems: 'center', justifyContent: 'center', ...shadow },
+  fabLogo: { width: FAB, height: FAB, borderRadius: FAB / 2 },
+  fabTalking: { borderWidth: 3, borderColor: GREEN, ...glow(GREEN, 14) },
+  dot: { position: 'absolute', top: 2, right: 2, width: 12, height: 12, borderRadius: 6, backgroundColor: RED, borderWidth: 2, borderColor: BG, ...glow(RED, 6) },
+  // Drawing on the live screen.
+  ink: { position: 'absolute', height: INK_W, borderRadius: INK_W / 2, backgroundColor: RED },
+  box: { position: 'absolute', borderWidth: 3, borderColor: RED, borderRadius: 6, backgroundColor: 'rgba(255,77,90,0.08)' },
+  hint: { position: 'absolute', alignSelf: 'center', flexDirection: 'row', alignItems: 'center', paddingVertical: 8, paddingHorizontal: 12, borderRadius: 20, backgroundColor: INK, borderWidth: 1, borderColor: LINE, ...shadow },
+  toolBtn: { paddingVertical: 5, paddingHorizontal: 10, borderRadius: 12, marginRight: 4 },
+  toolOn: { backgroundColor: RED, ...glow(RED, 8) },
+  toolText: { color: TEXT, fontSize: 14, fontWeight: '600' },
+  toolTextOn: { color: '#fff' },
+  hintSep: { width: 1, height: 18, backgroundColor: LINE, marginHorizontal: 6 },
+  hintLink: { color: '#8fb3ff', fontSize: 14, fontWeight: '600' },
+  hintBtn: { paddingHorizontal: 6, paddingVertical: 2 },
+  field: { position: 'absolute', left: 12, right: 12, height: 56, flexDirection: 'row', alignItems: 'center', paddingLeft: 14, paddingRight: 6, borderRadius: 16, backgroundColor: SURFACE, borderWidth: 1, borderColor: LINE, ...shadow },
+  fieldInput: { flex: 1, fontSize: 16, color: TEXT },
+  sendRound: { width: 40, height: 40, borderRadius: 20, backgroundColor: BLUE, alignItems: 'center', justifyContent: 'center', marginLeft: 4, ...glow(BLUE, 10) },
+  sendRoundText: { color: '#fff', fontSize: 20, fontWeight: '700' },
+  // The panel. Spelled out: StyleSheet.absoluteFillObject is gone in React
+  // Native 0.86, and spreading `undefined` left the panel with no size at all
+  // (the harness caught it).
+  panel: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, backgroundColor: BG },
+  header: { flexDirection: 'row', alignItems: 'center', gap: 12, paddingTop: 12, paddingHorizontal: 16, paddingBottom: 12, borderBottomWidth: 1, borderBottomColor: LINE },
+  headLogoRing: { width: 40, height: 40, borderRadius: 20, ...glow(BLUE, 10) },
+  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 },
+  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 },
+  talkEnd: { backgroundColor: RED, borderColor: RED },
+  talkBtnText: { fontSize: 13, fontWeight: '700', color: TEXT },
+  // 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 },
+  sectionRow: { flexDirection: 'row', alignItems: 'center', paddingRight: 16 },
+  workRow: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 11, gap: 10, borderTopWidth: 1, borderTopColor: LINE },
+  draftRow: { paddingHorizontal: 16, paddingVertical: 11, borderTopWidth: 1, borderTopColor: LINE, borderLeftWidth: 3, borderLeftColor: YELLOW, backgroundColor: 'rgba(246,197,68,0.06)' },
+  workLine: { flexDirection: 'row', alignItems: 'center', gap: 10 },
+  workTitle: { flex: 1, fontSize: 15, fontWeight: '600', color: TEXT },
+  state: { fontSize: 12, fontWeight: '800', letterSpacing: 0.3, color: MUTED, paddingVertical: 4, paddingHorizontal: 9, borderRadius: 9, backgroundColor: RAISED, borderWidth: 1, borderColor: LINE, overflow: 'hidden' },
+  state_ready: { color: BG, backgroundColor: GREEN, borderColor: GREEN },
+  state_building: { color: '#9cc0ff', backgroundColor: 'rgba(61,123,255,0.14)', borderColor: 'rgba(61,123,255,0.5)' },
+  state_checking: { color: '#9cc0ff', backgroundColor: 'rgba(61,123,255,0.14)', borderColor: 'rgba(61,123,255,0.5)' },
+  state_blocked: { color: '#fff', backgroundColor: RED, borderColor: RED },
+  demo: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 11, backgroundColor: 'rgba(47,210,122,0.08)' },
+  demoReady: { backgroundColor: 'rgba(47,210,122,0.16)' },
+  demoText: { flex: 1, fontSize: 13, fontWeight: '600', color: TEXT },
+  demoGo: { color: GREEN, fontSize: 14, fontWeight: '800', marginLeft: 8 },
+  draftBody: { fontSize: 13, color: MUTED, marginTop: 6, lineHeight: 19 },
+  link: { color: '#8fb3ff', fontSize: 13, fontWeight: '600' },
+  // The conversation takes what the work and the composer leave.
+  thread: { flex: 1, paddingHorizontal: 12 },
+  empty: { color: MUTED, fontSize: 14, textAlign: 'center', paddingVertical: 24, paddingHorizontal: 20, lineHeight: 20 },
+  bubble: { maxWidth: '86%', borderRadius: 16, paddingVertical: 9, paddingHorizontal: 13, marginVertical: 4 },
+  mine: { alignSelf: 'flex-end', backgroundColor: BLUE, borderBottomRightRadius: 4 },
+  theirs: { alignSelf: 'flex-start', backgroundColor: RAISED, borderWidth: 1, borderColor: LINE, borderBottomLeftRadius: 4 },
+  mineText: { color: '#fff', fontSize: 15, lineHeight: 21 },
+  theirsText: { color: TEXT, fontSize: 15, lineHeight: 21 },
+  thumb: { width: 140, height: 220, borderRadius: 8, marginBottom: 6, backgroundColor: '#0006' },
+  error: { color: RED, fontSize: 13, paddingHorizontal: 16, paddingTop: 6 },
+  composer: { paddingHorizontal: 12, paddingTop: 10, borderTopWidth: 1, borderTopColor: LINE, backgroundColor: SURFACE },
+  input: { minHeight: 44, maxHeight: 120, fontSize: 16, color: TEXT, backgroundColor: BG, borderWidth: 1, borderColor: LINE, borderRadius: 14, paddingHorizontal: 13, paddingTop: 11, paddingBottom: 11 },
+  row: { flexDirection: 'row', alignItems: 'center', marginTop: 8, gap: 8 },
+  chip: { flexDirection: 'row', alignItems: 'center', paddingVertical: 7, paddingHorizontal: 11, borderRadius: 12, borderWidth: 1, borderColor: LINE, backgroundColor: RAISED },
+  chipText: { fontSize: 13, color: TEXT, fontWeight: '600' },
+  primary: { paddingVertical: 9, paddingHorizontal: 16, borderRadius: 12, backgroundColor: BLUE, minWidth: 64, alignItems: 'center', ...glow(BLUE, 10) },
+  primaryText: { color: '#fff', fontSize: 14, fontWeight: '800', letterSpacing: 0.2 },
+  small: { paddingVertical: 6, paddingHorizontal: 12, minWidth: 0 },
+  quiet: { paddingVertical: 6, paddingHorizontal: 10 },
+  quietText: { color: MUTED, fontSize: 14, fontWeight: '600' },
+  iconBtn: { width: 36, height: 36, alignItems: 'center', justifyContent: 'center', borderRadius: 18, backgroundColor: RAISED },
+  iconText: { color: TEXT, fontSize: 16 },
+  // Voice mode: a pill over the app.
+  pill: { position: 'absolute', left: 12, right: 12, flexDirection: 'row', alignItems: 'center', paddingVertical: 8, paddingLeft: 14, paddingRight: 6, borderRadius: 24, backgroundColor: INK, borderWidth: 1, borderColor: 'rgba(47,210,122,0.45)', ...shadow },
+  pillText: { flex: 1, color: TEXT, fontSize: 14, fontWeight: '600' },
+  pillBtn: { paddingVertical: 6, paddingHorizontal: 10, borderRadius: 14, backgroundColor: RAISED, marginLeft: 6 },
+  pillBtnText: { color: TEXT, fontSize: 13, fontWeight: '700' },
+});

package/src/core.js

@@ -0,0 +1,310 @@
+// The overlay's pure half: no React Native here, so node --test runs it.
+// The server side is functions/in-app.mjs; the conversation is Tell SSB's
+// (functions/annotate.mjs), so the shapes below are the extension's.
+
+export const DEFAULT_API = 'https://simonsays.build';
+export const HOST = 5;
+export const TEXT = 6;
+const PIN_SLOP = 12;           // a drag shorter than this is a tap: a pin, not a box
+
+/** The app's SSB settings, or null when it is not set up (the overlay renders nothing). */
+export function overlayConfig({ appId, backend, api } = {}) {
+  if (!appId || !backend) return null;
+  return { appId: String(appId), backend: String(backend).replace(/\/+$/, ''), api: String(api || DEFAULT_API).replace(/\/+$/, '') };
+}
+
+/**
+ * The in-app API (functions/index.mjs /api/in-app/*). Every call carries the
+ * app's CURRENT session token, asked for each time: the app refreshes it.
+ */
+export function inAppApi(config, getToken, fetchImpl = globalThis.fetch) {
+  const call = async (path, init = {}) => {
+    const token = await getToken();
+    if (!token) { const e = new Error('signed out'); e.status = 401; throw e; }
+    const res = await fetchImpl(`${config.api}/api/in-app${path}`, {
+      ...init,
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${token}`,
+        'x-ssb-app': config.appId,
+        'x-ssb-backend': config.backend,
+        ...(init.headers || {}),
+      },
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) { const e = new Error(json.error || `SSB answered ${res.status}`); e.status = res.status; throw e; }
+    return json;
+  };
+  const post = (path, body) => call(path, { method: 'POST', body: JSON.stringify(body || {}) });
+  return {
+    me: () => call('/me'),
+    send: (body) => post('/annotations', body),
+    chat: (id) => call(`/chats/${encodeURIComponent(id)}`),
+    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'),
+  };
+}
+
+// ---- the pencil: scribbles on the live screen --------------------------------
+const MIN_STEP = 3;            // a point closer than this to the last one adds nothing
+
+/** A stroke with `p` added, unless it is too close to the last point to matter. */
+export function addPoint(stroke, p) {
+  const last = stroke[stroke.length - 1];
+  if (last && Math.hypot(p.x - last.x, p.y - last.y) < MIN_STEP) return stroke;
+  return [...stroke, { x: p.x, y: p.y }];
+}
+
+/**
+ * A stroke as straight segments a View can draw: each is a bar `width` long,
+ * centred on its midpoint and turned by `angle` (radians). A single point is a dot.
+ */
+export function segmentsOf(stroke, thickness = 4) {
+  if (stroke.length === 1) return [{ left: stroke[0].x - thickness / 2, top: stroke[0].y - thickness / 2, width: thickness, angle: 0 }];
+  const out = [];
+  for (let i = 1; i < stroke.length; i++) {
+    const a = stroke[i - 1], b = stroke[i];
+    const len = Math.hypot(b.x - a.x, b.y - a.y);
+    const width = len + thickness;   // overlap the joints so a curve has no gaps
+    out.push({ left: (a.x + b.x) / 2 - width / 2, top: (a.y + b.y) / 2 - thickness / 2, width, angle: Math.atan2(b.y - a.y, b.x - a.x) });
+  }
+  return out;
+}
+
+// A drawing is a list of items, each a pencil stroke or a box:
+//   { kind: 'stroke', points: [{x, y}] } | { kind: 'box', x0, y0, x1, y1 }   (screen points)
+const MIN_BOX = 8;             // a box smaller than this was a slip, not a box
+
+/** A box item from its drag, or null when it is too small to mean anything. */
+export function boxItem(d) {
+  if (Math.abs(d.x1 - d.x0) < MIN_BOX || Math.abs(d.y1 - d.y0) < MIN_BOX) return null;
+  return { kind: 'box', x0: d.x0, y0: d.y0, x1: d.x1, y1: d.y1 };
+}
+
+/** One item's box, in points. */
+export function itemRect(it) {
+  if (it.kind === 'box') {
+    const left = Math.min(it.x0, it.x1), top = Math.min(it.y0, it.y1);
+    return { left, top, width: Math.abs(it.x1 - it.x0), height: Math.abs(it.y1 - it.y0) };
+  }
+  const xs = it.points.map((p) => p.x), ys = it.points.map((p) => p.y);
+  const left = Math.min(...xs), top = Math.min(...ys);
+  return { left, top, width: Math.max(...xs) - left, height: Math.max(...ys) - top };
+}
+
+/** The box round everything drawn, or null with nothing drawn. */
+export function drawingBox(items) {
+  const rs = items.filter((it) => it.kind === 'box' || it.points?.length).map(itemRect);
+  if (!rs.length) return null;
+  const left = Math.min(...rs.map((r) => r.left)), top = Math.min(...rs.map((r) => r.top));
+  return { left, top, width: Math.max(...rs.map((r) => r.left + r.width)) - left, height: Math.max(...rs.map((r) => r.top + r.height)) - top };
+}
+
+/**
+ * What was drawn, as the ONE mark a send carries (annotate.mjs cleanMarks):
+ * a `box` when only boxes were drawn, else a `pen`, over the drawing's box,
+ * in fractions of the screen.
+ */
+export function drawingMark(items, screen) {
+  const r = drawingBox(items);
+  if (!r) return null;
+  const f = (v, d) => Math.min(1, Math.max(0, v / d));
+  return { kind: items.every((it) => it.kind === 'box') ? 'box' : 'pen',
+    x: f(r.left, screen.width), y: f(r.top, screen.height), w: f(r.width, screen.width), h: f(r.height, screen.height) };
+}
+
+/** The point the drawing is about (what the app has under it is named): the middle of its box. */
+export const drawingPoint = (items) => {
+  const r = drawingBox(items);
+  return r ? { x: r.left + r.width / 2, y: r.top + r.height / 2 } : null;
+};
+
+/**
+ * Where the note field goes: just above the keyboard when that is clear of
+ * the drawing, else under the status bar. `keyboardTop` is the
+ * keyboard's top edge in screen points (the screen height when it is down).
+ */
+export function fieldTop({ rect, screen, keyboardTop, insets, fieldH = 56 }) {
+  const above = Math.min(screen.height - insets.bottom, keyboardTop) - fieldH - 12;
+  if (above >= rect.top + rect.height + 8) return above;
+  return insets.top + 8;
+}
+
+// ---- the element under a mark: React's own tree ---------------------------
+const lower = (s) => String(s ?? '').trim();
+
+function* walk(root) {
+  const stack = root ? [root] : [];
+  while (stack.length) {
+    const f = stack.pop();
+    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 textUnder = (f, max = 120) => {
+  let out = '';
+  for (const n of walk(f.child)) {
+    if (n.tag === TEXT) out += (typeof n.memoizedProps === 'string' ? n.memoizedProps : String(n.memoizedProps?.text ?? '')) + ' ';
+    if (out.length > max) break;
+  }
+  return out.replace(/\s+/g, ' ').trim().slice(0, max);
+};
+
+/** The host fibers worth naming: ones with a testID, a label, a role, or a press. Our own `skip` subtree is left out. */
+export function namedHosts(root, skip = null, max = 400) {
+  const out = [];
+  const stack = root ? [root] : [];
+  while (stack.length && out.length < max) {
+    const f = stack.pop();
+    if (skip && f === skip) continue;
+    const p = f.memoizedProps || {};
+    if (f.tag === HOST && (p.testID || p.accessibilityLabel || p['aria-label'] || p.accessibilityRole || p.role || typeof p.onPress === 'function' || typeof p.onChangeText === 'function')) out.push(f);
+    for (let c = f.child; c; c = c.sibling) stack.push(c);
+  }
+  return out;
+}
+
+/** What the page says about an element, the shape the extension sends (annotate.mjs cleanMarks `element`). */
+export function describeHost(f) {
+  const p = f?.memoizedProps || {};
+  const role = p.accessibilityRole || p.role || (typeof p.onChangeText === 'function' ? 'textbox' : typeof p.onPress === 'function' ? 'button' : '');
+  const el = {
+    tag: typeof f?.type === 'string' ? f.type : '',
+    role: lower(role),
+    name: lower(p.accessibilityLabel || p['aria-label']),
+    text: textUnder(f),
+    css: p.testID ? `testID=${p.testID}` : '',
+  };
+  return Object.fromEntries(Object.entries(el).filter(([, v]) => v));
+}
+
+/** Of measured candidates [{rect, fiber}], the smallest that holds the point. */
+export function smallestAt(cands, pt) {
+  let best = null;
+  for (const c of cands) {
+    const r = c.rect;
+    if (!r || pt.x < r.left || pt.x > r.left + r.width || pt.y < r.top || pt.y > r.top + r.height) continue;
+    if (!best || r.width * r.height < best.rect.width * best.rect.height) best = c;
+  }
+  return best;
+}
+
+// ---- the conversation -------------------------------------------------------
+/** The drafts SSB has proposed: waiting, and the ones already started. */
+export function draftsOf(chat) {
+  const ps = chat?.proposals || [];
+  return { waiting: ps.filter((p) => p.status === 'proposed'), sent: ps.filter((p) => p.status === 'raised') };
+}
+
+/** The drafts bar's words: "2 drafts ready · 1 started", or '' when there is nothing. */
+export function draftsLine({ waiting, sent }) {
+  const parts = [];
+  if (waiting.length) parts.push(`${waiting.length} draft${waiting.length === 1 ? '' : 's'} ready`);
+  if (sent.length) parts.push(`${sent.length} started`);
+  return parts.join(' · ');
+}
+
+/** The latest SSB reply carrying "Confirm and start work", while a draft waits. */
+export function offerOf(chat) {
+  if (!draftsOf(chat).waiting.length) return null;
+  const last = [...(chat?.messages || [])].reverse().find((m) => m.role !== 'user');
+  return last?.offerStart ? last.id : null;
+}
+
+/** How often to ask for the thread: quick while it is open or SSB is writing, never otherwise. */
+export function pollEvery({ open, thinking }) {
+  if (open) return thinking ? 1500 : 4000;
+  return thinking ? 5000 : 0;
+}
+
+/** Did SSB say something new since `seenId`? (the button's dot while the sheet is closed). */
+export function newReply(chat, seenId) {
+  const last = [...(chat?.messages || [])].reverse().find((m) => m.role !== 'user' && !m.streaming);
+  return !!last && last.id !== seenId;
+}
+
+/** The body of a send (POST /api/in-app/annotations). */
+export function sendBody({ chatId, text, route, platform, screen, mark, element, screenshot }) {
+  return {
+    ...(chatId ? { chatId } : {}),
+    text: String(text || '').trim(),
+    url: String(route || '/'),
+    page: { title: `In the app (${platform || 'phone'}): ${route || '/'}`, viewport: { w: Math.round(screen.width), h: Math.round(screen.height), scrollY: 0 } },
+    marks: mark ? [{ ...mark, note: String(text || '').trim(), ...(element && Object.keys(element).length ? { element } : {}) }] : [],
+    ...(screenshot ? { screenshot } : {}),
+  };
+}
+
+// ---- "it's done, tap to see it" (functions/in-app-notify.mjs) ----------------
+/** The link an SSB notification opens (the dev-client preview with the demo), or null for any other notification. */
+export function ssbLinkOf(response) {
+  const data = response?.notification?.request?.content?.data;
+  return data?.kind === 'ssb-demo' && typeof data.url === 'string' && data.url ? data.url : null;
+}
+
+/** What the sheet says about the conversation's phone demo, or null. */
+export function demoBanner(chat) {
+  const d = chat?.demo;
+  if (!d) return null;
+  const what = d.title || 'your change';
+  if (d.status === 'ready' && d.url) return { text: `Ready to see: ${what}`, url: d.url };
+  if (d.status === 'preparing') return { text: `Done: ${what}. Preparing a demo you can open in the app…` };
+  if (d.status === 'failed') return { text: `Done: ${what}. The demo couldn't be prepared${d.error ? `: ${d.error}` : '.'}` };
+  return null;
+}
+
+// ---- the button: wherever it is put --------------------------------------------
+export const FAB = 52;
+const TAP_SLOP = 8;            // a press that moved less than this is a tap, not a drag
+
+/** Where the button sits by default: bottom-right, clear of the insets. */
+export const fabHome = (screen, insets) => ({ x: screen.width - FAB - 16, y: screen.height - FAB - 16 - insets.bottom });
+
+/** A position kept on screen: the whole button visible, off the status bar. */
+export function clampFab(pos, screen, insets) {
+  return {
+    x: Math.min(screen.width - FAB - 4, Math.max(4, pos.x)),
+    y: Math.min(screen.height - FAB - 4, Math.max(insets.top, pos.y)),
+  };
+}
+
+/** Did the finger travel far enough to be a drag? */
+export const isDrag = (dx, dy) => Math.hypot(dx, dy) >= TAP_SLOP;
+
+// ---- 🎙 Talk (functions/voice-chat.mjs, voice-agent/src/chat.mjs) --------------
+export const SNAPSHOT_TOPIC = 'ssb.guide.snapshot';   // the agent's (voice-agent/src/guide.mjs TOPIC.snapshot)
+
+/** What the agent is sent about the screen: the route, the picture when there is one, and whether this is the opening look. */
+export const snapshotOf = ({ route, screenshot, first = false }) => JSON.stringify({ route: route || '/', ...(screenshot ? { screenshot } : {}), ...(first ? { first: true } : {}) });
+
+/** The talk bar's words. */
+export function talkLine(talk) {
+  if (!talk) return '';
+  if (talk.status === 'connecting') return 'Connecting to SSB…';
+  if (talk.status === 'waiting') return 'Waiting for SSB to join…';
+  return talk.muted ? 'Talking with SSB · muted' : 'Talking with SSB';
+}
+
+// ---- the panel's top: the work (2026-10-20, the product owner: "the web
+// extension has jobs and in-progress things at the top, with chat down the
+// bottom … maybe we can move to that pattern") ------------------------------
+/** The extension's words for a job in flight (extension/overlay.js inFlightHtml). */
+export const STATE_WORD = Object.freeze({ ready: 'Ready', queued: 'Queued', building: 'Building', checking: 'Checking', blocked: 'Blocked' });
+
+/**
+ * What the top of the panel shows: the app's work in flight (GET
+ * /api/in-app/work, functions/sessions.mjs inFlightOf — whatever chat it came
+ * from), this chat's drafts waiting to start, and what this chat started that
+ * is not in flight any more (the row says so, with its job).
+ */
+export function workView({ inFlight = [], chat = null } = {}) {
+  const flying = Array.isArray(inFlight) ? inFlight : [];
+  const flyingIds = new Set(flying.map((x) => x.id));
+  const { waiting, sent } = draftsOf(chat);
+  return { flying, waiting, sent: sent.filter((p) => !p.jobId || !flyingIds.has(p.jobId)) };
+}