@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/serving/bridge/handlers/reads.ts

@@ -0,0 +1,186 @@
+import type { SessionSummary, SnapshotParams } from "../../../domain/capabilities/specs.ts";
+import { PageError } from "../../../domain/errors.ts";
+import type { JsonValue } from "../../../domain/json/strict-json.ts";
+import { LIMITS } from "../../../domain/limits.ts";
+import type { SessionRecord } from "../../../host/types.ts";
+import { ENTRY_FILE, joinPath } from "../../../pages/layout.ts";
+import { handler, type HandlerContext } from "../handler.ts";
+
+/** Read capabilities. spec 05 §Reads */
+
+export const contextGet = handler<null, unknown>({
+  method: "context.get",
+  async execute(_params, { serving, session, page }) {
+    return {
+      result: {
+        protocolVersion: 1,
+        session: { id: session.id, title: session.title.slice(0, LIMITS.titleChars), projectId: session.projectId },
+        page: { revision: page.revision, readOnly: page.stale },
+        capabilities: serving.registry.descriptors(),
+      },
+    };
+  },
+});
+
+export const sessionActivity = handler<{ limit: number }, unknown>({
+  method: "session.activity",
+  async execute(params, { serving, session }) {
+    const items = await serving.host.sessions.activity(session.id, params.limit);
+    return { result: { state: session.state, updatedAtMs: session.updatedAtMs, items } };
+  },
+});
+
+// --- sessions.snapshot -------------------------------------------------------
+
+interface Cursor {
+  readonly phase: "live" | "archived";
+  readonly offset: number;
+  readonly query: string;
+}
+
+function queryKey(params: SnapshotParams): string {
+  return `${params.projectId ?? ""}|${params.includeArchived ? 1 : 0}|${params.includeChildren ? 1 : 0}`;
+}
+
+export function encodeCursor(cursor: Cursor): string {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+
+export function decodeCursor(value: string, params: SnapshotParams): Cursor {
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as Partial<Cursor>;
+    if ((parsed.phase !== "live" && parsed.phase !== "archived") || !Number.isSafeInteger(parsed.offset) || (parsed.offset as number) < 0 || parsed.query !== queryKey(params)) {
+      throw new Error("mismatch");
+    }
+    return { phase: parsed.phase, offset: parsed.offset as number, query: parsed.query };
+  } catch {
+    throw new PageError("invalid_params", "The cursor does not belong to this query");
+  }
+}
+
+async function pageAvailability(context: HandlerContext, sessions: readonly SessionRecord[]): Promise<Map<string, boolean>> {
+  const { serving } = context;
+  const byHost = new Map<string, { session: string; path: string }[]>();
+  await Promise.all(
+    sessions.map(async (session) => {
+      try {
+        const location = await serving.host.sessions.storage(session.id);
+        const entries = byHost.get(location.hostId) ?? [];
+        entries.push({ session: session.id, path: joinPath(location.rootPath, ENTRY_FILE) });
+        byHost.set(location.hostId, entries);
+      } catch {
+        // No storage yet: no page.
+      }
+    }),
+  );
+  const availability = new Map<string, boolean>();
+  await Promise.all(
+    [...byHost.entries()].map(async ([hostId, entries]) => {
+      const existence = await serving.host.files.exist(hostId, entries.map((entry) => entry.path));
+      for (const entry of entries) availability.set(entry.session, existence[entry.path] === true);
+    }),
+  );
+  return availability;
+}
+
+export const sessionsSnapshot = handler<SnapshotParams, unknown>({
+  method: "sessions.snapshot",
+  async execute(params, context) {
+    const { serving } = context;
+    const start: Cursor = params.cursor ? decodeCursor(params.cursor, params) : { phase: "live", offset: 0, query: queryKey(params) };
+    const collected: SessionRecord[] = [];
+    let phase = start.phase;
+    let offset = start.offset;
+    let next: Cursor | null = null;
+    while (collected.length < params.limit) {
+      const want = params.limit - collected.length;
+      const rows = await serving.host.sessions.list({
+        ...(params.projectId ? { projectId: params.projectId } : {}),
+        archived: phase === "archived",
+        rootsOnly: !params.includeChildren,
+        offset,
+        limit: want + 1,
+      });
+      const visible = rows.filter(
+        (row) => row.visibility === "visible" && !row.deleted && row.archived === (phase === "archived") && (params.includeChildren || row.parentId === null),
+      );
+      const more = rows.length > want;
+      collected.push(...visible.slice(0, want));
+      offset += Math.min(rows.length, want);
+      if (more) {
+        next = { phase, offset, query: start.query };
+        break;
+      }
+      if (phase === "live" && params.includeArchived) {
+        phase = "archived";
+        offset = 0;
+        continue;
+      }
+      break;
+    }
+    const availability = await pageAvailability(context, collected);
+    const sessions: SessionSummary[] = collected.map((record) => ({
+      id: record.id,
+      title: record.title.slice(0, LIMITS.titleChars),
+      projectId: record.projectId,
+      parentSessionId: record.parentId,
+      status: record.state,
+      archived: record.archived,
+      page: { available: availability.get(record.id) === true, revision: availability.get(record.id) ? serving.pages.knownRevision(record.id) : null },
+      updatedAtMs: record.updatedAtMs,
+      attentionAtMs: record.attentionAtMs,
+      unread: record.unread,
+    }));
+    return { result: { sessions, nextCursor: next ? encodeCursor(next) : null, generatedAtMs: serving.now() } };
+  },
+});
+
+export const projectsList = handler<null, unknown>({
+  method: "projects.list",
+  async execute(_params, { serving }) {
+    const projects = await serving.host.projects.list();
+    return { result: { projects: projects.slice(0, LIMITS.projectsMax).map((project) => ({ id: project.id, name: project.name.slice(0, LIMITS.titleChars), kind: project.kind })) } };
+  },
+});
+
+export const providersList = handler<null, unknown>({
+  method: "providers.list",
+  async execute(_params, { serving }) {
+    const providers = await serving.host.providers.list();
+    return {
+      result: {
+        providers: providers.slice(0, LIMITS.providersMax).map((provider) => ({
+          id: provider.id,
+          displayName: provider.displayName.slice(0, LIMITS.titleChars),
+          available: provider.available,
+          models: provider.models.slice(0, LIMITS.modelsPerProvider).map((model) => ({
+            id: model.id,
+            displayName: model.displayName.slice(0, LIMITS.titleChars),
+            isDefault: model.isDefault,
+            reasoningLevels: model.reasoningLevels.slice(0, 16),
+          })),
+        })),
+      },
+    };
+  },
+});
+
+export function storageKey(session: string, key: string): string {
+  return `state:${session}:${key}`;
+}
+
+export const storageGet = handler<{ key: string }, unknown>({
+  method: "storage.get",
+  async execute(params, { serving, session }) {
+    const stored = await serving.host.kv.get(storageKey(session.id, params.key));
+    return { result: stored === undefined ? { found: false } : { found: true, value: stored } };
+  },
+});
+
+export const storageSet = handler<{ key: string; value: JsonValue }, unknown>({
+  method: "storage.set",
+  async execute(params, { serving, session }) {
+    await serving.host.kv.set(storageKey(session.id, params.key), params.value);
+    return { result: { stored: true } };
+  },
+});

package/src/serving/bridge/handlers/writes.ts

@@ -0,0 +1,175 @@
+import type { SessionsSendParams, SessionsStartParams } from "../../../domain/capabilities/specs.ts";
+import { PageError } from "../../../domain/errors.ts";
+import { fingerprint } from "../../../domain/json/canonical.ts";
+import type { JsonValue } from "../../../domain/json/strict-json.ts";
+import { formatReplyMessage } from "../../../domain/submissions/message.ts";
+import type { SessionRecord, StartSessionArgs } from "../../../host/types.ts";
+import { excerpt, handler, type HandlerContext } from "../handler.ts";
+
+/** Writes to the page's own session, and the confirmed cross-session effects. spec 05 */
+
+interface ReplyParams {
+  title?: string;
+  mode: "queue" | "steer";
+  result: JsonValue;
+  idempotencyKey?: string;
+}
+
+export const sessionReply = handler<ReplyParams, unknown>({
+  method: "session.reply",
+  async execute(params, { serving, session, page, requestId }) {
+    const key = `${session.id}:${params.idempotencyKey ?? requestId}`;
+    const print = fingerprint({ revision: page.revision, result: params.result, mode: params.mode, title: params.title ?? null });
+    const remembered = serving.replies.remember(key, print, () => serving.host.sessions.send(session.id, formatReplyMessage(params.title, params.result), params.mode), serving.now());
+    if (remembered.kind === "conflict") throw new PageError("conflict", "This idempotency key was already used with a different reply");
+    const outcome = await remembered.outcome;
+    return { result: { delivery: outcome.delivery, duplicate: remembered.kind === "replay" } };
+  },
+});
+
+async function targetSession(context: HandlerContext, id: string): Promise<SessionRecord> {
+  const target = await context.serving.host.sessions.get(id);
+  if (!target || target.deleted) throw new PageError("not_found", "That session is not available");
+  return target;
+}
+
+export const sessionsSend = handler<SessionsSendParams, unknown>({
+  method: "sessions.send",
+  async refuse(params, context) {
+    if (params.sessionId === context.session.id) throw new PageError("invalid_params", "Use session.reply to answer this page's own session");
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Send to “${excerpt(target.title, 60)}”: “${excerpt(params.prompt)}”${params.mode === "steer" ? " (interrupting its current turn)" : ""}`;
+  },
+  async execute(params, { serving }) {
+    const sent = await serving.host.sessions.send(params.sessionId, params.prompt, params.mode);
+    return { result: { sessionId: params.sessionId, delivery: sent.delivery, duplicate: false } };
+  },
+});
+
+async function resolveStart(params: SessionsStartParams, context: HandlerContext): Promise<{ args: StartSessionArgs; projectName: string; environmentLabel: string }> {
+  const projects = await context.serving.host.projects.list();
+  const project = projects.find((candidate) => candidate.id === params.projectId);
+  if (!project) throw new PageError("not_found", "That project is not available");
+  let environment: StartSessionArgs["environment"] = { kind: "project-default" };
+  let environmentLabel = "the project's default environment";
+  if (typeof params.environment === "object") {
+    const other = await targetSession(context, params.environment.sameAs);
+    if (!other.environmentId) throw new PageError("invalid_params", "That session has no environment to share");
+    environment = { kind: "reuse", environmentId: other.environmentId };
+    environmentLabel = `the environment of “${excerpt(other.title, 40)}”`;
+  }
+  return {
+    args: {
+      projectId: params.projectId,
+      prompt: params.prompt,
+      ...(params.title ? { title: params.title } : {}),
+      ...(params.providerId ? { providerId: params.providerId } : {}),
+      ...(params.model ? { model: params.model } : {}),
+      ...(params.reasoningLevel ? { reasoningLevel: params.reasoningLevel } : {}),
+      environment,
+    },
+    projectName: project.name,
+    environmentLabel,
+  };
+}
+
+export const sessionsStart = handler<SessionsStartParams, unknown>({
+  method: "sessions.start",
+  async refuse(params, context) {
+    await resolveStart(params, context);
+  },
+  async summarize(params, context) {
+    const { projectName, environmentLabel } = await resolveStart(params, context);
+    const runtime = [params.providerId, params.model, params.reasoningLevel].filter(Boolean).join(" · ") || "the project's default provider and model";
+    return `Start a session in ${projectName}: “${excerpt(params.prompt)}” — using ${runtime}, in ${environmentLabel}`;
+  },
+  async execute(params, context) {
+    const { args } = await resolveStart(params, context);
+    const started = await context.serving.host.sessions.start(args);
+    return { result: { sessionId: started.id } };
+  },
+});
+
+export const sessionsStop = handler<{ sessionId: string }, unknown>({
+  method: "sessions.stop",
+  async refuse(params, context) {
+    if (params.sessionId === context.session.id) throw new PageError("invalid_params", "A page cannot stop its own session");
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Stop “${excerpt(target.title, 60)}”`;
+  },
+  async execute(params, { serving }) {
+    await serving.host.sessions.stop(params.sessionId);
+    return { result: { stopped: true } };
+  },
+});
+
+export const sessionsArchive = handler<{ sessionId: string }, unknown>({
+  method: "sessions.archive",
+  async refuse(params, context) {
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Archive “${excerpt(target.title, 60)}”${params.sessionId === context.session.id ? " (this page's own session; its page will stop being served)" : ""}`;
+  },
+  async execute(params, { serving }) {
+    await serving.host.sessions.archive(params.sessionId);
+    return { result: { archived: true } };
+  },
+});
+
+export const sessionsMarkRead = handler<{ sessionId: string; read: boolean }, unknown>({
+  method: "sessions.markRead",
+  async refuse(params, context) {
+    await targetSession(context, params.sessionId);
+  },
+  async execute(params, { serving }) {
+    const after = await serving.host.sessions.markRead(params.sessionId, params.read);
+    return { result: { sessionId: params.sessionId, unread: after.unread } };
+  },
+});
+
+export const projectsBrowse = handler<null, unknown>({
+  method: "projects.browse",
+  async summarize() {
+    return "Choose a project folder on this device";
+  },
+  async execute(_params, { serving, session }) {
+    const location = await serving.host.sessions.storage(session.id);
+    const picked = await serving.host.projects.browse(location.hostId);
+    if (!picked) return { result: { selection: null } };
+    const token = serving.selections.issue({ session: session.id, hostId: location.hostId, path: picked.path }, serving.now());
+    return { result: { selection: { token, displayPath: displayPath(picked.path), hostName: picked.hostName } } };
+  },
+});
+
+function displayPath(path: string): string {
+  return path.replace(/^\/Users\/[^/]+/, "~").replace(/^\/home\/[^/]+/, "~").replace(/^[A-Za-z]:\\Users\\[^\\]+/, "~");
+}
+
+export const projectsCreate = handler<{ selectionToken: string; name?: string }, unknown>({
+  method: "projects.create",
+  async refuse(params, { serving, session }) {
+    if (!serving.selections.peek(params.selectionToken, session.id, serving.now())) {
+      throw new PageError("not_found", "That folder selection has expired; choose the folder again");
+    }
+  },
+  async summarize(params, { serving, session }) {
+    const selection = serving.selections.peek(params.selectionToken, session.id, serving.now());
+    const name = params.name ?? selection?.path.split(/[\\/]/).pop() ?? "the selected folder";
+    return `Create project “${excerpt(name, 60)}” from ${selection ? displayPath(selection.path) : "the selected folder"}`;
+  },
+  async execute(params, { serving, session }) {
+    const selection = serving.selections.redeem(params.selectionToken, session.id, serving.now());
+    if (!selection) throw new PageError("not_found", "That folder selection has expired; choose the folder again");
+    const name = params.name ?? selection.path.split(/[\\/]/).pop() ?? "New project";
+    const created = await serving.host.projects.create({ name, hostId: selection.hostId, path: selection.path });
+    return { result: { project: { id: created.id, name: created.name, kind: created.kind } } };
+  },
+});

package/src/serving/bridge/selection-store.ts

@@ -0,0 +1,58 @@
+import { randomBytes } from "node:crypto";
+import { LIMITS } from "../../domain/limits.ts";
+
+/**
+ * Folder-picker selections, held server-side so a page only ever sees an
+ * opaque token: single use, short-lived, bound to the requesting session.
+ * spec R5.35–R5.37
+ */
+export interface Selection {
+  readonly session: string;
+  readonly hostId: string;
+  readonly path: string;
+  readonly expiresAt: number;
+}
+
+export interface SelectionStore {
+  issue(selection: Omit<Selection, "expiresAt">, now: number): string;
+  /** Looks a selection up without consuming it. */
+  peek(token: string, session: string, now: number): Selection | null;
+  /** Returns and forgets the selection when the token is valid for the session. */
+  redeem(token: string, session: string, now: number): Selection | null;
+}
+
+export function createSelectionStore(): SelectionStore {
+  const selections = new Map<string, Selection>();
+
+  function prune(now: number): void {
+    for (const [token, selection] of selections) {
+      if (selection.expiresAt <= now) selections.delete(token);
+    }
+    while (selections.size > LIMITS.selectionTokens) {
+      const oldest = selections.keys().next().value;
+      if (oldest === undefined) break;
+      selections.delete(oldest);
+    }
+  }
+
+  return {
+    issue(selection, now) {
+      prune(now);
+      const token = `sel.${randomBytes(18).toString("base64url")}`;
+      selections.set(token, { ...selection, expiresAt: now + LIMITS.selectionTokenMs });
+      return token;
+    },
+    peek(token, session, now) {
+      prune(now);
+      const selection = selections.get(token);
+      return selection && selection.session === session ? selection : null;
+    },
+    redeem(token, session, now) {
+      prune(now);
+      const selection = selections.get(token);
+      if (!selection || selection.session !== session) return null;
+      selections.delete(token);
+      return selection;
+    },
+  };
+}

package/src/serving/bridge-route.ts

@@ -0,0 +1,23 @@
+import type { Context } from "hono";
+import { failure } from "../domain/capabilities/protocol.ts";
+import { PageError } from "../domain/errors.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { readJsonBody } from "./action-request.ts";
+import type { createDispatcher } from "./bridge/dispatcher.ts";
+import { jsonResponse } from "./responses.ts";
+
+/** `POST /bridge` — one capability invocation. */
+export function bridgeRoute(dispatch: ReturnType<typeof createDispatcher>) {
+  return async (context: Context): Promise<Response> => {
+    let body: unknown;
+    try {
+      body = await readJsonBody(context, LIMITS.capabilityPayloadBytes + 8_192);
+    } catch (error) {
+      const failed = PageError.is(error) ? error : new PageError("invalid_json", "Invalid bridge body");
+      const code = failed.code === "request_too_large" ? "request_too_large" : "invalid_json";
+      return jsonResponse({ response: failure(undefined, code, failed.message) }, failed.status);
+    }
+    const outcome = await dispatch(body);
+    return jsonResponse(outcome.body, outcome.status);
+  };
+}

package/src/serving/context.ts

@@ -0,0 +1,34 @@
+import type { CapabilityRegistry } from "../domain/capabilities/registry.ts";
+import type { RateLimiter } from "../domain/rate-limit.ts";
+import type { OutcomeMemory } from "../domain/submissions/idempotency.ts";
+import type { LiveSettings } from "../config/settings.ts";
+import type { SessionHost } from "../host/contract.ts";
+import type { PageStore } from "../pages/page-store.ts";
+import type { SiteStrategy } from "../pages/site.ts";
+import type { SelectionStore } from "./bridge/selection-store.ts";
+
+/** Everything a route or handler may need, assembled once by the composition root. */
+export interface ServingContext {
+  readonly host: SessionHost;
+  readonly pages: PageStore;
+  readonly settings: LiveSettings;
+  readonly signingKey: Uint8Array;
+  readonly site: SiteStrategy;
+  readonly routeBase: string;
+  readonly registry: CapabilityRegistry;
+  readonly rate: RateLimiter;
+  readonly submissions: OutcomeMemory<{ status: number; body: Record<string, unknown> }>;
+  readonly replies: OutcomeMemory<{ delivery: "started" | "queued" | "steered" }>;
+  readonly selections: SelectionStore;
+  /** The host application's URL for a session's conversation, origin-relative. */
+  readonly hostSessionUrl: (session: string) => string;
+  readonly now: () => number;
+}
+
+export function pageUrl(routeBase: string, session: string): string {
+  return `${routeBase}/page?session=${encodeURIComponent(session)}`;
+}
+
+export function homeUrl(routeBase: string): string {
+  return `${routeBase}/home`;
+}

package/src/serving/document-route.ts

@@ -0,0 +1,37 @@
+import type { Context } from "hono";
+import { injectKernel } from "../domain/html/document.ts";
+import { etagFor, ifNoneMatchMatches } from "../domain/revision.ts";
+import { KERNEL_RUNTIME } from "../generated/kernel-runtime.ts";
+import type { KernelConfig } from "../runtime/shared/protocol.ts";
+import type { ServingContext } from "./context.ts";
+import { baseHeaders, documentCsp, failureResponse } from "./responses.ts";
+import { eligibleSession, sessionIdFrom } from "./session-access.ts";
+
+/**
+ * `GET /document?session=<id>` — the entry document with the kernel injected,
+ * and the shell's revision poll: the ETag is the revision, the activity and
+ * source state ride along as headers. spec R2.11–R2.13, R2.17, R2.25
+ */
+export function documentRoute(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 headers = baseHeaders("text/html; charset=utf-8");
+      headers.set("content-security-policy", documentCsp());
+      headers.set("etag", etagFor(page.revision));
+      headers.set("x-thread-page-stale", String(page.stale));
+      headers.set("x-thread-page-activity", session.state);
+      headers.set("x-thread-page-updated-at", String(page.updatedAtMs));
+      if (ifNoneMatchMatches(context.req.header("if-none-match"), etagFor(page.revision))) {
+        return new Response(null, { status: 304, headers });
+      }
+      const config: KernelConfig = { pageRevision: page.revision, stale: page.stale };
+      const html = injectKernel(page.html, { kernel: KERNEL_RUNTIME, config, baseHref: serving.site.baseHref(id) });
+      return new Response(html, { status: 200, headers });
+    } catch (error) {
+      return failureResponse(error, serving.host.log, "GET /document", true);
+    }
+  };
+}

package/src/serving/home-route.ts

@@ -0,0 +1,23 @@
+import type { Context } from "hono";
+import { isSessionId } from "../domain/ids.ts";
+import type { ServingContext } from "./context.ts";
+import { pageUrl } from "./context.ts";
+import { errorPage } from "./responses.ts";
+
+/** `GET /home` — a redirect to the designated home page, never a listing. spec R7.9, R7.4 */
+export function homeRoute(serving: ServingContext) {
+  return async (_context: Context): Promise<Response> => {
+    const home = serving.settings.current().homeSessionId;
+    if (!isSessionId(home)) {
+      return errorPage(
+        "No home page is set yet. A home page is an ordinary page some agent built and designated. To get one, ask any agent: “Set up my Thread Pages home page” — it runs `bb thread-page home` in a session dedicated to it and builds a hub of your sessions there. Or run `bb thread-page home` yourself in the session whose page should be home.",
+        404,
+      );
+    }
+    const session = await serving.host.sessions.get(home).catch(() => null);
+    if (!session || session.deleted || session.archived) {
+      return errorPage("The home page points at a session that no longer exists. Run `bb thread-page home` in another session, or `bb thread-page home --clear`.", 404);
+    }
+    return new Response(null, { status: 302, headers: { location: pageUrl(serving.routeBase, home), "cache-control": "no-store, max-age=0" } });
+  };
+}

package/src/serving/responses.ts

@@ -0,0 +1,81 @@
+import { PageError, errorText } from "../domain/errors.ts";
+import { escapeHtml } from "../domain/html/escape.ts";
+import type { HostLogger } from "../host/types.ts";
+
+/** Response helpers and the two content security policies. spec R2.41–R2.43, 03 */
+
+export function baseHeaders(contentType: string): Headers {
+  return new Headers({
+    "cache-control": "no-store, max-age=0",
+    "content-type": contentType,
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+    "permissions-policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+  });
+}
+
+/** The trusted shell: nothing runs but our nonced script and style. */
+export function shellCsp(nonce: string): string {
+  return [
+    "default-src 'none'",
+    "base-uri 'none'",
+    "connect-src 'self'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+    "frame-src 'self'",
+    `script-src 'nonce-${nonce}'`,
+    `style-src 'nonce-${nonce}'`,
+    "img-src 'self' data:",
+  ].join("; ");
+}
+
+/**
+ * The document: open network and arbitrary code (spec R3.4, R3.11), no
+ * frames (embedding is deferred), no plugins, same-origin bases only, and
+ * the sandbox restated so it holds even if the frame attribute did not.
+ */
+export function documentCsp(): string {
+  return [
+    "default-src * data: blob: 'unsafe-inline' 'unsafe-eval'",
+    "script-src * data: blob: 'unsafe-inline' 'unsafe-eval'",
+    "style-src * data: blob: 'unsafe-inline'",
+    "img-src * data: blob:",
+    "font-src * data: blob:",
+    "media-src * data: blob:",
+    "connect-src * data: blob:",
+    "worker-src * blob: data:",
+    "frame-src 'none'",
+    "child-src blob:",
+    "object-src 'none'",
+    "base-uri 'self'",
+    "sandbox allow-scripts allow-forms",
+  ].join("; ");
+}
+
+export function jsonResponse(value: unknown, status = 200, extra?: Record<string, string>): Response {
+  const headers = baseHeaders("application/json; charset=utf-8");
+  for (const [key, entry] of Object.entries(extra ?? {})) headers.set(key, entry);
+  return new Response(JSON.stringify(value), { status, headers });
+}
+
+export function errorJson(error: PageError): Response {
+  return jsonResponse({ ok: false, code: error.code, message: error.message }, error.status);
+}
+
+export function errorPage(message: string, status: number): Response {
+  const headers = baseHeaders("text/html; charset=utf-8");
+  headers.set("content-security-policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Thread Page</title><style>body{max-width:42rem;margin:4rem auto;padding:0 1rem;font:16px/1.5 system-ui,sans-serif;color:CanvasText;background:Canvas}h1{font-size:1.4rem}</style></head><body><main><h1>Thread Page</h1><p>${escapeHtml(message)}</p></main></body></html>`;
+  return new Response(html, { status, headers });
+}
+
+/** Turns any failure into a response, logging the cause when it is not a page error. */
+export function failureResponse(error: unknown, log: HostLogger, where: string, asPage: boolean): Response {
+  if (PageError.is(error)) {
+    if (error.cause !== undefined) log.warn(`${where}: ${error.code}: ${errorText(error.cause)}`);
+    return asPage ? errorPage(error.message, error.status) : errorJson(error);
+  }
+  log.warn(`${where}: ${errorText(error)}`);
+  const generic = new PageError("handler_error", "Something went wrong serving this page.");
+  return asPage ? errorPage(generic.message, 500) : errorJson(generic);
+}

package/src/serving/routes.ts

@@ -0,0 +1,26 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { createDispatcher } from "./bridge/dispatcher.ts";
+import { ALL_HANDLERS } from "./bridge/handlers/index.ts";
+import { bridgeRoute } from "./bridge-route.ts";
+import type { ServingContext } from "./context.ts";
+import { documentRoute } from "./document-route.ts";
+import { homeRoute } from "./home-route.ts";
+import { shellRoute } from "./shell-route.ts";
+import { submitRoute } from "./submit-route.ts";
+import { uploadRoute } from "./upload-route.ts";
+
+/**
+ * The route table. spec 02 §Routes
+ *
+ * Every route uses the host's "local" auth: the reader's existing session
+ * with bb, plus the action token where an effect is possible.
+ */
+export function registerRoutes(bb: BbPluginApi, serving: ServingContext): void {
+  const dispatch = createDispatcher(serving, ALL_HANDLERS);
+  bb.http.route("GET", "/page", shellRoute(serving), { auth: "local" });
+  bb.http.route("GET", "/document", documentRoute(serving), { auth: "local" });
+  bb.http.route("GET", "/home", homeRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/submit", submitRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/upload", uploadRoute(serving), { auth: "local" });
+  bb.http.route("POST", "/bridge", bridgeRoute(dispatch), { auth: "local" });
+}