npm - @unifedev/thread-pages - Versions diffs - 0.3.2 → 1.0.3 - Mend

@unifedev/thread-pages 0.3.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/README.md +77 -129
package/dist/server.js +11426 -11802
package/dist/server.meta.json +2 -2
package/package.json +25 -18
package/server.ts +3 -2175
package/src/agent/cli.ts +193 -0
package/src/agent/guide.ts +355 -0
package/src/agent/instruction.ts +59 -0
package/src/agent/seed/seed.ts +69 -0
package/{theme.ts → src/agent/seed/theme-css.ts} +4 -11
package/src/agent/starter-hub.ts +217 -0
package/src/bb/activity.ts +59 -0
package/src/bb/bb-host.ts +280 -0
package/src/bb/public-origin.ts +45 -0
package/src/config/settings.ts +82 -0
package/src/domain/capabilities/contract.ts +48 -0
package/src/domain/capabilities/index.ts +10 -0
package/src/domain/capabilities/protocol.ts +112 -0
package/src/domain/capabilities/registry.ts +48 -0
package/src/domain/capabilities/schema.ts +198 -0
package/src/domain/capabilities/specs.ts +479 -0
package/src/domain/eligibility.ts +43 -0
package/src/domain/errors.ts +116 -0
package/src/domain/html/document.ts +109 -0
package/src/domain/html/escape.ts +16 -0
package/src/domain/ids.ts +37 -0
package/src/domain/json/canonical.ts +19 -0
package/src/domain/json/strict-json.ts +139 -0
package/src/domain/limits.ts +88 -0
package/src/domain/rate-limit.ts +64 -0
package/src/domain/revision.ts +27 -0
package/src/domain/submissions/idempotency.ts +59 -0
package/src/domain/submissions/message.ts +42 -0
package/src/domain/submissions/parse.ts +105 -0
package/src/domain/tokens/action-token.ts +52 -0
package/src/domain/tokens/confirmation.ts +99 -0
package/src/domain/tokens/mac.ts +50 -0
package/src/generated/kernel-runtime.ts +3 -0
package/src/generated/shell-runtime.ts +3 -0
package/src/host/contract.ts +65 -0
package/src/host/types.ts +89 -0
package/src/pages/layout.ts +65 -0
package/src/pages/page-store.ts +136 -0
package/src/pages/site.ts +36 -0
package/src/plugin.ts +71 -0
package/src/runtime/kernel/anchors.ts +45 -0
package/src/runtime/kernel/api.ts +15 -0
package/src/runtime/kernel/bridge-client.ts +148 -0
package/src/runtime/kernel/dirty.ts +51 -0
package/src/runtime/kernel/forms.ts +114 -0
package/src/runtime/kernel/install.ts +156 -0
package/src/runtime/kernel/labels.ts +98 -0
package/src/runtime/kernel/main.ts +6 -0
package/src/runtime/kernel/readonly.ts +75 -0
package/src/runtime/shared/protocol.ts +125 -0
package/src/runtime/shell/confirm.ts +70 -0
package/src/runtime/shell/install.ts +79 -0
package/src/runtime/shell/main.ts +12 -0
package/src/runtime/shell/navigate.ts +64 -0
package/src/runtime/shell/poll.ts +125 -0
package/src/runtime/shell/relay.ts +185 -0
package/src/serving/action-request.ts +32 -0
package/src/serving/bridge/dispatcher.ts +112 -0
package/src/serving/bridge/handler.ts +37 -0
package/src/serving/bridge/handlers/index.ts +26 -0
package/src/serving/bridge/handlers/navigation.ts +43 -0
package/src/serving/bridge/handlers/reads.ts +186 -0
package/src/serving/bridge/handlers/writes.ts +175 -0
package/src/serving/bridge/selection-store.ts +58 -0
package/src/serving/bridge-route.ts +23 -0
package/src/serving/context.ts +34 -0
package/src/serving/document-route.ts +37 -0
package/src/serving/home-route.ts +23 -0
package/src/serving/responses.ts +81 -0
package/src/serving/routes.ts +26 -0
package/src/serving/session-access.ts +22 -0
package/src/serving/shell-html.ts +77 -0
package/src/serving/shell-route.ts +51 -0
package/src/serving/signing-key.ts +25 -0
package/src/serving/submit-route.ts +47 -0
package/src/serving/upload-route.ts +46 -0
package/tsconfig.json +10 -6
package/ARCHITECTURE.md +0 -230
package/PLUGIN_OVERVIEW.md +0 -83
package/authoring.ts +0 -368
package/bridge.ts +0 -1721
package/docs/MODEL.md +0 -211
package/docs/ROADMAP.md +0 -96
package/home.ts +0 -419
package/page.ts +0 -782

package/docs/MODEL.md DELETED Viewed

@@ -1,211 +0,0 @@
-# How Thread Pages works
-This answers four questions: what instructions exist and where they live, where
-the HTML lives, where the template lives, and how you reach a page from a phone.
-## The one-paragraph version
-Each bb thread gets one HTML file in its own thread storage. The agent edits that
-file directly; saving it *is* publishing. A plugin route serves the file inside a
-sandboxed iframe on the bb origin you are already logged into, so the same URL
-works on your laptop and your phone with no extra port, tunnel, or password.
-Forms in the page post back to the thread as your next message.
-## Every instruction, and where it lives
-There are three, and only the first is loaded into every session.
-| # | What | Where it is stored | Loaded when |
-| --- | --- | --- | --- |
-| 1 | **The contract** — the page is the conversation, how to ask well, what belongs on a page | `authoring.ts` → `DEFAULT_AGENT_INSTRUCTION`, overridable in the `agentInstructionText` setting (stored in bb's settings DB) | Injected into every eligible root thread, if `agentInstructions` is on |
-| 2 | **The seed comment** — the three class names, the theme attributes, the escape-hatch rule | Inside each page's own HTML, put there by the seed | Read by the agent when it opens the file |
-| 3 | **The authoring guide** — charts, branching, swipe decks, files, assets, the bridge | `authoring.ts` → `AUTHORING_GUIDE`, printed by `bb thread-page guide` | Only when an agent runs that command |
-The split is deliberate. #1 is paid for by every session, so it holds only what
-changes behaviour. #2 costs nothing because the agent is already reading the
-file. #3 is unbounded and free to the sessions that never need it.
-There is **no** skill, no agent tool, and no `CLAUDE.md` entry. Check what is
-live with:
-```sh
-bb plugin config thread-pages          # all three settings and their values
-bb thread-page guide                   # print #3
-bb instructions get                    # bb-wide instructions (empty; not us)
-```
-To change the contract for all future sessions, edit `agentInstructionText`. To
-change what new pages start from, edit `pageSeedHtml`. Neither touches a page
-that already exists.
-## Where the HTML lives
-```
-~/.bb/thread-storage/<threadId>/
-  thread-page.html            the page — one file, ~28 KB seeded
-  thread-page-assets/         optional: images, css, fonts, json you show
-  thread-page-uploads/        files the user attached, named by the plugin
-```
-That is the whole storage model. The page is a normal file: read it, diff it,
-edit it with any tool. There is no database of pages, no revision history, and
-no separate publish step.
-The plugin also keeps two small things in bb's existing `plugin_kv` table:
-- `page-signing-key:v2` — 32 bytes, so open browser sessions survive a reload;
-- `cache:<threadId>` — a best-effort last-good copy, so a page still opens
-  read-only when its source machine is offline.
-No plugin-owned SQLite database, no background service.
-## Where the template lives
-There is no template file on disk. The seed is a string in the plugin:
-- `theme.ts` → `THEME_CSS` — the design system: five worlds, one resolver.
-- `authoring.ts` → `DEFAULT_PAGE_SEED` — the document that wraps it.
-`bb thread-page init` writes that seed **only when the file does not exist**. It
-never overwrites. The consequence worth understanding: **each page carries its
-own copy of the stylesheet.** The agent can therefore change any rule for one
-page, and a plugin update can never restyle a page you have already read. The
-cost is that improving the design system only affects pages created afterwards.
-Five worlds are available; pick one with `data-theme` on `<html>`:
-`paper`, `terminal`, `atrium`, `volume` (default), `bloom`. Also
-`data-mode` (`system`/`light`/`dark`) and `data-atmos` (`on`/`off`).
-## How a turn flows
-1. Agent runs `bb thread-page init` → path, link, and `NEW`/`EXISTING`/`SKIP`.
-2. Agent edits `thread-page.html`.
-3. Your open tab notices the changed ETag and reloads itself.
-4. You answer a form. The page posts to `/submit`.
-5. The plugin turns the answers into a message and sends it to the thread.
-6. It arrives as the agent's next turn.
-`SKIP` means the thread is a helper — a child, a fork, or a hidden worker. Only
-threads you started get a page, because those are the ones you talk to.
-## Reaching it from your phone
-**Nothing to expose.** Thread Pages has no server of its own — its routes are
-part of the bb server:
-```
-https://<your-handle>.getbb.app/api/v1/plugins/thread-pages/http/page?threadId=<id>
-```
-Whatever origin reaches bb reaches your pages, behind the **same getbb.app
-login**, with no second port and no separate share. Verified: an unauthenticated
-request to that URL returns the getbb.app sign-in wall and leaks no page content.
-`bb thread-page init` now prints that absolute URL when this bb is connected, so
-the link an agent hands you is already the one you can open on a phone. When bb
-is local-only it prints a relative path instead, which resolves against whatever
-you are browsing from.
-If you are not paired: `bb connect` once, from the dashboard. After that every
-page is remote automatically — there is no per-page or per-port step, and
-nothing for a new user to configure.
-For a private alternative, point Tailscale Serve at the whole bb loopback origin.
-Never Funnel it and never wildcard-bind bb.
-## The security model
-The page is written by an agent, so it is treated as untrusted code.
-**Inside the iframe** (`sandbox="allow-scripts allow-forms"`, opaque origin):
-your page's HTML, CSS and JavaScript. It has no bb cookie, no mutation token, no
-parent DOM, no `localStorage`, no raw bb API, no CLI, no arbitrary file access,
-and CSP blocks ordinary `fetch` and subresources.
-**Outside the iframe**, plugin-authored code on the bb origin holds the action
-token, performs same-origin calls, and renders confirmations.
-**The bridge.** `window.threadPage.invoke(method, params)` reaches a fixed list
-of named capabilities, each with its own validator, size limit, and effect class.
-There is no generic "call bb" escape.
-Anything that mutates state outside this 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 in a dialog, and the server
-re-verifies the signature before acting. The challenge is bound to one request
-id, method, parameter fingerprint, page revision and thread, and expires in two
-minutes — so it cannot be forged, replayed, or reused to approve different
-parameters.
-All capabilities are enabled except voice: `context.get`, `thread.activity`,
-`thread.reply`, `threads.snapshot`, `threads.continue`, `threads.spawn`,
-`threads.archive`, `threads.stop`, `threads.openPage`, `threads.openBb`,
-`navigation.openExternal`, `projects.list`, `projects.browse`,
-`projects.create`, `providers.list`, `storage.get`, `storage.set`.
-`voice.captureAndTranscribe` has a contract but no handler, by your decision.
-`projects.browse` opens the host's native folder picker and returns an **opaque,
-single-use token** plus a display string — never a filesystem path the page could
-reuse or leak. `projects.create` redeems that token.
-**The honest limitation.** 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.
-## The home page, and the Sessions link
-One thread's page is designated home:
-```sh
-bb thread-page home            # in the thread that should own it
-bb thread-page home --clear    # remove the link everywhere
-bb plugin config thread-pages  # shows homeThreadId
-```
-`/home` then redirects there, and **every other page shows a "← Sessions" link
-back to it automatically**. That link is chrome in the trusted shell, so no page
-authors it and no agent spends instruction budget on it. Home does not link to
-itself.
-`bb thread-page home` writes a real session hub when that thread has no page
-yet, and never touches one that exists. The default groups sessions by project,
-gives each group its own look, and offers filter, open, prompt, spawn, stop and
-archive per row.
-**Groups are not projects.** A group is a label, a look, and a *set* of project
-ids, stored in the page's own scoped storage under `home.groups`. One group per
-project is only the default. Ask the owning agent for "Work" and "Side projects",
-or to put one project in two groups, and it edits the page — no schema, no plugin
-change. Each group carries `data-world`, which re-resolves the design tokens for
-that subtree, so a project genuinely looks different without a second document.
-Home is an ordinary Thread Page: it calls `threads.snapshot`, `projects.list` and
-`providers.list` and renders what it likes. You can ask the owning agent to
-redesign it like any other page.
-## The working indicator
-While the owning thread is mid-turn, the page header shows a pulsing dot and
-wording you control:
-```sh
-bb plugin config thread-pages set workingLabel "Thinking…"
-bb plugin config thread-pages set workingLabel ""   # hides it
-```
-The point is the sentence: what you are reading is the last *saved* version, and
-another one is coming. It costs nothing to run — the state rides on the
-`x-thread-page-activity` header of the revision poll the shell already makes
-every 10 seconds, so there is no extra request, nothing for a page to implement,
-and nothing in any agent's instructions.
-## Files in this repository
-| File | Role |
-| --- | --- |
-| `server.ts` | Settings, CLI, HTTP routes, capability handlers, caching |
-| `page.ts` | Token signing, HTML parsing/injection, both browser runtimes, form and upload serialization |
-| `bridge.ts` | The capability contract and validators. No SDK, DOM, fetch, or filesystem imports |
-| `authoring.ts` | The instruction, the seed, the guide |
-| `home.ts` | The default home page: markup, styles, and script |
-| `theme.ts` | The design system |

package/docs/ROADMAP.md DELETED Viewed

@@ -1,96 +0,0 @@
-# Roadmap
-Version 0.3.0 · September 2026
-## Done
-Everything needed for daily use is implemented and verified in a browser.
-**The page.** Complete HTML/CSS/JS mini-apps in an opaque sandbox, parsed with
-parse5 and kernel-injected before authored scripts. Five-world design system
-carried in each page. Automatic semantic forms with independent per-form state,
-blank-safe answers, manual opt-out, and update protection. File attachments in a
-confined upload directory. A confined asset directory with a matching CSP.
-**The chrome.** Title bar, Sessions link, working indicator — all outside the
-sandbox, none of it costing an agent anything.
-**The home page.** `bb thread-page home` designates any thread's page and writes
-a session hub grouped by project, with a look per group and grouping stored in
-the page rather than hard-wired.
-**The bridge.** Seventeen of eighteen capabilities, with trusted confirmation for
-every cross-thread, destructive, device and external-navigation effect.
-**Access.** Remote by default through the existing bb origin, with no port share.
-## Left
-### Before wide release
-**A hostile-page corpus.** The only item I would call blocking for a public
-audience. The confirmation flow is tested against forgery, replay and
-parameter-swapping, but no test yet plays an attacker: trying to read the bb
-cookie, reach `parent`/`top`, forge another thread's action, or reach the network.
-The design says these are impossible; a test should prove it, and should also
-demonstrate the self-frame navigation limitation rather than leave it as prose.
-### Capabilities
-**`voice.captureAndTranscribe`** has a contract and validators but no handler.
-Recording happens in trusted chrome and transcription goes through bb's own voice
-service. Deferred as unused; the contract is there when it is wanted.
-### Worth doing
-- **Asset and upload cleanup.** Neither directory is ever pruned. A page that
-  receives many attachments grows without bound.
-- **`threads.snapshot` paging.** `nextCursor` is always `null`; the limit is 200.
-  Fine for now, wrong eventually.
-- **Design-system updates for existing pages.** Each page carries its own
-  stylesheet, which is what makes per-page restyling safe and plugin updates
-  harmless. The cost is that improvements only reach new pages. If that becomes
-  annoying, the answer is a command that re-splices the current stylesheet into a
-  page on request — not injection at render time, which would take the property
-  away.
-- **A second reference page.** The home page is the only worked example. One
-  more — a diagram or a multi-screen flow — would show the range better than the
-  guide's prose.
-## Non-goals
-- **A component library or theme picker.** The plugin hosts pages; it does not
-  design them. Five worlds exist so a page has a coherent starting point, not so
-  it has a menu.
-- **A fixed dashboard.** Home is an ordinary page. Anything the plugin renders
-  itself is one thing an agent cannot adapt to the task.
-- **General network access from a page.** When a task needs a remote service it
-  should get a named, reviewed capability, not a fetch proxy.
-- **Strict no-exfiltration.** Would require forbidding authored JavaScript, which
-  is the product. See ARCHITECTURE.md.
-## Release
-1. `npm ci && bb plugin types --check . && npm test && npm run typecheck && npm run build`
-2. Tag `vX.Y.Z` and push. bb records the tag with the commit it pointed at and
-   **refuses a tag that later moves** — so publish a fix as a new version rather
-   than retagging. If a tag has to move, everyone on it must remove and reinstall.
-3. Verify `bb plugin install git:<url>@^X.Y.0` on a clean machine.
-4. Publish to npm (see below).
-5. Submit to the marketplace with the `submit-a-plugin` skill, which reads the
-   current contract from `github.com/get-bb/marketplace` rather than assuming one.
-### Publishing to npm
-The scope has to exist and you have to be logged in as a member:
-```sh
-npm login                       # as the account that owns @unifedev
-npm publish --access public
-```
-`dist/` is committed and also packed, so neither a git nor an npm install needs a
-build step. `package-lock.json` is committed for the git path — npm strips it from
-tarballs by design, which is fine because npm resolves `parse5` itself.
-Verify afterwards with `bb plugin install npm:@unifedev/thread-pages@^0.3.0`.