@ggui-ai/ui-gen 0.5.0-rc.2 → 0.6.0

package/dist/advanced/index.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import * as esbuild2 from 'esbuild';
 import { build } from 'esbuild';
 import Anthropic from '@anthropic-ai/sdk';
-import { classifyUi, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, listContractGadgets, HOOK_NAME_RE, STDLIB_GADGETS_PACKAGE, resolveAppGadgets } from '@ggui-ai/protocol';
+import { classifyUi, MODEL_REGISTRY, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, listContractGadgets, HOOK_NAME_RE, STDLIB_GADGETS_PACKAGE, resolveAppGadgets } from '@ggui-ai/protocol';
 import fs, { mkdirSync, writeFileSync, unlinkSync, readFileSync, existsSync, rm, createReadStream, createWriteStream } from 'fs';
 import { contentHash } from '@ggui-ai/protocol/content-hash';
 import ts7 from 'typescript';
@@ -32,11 +32,20 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -76,6 +85,7 @@ var init_base = __esm({
       constructor(config) {
         this.config = config;
       }
+      config;
       /**
        * Map a LiteLLM-format model ID to this SDK's native format.
        * Default: strips the provider prefix (e.g., 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6').
@@ -1147,6 +1157,8 @@ var init_types = __esm({
         this.code = code;
         this.name = "OpenRouterError";
       }
+      status;
+      code;
       get isTransient() {
         return this.status === 408 || this.status === 429 || this.status === 502 || this.status === 503;
       }
@@ -1175,6 +1187,7 @@ var init_client2 = __esm({
           "X-Title": config.siteName ?? process.env.OPENROUTER_SITE_NAME ?? "ggui"
         };
       }
+      config;
       baseUrl;
       headers;
       /**
@@ -1438,6 +1451,8 @@ var init_primitives = __esm({
       "EmptyState",
       "Stat",
       "Stepper",
+      "Markdown",
+      "MarkdownInline",
       "Header",
       "Sidebar",
       "CardGrid",
@@ -1884,6 +1899,7 @@ var init_ui_compiler = __esm({
         this.validation = validation;
         this.name = "UiValidationError";
       }
+      validation;
     };
     UiBundleSizeError = class extends Error {
       constructor(size, limit) {
@@ -1892,6 +1908,8 @@ var init_ui_compiler = __esm({
         this.limit = limit;
         this.name = "UiBundleSizeError";
       }
+      size;
+      limit;
     };
   }
 });
@@ -4093,7 +4111,7 @@ function errorSummary(e) {
 }
 function interactionText(interaction) {
   let text = "";
-  for (const step of interaction.steps) {
+  for (const step of interaction.steps ?? []) {
     if (step.type === "model_output") {
       for (const content of step.content ?? []) {
         if (content.type === "text") {
@@ -4105,7 +4123,7 @@ function interactionText(interaction) {
   return text;
 }
 function functionCallSteps(interaction) {
-  return interaction.steps.filter(
+  return (interaction.steps ?? []).filter(
     (s) => s.type === "function_call"
   );
 }
@@ -6049,28 +6067,35 @@ var init_llm_evaluator = __esm({
 // src/evaluation/cost-tracker.ts
 var cost_tracker_exports = {};
 __export(cost_tracker_exports, {
-  CostTracker: () => CostTracker
+  CostTracker: () => CostTracker,
+  pricePer1k: () => pricePer1k
 });
-var PRICE_PER_1K_TOKENS, CostTracker;
+function resolveRegistryId(model) {
+  const keys = Object.keys(MODEL_REGISTRY);
+  if (keys.includes(model)) return model;
+  const bySuffix = keys.find((id) => id.endsWith(`/${model}`));
+  if (bySuffix) return bySuffix;
+  const undated = model.replace(/-\d{8}$/, "");
+  return keys.find((id) => id.endsWith(`/${undated}`)) ?? null;
+}
+function pricePer1k(model) {
+  const id = resolveRegistryId(model);
+  if (id === null) return FALLBACK_PER_1K;
+  const { costs } = MODEL_REGISTRY[id];
+  return { input: costs.inputPer1M / 1e3, output: costs.outputPer1M / 1e3 };
+}
+var FALLBACK_PER_1K, CostTracker;
 var init_cost_tracker = __esm({
   "src/evaluation/cost-tracker.ts"() {
-    PRICE_PER_1K_TOKENS = {
-      "claude-sonnet-4-6": { input: 3e-3, output: 0.015 },
-      "claude-haiku-4-5-20251001": { input: 8e-4, output: 4e-3 },
-      "gemini-3-flash-preview": { input: 1e-4, output: 4e-4 },
-      // Gemini 3.5 Flash-Lite — $0.30/$2.50 per MTok (ai.google.dev/gemini-api/docs/pricing).
-      "gemini-3.5-flash-lite": { input: 3e-4, output: 25e-4 },
-      "gpt-5.4-mini": { input: 3e-4, output: 12e-4 },
-      // $1.00 in / $6.00 out per MTok (OpenAI list, 2026-07) → per-1K.
-      "gpt-5.6-luna": { input: 1e-3, output: 6e-3 }
-    };
+    FALLBACK_PER_1K = { input: 3e-3, output: 0.015 };
     CostTracker = class {
       constructor(maxBudget) {
         this.maxBudget = maxBudget;
       }
+      maxBudget;
       totalCost = 0;
       record(model, inputTokens, outputTokens) {
-        const prices = PRICE_PER_1K_TOKENS[model] ?? { input: 3e-3, output: 0.015 };
+        const prices = pricePer1k(model);
         const cost = inputTokens / 1e3 * prices.input + outputTokens / 1e3 * prices.output;
         this.totalCost += cost;
         return cost;
@@ -12368,7 +12393,7 @@ function inspect(contract) {
     );
     actions.push({
       name,
-      tool: a?.tool,
+      nextStep: a?.nextStep,
       example: a?.example,
       scalarKeys,
       allKeys,
@@ -12615,14 +12640,10 @@ function inferLayout(s, prompt, blueprint) {
 var DRAG_RX = /\b(drag|drop|dragging|draggable)\b/i;
 var SWIPE_RX = /\b(swipe|swipes|gesture\s*stack)\b/i;
 var KEYBOARD_RX = /\b(keyboard\s*shortcut|hotkey|keystroke|kbd)\b/i;
-function inferWriteTrigger(s, prompt, blueprint) {
+function inferWriteTrigger(s, prompt) {
   if (s.actions.length === 0) {
     return { value: "click", source: "default" };
   }
-  if (blueprint?.mechanic === "drag")
-    return { value: "drag", source: "blueprint" };
-  if (blueprint?.mechanic === "swipe")
-    return { value: "swipe", source: "blueprint" };
   if (DRAG_RX.test(prompt)) return { value: "drag", source: "prompt" };
   if (SWIPE_RX.test(prompt)) return { value: "swipe", source: "prompt" };
   if (KEYBOARD_RX.test(prompt)) return { value: "keystroke", source: "prompt" };
@@ -12663,7 +12684,7 @@ function classifyAxes(input) {
   const fetch2 = inferFetch(s);
   const render = inferRender(s, prompt, blueprint);
   const layout = inferLayout(s, prompt, blueprint);
-  const writeTrigger = inferWriteTrigger(s, prompt, blueprint);
+  const writeTrigger = inferWriteTrigger(s, prompt);
   const tooling = inferTooling(s);
   const vector = {
     render: render.value,
@@ -13485,28 +13506,17 @@ function inferTypeFromExample(example) {
 }
 function generateBoilerplate(_userPrompt, contract, shellType, screen, composedSections, appGadgets) {
   const propsFields = [];
-  const propsData = contract?.propsSpec;
-  const propsProperties = propsData?.properties ?? propsData ?? {};
-  for (const [key, value] of Object.entries(propsProperties)) {
-    if (typeof value === "object" && value !== null) {
-      const spec = value;
-      const schema = spec.schema;
-      const required = spec.required !== false;
-      const nullable = schema?.nullable === true;
-      const tsType = schema ? (
-        // JsonSchema extends JsonObject, so this is a plain structural
-        // downcast (no `unknown` erasure) of already-shaped contract data.
-        jsonSchemaTypeToTs(schema)
-      ) : "unknown";
-      const fullType = nullable ? `${tsType} | null` : tsType;
-      const parts = [];
-      if (spec.description) parts.push(String(spec.description));
-      if (spec.default !== void 0) parts.push(`(default: ${JSON.stringify(spec.default)})`);
-      const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
-      propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
-    } else {
-      propsFields.push(`  ${key}: ${typeof value === "string" ? value : "unknown"};`);
-    }
+  const propsProperties = contract?.propsSpec?.properties ?? {};
+  for (const [key, entry] of Object.entries(propsProperties)) {
+    const required = entry.required !== false;
+    const nullable = entry.schema.nullable === true;
+    const tsType = jsonSchemaTypeToTs(entry.schema);
+    const fullType = nullable ? `${tsType} | null` : tsType;
+    const parts = [];
+    if (entry.description) parts.push(entry.description);
+    if (entry.default !== void 0) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
+    propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }
   const actionTypeAliases = [];
   const actionHookCalls = [];
@@ -14063,10 +14073,10 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 Props arrive via \`ggui_update\` and may be partial on first render. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
 
-- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.history, stream.latest, etc.
+- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
 - **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
 - **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
-- **Stream latest**: \`useStream\` returns \`{latest: T | undefined, history: T[]}\`. The default \`history\` is \`[]\` so it's safe to map; \`latest\` is undefined until the first frame arrives \u2014 guard before reading \`.foo\`.
+- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
 - **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
 - **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
 - **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
@@ -14963,7 +14973,7 @@ init_policy2();
 init_validation();
 
 // src/tools/get-wire.ts
-var WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate \u2014 use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 \u2014 agentTools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget \u2014 no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse \u2014 advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced \u2014 the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** \u2014 wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit \u2014 it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` \u2014 this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload \u2014 matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded \u2014 auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly \u2014 it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider \u2014 the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` \u2014 `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` \u2014 same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases \u2014 no call-site break.\n\nThe contract's `agentTools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe \u2014 `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for `useAction`'s task-scoped duplicate-dispatch suppression. Fires alongside the always-on `console.warn` whenever the runtime coalesces a same-(name, payload) re-dispatch within one event-loop task \u2014 the nested- interactive double-fire backstop.  Reachability constraint: the first-party renderers do NOT set this field \u2014 `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` and mounts `GguiWireProvider` itself. On every first-party render path the `console.warn` is the sole suppression signal. |\n";
+var WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate \u2014 use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 \u2014 agentCapabilities.tools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget \u2014 no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse \u2014 advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced \u2014 the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** \u2014 wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit \u2014 it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` \u2014 this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload \u2014 matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded \u2014 auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly \u2014 it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider \u2014 the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` \u2014 `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` \u2014 same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases \u2014 no call-site break.\n\nThe contract's `agentCapabilities.tools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe \u2014 `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for `useAction`'s task-scoped duplicate-dispatch suppression. Fires alongside the always-on `console.warn` whenever the runtime coalesces a same-(name, payload) re-dispatch within one event-loop task \u2014 the nested- interactive double-fire backstop.  Reachability constraint: the first-party renderers do NOT set this field \u2014 `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` and mounts `GguiWireProvider` itself. On every first-party render path the `console.warn` is the sole suppression signal. |\n";
 
 // src/harness/pitfalls.ts
 var PITFALLS = [