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

package/dist/adapters/base.js

@@ -3,6 +3,7 @@ var GeneratorAdapter = class {
   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').

package/dist/adapters/base.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/base.ts"],"names":[],"mappings":";AAoFO,IAAe,mBAAf,MAAgC;AAAA,EAKrC,YAA+B,MAAA,EAA0B;AAA1B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAA2B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiB1D,eAAe,cAAA,EAAgC;AAC7C,IAAA,OAAO,iBAAiB,cAAc,CAAA;AAAA,EACxC;AACF;AAQA,SAAS,iBAAiB,OAAA,EAAyB;AACjD,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,OAAA,CAAQ,GAAG,CAAA;AACtC,EAAA,OAAO,cAAc,CAAA,GAAI,OAAA,CAAQ,KAAA,CAAM,UAAA,GAAa,CAAC,CAAA,GAAI,OAAA;AAC3D;AAKO,SAAS,cAAA,CACd,WACG,WAAA,EACM;AACT,EAAA,IAAI,MAAA,CAAO,QAAQ,OAAO,IAAA;AAC1B,EAAA,IAAI,MAAA,CAAO,YAAY,OAAO,IAAA;AAC9B,EAAA,OAAO,WAAA,CAAY,KAAK,CAAC,IAAA,KAAS,CAAC,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,CAAA;AACvD","file":"base.js","sourcesContent":["// packages/ui-gen/src/adapters/base.ts\n//\n// Abstract base class for all generator adapters.\n\nimport type { McpServerConfig, AgentDefinition } from '@anthropic-ai/claude-agent-sdk';\nimport type { JsonObject } from '@ggui-ai/protocol';\nimport type { AdapterResult, ToolDefinition, ProviderName, AdapterMode } from './types';\n\n/**\n * Core configuration shared by all adapters.\n */\nexport interface AdapterConfig {\n  /** API key for the provider (BYOK) */\n  apiKey?: string;\n  /** Use Bedrock instead of direct API (Claude only) */\n  useBedrock?: boolean;\n  /**\n   * Thinking level for models with extended thinking (Gemini 3.x Flash\n   * via the Interactions API). Mirrors the API's `thinking_level` enum —\n   * `'minimal'` is the floor (the API has NO true off), then `'low'` /\n   * `'medium'` / `'high'`. Omitted → provider default, and Gemini 3.5\n   * Flash defaults thinking ON with no cap — the dominant latency cost\n   * in contract-bounded UI generation. Only the Google adapter consumes\n   * this today.\n   */\n  thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high';\n}\n\n/**\n * Extended configuration for Claude Agent SDK adapter.\n * Separated from AdapterConfig to avoid polluting the base interface\n * with provider-specific concerns.\n */\nexport interface ClaudeSdkConfig extends AdapterConfig {\n  /** Working directory for SDK subprocess */\n  cwd?: string;\n  /** Environment variables for SDK subprocess */\n  env?: Record<string, string>;\n  /** MCP server configs for Claude Agent SDK (keyed by name) */\n  mcpServers?: Record<string, McpServerConfig>;\n  /** Allowed tool names for Claude Agent SDK */\n  allowedTools?: string[];\n  /** Subagent definitions for Claude Agent SDK */\n  agents?: Record<string, AgentDefinition>;\n  /** Custom CLI path for Docker deployments */\n  cliPath?: string;\n  /** stderr callback for debug logging */\n  stderr?: (data: string) => void;\n  /** Progress callback */\n  onProgress?: (event: { type: string; [key: string]: unknown }) => void;\n}\n\n/**\n * Union config type — adapters accept their specific config\n * but the registry uses this union so callers can pass any config.\n */\nexport type AnyAdapterConfig = AdapterConfig | ClaudeSdkConfig;\n\n/**\n * Parameters for a single generation run.\n */\nexport interface GenerateParams {\n  /** System prompt (HOW to build — shared across all SDKs) */\n  systemPrompt: string;\n  /** User prompt (WHAT to build — the specific request) */\n  userPrompt: string;\n  /** Model identifier (provider-native format, e.g., 'claude-sonnet-4-6') */\n  model: string;\n  /** SDK-agnostic tool definitions */\n  tools: ToolDefinition[];\n  /** Maximum agentic loop turns */\n  maxTurns: number;\n  /** Model-specific options (e.g., speed_priority for Claude fast mode) */\n  modelOptions?: JsonObject;\n}\n\n/**\n * Abstract base class for generator adapters.\n *\n * Each adapter wraps a specific provider SDK (Claude, OpenAI, Google)\n * in either raw API mode or agent SDK mode, and implements the tool-use\n * loop using the SDK's native API. All adapters produce the same\n * output format (AdapterResult).\n */\nexport abstract class GeneratorAdapter {\n  abstract readonly provider: ProviderName;\n  abstract readonly mode: AdapterMode;\n  abstract readonly displayName: string;\n\n  constructor(protected readonly config: AnyAdapterConfig) {}\n\n  /**\n   * Run UI generation with the given tools, prompt, and model.\n   */\n  abstract generate(params: GenerateParams): Promise<AdapterResult>;\n\n  /**\n   * Check if this adapter can run (SDK installed, credentials available).\n   */\n  abstract isAvailable(): boolean;\n\n  /**\n   * Map a LiteLLM-format model ID to this SDK's native format.\n   * Default: strips the provider prefix (e.g., 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6').\n   * Override only if the prefix convention differs.\n   */\n  resolveModelId(litellmModelId: string): string {\n    return stripModelPrefix(litellmModelId);\n  }\n}\n\n/**\n * Strip provider prefix from LiteLLM-format model IDs.\n * 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6'\n * 'openai/gpt-5.3-codex' -> 'gpt-5.3-codex'\n * 'gemini/gemini-3-flash-preview' -> 'gemini-3-flash-preview'\n */\nfunction stripModelPrefix(modelId: string): string {\n  const slashIndex = modelId.indexOf('/');\n  return slashIndex >= 0 ? modelId.slice(slashIndex + 1) : modelId;\n}\n\n/**\n * Check if credentials are available from config or environment variables.\n */\nexport function hasCredentials(\n  config: AdapterConfig,\n  ...envVarNames: string[]\n): boolean {\n  if (config.apiKey) return true;\n  if (config.useBedrock) return true;\n  return envVarNames.some((name) => !!process.env[name]);\n}\n"]}
+{"version":3,"sources":["../../src/adapters/base.ts"],"names":[],"mappings":";AAoFO,IAAe,mBAAf,MAAgC;AAAA,EAKrC,YAA+B,MAAA,EAA0B;AAA1B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAA2B;AAAA,EAA3B,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiB/B,eAAe,cAAA,EAAgC;AAC7C,IAAA,OAAO,iBAAiB,cAAc,CAAA;AAAA,EACxC;AACF;AAQA,SAAS,iBAAiB,OAAA,EAAyB;AACjD,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,OAAA,CAAQ,GAAG,CAAA;AACtC,EAAA,OAAO,cAAc,CAAA,GAAI,OAAA,CAAQ,KAAA,CAAM,UAAA,GAAa,CAAC,CAAA,GAAI,OAAA;AAC3D;AAKO,SAAS,cAAA,CACd,WACG,WAAA,EACM;AACT,EAAA,IAAI,MAAA,CAAO,QAAQ,OAAO,IAAA;AAC1B,EAAA,IAAI,MAAA,CAAO,YAAY,OAAO,IAAA;AAC9B,EAAA,OAAO,WAAA,CAAY,KAAK,CAAC,IAAA,KAAS,CAAC,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,CAAA;AACvD","file":"base.js","sourcesContent":["// packages/ui-gen/src/adapters/base.ts\n//\n// Abstract base class for all generator adapters.\n\nimport type { McpServerConfig, AgentDefinition } from '@anthropic-ai/claude-agent-sdk';\nimport type { JsonObject } from '@ggui-ai/protocol';\nimport type { AdapterResult, ToolDefinition, ProviderName, AdapterMode } from './types';\n\n/**\n * Core configuration shared by all adapters.\n */\nexport interface AdapterConfig {\n  /** API key for the provider (BYOK) */\n  apiKey?: string;\n  /** Use Bedrock instead of direct API (Claude only) */\n  useBedrock?: boolean;\n  /**\n   * Thinking level for models with extended thinking (Gemini 3.x Flash\n   * via the Interactions API). Mirrors the API's `thinking_level` enum —\n   * `'minimal'` is the floor (the API has NO true off), then `'low'` /\n   * `'medium'` / `'high'`. Omitted → provider default, and Gemini 3.5\n   * Flash defaults thinking ON with no cap — the dominant latency cost\n   * in contract-bounded UI generation. Only the Google adapter consumes\n   * this today.\n   */\n  thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high';\n}\n\n/**\n * Extended configuration for Claude Agent SDK adapter.\n * Separated from AdapterConfig to avoid polluting the base interface\n * with provider-specific concerns.\n */\nexport interface ClaudeSdkConfig extends AdapterConfig {\n  /** Working directory for SDK subprocess */\n  cwd?: string;\n  /** Environment variables for SDK subprocess */\n  env?: Record<string, string>;\n  /** MCP server configs for Claude Agent SDK (keyed by name) */\n  mcpServers?: Record<string, McpServerConfig>;\n  /** Allowed tool names for Claude Agent SDK */\n  allowedTools?: string[];\n  /** Subagent definitions for Claude Agent SDK */\n  agents?: Record<string, AgentDefinition>;\n  /** Custom CLI path for Docker deployments */\n  cliPath?: string;\n  /** stderr callback for debug logging */\n  stderr?: (data: string) => void;\n  /** Progress callback */\n  onProgress?: (event: { type: string; [key: string]: unknown }) => void;\n}\n\n/**\n * Union config type — adapters accept their specific config\n * but the registry uses this union so callers can pass any config.\n */\nexport type AnyAdapterConfig = AdapterConfig | ClaudeSdkConfig;\n\n/**\n * Parameters for a single generation run.\n */\nexport interface GenerateParams {\n  /** System prompt (HOW to build — shared across all SDKs) */\n  systemPrompt: string;\n  /** User prompt (WHAT to build — the specific request) */\n  userPrompt: string;\n  /** Model identifier (provider-native format, e.g., 'claude-sonnet-4-6') */\n  model: string;\n  /** SDK-agnostic tool definitions */\n  tools: ToolDefinition[];\n  /** Maximum agentic loop turns */\n  maxTurns: number;\n  /** Model-specific options (e.g., speed_priority for Claude fast mode) */\n  modelOptions?: JsonObject;\n}\n\n/**\n * Abstract base class for generator adapters.\n *\n * Each adapter wraps a specific provider SDK (Claude, OpenAI, Google)\n * in either raw API mode or agent SDK mode, and implements the tool-use\n * loop using the SDK's native API. All adapters produce the same\n * output format (AdapterResult).\n */\nexport abstract class GeneratorAdapter {\n  abstract readonly provider: ProviderName;\n  abstract readonly mode: AdapterMode;\n  abstract readonly displayName: string;\n\n  constructor(protected readonly config: AnyAdapterConfig) {}\n\n  /**\n   * Run UI generation with the given tools, prompt, and model.\n   */\n  abstract generate(params: GenerateParams): Promise<AdapterResult>;\n\n  /**\n   * Check if this adapter can run (SDK installed, credentials available).\n   */\n  abstract isAvailable(): boolean;\n\n  /**\n   * Map a LiteLLM-format model ID to this SDK's native format.\n   * Default: strips the provider prefix (e.g., 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6').\n   * Override only if the prefix convention differs.\n   */\n  resolveModelId(litellmModelId: string): string {\n    return stripModelPrefix(litellmModelId);\n  }\n}\n\n/**\n * Strip provider prefix from LiteLLM-format model IDs.\n * 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6'\n * 'openai/gpt-5.3-codex' -> 'gpt-5.3-codex'\n * 'gemini/gemini-3-flash-preview' -> 'gemini-3-flash-preview'\n */\nfunction stripModelPrefix(modelId: string): string {\n  const slashIndex = modelId.indexOf('/');\n  return slashIndex >= 0 ? modelId.slice(slashIndex + 1) : modelId;\n}\n\n/**\n * Check if credentials are available from config or environment variables.\n */\nexport function hasCredentials(\n  config: AdapterConfig,\n  ...envVarNames: string[]\n): boolean {\n  if (config.apiKey) return true;\n  if (config.useBedrock) return true;\n  return envVarNames.some((name) => !!process.env[name]);\n}\n"]}

package/dist/adapters/generation-dispatch.js

@@ -1,6 +1,6 @@
 import Anthropic from '@anthropic-ai/sdk';
 import 'zod';
-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 * as esbuild from 'esbuild';
 import { build } from 'esbuild';
 import fs, { mkdirSync, writeFileSync, unlinkSync, readFileSync, existsSync, rm, createReadStream, createWriteStream } from 'fs';
@@ -30,11 +30,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)
@@ -546,6 +555,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;
       }
@@ -574,6 +585,7 @@ var init_client2 = __esm({
           "X-Title": config.siteName ?? process.env.OPENROUTER_SITE_NAME ?? "ggui"
         };
       }
+      config;
       baseUrl;
       headers;
       /**
@@ -677,7 +689,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") {
@@ -689,7 +701,7 @@ function interactionText(interaction) {
   return text;
 }
 function functionCallSteps(interaction) {
-  return interaction.steps.filter(
+  return (interaction.steps ?? []).filter(
     (s) => s.type === "function_call"
   );
 }
@@ -1790,6 +1802,8 @@ var init_primitives = __esm({
       "EmptyState",
       "Stat",
       "Stepper",
+      "Markdown",
+      "MarkdownInline",
       "Header",
       "Sidebar",
       "CardGrid",
@@ -2236,6 +2250,7 @@ var init_ui_compiler = __esm({
         this.validation = validation;
         this.name = "UiValidationError";
       }
+      validation;
     };
     UiBundleSizeError = class extends Error {
       constructor(size, limit) {
@@ -2244,6 +2259,8 @@ var init_ui_compiler = __esm({
         this.limit = limit;
         this.name = "UiBundleSizeError";
       }
+      size;
+      limit;
     };
   }
 });
@@ -4755,28 +4772,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;
@@ -10071,7 +10095,7 @@ function inspect(contract) {
     );
     actions.push({
       name,
-      tool: a?.tool,
+      nextStep: a?.nextStep,
       example: a?.example,
       scalarKeys,
       allKeys,
@@ -10318,14 +10342,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" };
@@ -10366,7 +10386,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,
@@ -11188,28 +11208,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 = [];
@@ -11766,10 +11775,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.
@@ -12990,7 +12999,7 @@ tighter on display sizes).
 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 = [