@ggui-ai/ui-gen 0.23.0 → 0.25.0

package/dist/workflows.d.ts

@@ -1,10 +1,11 @@
-import { C as Classification } from './axes-CzLEMDeB.js';
+import { C as Classification } from './axes-CKVCzR_x.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './styling-profile-CxfvV48g.js';
-import './types-public-Ow-tNtFE.js';
+import './types-public-BJTLpzWn.js';
+import '@ggui-ai/mcp-server-core';
 import './design-mode-DLufhrNp.js';
-import './types-BOvHNG7K.js';
+import './types-Dh1s4K9j.js';
 import './llm.js';
 import './policy.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.23.0",
+  "version": "0.25.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": [
@@ -189,9 +189,9 @@
     "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.23.0",
-    "@ggui-ai/protocol": "0.23.0",
-    "@ggui-ai/project-config": "0.23.0"
+    "@ggui-ai/project-config": "0.25.0",
+    "@ggui-ai/mcp-server-core": "0.25.0",
+    "@ggui-ai/protocol": "0.25.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -233,11 +233,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.23.0",
-    "@ggui-ai/gadgets": "0.23.0",
-    "@ggui-ai/sandbox": "0.23.0",
-    "@ggui-ai/wire": "0.23.0",
-    "@ggui-ai/ui-visual-tester": "0.23.0"
+    "@ggui-ai/design": "0.25.0",
+    "@ggui-ai/ui-visual-tester": "0.25.0",
+    "@ggui-ai/gadgets": "0.25.0",
+    "@ggui-ai/sandbox": "0.25.0",
+    "@ggui-ai/wire": "0.25.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -252,9 +252,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.23.0",
-    "@ggui-ai/project-config": "0.23.0",
-    "@ggui-ai/protocol": "0.23.0"
+    "@ggui-ai/mcp-server-core": "0.25.0",
+    "@ggui-ai/project-config": "0.25.0",
+    "@ggui-ai/protocol": "0.25.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/generation-dispatch.ts

@@ -33,11 +33,15 @@ import { buildSystemPrompt as buildSystemPromptWithFunnel } from "../harness/run
 // predicate against the full registry and passes the filtered result.
 import { REGISTRY as AXIS_CHECK_REGISTRY } from "../evaluation/axis-checks/registry.js";
 import { matches as axisCheckMatches } from "../evaluation/types-public.js";
-// Runtime-render default. The `createHarness` constructor accepts an
-// optional runtimeRender; this callsite injects
-// `DEFAULT_RUNTIME_RENDER_CHECK` so production keeps the happy-dom-
-// backed contract-wiring verification step.
+// Runtime-render check. The `createHarness` constructor accepts an
+// optional runtimeRender; this callsite wires the caller's instance
+// (`params.runtimeRender`) or, absent one, `DEFAULT_RUNTIME_RENDER_CHECK`,
+// so production keeps the happy-dom-backed contract-wiring verification
+// step. The dispatch never BUILDS a check: the instance carries the
+// concurrency cap, so its lifetime must be the caller's (one per
+// generator), never one per generation.
 import { DEFAULT_RUNTIME_RENDER_CHECK } from "../harness/check/runtime-render/adapter.js";
+import type { RuntimeRenderCheck } from "../harness/types-public.js";
 import { warmupRuntimeRenderProbe } from "../harness/check/runtime-render/index.js";
 import { assembleGenerationResult } from "../harness/coding/assemble-result.js";
 import {
@@ -54,13 +58,24 @@ import type {
 import type { ProviderName, ToolDefinition } from "./types.js";
 import type { QualityConfig } from "../evaluation/types-public.js";
 import type { AgentConfig } from "../harness/llm-router.js";
-import {
-  type GadgetDescriptor,
-  type JsonObject,
-} from "@ggui-ai/protocol";
+import { type GadgetDescriptor, type JsonObject } from "@ggui-ai/protocol";
 import { canvasForRendering, type CanvasClass, type DesignMode } from "../design-mode.js";
+import type { VisionProvider } from "../harness/llm-router.js";
+import type { CriteriaBank } from "../evaluation/criteria/bank.js";
 import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 
+/**
+ * ggui#1250 — the in-loop VISUAL judge as its own agent: a vision provider (typed so an OpenAI judge cannot
+ * be written), a model, and — when the caller resolves provider keys itself — that provider's key, which
+ * becomes the agent's own `routeOverride`. Never the coding agent's route: where this exists (an OpenAI
+ * coding lane), the coding key is another provider's.
+ */
+export interface VisualEvalAgentSpec {
+  readonly provider: VisionProvider;
+  readonly model: string;
+  readonly apiKey?: string;
+}
+
 export interface GenerationDispatchParams {
   provider: ProviderName;
   model: string;
@@ -108,6 +123,9 @@ export interface GenerationDispatchParams {
      * the same box. See `VisualEvalConfig.canvasViewports`.
      */
     canvasViewports?: Partial<Readonly<Record<CanvasClass, { width: number; height: number }>>>;
+    /** ggui#1436 — see `SingleComponentParams.visualEvaluation.criteriaBank`. */
+    criteriaBank?: CriteriaBank;
+    criteriaKind?: string;
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;
@@ -118,20 +136,38 @@ export interface GenerationDispatchParams {
    */
   fixtureProps?: JsonObject;
   /**
-   * Whether to wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's
-   * check leg. When `true` (default), the probe runs every coding turn
-   * and feeds wiring-check failures back to the coding agent — useful
-   * for quality gating but ~3-5s per call adds wall-clock per turn.
+   * Whether to wire the runtime-render check (`runtimeRender` when given,
+   * else `DEFAULT_RUNTIME_RENDER_CHECK`) into the harness's check leg.
+   * When `true` (default), the runtime-render probe runs ONCE
+   * at the exit decision, after the coding turns, in an isolated
+   * subprocess — never on the per-turn hot path. Without an `evaluation`
+   * config that round is observe + one repair turn (ggui#1380): a
+   * recoverable render crash buys exactly one repair turn and one
+   * re-probe, then the generation serves what it has; a probe that timed
+   * out, could not run, or had nothing to probe never blocks and never
+   * repairs. With an `evaluation` config the probe is the evaluation
+   * round's exit gate. Its status and timing land on
+   * `evalResult.runtimeProbe` (and on the generation's metadata through
+   * `createUiGenerator`).
    *
-   * When `false`, the harness omits runtime-render from the in-loop
-   * check pipeline. Cloud production runs with this off (per the
-   * migration plan — probe was never in the production hot path).
-   * Bench callers can run the probe externally as a final post-gen
-   * check to get pass/fail visibility without slowing the loop.
+   * When `false`, the harness omits runtime-render entirely: no probe
+   * round runs, and a caller can run the probe externally as a final
+   * post-generation check instead.
    *
    * Default: `true`.
    */
   enableRuntimeRender?: boolean;
+  /**
+   * The runtime-render check to wire (ggui#1380) — built by the CALLER with
+   * `createRuntimeRenderCheck(config)` and kept for the caller's lifetime,
+   * because the check instance owns the probe's concurrency cap: one
+   * instance per generator bounds the workers a serving deployment has
+   * live at once; one per dispatch would give every generation its own
+   * free slots and bound nothing. Absent ⇒ `DEFAULT_RUNTIME_RENDER_CHECK`
+   * (the evaluation lane's bounds, no concurrency cap). Only read when
+   * `enableRuntimeRender` is on.
+   */
+  runtimeRender?: RuntimeRenderCheck;
   /**
    * Operator-registered gadget catalog forwarded to the
    * code-gen system prompt's `clientCapabilities — registered
@@ -171,6 +207,13 @@ export interface GenerationDispatchParams {
    * existing behavior for callers that don't set it.
    */
   routeOverride?: AgentConfig["routeOverride"];
+  /**
+   * ggui#1250 — the in-loop visual judge named as its own agent (see {@link VisualEvalAgentSpec}).
+   * Absent (default, every existing caller): today's chain, `visualEval ← evaluation ← coding`, which on
+   * a lane without a vision path records the score half as skipped (#1248). Off by default; a measurement
+   * knob first, a product knob only by ruling.
+   */
+  visualEvalAgent?: VisualEvalAgentSpec;
   /**
    * Retry observer (#489) — see `AgentConfig.onRetry`. Threaded onto
    * the coding + evaluation agent specs so a rate-limited retry inside
@@ -200,7 +243,9 @@ export interface GenerationDispatchParams {
  * Map ProviderName ('claude' | 'openai' | 'google') to AgentConfig provider ('anthropic' | 'openai' | 'google').
  * The LLM router uses 'anthropic' while the rest of the codebase uses 'claude'.
  */
-function mapProviderForLLMRouter(provider: ProviderName): "anthropic" | "openai" | "google" | "openrouter" {
+function mapProviderForLLMRouter(
+  provider: ProviderName
+): "anthropic" | "openai" | "google" | "openrouter" {
   return provider === "claude" ? "anthropic" : provider;
 }
 
@@ -209,7 +254,7 @@ function mapProviderForLLMRouter(provider: ProviderName): "anthropic" | "openai"
  * provider-agnostic.
  */
 export async function dispatchGeneration(
-  params: GenerationDispatchParams,
+  params: GenerationDispatchParams
 ): Promise<GenerationResult> {
   // NOTE: userPrompt arrives already enriched with rendering context + contract
   // (including examples) from the caller (runner.ts / generator.ts).
@@ -247,8 +292,17 @@ export async function dispatchGeneration(
         onRetry: params.onRetry,
       }
     : undefined;
-  // ModelRoles doesn't currently expose a visualEval slot — falls through
-  // to the documented evaluation → coding chain inside resolveSessionAgents.
+  // ggui#1250 — the in-loop visual judge as its own agent when named: its own provider and its own key
+  // route, never the coding agent's. Absent: today's chain, visualEval ← evaluation ← coding, inside
+  // resolveSessionAgents (ModelRoles has no visualEval slot — a role is a model, and this needs a provider).
+  const visualEvalAgent = params.visualEvalAgent
+    ? {
+        provider: params.visualEvalAgent.provider,
+        model: params.visualEvalAgent.model,
+        ...(params.visualEvalAgent.apiKey !== undefined ? { routeOverride: { apiKey: params.visualEvalAgent.apiKey } } : {}),
+        onRetry: params.onRetry,
+      }
+    : undefined;
 
   // ── Contract enrichment ──────────────────────────────────────────────
   // The contract is used as-is: `clientCapabilities.gadgets`
@@ -294,17 +348,13 @@ export async function dispatchGeneration(
     // from '<package>'` lines for thin contract refs. The closure
     // capture below (systemPromptBuilder) wires the SAME catalog
     // into the HOW leg.
-    ...(params.appGadgets !== undefined
-      ? { appGadgets: params.appGadgets }
-      : {}),
+    ...(params.appGadgets !== undefined ? { appGadgets: params.appGadgets } : {}),
     // Forward the third-party wrapper `.d.ts` map so
     // `WhatLeg.gadgetTypes` reaches the coding-agent's typecheck
     // overlay (autoCommit → runTier0Checks → typecheck). The
     // systemPromptBuilder closure below also captures `gadgetTypes`
     // from `params` directly for the prompt `Type:` lines.
-    ...(params.gadgetTypes !== undefined
-      ? { gadgetTypes: params.gadgetTypes }
-      : {}),
+    ...(params.gadgetTypes !== undefined ? { gadgetTypes: params.gadgetTypes } : {}),
     // Design mode + canvas — the harness carries them to every leg.
     ...(params.designMode !== undefined ? { designMode: params.designMode } : {}),
     // ggui#1117 — the canvas is ALWAYS carried: a stated one, else the class
@@ -334,7 +384,15 @@ export async function dispatchGeneration(
     // prompt's gadget catalog renders a `Type:` line per third-party
     // gadget (the LLM sees a wrapper's real call shape it otherwise
     // can't know).
-    systemPromptBuilder: ({ userRequest, shellType, screen, axisDelta, designMode, canvas, profile }) =>
+    systemPromptBuilder: ({
+      userRequest,
+      shellType,
+      screen,
+      axisDelta,
+      designMode,
+      canvas,
+      profile,
+    }) =>
       buildSystemPromptWithFunnel(
         userRequest,
         shellType,
@@ -344,29 +402,30 @@ export async function dispatchGeneration(
         params.gadgetTypes,
         designMode,
         canvas,
-        profile,
+        profile
       ),
     // Pre-filtered axis-check registry. The `matches()` predicate
     // selects the checks relevant to this generation's axis vector.
     axisChecks: AXIS_CHECK_REGISTRY.filter((check) =>
-      axisCheckMatches(classification.vector, check),
+      axisCheckMatches(classification.vector, check)
     ),
-    // The default runtime-render check. Heavy deps (happy-dom + wire +
-    // design) stay on the dispatch side of the boundary; the skeleton
-    // createHarness defaults this to undefined.
+    // The runtime-render check, built under the caller's probe config.
+    // Heavy deps (happy-dom + wire + design) stay on the dispatch side of
+    // the boundary; the skeleton createHarness defaults this to undefined.
     //
     // Gated behind `enableRuntimeRender` (default true) so
     // benchmark/dev callers can opt out of in-loop probe execution and
     // run the probe externally as a final post-generation check.
-    runtimeRender: (params.enableRuntimeRender ?? true)
-      ? DEFAULT_RUNTIME_RENDER_CHECK
-      : undefined,
+    runtimeRender:
+      (params.enableRuntimeRender ?? true)
+        ? (params.runtimeRender ?? DEFAULT_RUNTIME_RENDER_CHECK)
+        : undefined,
   });
   console.log(
-    `[harness] id=${harness.id} name=${harness.name} workflow=${harness.process.workflow.name} overrides=${harness.meta.overrides.join(",") || "none"}`,
+    `[harness] id=${harness.id} name=${harness.name} workflow=${harness.process.workflow.name} overrides=${harness.meta.overrides.join(",") || "none"}`
   );
   console.log(
-    `[simple] axis-vector: ${JSON.stringify(classification.vector)} risk=${classification.riskTier}`,
+    `[simple] axis-vector: ${JSON.stringify(classification.vector)} risk=${classification.riskTier}`
   );
 
   // ── Guard: staged workflow is not wired on the dispatch path. ──
@@ -392,7 +451,7 @@ export async function dispatchGeneration(
         `This is a misconfiguration (probably pickProcessMode returning WORKFLOWS.staged). ` +
         `For staged-like behaviour, set process.mode="staged" + workflow.name="single_pass" instead — the A1 ` +
         `scaffold→fill phase machine lives inside the generate runner and fires without the workflow topology. ` +
-        `See ralph #3 report (2026-04-14) for the full rationale.`,
+        `See ralph #3 report (2026-04-14) for the full rationale.`
     );
   }
 
@@ -400,6 +459,7 @@ export async function dispatchGeneration(
   const agents = resolveSessionAgents({
     codingAgent,
     evaluationAgent,
+    ...(visualEvalAgent !== undefined ? { visualEvalAgent } : {}),
   });
 
   // ── Runtime policy resolution ──
@@ -409,29 +469,58 @@ export async function dispatchGeneration(
   // resolveRunPolicyForProfile falls through to the identity
   // resolveRunPolicy — byte-identical to the default behavior.
   const { resolveRunPolicyForProfile } = await import("../harness/policy.js");
-  const resolvedPolicy = resolveRunPolicyForProfile(
-    process.env.GGUI_POLICY_PROFILE,
-    harness,
-    { provider: routerProvider, modelId: resolvedModel },
-  );
+  const resolvedPolicy = resolveRunPolicyForProfile(process.env.GGUI_POLICY_PROFILE, harness, {
+    provider: routerProvider,
+    modelId: resolvedModel,
+  });
 
-  // ── Axis-keyed primitives doc slice ──
-  // When the resolved policy flips to axis-keyed, rebuild the first-turn
-  // system prompt with a sliced PRIMITIVES_DOCUMENTATION derived from the
-  // classification. The slice typically cuts the system prompt by ~80 KB
-  // (~20K tokens). Surface awareness is preserved — the name-only primitive
-  // catalog already lives in the system prompt above the sliced block.
-  // Always logs `[simple] primitive-doc-bytes` telemetry so both modes
-  // are auditable post-hoc.
+  // ── The primitives reference the first-turn prompt carries ──
+  // The system prompt embeds PRIMITIVES_DOCUMENTATION (markdown) verbatim.
+  // Three policy knobs decide what is SENT in its place, composed in this
+  // order (ggui#1324, speed/002 — the slice applies to the format in force;
+  // slicing the markdown before the TS swap sent a sliced markdown doc about
+  // the size of the full TS doc, which speed/001 measured as a trim):
+  //   1. primitiveDocFormat: "markdown" (the embedded doc) or "ts" (its
+  //      TypeScript-interface form, ~55% smaller, same information);
+  //   2. primitiveDocSlice: "full", or an axis-keyed allowlist from the
+  //      classification ("axis-keyed", or "axis-keyed+contract" which adds the
+  //      inputs the contract implies) applied to THAT format's doc;
+  //   3. primitiveIndex: a name-only index that replaces whatever is left
+  //      (tool-driven docs; wins when on).
+  // Every cell logs `[simple] primitive-doc-bytes … mode=…` (the slice) and
+  // `[simple] system-prompt-bytes … doc-format=… doc-bytes=…` (what is sent),
+  // so a prompt-size claim is auditable from the log, not inferred.
   let systemPromptOverride: string | undefined;
   {
     const { PRIMITIVES_DOCUMENTATION } = await import("../validation/index.js");
     const fullBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION, "utf8");
+    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
+    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
     const mode = resolvedPolicy.context.primitiveDocSlice ?? "full";
-    if (mode === "axis-keyed") {
-      const { computePrimitiveAllowlist, slicePrimitiveDocumentation } =
-        await import("../harness/primitive-slice.js");
+
+    let doc = PRIMITIVES_DOCUMENTATION;
+    if (docFormat === "ts" && indexMode === "off") {
+      const { PRIMITIVES_DOCUMENTATION_TS } = await import("../tools/get-primitives-ts.js");
+      doc = PRIMITIVES_DOCUMENTATION_TS;
+      const tsBytes = Buffer.byteLength(doc, "utf8");
+      console.log(
+        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`
+      );
+    }
+    const formatBytes = Buffer.byteLength(doc, "utf8");
+
+    if (mode === "axis-keyed" || mode === "axis-keyed+contract") {
+      const {
+        computePrimitiveAllowlist,
+        computeContractPrimitives,
+        slicePrimitiveDocumentation,
+        slicePrimitiveDocumentationTs,
+      } = await import("../harness/primitive-slice.js");
       let allowlist = computePrimitiveAllowlist(classification);
+      if (mode === "axis-keyed+contract") {
+        const fromContract = computeContractPrimitives(effectiveContract);
+        allowlist = [...new Set([...allowlist, ...fromContract])].sort();
+      }
       // Apply policy-driven excludes — some policy profiles drop
       // near-synonym layout primitives (e.g. Row/Box/Spacer).
       const excludes = resolvedPolicy.context.primitiveDocExcludes ?? [];
@@ -439,61 +528,41 @@ export async function dispatchGeneration(
         const excludeSet = new Set(excludes);
         allowlist = allowlist.filter((p) => !excludeSet.has(p));
       }
-      const sliced = slicePrimitiveDocumentation(
-        PRIMITIVES_DOCUMENTATION,
-        allowlist,
-      );
-      const slicedBytes = Buffer.byteLength(sliced, "utf8");
+      doc =
+        docFormat === "ts" && indexMode === "off"
+          ? slicePrimitiveDocumentationTs(doc, allowlist)
+          : slicePrimitiveDocumentation(doc, allowlist);
+      const slicedBytes = Buffer.byteLength(doc, "utf8");
       const excludeTag = excludes.length ? ` excludes=${excludes.join(",")}` : "";
       console.log(
-        `[simple] primitive-doc-bytes=${slicedBytes} mode=axis-keyed baseline=${fullBytes} drop=${((1 - slicedBytes / fullBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`,
-      );
-      systemPromptOverride = harness.how.systemPrompt.replace(
-        PRIMITIVES_DOCUMENTATION,
-        sliced,
+        `[simple] primitive-doc-bytes=${slicedBytes} mode=${mode} baseline=${formatBytes} drop=${((1 - slicedBytes / formatBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`
       );
     } else {
       console.log(
-        `[simple] primitive-doc-bytes=${fullBytes} mode=full baseline=${fullBytes} drop=0.0%`,
+        `[simple] primitive-doc-bytes=${formatBytes} mode=full baseline=${formatBytes} drop=0.0%`
       );
     }
 
     // ── Tool-driven primitive docs ──
-    // Layers on top of axis-keyed slicing — if slicing already trimmed
-    // the doc, the index replaces whatever's left. When both are
-    // active, the index wins (it is a more aggressive cut). The two are
-    // mutually exclusive in practice via profile selection; this
-    // ordering just defines the tiebreak.
-    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
+    // A name-only index replaces whatever is left (it is the more
+    // aggressive cut). The two are mutually exclusive in practice via
+    // profile selection; this ordering just defines the tiebreak.
     if (indexMode !== "off") {
       const { buildPrimitiveIndex } = await import("../harness/primitive-index.js");
-      const index = buildPrimitiveIndex(PRIMITIVES_DOCUMENTATION, indexMode);
-      const indexBytes = Buffer.byteLength(index, "utf8");
+      doc = buildPrimitiveIndex(PRIMITIVES_DOCUMENTATION, indexMode);
+      const indexBytes = Buffer.byteLength(doc, "utf8");
       console.log(
-        `[simple] primitive-index-bytes=${indexBytes} mode=${indexMode} baseline=${fullBytes} drop=${((1 - indexBytes / fullBytes) * 100).toFixed(1)}%`,
-      );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION,
-        index,
+        `[simple] primitive-index-bytes=${indexBytes} mode=${indexMode} baseline=${fullBytes} drop=${((1 - indexBytes / fullBytes) * 100).toFixed(1)}%`
       );
     }
 
-    // ── TypeScript-interface processed doc ──
-    // Replace the markdown-table doc with the TS-interface format
-    // version (~55% smaller, same info). Mutually exclusive with index
-    // modes.
-    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
-    if (docFormat === "ts" && indexMode === "off") {
-      const { PRIMITIVES_DOCUMENTATION_TS } = await import("../tools/get-primitives-ts.js");
-      const tsBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION_TS, "utf8");
-      console.log(
-        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`,
-      );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION,
-        PRIMITIVES_DOCUMENTATION_TS,
-      );
+    if (doc !== PRIMITIVES_DOCUMENTATION) {
+      systemPromptOverride = harness.how.systemPrompt.replace(PRIMITIVES_DOCUMENTATION, doc);
     }
+    const sentPrompt = systemPromptOverride ?? harness.how.systemPrompt;
+    console.log(
+      `[simple] system-prompt-bytes=${Buffer.byteLength(sentPrompt, "utf8")} doc-format=${docFormat === "ts" && indexMode === "off" ? "ts" : docFormat} doc-bytes=${Buffer.byteLength(doc, "utf8")} mode=${indexMode !== "off" ? `index:${indexMode}` : mode}`
+    );
 
     // ── plan→impl pipeline augmentation ──
     // Append a 2-phase flow description when planFirstTurn is active so
@@ -548,7 +617,7 @@ export async function dispatchGeneration(
     console.error(
       `[dispatch] runHarness terminated: ${runResult.reason} ` +
         `(source=${runResult.finalSource ? runResult.finalSource.length + "B" : "null"}, ` +
-        `compiled=${runResult.finalCompiled ? runResult.finalCompiled.length + "B" : "null"})`,
+        `compiled=${runResult.finalCompiled ? runResult.finalCompiled.length + "B" : "null"})`
     );
   }
 
@@ -560,7 +629,11 @@ export async function dispatchGeneration(
   // `assembleGenerationResult` is async — the spread below must see the
   // RESOLVED result, never the promise (a spread promise is `{}`: every
   // consumer downstream lost `compiledCode` / `tokens` on 2026-09-09).
-  const result: GenerationResult = await assembleGenerationResult({ session, telemetry, source: finalSource });
+  const result: GenerationResult = await assembleGenerationResult({
+    session,
+    telemetry,
+    source: finalSource,
+  });
   // Record the arm this generation ran under (bench reports read it per
   // cell). The canvas is the one the free prompt stated: explicit when
   // passed, else the same shell × screen derivation the prompt used.
@@ -579,11 +652,13 @@ export async function dispatchGeneration(
  */
 function withArmRecord(
   result: GenerationResult,
-  params: Pick<GenerationDispatchParams, "designMode" | "canvas" | "shellType" | "screen">,
+  params: Pick<GenerationDispatchParams, "designMode" | "canvas" | "shellType" | "screen">
 ): GenerationResult {
   const recordedCanvas: CanvasClass | undefined =
     params.canvas ??
-    (params.designMode === "free" ? canvasForRendering(params.shellType, params.screen) : undefined);
+    (params.designMode === "free"
+      ? canvasForRendering(params.shellType, params.screen)
+      : undefined);
   return {
     ...result,
     ...(params.designMode !== undefined ? { designMode: params.designMode } : {}),

package/src/adapters/tools.ts

@@ -20,7 +20,8 @@ import { validateAllContracts } from '../check/index.js';
 import { typecheck } from '../check/index.js';
 import { lintReactHooks } from '../check/index.js';
 import ts from 'typescript';
-import { tryRender, generateSampleProps } from '../tools/render-check.js';
+import { tryRender } from '../tools/render-check.js';
+import { generateSampleProps } from '../check/sample-props.js';
 
 /**
  * Context for creating generator tools.

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

@@ -212,7 +212,7 @@ With raw elements YOU own the semantics — nothing is accessible by constructio
 3. **Images have \`alt\`** (\`alt=""\` for decorative). Icon-only buttons need \`aria-label\`; decorative icons and emoji are \`aria-hidden="true"\`.
 4. **Live & streaming data** (a \`useStream\` \`.latest\` value, counters, clocks, flashing prices) sits in an \`aria-live="polite"\` (or \`role="status"\`) region so screen readers announce the change.
 5. **Headings nest**: one \`<h1>\` per screen, \`<h2>\` for sections, \`<h3>\` below — never skipped or inverted.
-6. **Busy state is announced**: \`<button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting…' : 'Submit'}</button>\`.
+6. **Busy state is announced**: every control that dispatches an action (a button, a select whose change dispatches, an input that sends on Enter) stays pending from \`useActionPending('<action>')\` until the agent's answer repaints the card — \`<button disabled={sendPending} aria-busy={sendPending}>{sendPending ? 'Sending…' : 'Send'}</button>\`. Only a control that dispatches the action carries its busy look; while it is pending, other controls of the same record may be disabled — nothing more (controls of other records, creation controls and the action's own cancel stay enabled); busy state the card owns (\`isLoading\`) the same way.
 7. **Stateful controls announce state**: \`role="checkbox"\` + \`aria-checked\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check mark) is never the only carrier of state.
 8. **Focus is visible** — style \`:focus-visible\` with a token color; never \`outline: none\` without a replacement.`;
 

package/src/boilerplate/generate.ts

@@ -230,6 +230,7 @@ export function generateBoilerplate(
   const actionTypeAliases: string[] = [];
   const actionHookCalls: string[] = [];
   const actionReturnFields: string[] = [];
+  let hasOneShotAction = false;
   const actionsMap: ActionSpec = contract?.actionSpec ?? {};
   for (const [key, entry] of Object.entries(actionsMap)) {
     const label = entry.label ?? key;
@@ -274,7 +275,29 @@ export function generateBoilerplate(
     // instruction for every action. So it stays, ALONE on the hook line — what
     // sits next to it is part of what it says.
     const onceHint = " — if this is meant ONCE, disable its control after it fires";
-    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
+    // ggui#1223 (rnd reliability/013, arm C): an action the contract DECLARES
+    // `oneShot` gets its spent state as data, pre-bound beside the dispatcher —
+    // WHAT to code, beside HOW — and the generic once-hint leaves ITS line only:
+    // left there, the hint steered the model to a local `useState(false)` guard
+    // against the prompt's block (arm B: 0 of 6 declared cells used the hook).
+    // The generic hint stays verbatim on every undeclared action.
+    if (entry.oneShot === true) {
+      hasOneShotAction = true;
+      actionHookCalls.push(
+        `  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint} — declared oneShot: the runtime drops a second dispatch`,
+      );
+      actionHookCalls.push(
+        `  const ${key}Spent = useActionSpent('${key}'); // true once fired, also after a reload — render the control from THIS: disabled={${key}Spent} and a spent label`,
+      );
+    } else {
+      actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
+    }
+    // ggui#1398 — the dispatch's in-flight state, bound at the site the model
+    // writes the control (reliability/013: a rule alone reached 1/6, the
+    // binding 6/6).
+    actionHookCalls.push(
+      `  const ${key}Pending = useActionPending('${key}'); // true from the tap until the agent's answer repaints the card — render EVERY control that dispatches '${key}' (a Button, a Select's onChange, an Input's Enter) from THIS: disabled={${key}Pending} aria-busy={${key}Pending}, and a working label on a button; no other control carries its aria-busy`,
+    );
     actionReturnFields.push(key);
   }
 
@@ -507,6 +530,8 @@ export function generateBoilerplate(
 
   const wireHooks: string[] = [];
   if (hasActions) wireHooks.push("useAction");
+  if (hasOneShotAction) wireHooks.push("useActionSpent");
+  if (hasActions) wireHooks.push("useActionPending");
   if (hasStream) wireHooks.push("useStream");
   if (hasContext) wireHooks.push("useGguiContext");
   const wireImport = hasAnyWireFromWire

package/src/boilerplate/hard-sections.ts

@@ -214,29 +214,29 @@ Rules:
 2. Layout and styling are universal. Colors, spacing, structure — these are the reusable part.
 3. Default values come from the current request — so the component renders correctly standalone.
 4. Copy comes from the props. NEVER invent display text the contract does not carry — no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** — not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` — UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it. An action's control shows the contract's \`label\` VERBATIM — every character, including \`&\`, \`/\`, \`–\` and quotes — never paraphrased, shortened or re-cased (\`"Confirm & Schedule"\` is not \`"Confirm Schedule"\`).
-5. Props interface must be typed and exported.`;
+5. Props interface must be typed and exported.
+6. Keys on a mapped list come from the item's own identity: \`key={item.id}\` when the contract gives an id; when the items carry none (KPI tiles \`{label, value}\`, forecast days \`{day, high}\`), key by the field that names each one — \`key={item.label}\`, \`key={day.day}\` — never by the map index: a reorder or a stream merge re-keys by index and re-mounts the wrong rows, and the self-check refuses an index key.`;
 
 /**
  * A control that fires an action the user would not mean to repeat must not
- * stay armed (ggui#1108 MITIGATION — the fix is one-shot-ness DECLARED on the
- * action and enforced by the runtime; this reduces exposure meanwhile). Both
- * arms, one HARD section: the model knows from the request and the contract
- * which actions are terminal, which no static rule of ours can infer.
+ * stay armed (ggui#1108). One-shot-ness is DECLARED on the action
+ * (`actionSpec.<name>.oneShot`), enforced by the runtime, and readable by the
+ * component through `useActionSpent` (ggui#1223) — so a declared action's
+ * control renders from data that survives a reload, and the local-state guard
+ * remains only as the fallback for an action the contract failed to declare.
+ * Both arms, one HARD section: the contract says which actions are once; where
+ * it does not, the request may, and no static rule of ours can infer it from a
+ * verb.
  */
 export const TERMINAL_ACTIONS = `## Actions the user means once
 
 A second press is a mistake only when it would make a SECOND THING HAPPEN IN THE WORLD — a second booking, a second charge, a second order, a second application sent. If pressing again would only write the SAME STATE AGAIN — saving, updating, renaming, setting a preference, toggling — nothing is duplicated and the control stays armed.
 
-Guard a control only where you have evidence, not a feeling about the verb: the request itself names a one-time commitment — "submit the application", "place the order", "confirm the booking".
+**The contract says which actions are once.** An action the contract declares \`oneShot: true\` (in the Contract block above) is guarded by the runtime — a second dispatch is dropped — and its spent state is DATA you read, never state you hold: render its control from \`const spent = useActionSpent('<name>')\`, \`disabled={spent}\`, and say so in the label or beside it ("Submitted", "Request sent") — a control that is disabled without explanation reads as broken. The hook's answer survives a reload and a second tab; \`useState(false)\` does not, so a reloaded card built on local state re-arms a control that already fired.
 
-**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked — save, edit, save again is ordinary. A control left armed is only what every interface does by default.
+**An action the contract does not declare \`oneShot\` stays armed.** Never guard one from a feeling about the verb — "confirm", "submit", "place" alone are not evidence. Guard it only where the request itself names a one-time commitment the contract failed to declare ("submit the application", "place the order"), and then with local state as the fallback: \`const [submitted, setSubmitted] = useState(false)\` set in the handler, \`disabled={submitted}\` with a label — knowing that this state lives with the component, not with the request, and starts fresh on a re-render with new props.
 
-When you do guard one:
-- Hold a small piece of state for it and set it in the handler: \`const [submitted, setSubmitted] = useState(false)\`.
-- \`disabled={submitted}\` on the control that fires it, and say so in the label or beside it ("Submitted", "Request sent") — a control that is disabled without explanation reads as broken.
-- A card re-rendered with new props starts fresh; the state above lives with the component, not with the request.
-
-Nothing in the wire DECLARES one-shot-ness yet, which is why the test is what a second press would DO — not how final the word sounds.`;
+**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked — save, edit, save again is ordinary. A control left armed is only what every interface does by default.`;
 
 /**
  * The frame owns the height — the component never sizes itself to the