@simon-says-build/ssb-overlay 0.0.0-stage → 0.1.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,39 @@
+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>;
+  };
+  /** 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, markOf, 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.1.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/", "README.md"],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.76"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "license": "UNLICENSED"
+}

package/src/SsbHost.js

@@ -0,0 +1,417 @@
+// <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 a small SSB button floats bottom-right. Tapping it takes
+// a picture of the screen as it is and opens a sheet: the conversation with
+// SSB about this app (Tell SSB's, functions/annotate.mjs), the picture to
+// attach, and **Mark** — tap or drag on the live screen, type beside the
+// mark, send: the mark is captured ON the screen, with the field and our
+// chrome hidden. 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 {
+  demoBanner, describeHost, draftsLine, draftsOf, fieldTop, inAppApi, markOf, markPoint, markRect, namedHosts,
+  newReply, offerOf, overlayConfig, pollEvery, sendBody, smallestAt, ssbLinkOf,
+} from './core.js';
+
+const h = React.createElement;
+const BLUE = '#2f5bea', INK = '#161a23', MUTED = '#6b7280', LINE = '#eef0f3', RED = '#e5484d';
+const DEFAULT_INSETS = { top: 60, bottom: 40 };
+
+// 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, 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, 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, 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 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 | marking | noting | capturing
+  const [shot, setShot] = useState(null);            // the screen as it was when the button was tapped
+  const [attach, setAttach] = useState(true);
+  const [mark, setMark] = useState(null);
+  const [element, setElement] = useState(null);
+  const [drag, setDrag] = useState(null);
+  const dragRef = useRef(null);
+  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 [showDrafts, setShowDrafts] = useState(false);
+  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(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 a waiting mark and the picture stale (the extension's
+  // rule): the mark is dropped and its words move to the composer.
+  const lastRoute = useRef(route);
+  useEffect(() => {
+    if (lastRoute.current === route) return;
+    lastRoute.current = route;
+    setShot(null);
+    if (mode === 'marking' || mode === 'noting') {
+      if (note.trim()) setDraft((d) => (d ? `${d}\n${note}` : note));
+      setMark(null); setElement(null); 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]);
+  useEffect(() => {
+    if (!gate || !chatId) return undefined;
+    const every = 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]);
+
+  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, mark, 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); setAttach(!!pic);
+    setMode('sheet');
+  }, [grab]);
+
+  const close = useCallback(() => {
+    Keyboard.dismiss();
+    setSeen(lastReplyId(chat));
+    setSeenDemo(chat?.demo?.url ?? null);
+    setMark(null); setElement(null); setNote(''); setShowDrafts(false);
+    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;
+    const ok = await deliver(sendBody({ chatId, text, route, platform: Platform.OS, screen, screenshot: attach ? shot : null }));
+    if (ok) { setDraft(''); if (attach) setAttach(false); }
+  }, [draft, busy, deliver, chatId, route, screen, attach, shot]);
+
+  const placed = useCallback(async (g) => {
+    const m = markOf(g, screen);
+    setMark(m); setDrag(null); setMode('noting');
+    // What the app has under the mark, named the way the app names it.
+    try {
+      const root = fiberOf(rootRef.current);
+      const skip = fiberOf(chromeRef.current);
+      const hosts = namedHosts(root, skip);
+      const cands = await Promise.all(hosts.map(async (fiber) => ({ fiber, rect: await measure(fiber) })));
+      const hit = smallestAt(cands, markPoint(m, screen));
+      setElement(hit ? describeHost(hit.fiber) : null);
+    } catch { setElement(null); }
+  }, [screen]);
+
+  const sendMark = useCallback(async () => {
+    const text = note.trim();
+    if (!text || busy || !mark) return;
+    Keyboard.dismiss();
+    setMode('capturing');                            // only the mark stays on screen
+    const pic = await grab();
+    setMode('sheet');
+    const ok = await deliver(sendBody({ chatId, text, route, platform: Platform.OS, screen, mark, element, screenshot: pic }));
+    if (ok) { setMark(null); setElement(null); setNote(''); setAttach(false); }
+    else setDraft((d) => d || text);
+  }, [note, busy, mark, grab, deliver, chatId, route, screen, element]);
+
+  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();
+      return true;
+    } catch (e) { setError(`${p.title}: ${e.message}`); return false; }
+    finally { setBusy(false); }
+  }, [ssb, chatId, load]);
+
+  const startAll = useCallback(async () => {
+    for (const p of draftsOf(chat).waiting) if (!(await decide(p, 'raise'))) break;
+  }, [chat, decide]);
+
+  const pan = useMemo(() => PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onMoveShouldSetPanResponder: () => true,
+    // The gesture lives in a ref (the release must not run inside a state updater); state only draws it.
+    onPanResponderGrant: (e) => { const { pageX, pageY } = e.nativeEvent; dragRef.current = { x0: pageX, y0: pageY, x1: pageX, y1: pageY }; setDrag(dragRef.current); },
+    onPanResponderMove: (e) => { const d = dragRef.current; if (!d) return; dragRef.current = { ...d, x1: e.nativeEvent.pageX, y1: e.nativeEvent.pageY }; setDrag(dragRef.current); },
+    onPanResponderRelease: (e) => { const d = dragRef.current; dragRef.current = null; if (d) placed({ ...d, x1: e.nativeEvent.pageX, y1: e.nativeEvent.pageY }); },
+    onPanResponderTerminate: () => { dragRef.current = null; setDrag(null); },
+  }), [placed]);
+
+  // ---- drawing ------------------------------------------------------------
+  const markView = (m, key = 'mark') => {
+    const r = markRect(m, screen);
+    return m.kind === 'box'
+      ? h(View, { key, pointerEvents: 'none', style: [s.box, r] })
+      : h(View, { key, pointerEvents: 'none', style: [s.pin, r] }, h(Text, { style: s.pinText }, '1'));
+  };
+
+  const chrome = (() => {
+    if (!gate) return null;
+    if (mode === 'capturing') return mark ? markView(mark) : null;
+    if (mode === 'idle') {
+      return h(Pressable, {
+        testID: 'ssb-button', accessibilityRole: 'button', accessibilityLabel: 'Ask SSB about this screen',
+        onPress: openSheet, style: ({ pressed }) => [s.fab, { bottom: insets.bottom + 16 }, pressed && s.pressed],
+      }, h(Text, { style: s.fabText }, 'SSB'), unread ? h(View, { style: s.dot }) : null);
+    }
+    if (mode === 'marking') {
+      const live = drag ? markOf(drag, screen) : null;
+      return h(View, { style: StyleSheet.absoluteFill, ...pan.panHandlers, testID: 'ssb-mark-surface' },
+        live ? markView(live, 'live') : null,
+        h(View, { style: [s.hint, { top: insets.top + 8 }] },
+          h(Text, { style: s.hintText }, 'Tap or drag on what this is about'),
+          h(Pressable, { onPress: () => setMode('sheet'), accessibilityRole: 'button', accessibilityLabel: 'Cancel marking' }, h(Text, { style: s.hintLink }, 'Cancel'))));
+    }
+    if (mode === 'noting' && mark) {
+      const top = fieldTop({ rect: markRect(mark, screen), screen, keyboardTop: kbTop, insets });
+      return h(View, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none' },
+        markView(mark),
+        h(View, { style: [s.field, { top }] },
+          h(TextInput, {
+            testID: 'ssb-mark-note', autoFocus: true, value: note, onChangeText: setNote, placeholder: 'What should change here?',
+            placeholderTextColor: MUTED, style: s.fieldInput, returnKeyType: 'send', onSubmitEditing: sendMark, blurOnSubmit: false,
+          }),
+          h(Pressable, { onPress: () => { setMark(null); setNote(''); setMode('sheet'); }, accessibilityRole: 'button', accessibilityLabel: 'Drop the mark', style: s.iconBtn }, h(Text, { style: s.iconText }, '✕')),
+          h(Pressable, { testID: 'ssb-mark-send', onPress: sendMark, disabled: !note.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.sendRound, (!note.trim() || busy) && s.disabled] }, h(Text, { style: s.sendRoundText }, '→'))));
+    }
+    if (mode === 'sheet') return h(Sheet, {
+      gate, chat, screen, insets, shot, attach, setAttach, draft, setDraft, busy, error, showDrafts, setShowDrafts,
+      onSend: sendDraft, onMark: () => { Keyboard.dismiss(); setMode('marking'); }, onClose: close,
+      onNew: () => { rememberChat(null); setChat(null); }, onDecide: decide, onStartAll: startAll,
+    });
+    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 Sheet({ gate, chat, screen, insets, shot, attach, setAttach, draft, setDraft, busy, error, showDrafts, setShowDrafts, onSend, onMark, onClose, onNew, onDecide, onStartAll }) {
+  const scroll = useRef(null);
+  const drafts = draftsOf(chat);
+  const line = draftsLine(drafts);
+  const offer = offerOf(chat);
+  const banner = demoBanner(chat);
+  const msgs = chat?.messages || [];
+  return h(KeyboardAvoidingView, { behavior: Platform.OS === 'ios' ? 'padding' : undefined, style: s.sheetWrap, pointerEvents: 'box-none' },
+    h(View, { style: [s.sheet, { maxHeight: screen.height * 0.78, paddingBottom: Math.max(12, insets.bottom - 20) }], testID: 'ssb-sheet' },
+      h(View, { style: s.header },
+        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 }, '✕'))),
+      banner ? h(Pressable, {
+        testID: 'ssb-demo', disabled: !banner.url, onPress: () => banner.url && Linking.openURL(banner.url).catch(() => {}),
+        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,
+      line ? h(View, { style: s.bar },
+        h(Pressable, { onPress: () => setShowDrafts(!showDrafts), style: { flex: 1 }, accessibilityRole: 'button', accessibilityLabel: line }, h(Text, { style: s.barText }, `${line}  ${showDrafts ? '▴' : '▾'}`)),
+        drafts.waiting.length ? h(Pressable, { testID: 'ssb-start-all', onPress: onStartAll, disabled: busy, style: [s.primary, busy && s.disabled] }, h(Text, { style: s.primaryText }, 'Start working')) : null) : null,
+      showDrafts ? h(ScrollView, { style: s.drafts },
+        ...drafts.waiting.map((p) => h(View, { key: p.id, style: s.draft },
+          h(Text, { style: s.draftTitle }, p.title),
+          p.detail ? h(Text, { style: s.draftBody, numberOfLines: 4 }, p.detail) : null,
+          h(View, { style: s.row },
+            h(Pressable, { onPress: () => onDecide(p, 'dismiss'), disabled: busy, style: s.quiet }, h(Text, { style: s.quietText }, 'Dismiss')),
+            h(Pressable, { onPress: () => onDecide(p, 'raise'), disabled: busy, style: [s.primary, busy && s.disabled] }, h(Text, { style: s.primaryText }, 'Start'))))),
+        ...drafts.sent.map((p) => h(View, { key: p.id, style: s.draft },
+          h(Text, { style: s.draftTitle }, `✓ ${p.title}`),
+          p.jobUrl ? h(Pressable, { onPress: () => Linking.openURL(p.jobUrl).catch(() => {}) }, h(Text, { style: s.link }, 'Watch the job →')) : null))) : null,
+      h(ScrollView, { ref: scroll, style: s.thread, contentContainerStyle: { paddingVertical: 8 }, onContentSizeChange: () => scroll.current?.scrollToEnd({ animated: true }) },
+        msgs.length ? null : h(Text, { style: s.empty }, 'Say what should change on this screen, or tap Mark to point at 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 },
+        h(TextInput, {
+          testID: 'ssb-composer', value: draft, onChangeText: setDraft, multiline: true, placeholder: 'Ask SSB, or say what should change…',
+          placeholderTextColor: MUTED, style: s.input,
+        }),
+        h(View, { style: s.row },
+          shot ? h(Pressable, { onPress: () => setAttach(!attach), accessibilityRole: 'checkbox', accessibilityState: { checked: attach }, accessibilityLabel: 'Attach this screen', style: [s.chip, attach && s.chipOn] },
+            h(Image, { source: { uri: shot }, style: s.chipThumb }),
+            h(Text, { style: [s.chipText, attach && { color: BLUE }] }, attach ? 'Screen attached' : 'Attach screen')) : null,
+          h(Pressable, { testID: 'ssb-mark', onPress: onMark, accessibilityRole: 'button', accessibilityLabel: 'Mark the screen', style: s.chip }, h(Text, { style: s.chipText }, '◎ Mark')),
+          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.25, shadowRadius: 18, shadowOffset: { width: 0, height: 6 }, elevation: 12 };
+const s = StyleSheet.create({
+  root: { flex: 1 },
+  pressed: { opacity: 0.7 },
+  disabled: { opacity: 0.5 },
+  fab: { position: 'absolute', right: 16, width: 48, height: 48, borderRadius: 24, backgroundColor: BLUE, alignItems: 'center', justifyContent: 'center', ...shadow },
+  fabText: { color: '#fff', fontSize: 13, fontWeight: '800', letterSpacing: 0.5 },
+  dot: { position: 'absolute', top: 2, right: 2, width: 12, height: 12, borderRadius: 6, backgroundColor: RED, borderWidth: 2, borderColor: '#fff' },
+  pin: { position: 'absolute', borderRadius: 14, backgroundColor: RED, borderWidth: 2, borderColor: '#fff', alignItems: 'center', justifyContent: 'center', ...shadow },
+  pinText: { color: '#fff', fontSize: 13, fontWeight: '700' },
+  box: { position: 'absolute', borderWidth: 3, borderColor: BLUE, borderRadius: 6, backgroundColor: 'rgba(47,91,234,0.08)' },
+  hint: { position: 'absolute', alignSelf: 'center', flexDirection: 'row', alignItems: 'center', paddingVertical: 8, paddingHorizontal: 14, borderRadius: 18, backgroundColor: INK, ...shadow },
+  hintText: { color: '#fff', fontSize: 14, fontWeight: '600', marginRight: 12 },
+  hintLink: { color: '#9db1ff', fontSize: 14, fontWeight: '600' },
+  field: { position: 'absolute', left: 12, right: 12, height: 56, flexDirection: 'row', alignItems: 'center', paddingLeft: 14, paddingRight: 6, borderRadius: 14, backgroundColor: '#fff', ...shadow },
+  fieldInput: { flex: 1, fontSize: 16, color: INK },
+  sendRound: { width: 40, height: 40, borderRadius: 20, backgroundColor: BLUE, alignItems: 'center', justifyContent: 'center', marginLeft: 4 },
+  sendRoundText: { color: '#fff', fontSize: 20, fontWeight: '700' },
+  sheetWrap: { ...StyleSheet.absoluteFillObject, justifyContent: 'flex-end' },
+  sheet: { backgroundColor: '#fff', borderTopLeftRadius: 18, borderTopRightRadius: 18, ...shadow },
+  header: { flexDirection: 'row', alignItems: 'center', paddingTop: 14, paddingHorizontal: 16, paddingBottom: 10, borderBottomWidth: 1, borderBottomColor: LINE },
+  title: { fontSize: 16, fontWeight: '700', color: INK },
+  sub: { fontSize: 12, color: MUTED, marginTop: 2 },
+  bar: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 8, backgroundColor: '#fffaf0', borderBottomWidth: 1, borderBottomColor: '#f5d38a' },
+  barText: { fontSize: 13, fontWeight: '600', color: INK },
+  demo: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 10, backgroundColor: '#f0fdf4', borderBottomWidth: 1, borderBottomColor: LINE },
+  demoReady: { backgroundColor: BLUE },
+  demoText: { flex: 1, fontSize: 13, fontWeight: '600', color: INK },
+  demoGo: { color: '#fff', fontSize: 14, fontWeight: '800', marginLeft: 8 },
+  drafts: { maxHeight: 260, borderBottomWidth: 1, borderBottomColor: LINE },
+  draft: { paddingHorizontal: 16, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: LINE },
+  draftTitle: { fontSize: 14, fontWeight: '600', color: INK },
+  draftBody: { fontSize: 13, color: MUTED, marginTop: 4, lineHeight: 18 },
+  link: { color: BLUE, fontSize: 13, marginTop: 6 },
+  thread: { paddingHorizontal: 12, flexGrow: 0, minHeight: 80 },
+  empty: { color: MUTED, fontSize: 14, textAlign: 'center', paddingVertical: 18, paddingHorizontal: 12 },
+  bubble: { maxWidth: '86%', borderRadius: 14, paddingVertical: 8, paddingHorizontal: 12, marginVertical: 4 },
+  mine: { alignSelf: 'flex-end', backgroundColor: INK },
+  theirs: { alignSelf: 'flex-start', backgroundColor: '#f1f3f6' },
+  mineText: { color: '#fff', fontSize: 15, lineHeight: 20 },
+  theirsText: { color: INK, fontSize: 15, lineHeight: 20 },
+  thumb: { width: 140, height: 220, borderRadius: 8, marginBottom: 6, backgroundColor: '#0002' },
+  error: { color: RED, fontSize: 13, paddingHorizontal: 16, paddingTop: 6 },
+  composer: { paddingHorizontal: 12, paddingTop: 8, borderTopWidth: 1, borderTopColor: LINE },
+  input: { minHeight: 44, maxHeight: 120, fontSize: 16, color: INK, borderWidth: 1, borderColor: '#d1d5db', borderRadius: 12, paddingHorizontal: 12, paddingTop: 10, paddingBottom: 10 },
+  row: { flexDirection: 'row', alignItems: 'center', marginTop: 8, gap: 8 },
+  chip: { flexDirection: 'row', alignItems: 'center', paddingVertical: 6, paddingHorizontal: 10, borderRadius: 10, borderWidth: 1, borderColor: '#d1d5db' },
+  chipOn: { borderColor: BLUE, backgroundColor: '#e8eeff' },
+  chipThumb: { width: 16, height: 28, borderRadius: 3, marginRight: 6, backgroundColor: '#0002' },
+  chipText: { fontSize: 13, color: INK, fontWeight: '600' },
+  primary: { paddingVertical: 9, paddingHorizontal: 16, borderRadius: 10, backgroundColor: BLUE, minWidth: 64, alignItems: 'center' },
+  primaryText: { color: '#fff', fontSize: 14, fontWeight: '700' },
+  quiet: { paddingVertical: 6, paddingHorizontal: 10 },
+  quietText: { color: MUTED, fontSize: 14, fontWeight: '600' },
+  iconBtn: { width: 36, height: 36, alignItems: 'center', justifyContent: 'center' },
+  iconText: { color: MUTED, fontSize: 18 },
+});

package/src/core.js

@@ -0,0 +1,204 @@
+// 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 }),
+  };
+}
+
+/** A finished gesture on the screen, as a mark in fractions of the screen: a tap is a pin, a drag a box. */
+export function markOf({ x0, y0, x1, y1 }, screen) {
+  const fx = (v) => Math.min(1, Math.max(0, v / screen.width));
+  const fy = (v) => Math.min(1, Math.max(0, v / screen.height));
+  if (Math.hypot(x1 - x0, y1 - y0) < PIN_SLOP) return { kind: 'pin', x: fx(x1), y: fy(y1) };
+  const left = Math.min(x0, x1), top = Math.min(y0, y1);
+  return { kind: 'box', x: fx(left), y: fy(top), w: fx(Math.abs(x1 - x0)), h: fy(Math.abs(y1 - y0)) };
+}
+
+/** The mark's box on the screen, in points (a pin is a small square round its point). */
+export function markRect(mark, screen) {
+  const x = mark.x * screen.width, y = mark.y * screen.height;
+  if (mark.kind === 'box') return { left: x, top: y, width: mark.w * screen.width, height: mark.h * screen.height };
+  return { left: x - 14, top: y - 14, width: 28, height: 28 };
+}
+
+/** The point a mark is about: a pin's point, a box's middle. */
+export const markPoint = (mark, screen) => mark.kind === 'box'
+  ? { x: (mark.x + mark.w / 2) * screen.width, y: (mark.y + mark.h / 2) * screen.height }
+  : { x: mark.x * screen.width, y: mark.y * screen.height };
+
+/**
+ * Where the field beside the mark goes: just above the keyboard when that is
+ * clear of the mark, 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;
+}