@simon-says-build/ssb-overlay 0.7.0 → 0.9.0

package/README.md

@@ -26,4 +26,31 @@ import { captureScreen } from "react-native-view-shot";
 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).
 
+SSB opens as a bottom sheet (0.9.0): half way up with the chat, full screen
+with the work at the top. It needs `@gorhom/bottom-sheet` 5,
+`react-native-reanimated`, `react-native-worklets` and
+`react-native-gesture-handler` in the app (`npx expo install` them; the
+installer does).
+
+## Help, for everyone who uses the app (0.8.0)
+
+`<SsbHelp>` is the web Help widget's native twin (docs/HELPDESK.md): ANY
+signed-in user of the app asks how it works; SSB answers, and hands it to a
+person on the organization's help desk when it cannot help. It shows only
+where the organization switched its help desk on for the app.
+
+```tsx
+import { SsbHelp, SsbHelpChat, useSsbHelp } from "@simon-says-build/ssb-overlay";
+
+<SsbHelp appId="impulse-native" backend="firebase:impulse-mode"
+  getToken={() => auth.currentUser?.getIdToken() ?? null} sessionKey={user?.uid}
+  route={usePathname()} bubble={showHelpEverywhere}>
+  {/* the app */}
+</SsbHelp>
+
+// Where Help belongs in the app: `useSsbHelp().show` / `.unread`, a screen
+// rendering <SsbHelpChat onClose={router.back} />, and `bubble` for a Help
+// button on every screen (the person's own switch, kept by the app).
+```
+
 `npm test` runs the pure half.

package/index.d.ts

@@ -55,3 +55,34 @@ export function SsbHost(props: {
   bundle?: string;
   children?: ReactNode;
 }): ReactNode;
+
+/**
+ * Help for the app's OWN users (0.8.0, docs/HELPDESK.md): the web Help
+ * widget's native twin, on the same API and desk. Wrap the app's root; it
+ * renders `children` unchanged unless the help API lets this login ask (any
+ * login the app's backend verifies, where the organization switched its help
+ * desk on). Put Help where it belongs with `useSsbHelp()` and `<SsbHelpChat>`;
+ * `bubble` floats it on every screen.
+ */
+export function SsbHelp(props: {
+  appId?: string;
+  /** Where the app signs in: its Supabase URL, or `firebase:<projectId>`. */
+  backend?: string;
+  api?: string;
+  getToken: () => Promise<string | null | undefined>;
+  sessionKey?: string | null;
+  /** The current route: sent with each question, so the answer knows the screen. */
+  route?: string;
+  /** Float a Help button on every screen (the person's own switch). Default false. */
+  bubble?: boolean;
+  /** Keep the bubble above the tab bar. Default {bottom: 100}. */
+  insets?: { bottom?: number };
+  colors?: { accent?: string; background?: string; text?: string; muted?: string; bubble?: string; team?: string; line?: string };
+  children?: ReactNode;
+}): ReactNode;
+
+/** The Help conversation as a screen of the app's own. `onClose` shows a close button. */
+export function SsbHelpChat(props: { onClose?: () => void; title?: string }): ReactNode;
+
+/** Whether this login may ask Help, whether a reply waits unread, and open it full screen. */
+export function useSsbHelp(): { show: boolean; unread: boolean; open: () => void };

package/index.js

@@ -1,2 +1,4 @@
 export { SsbHost } from './src/SsbHost.js';
+export { SsbHelp, SsbHelpChat, useSsbHelp } from './src/SsbHelp.js';
+export { helpConfig, helpApi } from './src/help.js';
 export { overlayConfig, inAppApi, drawingMark, sendBody, ssbLinkOf } from './src/core.js';

package/install/install.mjs

@@ -18,8 +18,12 @@ const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return
 const json = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
 const exists = (p) => fs.existsSync(p);
 
-/** The packages an install adds (react-native-view-shot through `expo install`, so its version fits the SDK). */
-export const PACKAGES = ['@simon-says-build/ssb-overlay', '@simon-says-build/demo-player', 'react-native-view-shot'];
+/** The packages an install adds, through `expo install` so native versions fit the SDK:
+ *  react-native-view-shot for the screen, and the bottom sheet SSB opens in
+ *  (@gorhom/bottom-sheet with Reanimated, worklets and gesture-handler, 2026-10-22)
+ *  — an app that has them keeps its own versions. */
+export const PACKAGES = ['@simon-says-build/ssb-overlay', '@simon-says-build/demo-player', 'react-native-view-shot',
+  '@gorhom/bottom-sheet', 'react-native-reanimated', 'react-native-worklets', 'react-native-gesture-handler'];
 
 // ---- what the app is ----------------------------------------------------------
 /** Every fact the install decides by, read off the repo. Pure apart from reading files. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simon-says-build/ssb-overlay",
-  "version": "0.7.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.",
+  "version": "0.9.0",
+  "description": "SSB inside a native app SimonSays controls: the SSB button for the people who change the app (screenshot, mark, ask for a change), and Help for everyone who uses it.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/simon-says-studio/simon-says-build.git",
@@ -22,9 +22,12 @@
     "README.md"
   ],
   "peerDependencies": {
+    "@gorhom/bottom-sheet": "^5.2.0",
     "@simon-says-build/demo-player": ">=0.1.0",
     "react": ">=18",
-    "react-native": ">=0.76"
+    "react-native": ">=0.76",
+    "react-native-gesture-handler": ">=2.16",
+    "react-native-reanimated": ">=3.16"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"

package/src/SsbHelp.js

@@ -0,0 +1,165 @@
+// <SsbHelp>: Help for an app's OWN users, inside a native app — the web Help
+// widget's twin (web/public/help/widget.js, docs/HELPDESK.md), on the same API
+// and the same desk. Not <SsbHost>: that is SSB for the people who change the
+// app; this is for everyone who uses it (docs/TWO-ELEMENTS.md).
+//
+// Wrap the app's root in <SsbHelp>. It renders its children and nothing else
+// until the help API says this login may ask (`show`). Then:
+//   - `useSsbHelp()` gives the app `{ show, unread, open }`, to put Help where
+//     it belongs in the app (Impulse: the top of the chats list);
+//   - <SsbHelpChat /> is the conversation as a screen of the app's own;
+//   - `bubble` floats a Help button on every screen, opening the same
+//     conversation full screen — the app decides when (a switch the person sets).
+//
+// One conversation, held here, so the bubble and a screen show the same thread.
+// No JSX, so it needs nothing from the app's Babel setup beyond React Native's.
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  ActivityIndicator, KeyboardAvoidingView, Modal, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, View,
+} from 'react-native';
+import { canAskPerson, helpApi, helpConfig, helpPollEvery, helpSendBody, helpUnread, helpWho, ticketLine } from './help.js';
+
+const h = React.createElement;
+const DEFAULT_COLORS = { accent: '#2f5bea', background: '#ffffff', text: '#1f2430', muted: '#6b7280', bubble: '#f3f4f6', team: '#fef3c7', line: '#e5e7eb' };
+const DEFAULT_INSETS = { bottom: 100 };
+const Ctx = createContext({ show: false, unread: false, open: () => {} });
+
+/** `{ show, unread, open }`: whether this login may ask, a reply waiting, and open the conversation full screen. */
+export const useSsbHelp = () => useContext(Ctx);
+
+export function SsbHelp({ appId, backend, api: apiOrigin, getToken, sessionKey, route, bubble = false, insets, colors, children }) {
+  const config = useMemo(() => helpConfig({ appId, backend, api: apiOrigin }), [appId, backend, apiOrigin]);
+  const tokenRef = useRef(getToken);
+  tokenRef.current = getToken;
+  const api = useMemo(() => (config ? helpApi(config, () => tokenRef.current?.()) : null), [config]);
+  const [me, setMe] = useState(null);
+  const [thread, setThread] = useState({ messages: [], thinking: false, ticket: null });
+  const [screens, setScreens] = useState(0);          // <SsbHelpChat>s mounted: the conversation is open
+  const [modal, setModal] = useState(false);
+  const [seen, setSeen] = useState(0);
+  const open = screens > 0 || modal;
+  const C = { ...DEFAULT_COLORS, ...(colors || {}) };
+
+  // May this login ask? Again whenever the login changes.
+  useEffect(() => {
+    let live = true;
+    setMe(null);
+    if (!api) return undefined;
+    api.me().then((r) => { if (live) setMe(r?.show ? r : null); }).catch(() => { if (live) setMe(null); });
+    return () => { live = false; };
+  }, [api, sessionKey]);
+
+  const read = useCallback(async () => {
+    if (!api || !me?.exists || !me.chatId) return;
+    try {
+      const r = await api.chat(me.chatId);
+      setThread({ messages: r.messages || [], thinking: !!r.thinking, ticket: r.ticket || null });
+    } catch { /* the next poll */ }
+  }, [api, me]);
+  useEffect(() => {
+    if (!me) return undefined;
+    read();
+    const t = setInterval(read, helpPollEvery({ open, thinking: thread.thinking }));
+    return () => clearInterval(t);
+  }, [me, open, thread.thinking, read]);
+  useEffect(() => { if (open) setSeen(thread.messages.length); }, [open, thread.messages.length]);
+
+  const send = useCallback(async (text) => {
+    const r = await api.send(helpSendBody({ text, route, me }));
+    setMe((m) => ({ ...m, chatId: r.chatId, exists: true }));
+    setThread((t) => ({ messages: [...t.messages, { id: `local-${Date.now()}`, role: 'user', text: String(text).trim() }], thinking: !r.ticket, ticket: r.ticket || t.ticket }));
+  }, [api, route, me]);
+  const askPerson = useCallback(async () => {
+    const r = await api.escalate(me.chatId);
+    setThread((t) => ({ ...t, ticket: r.ticket || t.ticket }));
+    read();
+  }, [api, me, read]);
+
+  const value = useMemo(() => ({
+    show: !!me, unread: !open && helpUnread(thread.messages, seen), open: () => setModal(true),
+    me, thread, send, askPerson, colors: C, mount: () => { setScreens((n) => n + 1); return () => setScreens((n) => n - 1); },
+  }), [me, open, thread, seen, send, askPerson, C.accent]);   // eslint-disable-line react-hooks/exhaustive-deps
+
+  const bottom = (insets || DEFAULT_INSETS).bottom ?? DEFAULT_INSETS.bottom;
+  return h(Ctx.Provider, { value },
+    children,
+    me && bubble && !open ? h(Pressable, {
+      testID: 'ssb-help-bubble', accessibilityRole: 'button', accessibilityLabel: 'Help',
+      onPress: () => setModal(true), style: [s.bubble, { bottom, backgroundColor: C.accent }],
+    }, h(Text, { style: s.bubbleText }, '?'), value.unread ? h(View, { style: s.dot, testID: 'ssb-help-unread' }) : null) : null,
+    me ? h(Modal, { visible: modal, animationType: 'slide', presentationStyle: 'pageSheet', onRequestClose: () => setModal(false) },
+      h(SsbHelpChat, { onClose: () => setModal(false) })) : null,
+  );
+}
+
+/** The conversation, as a screen of the app's own (or the bubble's sheet). `onClose` shows a close button. */
+export function SsbHelpChat({ onClose, title }) {
+  const ctx = useContext(Ctx);
+  const { me, thread, send, askPerson, colors: C = DEFAULT_COLORS, mount } = ctx;
+  const [draft, setDraft] = useState('');
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState('');
+  const scroll = useRef(null);
+  useEffect(() => (mount ? mount() : undefined), []);   // eslint-disable-line react-hooks/exhaustive-deps
+  if (!me) return h(View, { style: [s.empty, { backgroundColor: C.background }] }, h(ActivityIndicator, null));
+  const msgs = thread.messages || [];
+  const line = ticketLine(thread.ticket || me.ticket);
+  const go = async () => {
+    const text = draft.trim();
+    if (!text || sending) return;
+    setSending(true); setError('');
+    try { await send(text); setDraft(''); } catch (e) { setError(e.message); }
+    setSending(false);
+  };
+  const person = async () => { setError(''); try { await askPerson(); } catch (e) { setError(e.message); } };
+  const first = (me.requester?.label || '').split(/[ @]/)[0];
+  return h(KeyboardAvoidingView, { style: [s.root, { backgroundColor: C.background }], behavior: Platform.OS === 'ios' ? 'padding' : undefined, testID: 'ssb-help-chat' },
+    h(View, { style: [s.header, { borderBottomColor: C.line }] },
+      h(Text, { style: [s.title, { color: C.text }] }, title || `Help${me.app?.name ? ` · ${me.app.name}` : ''}`),
+      onClose ? h(Pressable, { onPress: onClose, accessibilityLabel: 'Close', testID: 'ssb-help-close', hitSlop: 12 }, h(Text, { style: [s.close, { color: C.muted }] }, '✕')) : null),
+    line ? h(Text, { style: [s.ticket, { color: C.accent, borderBottomColor: C.line }], testID: 'ssb-help-ticket' }, line) : null,
+    h(ScrollView, { ref: scroll, style: s.body, contentContainerStyle: s.bodyIn, onContentSizeChange: () => scroll.current?.scrollToEnd?.({ animated: true }) },
+      msgs.length ? null : h(Text, { style: [s.msg, s.left, { backgroundColor: C.bubble, color: C.text }] },
+        `Hi${first ? ` ${first}` : ''} — ask anything about ${me.app?.name || 'the app'}. If I can't help, I'll get you a person.`),
+      ...msgs.map((m) => (m.role === 'event'
+        ? h(Text, { key: m.id, style: [s.event, { color: C.muted }] }, m.text)
+        : h(View, { key: m.id, style: m.role === 'user' ? s.rightWrap : s.leftWrap },
+          h(Text, { style: [s.who, { color: C.muted }] }, helpWho(m)),
+          h(Text, { style: [s.msg, m.role === 'user' ? { backgroundColor: C.accent, color: '#fff' } : { backgroundColor: m.role === 'agent' ? C.team : C.bubble, color: C.text }] }, m.text)))),
+      thread.thinking ? h(Text, { style: [s.event, { color: C.muted, fontStyle: 'italic' }], testID: 'ssb-help-thinking' }, 'Thinking…') : null),
+    h(View, { style: [s.footer, { borderTopColor: C.line }] },
+      error ? h(Text, { style: s.error }, error) : null,
+      h(View, { style: s.row },
+        h(TextInput, { value: draft, onChangeText: setDraft, placeholder: 'How do I…', placeholderTextColor: C.muted, multiline: true, testID: 'ssb-help-input', style: [s.input, { color: C.text, borderColor: C.line }] }),
+        h(Pressable, { onPress: go, disabled: sending || !draft.trim(), testID: 'ssb-help-send', style: [s.send, { backgroundColor: C.accent }, (sending || !draft.trim()) && s.disabled] },
+          h(Text, { style: s.sendText }, sending ? '…' : 'Send'))),
+      canAskPerson(msgs, thread.ticket || me.ticket) ? h(Pressable, { onPress: person, testID: 'ssb-help-person' }, h(Text, { style: [s.person, { color: C.accent }] }, 'Talk to a person')) : null));
+}
+
+const s = StyleSheet.create({
+  root: { flex: 1 },
+  empty: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  header: { flexDirection: 'row', alignItems: 'center', paddingHorizontal: 16, paddingVertical: 14, borderBottomWidth: 1 },
+  title: { flex: 1, fontSize: 17, fontWeight: '700' },
+  close: { fontSize: 20 },
+  ticket: { paddingHorizontal: 16, paddingVertical: 8, fontSize: 13, borderBottomWidth: 1 },
+  body: { flex: 1 },
+  bodyIn: { padding: 16, gap: 8 },
+  leftWrap: { alignItems: 'flex-start' },
+  rightWrap: { alignItems: 'flex-end' },
+  left: { alignSelf: 'flex-start' },
+  who: { fontSize: 11, marginBottom: 2 },
+  msg: { maxWidth: '85%', paddingVertical: 8, paddingHorizontal: 12, borderRadius: 14, fontSize: 15, lineHeight: 21, overflow: 'hidden' },
+  event: { fontSize: 12, textAlign: 'center', marginVertical: 4 },
+  footer: { borderTopWidth: 1, padding: 10, gap: 6 },
+  row: { flexDirection: 'row', alignItems: 'flex-end', gap: 8 },
+  input: { flex: 1, minHeight: 44, maxHeight: 120, borderWidth: 1, borderRadius: 12, paddingHorizontal: 12, paddingVertical: 10, fontSize: 15 },
+  send: { paddingHorizontal: 16, height: 44, borderRadius: 12, alignItems: 'center', justifyContent: 'center' },
+  sendText: { color: '#fff', fontWeight: '700', fontSize: 15 },
+  disabled: { opacity: 0.5 },
+  person: { fontSize: 13, fontWeight: '600' },
+  error: { color: '#b91c1c', fontSize: 13 },
+  bubble: { position: 'absolute', right: 16, width: 52, height: 52, borderRadius: 26, alignItems: 'center', justifyContent: 'center', shadowColor: '#000', shadowOpacity: 0.25, shadowRadius: 10, shadowOffset: { width: 0, height: 4 }, elevation: 6 },
+  bubbleText: { color: '#fff', fontSize: 24, fontWeight: '800' },
+  dot: { position: 'absolute', top: 2, right: 2, width: 12, height: 12, borderRadius: 6, backgroundColor: '#ef4444', borderWidth: 2, borderColor: '#fff' },
+});

package/src/SsbHost.js

@@ -4,10 +4,9 @@
 // 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
+// Tapping it takes a picture of the screen as it is and opens SSB as a SHEET,
+// half way up (2026-10-22: it opened full screen from 2026-10-20 until then);
+// pulled up it is full screen, with 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
@@ -20,15 +19,18 @@
 // 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,
-  NativeModules, ScrollView, StyleSheet, Text, TextInput, View, useWindowDimensions,
+  ActivityIndicator, Image, Keyboard, Linking, PanResponder, Platform, Pressable,
+  NativeModules, StyleSheet, Text, TextInput, View, useWindowDimensions,
 } from 'react-native';
 // The app's demo player (a peer): ▶ Demo hands it the demo to play in this
 // build. An older player has no playDemo, and the button is not offered.
 import { playDemo, PLAYER_VERSION } from '@simon-says-build/demo-player';
+// The sheet (see Panel): peers the app already carries.
+import BottomSheet, { BottomSheetBackdrop, BottomSheetFooter, BottomSheetScrollView, BottomSheetTextInput } from '@gorhom/bottom-sheet';
+import { GestureHandlerRootView, ScrollView } from 'react-native-gesture-handler';
 import {
   FAB, addPoint, clampFab, demoBanner, fabHome, isDrag, describeHost, draftsOf, fieldTop, inAppApi, namedHosts, newReply, offerOf,
-  STATE_WORD, boxItem, bundleOriginOf, clientInfo, elsewhereLine, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
+  STATE_WORD, workSummary, boxItem, bundleOriginOf, clientInfo, elsewhereLine, workView, drawingBox, drawingMark, drawingPoint, itemRect, overlayConfig, pollEvery, SNAPSHOT_TOPIC, snapshotOf, talkLine, segmentsOf, sendBody, smallestAt, ssbLinkOf,
 } from './core.js';
 
 const h = React.createElement;
@@ -208,19 +210,20 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
 
   const open = mode !== 'idle';
   useEffect(() => { if (open) load(); }, [open, chatId]);
-  // The top of the panel: the app's work, asked when it opens and while it stays open.
+  // The top of the panel: THIS CONVERSATION's work (2026-10-22: not every job
+  // on the app, whoever asked), asked when it opens and while it stays open.
   const loadWork = useCallback(async () => {
-    try { const r = await ssb.work(here); setWork(r?.inFlight || []); setElsewhere(r?.readyElsewhere || []); } catch { /* the last list stands */ }
-  }, [ssb, here]);
+    try { const r = await ssb.work(here, chatId || ''); setWork(r?.inFlight || []); setElsewhere(r?.readyElsewhere || []); } catch { /* the last list stands */ }
+  }, [ssb, here, chatId]);
   // ▶ Demo: one demo of everything Ready in this build, played by this build.
   const startDemo = useCallback(async () => {
     setBusy(true); setError(null);
     try {
-      const r = await ssb.demo(here);
+      const r = await ssb.demo(here, chatId || '');
       if (!playDemo({ id: r.demoId, token: r.token, api: config.api, here: true })) throw new Error('the demo could not start');
       Keyboard.dismiss(); setMode('idle');
     } catch (e) { setError(e.message); } finally { setBusy(false); }
-  }, [ssb, here, config.api]);
+  }, [ssb, here, config.api, chatId]);
   useEffect(() => {
     if (mode !== 'sheet' || !gate) return undefined;
     loadWork();
@@ -498,8 +501,27 @@ function Host({ config, getToken, sessionKey, route, capture, storage, pushToken
     h(View, { ref: chromeRef, collapsable: false, pointerEvents: 'box-none', style: StyleSheet.absoluteFill }, chrome));
 }
 
+// THE SHEET (2026-10-22, Michael: "a compact chat as a sheet, where you can
+// expand fully, which shows the persistent panel at the top"). It opens HALF
+// way: the conversation and the composer, with the app still showing above
+// it and the work as one line (workSummary). Pulled up — or the line, or ⌃,
+// tapped — it is the full screen it used to open as, with THE WORK at the top.
+// Pulled down from half, or the backdrop tapped, it closes.
+//
+// @gorhom/bottom-sheet (a peer, with Reanimated and gesture-handler — both
+// apps the overlay ships in already carry all three): its snap points, its
+// keyboard handling (the composer is its TextInput, so the sheet rides the
+// keyboard) and its footer, which keeps the composer on the sheet's visible
+// bottom edge at either height. Its own GestureHandlerRootView, so it works
+// wherever the app put <SsbHost>.
+const SNAPS = ['50%', '100%'];
+const COMPACT = 0, FULL = 1;
+
 function Panel({ gate, chat, work, elsewhere, onDemo, screen, insets, draft, setDraft, busy, error, onSend, onDraw, onClose, onNew, onDecide, onStartAll, onOpenLink, canTalk, talk, onTalk, onEndTalk, onMute }) {
+  const sheet = useRef(null);
   const scroll = useRef(null);
+  const [at, setAt] = useState(COMPACT);
+  const [footH, setFootH] = useState(120);
   const [open, setOpen] = useState(null);            // the draft whose detail is shown
   const { flying, waiting, sent } = workView({ inFlight: work, chat });
   const offer = offerOf(chat);
@@ -508,80 +530,110 @@ function Panel({ gate, chat, work, elsewhere, onDemo, screen, insets, draft, set
   const ready = flying.filter((x) => x.state === 'ready');
   const away = elsewhereLine(elsewhere);
   const hasWork = flying.length || waiting.length || sent.length || banner || away;
+  const summary = workSummary({ flying, waiting });
+  const full = at === FULL;
   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 }, '✕'))),
-      // 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(View, { style: s.sectionRow },
-          h(Text, { style: [s.section, { flex: 1 }], testID: 'ssb-section-flight' }, 'In flight'),
-          ready.length && onDemo ? h(Pressable, { testID: 'ssb-demo-ready', onPress: onDemo, disabled: busy, accessibilityRole: 'button', accessibilityLabel: `Demo what is ready in this build (${ready.length})`, style: [s.primary, s.small, busy && s.disabled] },
-            h(Text, { style: s.primaryText }, `▶ Demo (${ready.length})`)) : null) : null,
-        // A row opens its job in the SimonSays app, the console when that app
-        // is not on the phone (functions/in-app.mjs jobLinksFor) — for those
-        // who can open it there; anyone else's rows stay plain.
-        ...flying.map((x) => h(x.links ? Pressable : View, {
-          key: `f${x.id}`, style: s.workRow, testID: `ssb-flight-${x.id}`,
-          ...(x.links ? { onPress: () => onOpenLink(x.links.app, x.links.web), accessibilityRole: 'link', accessibilityLabel: `Open in SimonSays: ${x.title}` } : {}),
-        },
-          h(Text, { style: s.workTitle, numberOfLines: 2 }, x.links ? `${x.title} ›` : x.title),
-          showMe(x)
-            ? h(Pressable, { onPress: () => onOpenLink(showMe(x)), accessibilityRole: 'button', accessibilityLabel: `Show me: ${x.title}`, style: [s.primary, s.small] }, h(Text, { style: s.primaryText }, '▶ Show me'))
-            : h(Text, { style: [s.state, s[`state_${x.state}`]] }, STATE_WORD[x.state] || x.state))),
-        away ? h(Text, { style: [s.draftBody, { paddingHorizontal: 16, paddingVertical: 8 }], testID: 'ssb-ready-elsewhere' }, away) : null,
-        waiting.length ? h(View, { style: s.sectionRow },
-          h(Text, { style: [s.section, { flex: 1 }] }, 'Drafts'),
-          waiting.length > 1 ? h(Pressable, { testID: 'ssb-start-all', onPress: onStartAll, disabled: busy, accessibilityRole: 'button', accessibilityLabel: 'Start all', style: [s.primary, s.small, busy && s.disabled] }, h(Text, { style: s.primaryText }, `Start all (${waiting.length})`)) : null) : null,
-        ...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,
-      // THE COMPOSER, or while talking the voice controls in its place: voice is
-      // the other way to say it, so Hang up sits where Send does.
-      h(View, { style: [s.composer, { paddingBottom: Math.max(12, insets.bottom > 60 ? 16 : insets.bottom) }] },
-        talk ? h(View, { style: s.talkBar, testID: 'ssb-talk-bar' },
-          h(View, { style: [s.talkDot, talk.status !== 'live' && { backgroundColor: MUTED }] }),
-          h(Text, { style: s.talkText }, talkLine(talk))) : h(TextInput, {
-          testID: 'ssb-composer', value: draft, onChangeText: setDraft, multiline: true, placeholder: 'Ask SSB, or say what should change…',
-          placeholderTextColor: MUTED, keyboardAppearance: 'dark', style: s.input,
-        }),
-        h(View, { style: s.row },
-          h(Pressable, { testID: 'ssb-draw', onPress: onDraw, accessibilityRole: 'button', accessibilityLabel: 'Draw on the screen', style: s.chip }, h(Text, { style: s.chipText }, '✎ Draw')),
-          canTalk && !talk ? h(Pressable, { testID: 'ssb-talk', onPress: onTalk, accessibilityRole: 'button', accessibilityLabel: 'Talk to SSB', style: s.chip }, h(Text, { style: s.chipText }, '🎙 Talk')) : null,
-          talk ? h(Pressable, { testID: 'ssb-mute', onPress: onMute, accessibilityRole: 'button', accessibilityLabel: talk.muted ? 'Unmute' : 'Mute', style: s.chip }, h(Text, { style: s.chipText }, talk.muted ? 'Unmute' : 'Mute')) : null,
-          h(View, { style: { flex: 1 } }),
-          talk
-            ? h(Pressable, { testID: 'ssb-hangup', onPress: onEndTalk, accessibilityRole: 'button', accessibilityLabel: 'End the talk', style: [s.primary, s.hangup] }, h(Text, { style: s.primaryText }, 'Hang up'))
-            : h(Pressable, { testID: 'ssb-send', onPress: onSend, disabled: !draft.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.primary, (!draft.trim() || busy) && s.disabled] },
-              busy ? h(ActivityIndicator, { size: 'small', color: '#fff' }) : h(Text, { style: s.primaryText }, 'Send'))))));
+  const snap = (i) => sheet.current?.snapToIndex(i);
+
+  const backdrop = useCallback((p) => h(BottomSheetBackdrop, { ...p, appearsOnIndex: COMPACT, disappearsOnIndex: -1, opacity: 0.45, pressBehavior: 'close' }), []);
+
+  // THE COMPOSER, or while talking the voice controls in its place: voice is
+  // the other way to say it, so Hang up sits where Send does.
+  const composer = h(View, { style: [s.composer, { paddingBottom: Math.max(12, insets.bottom > 60 ? 16 : insets.bottom) }], onLayout: (e) => setFootH(e.nativeEvent.layout.height) },
+    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(BottomSheetTextInput, {
+      testID: 'ssb-composer', value: draft, onChangeText: setDraft, multiline: true, placeholder: 'Ask SSB, or say what should change…',
+      placeholderTextColor: MUTED, keyboardAppearance: 'dark', style: s.input,
+    }),
+    h(View, { style: s.row },
+      h(Pressable, { testID: 'ssb-draw', onPress: onDraw, accessibilityRole: 'button', accessibilityLabel: 'Draw on the screen', style: s.chip }, h(Text, { style: s.chipText }, '✎ Draw')),
+      canTalk && !talk ? h(Pressable, { testID: 'ssb-talk', onPress: onTalk, accessibilityRole: 'button', accessibilityLabel: 'Talk to SSB', style: s.chip }, h(Text, { style: s.chipText }, '🎙 Talk')) : null,
+      talk ? h(Pressable, { testID: 'ssb-mute', onPress: onMute, accessibilityRole: 'button', accessibilityLabel: talk.muted ? 'Unmute' : 'Mute', style: s.chip }, h(Text, { style: s.chipText }, talk.muted ? 'Unmute' : 'Mute')) : null,
+      h(View, { style: { flex: 1 } }),
+      talk
+        ? h(Pressable, { testID: 'ssb-hangup', onPress: onEndTalk, accessibilityRole: 'button', accessibilityLabel: 'End the talk', style: [s.primary, s.hangup] }, h(Text, { style: s.primaryText }, 'Hang up'))
+        : h(Pressable, { testID: 'ssb-send', onPress: onSend, disabled: !draft.trim() || busy, accessibilityRole: 'button', accessibilityLabel: 'Send to SSB', style: [s.primary, (!draft.trim() || busy) && s.disabled] },
+          busy ? h(ActivityIndicator, { size: 'small', color: '#fff' }) : h(Text, { style: s.primaryText }, 'Send'))));
+  // The footer is a component TYPE to the sheet: a new function per keystroke
+  // remounted the text box after every letter (the harness sent "T" for a
+  // sentence). So it is made once, and the composer reaches it by context.
+  const footer = useCallback((p) => h(BottomSheetFooter, p, h(ComposerSlot)), []);
+
+  // THE WORK, at the top of the full sheet: in flight, then drafts to start, then what this chat started.
+  const workList = 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(View, { style: s.sectionRow },
+      h(Text, { style: [s.section, { flex: 1 }], testID: 'ssb-section-flight' }, 'In flight'),
+      ready.length && onDemo ? h(Pressable, { testID: 'ssb-demo-ready', onPress: onDemo, disabled: busy, accessibilityRole: 'button', accessibilityLabel: `Demo what is ready in this build (${ready.length})`, style: [s.primary, s.small, busy && s.disabled] },
+        h(Text, { style: s.primaryText }, `▶ Demo (${ready.length})`)) : null) : null,
+    // A row opens its job in the SimonSays app, the console when that app
+    // is not on the phone (functions/in-app.mjs jobLinksFor) — for those
+    // who can open it there; anyone else's rows stay plain.
+    ...flying.map((x) => h(x.links ? Pressable : View, {
+      key: `f${x.id}`, style: s.workRow, testID: `ssb-flight-${x.id}`,
+      ...(x.links ? { onPress: () => onOpenLink(x.links.app, x.links.web), accessibilityRole: 'link', accessibilityLabel: `Open in SimonSays: ${x.title}` } : {}),
+    },
+      h(Text, { style: s.workTitle, numberOfLines: 2 }, x.links ? `${x.title} ›` : x.title),
+      showMe(x)
+        ? h(Pressable, { onPress: () => onOpenLink(showMe(x)), accessibilityRole: 'button', accessibilityLabel: `Show me: ${x.title}`, style: [s.primary, s.small] }, h(Text, { style: s.primaryText }, '▶ Show me'))
+        : h(Text, { style: [s.state, s[`state_${x.state}`]] }, STATE_WORD[x.state] || x.state))),
+    away ? h(Text, { style: [s.draftBody, { paddingHorizontal: 16, paddingVertical: 8 }], testID: 'ssb-ready-elsewhere' }, away) : null,
+    waiting.length ? h(View, { style: s.sectionRow },
+      h(Text, { style: [s.section, { flex: 1 }] }, 'Drafts'),
+      waiting.length > 1 ? h(Pressable, { testID: 'ssb-start-all', onPress: onStartAll, disabled: busy, accessibilityRole: 'button', accessibilityLabel: 'Start all', style: [s.primary, s.small, busy && s.disabled] }, h(Text, { style: s.primaryText }, `Start all (${waiting.length})`)) : null) : null,
+    ...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'))));
+
+  // Half open: the work is one line, and a ready demo keeps its button —
+  // it is the thing most worth a tap.
+  const compactWork = (summary || banner) ? h(Pressable, { testID: 'ssb-work-summary', onPress: () => snap(FULL), accessibilityRole: 'button', accessibilityLabel: `Show the work: ${summary || banner.text}`, style: s.summary },
+    h(Text, { style: s.summaryText, numberOfLines: 1 }, summary || banner.text),
+    banner?.url ? h(Pressable, { testID: 'ssb-demo', onPress: () => onOpenLink(banner.url), accessibilityRole: 'button', style: [s.primary, s.small] }, h(Text, { style: s.primaryText }, '▶ See it')) : null,
+    h(Text, { style: s.summaryGo }, '⌃')) : null;
+
+  return h(GestureHandlerRootView, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none' },
+    h(ComposerCtx.Provider, { value: composer }, h(BottomSheet, {
+      ref: sheet, index: COMPACT, snapPoints: SNAPS, enableDynamicSizing: false, enablePanDownToClose: true,
+      topInset: insets.top, onChange: (i) => { if (i >= 0) setAt(i); }, onClose,
+      backdropComponent: backdrop, footerComponent: footer,
+      keyboardBehavior: 'interactive', keyboardBlurBehavior: 'restore', android_keyboardInputMode: 'adjustResize',
+      backgroundStyle: s.sheetBg, handleIndicatorStyle: s.grabber,
+    },
+      h(View, { style: { flex: 1 }, testID: 'ssb-panel' },
+        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, { testID: full ? 'ssb-collapse' : 'ssb-expand', onPress: () => snap(full ? COMPACT : FULL), accessibilityRole: 'button', accessibilityLabel: full ? 'Make SSB smaller' : 'Open SSB full screen', style: s.iconBtn }, h(Text, { style: s.iconText }, full ? '⌄' : '⌃')),
+          h(Pressable, { testID: 'ssb-close', onPress: () => sheet.current?.close(), accessibilityRole: 'button', accessibilityLabel: 'Close SSB', style: s.iconBtn }, h(Text, { style: s.iconText }, '✕'))),
+        full ? (hasWork ? workList : null) : compactWork,
+        // THE CONVERSATION, below; the footer (the composer) floats over its end.
+        h(BottomSheetScrollView, { ref: scroll, style: s.thread, contentContainerStyle: { paddingTop: 8, paddingBottom: footH + 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)))));
 }
+const ComposerCtx = React.createContext(null);
+const ComposerSlot = () => React.useContext(ComposerCtx);
 
 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 } });
@@ -611,8 +663,12 @@ const s = StyleSheet.create({
   // 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 },
+  sheetBg: { backgroundColor: BG, borderTopLeftRadius: 22, borderTopRightRadius: 22, borderWidth: 1, borderColor: LINE },
+  grabber: { backgroundColor: MUTED, width: 40 },
+  summary: { flexDirection: 'row', alignItems: 'center', gap: 10, paddingHorizontal: 16, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: LINE, backgroundColor: SURFACE },
+  summaryText: { flex: 1, fontSize: 13, fontWeight: '700', color: TEXT },
+  summaryGo: { color: MUTED, fontSize: 16, fontWeight: '800' },
+  header: { flexDirection: 'row', alignItems: 'center', gap: 12, paddingTop: 4, 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 },

package/src/core.js

@@ -5,7 +5,7 @@
 export const DEFAULT_API = 'https://simonsays.build';
 // What this overlay is, said when it registers for pushes (clientInfo below).
 // Kept equal to package.json by test/core.test.mjs.
-export const OVERLAY_VERSION = '0.7.0';
+export const OVERLAY_VERSION = '0.9.0';
 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
@@ -49,8 +49,12 @@ export function inAppApi(config, getToken, fetchImpl = globalThis.fetch) {
     voice: (body) => post('/voice', body),
     // `bundle`: where this app's JS came from (a preview's tunnel), so SSB
     // scopes Ready to this build; undefined = the whole list, as before.
-    work: (bundle) => call(bundle === undefined ? '/work' : `/work?bundle=${encodeURIComponent(bundle)}`),
-    demo: (bundle) => post('/demo', { bundle }),
+    // `chat`: only this conversation's work ("" before there is one: nothing).
+    work: (bundle, chat) => {
+      const q = [bundle === undefined ? null : `bundle=${encodeURIComponent(bundle)}`, chat === undefined ? null : `chat=${encodeURIComponent(chat || '')}`].filter(Boolean);
+      return call(q.length ? `/work?${q.join('&')}` : '/work');
+    },
+    demo: (bundle, chatId) => post('/demo', { bundle, ...(chatId !== undefined ? { chatId: chatId || '' } : {}) }),
   };
 }
 
@@ -316,6 +320,22 @@ export function workView({ inFlight = [], chat = null } = {}) {
   return { flying, waiting, sent: sent.filter((p) => !p.jobId || !flyingIds.has(p.jobId)) };
 }
 
+// The COMPACT sheet's one line about the work (2026-10-22): the full sheet
+// lists it at the top; half-open, the chat has the room and the work is a
+// line that says how much there is — tap it, or pull the sheet up, to see it.
+// Ready first (it is what to look at), then the rest by state, then drafts.
+// "" when there is nothing, so the line is not drawn.
+export function workSummary({ flying = [], waiting = [] } = {}) {
+  const n = {};
+  for (const x of flying) n[x.state] = (n[x.state] || 0) + 1;
+  const parts = ['ready', 'building', 'checking', 'queued', 'blocked']
+    .filter((k) => n[k]).map((k) => `${n[k]} ${(STATE_WORD[k] || k).toLowerCase()}`);
+  const other = flying.length - parts.reduce((a, p) => a + Number(p.split(' ')[0]), 0);
+  if (other > 0) parts.push(`${other} in flight`);
+  if (waiting.length) parts.push(`${waiting.length} draft${waiting.length === 1 ? '' : 's'} to start`);
+  return parts.join(' · ');
+}
+
 // READY IS THIS BUILD (2026-10-20, docs/IN-APP-SSB.md): the origin the app's
 // JS bundle was loaded from — a preview's tunnel — or "" for a build that
 // loads from a file (a store or local build, which holds no SSB preview).

package/src/help.js

@@ -0,0 +1,76 @@
+// HELP for an app's own users, the pure half (no React Native here, so
+// node --test runs it). The web Help widget's native twin
+// (web/public/help/widget.js, docs/HELPDESK.md): the same API, the same
+// conversation, the same desk. The server is functions/help-widget.mjs: ANY
+// login the app's backend verifies is let in (this is a customer asking for
+// help, not someone changing the app), only where the app's organization
+// switched its help desk on. A native app sends no Origin, so no CORS applies.
+
+import { DEFAULT_API } from './core.js';
+
+/** The Help settings, or null when they are not set (Help renders nothing). */
+export function helpConfig({ appId, backend, api } = {}) {
+  if (!appId || !backend) return null;
+  return { appId: String(appId), backend: String(backend).replace(/\/+$/, ''), api: String(api || DEFAULT_API).replace(/\/+$/, '') };
+}
+
+/** The help API (/api/help/:appId/*). Every call carries the app's CURRENT session token. */
+export function helpApi(config, getToken, fetchImpl = globalThis.fetch) {
+  const base = `${config.api}/api/help/${encodeURIComponent(config.appId)}`;
+  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(`${base}${path}`, {
+      ...init,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}`, 'x-ssb-backend': config.backend, ...(init.headers || {}) },
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) { const e = new Error(json.error || `Help 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('/messages', body),
+    chat: (id) => call(`/chats/${encodeURIComponent(id)}`),
+    escalate: (chatId) => post('/escalate', { chatId }),
+  };
+}
+
+/** What a message to Help carries: the words, and where in the app they were. */
+export function helpSendBody({ text, route, me }) {
+  return {
+    text: String(text || '').trim().slice(0, 6000),
+    ...(route ? { url: `app:${String(route).slice(0, 400)}` } : {}),
+    ...(me?.exists && me.chatId ? { chatId: me.chatId } : {}),
+  };
+}
+
+/** How often to read the thread: often while SSB thinks, less while open, rarely closed. */
+export function helpPollEvery({ open, thinking }) {
+  if (open) return thinking ? 2500 : 6000;
+  return 30000;
+}
+
+/** Who says a message, as the panel labels it. */
+export function helpWho(m) {
+  if (m.role === 'user') return 'You';
+  if (m.role === 'agent') return `${m.byLabel || 'Support'} · team`;
+  return 'Assistant';
+}
+
+/** The line under the header while a person has the conversation, or ''. */
+export function ticketLine(ticket) {
+  if (!ticket) return '';
+  if (ticket.status === 'solved') return 'Solved — ask anything new.';
+  return `A person${ticket.orgName ? ` from ${ticket.orgName}` : ''} has this${ticket.assignee ? ` · ${ticket.assignee}` : ''}`;
+}
+
+/** "Talk to a person" is offered once there is a conversation and nobody has it. */
+export const canAskPerson = (messages, ticket) => (messages || []).length > 0 && (!ticket || ticket.status === 'solved');
+
+/** A reply landed while the panel was closed (the bubble's dot). */
+export function helpUnread(messages, seen) {
+  const list = messages || [];
+  return list.length > seen && list[list.length - 1]?.role !== 'user';
+}