typebulb 0.55.5 → 0.56.1

package/README.md

@@ -30,7 +30,7 @@ This document is dedicated to the typebulb CLI. At its core, it compiles and ser
 - **`tb.infer()`** — one-shot runtime inference over the bulb's own blocks (`infer.md` + `data.txt` → `insight.json`), with a confirmation modal, streaming, and share/save of a good run. 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 inline bulbs, KaTeX, and mermaid live in the conversation, 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, Codex, or Pi).
+- **Agent mirror** — a browser view of your coding agent's sessions, rendering inline bulbs, KaTeX, and mermaid live in the conversation, 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, Codex, or Pi). Bulbs the agent runs open where the mirror is: in VS Code beside it, or in your browser.
 - **Proxying Claude** — the agent mirror lets you proxy Claude with a model from [OpenRouter](https://openrouter.ai). This will apply to your project only.
 
 ## Usage
@@ -68,7 +68,7 @@ typebulb trust [file]          Remember a bulb as trusted (no arg: list trusted
 typebulb untrust <file>        Forget a bulb's trust (back to Restricted)
 typebulb --no-watch <file>     Disable hot reload
 typebulb --port 3333 <file>    Bind this exact port (fails if taken)
-typebulb --no-open <file>      Don't auto-open browser
+typebulb --no-open <file>      Open nothing at launch, not even inside VS Code
 typebulb --mode <name> <file>  Also load .env.<name> on top of .env / .env.local
 typebulb --batch <name> <file> Scope tb.dir + relative tb.fs paths to <bulb-folder>/batches/<name> (batch runs)
 typebulb --trust <file>        Grant filesystem + AI + server.ts for this run (default: Restricted)
@@ -258,7 +258,7 @@ The agent mirror turns that block into a live, sandboxed app, with a *breakout
 
 ### Emitting a local bulb
 
-- **Launch once, and share the printed link.** `npx typebulb foo.bulb.md` starts the server (in VS Code's terminal and agent shells it prints the link to share rather than opening a tab). The link stays good: a bulb keeps its port across runs, keyed to the filename, so re-share it after a rename.
+- **Launch once, and share the printed link.** `npx typebulb foo.bulb.md` starts the server (the page opens where the agent mirror is; with no mirror page open, VS Code's terminal and agent shells print the link to share rather than opening a tab). The link stays good: a bulb keeps its port across runs, keyed to the filename, so re-share it after a rename.
 - **In an agent shell, background the launch** (Claude Code: `run_in_background`; pi: run it plainly). The server runs until stopped, so a foreground launch only holds your turn.
 
 ### Iterating on a local bulb
@@ -281,7 +281,7 @@ That one launch *is* the loop: the server watches the file, so every save recomp
 - **Measuring layout** — `typebulb send <file> 'tb:rect button "Pass"'` prints that control's viewport-relative rect as JSON (`{x, y, width, height, viewport}`, integers): how big something ended up, whether two things align, whether one is offscreen — arithmetic on rects, no probe handler. Only what the outline names is measurable; give a structural container a `role` **and** an `aria-label` (`<div role="group" aria-label="board">`) to measure it — a label alone leaves it invisible.
 - **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. The click is synthetic, so a handler needing user activation (a clipboard write, fullscreen) does nothing and reports nothing. 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.
+- **A page must be open** — the CLI runs no browser of its own, so every client-side check waits on a real window. The CLI opens one where the agent mirror is open (in VS Code beside it, or in the user's browser): at launch, and again from `send --wait` or any `tb:` verb that finds none, so a tab the user closed reopens and the message delivers. Run the bulb, edit, `send --wait`; never relaunch for a page. With no mirror page open anywhere, nothing can open one: end your turn with the link, arming `typebulb wait <file> --match "[page] connected"` in the background first; the user opening it is your wake-up. Never open a window at the user yourself.
 - **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, or `role="img" aria-label="…"` on the container when a chart library owns the canvas. A WebGL/WebGPU canvas without `preserveDrawingBuffer` reads back blank outside its own frame — capture during the draw instead.
 
 ### Emitting a server-only bulb

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 (sandboxed, 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/inline 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.55.5
+version: 0.56.1
 ---
 
-> Generated from typebulb v0.55.5. `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.56.1. `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
 
@@ -38,7 +38,7 @@ This document is dedicated to the typebulb CLI. At its core, it compiles and ser
 - **`tb.infer()`** — one-shot runtime inference over the bulb's own blocks (`infer.md` + `data.txt` → `insight.json`), with a confirmation modal, streaming, and share/save of a good run. 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 inline bulbs, KaTeX, and mermaid live in the conversation, 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, Codex, or Pi).
+- **Agent mirror** — a browser view of your coding agent's sessions, rendering inline bulbs, KaTeX, and mermaid live in the conversation, 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, Codex, or Pi). Bulbs the agent runs open where the mirror is: in VS Code beside it, or in your browser.
 - **Proxying Claude** — the agent mirror lets you proxy Claude with a model from [OpenRouter](https://openrouter.ai). This will apply to your project only.
 
 ## Usage
@@ -76,7 +76,7 @@ typebulb trust [file]          Remember a bulb as trusted (no arg: list trusted
 typebulb untrust <file>        Forget a bulb's trust (back to Restricted)
 typebulb --no-watch <file>     Disable hot reload
 typebulb --port 3333 <file>    Bind this exact port (fails if taken)
-typebulb --no-open <file>      Don't auto-open browser
+typebulb --no-open <file>      Open nothing at launch, not even inside VS Code
 typebulb --mode <name> <file>  Also load .env.<name> on top of .env / .env.local
 typebulb --batch <name> <file> Scope tb.dir + relative tb.fs paths to <bulb-folder>/batches/<name> (batch runs)
 typebulb --trust <file>        Grant filesystem + AI + server.ts for this run (default: Restricted)
@@ -266,7 +266,7 @@ The agent mirror turns that block into a live, sandboxed app, with a *breakout
 
 ### Emitting a local bulb
 
-- **Launch once, and share the printed link.** `npx typebulb foo.bulb.md` starts the server (in VS Code's terminal and agent shells it prints the link to share rather than opening a tab). The link stays good: a bulb keeps its port across runs, keyed to the filename, so re-share it after a rename.
+- **Launch once, and share the printed link.** `npx typebulb foo.bulb.md` starts the server (the page opens where the agent mirror is; with no mirror page open, VS Code's terminal and agent shells print the link to share rather than opening a tab). The link stays good: a bulb keeps its port across runs, keyed to the filename, so re-share it after a rename.
 - **In an agent shell, background the launch** (Claude Code: `run_in_background`; pi: run it plainly). The server runs until stopped, so a foreground launch only holds your turn.
 
 ### Iterating on a local bulb
@@ -289,7 +289,7 @@ That one launch *is* the loop: the server watches the file, so every save recomp
 - **Measuring layout** — `typebulb send <file> 'tb:rect button "Pass"'` prints that control's viewport-relative rect as JSON (`{x, y, width, height, viewport}`, integers): how big something ended up, whether two things align, whether one is offscreen — arithmetic on rects, no probe handler. Only what the outline names is measurable; give a structural container a `role` **and** an `aria-label` (`<div role="group" aria-label="board">`) to measure it — a label alone leaves it invisible.
 - **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. The click is synthetic, so a handler needing user activation (a clipboard write, fullscreen) does nothing and reports nothing. 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.
+- **A page must be open** — the CLI runs no browser of its own, so every client-side check waits on a real window. The CLI opens one where the agent mirror is open (in VS Code beside it, or in the user's browser): at launch, and again from `send --wait` or any `tb:` verb that finds none, so a tab the user closed reopens and the message delivers. Run the bulb, edit, `send --wait`; never relaunch for a page. With no mirror page open anywhere, nothing can open one: end your turn with the link, arming `typebulb wait <file> --match "[page] connected"` in the background first; the user opening it is your wake-up. Never open a window at the user yourself.
 - **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, or `role="img" aria-label="…"` on the container when a chart library owns the canvas. A WebGL/WebGPU canvas without `preserveDrawingBuffer` reads back blank outside its own frame — capture during the draw instead.
 
 ### Emitting a server-only bulb