@ggui-ai/ui-gen 0.25.0 → 0.27.0

package/README.md

@@ -1,10 +1,10 @@
 # @ggui-ai/ui-gen
 
-UI generation harness for [ggui](https://github.com/ggui-ai/ggui) — the engine that turns a `DataContract` into a working React component.
+UI generation harness for [GGUI](https://github.com/ggui-ai/ggui) — the engine that turns a `DataContract` into a working React component.
 
 It bundles the three coupled pieces of the generation pipeline:
 
-- **System prompt** — the instructions that tell the LLM _how_ to code against the ggui design system.
+- **System prompt** — the instructions that tell the LLM _how_ to code against the GGUI design system.
 - **Coding harness** — the multi-turn loop (implement → self-check → patch → evaluate) plus provider adapters for Claude, OpenAI, and Google models.
 - **Evaluation engine** — deterministic checks and LLM-judged scoring of generated components.
 

package/dist/{adapter-Cg_rkpGq.d.ts → adapter-h4_V69LI.d.ts}

@@ -1,7 +1,7 @@
 import { RuntimeRenderCheck } from './harness/types-public.js';
 import { GenerationRuntimeProbeCheck } from '@ggui-ai/mcp-server-core';
 import { JsonObject, DataContract } from '@ggui-ai/protocol';
-import { P as ProbeHostLoad } from './types-public-BJTLpzWn.js';
+import { f as ProbeHostLoad, g as ProbePendingAffordance } from './types-public-h8IMnYuh.js';
 
 /**
  * The subprocess bounds of one isolated check (ggui#1380). They are
@@ -38,6 +38,30 @@ interface RenderCheckHostOptions {
     readonly bounds?: Partial<RenderCheckHostBounds>;
 }
 
+/**
+ * The action walk (ggui#1652): find a control that dispatches one action by
+ * walking the card's screens, as a person would, in a mount of its own.
+ *
+ * A screen is the card's set of controls, told apart by each control's tag,
+ * type, label (its aria-label, placeholder or text) and disabled state, never
+ * by typed values, selection or generated names.
+ * Picking an answer is the same screen unless it enables or disables a
+ * control; a wizard's next step, or an Edit button that now reads Save, is a
+ * new one. Each control is pressed once per screen. When every control on
+ * the current screen has been pressed, the walk returns over controls it has
+ * already pressed to the nearest screen that still has one to press. A press
+ * that leads back to a screen already seen is not progress, so Back and Next
+ * cannot loop, in any language. The walk stops at the first press that
+ * dispatches the action, when every reachable control has been pressed, at
+ * a cap on presses, or at its deadline. Neither the cap nor the deadline
+ * stops it while it is on the first screen with a control there still
+ * unpressed; once a press leaves the first screen both apply, and a
+ * first-screen control left unpressed is pressed only if a known route
+ * leads back to it (a one-way wizard has none).
+ */
+
+type WalkStop = "dispatched" | "explored" | "press-cap" | "deadline" | "no-mount";
+
 /**
  * 3-state outcome. Internal to runtime-render.
  * The adapter maps this to existing EvalIssue shapes:
@@ -88,8 +112,23 @@ interface RenderCheckIssue {
          * beside `{ primed: 0 }` or `{ error }` than beside `{ primed: 1 }`.
          */
         readonly inputPriming?: InputPrimingDiagnostic;
+        /** For action-wiring (ggui#1652): how far the walk over the card's screens got without dispatching the action. */
+        readonly walk?: ActionWalkDiagnostic;
     };
 }
+/**
+ * The action walk's account of an action it could not dispatch (ggui#1652):
+ * how many controls it pressed across how many screens, why it stopped,
+ * whether any screen rendered a control naming the action, and the last
+ * controls it pressed. Never the first button in the page.
+ */
+interface ActionWalkDiagnostic {
+    readonly presses: number;
+    readonly screens: number;
+    readonly stoppedBy: Exclude<WalkStop, "dispatched">;
+    readonly namedControlSeen: boolean;
+    readonly lastPressed: readonly string[];
+}
 /**
  * Outcome of `primeInputs` before the action-wiring probe (ggui#1187). A
  * priming failure never aborts the check — it is recorded here, on every
@@ -124,12 +163,21 @@ interface RenderCheckResult {
         readonly renderMs: number;
         /** Host load around an isolated check (absent in-process). */
         readonly hostLoad?: ProbeHostLoad;
+        /** ggui#1398: the pending-affordance walk, report-only; absent when no action walk ran. */
+        readonly pendingAffordance?: ProbePendingAffordance;
     };
 }
 interface RunRenderCheckInput {
     readonly sourceCode: string;
     readonly mockupProps: JsonObject;
     readonly contract?: DataContract;
+    /**
+     * Epoch ms by which the check must finish: set by the isolating host from
+     * its own bound, absent in-process. The report-only pending phase is
+     * skipped when less than {@link PENDING_PHASE_RESERVE_MS} remains, so it
+     * can never push a check past its bound (ggui#1398).
+     */
+    readonly deadlineAt?: number;
 }
 /**
  * Options of {@link runRenderCheck} (ggui#1380): the host's options —

package/dist/adapters/base.d.ts

@@ -41,8 +41,13 @@ interface ClaudeSdkConfig extends AdapterConfig {
     env?: Record<string, string>;
     /** MCP server configs for Claude Agent SDK (keyed by name) */
     mcpServers?: Record<string, McpServerConfig>;
-    /** Allowed tool names for Claude Agent SDK */
+    /** Tool names to approve. Absent → every tool of every server in `mcpServers` (ggui#1714). */
     allowedTools?: string[];
+    /**
+     * CLI built-in tools to offer the model (e.g. `['Write']`). Default: none.
+     * An explicit opt-in: a built-in that writes or executes acts on the host (ggui#1714).
+     */
+    builtinTools?: readonly string[];
     /** Subagent definitions for Claude Agent SDK */
     agents?: Record<string, AgentDefinition>;
     /** Custom CLI path for Docker deployments */

package/dist/adapters/base.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/base.ts"],"names":[],"mappings":";AA2FO,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,IAAI,MAAA,CAAO,iBAAiB,OAAO,IAAA;AACnC,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   * ggui#1185 — run on the machine's own Claude Code login instead of a key.\n   * Claude SDK adapter only. The adapter strips every provider key from the\n   * spawned env and pins the run tool-less, config-less and non-bare (see\n   * `claude/claude-code-login.ts`). Opt-in; absent ⇒ key-based auth.\n   */\n  claudeCodeLogin?: 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  if (config.claudeCodeLogin) return true;\n  return envVarNames.some((name) => !!process.env[name]);\n}\n"]}
+{"version":3,"sources":["../../src/adapters/base.ts"],"names":[],"mappings":";AAgGO,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,IAAI,MAAA,CAAO,iBAAiB,OAAO,IAAA;AACnC,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   * ggui#1185 — run on the machine's own Claude Code login instead of a key.\n   * Claude SDK adapter only. The adapter strips every provider key from the\n   * spawned env and pins the run tool-less, config-less and non-bare (see\n   * `claude/claude-code-login.ts`). Opt-in; absent ⇒ key-based auth.\n   */\n  claudeCodeLogin?: 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  /** Tool names to approve. Absent → every tool of every server in `mcpServers` (ggui#1714). */\n  allowedTools?: string[];\n  /**\n   * CLI built-in tools to offer the model (e.g. `['Write']`). Default: none.\n   * An explicit opt-in: a built-in that writes or executes acts on the host (ggui#1714).\n   */\n  builtinTools?: readonly 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  if (config.claudeCodeLogin) return true;\n  return envVarNames.some((name) => !!process.env[name]);\n}\n"]}

package/dist/adapters/generation-dispatch.d.ts

@@ -2,17 +2,18 @@ import { EvaluationConfig } from '../evaluation/types.js';
 import { RuntimeRenderCheck } from '../harness/types-public.js';
 import { ModelRoles, GenerationResult } from '../harness/result-types.js';
 import { ProviderName, ToolDefinition } from './types.js';
-import { Q as QualityConfig } from '../types-public-BJTLpzWn.js';
-import { A as AgentConfig, V as VisionProvider } from '../llm-router-nfO7wPec.js';
+import { Q as QualityConfig, b as AgentConfig, V as VisionProvider } from '../types-public-h8IMnYuh.js';
 import { DataContract, JsonObject, GadgetDescriptor } from '@ggui-ai/protocol';
-import { C as CanvasClass, D as DesignMode } from '../design-mode-DLufhrNp.js';
-import { C as CriteriaBank } from '../bank-CT4eEkta.js';
+import { C as CanvasClass, D as DesignMode } from '../design-mode-DGWN_Gkm.js';
+import { C as CriteriaBank } from '../bank-Ctdp3FUA.js';
 import { G as GenerationProfileInput } from '../styling-profile-CxfvV48g.js';
-import { R as RenderingContext } from '../prompts-YU9piOgs.js';
+import { R as RenderingContext } from '../prompts-BhNUuRoZ.js';
 import '../axes-CKVCzR_x.js';
 import '../llm.js';
 import '../types-Dh1s4K9j.js';
 import '../policy.js';
+import '../visual-evaluator-C2strxqD.js';
+import 'puppeteer-core';
 import 'zod';
 import '@ggui-ai/mcp-server-core';
 
@@ -83,6 +84,8 @@ interface GenerationDispatchParams {
         /** ggui#1436 — see `SingleComponentParams.visualEvaluation.criteriaBank`. */
         criteriaBank?: CriteriaBank;
         criteriaKind?: string;
+        /** ggui#1542 — see `SingleComponentParams.visualEvaluation.actOn`. */
+        actOn?: "critical" | "major";
     };
     /** Quality config controlling eval tiers and improvement behavior */
     qualityConfig?: QualityConfig;