@unifedev/thread-pages 0.3.2 → 1.1.0

package/ARCHITECTURE.md

@@ -1,230 +0,0 @@
-# Architecture
-
-Version 0.3.0 · September 2026
-
-This is the design and its reasoning. [docs/MODEL.md](./docs/MODEL.md) is the
-operator's view — where things are stored and how to reach them.
-[docs/ROADMAP.md](./docs/ROADMAP.md) is what is left.
-
-## Intent
-
-A Thread Page is a small application an agent writes for one task, for one
-person to read and answer from.
-
-Chat is a poor medium for the moments that matter: a comparison, a diagram, a set
-of choices, a thing only the user can decide. Those want a page. But a *fixed*
-page — a dashboard with slots — is worse than chat, because the shape of what
-needs saying changes with every task.
-
-So the plugin supplies no design. It supplies a secure host for a document the
-agent writes freshly each time, and a way for that document to talk back.
-
-Three properties follow, and everything else is downstream of them:
-
-1. **The page is a file the agent edits directly.** Not a template it fills, not
-   an API it posts to. Saving is publishing.
-2. **The agent's contract stays small.** One command, a short instruction, and
-   an optional guide it fetches only when the page needs more than prose.
-3. **Page code is untrusted.** It is generated, so it is sandboxed and given
-   narrow named capabilities rather than credentials.
-
-## The shape
-
-```
-~/.bb/thread-storage/<threadId>/thread-page.html     the page
-                              /thread-page-assets/   what it shows
-                              /thread-page-uploads/  what the user sent
-```
-
-An agent runs `bb thread-page init`, gets that path, and edits the file. The
-plugin serves it at a stable URL on the bb origin the user is already
-authenticated to — so the same link works on a laptop and a phone with no extra
-port, tunnel, or password.
-
-Nothing else is stored. Two small values live in bb's existing key-value table: a
-signing key, so open browser sessions survive a plugin reload, and a best-effort
-last-good copy per page, so a page still opens read-only when its machine is
-offline. There is no plugin database and no background service.
-
-## Trust boundary
-
-The page is generated code, so it is treated as hostile.
-
-**Inside the iframe** — `sandbox="allow-scripts allow-forms"`, opaque origin.
-Arbitrary HTML, CSS and JavaScript are allowed *because* the frame has no bb
-cookie, no mutation token, no parent DOM, no `localStorage`, no raw bb API, no
-CLI, and no filesystem access. CSP blocks ordinary `fetch` and subresources.
-Page-authored code can therefore be as creative as the task needs without that
-creativity being a security question.
-
-**Outside the iframe** — plugin-authored code on the bb origin. It holds the
-action token, makes the same-origin calls, owns navigation, and renders
-confirmations. The document URL carries render authority only, so page code never
-sees a credential that can change anything.
-
-**Between them** — one `MessagePort` and a fixed capability list. Each capability
-has its own validator, size and depth limits, effect class, and output
-projection. There is no generic "call bb" method, no path parameter, and no
-provider passthrough.
-
-### Confirmed effects
-
-Anything that reaches outside the current thread requires a confirmation the page
-cannot fake or word:
-
-1. The page invokes the method.
-2. The server refuses once, returning a signed challenge that carries **its own**
-   summary, derived from validated parameters.
-3. The trusted shell shows that summary in a dialog the sandbox cannot draw over.
-4. The server verifies the signature before acting.
-
-The challenge is bound to one request id, method, parameter fingerprint, page
-revision and thread, and expires in two minutes. So it cannot be forged, replayed,
-or reused to approve different parameters — a page cannot get "message thread A"
-approved and then quietly reuse it for thread B.
-
-### The honest limitation
-
-Page JavaScript can navigate its own frame and encode data in the destination
-URL. Browser sandbox flags do not close that channel, and CSP resource directives
-do not either. A page therefore has access to data already inside its own frame.
-
-It grants no bb authority. Closing it entirely would mean forbidding authored
-JavaScript and shipping a declarative renderer instead, which would cost the
-open-page model that is the point of the product. This is a stated trade, not an
-oversight.
-
-## Capabilities
-
-| Method | Effect | Confirmed |
-| --- | --- | --- |
-| `context.get` | read | |
-| `thread.activity` | read | |
-| `threads.snapshot` | read | |
-| `projects.list` | read | |
-| `providers.list` | read | |
-| `storage.get` | read | |
-| `thread.reply` | current-thread write | |
-| `storage.set` | current-thread write | |
-| `threads.openPage` | navigation | |
-| `threads.openBb` | navigation | |
-| `threads.continue` | cross-thread write | yes |
-| `threads.spawn` | cross-thread write | yes |
-| `projects.create` | cross-thread write | yes |
-| `threads.archive` | destructive | yes |
-| `threads.stop` | destructive | yes |
-| `navigation.openExternal` | navigation | yes |
-| `projects.browse` | device | yes |
-| `voice.captureAndTranscribe` | device | contract only |
-
-Adding a capability extends this list. It never requires a new page component,
-because no page component is built in.
-
-Two deliberate narrowings. `projects.browse` opens the host's native folder
-picker and returns an **opaque single-use token** plus a display string — never a
-filesystem path the page could reuse or leak; `projects.create` redeems it.
-`storage.*` is namespaced per thread, so pages cannot read each other's state
-despite sharing one table.
-
-## What the plugin renders, and what it does not
-
-The plugin owns exactly three pieces of UI, all of them chrome outside the
-sandbox:
-
-- the page title bar;
-- a **Sessions** link back to the home page;
-- a working indicator while the thread is mid-turn.
-
-The last two are worth explaining, because both could have been pushed onto
-agents and deliberately were not.
-
-**The Sessions link** is chrome so that no agent spends instruction budget on it
-and no page can forget it. The home page it points to is not special: any
-thread's page can be designated home with `bb thread-page home`, and it is an
-ordinary Thread Page afterwards.
-
-**The working indicator** answers "is it still writing?". Its state rides on the
-`x-thread-page-activity` header of the revision poll the shell already makes
-every ten seconds — so it costs no extra request, nothing in any page's HTML, and
-nothing in any agent's instructions. Its wording is a setting; blank hides it.
-
-Everything else is the page's.
-
-## The home page
-
-`bb thread-page home` designates a thread and, if that thread has no page yet,
-writes a session hub. The default groups sessions by project and gives each group
-its own look.
-
-The design point is that **a group is not a project**. A group is a label, a
-look, and a *set* of project ids, kept in the page's own scoped storage. One
-group per project is only the default; a project may appear in several groups,
-and regrouping is an edit to the page rather than a schema change.
-
-Per-group looks need no second document. The stylesheet's `data-world` attribute
-re-resolves every design token for a subtree, so a group can carry a different
-palette, typeface, shape language and button style inside one page. Separate
-linked pages remain possible through `threads.openPage`; they were not necessary.
-
-## The design system
-
-Five worlds — `paper`, `terminal`, `atrium`, `volume`, `bloom` — each declaring
-both light and dark palettes at once, with one resolver publishing the live half
-onto the tokens the rest of the sheet uses. A page picks one with `data-theme` on
-`<html>`, plus `data-mode` and `data-atmos`.
-
-It needs no class names: every rule keys off semantic structure, so plain HTML is
-already styled. Three class names exist for things structure cannot express —
-`.card`, `.needs-you`, `.label`.
-
-**The stylesheet travels inside each page** rather than being injected at render
-time. That means an agent can change any rule for one page, and a plugin update
-can never restyle a page the user has already read. The cost is that improvements
-to the design system only reach pages created afterwards; that trade favours the
-reader.
-
-A page may add one more `<style>` with two rules: everything inside
-`@scope (main)`, and colour and shape from `var(--token)` only. The second is
-what keeps a bespoke chart correct in all five worlds and in dark mode.
-
-## Instructions
-
-Three, and only the first is loaded per session.
-
-1. **The contract** — why the page matters, how to ask well, what belongs on a
-   page. Injected into eligible root threads. It holds only what changes
-   behaviour; every mechanical convention is absorbed by the runtime or the seed.
-2. **The seed comment** — the class names, the theme attributes, the escape-hatch
-   rule. Free, because the agent is already reading the file.
-3. **The guide** — `bb thread-page guide`. Unbounded, and paid for only by the
-   sessions that open it.
-
-There is no skill and no agent tool. Both would put the plugin in every session's
-context whether or not the task needs it.
-
-## Eligibility
-
-Only threads a user started get a page. Children, forks and hidden workers get
-`SKIP` and answer in chat, because they are not the ones being talked to. `init`
-rechecks this at call time rather than trusting the injected instruction.
-
-## Testing
-
-93 tests over three suites, none needing a browser:
-
-- `bridge.test.ts` — the capability contract in isolation: validators, limits,
-  effect classes, confirmation binding. No SDK, DOM, or filesystem.
-- `page.test.ts` — HTML parsing against malformed and adversarial documents,
-  kernel ordering, sandbox invariants, form and label derivation.
-- `server.test.ts` — routes, tokens, capabilities, uploads, assets, home, and the
-  working state, against a fake host.
-
-Browser verification is done by hand for the things tests cannot see. Several
-real defects were found only that way — an invalid CSP source that silently
-blocked every relative asset, an auth rule that rejected raw upload bodies, a
-`<select>`'s options leaking into an answer label, and a snapshot flag that
-selected archived threads instead of adding them. Each has a test now.
-
-The gap worth naming: there is no hostile-page corpus yet. The confirmation flow
-is tested against forgery, replay and parameter-swapping, but no test plays an
-attacker trying to reach the parent frame or steal a cookie.

package/PLUGIN_OVERVIEW.md

@@ -1,83 +0,0 @@
-# Thread Pages
-
-Give every bb thread its own web page — written by the agent, for that one task.
-
-## What it does
-
-An agent working on a task usually has more to tell you than chat can carry: a
-comparison, a diagram, a set of choices, a thing only you can decide. Thread
-Pages gives it a real page to say it on.
-
-The agent runs one command, gets an HTML file, and edits it directly. Saving the
-file publishes it. You open one stable link — in bb, in a browser, on your
-phone — read the page, and answer from inside it. Your answer arrives as the
-agent's next message.
-
-The page is a complete HTML document the agent writes for the task at hand. Not
-a template with slots. If the task needs a chart, it writes a chart. If it needs
-an eight-screen wizard, a diagram you click, or three separate forms, it writes
-that. The plugin supplies the secure host, never the design.
-
-## Why it is built this way
-
-**Nothing to learn, nothing to load.** There is no skill in the agent's context,
-no page tool, no publish protocol, no runtime copied into your files. The
-standing instruction is two sentences. Deeper guidance is one optional command
-away, so a simple task never pays for it.
-
-**The page is a file.** It lives in the thread's own storage as ordinary HTML.
-The agent reads and writes it with the tools it already has. You can open it,
-diff it, or keep it.
-
-**Your bb, your page.** Pages are served through the bb origin you are already
-authenticated to, so they work over bb Connect and on mobile without exposing a
-second port or a public URL.
-
-**Safe by construction.** Page code runs in an opaque-origin sandbox with no bb
-cookie, no mutation token, no parent DOM, no raw API, and no general network
-access. Anything the page can ask bb to do goes through one narrow, validated
-capability at a time.
-
-## In the page
-
-- Any HTML, CSS, and JavaScript the task needs, including Web Components, SVG,
-  canvas, and multi-screen state.
-- Forms that reply to the thread with no code at all — blank answers included,
-  several forms at once, each with its own state.
-- File attachments, stored beside the thread and handed to the agent by path.
-- Images, stylesheets, fonts, and data from a confined per-thread asset folder.
-- Live thread activity, and a working indicator while the agent is mid-turn.
-- Listing, messaging, starting, stopping and archiving sessions from a page.
-- Update protection, so a page reload never eats what you were typing.
-- A read-only cached copy when the source machine goes offline.
-
-## Getting started
-
-Install the plugin, then turn on **Agent initialization hint** in its settings
-to have new sessions use their page automatically. Or leave it off and ask any
-agent to run `bb thread-page init`.
-
-The page seed and the instruction text are both settings, so you can change what
-every future page starts from without touching any existing page.
-
-## The home page
-
-`bb thread-page home` writes a session hub grouped by project, each group with
-its own look, and every other page then shows a **← Sessions** link back to it.
-
-Home is an ordinary page afterwards — ask the agent that owns it to regroup or
-restyle it. Groups are not tied to projects: a group is a label, a look, and a
-set of projects, so "Work" and "Side projects" are as valid as one-per-project,
-and a project can appear in both.
-
-## Current state
-
-Everything needed for daily use is implemented and verified in a browser: page
-authoring, forms, attachments, confined assets, live activity, the session hub,
-and the full capability set with trusted confirmations. Voice dictation has a
-defined contract but no handler yet.
-
-One limitation worth stating plainly: page JavaScript can navigate its own frame
-and put data in that URL. Browsers cannot prevent this while still allowing page
-scripts. It grants no bb authority, but a page you did not write is still code
-you are choosing to run.

package/authoring.ts

@@ -1,368 +0,0 @@
-import {
-  DEFAULT_HOME_BODY,
-  DEFAULT_HOME_SCRIPT,
-  DEFAULT_HOME_STYLE,
-} from "./home.js";
-import { escapeHtml } from "./page.js";
-import { THEME_CSS } from "./theme.js";
-
-/**
- * The standing contract, injected into eligible root threads.
- *
- * It carries why the page matters and how to ask well, because those are what
- * actually change an agent's behaviour. Everything mechanical - form wiring,
- * styling, labels, blank handling - is absorbed by the runtime and the seed, so
- * none of it is spent here. Anything deeper is one guide command away, paid for
- * only by the sessions that need it.
- */
-export const DEFAULT_AGENT_INSTRUCTION = `# The page is the conversation
-
-The user does not read chat. Every turn you write or update one HTML page, they
-read it and reply from inside it, and their answer arrives as your next message.
-Everything they need must be on that page, and every action they might take must
-be possible from it — including the ones you would rather they did not choose. A
-page they cannot answer from is a dead end. Chat carries the link and one line.
-
-Start every turn with \`bb thread-page init\`. It prints the page path and link.
-Read an existing page before editing it; saving publishes it immediately and an
-open page reloads itself. Update it on every turn, including small ones. If init
-says SKIP this thread is a helper — answer in chat and stay off the page. When
-you spawn threads of your own, parent them to yourself so they stay helpers.
-
-## Every page ends with a way to answer
-
-Any <form> is wired automatically: answers arrive as your next message. Write
-plain semantic HTML — it is already styled, and there is nothing to remember.
-<fieldset><legend> names a group, a wrapping <label> names one control, <small>
-is a hint, and several <button name value> give one-click answers.
-
-Asking well is most of the work. Answering should cost a click, not a paragraph:
-buttons and radios for decisions, checkboxes for multi-select, free text only
-where the answer is genuinely open. A range needs a scale that means something
-and is easier to drag than to type — never a vague 1-to-5. Nothing is ever
-required and blank is a real answer, so ask for everything that would help and
-let them skip the rest. Always leave one open text field for what you failed to
-anticipate: your form is their only way to redirect you, and a form that permits
-only the answers you expect quietly takes the decision away from them.
-
-## What belongs on the page
-
-Only what they cannot skip: what you did, at the level they could explain it to
-someone else; decisions that are genuinely theirs, with the options and your
-recommendation; what only they can supply; anything they should sanity-check
-because a wrong assumption of yours would be costly.
-
-Every word necessary, nothing said twice. Each update leads with what changed and
-has to stand alone, because they answer from that version without scrolling back.
-Report failures, skipped steps and your own mistakes plainly. Conclusion first,
-detail only if it changes what they do.
-
-You own the work end to end: make the routine calls yourself, keep every file you
-touch correct as you go, and escalate to the page rather than to chat.
-
-## The home page
-
-One thread's page is the home page, and every other page shows a Sessions link
-back to it automatically — you never write that link yourself. Home is an
-ordinary page: it should list the user's sessions with the threads.snapshot
-capability and let them open, continue, or start one.
-
-If the user asks for a home page, or asks where their sessions are, run
-\`bb thread-page home\` in the thread that should own it and then build that page
-against \`bb thread-page guide\`. Check whether one already exists before making
-a second.
-
-A page needing more than prose and a form — a chart, a branch, cards to swipe, a
-file, live session control — runs \`bb thread-page guide\` first.`;
-
-/**
- * The default new-page document.
- *
- * The design system travels in the page rather than being injected at render
- * time, so the agent can read and change every rule, and a later plugin update
- * never restyles a page the user has already read. Plain semantic HTML inside
- * <main> is fully styled by it; there are three class names in total.
- */
-export const DEFAULT_PAGE_SEED = `<!doctype html>
-<html lang="en" data-theme="volume" data-mode="system" data-atmos="on">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
-  <title>{{TITLE}}</title>
-  <style>${THEME_CSS}</style>
-</head>
-<body>
-  <div class="atmosphere" aria-hidden="true"></div>
-  <div class="wrap">
-
-  <header class="brief-head">
-    <h1>{{TITLE}}</h1>
-    <p class="brief-meta"><span>{{DATE}}</span></p>
-  </header>
-
-  <!--
-    Write inside the main element below. Plain semantic HTML is already styled:
-    h2, p, ul, table, form, fieldset/legend, a wrapping label, small, details.
-    Three class names exist: .card boxes an aside, .needs-you flags a block
-    that is blocked on the reader, .label is a small uppercase tag.
-
-    data-theme is paper | terminal | atrium | volume | bloom.
-    data-mode is system | light | dark. data-atmos is on | off.
-
-    Any extra CSS goes in one more style block, everything inside
-    @scope (main), and colour and shape from var(--token) only — never a hex.
-    That is what keeps a bespoke page correct in all five worlds and in dark.
-
-    For charts, multi-screen flows, files, activity, or bridge methods:
-      bb thread-page guide
-  -->
-  <main>
-    <p>Replace this with what changed and what you need from the reader.</p>
-
-    <form data-title="{{TITLE}}">
-      <label>Reply
-        <textarea name="reply" rows="4"></textarea>
-      </label>
-      <button name="action" value="Reply">Reply</button>
-    </form>
-  </main>
-
-  </div>
-</body>
-</html>
-`;
-
-/**
- * The home page document: the same shell and stylesheet as any other page, with
- * a session hub already written into it. It is an ordinary page afterwards, so
- * the owning agent can restyle or regroup it on request.
- */
-export function renderHomeSeed(template: string, now: Date = new Date()): string {
-  const base = renderPageSeed(template, "Sessions", now);
-  const bodyStart = base.indexOf("  <header class=\"brief-head\">");
-  const bodyEnd = base.indexOf("  </div>\n</body>");
-  if (bodyStart < 0 || bodyEnd < 0 || bodyEnd <= bodyStart) {
-    // A custom seed we cannot splice: keep the user's own document rather than
-    // silently replacing it, and let the agent write the hub itself.
-    return base;
-  }
-  return (
-    base.slice(0, bodyStart) +
-    DEFAULT_HOME_BODY +
-    `\n  <style>${DEFAULT_HOME_STYLE}</style>\n` +
-    `  <script>${DEFAULT_HOME_SCRIPT}</script>\n\n` +
-    base.slice(bodyEnd)
-  );
-}
-
-export function renderPageSeed(
-  template: string,
-  title: string,
-  now: Date = new Date(),
-): string {
-  const date = now.toLocaleDateString("en-GB", {
-    day: "numeric",
-    month: "long",
-    year: "numeric",
-  });
-  return template
-    .replaceAll("{{TITLE}}", escapeHtml(title))
-    .replaceAll("{{DATE}}", escapeHtml(date));
-}
-
-export const AUTHORING_GUIDE = `# Thread Pages authoring guide
-
-Use the smallest page shape that makes the task easier. Plain semantic HTML is
-the default; a Thread Page may also be a complete HTML/CSS/JavaScript mini-app.
-Saving the file publishes it.
-
-## Built in
-
-- Every non-manual <form> replies to this thread. Add
-  data-thread-page-manual when your application owns submission.
-- Blank answers are valid. Fieldset legends and labels become answer names.
-- Multiple forms have independent pending and dirty state.
-- A clicked submit button leads the message as Action.
-- window.threadPage.setDirty(true|false) protects custom application state
-  from an automatic page reload.
-- window.threadPage.invoke(method, params) calls an enabled, validated BB
-  capability. Run context.get to discover the current capability roster.
-
-## What plain HTML already gives you
-
-The seed carries the design system, so semantic HTML is already styled. You do
-not need most of what follows; reach past prose only when the shape of the thing
-genuinely is not prose.
-
-  h2, p, ul, table    the page's type scale, rhythm, rules, tabular figures
-  form                a panel, wiring to this thread, a status line
-  fieldset + legend   a named group; the legend becomes the question
-  label wrapping one  the label becomes that answer's name
-  small in a label    a hint under the option
-  input type=range    a slider with a live value readout
-  input type=file     uploaded on submit, path sent to this thread
-  details/summary     detail on demand; add name="x" for an accordion
-  div class=card      a boxed aside
-  p class=needs-you   a flagged block, for what is blocked on the reader
-  span class=label    a small uppercase tag
-
-Three class names. That is the whole vocabulary; everything else is selected by
-what the element is.
-
-## The look is three attributes
-
-On <html>:
-
-  data-theme   paper | terminal | atrium | volume | bloom
-  data-mode    system | light | dark
-  data-atmos   on | off
-
-Each world sets a palette (both halves at once), a typeface, a shape language,
-an atmosphere layer, and its own idea of what choosing and committing look like.
-Changing the attribute reskins everything, including anything you built.
-
-## The escape hatch
-
-A page may carry one extra <style> block with two rules:
-
-  1. Everything inside @scope (main). The browser enforces it, so a page cannot
-     reach the shell.
-  2. Tokens only. No hex, no rgb(). Colour and shape come from var(--...).
-
-Rule 2 is what keeps a bespoke page inside the system: dark mode still works and
-switching world reskins your chart too. A page that writes #3b82f6 is wrong half
-the time and nobody notices until night.
-
-Tokens: --bg --surface --ink --ink-2 --ink-3 --rule --rule-soft --code-bg
---accent --accent-soft --accent-line --flag --ok --font-body --font-head
---radius --rule-w --shadow --measure --space --size --h1-size --label-case
---caps-track --dur --ease
-
-## Prefer native HTML first
-
-- details/summary (and details name="x") for disclosure and accordions.
-- input type="range" for an eyeballed scale; Thread Pages adds a live output.
-- CSS :has() for simple branches — real different content, not a hidden field.
-- overflow-x:auto plus scroll-snap for swipeable cards: a real swipe on a
-  phone, a scrollbar on a desktop, arrow keys on a keyboard, in four lines.
-- inline SVG for diagrams and charts; var(--accent) works inside it. Give a
-  zero a visible stub bar or the eye reads it as missing data.
-- animation-timeline: view() for scroll-linked motion, wrapped in
-  @media (prefers-reduced-motion: no-preference) so still is the default.
-- @starting-style with transition-behavior: allow-discrete for enter/exit.
-- dialog, popover, container queries, color-mix(), and view transitions when
-  they clarify the task.
-- Respect prefers-reduced-motion and keep every action keyboard reachable.
-  Never make something reachable only by pointer.
-
-## Before you save
-
-  grep -o '#[0-9a-fA-F]\{3,8\}' page.html   # inside your <style>: empty
-  grep -c '@scope (main)' page.html          # 1 if you added a <style>
-
-Then read it once at 320px wide, once in dark, once with reduced motion. Those
-three are where a page that looks finished stops being one.
-
-## Complete custom applications
-
-Inline CSS and JavaScript, Web Components, SVG/canvas, internal routes, and
-multi-step state are allowed inside the opaque sandbox. The page cannot read BB
-cookies, the mutation token, parent DOM, localStorage, raw SDK/API, CLI, or
-arbitrary files. Ordinary fetch and subresource networking are blocked unless a
-confined resource is explicitly supplied.
-
-Arbitrary JavaScript can still navigate its own sandboxed frame and encode
-page/input data in the URL. The open mini-app model trusts authored code with
-data already visible in its frame. Strong no-exfiltration requires a
-declarative/no-authored-JavaScript page.
-
-## The session hub, and the home page
-
-One page is the home page; \`bb thread-page home\` designates the current
-thread's. Every other page then shows a Sessions link back to it as chrome, so
-no page writes that link. Home is an ordinary page — give it whatever design
-suits, and render the list yourself:
-
-  const { threads } = await window.threadPage.invoke("threads.snapshot", { limit: 50 });
-  // each: id, title, projectId, parentThreadId, status, archived,
-  //       page: { available, revision }, updatedAtMs
-
-  await window.threadPage.invoke("threads.openPage", { threadId });   // its page
-  await window.threadPage.invoke("threads.openBb", { threadId });     // in bb
-  await window.threadPage.invoke("threads.continue", { threadId, prompt });
-  await window.threadPage.invoke("threads.spawn", { projectId, prompt });
-  await window.threadPage.invoke("threads.archive", { threadId });
-  await window.threadPage.invoke("threads.stop", { threadId });
-
-  const { projects } = await window.threadPage.invoke("projects.list", {});
-  const { providers } = await window.threadPage.invoke("providers.list");
-
-  // Folder picker, then create a project from the opaque selection token.
-  const { selection } = await window.threadPage.invoke("projects.browse", {});
-  if (selection) await window.threadPage.invoke("projects.create",
-    { selectionToken: selection.token, name: "My project" });
-
-  await window.threadPage.invoke("navigation.openExternal", { url, label });
-
-  // Small state that survives a reload, scoped to this page.
-  await window.threadPage.invoke("storage.set", { key: "wizard.step", value: 3 });
-  const state = await window.threadPage.invoke("storage.get", { key: "wizard.step" });
-
-Anything that changes another thread, archives, stops, creates a project, or
-leaves bb shows a confirmation in trusted chrome first. You do not build that
-and cannot word it; a declined action rejects with code "cancelled". Handle it.
-
-## Current bridge
-
-const context = await window.threadPage.invoke("context.get");
-const stop = window.threadPage.watch(
-  "thread.activity",
-  { limit: 8 },
-  (value) => renderActivity(value),
-  { intervalMs: 8000 }
-);
-
-await window.threadPage.invoke("thread.reply", {
-  title: "Diagram result",
-  mode: "queue", // or "steer"
-  result: { selectedNodes: ["a", "b"] },
-  idempotencyKey: "optional-stable-key"
-});
-
-Call stop() when a watched component unmounts. A page that never calls watch
-does no bridge polling.
-
-## Files the user sends you
-
-An automatic form may contain input type="file" (including multiple). On submit
-the bytes are uploaded first, stored under this thread's confined upload
-directory, and reported to you in the form message as:
-
-  $BB_THREAD_STORAGE/thread-page-uploads/<generated-name>
-
-Read them there with your normal tools. Each file must be under 24 MiB. Names
-are generated by the plugin, so a hostile page cannot choose a path. Uploads
-fail visibly on the page; they are never silently dropped.
-
-## Files you show the user
-
-Put sibling resources in:
-
-  $BB_THREAD_STORAGE/thread-page-assets/
-
-Reference them relatively (<img src="chart.png">, <link href="page.css">) or
-resolve one explicitly:
-
-  const url = window.threadPage.assetUrl("chart.png");
-
-The directory is exposed to the page as one temporary, path-shaped preview and
-is the only network origin the page's CSP allows. Names may use letters,
-digits, dot, dash, and underscore only, with no subdirectories. When the
-directory does not exist there is no asset base and assetUrl throws.
-
-## Design ownership
-
-The plugin does not impose a theme or component library. You may define any
-task-specific visual system. Prefer CSS custom properties with light/dark
-values so the page stays coherent, and test at a narrow mobile width.
-`;