@unifedev/thread-pages 1.0.3 → 1.1.0

package/dist/server.meta.json

@@ -3,7 +3,7 @@
   "sdkVersion": "0.4.47",
   "artifactFormatVersion": 1,
   "pluginId": "thread-pages",
-  "pluginVersion": "1.0.3",
+  "pluginVersion": "1.1.0",
   "builtWith": {
     "bbVersion": "0.42.1",
     "pluginSdkVersion": "0.4.47"

package/docs/B1-OWN-FILES.md

@@ -0,0 +1,133 @@
+# A page's own files, and the workaround that should be deleted
+
+**Status:** the workaround shipped. It is temporary by design. This document
+says what it works around, how to know the workaround is no longer needed, and
+exactly what to delete.
+
+## The bug
+
+A page that loads its own stylesheet or data file renders correctly on
+loopback and **renders empty for the reader on bb Connect** — the origin a
+reader actually uses on a phone. Nothing errors. The author cannot see it from
+the machine that wrote the page, so every fixture in `verify/` passed while the
+feature was broken in the field.
+
+Reported as B1 in `unife-bb-plugin/docs/FIELD-ISSUES-2026-09-08.md`, where a
+reader saw a fully functional interface reporting that a 300-row wiki was
+empty.
+
+## The cause, measured
+
+Unauthenticated GETs, no cookie, 2026-09-09, bb 0.42.1:
+
+| Path | loopback `127.0.0.1:38886` | `bart.getbb.app` |
+| --- | --- | --- |
+| `…/plugins/thread-pages/http/page?session=…` | 200 | 401 |
+| `…/threads/<id>/thread-storage/files/index.html` | 200 | 401 |
+| `/api/v1/health` (does not exist) | 404 | 401 |
+| `…/plugins/nonexistent-xyz/http/page` | 404 | **401** |
+
+The last row is the one that matters: a plugin that does not exist gets bb's
+own 404 locally and Cloudflare's 401 remotely. **bb Connect authenticates at
+the edge, before bb is reached at all.** The remote responses carry
+`server: cloudflare` and a `cf-ray`, and their body is the Connect sign-in
+gate — `apps/connect/src/worker.ts` in `get-bb/bb`, which ends its credential
+ladder with `signInPage(...)` when no session cookie is present.
+
+The page frame is `sandbox="allow-scripts allow-forms"`, so it has an opaque
+origin. Its **document** request is issued by the trusted shell, whose
+site-for-cookies is the Connect host, so the `SameSite=Lax` cookie is attached
+and the document loads. Any **subresource** request issued from inside that
+frame has an opaque origin in its ancestor chain, so its site-for-cookies is
+null, the request counts as cross-site, and the Lax cookie is not attached.
+Both Connect cookies are Lax: `apps/desktop/src/connect-desktop-session.ts`
+hard-codes `sameSite: "lax"`, and the account cookie is better-auth's default.
+
+The document-request half and the edge-gate half are measured. The
+cookie-attachment rule is the specification applied to a case that cannot be
+instrumented without devtools on the authenticated remote origin; it is the
+only account consistent with what was observed.
+
+### What this rules out
+
+**Plugin prefix routes do not fix this.** The `plugin-prefix` site strategy in
+`src/pages/site.ts` and the proposal in
+`unife-bb-plugin/rewrite/07-bb-prefix-routes-proposal.md` move a page's files
+from one path the edge 401s to another path the edge 401s. Prefix routes fix a
+different bug — X17, `fetch()` of a page's own files, refused because bb core
+routes reject `Origin: null` — and they are the substrate the real fix needs.
+They are not the fix.
+
+## The workaround, as shipped
+
+`src/pages/inline.ts` resolves every relative reference in the entry document
+against the page root **when the document is served**, and rewrites it to a
+`data:` URL. The document is the one artifact whose request is always
+authorised, so it carries the page's files with it.
+
+- The URL is rewritten, not the element, so `defer`, `type="module"`, `media`,
+  `alt` and every other attribute keep their meaning — and a file containing
+  `</script>` cannot break out of the document.
+- `url()` inside a resolved stylesheet is followed, bounded by
+  `LIMITS.inlineCssDepth`.
+- Anything absolute, protocol-relative, already a URL, or a bare fragment is
+  left exactly as written.
+- Anything missing, over `LIMITS.inlineFileBytes`, or over
+  `LIMITS.inlineTotalBytes` is left as written and logged by path and reason.
+  The page degrades to its pre-workaround behaviour rather than to a broken
+  document.
+- Traversal is refused by `isSafeRelativePath` and reported as `unsafe-path`.
+
+Wired in `src/plugin.ts` (one argument to `createPageStore`) and resolved
+inside `PageStore.load`, so the served document, its revision, its ETag and its
+offline copy all describe the same bytes.
+
+### What it costs
+
+- A page's files are inside the document, so they count against the 5 MiB
+  entry limit, and a page over 200 KiB keeps no offline copy. That drop used
+  to be silent; `page-store.ts` now logs it with the size and the limit.
+- base64 adds a third.
+- Files are re-read on each document load. Sidecar edits therefore reload an
+  open page, which is a better story than before — but a very large data file
+  is re-read on every revision poll that returns a body.
+- A `data:` URL module script cannot resolve relative imports.
+
+## When to delete it
+
+When the host can authorise a sandboxed document's own subresource requests.
+Concretely, when **both** of these have landed in bb:
+
+1. **Prefix plugin HTTP routes** — `bb.http.route("GET", "/page/*", …)` with
+   `auth: "none"`, so this plugin can serve its own page directory and the
+   document URL becomes path-shaped. Branch: `feat/plugin-prefix-http-routes`.
+2. **A Connect page grant** — a short-lived, signed, GET-only credential
+   carried as a path segment (`…/http/__grant/<token>/…`, so relative
+   references inherit it) that the Connect worker verifies and strips before
+   forwarding. Branch: `feat/connect-page-grant`.
+
+A cookie change (`SameSite=None`) was considered and rejected: it attaches the
+cookie to every cross-site request to the Connect domain, including subresource
+GETs that carry no `Origin` header for bb's own origin checks to reject.
+
+### How to verify it is no longer needed
+
+Write a file beside `index.html`, reference it relatively, disable the
+workaround, and read the page **over bb Connect on a phone or with devtools on
+the remote origin** — never on loopback, where it has always worked. This is
+the acceptance criterion `verify/` is missing.
+
+### What to delete
+
+1. `src/pages/inline.ts` and `test/pages/inline.test.ts`.
+2. The `resolve` argument to `createPageStore` in `src/plugin.ts`, and the
+   `PageResolver` type, the `site` field on `LoadedPage`, and the resolve block
+   in `PageStore.load` in `src/pages/page-store.ts`.
+3. `inlineFileBytes`, `inlineTotalBytes` and `inlineCssDepth` from
+   `src/domain/limits.ts`.
+4. The "How this actually works" block in `ownFiles()` and the added row in
+   `limitations()` in `src/agent/guide.ts`, plus the guide tests asserting them.
+5. This document.
+
+Keep the offline-copy warning in `page-store.ts`. It was always right; the
+workaround only made it matter sooner.

package/docs/FOR-PAGE-AUTHORS-1.1.md

@@ -0,0 +1,167 @@
+# Thread Pages 1.1 — for an agent that already has a page
+
+You are reading this because your session has a page you wrote against 1.0.x.
+Nothing you wrote has broken. Some things you were told were impossible are now
+possible, one workaround you were told to use is no longer needed, and two
+things in your page are worth fixing while you are here.
+
+Run `bb thread-page guide` for the full current contract. This file is only the
+difference.
+
+---
+
+## 1. Your page's own files work now — on the reader's phone, not just yours
+
+**What you were told in 1.0:** subresources "load normally", and `fetch()` of
+your own files is refused.
+
+**What was actually true:** a file beside `index.html` loaded on loopback and
+was **refused on any authenticated origin**, including bb Connect, which is how
+your reader opens the page on a phone. Your page rendered; its stylesheet and
+data did not; nothing errored. If you built anything that reads a file beside
+`index.html`, it has probably been silently empty for your reader this whole
+time, and you could not have seen it from your own machine.
+
+**What is true now:** the host resolves every relative reference when it serves
+the document and rewrites it to a `data:` URL. Write the reference; it works on
+every origin.
+
+    <link rel="stylesheet" href="page.css">
+    <script src="data.js"></script>
+    <img src="figures/chart.png" alt="…">
+
+`url()` inside a stylesheet you reference is followed too, so backgrounds and
+`@font-face` survive.
+
+### What to do about it
+
+**If you inlined data into `index.html` because the guide told you to** — move
+it back out. `<script src="data.js">` works, and it makes your entry document
+small again, which makes it cheap to edit.
+
+**If your page has a file beside it and shows zeroes** — that was this bug. It
+should be right now; no change needed on your side.
+
+## 2. You can publish new data without rewriting `index.html`
+
+Changing a file beside `index.html` changes the served document, so an open page
+reloads within about ten seconds. That is the whole live-data mechanism: write
+`data.js`, the reader's page updates.
+
+Two things to get right, both in the guide under *Keeping a page's data current*:
+
+- **Make the write deterministic.** An unchanged data set must produce a
+  byte-identical file. A generated timestamp in the payload turns every rebuild
+  into a reload for every reader, and your page will look like it is flickering
+  for no reason.
+- **Call `setDirty(true)`** while the reader is mid-edit in state the host
+  cannot see. Captured forms do this for you; your own widgets do not.
+
+## 3. Your files now count against the document's size
+
+Because they are carried inside the document:
+
+| | |
+| --- | --- |
+| Entry document | 5 MiB, including everything it carries |
+| Per file | 2 MiB |
+| All files together | 3 MiB |
+| Offline copy kept | only under 200 KiB total |
+| base64 | adds a third to all of the above |
+
+A file that is missing, too large or over the budget is **left exactly as you
+wrote it** and named in the log — `bb plugin logs thread-pages`. Your page still
+renders; that one reference does not resolve. Check the log once after you
+publish; it is the only place this is reported.
+
+If your page carries a large dataset and you care about it opening offline, keep
+the document under 200 KiB. The host now warns in the log when it drops the
+offline copy instead of dropping it silently.
+
+## 4. `[hidden]` — fix this in your page by hand
+
+A class rule that sets `display` outranks the user-agent rule for the `hidden`
+attribute, so `<p class="banner" hidden>` rendered as an empty coloured bar. New
+pages get the fix in their seeded stylesheet. **Your page carries its own copy of
+the stylesheet and will not get it.** Add this to your `<style>`:
+
+    [hidden] { display: none !important; }
+
+If you have ever written `hidden` on an element and been confused by a stray
+empty bar in a screenshot, this was why.
+
+## 5. Delete the old seed comment from your page
+
+The 1.0 seed's authoring comment spelled HTML tags out literally — `<main>`,
+`<style>`, `<script src="app.js">`. They are comment text, not elements, but
+every string operation you run on your own file sees them. A structural check on
+a healthy page reports two `<main>` elements and one unclosed `<script>`, and
+`indexOf("<main>")` finds the comment before the real element, so the obvious
+splice starts in the wrong place.
+
+**If that comment is still in your `index.html`, delete it or rewrite it without
+angle brackets.** It is costing you every time you edit your page. The current
+seed names no tags at all.
+
+## 6. Edit your page by rewriting it, not by splicing
+
+There is no page-editing command and there is not meant to be one: `index.html`
+is a file in your storage directory that you read and write with your ordinary
+tools. **Nothing in it is reserved** — not the stylesheet, not the header, not
+the comment it came with. Rewrite the whole document. A splice computed from
+string indices can silently eat content; a whole-document write cannot.
+
+This got much cheaper in 1.1: with §1 fixed, your stylesheet can live in
+`page.css` instead of taking up 27 KB of the file you are rewriting.
+
+## 7. If your page should stay put, it must not carry a form
+
+A page nobody should have to rewrite — a dashboard, a console — holds no
+captured `<form>`, because a form messages your session and something then has
+to rewrite the page. Its buttons should call `sessions.start` and `pages.open`
+instead. The 1.0 seed shipped a reply form, which read as an endorsement of the
+wrong default; the current seed says to delete it.
+
+**A page may now also be build output** — a script generating it from
+version-controlled source is legitimate. The rule that does not bend: the page
+still has one owning session, and that session's agent builds it the first time.
+A page with no agent behind it is a page nobody can be asked to change.
+
+## 8. If you call a 0.3.x method, the error now tells you the new name
+
+    Unknown capability: threads.spawn (renamed to sessions.start in 1.0; there is no alias)
+
+The full table is in `docs/UPGRADING.md`. There are still no aliases; the old
+name still fails.
+
+## 9. Before you save, read it over the reader's real origin
+
+The old checklist covered 320px, dark mode and reduced motion — all things you
+can check locally. It missed the only axis where behaviour actually differs:
+**authentication.** A local bb requires no credential and a remote one does.
+Read your page once over bb Connect, not only loopback. That is what would have
+caught §1 two days earlier.
+
+## What is still not possible
+
+Unchanged in 1.1, so do not spend time on them:
+
+- `fetch("data.json")` of your own file from page script. Only references in the
+  document are resolved. Use `<script src="data.js">` or inline it.
+- Embedding another page or site in an `<iframe>` (`frame-src 'none'`).
+- `window.open`, `window.prompt`, `alert`, `confirm`, top-level navigation.
+- Reading a file from the project your session belongs to.
+- Reading or writing another agent's page, and any registry that would let one
+  page list itself on another. If two pages should look alike, read the other
+  page and copy from it.
+- `voice.captureAndTranscribe`.
+
+## A five-minute pass over your page
+
+1. `bb thread-page init` — confirm it still says EXISTING and prints no warning.
+2. Add `[hidden] { display: none !important; }` to your `<style>` (§4).
+3. Delete the old seed comment if it is still there (§5).
+4. If you inlined data to work around §1, move it into a file beside the page.
+5. If the page should stay put, remove any captured `<form>` (§7).
+6. `bb plugin logs thread-pages` — check nothing of yours failed to resolve (§3).
+7. Read it once over bb Connect, on a phone if you can (§9).

package/docs/UPGRADING.md

@@ -0,0 +1,53 @@
+# Upgrading
+
+## 0.3.x → 1.0
+
+1.0.0 was a rewrite against the specification, and it renamed the whole
+page-facing surface at once. Nothing is aliased: an old name fails rather than
+silently doing the right thing. A page written against 0.3.x therefore breaks
+in several places at the same time, each of them quietly.
+
+| 0.3.x | 1.0 |
+| --- | --- |
+| `thread-page.html` | `index.html` |
+| `thread-page-assets/` | any file beside the entry document, nested paths included |
+| `threads.spawn` | `sessions.start` |
+| `threads.snapshot` | `sessions.snapshot` |
+| `threads.send` | `sessions.send` |
+| `threads.stop` | `sessions.stop` |
+| `threads.archive` | `sessions.archive` |
+| `threads.openPage` | `pages.open` |
+| `threads.openBb` | `sessions.openHost` |
+| `thread.get` | `context.get` |
+| `thread.reply` / `threads.reply` | `session.reply` |
+| `thread.activity` / `threads.activity` | `session.activity` |
+| `page.storage.get` / `page.storage.set` | `storage.get` / `storage.set` |
+| `navigation.open` | `navigation.openExternal` |
+| `homeThreadId` (plugin setting) | `homeSessionId` (`bb thread-page status`) |
+| `window.threadPage.assetUrl()` | removed — the API is frozen at `invoke` / `watch` / `setDirty` / `version` |
+
+### The two that cost the most
+
+**The entry document was renamed.** `thread-page.html` is not served and not
+migrated. A session that had a page looks like a session that never had one.
+`bb thread-page init` notices the old file and says so; move what you want out
+of it by hand.
+
+**`assetUrl()` was removed rather than deprecated**, so a page that calls it
+throws instead of degrading. Reference files relatively instead.
+
+### What the host tells you now
+
+Calling a renamed method returns `unknown_method` with the replacement named:
+
+    Unknown capability: threads.spawn (renamed to sessions.start in 1.0; there is no alias)
+
+The table above is the complete list the host recognises; see
+`src/domain/capabilities/renamed.ts`.
+
+### Not a rename
+
+`sessions.snapshot` also changed behaviour in 1.0.2: it lists root sessions
+only unless you pass `includeChildren: true`, and every session now carries
+`unread` and `attentionAtMs`. Check `bb thread-page guide` for the current
+shape rather than assuming the 0.3.x one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifedev/thread-pages",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Thread Pages for bb: every agent session gets one directly editable HTML page you can read and answer from, on any device.",
   "license": "MIT",
   "author": "Bartosz",
@@ -66,6 +66,7 @@
     "!src/**/*.test.ts",
     "dist/server.js",
     "dist/server.meta.json",
+    "docs/*.md",
     "README.md",
     "tsconfig.json",
     "package-lock.json"

package/src/agent/guide.ts

@@ -17,6 +17,7 @@ export function buildGuide(registry: CapabilityRegistry, site: SiteStrategy): st
     forms(),
     uploads(),
     ownFiles(site),
+    keepingCurrent(),
     runtimeApi(),
     capabilities(registry),
     startingSessions(),
@@ -25,6 +26,7 @@ export function buildGuide(registry: CapabilityRegistry, site: SiteStrategy): st
     composition(),
     home(),
     accessibility(),
+    upgrading(),
     limits(),
     limitations(site),
   ].join("\n\n");
@@ -145,20 +147,65 @@ spaces and punctuation in names are all fine:
 
 No permission, no declaration, no API: writing a file into your page root is
 enough. Keep everything inside your own page root; another agent's page is
-not yours to write.${
+not yours to write.
+
+**How this actually works, because it constrains what you can do.** Your page
+runs in a sandbox on an opaque origin, and a request it makes for itself
+carries no credential. A bb on loopback asks for none and the file arrives; a
+bb reached over an authenticated origin — which is how the reader opens the
+page on a phone — refuses it. So the host resolves your relative references
+**when it serves the document**: each one is read from your page root and
+rewritten to a \`data:\` URL before the reader's browser ever sees it. The
+consequences worth knowing:
+
+- It works the same on every origin. Write the reference; do not work around it.
+- Your files are **inside the document**, so they count against the ${mebibytes(LIMITS.entryDocumentBytes)}
+  entry limit, and a page over ${kibibytes(LIMITS.offlineCopyBytes)} keeps no offline copy. Per file at
+  most ${mebibytes(LIMITS.inlineFileBytes)}, ${mebibytes(LIMITS.inlineTotalBytes)} across the page; base64 adds a third to both.
+- A file that is missing, too large or over the budget is **left as you wrote
+  it** and named in the plugin log (\`bb plugin logs thread-pages\`). The page
+  still renders; that one reference does not resolve.
+- \`url()\` inside a stylesheet you reference is followed too, so backgrounds
+  and \`@font-face\` survive. Absolute and remote URLs are never touched.
+- Changing a file beside ${ENTRY_FILE} changes the document, so an open page
+  reloads — see *Keeping a page's data current*. You do not have to touch
+  ${ENTRY_FILE} to publish new data.
+${
   site.name === "core-storage"
     ? `
-
-**One limitation on this host:** \`fetch("data.json")\` of your own file from
-page script is refused (403) — the host's file route rejects the sandbox's
-\`Origin: null\`. Subresources (<script>, <link>, <img>) load normally, so
-load data with <script src="data.js"> or inline it in the document. Remote
-fetches work (see Network).`
+**One limitation left on this host:** \`fetch("data.json")\` of your own file
+from page script is refused (403) — the host's file route rejects the
+sandbox's \`Origin: null\`, and only subresource references are resolved for
+you. Load data with <script src="data.js"> or inline it in the document.
+Remote fetches work (see Network).`
     : `
-
 Page script may also fetch its own files as data: \`await fetch("data.json")\`.`
 }`;
 
+const keepingCurrent = () => `## Keeping a page's data current
+
+The entry document is the only artifact guaranteed to reach every reader, on
+every origin. Rewriting it is therefore how you push new data to an open page:
+the shell notices the new revision within ${LIMITS.shellPollMs / 1000} s and reloads the page under
+the reader, preserving what they were typing. You do not need a poller, a
+sidecar or a socket for this — a page that follows a data source is a page
+something rewrites.
+
+Three things to get right:
+
+- **Make the build deterministic.** An unchanged data set must produce a
+  byte-identical document. This is the non-obvious half: a generated timestamp
+  in the payload turns every rebuild into a reload for every reader, and the
+  page will look like it is flickering for no reason.
+- **Set \`setDirty(true)\` while the reader is mid-edit** in state the host
+  cannot see. A captured form does this for you; your own widgets do not.
+- **Refresh on a slow watch, not a tight timer.** A page shares a budget of
+  ${LIMITS.ratePerMinute} requests a minute with its own forms.
+
+\`window.threadPage.watch\` is the other half, for live host state — sessions,
+activity — that does not live in your file. Use the document rewrite for data
+you generate, and \`watch\` for data the host owns.`;
+
 const runtimeApi = () => `## window.threadPage
 
 The complete page-facing API; it is frozen and cannot be replaced.
@@ -270,7 +317,23 @@ writes its own page. Link to it with \`pages.open\`, or suggest making it home.
 If you want another agent's page changed, send that agent a message with
 \`sessions.send\` rather than editing its file. Do not create a session merely
 to hold a page: a page that stays put is owned by a real agent that built it
-and then stopped.`;
+and then stopped.
+
+**The whole file is yours.** There is no page-editing API and there is not
+meant to be one: ${ENTRY_FILE} is a file in your storage directory that you
+read and write with your ordinary tools. Nothing in it is reserved — not the
+stylesheet, not the header, not the comment the seed came with. Rewriting the
+document whole is the expected way to change it, and safer than splicing,
+because a splice computed from string indices can silently eat content that a
+whole-document write cannot.
+
+**A page may be build output.** A repository script generating pages into
+several sessions' storage — so a team gets one identical interface from a
+checkout rather than from three agents independently writing HTML — is
+legitimate. The rule that does not bend: every page still has one owning
+session, and that session's agent builds the page the first time, whether or
+not a script takes over afterwards. A page with no agent behind it is a page
+nobody can be asked to change.`;
 
 const home = () => `## The home page
 
@@ -316,7 +379,36 @@ const accessibility = () => `## Before you save
 - Every action reachable by keyboard; nothing pointer-only.
 - Inline SVG for diagrams and charts, with var(--accent) inside it; a zero
   gets a visible stub or the eye reads missing data.
-- grep -o '#[0-9a-fA-F]\\{3,8\\}' ${ENTRY_FILE} inside your <style> should be empty.`;
+- grep -o '#[0-9a-fA-F]\\{3,8\\}' ${ENTRY_FILE} inside your <style> should be empty.
+- Read it once over the reader's real origin, not only loopback. A local bb
+  requires no credential and a remote one does, so anything the page loads for
+  itself can work for you and fail for them. Authentication is the one axis
+  where behaviour genuinely differs between your machine and theirs.`;
+
+const upgrading = () => `## If your page predates 1.1
+
+Three things to fix in a page written against 1.0.x. Each is a one-line edit
+and none of them announces itself.
+
+1. **Add \`[hidden] { display: none !important; }\`** to your <style>. A class
+   rule that sets display outranks the attribute, so an element you wrote
+   \`hidden\` renders as an empty bar. New pages carry the fix; yours has its
+   own copy of the stylesheet and will not get it.
+2. **Delete the seed's old authoring comment** if it is still there. It spelled
+   tags out literally, so every string operation you run on your own file sees
+   a <main> and a <style> that are not elements, and the obvious splice starts
+   inside the comment.
+3. **Move inlined data back out.** 1.0 told you to inline anything the page
+   could not do without, because a file beside the page failed on the reader's
+   origin. That is fixed: reference it relatively and it works everywhere. Your
+   entry document gets small again, which makes it cheap to rewrite.
+
+Then check \`bb plugin logs thread-pages\` once, and read the page over the
+reader's real origin rather than loopback.
+
+Full notes, including what still is not possible:
+\`docs/FOR-PAGE-AUTHORS-1.1.md\` in the plugin, and \`docs/UPGRADING.md\` for
+the 0.3.x method names.`;
 
 const limits = () => `## Limits
 
@@ -351,5 +443,8 @@ const limitations = (site: SiteStrategy) => `## Known limitations
   generic message; the cause is in the plugin log (\`bb plugin logs thread-pages\`).
 - Embedding another page or site in an <iframe> is blocked (frame-src 'none').
 - \`voice.captureAndTranscribe\` is not implemented: unknown_method.${
-  site.name === "core-storage" ? `\n- fetch() of your own files from page script is refused on this host (see Files you show the reader).` : ""
+  site.name === "core-storage"
+    ? `\n- fetch() of your own files from page script is refused on this host (see Files you show the reader).` +
+      `\n- Your own files are carried inside the entry document rather than served as files, because this host cannot authorise a sandboxed document's own requests. That is why they count against the document's size limits.`
+    : ""
 }`;

package/src/agent/seed/seed.ts

@@ -24,27 +24,31 @@ export const DEFAULT_PAGE_SEED = `<!doctype html>
   </header>
 
   <!--
-    Write inside <main>. 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.
+    Everything below is yours: this whole file, including the stylesheet in
+    the head. Rewrite it however the task needs. Two things the file cannot
+    tell you, because they are behaviour rather than markup:
 
-    Every <form> answers this session automatically unless it carries
-    data-thread-page-manual. Blank answers are valid. A <form method="dialog">
-    you only meant as a local confirm still sends a message unless it opts out.
+    1. Every form element in this document is captured and delivered to this
+       session as a message. That includes a dialog form you only meant as a
+       local confirm; put data-thread-page-manual on any form that is not
+       meant to answer. Nothing is required and blank is a real answer.
+    2. window.prompt, alert, confirm and window.open do nothing here — the
+       sandbox silences them. Build the input into the page instead.
 
-    Files you put beside this index.html are served relatively: <img
-    src="chart.png">, <link href="page.css">, <script src="app.js">, nested
-    paths included. Ordinary <a href="https://…"> links work.
+    The look is three attributes on the html element. data-theme: paper,
+    terminal, atrium, volume or bloom. data-mode: system, light or dark.
+    data-atmos: on or off.
 
-    data-theme: paper | terminal | atrium | volume | bloom.
-    data-mode: system | light | dark. data-atmos: on | off.
-    Extra CSS goes in one more <style>, everything inside @scope (main),
-    colour and shape from var(--token) only.
+    If this page should stay put — a dashboard, a console, a page nobody
+    should have to rewrite — delete the reply form below and let its buttons
+    start fresh sessions instead. See the guide.
 
-    Never use window.prompt, alert, confirm or window.open: the sandbox
-    silences them. For anything more — charts, files, live session state,
-    starting sessions, links — run: bb thread-page guide
+    Everything else — files beside this one, charts, live session state,
+    starting sessions, links, limits — is in: bb thread-page guide
+
+    This comment deliberately names no HTML tags. An earlier version spelled
+    them out, and every agent that edited its page by string surgery found
+    tags here that were not in the document. Keep it that way.
   -->
   <main>
     <p>Replace this with what changed and what you need from the reader.</p>

package/src/agent/seed/theme-css.ts

@@ -37,6 +37,11 @@ export const THEME_CSS = String.raw`
 
   *, *::before, *::after { box-sizing: border-box; }
 
+  /* A class rule that sets display outranks the user-agent rule for the
+     hidden attribute, so a page that styles .banner with display:flex would
+     render a hidden banner as an empty bar. This keeps hidden meaning hidden. */
+  [hidden] { display: none !important; }
+
   html { -webkit-text-size-adjust: 100%; }
 
   body {

package/src/domain/capabilities/protocol.ts

@@ -4,6 +4,7 @@ import { isJsonObject, validateJson, type JsonValue } from "../json/strict-json.
 import { LIMITS } from "../limits.ts";
 import type { CapabilityRegistry } from "./registry.ts";
 import type { AnyCapabilitySpec } from "./contract.ts";
+import { unknownMethodMessage } from "./renamed.ts";
 
 /**
  * The bridge protocol: what a page sends over the port and what it gets back.
@@ -89,7 +90,7 @@ export interface ResolvedInvocation<Params = unknown> {
 export function resolveInvocation(request: BridgeRequest, registry: CapabilityRegistry, currentRevision: string): ResolvedInvocation {
   if (request.pageRevision !== currentRevision) throw new PageError("stale_page", "This page changed; reload it before responding.");
   const spec = registry.get(request.method);
-  if (!spec || !spec.implemented) throw new PageError("unknown_method", `Unknown capability: ${request.method}`);
+  if (!spec || !spec.implemented) throw new PageError("unknown_method", unknownMethodMessage(request.method));
   const params = spec.validateParams(request.params);
   if (!params.ok) {
     const first = params.issues[0];

package/src/domain/capabilities/renamed.ts

@@ -0,0 +1,34 @@
+/**
+ * Names the 0.3.x API answered for, when a page still calls it. spec R5.38–R5.41
+ *
+ * 1.0.0 renamed the whole page-facing surface with no migration path, and the
+ * only signal a page got back was `unknown_method: threads.spawn` — which
+ * reads as "this host cannot do that" rather than "this is called something
+ * else now". Naming the replacement turns a debugging session into a one-line
+ * fix. There are no aliases and there will be none: the old name still fails.
+ */
+export const RENAMED_METHODS: Readonly<Record<string, string>> = Object.freeze({
+  "threads.spawn": "sessions.start",
+  "threads.snapshot": "sessions.snapshot",
+  "threads.send": "sessions.send",
+  "threads.stop": "sessions.stop",
+  "threads.archive": "sessions.archive",
+  "threads.activity": "session.activity",
+  "threads.reply": "session.reply",
+  "threads.openPage": "pages.open",
+  "threads.openBb": "sessions.openHost",
+  "thread.get": "context.get",
+  "thread.reply": "session.reply",
+  "thread.activity": "session.activity",
+  "page.storage.get": "storage.get",
+  "page.storage.set": "storage.set",
+  "navigation.open": "navigation.openExternal",
+});
+
+/** The `unknown_method` message for a method, naming its replacement when there is one. */
+export function unknownMethodMessage(method: string): string {
+  const replacement = RENAMED_METHODS[method];
+  return replacement
+    ? `Unknown capability: ${method} (renamed to ${replacement} in 1.0; there is no alias)`
+    : `Unknown capability: ${method}`;
+}