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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.5.0-rc.2",
+  "version": "0.6.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -188,9 +188,9 @@
     "puppeteer-core": "^24.40.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.5.0-rc.2",
-    "@ggui-ai/protocol": "0.5.0-rc.2",
-    "@ggui-ai/project-config": "0.5.0-rc.2"
+    "@ggui-ai/mcp-server-core": "0.6.0",
+    "@ggui-ai/project-config": "0.6.0",
+    "@ggui-ai/protocol": "0.6.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -229,11 +229,11 @@
     "openai": "^6.29.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.5.0-rc.2",
-    "@ggui-ai/gadgets": "0.5.0-rc.2",
-    "@ggui-ai/sandbox": "0.5.0-rc.2",
-    "@ggui-ai/ui-visual-tester": "0.5.0-rc.2",
-    "@ggui-ai/wire": "0.5.0-rc.2"
+    "@ggui-ai/design": "0.6.0",
+    "@ggui-ai/gadgets": "0.6.0",
+    "@ggui-ai/sandbox": "0.6.0",
+    "@ggui-ai/wire": "0.6.0",
+    "@ggui-ai/ui-visual-tester": "0.6.0"
   },
   "devDependencies": {
     "@google/adk": "^0.5.0",
@@ -248,9 +248,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.5.0-rc.2",
-    "@ggui-ai/project-config": "0.5.0-rc.2",
-    "@ggui-ai/protocol": "0.5.0-rc.2"
+    "@ggui-ai/mcp-server-core": "0.6.0",
+    "@ggui-ai/protocol": "0.6.0",
+    "@ggui-ai/project-config": "0.6.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/blueprint-validator.ts

@@ -187,7 +187,7 @@ function selfCheckTier(source: string, contract?: DataContract): SelfCheckResult
   }
 
   if (contract?.propsSpec) {
-    const propNames = Object.keys((contract.propsSpec as { shape?: Record<string, unknown> }).shape ?? {});
+    const propNames = Object.keys(contract.propsSpec.properties ?? {});
     for (const propName of propNames) {
       if (!source.includes(propName)) {
         warnings.push({

package/src/boilerplate/generate.ts

@@ -30,7 +30,6 @@ import type {
   ContextSpec,
   DataContract,
   JsonObject,
-  JsonSchema,
   JsonValue,
   StreamSpec,
 } from "@ggui-ai/protocol";
@@ -185,40 +184,30 @@ export function generateBoilerplate(
   appGadgets?: readonly GadgetDescriptor[],
 ): string {
   // ── Props interface from data contract (data only — NO action callbacks) ──
-  // Contract shape: { properties: { fieldName: { schema, required, description } } }
+  // Contract shape (PropsSpec is ALWAYS the wrapper — never flat):
+  // { properties: { fieldName: { schema, required, description } } }
   const propsFields: string[] = [];
-  const propsData = contract?.propsSpec as JsonObject | undefined;
-  // Unwrap: contract.propsSpec may be { properties: { ... } } or flat { field: spec }
-  const propsProperties = (propsData?.properties as JsonObject) ?? propsData ?? {};
-  for (const [key, value] of Object.entries(propsProperties)) {
-    if (typeof value === "object" && value !== null) {
-      const spec = value as JsonObject;
-      const schema = spec.schema as JsonObject | undefined;
-      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 as JsonSchema)
-        : "unknown";
-      const fullType = nullable ? `${tsType} | null` : tsType;
-      // Build comment: description + default value hint
-      const parts: string[] = [];
-      if (spec.description) parts.push(String(spec.description));
-      if (spec.default !== undefined) 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;
+    // Build comment: description + default value hint
+    const parts: string[] = [];
+    if (entry.description) parts.push(entry.description);
+    if (entry.default !== undefined) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    const desc = parts.length > 0 ? ` // ${parts.join(' ')}` : "";
+    propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }
 
   // ── Actions (useAction hooks — fire-and-forget to agent) ──
-  // Contract shape: { actionSpec: { actionName: { label, description, schema?, example?, tool? } } }
-  // ActionEntry.dispatch: when `kind === 'tool'`, this action routes to an
-  // MCP tool registered on this server (synchronous dispatch). Wire useAction
-  // normally — the platform handles tool dispatch. The tool name is
-  // informational (use it for button labels, icons, copy).
+  // Contract shape: { actionSpec: { actionName: { label, description, schema?, example?, nextStep? } } }
+  // ActionEntry.nextStep: optional hint naming the MCP tool the AGENT
+  // should invoke on its next turn after this action fires. Actions have
+  // exactly one routing target — the agent; there is NO synchronous
+  // server-side dispatch. The name is informational here (use it for
+  // button labels, icons, copy).
   const actionTypeAliases: string[] = [];
   const actionHookCalls: string[] = [];
   const actionReturnFields: string[] = [];

package/src/boilerplate/system-prompt.ts

@@ -349,10 +349,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 — 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 — 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 — 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 — 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 — 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="…" description="…" />\` — a region that renders nothing when empty looks broken to the user.

package/src/check/extract-wire-calls.ts

@@ -212,8 +212,8 @@ export function extractWireImports(code: string): ReadonlySet<string> {
  * slots. Contract-key typing matches the `@ggui-ai/protocol` canonical
  * flat-map shape.
  *
- * `agentTools` and `clientCapabilities` are NOT enumerated:
- *   - `agentTools` is a catalog the AGENT invokes (no component hook).
+ * `agentCapabilities.tools` and `clientCapabilities` are NOT enumerated:
+ *   - `agentCapabilities.tools` is a catalog the AGENT invokes (no component hook).
  *     Cross-references surface via `actionSpec[*].nextStep` and
  *     `streamSpec[*].source.tool`, already covered by `action` / `stream`.
  *   - `clientCapabilities` are declarations of browser-capability hooks

package/src/classifier/axes.ts

@@ -89,9 +89,9 @@ export type LayoutShape =
 // =============================================================================
 
 export type ToolingShape =
-  | "none"    // contract has no agentCapabilities.tools and no clientCapabilities.libraries
+  | "none"    // contract has no agentCapabilities.tools and no clientCapabilities.gadgets
   | "wired"   // agentCapabilities.tools present (catalog referenced via actionSpec.nextStep / streamSpec.source.tool)
-  | "client"  // clientCapabilities.libraries present (browser-capability hooks the component imports)
+  | "client"  // clientCapabilities.gadgets present (browser-capability hooks the component imports)
   | "both";   // contract exposes both catalogs
 
 // =============================================================================

package/src/classifier/classifier.ts

@@ -23,7 +23,7 @@ export interface ClassifyInput {
   contract: ClassifierInput;
   prompt?: string;
   blueprint?: {
-    mechanic?: string;
+    mechanic?: import("@ggui-ai/protocol").ScreenMechanic;
     layoutHint?: string;
   };
 }
@@ -39,7 +39,7 @@ export function classifyAxes(input: ClassifyInput): Classification {
   const fetch = 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: AxisVector = {

package/src/classifier/infer-layout.ts

@@ -4,7 +4,7 @@ import type { AxisSource, LayoutShape } from "./axes";
 import type { ContractSignals } from "./inspect";
 
 interface BlueprintHint {
-  mechanic?: string;
+  mechanic?: import("@ggui-ai/protocol").ScreenMechanic;
   layoutHint?: string;
 }
 

package/src/classifier/infer-render.ts

@@ -4,7 +4,7 @@ import type { AxisSource, RenderShape } from "./axes";
 import type { ContractSignals } from "./inspect";
 
 interface BlueprintHint {
-  mechanic?: string;
+  mechanic?: import("@ggui-ai/protocol").ScreenMechanic;
   layoutHint?: string;
 }
 

package/src/classifier/infer-tooling.ts

@@ -1,7 +1,7 @@
 // packages/ui-gen/src/classifier/infer-tooling.ts
 //
 // tooling axis — derived purely from contract presence of
-// `agentCapabilities.tools` / `clientCapabilities.libraries`.
+// `agentCapabilities.tools` / `clientCapabilities.gadgets`.
 // Describes the *direction* of tool usage present on the contract:
 // wired = UI references an agent tool, client = UI declares a
 // browser-capability gadget hook.

package/src/classifier/infer-trigger.ts

@@ -3,19 +3,16 @@
 import type { AxisSource, WriteTrigger } from "./axes";
 import type { ContractSignals } from "./inspect";
 
-interface BlueprintHint {
-  mechanic?: string;
-  layoutHint?: string;
-}
-
 const DRAG_RX = /\b(drag|drop|dragging|draggable)\b/i;
 const SWIPE_RX = /\b(swipe|swipes|gesture\s*stack)\b/i;
 const KEYBOARD_RX = /\b(keyboard\s*shortcut|hotkey|keystroke|kbd)\b/i;
 
+// The blueprint hint no longer participates: the mechanics that once
+// carried a trigger signal (drag/swipe) were deleted from ScreenMechanic
+// in draft-2026-06-12; static/live/form say nothing about triggers.
 export function inferWriteTrigger(
   s: ContractSignals,
   prompt: string,
-  blueprint: BlueprintHint | undefined,
 ): { value: WriteTrigger; source: AxisSource } {
   // If there are no actions at all, trigger is irrelevant — default to 'click'
   // but mark source as 'default' to convey that the value isn't load-bearing.
@@ -23,12 +20,6 @@ export function inferWriteTrigger(
     return { value: "click", source: "default" };
   }
 
-  // Blueprint mechanic — explicit authored hint
-  if (blueprint?.mechanic === "drag")
-    return { value: "drag", source: "blueprint" };
-  if (blueprint?.mechanic === "swipe")
-    return { value: "swipe", source: "blueprint" };
-
   // Prompt signals
   if (DRAG_RX.test(prompt)) return { value: "drag", source: "prompt" };
   if (SWIPE_RX.test(prompt)) return { value: "swipe", source: "prompt" };

package/src/classifier/inspect.ts

@@ -171,7 +171,7 @@ function hasGeoCoordsRecursive(node: unknown, depth = 0): boolean {
 
 export interface ActionEntryInfo {
   name: string;
-  tool?: string;
+  nextStep?: string;
   example?: Record<string, unknown>;
   /** Top-level keys in example whose value is scalar (string/number/boolean). */
   scalarKeys: string[];
@@ -299,8 +299,8 @@ export function inferStreamKindFromSchema(
 
 /**
  * Per-tool projection of the contract's `agentCapabilities.tools`
- * catalog. Also reused for `clientCapabilities.libraries` entries
- * (always with empty `requestKeys`) — libraries are pure declaration.
+ * catalog. Also reused for `clientCapabilities.gadgets` entries
+ * (always with empty `requestKeys`) — gadgets are pure declaration.
  */
 export interface AgentToolInfo {
   name: string;
@@ -319,8 +319,8 @@ export interface ContractSignals {
    *  fetch-axis classification. */
   agentTools: AgentToolInfo[];
   /**
-   * Binding names declared in `clientCapabilities.libraries`. The
-   * `requestKeys` field is always empty — libraries are
+   * Binding names declared in `clientCapabilities.gadgets`. The
+   * `requestKeys` field is always empty — gadgets are
    * declaration-only.
    */
   clientCapabilities: AgentToolInfo[];
@@ -405,7 +405,7 @@ export function inspect(contract: ClassifierInput): ContractSignals {
     (contract.actionSpec as Record<string, unknown> | undefined) ?? {};
   const actions: ActionEntryInfo[] = [];
   for (const [name, action] of Object.entries(actionsMap)) {
-    const a = action as { example?: Record<string, unknown>; tool?: string };
+    const a = action as { example?: Record<string, unknown>; nextStep?: string };
     const scalarKeys = scalarKeyCount(a?.example);
     const allKeys = allTopLevelKeys(a?.example);
     const referencedEntities = referencedEntitiesForPayload(
@@ -415,7 +415,7 @@ export function inspect(contract: ClassifierInput): ContractSignals {
     );
     actions.push({
       name,
-      tool: a?.tool,
+      nextStep: a?.nextStep,
       example: a?.example,
       scalarKeys,
       allKeys,

package/src/coding-agent/self-check.ts

@@ -72,7 +72,7 @@ export async function runCodingAgentSelfCheck(
   // will not fire the wire at runtime — but `pnpm typecheck` won't flag the
   // absence (a missing call is a missing side effect, not a type error).
   // This rule closes that gap at the deterministic self_check tier.
-  // `agentTools` (catalog declaration, NOT a hook) and `clientCapabilities`
+  // `agentCapabilities.tools` (catalog declaration, NOT a hook) and `clientCapabilities`
   // (vendor-package hooks, not @ggui-ai/wire) are intentionally excluded.
   if (contract) {
     try {

package/src/evaluation/cost-tracker.ts

@@ -4,16 +4,44 @@
 // Records LLM token usage across all calls in a generation pipeline
 // and enforces an optional budget ceiling.
 
-const PRICE_PER_1K_TOKENS: Record<string, { input: number; output: number }> = {
-  'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
-  'claude-haiku-4-5-20251001': { input: 0.0008, output: 0.004 },
-  'gemini-3-flash-preview': { input: 0.0001, output: 0.0004 },
-  // Gemini 3.5 Flash-Lite — $0.30/$2.50 per MTok (ai.google.dev/gemini-api/docs/pricing).
-  'gemini-3.5-flash-lite': { input: 0.0003, output: 0.0025 },
-  'gpt-5.4-mini': { input: 0.0003, output: 0.0012 },
-  // $1.00 in / $6.00 out per MTok (OpenAI list, 2026-07) → per-1K.
-  'gpt-5.6-luna': { input: 0.001, output: 0.006 },
-};
+import { MODEL_REGISTRY, type ModelId } from '@ggui-ai/protocol';
+
+/**
+ * Resolve a bare wire model id (what the generation pipeline reports —
+ * `gpt-5.6-luna`, `claude-haiku-4-5-20251001`) to a LiteLLM-keyed
+ * {@link MODEL_REGISTRY} entry (`openai/gpt-5.6-luna`,
+ * `anthropic/claude-haiku-4-5`).
+ *
+ * This table used to hand-maintain its own per-1K prices, and drifted:
+ * on 2026-07-31 four of its six rows were wrong (Haiku 4.5 20% low,
+ * gemini-3-flash-preview 5-7x low, gpt-5.4-mini ~3x low, Luna 5x high
+ * after OpenAI's cut). Deriving from the registry — which the pod's
+ * pricing test now pins against the vendored LiteLLM snapshot — means
+ * one place to update and one place that can be wrong.
+ *
+ * Resolution order mirrors the benchmark harness's
+ * `resolveJudgeCostModelId`: exact key, unique `/<model>` suffix, then
+ * the same suffix match with a trailing `-YYYYMMDD` date pin stripped.
+ */
+function resolveRegistryId(model: string): ModelId | null {
+  const keys = Object.keys(MODEL_REGISTRY) as ModelId[];
+  if ((keys as string[]).includes(model)) return model as ModelId;
+  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;
+}
+
+/** Fallback when a model has no registry entry — Sonnet-class rates. */
+const FALLBACK_PER_1K = { input: 0.003, output: 0.015 };
+
+/** Per-1K input/output USD for a bare wire model id. */
+export function pricePer1k(model: string): { input: number; output: number } {
+  const id = resolveRegistryId(model);
+  if (id === null) return FALLBACK_PER_1K;
+  const { costs } = MODEL_REGISTRY[id];
+  return { input: costs.inputPer1M / 1000, output: costs.outputPer1M / 1000 };
+}
 
 export class CostTracker {
   private totalCost = 0;
@@ -21,7 +49,7 @@ export class CostTracker {
   constructor(private maxBudget: number | null) {}
 
   record(model: string, inputTokens: number, outputTokens: number): number {
-    const prices = PRICE_PER_1K_TOKENS[model] ?? { input: 0.003, output: 0.015 };
+    const prices = pricePer1k(model);
     const cost = (inputTokens / 1000) * prices.input + (outputTokens / 1000) * prices.output;
     this.totalCost += cost;
     return cost;

package/src/harness/check/runtime-render/render-check.ts

@@ -475,8 +475,8 @@ export async function runRenderCheck(
       }
 
       // ── Check 3: Agent-tool wiring — RETIRED ──────────────────────────
-      // `useWiredTool` is retired. The contract's `agentTools` is a
-      // catalog of tools the AGENT invokes — there is no component hook
+      // `useWiredTool` is retired. The contract's `agentCapabilities.tools`
+      // is a catalog of tools the AGENT invokes — there is no component hook
       // surface. Cross-refs from actionSpec[*].nextStep /
       // streamSpec[*].source.tool ride through checks 2 (action wiring)
       // and 6 (stream re-render); the catalog itself has no
@@ -965,8 +965,8 @@ async function checkActionWiring(input: CheckActionInput): Promise<RenderCheckIs
 }
 
 // `checkWiredToolWiring` is retired — `useWiredTool` was removed; the
-// contract's `agentTools` is a catalog the AGENT invokes (no component
-// hook to verify). Cross-refs from `actionSpec[*].nextStep` and
+// contract's `agentCapabilities.tools` is a catalog the AGENT invokes
+// (no component hook to verify). Cross-refs from `actionSpec[*].nextStep` and
 // `streamSpec[*].source.tool` ride through the action / stream check
 // arms in `runRenderCheck` instead.
 

package/src/harness/llm-router.ts

@@ -876,7 +876,7 @@ export class OpenAIAgent extends LLMAgent {
  */
 function interactionText(interaction: Interactions.Interaction): string {
   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') {
@@ -892,7 +892,7 @@ function interactionText(interaction: Interactions.Interaction): string {
 function functionCallSteps(
   interaction: Interactions.Interaction,
 ): Interactions.FunctionCallStep[] {
-  return interaction.steps.filter(
+  return (interaction.steps ?? []).filter(
     (s): s is Interactions.FunctionCallStep => s.type === 'function_call',
   );
 }

package/src/providers/bedrock.ts

@@ -56,8 +56,8 @@
  * model id namespaces:
  *
  *   - Direct API: `claude-haiku-4-5`, `claude-opus-4-7`, etc.
- *   - Bedrock foundation models: `anthropic.claude-3-5-sonnet-20241022-v2:0`
- *   - Bedrock cross-region inference profiles: `us.anthropic.claude-3-5-sonnet-20241022-v2:0`
+ *   - Bedrock foundation models: `anthropic.claude-sonnet-4-6`
+ *   - Bedrock cross-region inference profiles: `us.anthropic.claude-haiku-4-5-20251001-v1:0`
  *
  * The adapter passes whatever `request.model` contains straight to
  * Bedrock — translation lives in the caller (model picker / deployment

package/src/tools/get-wire.ts

@@ -2,4 +2,4 @@
  * AUTO-GENERATED from @ggui-ai/wire JSDoc.
  * Do not edit manually. Run: pnpm --filter @ggui-ai/wire generate:docs
  */
-export const 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 — 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 — 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 — 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 — 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 — 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** — 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 — 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'` — 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 — 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 — 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 — it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider — 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)` — `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` — same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases — 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 — `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 — the nested- interactive double-fire backstop.  Reachability constraint: the first-party renderers do NOT set this field — `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";
+export const 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 — 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 — 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 — 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 — 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 — 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** — 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 — 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'` — 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 — 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 — 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 — it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider — 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)` — `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` — same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases — 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 — `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 — the nested- interactive double-fire backstop.  Reachability constraint: the first-party renderers do NOT set this field — `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";

package/src/validation/primitives.ts

@@ -60,6 +60,8 @@ export const VALID_PRIMITIVES = [
   'EmptyState',
   'Stat',
   'Stepper',
+  'Markdown',
+  'MarkdownInline',
   'Header',
   'Sidebar',
   'CardGrid',