@unifedev/thread-pages 0.3.2 → 1.1.0

package/dist/server.meta.json

@@ -3,9 +3,9 @@
   "sdkVersion": "0.4.47",
   "artifactFormatVersion": 1,
   "pluginId": "thread-pages",
-  "pluginVersion": "0.3.2",
+  "pluginVersion": "1.1.0",
   "builtWith": {
-    "bbVersion": "0.40.0",
+    "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,7 +1,7 @@
 {
   "name": "@unifedev/thread-pages",
-  "version": "0.3.2",
-  "description": "Thread Pages for bb: every agent session gets one directly editable HTML page you can answer from, on any device.",
+  "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",
   "repository": {
@@ -23,42 +23,50 @@
   "type": "module",
   "private": false,
   "engines": {
-    "bb": ">=0.40",
-    "bbPluginSdk": ">=0.4.21"
+    "bb": ">=0.42",
+    "bbPluginSdk": ">=0.4.47"
   },
   "scripts": {
-    "build": "bb plugin build",
+    "build:runtime": "node scripts/build-runtime.mjs",
+    "build": "npm run build:runtime && bb plugin build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "check": "npm run build:runtime && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "parse5": "^8.0.1"
   },
   "devDependencies": {
-    "@get-bb/plugin-sdk": "0.4.47",
+    "@get-bb/plugin-sdk": "^0.4.47",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^22.10.0",
-    "bb-app": "0.40.0",
+    "bb-app": "0.42.1",
+    "better-sqlite3": "^12.0.0",
     "cron-parser": "^5.5.0",
+    "esbuild": "^0.28.2",
+    "hono": "^4.13.7",
+    "jsdom": "^30.0.1",
     "typescript": "^5.7.2",
-    "vitest": "^3.0.0"
+    "vitest": "^5.0.0",
+    "zod": "^4.3.6"
   },
   "bb": {
     "name": "Thread Pages",
-    "description": "Host one directly editable HTML mini-app for each thread.",
+    "description": "Host one directly editable HTML page per session, served as a site the reader can answer from.",
     "branding": {
       "icon": "FileText"
     },
     "server": "./server.ts",
     "skills": []
   },
-  "dependencies": {
-    "parse5": "^8.0.1"
-  },
   "files": [
-    "*.ts",
-    "!*.test.ts",
+    "server.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
     "dist/server.js",
     "dist/server.meta.json",
-    "docs/",
-    "ARCHITECTURE.md",
-    "PLUGIN_OVERVIEW.md",
+    "docs/*.md",
     "README.md",
     "tsconfig.json",
     "package-lock.json"