typebulb 0.57.2 → 0.58.0

package/README.md

@@ -192,6 +192,7 @@ everywhere.
 |-----|--------------|:-----------:|
 | `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.setData(chunks)` / `tb.setInsight(v)` | Replace this run's data / insight and get back a link carrying it; the file is untouched | |
 | `tb.theme` | Get/set the light/dark override; `undefined` follows the OS | |
 | `tb.mode` | Runtime mode — `'local'` (CLI) or `'inline'` (sandboxed iframe); `'ide'`/`'published'` on typebulb.com | |
 | `tb.proxy(url)` | Rewrite a CDN URL to load through the host origin (Web Worker / WASM) | |
@@ -507,6 +508,21 @@ the whole file; `put` replaces it blind, knowing neither its size, its format, n
 - **Put**: `typebulb put <file> <kind>=<source>` writes a file's content into that block; `<kind>=-` reads stdin. Several pairs in one command are one atomic write. It replaces the block, appends it when absent, writes nothing when the content is identical, and **removes** the block when the source is empty — the only way to clear one.
 - Only the named block changes; every other block and the frontmatter survive byte-for-byte. A running bulb hot-reloads on a `put`.
 
+## Runtime data (`tb.setData`)
+
+A bulb that computes its own results (a scrape, a batch score, a simulation, a tournament) can swap
+them in as the data it's running on, and get back a link that carries them:
+
+```ts
+const url = await tb.setData(JSON.stringify(results))
+if (url) tb.copy(url)
+```
+
+- `tb.data()` / `tb.json()` return the new chunks for the rest of the page, and the URL's `#tb=` fragment holds them, so reloading or opening that link restores the run. `tb.setInsight(value)` is the same for `tb.insight()`.
+- **Runtime only, never the file.** A reload without the fragment is back on the bulb's own `data.txt`. Two gestures promote a run to source, and no `tb.*` call does: `typebulb put` from the terminal, or `tb.infer()` to raise the modal and press **Save to bulb**, which files whatever the page holds — an LLM call is not needed and the size ceiling does not apply (needs `--trust`).
+- **The link has a size ceiling; the file doesn't.** Around 60KB encoded, so pass what a share needs rather than everything. `undefined` back means it didn't fit (also what an inline bulb gets — no address bar).
+- **Set only what you changed.** An unset slot stays out of the link and falls through to the bulb's own block, so a data-only run doesn't drag a copy of `insight.json` along. Both in one tick is one encode and one link: `tb.setData(d); const url = await tb.setInsight(i)`.
+
 ## 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:

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.57.2
+version: 0.58.0
 ---
 
-> Generated from typebulb v0.57.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.58.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
 
@@ -200,6 +200,7 @@ everywhere.
 |-----|--------------|:-----------:|
 | `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.setData(chunks)` / `tb.setInsight(v)` | Replace this run's data / insight and get back a link carrying it; the file is untouched | |
 | `tb.theme` | Get/set the light/dark override; `undefined` follows the OS | |
 | `tb.mode` | Runtime mode — `'local'` (CLI) or `'inline'` (sandboxed iframe); `'ide'`/`'published'` on typebulb.com | |
 | `tb.proxy(url)` | Rewrite a CDN URL to load through the host origin (Web Worker / WASM) | |
@@ -515,6 +516,21 @@ the whole file; `put` replaces it blind, knowing neither its size, its format, n
 - **Put**: `typebulb put <file> <kind>=<source>` writes a file's content into that block; `<kind>=-` reads stdin. Several pairs in one command are one atomic write. It replaces the block, appends it when absent, writes nothing when the content is identical, and **removes** the block when the source is empty — the only way to clear one.
 - Only the named block changes; every other block and the frontmatter survive byte-for-byte. A running bulb hot-reloads on a `put`.
 
+## Runtime data (`tb.setData`)
+
+A bulb that computes its own results (a scrape, a batch score, a simulation, a tournament) can swap
+them in as the data it's running on, and get back a link that carries them:
+
+```ts
+const url = await tb.setData(JSON.stringify(results))
+if (url) tb.copy(url)
+```
+
+- `tb.data()` / `tb.json()` return the new chunks for the rest of the page, and the URL's `#tb=` fragment holds them, so reloading or opening that link restores the run. `tb.setInsight(value)` is the same for `tb.insight()`.
+- **Runtime only, never the file.** A reload without the fragment is back on the bulb's own `data.txt`. Two gestures promote a run to source, and no `tb.*` call does: `typebulb put` from the terminal, or `tb.infer()` to raise the modal and press **Save to bulb**, which files whatever the page holds — an LLM call is not needed and the size ceiling does not apply (needs `--trust`).
+- **The link has a size ceiling; the file doesn't.** Around 60KB encoded, so pass what a share needs rather than everything. `undefined` back means it didn't fit (also what an inline bulb gets — no address bar).
+- **Set only what you changed.** An unset slot stays out of the link and falls through to the bulb's own block, so a data-only run doesn't drag a copy of `insight.json` along. Both in one tick is one encode and one link: `tb.setData(d); const url = await tb.setInsight(i)`.
+
 ## 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: