typebulb 0.13.3 → 0.13.5

package/README.md

@@ -3,7 +3,7 @@
 **Typebulb** runs apps in markdown files called **bulbs**. To run bulbs:
 
 * `npx typebulb`. When you want a quick local app or tool where the overhead of an entire npm project is overkill *(trivial for your LLM to convert to when you actually need to)*. Can be entirely client code, or both client and nodejs code that talk via a secure bridge.
-* `npx typebulb agent:claude`. When you want to view Claude Code conversations with embedded bulbs in the agent messages.
+* `npx typebulb agent`. When you want a browser view of your project's Claude Code sessions that renders embedded bulbs live — the **agent mirror**. Tell Claude to run this command.
 * **[typebulb.com](https://typebulb.com)**. When you want to share tools, visualizations, experiments etc. See [FAQ](https://typebulb.com/faq).
 
 The `typebulb` CLI enables the first two cases, by compiling and serving hot-reloadable bulbs locally.
@@ -27,7 +27,7 @@ A `.bulb.md` file bundles code, styles, data, and config in one file.
 - **AI calls** — `tb.ai()` for general-purpose AI (chatbots, agents, experiments). `tb.models()` lists available models. Set API keys in `.env` (see below). Requires `--trust`.
 - **Sandboxed by default** — A plain `npx typebulb my-app.bulb.md` runs with no filesystem or `server.ts` (like typebulb.com); `--trust` grants those for a run. Trust is **remembered**: `typebulb trust <file>` elevates a bulb once so later plain runs are trusted, `untrust` revokes it, and `--no-trust` forces sandboxed for a single run.
 - **Predict trust** — `typebulb predict <file>` reports the capability a bulb will likely need (fs / AI / `server.ts`) without running it, so you can decide on `--trust` up front rather than after a mid-run permission failure.
-- **Agent mirror** — `typebulb agent:claude` opens the agent mirror, a browser view over a Claude Code session that renders embedded bulbs, KaTeX, and mermaid live inline, plus runs/stops local bulbs (see [Claude](#claude)). `typebulb agent` (no target) is the first command an agent runs: it tells the agent how to show a bulb inline or build one locally. `typebulb skill` prints this whole README as an Agent Skill the agent can read and save.
+- **Agent mirror** — a browser view of your project's Claude Code sessions that renders embedded bulbs, KaTeX, and mermaid live inline, plus runs/stops local bulbs (see [Claude](#claude)). `typebulb agent:claude` opens it. `typebulb agent` (no target) is the first command an agent runs: it brings up the mirror without opening a browser, prints its link, and points at the authoring skill. `typebulb skill` prints this whole README as an Agent Skill the agent can read and save.
 
 ## Quick Start
 
@@ -117,9 +117,9 @@ npm install -g typebulb
 
 ```
 typebulb [file.bulb.md]        Run a bulb (defaults to .bulb.md in cwd)
-typebulb agent:claude          Open the agent mirror (a Claude Code session)
-typebulb agent                 Start here — how to show a bulb inline or build one locally
-                               (prints the mirror URL when one is up); always exits 0
+typebulb agent:claude          Open the agent mirror of your project's Claude Code sessions
+typebulb agent                 An agent's first command — brings up the agent mirror,
+                               prints its URL + the authoring-skill paths; always exits 0
 typebulb skill                 Print this README as an Agent Skill on stdout
 typebulb call <file> <fn> […]  Invoke one server.ts export headlessly: prints its return as JSON to stdout, logs/errors to stderr (needs --trust)
 typebulb check [file.bulb.md]  Type-check a bulb without running it
@@ -231,18 +231,18 @@ A local `.bulb.md` can be re-imported into typebulb.com. If it has a `**server.t
 
 The agent mirror currently supports Claude Code only. `npx typebulb agent:claude` gives the user a great scratchpad experience:
 
-* a view over the Claude Code session, where assistant messages containing bulbs render as sandboxed embedded bulbs inline in the conversation, alongside KaTeX math, mermaid diagrams and svg.
+* a view of the project's Claude Code sessions, where assistant messages containing bulbs render as sandboxed embedded bulbs inline in the conversation, alongside KaTeX math, mermaid diagrams and svg.
 * run and stop any bulb in their project.
 * promote any embedded bulb to a `.bulb.md` file in the `typebulbs/` folder.
 
-It opens a browser window outside VS Code, so start it yourself with `npx typebulb agent:claude --no-open` and give the user the localhost link to open in VS Code — don't wait for the user to run it.
+Start it yourself with `npx typebulb agent` — don't wait for the user — and end your reply with the localhost link it prints: it's the user's next click, and a link buried mid-message gets missed.
 
 To keep this skill on hand across sessions, run `npx typebulb skill` and copy its output into your skills folder (for Claude Code, `.claude/skills/typebulb/SKILL.md`) — only if the user asks.
 
 ### When Claude should output local vs embedded bulbs
 
 - **First, can it even embed?** A bulb needing `tb.ai`, `tb.fs`, or `server.ts` must be **local** — embeds are client-only, so those calls fail there. The choice below is only for client-only bulbs.
-- **Is anyone watching?** An embed only renders live when the agent mirror is open; with none it shows as raw text. `typebulb agent` tells you which case you're in. If no mirror is up and you want to show something inline, start it yourself — `npx typebulb agent:claude --no-open` — and share the link; don't make the user do it.
+- **Is anyone watching?** An embed only renders live when the agent mirror is open; with none it shows as raw text. `npx typebulb agent` starts the mirror if needed and prints its link — share it with the user; don't make the user start anything.
 - **Something to see right now, in the flow of the conversation** — a chart of some numbers, a quick simulation, an illustrative widget. → **embedded**: emit it in a `bulb` block so it renders live inline.
 - **A tool worth keeping** — something to reuse, run on its own, or refine over several turns. → **local**: write a `.bulb.md` file run with `npx typebulb`. An embedded block is throwaway and can't be edited in place, so it's the wrong fit for anything iterative.
 
@@ -289,6 +289,57 @@ The host owns a bulb's **width**; you own its **height**.
 - **`config.json` → `ts.jsxImportSource`** — the one supported `ts` option; defaults to `react`. Set it to use a different JSX runtime (e.g. `preact`).
 - **Never invent a connection string or API key** — a `server.ts` that needs a database or API reads it from `.env` (loaded from the directory you run in). Ask the user for the value; don't fabricate one or commit it.
 
+## Trust Model
+
+Typebulb has 3 trust tiers for a bulb, captured by 2 axes:
+
+|  | browser: **iframe** | browser: **top-level** |
+|---|:---:|:---:|
+| node access: **no** | **Embedded** | **Restricted** |
+| node access: **yes** | — | **Trusted** |
+
+The 3 Tiers from least to most powerful:
+
+* **Embedded**: These bulbs live in an iframe, and have the most restricted capability. They're created by Typebulb's Agent Mirror when rendering chat files. When bulb-markdown is detected in your agent's replies, they're rendered as embedded bulbs. 
+* **Restricted**: These bulbs are launched as localhost pages. Unlike embedded bulbs, they can also access storage, cookies, web workers, WebGPU etc.
+* **Trusted**: These bulbs are the most powerful and must be explicitly marked as trusted. Unlike restricted bulbs, they can access node via your `server.ts` or via privileged `tb.*` functions such as `tb.fs` or `tb.ai`. To grant, call typebulb with `--trust` for one run, or `typebulb trust <file>` to remember it — per file, for your user account, across all your projects. Revoke a remembered grant with `typebulb untrust <file>`; `--no-trust` forces a single sandboxed run without forgetting the grant.
+
+Here's a state transition diagram for the trust tiers:
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    [*] --> Embedded
+    [*] --> Restricted
+    Embedded --> Restricted: breakout
+    Restricted --> Trusted: trust
+    Trusted --> Restricted: untrust
+```
+**Capability Summary Table**:
+
+| Capability | Embedded | Restricted | Trusted |
+|---|:--:|:--:|:--:|
+| Run code in browser, access network including localhost | ✅ | ✅ | ✅ |
+| Use storage, cookies, background threads, and the GPU | 🚫 | ✅ | ✅ |
+| Read local files, run node code with `server.ts`, use your AI keys | 🚫 | 🚫 | ✅ |
+
+## Bulb Imports
+
+Imports in `code.tsx` can only use bare specifiers (otherwise the linter will error):
+
+```ts
+import React, { useState } from "react"
+```
+
+Which must be declared in the dependencies section:
+```json
+  "dependencies": {
+    "react": "^19.2.7"
+  }
+```
+
+Typebulb has a package resolver that will load and cache these packages from `esm.sh` when the bulb runs.
+
 ## License
 
 MIT