@ggui-ai/ui-gen 0.27.0 → 0.29.0

package/dist/workflows.js

@@ -1,153 +1,4 @@
-// src/workflows.ts
-var identityParser = (raw) => raw;
-var SINGLE_PASS = {
-  id: "single_pass@1",
-  name: "single_pass",
-  description: "One LLM-driven impl loop. Used for risk:low + risk:medium contract.",
-  phases: [
-    {
-      id: "impl",
-      tasks: [
-        {
-          id: "generate",
-          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,
-          contextBuilder: (ctx) => `User prompt: ${ctx.prompt}
-
-Boilerplate is pre-written. Fill it in with apply_changes.`,
-          outputFormat: "tool-call",
-          outputParser: identityParser,
-          outputName: "source"
-        }
-      ]
-    }
-  ]
-};
-var STAGED = {
-  id: "staged@1",
-  name: "staged",
-  description: "plan \u2192 execute. One architect task then one coder task.",
-  phases: [
-    {
-      id: "plan",
-      tasks: [
-        {
-          id: "architect",
-          systemPrompt: "You are a UI architect. Produce a plan, no code.",
-          contextBuilder: (ctx) => `Plan the UI for: ${ctx.prompt}`,
-          outputFormat: "structured",
-          outputParser: identityParser,
-          outputName: "plan",
-          maxTokens: 800
-        }
-      ]
-    },
-    {
-      id: "execute",
-      tasks: [
-        {
-          id: "coder",
-          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,
-          contextBuilder: (ctx) => `User prompt: ${ctx.prompt}
-
-Plan:
-${ctx.priorResults.plan ?? "(no plan)"}
-
-Implement per plan with apply_changes.`,
-          inputs: ["plan"],
-          outputFormat: "tool-call",
-          outputParser: identityParser,
-          outputName: "source"
-        }
-      ]
-    }
-  ]
-};
-var STAGED_CONCURRENT = {
-  id: "staged_concurrent@1",
-  name: "staged-concurrent",
-  description: "plan \u2192 [types \u2225 hooks \u2225 jsx] \u2192 integrate. DAG with parallel skeleton phase.",
-  phases: [
-    {
-      id: "plan",
-      tasks: [
-        {
-          id: "architect",
-          systemPrompt: "Plan the UI. No code.",
-          contextBuilder: (ctx) => `Plan the UI for: ${ctx.prompt}`,
-          outputFormat: "structured",
-          outputParser: identityParser,
-          outputName: "plan",
-          maxTokens: 600
-        }
-      ]
-    },
-    {
-      id: "skeleton",
-      tasks: [
-        {
-          id: "types",
-          systemPrompt: "Emit only type declarations for the contract.",
-          contextBuilder: (ctx) => `Emit TypeScript types for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? "(n/a)"}`,
-          inputs: ["plan"],
-          outputFormat: "structured",
-          outputParser: identityParser,
-          outputName: "types",
-          maxTokens: 400
-        },
-        {
-          id: "hooks",
-          systemPrompt: "Emit only hook declarations (useState/useEffect/useStream).",
-          contextBuilder: (ctx) => `Emit hooks for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? "(n/a)"}`,
-          inputs: ["plan"],
-          outputFormat: "structured",
-          outputParser: identityParser,
-          outputName: "hooks",
-          maxTokens: 400
-        },
-        {
-          id: "jsx",
-          systemPrompt: "Emit only the render JSX tree skeleton.",
-          contextBuilder: (ctx) => `Emit JSX for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? "(n/a)"}`,
-          inputs: ["plan"],
-          outputFormat: "structured",
-          outputParser: identityParser,
-          outputName: "jsx",
-          maxTokens: 400
-        }
-      ]
-    },
-    {
-      id: "integrate",
-      tasks: [
-        {
-          id: "glue",
-          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,
-          contextBuilder: (ctx) => `Combine into one component. Types:
-${ctx.priorResults.types}
-
-Hooks:
-${ctx.priorResults.hooks}
-
-JSX:
-${ctx.priorResults.jsx}`,
-          inputs: ["types", "hooks", "jsx"],
-          outputFormat: "tool-call",
-          outputParser: identityParser,
-          outputName: "source"
-        }
-      ]
-    }
-  ]
-};
-var WORKFLOWS = {
-  single_pass: SINGLE_PASS,
-  staged: STAGED,
-  staged_concurrent: STAGED_CONCURRENT
-};
-function pickWorkflow(_classification) {
-  return WORKFLOWS.single_pass;
-}
-
-export { WORKFLOWS, pickWorkflow };
+export { WORKFLOWS, pickWorkflow } from './chunk-S2GVXKKY.js';
+import './chunk-G3PMV62Z.js';
 //# sourceMappingURL=workflows.js.map
 //# sourceMappingURL=workflows.js.map

package/dist/workflows.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workflows.ts"],"names":[],"mappings":"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","file":"workflows.js","sourcesContent":["// packages/ui-gen/src/workflows.ts\n//\n// Workflow registry + classification-driven picker. Each workflow\n// describes an execution topology (phases × tasks) for producing source\n// from a contract + prompt; the harness runtime owns actual LLM calls.\n//\n// Workflow shapes are validated shipping defaults — even `staged` /\n// `staged-concurrent` are reserved-but-registered topologies the picker\n// may route to in future risk-tier routing. Classification-driven\n// routing itself is deliberately conservative today (always\n// `single_pass`); changing the picker is a behavior change that should\n// be validated against the generation benchmark suite.\n//\n// Public surface is intentionally minimal: consumers import `WORKFLOWS`\n// (the map) + `pickWorkflow` (the router) + `WorkflowId` (the key\n// type). Individual topology constants (SINGLE_PASS, STAGED,\n// STAGED_CONCURRENT) are internal — access them via\n// `WORKFLOWS.single_pass` etc.\n\nimport type { Classification } from \"./classifier/axes.js\";\nimport type { Workflow } from \"./harness/types-public.js\";\n\n/** Identity parser — used for tasks whose output is already a string. */\nconst identityParser = (raw: unknown): string => raw as string;\n\n/**\n * single_pass — one phase, one task. The current default. The task runs\n * the existing impl/patch/eval-fix loop as a single atomic block.\n */\nconst SINGLE_PASS: Workflow = {\n  id: \"single_pass@1\",\n  name: \"single_pass\",\n  description: \"One LLM-driven impl loop. Used for risk:low + risk:medium contract.\",\n  phases: [\n    {\n      id: \"impl\",\n      tasks: [\n        {\n          id: \"generate\",\n          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,\n          contextBuilder: (ctx) =>\n            `User prompt: ${ctx.prompt}\\n\\nBoilerplate is pre-written. Fill it in with apply_changes.`,\n          outputFormat: \"tool-call\",\n          outputParser: identityParser,\n          outputName: \"source\",\n        },\n      ],\n    },\n  ],\n};\n\n/**\n * staged — plan phase then execute phase. For risk:high contract where\n * decomposing planning from authoring reduces light-model cognitive load.\n *\n * Registered but not yet routed by `pickWorkflow` — the executor wires\n * architect/coder TaskRunners through a separate dispatch path in core/.\n */\nconst STAGED: Workflow = {\n  id: \"staged@1\",\n  name: \"staged\",\n  description: \"plan → execute. One architect task then one coder task.\",\n  phases: [\n    {\n      id: \"plan\",\n      tasks: [\n        {\n          id: \"architect\",\n          systemPrompt: \"You are a UI architect. Produce a plan, no code.\",\n          contextBuilder: (ctx) => `Plan the UI for: ${ctx.prompt}`,\n          outputFormat: \"structured\",\n          outputParser: identityParser,\n          outputName: \"plan\",\n          maxTokens: 800,\n        },\n      ],\n    },\n    {\n      id: \"execute\",\n      tasks: [\n        {\n          id: \"coder\",\n          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,\n          contextBuilder: (ctx) =>\n            `User prompt: ${ctx.prompt}\\n\\nPlan:\\n${ctx.priorResults.plan ?? \"(no plan)\"}\\n\\nImplement per plan with apply_changes.`,\n          inputs: [\"plan\"],\n          outputFormat: \"tool-call\",\n          outputParser: identityParser,\n          outputName: \"source\",\n        },\n      ],\n    },\n  ],\n};\n\n/**\n * staged-concurrent — plan, then parallel skeleton tasks, then integrate.\n * Reserved shape for risk:high + multi-axis contract where the LLM\n * benefits from breaking structural concerns apart.\n */\nconst STAGED_CONCURRENT: Workflow = {\n  id: \"staged_concurrent@1\",\n  name: \"staged-concurrent\",\n  description: \"plan → [types ∥ hooks ∥ jsx] → integrate. DAG with parallel skeleton phase.\",\n  phases: [\n    {\n      id: \"plan\",\n      tasks: [\n        {\n          id: \"architect\",\n          systemPrompt: \"Plan the UI. No code.\",\n          contextBuilder: (ctx) => `Plan the UI for: ${ctx.prompt}`,\n          outputFormat: \"structured\",\n          outputParser: identityParser,\n          outputName: \"plan\",\n          maxTokens: 600,\n        },\n      ],\n    },\n    {\n      id: \"skeleton\",\n      tasks: [\n        {\n          id: \"types\",\n          systemPrompt: \"Emit only type declarations for the contract.\",\n          contextBuilder: (ctx) =>\n            `Emit TypeScript types for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? \"(n/a)\"}`,\n          inputs: [\"plan\"],\n          outputFormat: \"structured\",\n          outputParser: identityParser,\n          outputName: \"types\",\n          maxTokens: 400,\n        },\n        {\n          id: \"hooks\",\n          systemPrompt: \"Emit only hook declarations (useState/useEffect/useStream).\",\n          contextBuilder: (ctx) =>\n            `Emit hooks for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? \"(n/a)\"}`,\n          inputs: [\"plan\"],\n          outputFormat: \"structured\",\n          outputParser: identityParser,\n          outputName: \"hooks\",\n          maxTokens: 400,\n        },\n        {\n          id: \"jsx\",\n          systemPrompt: \"Emit only the render JSX tree skeleton.\",\n          contextBuilder: (ctx) =>\n            `Emit JSX for: ${ctx.prompt}. Plan: ${ctx.priorResults.plan ?? \"(n/a)\"}`,\n          inputs: [\"plan\"],\n          outputFormat: \"structured\",\n          outputParser: identityParser,\n          outputName: \"jsx\",\n          maxTokens: 400,\n        },\n      ],\n    },\n    {\n      id: \"integrate\",\n      tasks: [\n        {\n          id: \"glue\",\n          systemPrompt: (ctx) => ctx.harness.how.systemPrompt,\n          contextBuilder: (ctx) =>\n            `Combine into one component. Types:\\n${ctx.priorResults.types}\\n\\nHooks:\\n${ctx.priorResults.hooks}\\n\\nJSX:\\n${ctx.priorResults.jsx}`,\n          inputs: [\"types\", \"hooks\", \"jsx\"],\n          outputFormat: \"tool-call\",\n          outputParser: identityParser,\n          outputName: \"source\",\n        },\n      ],\n    },\n  ],\n};\n\nexport const WORKFLOWS = {\n  single_pass: SINGLE_PASS,\n  staged: STAGED,\n  staged_concurrent: STAGED_CONCURRENT,\n} as const;\n\nexport type WorkflowId = keyof typeof WORKFLOWS;\n\n/**\n * Pick a workflow based on classification shape. One dispatch rule —\n * kept small on purpose. Changing this mapping is a first-class\n * experiment.\n *\n * Deliberately conservative — always `single_pass`. Classification-\n * driven routing to `staged` / `staged-concurrent` will follow once\n * the workflow executor can actually run non-single_pass shapes end-\n * to-end on the dispatch path.\n */\nexport function pickWorkflow(_classification: Classification): Workflow {\n  return WORKFLOWS.single_pass;\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"workflows.js"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.27.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.",
+  "version": "0.29.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": [
     "ggui",
@@ -183,17 +183,21 @@
     }
   },
   "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.229",
     "@google/adk": "^2.0.0",
     "@openai/agents": "^0.17.0",
     "@sparticuz/chromium": "^149.0.0",
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.27.0",
-    "@ggui-ai/project-config": "0.27.0",
-    "@ggui-ai/protocol": "0.27.0"
+    "@ggui-ai/mcp-server-core": "0.29.0",
+    "@ggui-ai/project-config": "0.29.0",
+    "@ggui-ai/protocol": "0.29.0"
   },
   "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
     "@google/adk": {
       "optional": true
     },
@@ -215,12 +219,12 @@
   },
   "dependencies": {
     "@anthropic-ai/bedrock-sdk": "^0.33.3",
-    "@anthropic-ai/claude-agent-sdk": "0.3.229",
     "@anthropic-ai/sdk": "^0.123.0",
     "@google/genai": "^2.8.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "diff": "^8.0.3",
     "esbuild": "^0.28.2",
@@ -232,29 +236,29 @@
     "memfs": "^4.56.11",
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
-    "zod": "^4.3.6",
-    "@ggui-ai/design": "0.27.0",
-    "@ggui-ai/sandbox": "0.27.0",
-    "@ggui-ai/gadgets": "0.27.0",
-    "@ggui-ai/ui-visual-tester": "0.27.0",
-    "@ggui-ai/wire": "0.27.0"
+    "zod": "^4.6.6",
+    "@ggui-ai/design": "0.29.0",
+    "@ggui-ai/gadgets": "0.29.0",
+    "@ggui-ai/sandbox": "0.29.0",
+    "@ggui-ai/ui-visual-tester": "0.29.0",
+    "@ggui-ai/wire": "0.29.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.229",
     "@google/adk": "^2.0.0",
     "@openai/agents": "^0.17.0",
     "@sparticuz/chromium": "^149.0.0",
     "@types/eslint": "^9.6.1",
     "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "puppeteer-core": "^25.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
-    "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.27.0",
-    "@ggui-ai/project-config": "0.27.0",
-    "@ggui-ai/protocol": "0.27.0"
+    "vitest": "^4.1.11",
+    "@ggui-ai/mcp-server-core": "0.29.0",
+    "@ggui-ai/protocol": "0.29.0",
+    "@ggui-ai/project-config": "0.29.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/claude/sdk.ts

@@ -15,6 +15,7 @@ import { createArtifacts, processMessage } from './message-parser';
 import { createToolMcpServer } from './tool-bridge';
 import { claudeCodeLoginQueryOptions, loginChildEnv } from './claude-code-login';
 import { sdkToolPins } from './sdk-tool-pins';
+import { loadClaudeAgentSdk } from '../../harness/claude-agent-sdk-loader';
 
 export class ClaudeSdkAdapter extends GeneratorAdapter {
   readonly provider: ProviderName = 'claude';
@@ -38,8 +39,9 @@ export class ClaudeSdkAdapter extends GeneratorAdapter {
     const startTime = Date.now();
     const cfg = this.sdkConfig;
 
-    // Dynamic import to avoid loading claude-agent-sdk in non-Claude contexts
-    const { query } = await import('@anthropic-ai/claude-agent-sdk');
+    // The SDK is an optional peer (ggui#1951): loaded on first use, and a
+    // missing one fails with the install line.
+    const { query } = await loadClaudeAgentSdk();
 
     // Build environment from config or process.env
     // ggui#1185/#1278 — on the login path the binary sees an allowlisted

package/src/adapters/claude/tool-bridge.ts

@@ -13,6 +13,7 @@
 import type { ToolDefinition } from '../types';
 import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
 import type { JsonObject } from '@ggui-ai/protocol';
+import { loadClaudeAgentSdk } from '../../harness/claude-agent-sdk-loader';
 
 /** Name used for the in-process MCP server. */
 export const MCP_SERVER_NAME = 'ggui';
@@ -30,7 +31,7 @@ export async function createToolMcpServer(
   server: McpSdkServerConfigWithInstance;
   allowedToolNames: string[];
 }> {
-  const { tool, createSdkMcpServer } = await import('@anthropic-ai/claude-agent-sdk');
+  const { tool, createSdkMcpServer } = await loadClaudeAgentSdk();
 
   const mcpTools = tools.map((def) => {
     // Extract Zod shape from the input schema

package/src/adapters/generation-dispatch.ts

@@ -28,6 +28,9 @@ import { resolveHarnessPolicy } from "../harness/policy.js";
 // prompts carry pitfalls + design-system docs + primitives + wire
 // content.
 import { buildSystemPrompt as buildSystemPromptWithFunnel } from "../harness/runtime.js";
+import type { CodingTurnPrompt } from "../harness/runtime.js";
+
+export type { CodingTurnPrompt };
 // Axis-check registry filter. The `createHarness` constructor accepts a
 // pre-filtered axisChecks list; this callsite runs the `matches()`
 // predicate against the full registry and passes the filtered result.
@@ -137,6 +140,11 @@ export interface GenerationDispatchParams {
    * Production callers can omit this; benchmark runners should pass commit.props.
    */
   fixtureProps?: JsonObject;
+  /**
+   * Observer of the exact prompt each coding turn sends — the system prompt after the component-reference swap
+   * below, and the turn's user message (see `CodingTurnPrompt`). Read-only; nothing sent changes. Absent = no report.
+   */
+  onCodingTurnPrompt?: (sent: CodingTurnPrompt) => void;
   /**
    * Whether to wire the runtime-render check (`runtimeRender` when given,
    * else `DEFAULT_RUNTIME_RENDER_CHECK`) into the harness's check leg.
@@ -332,6 +340,7 @@ export async function dispatchGeneration(
     visualEvaluation: params.visualEvaluation,
     qualityConfig: params.qualityConfig,
     fixtureProps: params.fixtureProps,
+    ...(params.onCodingTurnPrompt !== undefined ? { onCodingTurnPrompt: params.onCodingTurnPrompt } : {}),
   };
 
   // ── Classify + build harness.

package/src/adapters/openai/raw.ts

@@ -58,6 +58,7 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
     // OpenAI's input token count INCLUDES cached tokens; track the cached
     // subset so tokens.input reports NON-cached input (ggui#1186).
     let totalCachedInputTokens = 0;
+    let totalCacheWriteTokens = 0;
     let turnsUsed = 0;
     let allTextOutput = '';
 
@@ -80,6 +81,8 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
         totalOutputTokens += response.usage.output_tokens ?? 0;
         totalCachedInputTokens +=
           response.usage.input_tokens_details?.cached_tokens ?? 0;
+        totalCacheWriteTokens +=
+          response.usage.input_tokens_details?.cache_write_tokens ?? 0;
       }
 
       // Process output items
@@ -166,6 +169,7 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
         totalInputTokens,
         totalOutputTokens,
         totalCachedInputTokens,
+        totalCacheWriteTokens,
       ),
       generationTimeMs: Date.now() - startTime,
       turnsUsed,

package/src/adapters/openai/sdk.ts

@@ -94,13 +94,18 @@ export class OpenAiSdkAdapter extends GeneratorAdapter {
       (sum, details) => sum + (details.cached_tokens ?? 0),
       0,
     );
+    // ggui#1957 — and the cache writes, the same kind of subset.
+    const cacheWriteTokens = (usage.inputTokensDetails ?? []).reduce(
+      (sum, details) => sum + (details.cache_write_tokens ?? 0),
+      0,
+    );
 
     return {
       compiledCode: capture.compiledCode,
       sourceCode: capture.sourceCode,
       stream: capture.stream,
       generatorMeta: capture.generatorMeta,
-      ...splitOpenAiUsage(inputTokens, outputTokens, cachedInputTokens),
+      ...splitOpenAiUsage(inputTokens, outputTokens, cachedInputTokens, cacheWriteTokens),
       generationTimeMs: Date.now() - startTime,
       turnsUsed: result.rawResponses?.length ?? 0,
     };

package/src/adapters/openai/tokens.ts

@@ -21,18 +21,32 @@ import type { AdapterResult } from '../types';
  * inflates `$/gen` and breaks `render_cache_metric`'s `cacheReadPct`
  * denominator). So the OpenAI adapters subtract the cached subset here.
  *
- * `total` is the full processed footprint (non-cached input + cache
- * reads + output = `inputTokensInclCached + outputTokens`), matching the
- * Claude adapter's `total` (input + cacheCreation + cacheRead + output);
- * OpenAI has no explicit cache-creation step, so there is no
- * `cacheCreationTokens` term.
+ * Cache WRITES are the same kind of subset (ggui#1957): OpenAI bills them on
+ * GPT-5.6 and later (1.25× input) and reports them as
+ * `input_tokens_details.cache_write_tokens`, "the number of input tokens
+ * that were written to the cache", inside the same input total. They are
+ * subtracted from `input` as the reads are and reported as
+ * `cacheCreationTokens`, so a consumer prices them at the cache-write rate,
+ * exactly once.
+ *
+ * `total` is the full processed footprint (non-cached input + cache reads +
+ * cache writes + output = `inputTokensInclCached + outputTokens`), matching
+ * the Claude adapter's `total` (input + cacheCreation + cacheRead + output).
  */
 export function splitOpenAiUsage(
   inputTokensInclCached: number,
   outputTokens: number,
   cachedTokens: number,
-): { tokens: AdapterResult['tokens']; cacheReadTokens: number } {
-  return splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens);
+  cacheWriteTokens: number,
+): { tokens: AdapterResult['tokens']; cacheReadTokens: number; cacheCreationTokens: number } {
+  const split = splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens);
+  // Never let a malformed usage report drive input negative: the writes are at most what remains after the reads.
+  const cacheCreation = Math.min(Math.max(cacheWriteTokens, 0), split.tokens.input);
+  return {
+    tokens: { input: split.tokens.input - cacheCreation, output: split.tokens.output, total: split.tokens.total },
+    cacheReadTokens: split.cacheReadTokens,
+    cacheCreationTokens: cacheCreation,
+  };
 }
 
 /**

package/src/adapters/provider-router.ts

@@ -29,6 +29,7 @@ import type { LlmRoute } from '@ggui-ai/protocol';
 export function getBedrockModelId(model: string): string {
   const BEDROCK_MAP: Record<string, string> = {
     'anthropic/claude-haiku-4-5': 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    'anthropic/claude-haiku-5-5': 'us.anthropic.claude-haiku-5-5', // listed ACTIVE in us-east-1 (ggui#1743)
     'anthropic/claude-sonnet-4-6': 'us.anthropic.claude-sonnet-4-6',
     'anthropic/claude-opus-4-6': 'us.anthropic.claude-opus-4-6-v1:0',
     // Claude 5-family (ggui#706, strings verified 2026-09-02 against

package/src/adapters/tool-bridge.ts

@@ -4,7 +4,7 @@
 // Zod → JSON Schema for tool declarations, and validated narrowing of
 // decoded tool-call arguments to `JsonObject`.
 
-import { z } from 'zod';
+import * as z from 'zod';
 import type { JsonObject, JsonValue } from '@ggui-ai/protocol';
 
 /**

package/src/adapters/tools.ts

@@ -5,7 +5,7 @@
 // but without Claude Agent SDK dependencies, making them portable across
 // OpenAI, Google, and Anthropic SDKs.
 
-import { z } from 'zod';
+import * as z from 'zod';
 import * as esbuild from 'esbuild';
 import { PRIMITIVES_DOCUMENTATION } from '../validation/index.js';
 import {

package/src/advanced/feedback.ts

@@ -7,8 +7,7 @@
  * (`validateContractBehavior`) returns structured
  * {@link BehaviorFailure}s. This module converts both into
  * prompt-augmenting text fragments the regen call appends to the
- * user prompt — same shape the existing `runEvaluationLoop` uses
- * for LLM-eval complaints.
+ * user prompt.
  *
  * Format mirrors the diagnostic format the runtime-render adapter
  * already produces (see `harness/check/runtime-render/adapter.ts`),

package/src/advanced/generator.ts

@@ -64,7 +64,7 @@ import {
 /** Generator identity — slug, tier, and model. */
 export const ADVANCED_GENERATOR_SLUG = 'ui-gen-advanced' as const;
 export const ADVANCED_GENERATOR_TIER: GeneratorTier = 'advanced';
-export const ADVANCED_GENERATOR_MODEL: ModelRef = 'anthropic/claude-opus-4-7';
+export const ADVANCED_GENERATOR_MODEL: ModelRef = 'anthropic/claude-opus-5-5';
 
 /**
  * Re-exported under a friendlier name for callers wiring deploys.
@@ -134,8 +134,9 @@ export interface CreateAdvancedUiGeneratorOptions
 
   /**
    * Inner generator. Defaults to a fresh `createUiGenerator({tier:
-   * 'advanced', model: 'opus-4-7'})` so the BYOK route resolves to an
-   * Opus model on Anthropic. Tests can inject a stub.
+   * 'advanced', model: ADVANCED_GENERATOR_MODEL})`. That model is the
+   * generator's declared identity only: each request runs on the model
+   * its own `input.llm` route names. Tests can inject a stub.
    *
    * The inner generator's identity (slug/tier/model) is irrelevant —
    * this advanced wrapper exposes its own fixed identity.

package/src/boilerplate/free-design-prompt.ts

@@ -96,6 +96,13 @@ const SEMANTIC_ROLES: ReadonlyArray<{ readonly names: readonly string[]; readonl
   { names: ["onPrimary"], role: "text on the brand color" },
   { names: ["outline", "outlineVariant"], role: "borders + dividers" },
   { names: ["onError"], role: "text on an error fill" },
+  {
+    names: ["tint-1", "tint-2", "tint-3", "tint-4", "tint-5", "tint-6", "tint-7", "tint-8"],
+    role:
+      "categorical fills for DATA categories only (series, lanes, kinds, element groups) — never for state, never as decoration; " +
+      "the text on a tint is `onContainer` only, one short line, never muted text; the category is always also in words (a label or a legend); " +
+      "a category keeps its tint for the life of the card (assign from the data's order, never render order); more than eight categories: group to eight, or words only",
+  },
 ];
 
 /** Split the manifest's `--ggui-color-*` names into ramps (family + numeric steps) and semantic roles. */

package/src/boilerplate/generate.ts

@@ -35,8 +35,10 @@ import type {
 } from "@ggui-ai/protocol";
 import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
 import { renderBoilerplate } from "./render.js";
+import { BOILERPLATE_REACT_IMPORT } from "./react-hooks.js";
 import { jsonSchemaTypeToTs } from "./json-schema-ts.js";
-import { DEFAULT_DESIGN_MODE, type DesignMode } from "../design-mode.js";
+import { GGUI_MOUNT_CANVAS_EXPORT } from "@ggui-ai/design/rendering";
+import { DEFAULT_DESIGN_MODE, canvasForRendering, type DesignMode } from "../design-mode.js";
 
 /** Shell layout modes supported by the boilerplate templates. */
 export type ShellType = "chat" | "fullscreen" | "spatial";
@@ -544,9 +546,10 @@ export function generateBoilerplate(
   const gadgetImport =
     gadgetImportLine.length > 0 ? `${gadgetImportLine}\n` : "";
 
-  // ── React import — only include hooks that are actually needed ──
-  const reactHooks = ["useState", "useCallback", "useMemo", "useEffect", "useRef"];
-  const reactImport = `import React, { ${reactHooks.join(", ")} } from 'react';`;
+  // ── React import — the hooks generated code may use, always listed (the line is DO NOT EDIT) ──
+  // `useLayoutEffect` (ggui#1896): the prompt seeds a context slot from a prop with it, so the
+  // first frame never paints the slot's contract default.
+  const reactImport = BOILERPLATE_REACT_IMPORT;
 
   // ── Hook body ──────────────────────────────────────────
   // Wire hooks are placed inside render(), before the return statement.
@@ -603,11 +606,21 @@ export function generateBoilerplate(
   // hooks own their typed return shape internally; the contract surface
   // is pure declaration.
 
+  // The canvas this card is composed for, as a named export the runtime reads at mount
+  // (`resolveMountFit`): a chat-width card on a fullscreen surface keeps its natural height in its
+  // own frame instead of filling the surface. The compile step writes it; the model never does.
+  // It follows the shell × screen descriptors, which is what makes a chat shell `xs-chat-card`.
+  // An explicit canvas (the free prompt's) is not consulted: it can disagree with the shell, and the
+  // constrained boilerplate stays byte-identical whatever canvas is passed (INVARIANT 1).
+  const mountCanvas =
+    `\n\n// DO NOT EDIT — the canvas this card is composed for; the runtime reads it at mount.\n` +
+    `export const ${GGUI_MOUNT_CANVAS_EXPORT} = "${canvasForRendering(shellType, screen)}";`;
+
   return renderBoilerplate(shellType ?? "fullscreen", screen ?? "universal", {
     REACT_IMPORT: reactImport,
     ALL_DESIGN,
     WIRE_IMPORT: wireImport + gadgetImport,
-    PROPS_INTERFACE: propsInterface,
+    PROPS_INTERFACE: propsInterface + mountCanvas,
     ACTION_TYPES: actionTypesBlock,
     STREAM_TYPES: streamTypesBlock,
     CONTEXT_HOOKS: contextHooks,

package/src/boilerplate/hard-sections.ts

@@ -168,7 +168,7 @@ export default function Component(props: Props) {
   return (
     <Container>
       <Text>Step {currentStep}</Text>
-      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
+      <Input value={draftText} onChange={setDraftText} />
       <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
     </Container>
   );
@@ -181,7 +181,9 @@ For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
 
 Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms — adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state — drafts, current step, hover, selection — without you calling any API.
 
-**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={setDraftText}>\` so the agent sees the typing live (a design control's \`onChange\` hands you the value, never an event). If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+
+**Seeding a slot from a prop.** A slot starts at the contract's default, never at a prop. When a slot must start from a prop (a form pre-filled from \`props\`), seed it with \`useLayoutEffect(() => setName(props.name ?? ''), [props.name])\` — \`useLayoutEffect\`, not \`useEffect\`: \`useEffect\` lets the first frame paint the empty default before the prop arrives. The dependency array re-seeds the slot when the agent repaints with new props.
 
 **When NOT to use it.** Local UI state the contract did NOT declare — \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
 
@@ -250,7 +252,10 @@ export const FRAME_SIZING = `## Sizing — the frame owns the height and the wid
 The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
 - An inline card takes its natural height. A content-sized frame is measured FROM the content, so a \`100vh\` root can never shrink and grows the frame on every re-measure.
 - Under fullscreen the frame already stretches your root to its full height. Centre inside it with flex (\`display: flex; flex-direction: column; justify-content: center\`), never with a viewport height.
-- Under fullscreen the frame also keeps a 16 px inset between your content and the panel's edge — leave it. A \`surface="hero"\` band that OPENS the card runs edge to edge on its own. Any other band that is MEANT to run edge to edge (a full-width strip of rows, a closing action bar) takes \`bleed\` (\`<Box surface="sunken" bleed>…</Box>\`); only such a band should, and \`bleed\` is ignored outside fullscreen.
+- In EVERY fit (an inline card, a framed card, fullscreen) the card keeps ONE content edge: the runtime insets your root's content from the card's edge. Leave it, and never pad it back out. Only two things run edge to edge, in every fit:
+  - a \`surface="hero"\` band that is your root's FIRST child, opening the card (\`<Box surface="hero">…</Box>\` directly inside the root, not wrapped in a \`Stack\`, not second);
+  - any other band that declares \`bleed\` (\`<Box surface="sunken" bleed>…</Box>\`). Only a band MEANT to run edge to edge takes it: a full-width strip of rows, a closing action bar.
+  A band you paint yourself (a \`Box\` with a \`background\`) is NOT an edge-to-edge band. It sits inside the inset with the card's corners showing around it, like a box floating in the card. An opening band is always the kit's \`surface="hero"\`, never your own colour.
 - To fill a parent that has a height use \`height: 100%\` or \`flex: 1\`; a viewport unit is only ever a \`max-height\` cap on a scroll region.
 
 The width works the same way, and the mistake is the mirror image: **your outermost element FILLS the frame; a width cap belongs INSIDE it, on the column that holds text.**