typebulb 0.13.2 → 0.13.4

package/README.md

@@ -252,7 +252,7 @@ To render a bulb live inline, wrap the **entire** bulb — frontmatter and all b
 
 The agent mirror turns that block into a live, sandboxed app, with a *breakout ↗* control that saves it as a `.bulb.md` in the `typebulbs/` folder — editable with hot reload, and sandboxed unless you trust it. Embedded bulbs are client-only — no `server.ts`, no `tb.fs`/`tb.ai`, no storage.
 
-**Fixing a broken embed?** Re-emit it under the *same* `name:` — the mirror folds the old version into a stub and keeps your fix as the live one. (A rename is treated as a new bulb.)
+**Iterating on an embed?** Re-emit under the *same* `name:` to refine it (a different `name:` starts a separate bulb) — the mirror keeps the latest version live and folds each earlier one into an expandable stub in place, so the transcript shows the bulb's evolution, not a stack of repeated renders. Same move fixes a broken embed.
 
 **A broken embed reads back.** Emit it and move on; embeds usually just work. If the user says one broke, the mirror has already forwarded its compile/runtime error to `typebulb logs claude`, name-tagged (`[embed <name>]`) — pull it from there and fix, instead of asking the user to copy-paste.
 
@@ -282,13 +282,64 @@ The host owns a bulb's **width**; you own its **height**.
 - **`tb.ai()` takes more than the basics** — the full shape is `tb.ai({ messages, system?, reasoning?, provider?, model?, webSearch? })` → `Promise<{ text }>` (non-streaming). `webSearch` defaults **on** in the CLI (you supply your own key); pass `webSearch: false` to turn it off.
 - **`tb.theme` drives the `html[data-theme]` attribute** — style off that selector (`html[data-theme="dark"] { … }`); don't read `tb.theme` to branch your rendering.
 - **`color-scheme` is set for you** — the host always applies `html[data-theme="dark"] { color-scheme: dark }` / `html[data-theme="light"] { color-scheme: light }` on top of your `styles.css`.
-- **Math renders live in the mirror** — write inline math as `$…$` and display math as `$$…$$` (the mirror renders KaTeX; a plain terminal chat doesn't, so reach for real math here). Prefer `$y = x^2$` over inline-code or a Unicode superscript (`y = x²`).
+- **Math (KaTeX) renders in your replies** — write inline `$…$` / display `$$…$$` (prefer `$y = x^2$` over inline-code or a Unicode `y = x²`). The mirror's KaTeX renders only in prose and doesn't reach inside a fenced block (bulb, mermaid, svg, code).
 - **`tb.json<T>(n)` is generic** — `tb.json<Album[]>(0)` returns typed parsed JSON; `tb.data(n)` returns the raw string.
 - **`tb.proxy()` is for same-origin Web Worker / WASM loads** — e.g. ffmpeg or tesseract: `tb.proxy("https://unpkg.com/...")` routes the CDN URL through the local server's origin.
 - **Prefer an `index.html` fragment** over a full HTML document — usually just the mount stub (`<div id="root"></div>`).
 - **`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.9"
+  }
+```
+
+Typebulb has a package resolver that will load and cache these packages from `esm.sh` when the bulb runs.
+
 ## License
 
 MIT