@unifedev/thread-pages 0.3.2 → 1.1.0

package/README.md

@@ -1,153 +1,101 @@
 # Thread Pages
 
-`@unifedev/thread-pages` — part of [Unife](https://github.com/unifedev), a
-unified interface for everything. Thread Pages is the unified interface for
-working with AI agents; this plugin implements it for [bb](https://getbb.app).
-
-**Every agent session gets one web page, written for that task, that you can read
-and answer from on any device.**
-
-An agent 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
-page to say it on — and gives you a form to answer from, which arrives as the
-agent's next message.
-
-The page is a complete HTML document the agent writes for the task at hand. If it
-needs a chart, it writes a chart. If it needs a multi-screen flow, a diagram you
-click, or three separate forms, it writes that. The plugin supplies the secure
-host, never the design.
-
-## Install
-
-```sh
-bb plugin install git:https://github.com/unifedev/bb-thread-pages.git
-```
-
-Then turn on **Agent initialization hint** in the plugin's settings, so new
-sessions use their page automatically:
+A bb plugin: every agent session gets one page it writes itself, served as a
+site the reader can read and answer from on any device.
 
 ```sh
-bb plugin config thread-pages set agentInstructions true
+bb plugin install git:https://github.com/unifedev/bb-thread-pages.git@^1.0.0
 ```
 
-That is the whole setup. If this bb is paired with `bb connect`, every page is
-reachable from your phone immediately — there is no port to expose and nothing
-per-page to configure.
+Then two things:
 
-## Using it
-
-The agent's whole workflow is one command:
-
-```sh
-bb thread-page init      # create or locate this thread's page; prints the link
-```
-
-Two others exist:
-
-```sh
-bb thread-page guide     # authoring reference, only when a page needs more
-bb thread-page home      # make this thread's page the home page
-```
+1. Turn on **Agent instructions** in the plugin's settings (or
+   `bb plugin config thread-pages set agentInstructions true`). Every new
+   session then writes a page for its task and answers you from it.
+2. Start a session anywhere and say *"Set up my Thread Pages home page."* The
+   agent runs `bb thread-page home` there, builds a hub of your sessions from
+   the guide's starter, and replies with the link every page links back to.
+   To change the hub later, ask that session.
 
-`bb thread-page home` writes a session hub grouped by project, with a filter,
-live status, and per-row open, prompt, stop and archive. 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.
+## This repository is the implementation only
 
-## Documentation
+The product is specified in a separate repository, **`unife-bb-plugin`**
+(Syns): `spec/` is the buildable specification, `docs/DECISIONS.md` the
+reasoning, `rewrite/` the architecture of this implementation and the
+decisions taken while building it, `verify/` the fixtures and scenarios that
+verify it. Nothing here decides what the product should be.
 
-- [docs/MODEL.md](./docs/MODEL.md) — **start here**: instructions, storage,
-  templates, and remote access
-- [ARCHITECTURE.md](./ARCHITECTURE.md) — the design and its reasoning
-- [docs/ROADMAP.md](./docs/ROADMAP.md) — what is left
-- [PLUGIN_OVERVIEW.md](./PLUGIN_OVERVIEW.md) — marketplace description
+## What an agent gets
 
-## What a page can do
+- `bb thread-page init` — creates `index.html` in the session's storage
+  directory from the seed (never overwrites), prints the path and the link.
+- `bb thread-page guide` — the authoring guide: forms, files, uploads,
+  `window.threadPage`, every capability, limits, and what the sandbox silences.
+- `bb thread-page home [--clear]` — makes this session's page the home page.
+- `bb thread-page status` — settings, the exact instruction a new session
+  receives, and this session's page.
 
-Authored freely inside the sandbox:
+The page root is the session's storage directory (`$BB_THREAD_STORAGE`):
+`index.html` is the page, any file beside it is served relatively (nested
+paths included), `uploads/` holds what the reader attaches.
 
-- any HTML, CSS and JavaScript, 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, so a page can show what the agent is doing now;
-- small state that survives a reload.
-
-Through named capabilities, with confirmation where it matters:
-
-- list sessions, projects and providers;
-- message, start, stop or archive a session;
-- create a project through the host's native folder picker;
-- open another page, a bb thread, or an external link.
-
-The plugin also supplies three pieces of chrome outside the page: the title bar,
-the Sessions link, and a working indicator while the thread is mid-turn. Its
-wording is a setting; blank hides it.
-
-## Where things live
+## Layout
 
 ```
-~/.bb/thread-storage/<threadId>/
-  thread-page.html            the page
-  thread-page-assets/          what it shows you
-  thread-page-uploads/         what you attached
+server.ts                 entry: hands bb to the composition root
+src/plugin.ts             composition root
+src/domain/               host-free: limits, errors, tokens, capabilities, submissions, HTML injection
+src/host/                 the host contract (spec 08) and its projected types
+src/bb/                   the bb adapter — the only package that imports the SDK's runtime shapes
+src/pages/                page layout, the page store (revision, offline copy), the site strategy
+src/serving/              routes, the bridge dispatcher and capability handlers
+src/agent/                CLI, standing instruction, seed (with the design system), generated guide
+src/config/               the five settings
+src/runtime/              browser code: the kernel (inside the sandboxed page) and the shell (trusted chrome)
+src/generated/            the bundled runtimes as string modules (committed; npm run build:runtime)
+test/                     vitest: domain, runtime (jsdom), serving (fake host), bb adapter, guide
+scripts/build-runtime.mjs esbuild step for src/runtime
 ```
 
-The page is a normal file — read it, diff it, keep it. There is no database of
-pages and no separate publish step. Settings hold the instruction text and the
-new-page seed, so you can change what future pages start from without touching
-one that exists.
-
-## Access
-
-Thread Pages needs no port share. Its routes are part of the bb server, so the
-origin that reaches bb reaches your pages, behind the same owner login:
-
-```text
-https://<handle>.getbb.app/api/v1/plugins/thread-pages/http/page?threadId=<id>
-```
-
-`bb thread-page init` prints that absolute URL whenever this bb is connected, and
-a relative path when it is local-only. For private access instead, point
-Tailscale Serve at the whole bb loopback origin — never Funnel it, and never
-wildcard-bind bb.
-
-## Security
-
-The page is generated code, so it is treated as untrusted. It runs in an
-opaque-origin sandbox with no bb cookie, no mutation token, no parent DOM, no
-`localStorage`, no raw bb API, no CLI, no filesystem access, and no ordinary
-network access. Everything it can ask bb to do goes through one validated,
-named capability at a time.
-
-Anything reaching outside the current thread requires a confirmation the page
-cannot fake: the server answers once with a signed challenge carrying **its own**
-summary, the trusted shell shows that summary, and the server re-verifies the
-signature before acting. The challenge is bound to one request, method, parameter
-fingerprint, page revision and thread, and expires in two minutes.
-
-One limitation stated 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 is code you are choosing to run.
-
-## Development
+## Working on it
 
 ```sh
 npm ci
-bb plugin types --check .
-npm test
-npm run typecheck
-npm run build
-bb plugin reload thread-pages
+npm run check          # build runtimes, typecheck, test
+npm run build          # runtimes + bb plugin build → dist/
+bb plugin install .    # try it locally
 ```
 
-93 tests cover the capability contract, token scope and tampering, HTML parsing
-against adversarial documents, sandbox and CSP invariants, forms, uploads,
-confined assets, the home page, and the confirmation flow against forgery,
-replay and parameter-swapping.
-
-## Licence
+`src/generated/*.ts` must be rebuilt (`npm run build:runtime`) after any
+change under `src/runtime/`; a test fails when they are stale.
+
+Confirmed capabilities render a dialog in the shell; its buttons, not the
+dialog's `close` event, settle the result, so they can be driven headlessly.
+
+## Serving on bb 0.42.1
+
+bb's plugin router matches paths exactly, so the plugin cannot serve
+`/page/<id>/*` itself. Files beside `index.html` are served by bb core's
+thread-storage route through one same-origin `<base>` injected into the
+document (`SiteStrategy` "core-storage"). One consequence: page script cannot
+`fetch()` its own files (bb refuses the sandbox's `Origin: null`); subresources
+load normally. The "plugin-prefix" strategy in `src/pages/site.ts` removes the
+limitation once bb offers prefix routes.
+
+## Release
+
+A release is a git tag **and** an npm publish, always both: `bb plugin install
+git:…@^X.Y.0` resolves tags, `bb plugin install npm:@unifedev/thread-pages`
+resolves npm, and the two must name the same code.
+
+1. `npm ci && npm run check && npm run build`
+2. Bump `version` in `package.json`, add the `CHANGELOG.md` entry, commit
+   `dist/` and `src/generated/` with it.
+3. `git tag -a vX.Y.Z -m "Thread Pages X.Y.Z" && git push origin main --tags`.
+   bb refuses a tag that later moves: publish a fix as a new version.
+4. `npm publish --access public` (as a member of `@unifedev`). Verify with
+   `npm view @unifedev/thread-pages version`.
+5. On a clean machine: `bb plugin install npm:@unifedev/thread-pages@^X.Y.0`
+   or the `git:` form, then `bb thread-page status`.
 
 MIT