typebulb 0.58.0 → 0.58.2

package/dist/dts/tbTypings.js

@@ -9,312 +9,315 @@
  * TypeChecker, and the CLI's emitted typecheck dirs.
  */
 import { modeUnion } from 'typebulb/format';
-const dataAndJson = `
-  /**
-   * Get raw data chunk from the Data tab.
-   * @param index - Chunk index (0-based). Separate chunks with 2 blank lines.
-   */
-  data(index: number): string;
-  /**
-   * Get data chunk parsed as JSON (handles JSON-ish with unquoted keys).
-   * @param index - Chunk index (0-based)
-   * @throws If chunk is not valid JSON/JSON-ish
-   */
+const dataAndJson = `
+  /**
+   * Get raw data chunk from the Data tab.
+   * @param index - Chunk index (0-based). Separate chunks with 2 blank lines.
+   */
+  data(index: number): string;
+  /**
+   * Get data chunk parsed as JSON (handles JSON-ish with unquoted keys).
+   * @param index - Chunk index (0-based)
+   * @throws If chunk is not valid JSON/JSON-ish
+   */
   json<T = unknown>(index: number): T;`;
-const insight = `
-  /**
-   * Get the insight data produced by the inference layer.
-   *
-   * Returns the parsed JSON from insight.json, populated by the inference LLM.
-   * Use a type parameter to get typed access to the insight data.
-   *
-   * @returns The parsed insight JSON, or undefined if no insight is available
-   */
+const insight = `
+  /**
+   * Get the insight data produced by the inference layer.
+   *
+   * Returns the parsed JSON from insight.json, populated by the inference LLM.
+   * Use a type parameter to get typed access to the insight data.
+   *
+   * @returns The parsed insight JSON, or undefined if no insight is available
+   */
   insight<T = unknown>(): T | undefined;`;
 // Runtime-state writers — duals of tb.data()/tb.json() and tb.insight() (TB-State.md).
-const runtimeStateWriters = `
-  /**
-   * Replace the data this run is working on, and get back a link that carries it.
-   *
-   * Updates what \`tb.data()\` / \`tb.json()\` return for the rest of this page, and writes the
-   * result into the URL fragment so the address bar addresses this run. The bulb's source
-   * \`data.txt\` is never touched: a reload without the fragment goes back to the file.
-   *
-   * @param chunks - The new data chunks (a bare string is treated as one chunk)
-   * @returns The shareable URL, or undefined when there is no address bar (inline bulbs) or the
-   *   data is too large to fit a URL. Pass only what a share needs, not necessarily everything.
-   */
-  setData(chunks: string | string[]): Promise<string | undefined>;
-  /**
-   * Replace the insight this run is working on, and get back a link that carries it.
-   *
-   * The \`tb.insight()\` counterpart of \`setData\`, with the same fragment behavior and the same
-   * rule: runtime only, never the bulb's source \`insight.json\`.
-   *
-   * @param value - Any JSON-serializable value
-   * @returns The shareable URL, or undefined (see \`setData\`)
-   */
-  setInsight(value: unknown): Promise<string | undefined>;`;
+const runtimeStateWriters = `
+  /**
+   * Replace the data this run is working on.
+   *
+   * Updates what \`tb.data()\` / \`tb.json()\` return for the rest of this page, and writes the
+   * result into the URL fragment, so the address bar addresses this run and \`tb.url()\` carries
+   * it. The bulb's source \`data.txt\` is never touched: a reload without the fragment goes back
+   * to the file.
+   *
+   * @param chunks - The new data chunks (a bare string is treated as one chunk)
+   * @returns Resolves once the address bar reflects the write. Data too large to fit a URL
+   *   (~60KB encoded) still swaps, but carries no fragment: pass what a share needs, not
+   *   necessarily everything.
+   */
+  setData(chunks: string | string[]): Promise<void>;
+  /**
+   * Replace the insight this run is working on.
+   *
+   * The \`tb.insight()\` counterpart of \`setData\`, with the same fragment behavior and the same
+   * rule: runtime only, never the bulb's source \`insight.json\`.
+   *
+   * @param value - Any JSON-serializable value
+   */
+  setInsight(value: unknown): Promise<void>;`;
 // One options shape, reused by tb.ai() and tb.ai.stream().
-const aiOptions = `options: {
-    messages: Array<{ role: "user" | "assistant"; content: string }>;
-    system?: string;
-    /** Reasoning effort: 0=minimal, 1=low, 2=med, 3=high, 4=xhigh. Mapped to each provider's native mechanism (OpenAI/OpenRouter reasoning effort, Gemini thinking level, Anthropic adaptive thinking). 0 reaches the vendor's explicit off switch, and floors to a little thinking only on always-thinking models. 4 reaches the rung above high where the vendor has one (OpenAI/OpenRouter xhigh, Anthropic max) and clamps to high where it doesn't (Gemini) — never an error. Pin 1 (low) for most work; pick 0 deliberately, when you want the raw model or latency is the constraint. Omitting is NOT off — it buys the model's own default (medium on GPT-5.6), which reasons and bills invisibly. Ignored on the courtesy model, which runs at the level Typebulb sets. */
-    effort?: 0 | 1 | 2 | 3 | 4;
-    provider?: string;
-    model?: string;
-    /** Give the model a web-search tool, billed to the user's key. Off by default; the free model never searches. */
-    webSearch?: boolean;
-    /** Abort the request. On abort the promise rejects / the stream ends. */
-    signal?: AbortSignal;
+const aiOptions = `options: {
+    messages: Array<{ role: "user" | "assistant"; content: string }>;
+    system?: string;
+    /** Reasoning effort: 0=minimal, 1=low, 2=med, 3=high, 4=xhigh. Mapped to each provider's native mechanism (OpenAI/OpenRouter reasoning effort, Gemini thinking level, Anthropic adaptive thinking). 0 reaches the vendor's explicit off switch, and floors to a little thinking only on always-thinking models. 4 reaches the rung above high where the vendor has one (OpenAI/OpenRouter xhigh, Anthropic max) and clamps to high where it doesn't (Gemini) — never an error. Pin 1 (low) for most work; pick 0 deliberately, when you want the raw model or latency is the constraint. Omitting is NOT off — it buys the model's own default (medium on GPT-5.6), which reasons and bills invisibly. Ignored on the courtesy model, which runs at the level Typebulb sets. */
+    effort?: 0 | 1 | 2 | 3 | 4;
+    provider?: string;
+    model?: string;
+    /** Give the model a web-search tool, billed to the user's key. Off by default; the free model never searches. */
+    webSearch?: boolean;
+    /** Abort the request. On abort the promise rejects / the stream ends. */
+    signal?: AbortSignal;
   }`;
 /** A streamed delta from \`tb.ai.stream()\` — a discriminated union, exactly one kind per chunk. */
-const aiChunkType = `
-/** Provider-reported token counts for one call — real usage from the API, never an estimate.
- *  \`output\` is total billed output (reasoning included); \`reasoning\` is the itemized subset where
- *  the provider splits it (OpenAI, Gemini, OpenRouter — Anthropic doesn't); \`cacheRead\` is the
- *  cached subset of \`input\`. */
-type AiUsage = { input: number; output: number; reasoning?: number; cacheRead?: number };
-
-/** A single streamed delta from \`tb.ai.stream()\`. Discriminated by \`kind\`. */
-type AiChunk =
-  | { kind: "text"; text: string }
-  | { kind: "reasoning"; text: string }
-  | { kind: "usage"; usage: AiUsage };
+const aiChunkType = `
+/** Provider-reported token counts for one call — real usage from the API, never an estimate.
+ *  \`output\` is total billed output (reasoning included); \`reasoning\` is the itemized subset where
+ *  the provider splits it (OpenAI, Gemini, OpenRouter — Anthropic doesn't); \`cacheRead\` is the
+ *  cached subset of \`input\`. */
+type AiUsage = { input: number; output: number; reasoning?: number; cacheRead?: number };
+
+/** A single streamed delta from \`tb.ai.stream()\`. Discriminated by \`kind\`. */
+type AiChunk =
+  | { kind: "text"; text: string }
+  | { kind: "reasoning"; text: string }
+  | { kind: "usage"; usage: AiUsage };
 `;
 /** What \`tb.aiAccess()\` answers. Named so bulbs can hold it in state without respelling the union. */
-const aiAccessType = `
-/** What backs \`tb.ai\`: the user's own keys, the quota-limited courtesy model, or nothing. */
-type AiAccess = "own" | "courtesy" | "none";
+const aiAccessType = `
+/** What backs \`tb.ai\`: the user's own keys, the quota-limited courtesy model, or nothing. */
+type AiAccess = "own" | "courtesy" | "none";
 `;
-const ai = `
-  /**
-   * General-purpose AI call. \`tb.ai(opts)\` resolves with the full text; \`tb.ai.stream(opts)\`
-   * returns an async iterable of {@link AiChunk} deltas you consume with \`for await\`.
-   *
-   * @returns Promise resolving to { text, usage? } — \`usage\` is the provider-reported token
-   *   counts ({@link AiUsage}), absent when the provider reported none
-   * @throws On rate limit, network error, or provider error
-   */
-  ai: {
-    (${aiOptions}): Promise<{ text: string; usage?: AiUsage }>;
-    /**
-     * Streaming counterpart of \`tb.ai()\`. Yields \`{ kind: "text" | "reasoning", text }\` deltas
-     * as they arrive, then one final \`{ kind: "usage", usage }\` chunk with the call's token
-     * counts (when the provider reported them); break the loop (or abort \`signal\`) to cancel
-     * and stop the upstream. Match \`kind\` positively — a bare \`else\` branch that assumes
-     * "not reasoning means text" will misread the usage chunk.
-     *
-     * \`kind: "reasoning"\` deltas only arrive when you pass \`effort: 1-4\` AND use a
-     * thinking-capable model; otherwise the stream is \`text\`-only.
-     *
-     * @example
-     * let answer = "";
-     * for await (const c of tb.ai.stream({ messages })) {
-     *   if (c.kind === "text") answer += c.text;
-     * }
-     */
-    stream(${aiOptions}): AsyncIterable<AiChunk>;
+const ai = `
+  /**
+   * General-purpose AI call. \`tb.ai(opts)\` resolves with the full text; \`tb.ai.stream(opts)\`
+   * returns an async iterable of {@link AiChunk} deltas you consume with \`for await\`.
+   *
+   * @returns Promise resolving to { text, usage? } — \`usage\` is the provider-reported token
+   *   counts ({@link AiUsage}), absent when the provider reported none
+   * @throws On rate limit, network error, or provider error
+   */
+  ai: {
+    (${aiOptions}): Promise<{ text: string; usage?: AiUsage }>;
+    /**
+     * Streaming counterpart of \`tb.ai()\`. Yields \`{ kind: "text" | "reasoning", text }\` deltas
+     * as they arrive, then one final \`{ kind: "usage", usage }\` chunk with the call's token
+     * counts (when the provider reported them); break the loop (or abort \`signal\`) to cancel
+     * and stop the upstream. Match \`kind\` positively — a bare \`else\` branch that assumes
+     * "not reasoning means text" will misread the usage chunk.
+     *
+     * \`kind: "reasoning"\` deltas only arrive when you pass \`effort: 1-4\` AND use a
+     * thinking-capable model; otherwise the stream is \`text\`-only.
+     *
+     * @example
+     * let answer = "";
+     * for await (const c of tb.ai.stream({ messages })) {
+     *   if (c.kind === "text") answer += c.text;
+     * }
+     */
+    stream(${aiOptions}): AsyncIterable<AiChunk>;
   };`;
-const models = `
-  /**
-   * Returns AI models available to the current user.
-   * Models are filtered by the user's configured API keys.
-   * If no keys are configured, returns only the courtesy model.
-   */
-  models(): Promise<Array<{
-    /** Provider protocol: "anthropic", "openai", "gemini", "openrouter" */
-    provider: string;
-    /** Model identifier, e.g. "claude-sonnet-4-6" */
-    name: string;
-    /** Human-readable display name, e.g. "Sonnet 4.6" */
-    friendlyName: string;
-    /** Provider display name, e.g. "Anthropic" */
-    providerName: string;
-    /** True on the .env-configured default model (TB_AI_PROVIDER + TB_AI_MODEL); absent otherwise */
-    default?: boolean;
-  }>>;
-  /**
-   * What backs \`tb.ai\` right now:
-   *
-   * - \`'own'\` — the user's own API keys (or their own local model server)
-   * - \`'courtesy'\` — the quota-limited courtesy model, fine for a call or two
-   * - \`'none'\` — no AI at all (the CLI with no keys, an inline bulb)
-   *
-   * A bulb making many AI calls should show a "use your own keys" notice
-   * instead of running unless this is \`'own'\`. Never derive it from
-   * \`tb.mode\` or the length of \`tb.models()\` — which hosts offer a courtesy
-   * model is the host's business and changes without your bulb changing.
-   */
+const models = `
+  /**
+   * Returns AI models available to the current user.
+   * Models are filtered by the user's configured API keys.
+   * If no keys are configured, returns only the courtesy model.
+   */
+  models(): Promise<Array<{
+    /** Provider protocol: "anthropic", "openai", "gemini", "openrouter" */
+    provider: string;
+    /** Model identifier, e.g. "claude-sonnet-4-6" */
+    name: string;
+    /** Human-readable display name, e.g. "Sonnet 4.6" */
+    friendlyName: string;
+    /** Provider display name, e.g. "Anthropic" */
+    providerName: string;
+    /** True on the .env-configured default model (TB_AI_PROVIDER + TB_AI_MODEL); absent otherwise */
+    default?: boolean;
+  }>>;
+  /**
+   * What backs \`tb.ai\` right now:
+   *
+   * - \`'own'\` — the user's own API keys (or their own local model server)
+   * - \`'courtesy'\` — the quota-limited courtesy model, fine for a call or two
+   * - \`'none'\` — no AI at all (the CLI with no keys, an inline bulb)
+   *
+   * A bulb making many AI calls should show a "use your own keys" notice
+   * instead of running unless this is \`'own'\`. Never derive it from
+   * \`tb.mode\` or the length of \`tb.models()\` — which hosts offer a courtesy
+   * model is the host's business and changes without your bulb changing.
+   */
   aiAccess(): Promise<AiAccess>;`;
-const theme = `
-  /**
-   * The bulb's theme override (\`<html data-theme>\`).
-   *
-   * - Get: the current override — \`'dark'\` | \`'light'\`, or \`undefined\` when
-   *   following the OS preference.
-   * - Set \`'dark'\`/\`'light'\` to force and persist it (per-bulb); set
-   *   \`undefined\` to clear the override and follow the OS again.
-   *
-   * Drives \`<html data-theme>\`, so render off \`html[data-theme="…"]\` selectors
-   * (or observe the attribute) rather than reading \`tb.theme\`.
-   */
+const theme = `
+  /**
+   * The bulb's theme override (\`<html data-theme>\`).
+   *
+   * - Get: the current override — \`'dark'\` | \`'light'\`, or \`undefined\` when
+   *   following the OS preference.
+   * - Set \`'dark'\`/\`'light'\` to force and persist it (per-bulb); set
+   *   \`undefined\` to clear the override and follow the OS again.
+   *
+   * Drives \`<html data-theme>\`, so render off \`html[data-theme="…"]\` selectors
+   * (or observe the attribute) rather than reading \`tb.theme\`.
+   */
   theme: 'light' | 'dark' | undefined;`;
-const mode = `
-  /**
-   * The mode this bulb is running in.
-   *
-   * - \`'local'\` — Running via the typebulb CLI
-   * - \`'ide'\` — Running in the typebulb.com editor
-   * - \`'published'\` — Running as a published/standalone bulb on typebulb.com
-   * - \`'inline'\` — Running inline in an agent's transcript, rendered by the mirror
-   *   (sandboxed, client-only: AI, filesystem, and server RPC are unavailable)
-   */
+const mode = `
+  /**
+   * The mode this bulb is running in.
+   *
+   * - \`'local'\` — Running via the typebulb CLI
+   * - \`'ide'\` — Running in the typebulb.com editor
+   * - \`'published'\` — Running as a published/standalone bulb on typebulb.com
+   * - \`'inline'\` — Running inline in an agent's transcript, rendered by the mirror
+   *   (sandboxed, client-only: AI, filesystem, and server RPC are unavailable)
+   */
   mode: ${modeUnion};`;
-const fs = `
-  /**
-   * Local filesystem access (CLI only).
-   *
-   * Relative paths resolve against the bulb's folder (\`tb.dir\` —
-   * \`<bulb-dir>/<filename-stem>/\`, created on demand), so
-   * \`tb.fs.write('results.json')\` lands beside the bulb. \`../\` reaches sibling
-   * bulbs' folders; everything stays confined to the project (the launch cwd).
-   * Throws in ide/published mode.
-   */
-  fs: {
-    /** Read a file as UTF-8 text. Throws if the file is not valid UTF-8 — use readBytes for binary. */
-    read(path: string): Promise<string>;
-    /** Read a file as raw bytes. */
-    readBytes(path: string): Promise<Uint8Array>;
-    /** Write text or raw bytes to a file. Creates parent directories if needed. */
-    write(path: string, content: string | Uint8Array): Promise<boolean>;
+const fs = `
+  /**
+   * Local filesystem access (CLI only).
+   *
+   * Relative paths resolve against the bulb's folder (\`tb.dir\` —
+   * \`<bulb-dir>/<filename-stem>/\`, created on demand), so
+   * \`tb.fs.write('results.json')\` lands beside the bulb. \`../\` reaches sibling
+   * bulbs' folders; everything stays confined to the project (the launch cwd).
+   * Throws in ide/published mode.
+   */
+  fs: {
+    /** Read a file as UTF-8 text. Throws if the file is not valid UTF-8 — use readBytes for binary. */
+    read(path: string): Promise<string>;
+    /** Read a file as raw bytes. */
+    readBytes(path: string): Promise<Uint8Array>;
+    /** Write text or raw bytes to a file. Creates parent directories if needed. */
+    write(path: string, content: string | Uint8Array): Promise<boolean>;
   };`;
-const dir = `
-  /**
-   * The bulb's folder — absolute path to \`<bulb-dir>/<filename-stem>/\`
-   * (or its \`batches/<name>/\` folder when the run is scoped with \`--batch\`).
-   *
-   * For interop only (handing a path to \`server.ts\` or a spawned tool):
-   * \`tb.fs\` already resolves relative paths against it, so bulb code writing
-   * its own files never needs it. CLI only — throws in ide/published/inline mode.
-   */
+const dir = `
+  /**
+   * The bulb's folder — absolute path to \`<bulb-dir>/<filename-stem>/\`
+   * (or its \`batches/<name>/\` folder when the run is scoped with \`--batch\`).
+   *
+   * For interop only (handing a path to \`server.ts\` or a spawned tool):
+   * \`tb.fs\` already resolves relative paths against it, so bulb code writing
+   * its own files never needs it. CLI only — throws in ide/published/inline mode.
+   */
   readonly dir: string;`;
-const clientOnlyMembers = `
-  /**
-   * Async value inspector for tensor-like objects.
-   *
-   * Materializes lazy values (like GPU tensors) and logs them with metadata.
-   * Handles objects with \`.js()\`, \`.data()\`, \`.array()\`, \`.arraySync()\`, etc.
-   *
-   * @remarks
-   * - Always use \`await\` - materialization may be async (GPU→CPU readback)
-   * - Large values are truncated (max 1000 elements)
-   * - Promises are logged as \`[Promise]\` (not awaited - could hang)
-   */
-  dump(...args: any[]): Promise<void>;
-  /**
-   * Trigger inference to generate new insight data.
-   *
-   * Opens a confirmation modal showing the data to be analyzed, then streams
-   * the inference result. On success, updates the insight so subsequent
-   * \`tb.insight()\` calls return the new value.
-   *
-   * @param opts - Options for inference
-   * @param opts.data - Data to pre-populate in the modal (string or array of strings). If omitted, modal opens with empty textarea for user to paste.
-   * @returns Promise that resolves with the parsed insight JSON
-   * @throws If inference is already in progress, or on network/parse/rate limit errors
-   */
-  infer<T = unknown>(opts?: { data?: string | string[] }): Promise<T>;
-  /**
-   * Proxy a CDN URL through the sandbox origin for Web Worker/WASM same-origin loading.
-   *
-   * In the sandbox, prepends \`/proxy/\` so the URL is served from the same origin.
-   * Outside the sandbox (exported HTML, CLI), returns the URL unchanged.
-   *
-   * @param url - Full HTTPS URL to an allowlisted CDN (esm.sh, unpkg.com, cdn.jsdelivr.net, cdnjs.cloudflare.com)
-   * @returns The proxied URL (sandbox) or the original URL (standalone/CLI)
-   */
-  proxy(url: string): string;
-  /**
-   * Copy text to clipboard.
-   * Must be called synchronously within a user gesture (click/keydown).
-   * @returns true if successful, false otherwise
-   */
-  copy(text: string): Promise<boolean>;
-  /**
-   * Get the canonical URL of this bulb.
-   *
-   * Returns the parent typebulb.com URL (including path, query, and \`#tb=\` fragment),
-   * resolving correctly from inside the cross-origin sandbox iframe.
-   * Use this instead of \`location.href\` or \`document.referrer\`.
-   *
-   * @returns The full canonical URL
-   */
+const clientOnlyMembers = `
+  /**
+   * Async value inspector for tensor-like objects.
+   *
+   * Materializes lazy values (like GPU tensors) and logs them with metadata.
+   * Handles objects with \`.js()\`, \`.data()\`, \`.array()\`, \`.arraySync()\`, etc.
+   *
+   * @remarks
+   * - Always use \`await\` - materialization may be async (GPU→CPU readback)
+   * - Large values are truncated (max 1000 elements)
+   * - Promises are logged as \`[Promise]\` (not awaited - could hang)
+   */
+  dump(...args: any[]): Promise<void>;
+  /**
+   * Trigger inference to generate new insight data.
+   *
+   * Opens a confirmation modal showing the data to be analyzed, then streams
+   * the inference result. On success, updates the insight so subsequent
+   * \`tb.insight()\` calls return the new value.
+   *
+   * @param opts - Options for inference
+   * @param opts.data - Data to pre-populate in the modal (string or array of strings). If omitted, modal opens with empty textarea for user to paste.
+   * @returns Promise that resolves with the parsed insight JSON
+   * @throws If inference is already in progress, or on network/parse/rate limit errors
+   */
+  infer<T = unknown>(opts?: { data?: string | string[] }): Promise<T>;
+  /**
+   * Proxy a CDN URL through the sandbox origin for Web Worker/WASM same-origin loading.
+   *
+   * In the sandbox, prepends \`/proxy/\` so the URL is served from the same origin.
+   * Outside the sandbox (exported HTML, CLI), returns the URL unchanged.
+   *
+   * @param url - Full HTTPS URL to an allowlisted CDN (esm.sh, unpkg.com, cdn.jsdelivr.net, cdnjs.cloudflare.com)
+   * @returns The proxied URL (sandbox) or the original URL (standalone/CLI)
+   */
+  proxy(url: string): string;
+  /**
+   * Copy text to clipboard.
+   * Must be called synchronously within a user gesture (click/keydown).
+   * @returns true if successful, false otherwise
+   */
+  copy(text: string): Promise<boolean>;
+  /**
+   * Get the canonical URL of this bulb.
+   *
+   * Returns the parent typebulb.com URL (including query and \`#tb=\` fragment), resolving
+   * correctly from inside the cross-origin sandbox iframe. That is the published \`/full\` page
+   * even while authoring in the IDE, because it is the link someone you send it to can open.
+   * Locally it is the served localhost URL. Use this instead of \`location.href\` or
+   * \`document.referrer\`.
+   *
+   * @returns The full canonical URL
+   */
   url(): Promise<string>;`;
-const onMessage = `
-  /**
-   * Subscribe to a value pushed from the terminal via \`typebulb send <file> [message]\`.
-   *
-   * The dual of \`tb.log\` (data out): a value sent *in* from the CLI, no \`--trust\` required.
-   * Use it to start expensive work on demand instead of on load — e.g. \`tb.onMessage(() => start())\`
-   * — so hot reloads don't re-trigger it while you edit, and an agent kicks off one run when ready.
-   *
-   * The message is the JSON-parsed value of what \`send\` was given (or the raw string if it isn't
-   * JSON; \`undefined\` for a bare \`typebulb send <file>\`). A non-\`undefined\` return value (awaited)
-   * becomes the reply \`send --wait\` prints on stdout — JSON-serializable, at most one handler
-   * replying — the structured read-back for self-tests. Returns an unsubscribe function. Inert in
-   * an inline bulb (no sender) — the handler is registered but never fires.
-   *
-   * @param handler - Called with each pushed message; may return a JSON-serializable reply.
-   * @returns An unsubscribe function.
-   */
+const onMessage = `
+  /**
+   * Subscribe to a value pushed from the terminal via \`typebulb send <file> [message]\`.
+   *
+   * The dual of \`tb.log\` (data out): a value sent *in* from the CLI, no \`--trust\` required.
+   * Use it to start expensive work on demand instead of on load — e.g. \`tb.onMessage(() => start())\`
+   * — so hot reloads don't re-trigger it while you edit, and an agent kicks off one run when ready.
+   *
+   * The message is the JSON-parsed value of what \`send\` was given (or the raw string if it isn't
+   * JSON; \`undefined\` for a bare \`typebulb send <file>\`). A non-\`undefined\` return value (awaited)
+   * becomes the reply \`send --wait\` prints on stdout — JSON-serializable, at most one handler
+   * replying — the structured read-back for self-tests. Returns an unsubscribe function. Inert in
+   * an inline bulb (no sender) — the handler is registered but never fires.
+   *
+   * @param handler - Called with each pushed message; may return a JSON-serializable reply.
+   * @returns An unsubscribe function.
+   */
   onMessage(handler: (message: any) => unknown): () => void;`;
-const log = `
-  /**
-   * Print to the CLI's stdout — the bulb's log channel, read back with \`typebulb logs <file>\`.
-   *
-   * Ungated: needs no \`server.ts\` block and no \`--trust\`, so a Restricted client-only bulb can
-   * instrument itself. Args cross to the CLI as JSON; where no CLI serves the page (web, inline,
-   * or a transport failure) it falls back to the browser console. Works in \`server.ts\` too (same
-   * as \`console.log\` there).
-   */
+const log = `
+  /**
+   * Print to the CLI's stdout — the bulb's log channel, read back with \`typebulb logs <file>\`.
+   *
+   * Ungated: needs no \`server.ts\` block and no \`--trust\`, so a Restricted client-only bulb can
+   * instrument itself. Args cross to the CLI as JSON; where no CLI serves the page (web, inline,
+   * or a transport failure) it falls back to the browser console. Works in \`server.ts\` too (same
+   * as \`console.log\` there).
+   */
   log(...args: any[]): void;`;
-const clientServerProxy = `
-  /**
-   * Server-side function proxy.
-   *
-   * In the CLI, calls exported functions from the \`**server.ts**\` section.
-   *
-   * A normal export is awaited for its result (\`await tb.server.fn()\`). An \`async function*\`
-   * export streams: \`for await (const chunk of tb.server.gen())\`. The call object supports both;
-   * break the \`for await\` to cancel and tear down the server generator.
-   */
+const clientServerProxy = `
+  /**
+   * Server-side function proxy.
+   *
+   * In the CLI, calls exported functions from the \`**server.ts**\` section.
+   *
+   * A normal export is awaited for its result (\`await tb.server.fn()\`). An \`async function*\`
+   * export streams: \`for await (const chunk of tb.server.gen())\`. The call object supports both;
+   * break the \`for await\` to cancel and tear down the server generator.
+   */
   server: Record<string, (...args: any[]) => Promise<any> & AsyncIterable<any>>;`;
 /** Typebulb globals available in browser-side code (code.tsx). */
-export const clientTbTypings = `${aiChunkType}${aiAccessType}
-/**
- * Typebulb utilities namespace.
- * Type \`tb.\` to discover available helpers.
- */
-declare const tb: {${dataAndJson}${clientOnlyMembers}${insight}${runtimeStateWriters}${log}${clientServerProxy}${onMessage}${ai}${fs}${dir}${models}${theme}${mode}
-};
+export const clientTbTypings = `${aiChunkType}${aiAccessType}
+/**
+ * Typebulb utilities namespace.
+ * Type \`tb.\` to discover available helpers.
+ */
+declare const tb: {${dataAndJson}${clientOnlyMembers}${insight}${runtimeStateWriters}${log}${clientServerProxy}${onMessage}${ai}${fs}${dir}${models}${theme}${mode}
+};
 `;
-const serverLog = `
-  /**
-   * Print to the CLI's stdout — the same channel as \`console.log\` here (the server's console IS
-   * the bulb's log). One log verb across blocks: page-side \`tb.log\` reaches this same stdout.
-   */
+const serverLog = `
+  /**
+   * Print to the CLI's stdout — the same channel as \`console.log\` here (the server's console IS
+   * the bulb's log). One log verb across blocks: page-side \`tb.log\` reaches this same stdout.
+   */
   log(...args: any[]): void;`;
 /** Typebulb globals available in Node-side code (server.ts).
  *  Only what carries a bulb-specific rule Node can't know — tb.ai, tb.fs, tb.dir (TB-FS.md);
  *  plus the tb.log uniformity exception (serverTb.ts). The browser-only helpers are intentionally
  *  absent. Must match serverTb.ts's runtime surface. */
-export const serverTbTypings = `${aiChunkType}${aiAccessType}
-/**
- * Typebulb utilities namespace (server-side).
- * Type \`tb.\` to discover available helpers.
- */
-declare const tb: {${serverLog}${ai}${fs}${dir}${models}${mode}
-};
+export const serverTbTypings = `${aiChunkType}${aiAccessType}
+/**
+ * Typebulb utilities namespace (server-side).
+ * Type \`tb.\` to discover available helpers.
+ */
+declare const tb: {${serverLog}${ai}${fs}${dir}${models}${mode}
+};
 `;
 //# sourceMappingURL=tbTypings.js.map

package/dist/dts/tbTypings.js.map

@@ -1 +1 @@
-{"version":3,"file":"tbTypings.js","sourceRoot":"","sources":["../../dts/src/tbTypings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,WAAW,GAAG;;;;;;;;;;;uCAWmB,CAAA;AAEvC,MAAM,OAAO,GAAG;;;;;;;;;yCASyB,CAAA;AAEzC,uFAAuF;AACvF,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;2DAsB+B,CAAA;AAE3D,2DAA2D;AAC3D,MAAM,SAAS,GAAG;;;;;;;;;;;IAWd,CAAA;AAEJ,oGAAoG;AACpG,MAAM,WAAW,GAAG;;;;;;;;;;;;CAYnB,CAAA;AAED,wGAAwG;AACxG,MAAM,YAAY,GAAG;;;CAGpB,CAAA;AAED,MAAM,EAAE,GAAG;;;;;;;;;;OAUJ,SAAS;;;;;;;;;;;;;;;;;aAiBH,SAAS;KACjB,CAAA;AAEL,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCA8BkB,CAAA;AAEjC,MAAM,KAAK,GAAG;;;;;;;;;;;;uCAYyB,CAAA;AAEvC,MAAM,IAAI,GAAG;;;;;;;;;;UAUH,SAAS,GAAG,CAAA;AAEtB,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;KAiBN,CAAA;AAEL,MAAM,GAAG,GAAG;;;;;;;;;wBASY,CAAA;AAExB,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAmDA,CAAA;AAE1B,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;6DAiB2C,CAAA;AAE7D,MAAM,GAAG,GAAG;;;;;;;;;6BASiB,CAAA;AAE7B,MAAM,iBAAiB,GAAG;;;;;;;;;;iFAUuD,CAAA;AAEjF,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,WAAW,GAAG,YAAY;;;;;qBAKvC,WAAW,GAAG,iBAAiB,GAAG,OAAO,GAAG,mBAAmB,GAAG,GAAG,GAAG,iBAAiB,GAAG,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI;;CAEjK,CAAA;AAED,MAAM,SAAS,GAAG;;;;;6BAKW,CAAA;AAE7B;;;wDAGwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,WAAW,GAAG,YAAY;;;;;qBAKvC,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,MAAM,GAAG,IAAI;;CAE7D,CAAA"}
+{"version":3,"file":"tbTypings.js","sourceRoot":"","sources":["../../dts/src/tbTypings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,WAAW,GAAG;;;;;;;;;;;uCAWmB,CAAA;AAEvC,MAAM,OAAO,GAAG;;;;;;;;;yCASyB,CAAA;AAEzC,uFAAuF;AACvF,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;6CAuBiB,CAAA;AAE7C,2DAA2D;AAC3D,MAAM,SAAS,GAAG;;;;;;;;;;;IAWd,CAAA;AAEJ,oGAAoG;AACpG,MAAM,WAAW,GAAG;;;;;;;;;;;;CAYnB,CAAA;AAED,wGAAwG;AACxG,MAAM,YAAY,GAAG;;;CAGpB,CAAA;AAED,MAAM,EAAE,GAAG;;;;;;;;;;OAUJ,SAAS;;;;;;;;;;;;;;;;;aAiBH,SAAS;KACjB,CAAA;AAEL,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCA8BkB,CAAA;AAEjC,MAAM,KAAK,GAAG;;;;;;;;;;;;uCAYyB,CAAA;AAEvC,MAAM,IAAI,GAAG;;;;;;;;;;UAUH,SAAS,GAAG,CAAA;AAEtB,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;KAiBN,CAAA;AAEL,MAAM,GAAG,GAAG;;;;;;;;;wBASY,CAAA;AAExB,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAqDA,CAAA;AAE1B,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;6DAiB2C,CAAA;AAE7D,MAAM,GAAG,GAAG;;;;;;;;;6BASiB,CAAA;AAE7B,MAAM,iBAAiB,GAAG;;;;;;;;;;iFAUuD,CAAA;AAEjF,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,WAAW,GAAG,YAAY;;;;;qBAKvC,WAAW,GAAG,iBAAiB,GAAG,OAAO,GAAG,mBAAmB,GAAG,GAAG,GAAG,iBAAiB,GAAG,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI;;CAEjK,CAAA;AAED,MAAM,SAAS,GAAG;;;;;6BAKW,CAAA;AAE7B;;;wDAGwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,WAAW,GAAG,YAAY;;;;;qBAKvC,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,MAAM,GAAG,IAAI;;CAE7D,CAAA"}