@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/serving/session-access.ts

@@ -0,0 +1,22 @@
+import type { Context } from "hono";
+import { describeIneligible, ineligibleReason } from "../domain/eligibility.ts";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { isSessionId } from "../domain/ids.ts";
+import type { SessionRecord } from "../host/types.ts";
+import type { ServingContext } from "./context.ts";
+
+/** Shared first steps of every route: which session, does it exist, may it have a page. */
+export function sessionIdFrom(context: Context): string {
+  const url = new URL(context.req.url);
+  const candidate = url.searchParams.get("session") ?? url.searchParams.get("threadId");
+  if (!isSessionId(candidate)) throw new PageError("invalid_session", PUBLIC_MESSAGES.invalidSession);
+  return candidate;
+}
+
+export async function eligibleSession(serving: ServingContext, id: string): Promise<SessionRecord> {
+  const session = await serving.host.sessions.get(id);
+  if (!session) throw new PageError("not_found", "That session does not exist.");
+  const reason = ineligibleReason(session);
+  if (reason) throw new PageError("ineligible", `${PUBLIC_MESSAGES.ineligible} (${describeIneligible(reason)}.)`);
+  return session;
+}

package/src/serving/shell-html.ts

@@ -0,0 +1,77 @@
+import { escapeHtml } from "../domain/html/escape.ts";
+import { SHELL_RUNTIME } from "../generated/shell-runtime.ts";
+import type { ShellConfig } from "../runtime/shared/protocol.ts";
+
+/**
+ * The trusted shell document: title bar, home link, working indicator,
+ * status, reload control, the sandboxed frame and the confirmation dialog.
+ * Identical wherever the page is read. spec R2.14–R2.16
+ */
+export interface ShellView {
+  nonce: string;
+  title: string;
+  homeUrl: string | null;
+  working: boolean;
+  config: ShellConfig;
+}
+
+const SHELL_CSS = `
+:root{color-scheme:light dark;font:14px/1.4 ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--bg:#f7f7f5;--surface:#fff;--ink:#17181b;--muted:#676c75;--line:#dfe0e3;--accent:#315fc5;--warn:#a54312}
+@media(prefers-color-scheme:dark){:root{--bg:#111216;--surface:#191b20;--ink:#eeeef0;--muted:#a5a9b1;--line:#30333a;--accent:#91aff1;--warn:#efa879}}
+*{box-sizing:border-box}html,body{height:100%;margin:0;background:var(--bg);color:var(--ink)}
+.shell{display:grid;grid-template-rows:auto 1fr;height:100%;min-height:100dvh}
+.bar{display:flex;align-items:center;gap:.75rem;min-height:2.5rem;padding:.45rem max(.7rem,env(safe-area-inset-right)) .45rem max(.7rem,env(safe-area-inset-left));border-bottom:1px solid var(--line);background:var(--surface)}
+.home{flex:none;color:var(--muted);text-decoration:none;font-weight:600;white-space:nowrap}.home:hover{color:var(--ink)}
+.title{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:600}
+.status{margin-left:auto;color:var(--muted);text-align:right}.status[data-tone=warn]{color:var(--warn)}
+.work{flex:none;display:none;align-items:center;gap:.4rem;color:var(--muted)}.work[data-visible=true]{display:inline-flex}
+.work .dot{width:.5rem;height:.5rem;border-radius:50%;background:var(--accent)}
+@media(prefers-reduced-motion:no-preference){.work[data-visible=true] .dot{animation:tp-pulse 1.4s ease-in-out infinite}}
+@keyframes tp-pulse{0%,100%{opacity:1}50%{opacity:.25}}
+button.reload{display:none;padding:.25rem .55rem;border:1px solid var(--line);border-radius:.4rem;color:var(--ink);background:var(--bg);cursor:pointer}button.reload[data-visible=true]{display:inline-block}
+iframe{display:block;width:100%;height:100%;border:0;background:var(--bg)}
+dialog{margin:auto;max-width:min(30rem,calc(100vw - 2rem));padding:1.15rem 1.25rem;border:1px solid var(--line);border-radius:.75rem;color:var(--ink);background:var(--surface)}
+dialog::backdrop{background:rgb(0 0 0 / .45)}dialog h2{margin:0 0 .5rem;font-size:1rem}dialog p{margin:0 0 1rem;color:var(--muted);overflow-wrap:anywhere}
+dialog .row{display:flex;gap:.5rem;justify-content:flex-end}dialog button{padding:.4rem .8rem;border:1px solid var(--line);border-radius:.4rem;color:var(--ink);background:var(--bg);cursor:pointer}
+dialog button[value=confirm]{color:#fff;background:var(--accent);border-color:var(--accent)}
+`;
+
+export function renderShell(view: ShellView): string {
+  const title = escapeHtml(view.title);
+  const nonce = escapeHtml(view.nonce);
+  const config = escapeHtml(JSON.stringify(view.config));
+  const working = view.working && view.config.workingLabel ? "true" : "false";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<title>${title}</title>
+<style nonce="${nonce}">${SHELL_CSS}</style>
+</head>
+<body>
+<div class="shell">
+  <header class="bar">
+    ${view.homeUrl ? `<a class="home" href="${escapeHtml(view.homeUrl)}" title="All sessions">← Sessions</a>` : ""}
+    <span class="title">${title}</span>
+    <span class="work" role="status" data-shell-working data-visible="${working}"><span class="dot" aria-hidden="true"></span><span>${escapeHtml(view.config.workingLabel)}</span></span>
+    <span class="status" role="status" data-shell-status${view.config.stale ? ' data-tone="warn"' : ""}>${view.config.stale ? "Offline copy — read-only" : ""}</span>
+    <button type="button" class="reload" data-shell-reload aria-label="Reload updated page">Reload</button>
+  </header>
+  <iframe title="${title}" sandbox="allow-scripts allow-forms" referrerpolicy="no-referrer"></iframe>
+</div>
+<dialog aria-labelledby="tp-confirm-title">
+  <form method="dialog">
+    <h2 id="tp-confirm-title">Confirm this action</h2>
+    <p></p>
+    <div class="row">
+      <button type="button" value="cancel">Cancel</button>
+      <button type="button" value="confirm">Confirm</button>
+    </div>
+  </form>
+</dialog>
+<script nonce="${nonce}" data-config="${config}">${SHELL_RUNTIME}</script>
+</body>
+</html>`;
+}

package/src/serving/shell-route.ts

@@ -0,0 +1,51 @@
+import { randomBytes } from "node:crypto";
+import type { Context } from "hono";
+import { isSessionId } from "../domain/ids.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { mintActionToken } from "../domain/tokens/action-token.ts";
+import type { ServingContext } from "./context.ts";
+import { homeUrl } from "./context.ts";
+import { baseHeaders, failureResponse, shellCsp } from "./responses.ts";
+import { renderShell } from "./shell-html.ts";
+import { eligibleSession, sessionIdFrom } from "./session-access.ts";
+
+/** `GET /page?session=<id>` — the shell for one page. spec 02 §The shell */
+export function shellRoute(serving: ServingContext) {
+  return async (context: Context): Promise<Response> => {
+    try {
+      const id = sessionIdFrom(context);
+      const session = await eligibleSession(serving, id);
+      const page = await serving.pages.load(id);
+      const now = serving.now();
+      const { token, payload } = mintActionToken({ session: id, revision: page.revision, now }, serving.signingKey);
+      const nonce = randomBytes(18).toString("base64url");
+      const settings = serving.settings.current();
+      const home = isSessionId(settings.homeSessionId) && settings.homeSessionId !== id ? homeUrl(serving.routeBase) : null;
+      const html = renderShell({
+        nonce,
+        title: session.title,
+        homeUrl: home,
+        working: session.state === "working",
+        config: {
+          actionToken: token,
+          pageRevision: page.revision,
+          expiresAt: payload.exp,
+          documentUrl: serving.site.documentUrl(id),
+          submitUrl: `${serving.routeBase}/submit`,
+          uploadUrl: `${serving.routeBase}/upload`,
+          bridgeUrl: `${serving.routeBase}/bridge`,
+          workingLabel: settings.workingLabel,
+          stale: page.stale,
+          pollMs: LIMITS.shellPollMs,
+          maxUploadBytes: LIMITS.uploadFileBytes,
+          maxUploads: LIMITS.uploadsPerForm,
+        },
+      });
+      const headers = baseHeaders("text/html; charset=utf-8");
+      headers.set("content-security-policy", shellCsp(nonce));
+      return new Response(html, { status: 200, headers });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "GET /page", true);
+    }
+  };
+}

package/src/serving/signing-key.ts

@@ -0,0 +1,25 @@
+import { randomBytes } from "node:crypto";
+import { errorText } from "../domain/errors.ts";
+import type { SessionHost } from "../host/contract.ts";
+
+const KEY = "signing-key:v3";
+
+/** The token signing key: 32 random bytes, generated on first use, persisted, never logged. spec R2.8 */
+export async function loadSigningKey(host: SessionHost): Promise<Uint8Array> {
+  try {
+    const stored = await host.kv.get(KEY);
+    if (typeof stored === "string" && /^[A-Za-z0-9_-]{43}$/.test(stored)) {
+      const decoded = Buffer.from(stored, "base64url");
+      if (decoded.byteLength === 32) return decoded;
+    }
+  } catch (error) {
+    host.log.warn(`signing key: could not read the stored key: ${errorText(error)}`);
+  }
+  const generated = randomBytes(32);
+  try {
+    await host.kv.set(KEY, generated.toString("base64url"));
+  } catch (error) {
+    host.log.warn(`signing key: could not persist; open pages will need a reload after the next plugin reload: ${errorText(error)}`);
+  }
+  return generated;
+}

package/src/serving/submit-route.ts

@@ -0,0 +1,47 @@
+import type { Context } from "hono";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { sha256Hex } from "../domain/revision.ts";
+import { formatSubmissionMessage } from "../domain/submissions/message.ts";
+import { parseSubmission } from "../domain/submissions/parse.ts";
+import { acquireRate, readJsonBody, requireActionToken } from "./action-request.ts";
+import type { ServingContext } from "./context.ts";
+import { failureResponse, jsonResponse } from "./responses.ts";
+import { eligibleSession } from "./session-access.ts";
+
+/** `POST /submit` — one form submission becomes one message. spec R2.32–R2.37 */
+export function submitRoute(serving: ServingContext) {
+  return async (context: Context): Promise<Response> => {
+    let release: (() => void) | null = null;
+    try {
+      const body = await readJsonBody(context, LIMITS.submissionBodyBytes);
+      const submission = parseSubmission(body);
+      if (!submission) throw new PageError("invalid_request", "Invalid submission");
+      const token = requireActionToken(serving, submission.actionToken);
+      if (submission.pageRevision !== token.revision) throw new PageError("stale_page", PUBLIC_MESSAGES.stalePage);
+      release = acquireRate(serving, token.session);
+      const now = serving.now();
+      const fingerprint = sha256Hex(JSON.stringify({ revision: submission.pageRevision, title: submission.title, answers: submission.answers, files: submission.files }));
+      const remembered = serving.submissions.remember(
+        `${token.session}:${submission.submissionId}`,
+        fingerprint,
+        async () => {
+          await eligibleSession(serving, token.session);
+          const page = await serving.pages.load(token.session);
+          if (page.stale) throw new PageError("unavailable", PUBLIC_MESSAGES.staleCopy);
+          if (page.revision !== token.revision) throw new PageError("stale_page", PUBLIC_MESSAGES.stalePage);
+          const sent = await serving.host.sessions.send(token.session, formatSubmissionMessage(submission), "queue");
+          return { status: 200, body: { ok: true, delivery: sent.delivery } };
+        },
+        now,
+      );
+      if (remembered.kind === "conflict") throw new PageError("conflict", "This submission id was already used with different answers");
+      const outcome = await remembered.outcome;
+      return jsonResponse(outcome.body, outcome.status);
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "POST /submit", false);
+    } finally {
+      release?.();
+    }
+  };
+}

package/src/serving/upload-route.ts

@@ -0,0 +1,46 @@
+import { randomBytes } from "node:crypto";
+import type { Context } from "hono";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { LIMITS, mebibytes } from "../domain/limits.ts";
+import { UPLOAD_DIR, uploadFileName } from "../pages/layout.ts";
+import { acquireRate, readJsonBody, requireActionToken } from "./action-request.ts";
+import type { ServingContext } from "./context.ts";
+import { failureResponse, jsonResponse } from "./responses.ts";
+import { eligibleSession } from "./session-access.ts";
+
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/**
+ * `POST /upload` — one attached file, base64 in a JSON envelope (the host's
+ * "local" auth refuses raw bodies), stored under a host-generated name in the
+ * page's uploads directory. spec R4.19–R4.24
+ */
+export function uploadRoute(serving: ServingContext) {
+  const maxBody = Math.ceil((LIMITS.uploadFileBytes * 4) / 3) + 8_192;
+  return async (context: Context): Promise<Response> => {
+    let release: (() => void) | null = null;
+    try {
+      const body = await readJsonBody(context, maxBody);
+      if (!body || typeof body !== "object" || Array.isArray(body)) throw new PageError("invalid_request", "Invalid upload envelope");
+      const envelope = body as Record<string, unknown>;
+      const token = requireActionToken(serving, envelope.actionToken);
+      if (typeof envelope.content !== "string" || !BASE64.test(envelope.content)) throw new PageError("invalid_request", "Attachment content must be base64");
+      release = acquireRate(serving, token.session);
+      await eligibleSession(serving, token.session);
+      const page = await serving.pages.load(token.session);
+      if (page.stale) throw new PageError("unavailable", PUBLIC_MESSAGES.staleCopy);
+      const bytes = Buffer.from(envelope.content, "base64");
+      if (bytes.byteLength === 0) throw new PageError("invalid_request", "The file is empty");
+      if (bytes.byteLength > LIMITS.uploadFileBytes) throw new PageError("request_too_large", `Attachments must be at most ${mebibytes(LIMITS.uploadFileBytes)}`);
+      const name = uploadFileName(typeof envelope.name === "string" ? envelope.name : "upload", serving.now(), randomBytes(3).toString("hex"));
+      const location = await serving.host.sessions.storage(token.session);
+      const outcome = await serving.host.files.write(location, `${UPLOAD_DIR}/${name}`, bytes, { onlyIfAbsent: true });
+      if (outcome !== "written") throw new PageError("conflict", "The attachment could not be stored under a fresh name; try again");
+      return jsonResponse({ ok: true, name, path: `${UPLOAD_DIR}/${name}`, sizeBytes: bytes.byteLength });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "POST /upload", false);
+    } finally {
+      release?.();
+    }
+  };
+}

package/tsconfig.json

@@ -1,15 +1,19 @@
 {
   "compilerOptions": {
+    "strict": true,
     "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
+    "types": ["node"],
     "noEmit": true,
+    "skipLibCheck": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
-    "types": ["node"]
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "allowImportingTsExtensions": true
   },
-  "include": ["*.ts"]
+  "include": ["server.ts", "src", "test", "scripts"]
 }

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.