typebulb

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. When you want to view agent conversations with embedded bulbs in the agent messages, also providing a finder/launcher for your local bulbs. Supports Claude Code and Pi agent harnesses; tell your agent to run it.
• typebulb.com. When you want to share tools, visualizations, experiments etc. See FAQ.

The typebulb CLI enables the first two cases, by compiling and serving hot-reloadable bulbs locally.

A .bulb.md file bundles code, styles, data, and config in one file.

This document doubles as a skill: it is written so an LLM agent can read it and successfully write and run bulbs with the typebulb CLI.

Features

• Server-side code — Add a **server.ts** section; exported functions become callable from the browser via tb.server.<name>() (e.g., export async function query(...) → await tb.server.query(...)). An export async function* streams: consume it with for await (const chunk of tb.server.gen()). Requires --trust.
• CLI logging — tb.server.log(...) prints to the CLI's stdout
• Wake-on-event — typebulb wait <file|agent> blocks until the target server logs a new line, prints it, and exits. Run in the background, that exit is an agent's wake-up: a user action a bulb logs, or an embed's render outcome — no polling.
• Env files — .env / .env.local load from cwd, .env.local overriding .env (an exported shell var wins over both). --mode <name> adds .env.<name> to switch environments (local/staging/prod); a startup line reports which keys loaded from where.
• Server mode — --server runs only the **server.ts** section in Node, skipping the web server. Bulbs with only **server.ts** (no **code.tsx**) use this mode automatically.
• Type-check without running — typebulb check <file> runs tsc --noEmit against the bulb: non-zero exit with diagnostics on errors, a one-line all-clear on stderr on success.
• Filesystem access — tb.fs.read() (UTF-8 text), tb.fs.readBytes() (raw Uint8Array), and tb.fs.write() (text or bytes) for local files. Requires --trust.
• Hot reload — Recompiles on save and refreshes the browser (on by default; disable with --no-watch)
• Package resolution — Client dependencies are automatically resolved by generating import maps (same resolver as typebulb.com). Server dependencies are automatically installed via npm.
• Replace dependency — --replace <name>=<path> replaces a declared dependency with a local built package folder (browser-ready ESM, no external bare imports) instead of a CDN, for testing an unpublished build. Supplies both runtime bytes and types; applies to run and check. Under --watch the folder is watched and the browser reloads on rebuild (--no-watch freezes it). Dev-only; nothing is written to the bulb.
• Local caching — Resolver metadata and CDN package bytes are cached under ~/.typebulb/cache/, so repeat runs don't re-hit the network and warm runs work offline.
• tb.ai() — a bulb's own code calling AI providers at runtime (chatbots, agents, experiments). tb.models() lists available models. Set API keys in .env (see below). Requires --trust.
• Restricted 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 a Restricted 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 — a browser view of your coding agent's sessions, rendering embedded bulbs, KaTeX, and mermaid live inline, plus runs/stops local bulbs. On Pi it also carries a prompt panel, so the user can drive their pi sessions from the mirror directly. typebulb agent brings it up, auto-detecting your harness (Claude Code or Pi) — see Agent Harness Support. typebulb skill prints this whole README as an Agent Skill the agent can read and save.
• Proxying Claude — the agent mirror lets you proxy Claude with a model from OpenRouter. This will apply to your project only.

Usage

typebulb [file.bulb.md]        Run a bulb (defaults to .bulb.md in cwd)
typebulb agent                 An agent's first command — auto-detects the harness, starts the mirror detached, prints its URL, exits 0
typebulb agent:{claude|pi}     Open a named harness's mirror in the foreground — the explicit form, or to override auto-detect
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 send <file> [msg]     Push a message into a running bulb's page (its tb.onMessage handlers); the client-side twin of call, no --trust
typebulb check [file.bulb.md]  Type-check a bulb without running it
typebulb predict [file]        Report the capability a bulb probably needs, without running it
typebulb models                List AI models for tb.ai, filtered by your .env API keys
typebulb logs [file|agent]     Print a running bulb's (or `agent` mirror's) captured console (no arg: list running servers; -f follow, -n N tail, --run latest|N for one reload's output, --clear to empty it)
typebulb wait [file|agent]     Block until the target logs a matching line, print it, exit — an agent's wake-up
                               (run it backgrounded; --match <substr> filters; exit 2 = gave up)
typebulb stop [file|pid|agent] Stop a running bulb or mirror (no arg: list this project's running servers)
typebulb stop --bulbs          Stop this project's bulbs; the agent mirror keeps running
typebulb stop --agent          Stop this project's agent mirror; its bulbs keep running
typebulb stop --global         Stop every running bulb and mirror, all projects (housekeeping)
typebulb trust [file]          Remember a bulb as trusted (no arg: list trusted bulbs)
typebulb untrust <file>        Forget a bulb's trust (back to Restricted)
typebulb --no-watch <file>     Disable hot reload
typebulb --port 3333 <file>    Custom port
typebulb --no-open <file>      Don't auto-open browser
typebulb --mode <name> <file>  Also load .env.<name> on top of .env / .env.local
typebulb --trust <file>        Grant filesystem + AI + server.ts for this run (default: Restricted)
typebulb --no-trust <file>     Force Restricted even if the bulb is remembered-trusted
typebulb --server <file>       Run server.ts only, no web server (needs --trust)
typebulb --replace <name>=<path> Replace a dependency with a local build
typebulb --help                Show help
typebulb --version             Show version

Bulb Format

A bulb is a single markdown file — the minimum viable structure for a small app. Its named blocks hold the code, plus optional styles, data, and config. Every block except code.tsx is optional. Mechanically, each block is a **name** header on its own line followed by a fenced code block, and the file opens with YAML frontmatter (format: typebulb/v1, name:).

| Block | Purpose | |-------|---------| | **code.tsx** | Required. App logic and UI (TypeScript/TSX). | | **index.html** | The mount container. Include it — nearly every bulb does (e.g. <div id="root"></div>). Only pure console apps omit it. | | **styles.css** | CSS. | | **config.json** | dependencies and a description. | | **data.txt** | Read-only data your code processes via tb.data(n) (raw string) / tb.json(n) (parsed) — JSON, CSV, XML, YAML, or plain text. Multiple chunks are separated by two blank lines. | | **infer.md** / **insight.json** | Runtime one-shot LLM call via tb.infer() — a typebulb.com feature; not supported locally. | | **notes.md** | Persistent context for the AI assistant, carried across conversations and clones. Not run. | | **server.ts** | Node.js code; its exports become tb.server.<name>() in the browser. Mostly plain Node — log with console.log — but tb.ai/tb.ai.stream/tb.models are callable here too (under --trust). Local only. |

Example

---
format: typebulb/v1
name: Counter
---

**code.tsx**

```tsx
import React, { useState } from "react"
import { createRoot } from "react-dom/client"

function App() {
  const [n, setN] = useState(0)
  return (
    <div className="card">
      <h1>Count: {n}</h1>
      <button onClick={() => setN(n + 1)}>increment</button>
    </div>
  )
}

createRoot(document.getElementById("root")!).render(<App />)
```

**index.html**

```html
<div id="root"></div>
```

**styles.css**

```css
.card {
  max-width: 360px;
  margin: 0 auto;          /* horizontal centering only */
  padding: 24px 16px;      /* vertical space as padding, never margin (see Sizing) */
  font: 14px system-ui, sans-serif;
  display: grid;
  gap: 12px;
  text-align: center;
}
h1 { font-size: 20px; margin: 0; }
button {
  font: inherit;
  padding: 6px 14px;
  border: 1px solid currentColor;   /* theme-aware: inherits light/dark */
  border-radius: 6px;
  background: transparent;
  color: inherit;
  cursor: pointer;
}
```

**config.json**

```json
{
  "description": "A button that increments a counter.",
  "dependencies": {
    "react": "^19.2.7",
    "react-dom": "^19.2.7"
  }
}
```

Run it:

npx typebulb my-app.bulb.md

Or install globally:

npm install -g typebulb

The tb.* API, by target

tb is a pre-declared global your code can use without importing. What each call does, and where it works:

| API | What it does | Local | Embedded | |-----|--------------|:-----:|:--------:| | tb.data(n) / tb.json(n) | Read data chunk n from the data.txt block — raw string, or parsed JSON | ✅ | ✅ | | tb.insight() | Read the insight.json block as JSON | ✅ | ✅ | | tb.theme | Get/set the light/dark override; undefined follows the OS | ✅ | ✅ | | tb.mode | Runtime mode — 'local' (CLI) or 'embedded' (sandboxed iframe); 'editor'/'published' on typebulb.com | ✅ | ✅ | | tb.proxy(url) | Rewrite a CDN URL to load through the host origin (Web Worker / WASM) | ✅ | ✅ | | tb.dump(...) | Log values (incl. lazy / device-backed tensors) to the browser console | ✅ | ✅ | | tb.copy(text) | Copy text to the clipboard | ✅ | ✅ | | tb.url() | Get the bulb URL (the served localhost URL, locally) | ✅ | ✅ | | tb.models() | List available AI models (for dynamic model selectors); returns [] when embedded (no host AI) | ✅ | ✅ | | tb.hasOwnKeys() | Whether the user's own AI keys back tb.ai — false means courtesy model only; always false embedded | ✅ | ✅ | | tb.onMessage(cb) | Receive a value pushed in from the terminal by typebulb send — inert when embedded (no sender) | ✅ | ✅ | | tb.fs.read/readBytes/write | Read and write local files | ✅ --trust | ❌ | | tb.server.<name>(...) | Call a function exported from the server.ts block | ✅ --trust | ❌ | | tb.ai({ messages, … }) | General-purpose AI call (chat, agents) | ✅ --trust | ❌ | | tb.ai.stream({ … }) | Streaming AI — for await an AsyncIterable<{ kind, text }> of deltas | ✅ --trust | ❌ | | tb.infer() | One-shot LLM call driven by the infer.md block | ❌ | ❌ |

• ❌ (embedded): the call throws "not available in an embedded bulb" — an embed is a client-only sandboxed iframe with no persistent storage either (localStorage, IndexedDB, cookies, same-origin Workers all fail), so keep state in memory. tb.mode === 'embedded' lets a bulb detect this and self-adjust.
• tb.proxy only rewrites allow-listed CDNs — esm.sh, unpkg.com, cdn.jsdelivr.net, cdnjs.cloudflare.com; any other host 403s. Serve a WASM/worker asset (a tesseract or ffmpeg core, a pdf.js worker) from one of these.

Portability back to typebulb.com

A local .bulb.md can be re-imported into typebulb.com. If it has a **server.ts** block you'll be warned on import, since server.ts is only meaningful locally.

Agent Harness Support

The agent mirror gives the user a great scratchpad experience for the Claude Code and Pi agent harnesses (npx typebulb agent:{claude|pi}). This lets the user:

• view the project's conversations/sessions, where assistant messages containing bulbs render as 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.

Start it yourself with npx typebulb agent (it auto-detects your harness) — 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.

One exception: if TYPEBULB_MIRROR=1 is set in your environment, the user is prompting you from the mirror itself — it's already open in front of them, so skip npx typebulb agent and don't end with its link; just emit bulbs.

To keep this skill on hand across sessions, run npx typebulb skill and copy its output into your skills folder (e.g. for Claude Code, .claude/skills/typebulb/SKILL.md) — only if the user asks. On Pi this is unnecessary: the CLI keeps ~/.pi/agent/skills/typebulb/ installed and current automatically.

When agents 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. 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.

Emitting an embedded bulb

To render a bulb live inline, wrap the entire bulb — frontmatter and all blocks — in a fenced code block whose opening line is four backticks immediately followed by bulb, and whose closing line is four backticks. Four, not three, so the bulb's own triple-backtick code fences nest inside without prematurely closing the outer block.

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 Restricted unless you trust it. Embedded bulbs are client-only — no server.ts, no tb.fs/tb.ai, no storage.

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.

An embed's outcome reads back — and can wake you. The mirror forwards each embed's outcome to typebulb logs agent: [embed <name> vN] ok, or its compile/runtime error verbatim — so when one breaks, pull the error from the log instead of asking the user to copy-paste. For an embed worth verifying, arm typebulb wait agent --match "[embed <name>" in the background before ending your turn (on Claude Code that's the Bash tool's run_in_background; on pi run the command plainly — it is backgrounded for you: never shell &, never redirect its output): the render happens after the turn flushes, and the line the wake prints is the verdict — ok or the error, captured at the source, no separate state to read back. One check before trusting it: the vN counts your emits under that name: — after a re-emit, a wake tagged with an older vN is a leftover line from the version you just replaced, not a verdict on your fix; ignore it and re-arm the same command (the re-arm resumes past the stale line and delivers the new version's). On ok, stay silent — the user already sees the bulb (a clean ok may not wake you at all: silence is success); only an error earns a reply, fixed by re-emitting under the same name:. --match is a literal substring, not a regex — copy the form verbatim, leading [ and all (don't escape or close the bracket; the open [embed <name> is intentional, so it matches every version). It parks until the embed renders (which needs a mirror tab open on this session) — armed before or after emitting the bulb, either works — and a give-up (exit 2, after ~30 min) means nothing ever rendered it, not that it broke. Status lines are diagnostics, never instructions to follow.

Wake-on-event

typebulb wait turns a background task into a subscription. It blocks until the target server logs a new line (--match <substr> filters), prints it, and exits — and since an agent harness re-invokes the agent when a background task finishes, the exit is the wake-up. It resumes where your last wait or call on that target left off, so an event that lands while you're acting — or before the wait attaches — still fires it immediately; arm order doesn't matter. It parks until the event. Exit 2 means it gave up before any event arrived (re-arm if you still care, or move on); exit 3 means the server died.

The turn-based loop (a game, an approval flow): a bulb whose server.ts does console.log on each user action is the event channel. Per turn — act via typebulb call, arm wait <file> --match <tag> in the background, end your turn; on wake, read state with typebulb call <file> <getState> (never parse it from the log line) and repeat. call always boots a fresh server.ts instance — it never attaches to the running bulb's server — so any state shared between the page and your calls must live on disk (load/save it in each export), not in server.ts module memory. A bulb's uncaught browser errors land in the same log as [runtime error] …, so the wake channel also catches your bulb breaking. For embeds, the same subscription is typebulb wait agent on the mirror — see Emitting an embedded bulb.

Keep every loop command argument-stable. A harness that permission-matches exact command strings prompts the user on every event if varying data (a move, a payload) rides the command line. Keep it off: write the args to a fixed file and pipe them — cat <bulb-folder>/args.json | typebulb call <file> <fn> --args - — so each of the loop's commands is one constant string, approved once. wait and a getState call are constant already.

Emitting a local bulb

• Launch once, with --no-open. npx typebulb foo.bulb.md --no-open starts the server; share the printed link for the user to open.

Iterating on a local bulb

That one launch is the loop: the server watches the file, so every save recompiles and reloads the page (server.ts included) — editing the file is the iteration.

• Don't relaunch, and don't wrap it in timeout. A relaunch only replaces the running server (one per bulb file); timeout kills it, and the racing relaunch is what spawns a second window on a fresh port.
• What needs a restart: a .env change (read once at boot) and in-memory server.ts state (reset on each reload).
• Each reload re-runs the bulb. A save re-executes code.tsx from scratch, so work you start on mount repeats every edit — re-spending GPU/network, re-firing side effects, flooding the log. Put expensive or side-effecting work behind a trigger: tb.onMessage(() => start()), then typebulb send <file> when ready (also a general terminal→page channel — pass params, drive a loop).
• Reading the log: it appends across every reload, so typebulb logs --run latest <file> shows just the current run (no need to clear).
• When done: Ctrl-C, or typebulb stop <file> — closing the terminal leaves the server running detached.

Emitting a server-only bulb

A **server.ts** block with no **code.tsx** is a headless bulb — no UI, no port, absent from the launcher. Under --trust its code can call tb.ai, tb.ai.stream, and tb.models against your .env keys.

• Invoke one export with typebulb call <file> <fn> [args…] --trust. It boots, runs that export, prints the return as JSON to stdout, and exits — a fresh boot per call. Log with console.log (no tb.server.log here); under call logs go to stderr, so the JSON result owns stdout.

Sizing

The host owns a bulb's width; you own its height.

Width is the host's. Standalone, a bulb fills its browser window; in the agent mirror, an embed fits the conversation column by default, with a per-embed spread toggle to the full transcript width — and a cap so a tall embed doesn't run away down the transcript. Don't set a width or guess how much room you'll get. max-width is the one width worth setting — a readability cap that only declines excess, so it's safe at any granted width. It's also what spread runs into: a dense visualization that earns the full transcript width should omit it.

Height follows your content. Set a height that adapts — content-driven or viewport-filling — never a fixed pixel value, which neither grows to fill a broken-out window nor shrinks to its content. Prose, a form, a chart flow to their natural height: set none. A full-bleed surface with no natural height of its own gets height: 100dvh and a pixel floor like min-height: 420px. Both are needed — 100dvh fills its own window if the bulb is broken out, and the floor holds a definite band when embedded. Without the floor a bare 100dvh collapses to zero embedded, because the mirror sizes an embed to its content height and 100dvh gives it nothing to measure against.

When embedded, keep vertical space on the root in padding, not margin. The mirror measures an embed by document.body.scrollHeight, and the runtime makes body a block formatting context so a root child's vertical margin (yours, or a UA default like <h1>'s) is contained rather than escaping the measurement — so you no longer have to get this exactly right. It's still cleaner to keep the horizontal auto for centering and move the vertical space to padding:

.wrap { margin: 0 auto; padding: 24px 16px; }   /* not: margin: 24px auto */

Tips for Agents

• config.json description is the bulb's search-result blurb — what makes someone open it, kept short (it truncates past ~160 chars).
• The frontmatter name: is the bulb's title — a few words, not a sentence — and the filename should be its slug (name: Counter → counter.bulb.md), saved in the project's typebulbs/ folder.
• A bulb's working files belong beside it, in a folder named for its slug. tb.fs/server.ts paths are relative to the launch dir (cwd), not the bulb's folder — so run from the project root and prefix the bulb's path: typebulbs/counter/…, not a bare counter/….
• Self-testing a local bulb — To confirm a bulb works, run it, instrument with tb.server.log(...) (prints to the server's stdout, captured in the log — and works even on a Restricted bulb), and read it back with typebulb logs. That's the loop to verify behaviour without asking the user to copy-paste console output. tb.fs.write(...) is handy for dumping large outputs.
• Self-testing client code — to drive the browser side, gate the work behind tb.onMessage(m => { if (m === 'selftest') run() }), trigger it with typebulb send <file> selftest --wait, and read run()'s tb.server.log(...) back the same way. The client-side counterpart to instrumenting server.ts.
• Testing a server.ts export directly — typebulb call <file> <fn> [arg…] boots server.ts, invokes one export, and prints its return as JSON to stdout (logs/errors to stderr, so … | jq works). Args after <fn> are JSON-or-string; --args '<json-array>' (or --args - for stdin) escapes tricky quoting. Needs --trust.
• Mount to the container your index.html declares. The corpus convention is <div id="root"></div> with createRoot(document.getElementById("root")!).
• All imports at the top of code.tsx, and every bare import declared in config.json dependencies. Bare imports (react, d3, three, …) resolve from a CDN — no install step — but declaring them is required, not optional: an import missing from dependencies is a lint error that fails npx typebulb check and refuses to run. Declaring is also what pins versions and lets check fetch type defs (without it you get errors like TS2875: react/jsx-runtime). So a bulb with imports must carry a config.json with a matching dependencies entry for each.
• Theme-aware styling. Style off CSS variables / currentColor so the bulb reads correctly in both light and dark; the host sets the theme.
• tb.ai() takes more than the basics — the full shape is tb.ai({ messages, system?, effort?, provider?, model?, webSearch? }) → Promise<{ text }>. webSearch defaults on in the CLI (you supply your own key); pass webSearch: false to turn it off. For token-by-token output use tb.ai.stream(...) (see tb.ai() § Streaming).
• Gate AI-heavy bulbs on tb.hasOwnKeys(). false means only the quota-limited courtesy model backs tb.ai (or, in the CLI, no keys at all) — fine for a call or two, but a bulb that makes many (an agent loop, a model-vs-model game) should render a "use your own keys" notice instead of the run controls.
• 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 (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).
• Charts: prefer a bulb over mermaid's xychart unless a static, unlabeled bar or line is enough — start from the Charts skeleton.
• 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 Restricted run without forgetting the grant.

Here's a state transition diagram for the trust tiers:

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):

import React, { useState } from "react"

Which must be declared in the dependencies section:

  "dependencies": {
    "react": "^19.2.7"
  }

Typebulb has a package resolver that will load and cache these packages from esm.sh when the bulb runs.

Custom AI Models

Three ways to use models from different providers in typebulb:

• tb.ai() — a bulb's own code calling AI providers with your keys
• proxy claude — backs your claude sessions with an alternate (OpenRouter) model
• Use the Pi agent harness npx typebulb agent:pi

.env setup

Add API keys to your .env file:

| Provider name | API key env var | |---------------|-----------------| | anthropic | ANTHROPIC_API_KEY | | openai | OPENAI_API_KEY | | gemini | GOOGLE_API_KEY | | openrouter | OPENROUTER_API_KEY | | ollama | (none — local server) | | openai-compat | TB_AI_API_KEY (optional) + TB_AI_BASE_URL |

Optionally, set your default provider and model:

TB_AI_PROVIDER=anthropic
TB_AI_MODEL=claude-haiku-4-5-20251001

Run typebulb models to list the models available for the providers specified.

tb.ai()

Trusted bulbs can call AI providers from their own code at runtime, billed to your API keys.

You can call the provider and model explicitly like this: tb.ai({ provider: "gemini", model: "gemini-3.1-flash-lite", ... }).

Or you can rely on the default provider and model if you set them in .env.

Reasoning effort

tb.ai() accepts an optional effort parameter (0–3) that hints at how much the model should reason. low (1) is the sensible default for most work; omit it for the model's own default.

| Level | Label | Effect | |-------|-------|--------| | 0 | Minimal | Least reasoning — mapped to each provider's floor. Not a guaranteed "off": some models still think a little, and adaptive ones already self-skip at low. | | 1 | Low | Light reasoning | | 2 | Med | Moderate reasoning | | 3 | High | Heavy reasoning |

const { text } = await tb.ai({
  messages: [{ role: "user", content: "Explain quantum tunneling" }],
  effort: 2,
});

Streaming

tb.ai.stream({ … }) is the streaming counterpart of tb.ai() — an async iterable of { kind: "text" | "reasoning", text } deltas. tb.ai() (await the full text) is unchanged; reach for .stream only when a response is long enough to be worth showing as it arrives.

let answer = "";
for await (const c of tb.ai.stream({ messages })) {
  if (c.kind === "text") { answer += c.text; render(answer); }   // c.kind === "reasoning" for thinking deltas
}

Breaking the loop stops the stream; same options as tb.ai(). kind: "reasoning" chunks require effort: 1-3 and a thinking-capable model.

Ollama & OpenAI-compatible endpoints

provider: "ollama" is the zero-config local preset: it talks to a local Ollama server over its OpenAI-compatible endpoint — no API key, defaults to http://localhost:11434 (override with OLLAMA_HOST). typebulb models lists your installed Ollama models alongside cloud ones.

provider: "openai-compat" is the generic escape hatch to any OpenAI-compatible endpoint — local or remote (LM Studio, vLLM, a self-hosted box, a keyed proxy, a cloud OpenAI-compat vendor). Set TB_AI_BASE_URL (the OpenAI-style base URL ending in /v1, e.g. http://localhost:1234/v1 — /chat/completions is appended) and an optional TB_AI_API_KEY. Set TB_AI_MODEL explicitly (no auto-discovery).

Proxying Claude

The user can proxy claude with the agent mirror's model switcher, to any model on OpenRouter model instead of Anthropic. This lets the user use OpenRouter models with Claude Code's harness.

Charts

Mermaid's xychart-beta is static, unlabeled bars and lines — no tooltips, no legend, no other chart types. Anything more is a bulb. Start from this skeleton:

---
format: typebulb/v1
name: Revenue vs Cost
---

**code.tsx**

```tsx
import React from "react"
import { createRoot } from "react-dom/client"
import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend,
  ResponsiveContainer } from "recharts"

type Point = { month: string; revenue: number; cost: number }
const data = tb.json<Point[]>(0)

function App() {
  return (
    <div className="wrap">
      <h1>Revenue vs Cost</h1>
      <ResponsiveContainer width="100%" height={320}>
        <LineChart data={data}>
          <CartesianGrid stroke="currentColor" strokeOpacity={0.1} />
          <XAxis dataKey="month" stroke="currentColor" tick={{ fill: "currentColor", fontSize: 12 }} />
          <YAxis stroke="currentColor" tick={{ fill: "currentColor", fontSize: 12 }} />
          <Tooltip contentStyle={{ background: "Canvas", color: "CanvasText",
            border: "1px solid currentColor", borderRadius: 6 }} />
          <Legend wrapperStyle={{ fontSize: 13 }} />
          <Line dataKey="revenue" stroke="#14b8a6" strokeWidth={2} />
          <Line dataKey="cost" stroke="#e11d48" strokeWidth={2} />
        </LineChart>
      </ResponsiveContainer>
    </div>
  )
}

createRoot(document.getElementById("root")!).render(<App />)
```

**index.html**

```html
<div id="root"></div>
```

**styles.css**

```css
.wrap {
  max-width: 720px;        /* readability cap — omit when the chart earns spread width */
  margin: 0 auto;          /* horizontal centering only */
  padding: 24px 16px;      /* vertical space as padding, never margin (see Sizing) */
  font: 14px system-ui, sans-serif;
}
h1 { font-size: 18px; margin: 0 0 12px; }
```

**data.txt**

```txt
[
  { "month": "Jan", "revenue": 12, "cost": 8 },
  { "month": "Feb", "revenue": 14, "cost": 9 },
  { "month": "Mar", "revenue": 11, "cost": 10 },
  { "month": "Apr", "revenue": 17, "cost": 10 },
  { "month": "May", "revenue": 21, "cost": 12 },
  { "month": "Jun", "revenue": 24, "cost": 12 }
]
```

**config.json**

```json
{
  "description": "Monthly revenue vs cost as a two-series line chart.",
  "dependencies": {
    "react": "^19.2.7",
    "react-dom": "^19.2.7",
    "recharts": "^3.8.1"
  }
}
```

The non-obvious bits: axes and grid off currentColor (light/dark with zero theme JS), the tooltip on Canvas/CanvasText system colors, and an explicit height on ResponsiveContainer — a chart has no natural height; the root still sizes to content. For point-dense marks (thousands of scatter dots or bars) or types recharts lacks (heatmap, candlestick, gauge), use echarts (canvas) instead.

License

MIT