typebulb 0.45.2 → 0.47.0

package/README.md

@@ -46,6 +46,7 @@ typebulb send <file> tb:snapshot  Print the live page's rendered outline (roles,
 typebulb send <file> tb:rect …    Print a named control's rect ('tb:rect button "Pass"' → {x,y,width,height} + viewport)
 typebulb send <file> tb:click …   Click a control by role+name ('tb:click button "Pass"'); the reply is a fresh snapshot
 typebulb send <file> tb:set …     Set a form control ('tb:set combobox "level" = hard'), firing input+change
+typebulb send <file> tb:png …     Save the live canvas as PNG, print its path (sole canvas needs no name; 'tb:png "<name>"' among several)
 typebulb get <file> <kind>     Print one block's content (data, insight, code, …) to stdout
 typebulb put <file> <k>=<src>  Write a file's (or stdin's) content into a block, surgically
 typebulb pull <url|file>       Fetch a bulb from typebulb.com into typebulbs/u/<user>/<slug>.bulb.md
@@ -197,7 +198,7 @@ everywhere.
 | `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); the `.env` default is flagged (`default: true`); 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.aiAccess()` | What backs `tb.ai` — `'own' \| 'courtesy' \| 'none'` | |
 | `tb.log(...)` | Print to the CLI's stdout (read back with `typebulb logs`); falls back to the browser console when no CLI serves the page | |
 | `tb.onMessage(cb)` | Receive a value pushed in from the terminal by `typebulb send`; a non-`undefined` return becomes the reply `send --wait` prints — inert when embedded (no sender) | |
 | `tb.fs.read/readBytes/write` | Read and write local files | yes |
@@ -272,6 +273,7 @@ That one launch *is* the loop: the server watches the file, so every save recomp
 - **Acting on the page** — `typebulb send <file> 'tb:click button "Pass"'` clicks the one control matching that role and name (exact, else a unique case-insensitive substring) and replies with a fresh snapshot; `tb:set combobox "strength" = hard` is the same for form controls (checkboxes and radios take `tb:click`). A disabled, readonly, or covered target is an error naming it — that silence is the bug class these verbs catch. Needs exactly one page open, and the reply is the immediate frame (slow work: follow up with `tb:snapshot`). Only what the outline names is targetable: real `<button>`s and labeled controls, not an `onClick` `<div>`.
 - **Poking state** — for state beyond what a form control expresses (`tb:set` covers those), author a set-handler up front: a `tb.onMessage` branch that takes a data payload (JSON arrives parsed), applies it to your state — committing the change if your framework needs an explicit step — and returns the new state: `typebulb send <file> '{"set":"speed","value":2}' --wait` prints it. In React, register it in an effect so it closes over the setters (the returned unsubscribe is the cleanup).
 - **A page must be open** — the CLI runs no browser of its own, so every client-side check waits on a real window (and `--no-open` means there isn't one). `send` says which case it is: nobody has ever connected (share the link), or a page dropped and hasn't returned (it's stale — reload it). Never open a window at the user: the server logs `[page] connected` when a page attaches, so end your turn with the link, arming `typebulb wait <file> --match "[page] connected"` in the background first — the user opening the page is your wake-up.
+- **Reading a canvas** — `typebulb send <file> tb:png` writes the page's canvas to a PNG (a stable per-bulb path under `~/.typebulb/`, overwritten each read) and prints the path — rendered truth for a bulb whose output is drawn, with no probe handler and nothing disturbed. One canvas needs no name; several take `tb:png "<name>"` (an `aria-label` on the canvas names it). A WebGL/WebGPU canvas without `preserveDrawingBuffer` reads back blank outside its own frame — capture during the draw instead.
 
 ### Emitting a server-only bulb
 
@@ -302,14 +304,14 @@ The host owns a bulb's **width**; you own its **height**.
 - **Self-testing a local bulb** — To confirm a bulb works, run it, instrument with `tb.log(...)`, 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** — gate checks behind `tb.onMessage(m => { if (m === 'selftest') return run() })`, trigger with `typebulb send <file> selftest --wait`, and assert on the JSON reply — see [Interrogating the live page](#interrogating-the-live-page).
 - **Probe handlers go in the first draft** — the selftest, readback, and set handlers you'll want later: adding one is an edit, and that hot reload destroys the very state you meant to inspect.
-- **Read a canvas back as an image** — return a bare `canvas.toDataURL()` string from a handler; `typebulb send <file> png --wait` prints it raw, and decoding the base64 after the `data:image/png;base64,` prefix yields a PNG you can view. That's the visual-verification loop for canvas/WebGPU bulbs.
+- **Read a canvas back as an image** — `typebulb send <file> tb:png`: the visual-verification loop for canvas/WebGPU bulbs (see [Interrogating the live page](#interrogating-the-live-page)). The authored form — return a bare `canvas.toDataURL()` string from a handler — remains for what the verb can't reach, like capturing a WebGL frame during its own draw.
 - **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.
 - **Native dropdowns.** Style `select, option { background: Canvas; color: CanvasText }` (system colors track the host's `color-scheme`) — a `transparent` `<select>` otherwise opens an unthemed popup, white-on-white in dark mode.
 - **`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](#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.
+- **Gate AI-heavy bulbs on `tb.aiAccess()`** — `'own'` / `'courtesy'` / `'none'`, never re-derived from `tb.mode` or the model list (see [AI access](#ai-access)).
 - **`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).
@@ -371,7 +373,7 @@ Which must be declared in the dependencies section:
 
 Typebulb has a package resolver that will load and cache these packages from `esm.sh` when the bulb runs.
 
-## Custom AI Models
+## AI Models
 
 Three ways to use models from different providers in typebulb:
 
@@ -440,6 +442,21 @@ for await (const c of tb.ai.stream({ messages })) {
 
 Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-3` and a thinking-capable model**.
 
+### AI access
+
+`tb.aiAccess()` reports what backs `tb.ai`, typed as the ambient `AiAccess`.
+
+| Value | What it means | What a bulb does |
+|-------|---------------|------------------|
+| `'own'` | The user's own keys, or their own local model server | Run everything |
+| `'courtesy'` | typebulb.com's quota-limited courtesy model | Fine for a call or two; a bulb that makes many (an agent loop, a model-vs-model game) shows a "use your own keys" notice instead of the run controls |
+| `'none'` | No AI at all — the CLI with no keys, or an embedded bulb | Say so; don't leave dead controls on screen |
+
+```ts
+const [access, setAccess] = useState<AiAccess>("own");
+useEffect(() => { tb.aiAccess().then(setAccess); }, []);
+```
+
 ### Ollama & OpenAI-compatible endpoints
 
 `provider: "ollama"` is the zero-config local preset: it talks to a local [Ollama](https://ollama.com) 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.

package/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: typebulb
 description: "Author and run Typebulb bulbs — single-file markdown apps (TypeScript/TSX) that run locally via `npx typebulb` (full power: filesystem, database, `server.ts`, `tb.ai`) or render live inline in your coding agent's session through Typebulb's agent mirror (embedded, client-only). A bulb can be a visual widget (chart, simulation, diagram, calculator, UI), a full-stack tool with a Node backend, or an AI app that calls models at runtime. Covers the bulb format, the `tb.*` API, trust, and the local run/embed workflow. Use when the user wants a bulb, a quick local tool (visual, backend-backed, or AI-powered), or something visual rendered inline in the conversation."
-version: 0.45.2
+version: 0.47.0
 ---
 
-> Generated from typebulb v0.45.2. `npx typebulb agent` prints the running version alongside the path to its packaged SKILL.md: if that version is newer than this one, replace this file with that one.
+> Generated from typebulb v0.47.0. `npx typebulb agent` prints the running version alongside the path to its packaged SKILL.md: if that version is newer than this one, replace this file with that one.
 
 # typebulb
 
@@ -54,6 +54,7 @@ typebulb send <file> tb:snapshot  Print the live page's rendered outline (roles,
 typebulb send <file> tb:rect …    Print a named control's rect ('tb:rect button "Pass"' → {x,y,width,height} + viewport)
 typebulb send <file> tb:click …   Click a control by role+name ('tb:click button "Pass"'); the reply is a fresh snapshot
 typebulb send <file> tb:set …     Set a form control ('tb:set combobox "level" = hard'), firing input+change
+typebulb send <file> tb:png …     Save the live canvas as PNG, print its path (sole canvas needs no name; 'tb:png "<name>"' among several)
 typebulb get <file> <kind>     Print one block's content (data, insight, code, …) to stdout
 typebulb put <file> <k>=<src>  Write a file's (or stdin's) content into a block, surgically
 typebulb pull <url|file>       Fetch a bulb from typebulb.com into typebulbs/u/<user>/<slug>.bulb.md
@@ -205,7 +206,7 @@ everywhere.
 | `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); the `.env` default is flagged (`default: true`); 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.aiAccess()` | What backs `tb.ai` — `'own' \| 'courtesy' \| 'none'` | |
 | `tb.log(...)` | Print to the CLI's stdout (read back with `typebulb logs`); falls back to the browser console when no CLI serves the page | |
 | `tb.onMessage(cb)` | Receive a value pushed in from the terminal by `typebulb send`; a non-`undefined` return becomes the reply `send --wait` prints — inert when embedded (no sender) | |
 | `tb.fs.read/readBytes/write` | Read and write local files | yes |
@@ -280,6 +281,7 @@ That one launch *is* the loop: the server watches the file, so every save recomp
 - **Acting on the page** — `typebulb send <file> 'tb:click button "Pass"'` clicks the one control matching that role and name (exact, else a unique case-insensitive substring) and replies with a fresh snapshot; `tb:set combobox "strength" = hard` is the same for form controls (checkboxes and radios take `tb:click`). A disabled, readonly, or covered target is an error naming it — that silence is the bug class these verbs catch. Needs exactly one page open, and the reply is the immediate frame (slow work: follow up with `tb:snapshot`). Only what the outline names is targetable: real `<button>`s and labeled controls, not an `onClick` `<div>`.
 - **Poking state** — for state beyond what a form control expresses (`tb:set` covers those), author a set-handler up front: a `tb.onMessage` branch that takes a data payload (JSON arrives parsed), applies it to your state — committing the change if your framework needs an explicit step — and returns the new state: `typebulb send <file> '{"set":"speed","value":2}' --wait` prints it. In React, register it in an effect so it closes over the setters (the returned unsubscribe is the cleanup).
 - **A page must be open** — the CLI runs no browser of its own, so every client-side check waits on a real window (and `--no-open` means there isn't one). `send` says which case it is: nobody has ever connected (share the link), or a page dropped and hasn't returned (it's stale — reload it). Never open a window at the user: the server logs `[page] connected` when a page attaches, so end your turn with the link, arming `typebulb wait <file> --match "[page] connected"` in the background first — the user opening the page is your wake-up.
+- **Reading a canvas** — `typebulb send <file> tb:png` writes the page's canvas to a PNG (a stable per-bulb path under `~/.typebulb/`, overwritten each read) and prints the path — rendered truth for a bulb whose output is drawn, with no probe handler and nothing disturbed. One canvas needs no name; several take `tb:png "<name>"` (an `aria-label` on the canvas names it). A WebGL/WebGPU canvas without `preserveDrawingBuffer` reads back blank outside its own frame — capture during the draw instead.
 
 ### Emitting a server-only bulb
 
@@ -310,14 +312,14 @@ The host owns a bulb's **width**; you own its **height**.
 - **Self-testing a local bulb** — To confirm a bulb works, run it, instrument with `tb.log(...)`, 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** — gate checks behind `tb.onMessage(m => { if (m === 'selftest') return run() })`, trigger with `typebulb send <file> selftest --wait`, and assert on the JSON reply — see [Interrogating the live page](#interrogating-the-live-page).
 - **Probe handlers go in the first draft** — the selftest, readback, and set handlers you'll want later: adding one is an edit, and that hot reload destroys the very state you meant to inspect.
-- **Read a canvas back as an image** — return a bare `canvas.toDataURL()` string from a handler; `typebulb send <file> png --wait` prints it raw, and decoding the base64 after the `data:image/png;base64,` prefix yields a PNG you can view. That's the visual-verification loop for canvas/WebGPU bulbs.
+- **Read a canvas back as an image** — `typebulb send <file> tb:png`: the visual-verification loop for canvas/WebGPU bulbs (see [Interrogating the live page](#interrogating-the-live-page)). The authored form — return a bare `canvas.toDataURL()` string from a handler — remains for what the verb can't reach, like capturing a WebGL frame during its own draw.
 - **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.
 - **Native dropdowns.** Style `select, option { background: Canvas; color: CanvasText }` (system colors track the host's `color-scheme`) — a `transparent` `<select>` otherwise opens an unthemed popup, white-on-white in dark mode.
 - **`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](#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.
+- **Gate AI-heavy bulbs on `tb.aiAccess()`** — `'own'` / `'courtesy'` / `'none'`, never re-derived from `tb.mode` or the model list (see [AI access](#ai-access)).
 - **`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).
@@ -379,7 +381,7 @@ Which must be declared in the dependencies section:
 
 Typebulb has a package resolver that will load and cache these packages from `esm.sh` when the bulb runs.
 
-## Custom AI Models
+## AI Models
 
 Three ways to use models from different providers in typebulb:
 
@@ -448,6 +450,21 @@ for await (const c of tb.ai.stream({ messages })) {
 
 Breaking the loop stops the stream; same options as `tb.ai()`. **`kind: "reasoning"` chunks require `effort: 1-3` and a thinking-capable model**.
 
+### AI access
+
+`tb.aiAccess()` reports what backs `tb.ai`, typed as the ambient `AiAccess`.
+
+| Value | What it means | What a bulb does |
+|-------|---------------|------------------|
+| `'own'` | The user's own keys, or their own local model server | Run everything |
+| `'courtesy'` | typebulb.com's quota-limited courtesy model | Fine for a call or two; a bulb that makes many (an agent loop, a model-vs-model game) shows a "use your own keys" notice instead of the run controls |
+| `'none'` | No AI at all — the CLI with no keys, or an embedded bulb | Say so; don't leave dead controls on screen |
+
+```ts
+const [access, setAccess] = useState<AiAccess>("own");
+useEffect(() => { tb.aiAccess().then(setAccess); }, []);
+```
+
 ### Ollama & OpenAI-compatible endpoints
 
 `provider: "ollama"` is the zero-config local preset: it talks to a local [Ollama](https://ollama.com) 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.