@ggui-ai/ui-gen 0.8.0 → 0.10.0

package/src/evaluation/axis-checks/registry.ts

@@ -6,6 +6,7 @@
 import type { AxisCheck } from "./types.js";
 import { UNIVERSAL_CHECKS } from "./checks/universal.js";
 import { STATE_MERGE_CHECKS } from "./checks/state-merge.js";
+import { STATE_UI_AFFORDANCE_CHECKS } from "./checks/state-ui-affordance.js";
 import { REALTIME_CHECKS } from "./checks/realtime.js";
 import { WRITES_CHECKS } from "./checks/writes.js";
 import { STATE_PAYLOAD_CHECKS } from "./checks/state-payload.js";
@@ -15,6 +16,7 @@ import { EXTRA_CHECKS } from "./extras.js";
 export const REGISTRY: readonly AxisCheck[] = [
   ...UNIVERSAL_CHECKS,
   ...STATE_MERGE_CHECKS,
+  ...STATE_UI_AFFORDANCE_CHECKS,
   ...REALTIME_CHECKS,
   ...WRITES_CHECKS,
   ...STATE_PAYLOAD_CHECKS,

package/src/evaluation/index.ts

@@ -71,3 +71,14 @@ export type {
 } from './types.js';
 export { runAxisChecks } from './axis-checks/index.js';
 export type { RunAxisChecksInput } from './axis-checks/index.js';
+
+// The visual judge's raw multimodal call — arbitrary prompt + screenshot
+// Buffer, routed through the same `createVisionAgent`/`apiCall()` choke
+// point as every in-loop evaluation call (the #504 contract). Exposed so
+// standalone visual-judging instruments (host-fit probes, external
+// benches) can reuse the judging machinery WITHOUT entering the in-loop
+// rubric — scoring generation on criteria the generator was never taught
+// is a constraint-alignment violation, so out-of-loop judges get this
+// seam instead of a rubric extension.
+export { callMultimodalLLM } from './visual-evaluator.js';
+export type { VisualEvalConfig } from './visual-evaluator.js';

package/src/evaluation/llm-evaluator.ts

@@ -16,7 +16,7 @@
 
 import type { EvalIssue, EvalResult, EvalCategory } from './types-public.js';
 import { createAgent } from '../harness/llm-router';
-import type { LLMToolDef, LLMAgent } from '../harness/llm-router';
+import type { AgentConfig, LLMToolDef, LLMAgent } from '../harness/llm-router';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { getCriterionById } from './types-public.js';
 
@@ -64,6 +64,21 @@ export interface LLMEvalContext {
 export interface LLMEvalConfig {
   provider: 'claude' | 'openai' | 'google' | 'openrouter';
   model?: string;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded onto the agent this
+   * evaluator constructs so it never falls back to reading
+   * `process.env`. Absent (default) preserves existing behavior.
+   */
+  routeOverride?: AgentConfig['routeOverride'];
+  /**
+   * Provider-429-retry observer (#489) — see `AgentConfig.onRetry`.
+   * Threaded onto the agent this evaluator constructs so a rate-limited
+   * retry inside an evaluation turn's `apiCall()` reaches the same
+   * caller the coding leg reaches. Absent (default) preserves existing
+   * behavior (retries still happen; no observer fires).
+   */
+  onRetry?: AgentConfig['onRetry'];
 }
 
 /** A request-specific evaluation criterion generated by the LLM. */
@@ -745,8 +760,16 @@ export async function runLLMEvaluation(
     .map((line, i) => `${String(i + 1).padStart(4)} | ${line}`)
     .join('\n');
 
-  // Create a single agent — all calls share the same client + cache
-  const agent = createAgent(routerProvider);
+  // Create a single agent — all calls share the same client + cache.
+  // Pass the full config (not just the bare provider string) so a
+  // caller-supplied `routeOverride` (#484) reaches the constructed
+  // `LLMAgent` instance and it never falls back to `process.env`.
+  const agent = createAgent({
+    provider: routerProvider,
+    model,
+    routeOverride: config.routeOverride,
+    onRetry: config.onRetry,
+  });
 
   // Dynamic criteria removed — they generated overly strict edge-case checks
   // that wasted coding turns on nitpicks. Will be replaced by a holistic

package/src/evaluation/visual-evaluator.ts

@@ -16,6 +16,7 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
+import { createVisionAgent, type AgentConfig } from '../harness/llm-router';
 import type { EvaluationResult, EvaluationIssue, DimensionScores } from './types';
 import type { EvalIssue } from './types-public.js';
 
@@ -34,6 +35,20 @@ export interface VisualEvalConfig {
   sampleProps?: Record<string, unknown>;
   /** Viewport dimensions for screenshot */
   viewport?: { width: number; height: number };
+  /**
+   * Optional provider-routing override — see
+   * `AgentConfig.routeOverride`. Threaded onto the agent this
+   * evaluator constructs so its multimodal call never falls back to
+   * `process.env` for credentials or model routing.
+   */
+  routeOverride?: AgentConfig['routeOverride'];
+  /**
+   * Provider-429-retry observer — see `AgentConfig.onRetry`.
+   * Without it, a rate-limited retry inside the evaluation call
+   * happens (the agent's retry loop is unconditional) but never
+   * reaches the caller's structured log.
+   */
+  onRetry?: AgentConfig['onRetry'];
 }
 
 export interface VisualEvalContext {
@@ -185,7 +200,11 @@ async function captureScreenshot(
     const browser = await puppeteer.default.launch(launchOptions);
     try {
       const page = await browser.newPage();
-      await page.setContent(html, { waitUntil: 'networkidle0', timeout: 15000 });
+      // puppeteer ≥24.43 narrowed setContent's waitUntil to
+      // 'load' | 'domcontentloaded'; waitForNetworkIdle (0 connections
+      // for 500ms) reproduces the old 'networkidle0' semantics.
+      await page.setContent(html, { waitUntil: 'load', timeout: 15000 });
+      await page.waitForNetworkIdle({ idleTime: 500, timeout: 15000 }).catch(() => {});
       await page.waitForSelector('#root > *', { timeout: 10000 }).catch(() => {});
       // Wait a bit for CSS/fonts to settle
       await new Promise(r => setTimeout(r, 1000));
@@ -243,75 +262,37 @@ Respond with ONLY a JSON object (no markdown, no explanation):
   "critique": "<2-3 sentences: what's good, what needs improvement, does it achieve the user's goal?>"
 }`;
 
-interface VisualProviderResponse {
-  text: string;
-  inputTokens: number;
-  outputTokens: number;
-}
-
+/**
+ * Send the screenshot to the configured multimodal provider through
+ * the shared `LLMAgent` machinery. Routing through `createVisionAgent`
+ * (rather than constructing provider SDK clients inline) is what puts
+ * this call inside the same `apiCall()` choke point as every other
+ * completion: provider 429s retry with `Retry-After` honoring, the
+ * caller's `onRetry` observer sees each retry, and `routeOverride`
+ * governs credentials and model routing (including the Anthropic
+ * Bedrock path) instead of `process.env`.
+ */
 async function callMultimodalLLM(
-  provider: 'claude' | 'google',
+  config: VisualEvalConfig,
   model: string,
   prompt: string,
   screenshot: Buffer,
   originalPrompt: string,
-): Promise<VisualProviderResponse> {
+) {
   const userPrompt = `## Original Request\n${originalPrompt}\n\nEvaluate the screenshot of the generated component.`;
-
-  if (provider === 'claude') {
-    const { default: Anthropic } = await import('@anthropic-ai/sdk');
-    const client = new Anthropic({
-      apiKey: process.env.ANTHROPIC_API_KEY,
-      baseURL: 'https://api.anthropic.com',
-    });
-    const response = await client.messages.create({
-      model: model.startsWith('anthropic/') ? model.slice(10) : model,
-      max_tokens: 1500,
-      system: prompt,
-      messages: [{
-        role: 'user',
-        content: [
-          {
-            type: 'image',
-            source: {
-              type: 'base64',
-              media_type: 'image/png',
-              data: screenshot.toString('base64'),
-            },
-          },
-          { type: 'text', text: userPrompt },
-        ],
-      }],
-    });
-    return {
-      text: response.content.filter(b => b.type === 'text').map(b => b.text).join(''),
-      inputTokens: response.usage.input_tokens,
-      outputTokens: response.usage.output_tokens,
-    };
-  }
-
-  // Google Gemini
-  const { GoogleGenAI } = await import('@google/genai');
-  const client = new GoogleGenAI({
-    apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
-  });
-  const response = await client.models.generateContent({
-    model: model.startsWith('google/') ? model.slice(7) : model,
-    contents: [{
-      role: 'user',
-      parts: [
-        { inlineData: { mimeType: 'image/png', data: screenshot.toString('base64') } },
-        { text: userPrompt },
-      ],
-    }],
-    config: { systemInstruction: prompt },
+  const agent = createVisionAgent({
+    provider: config.provider === 'claude' ? 'anthropic' : config.provider,
+    model,
+    routeOverride: config.routeOverride,
+    onRetry: config.onRetry,
   });
-  const usage = response.usageMetadata;
-  return {
-    text: response.candidates?.[0]?.content?.parts?.map(p => p.text || '').join('') || '',
-    inputTokens: usage?.promptTokenCount ?? 0,
-    outputTokens: usage?.candidatesTokenCount ?? 0,
-  };
+  return agent.callVision(
+    model,
+    prompt,
+    userPrompt,
+    { mediaType: 'image/png', base64: screenshot.toString('base64') },
+    1500,
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -354,7 +335,7 @@ export async function runVisualEvaluation(
   // Send to multimodal LLM
   const model = config.model ?? getDefaultVisualModel(config.provider);
   const response = await callMultimodalLLM(
-    config.provider,
+    config,
     model,
     VISUAL_EVAL_PROMPT,
     screenshot,
@@ -373,9 +354,11 @@ export async function runVisualEvaluation(
 }
 
 /**
- * Exported for testing — bundles and builds the HTML for rendering.
+ * Exported for testing — bundles and builds the HTML for rendering;
+ * `callMultimodalLLM` so the #504 routing contract (config →
+ * `createVisionAgent`) is assertable without a screenshot pipeline.
  */
-export { bundleForRendering, buildRenderHTML };
+export { bundleForRendering, buildRenderHTML, callMultimodalLLM };
 
 // ---------------------------------------------------------------------------
 // Response parsing

package/src/fragments/realtime.ts

@@ -16,14 +16,14 @@ export const realtimeFragments: Record<string, HarnessFragment> = {
     value: "merge",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\n```\n\nNever append — stream=merge means the entity already exists locally.",
+      "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\n```\n\nNever append — stream=merge means the entity already exists locally.",
   },
   append: {
     axis: "realtime",
     value: "append",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.",
+      "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.",
   },
   status: {
     axis: "realtime",
@@ -44,7 +44,7 @@ export const realtimeFragments: Record<string, HarnessFragment> = {
     value: "mixed",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\n\nExample (chat-interface — message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.",
+      "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\n\nExample (chat-interface — message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => setMessageList(props.messages), [props.messages]); // re-seed on ggui_amend repaint\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.",
     boilerplateMarker: [
       "",
       "  // ── Mixed stream handlers ──",

package/src/fragments/state.ts

@@ -24,11 +24,11 @@ export const stateFragments: Record<string, HarnessFragment> = {
     value: "merge",
     cacheTier: "axisDelta",
     promptText:
-      "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])`.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
+      "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])` AND re-seed on prop change: `useEffect(() => setItems(props.items ?? []), [props.items])` — a `ggui_amend` repaint must move the list.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
     boilerplateMarker: [
       "",
       "  // ── Live entity state (merge-by-id) ──",
-      "  // useState(props.items ?? []); merge stream events by item.id; never append.",
+      "  // useState(props.items ?? []); re-seed via useEffect on [props.items]; merge stream events by item.id; never append.",
       "",
     ].join("\n"),
   },

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

@@ -217,6 +217,24 @@ function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
         fix: classifyRenderCrashFix(issue.reason),
       };
 
+    case "optional-props-omitted":
+      // Same crash class as render-no-throw, surfaced by the second
+      // render pass with optional props stripped (ggui#528): the wire
+      // gate only requires `required: true` props, so a legitimate
+      // render may omit these and the component must survive it.
+      return {
+        tier: 0,
+        result,
+        category: "crash",
+        subcategory,
+        severity: "critical",
+        description: `Component crashed when optional props were omitted: ${issue.reason}`,
+        fix:
+          `Guard every optional prop before member access (props.${subject.split(",")[0]?.trim() ?? "x"}?.map(...), ` +
+          `a default via destructuring, or an early empty-state return). Optional props (no \`required: true\` in the contract) ` +
+          `may be absent at runtime even though the harness fills them.`,
+      };
+
     case "action-wiring": {
       const fix = issue.outcome === "unverified"
         ? `Source shows the action callback flowing into a non-native or custom-component prop. If wiring is intentional (e.g., Dropdown.onChange, drag-drop), this warn is informational — manual/browser verification is required to confirm. Otherwise wire to a native onClick={() => ${subject}(payload)} on <button> or design-system <Button>.`

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

@@ -9,6 +9,8 @@
 //   - declared props appear in the DOM                      (warn)
 //   - declared stream events update the DOM when emitted    (warn)
 
+import { installProductionActShim } from "./production-act-shim.js";
+
 export { runRenderCheck, type RenderCheckResult, type RenderCheckIssue } from "./render-check.js";
 export { createProbe, createProbeWireConfig, type Probe } from "./probe.js";
 export { prepareMockupProps, type MockupPropsResult } from "./prepare-mockup.js";
@@ -51,6 +53,12 @@ export async function warmupRuntimeRenderProbe(): Promise<{ ms: number; loaded:
       missing += 1;
     }
   };
+  // Must run before RTL's first import in this process — hosts that
+  // call this warmup at process start (server-side blueprint
+  // validation) land RTL in the module cache, with its act snapshot
+  // taken, here — long before the first real probe call. See
+  // production-act-shim.ts's docstring for why.
+  installProductionActShim();
   await Promise.all([
     tryLoad("happy-dom"),
     tryLoad("@testing-library/react"),

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

@@ -152,6 +152,20 @@ function synthesizeFromSchema(
     return synthesizeFromSchema(schema.anyOf[0], hint, warnings, depth + 1);
   }
 
+  // Draft-07 type array (`['string','null']` — the canonical nullable
+  // form since draft-2026-08-19): synthesize from the first non-null
+  // member ('null' only when it is the sole member). The depth guard
+  // above bounds the recursion.
+  if (Array.isArray(schema.type)) {
+    const primary = schema.type.find((t) => t !== "null") ?? "null";
+    return synthesizeFromSchema(
+      { ...schema, type: primary },
+      hint,
+      warnings,
+      depth + 1,
+    );
+  }
+
   switch (schema.type) {
     case "string": {
       // Format-aware placeholder

package/src/harness/check/runtime-render/production-act-shim.ts

@@ -0,0 +1,158 @@
+// packages/ui-gen/src/harness/check/runtime-render/production-act-shim.ts
+//
+// Minimal adaptation to two upstream constraints, neither of which
+// this package controls:
+//
+//   1. React intentionally strips `act` from its PRODUCTION build.
+//      `react/cjs/react.production.js` does not export it — only the
+//      development build does (`typeof require('react').act` is
+//      `'function'` under a dev build, `undefined` under production).
+//   2. `@testing-library/react`'s `act-compat` module hard-requires
+//      `act` at MODULE SCOPE: it snapshots
+//      `typeof React.act === 'function' ? React.act : DeprecatedReactTestUtils.act`
+//      into a `const` the first time it is imported in the process.
+//      Under a production build, that snapshot resolves to React
+//      DOM's `react-dom/test-utils` production `act` stub, which
+//      THROWS `React.act is not a function` the moment it is called.
+//
+// Hosts that run this probe inside a production Node process
+// (server-side blueprint validation) hit this: every render throws
+// through RTL's `act` wrapper before the probe ever sees the
+// component. Hosts that run it under a development/test build (every
+// CI/vitest run in this repo — `NODE_ENV=test` resolves the dev
+// build) never see it; `act` is real there and this shim is a no-op.
+//
+// **Load-order constraint**: this MUST run before the FIRST import of
+// `@testing-library/react` anywhere in the process — act-compat binds
+// its `act` reference into a module-scope `const` at import time, so
+// patching `react-dom/test-utils` AFTER that import has already
+// happened does nothing (the snapshot already captured the broken
+// stub). Patch `react-dom/test-utils`, never `react` itself — that
+// entry point is deprecated and test-only, so this patch cannot
+// perturb any production rendering path; nothing else in a server
+// process legitimately imports it.
+//
+// `createRequire` (not `import`) reaches these modules deliberately:
+// ESM namespace objects are frozen, so a normal `import` gives no way
+// to mutate `act` on it. The CJS `module.exports` objects `require`
+// resolves are mutable, and RTL's act-compat interop-copies THAT
+// object's properties at its own load time — so mutating it here,
+// before RTL loads, is what makes the patch visible to RTL at all.
+
+import { createRequire } from "node:module";
+
+let installed = false;
+
+/**
+ * The one property this module reads/mutates on `react` and
+ * `react-dom/test-utils`'s CJS exports. A minimal local shape rather
+ * than the real (deprecated, possibly absent) type declarations for
+ * `react-dom/test-utils` — narrow enough to type-check the mutation
+ * without `as any` / `Record<string, unknown>`.
+ */
+interface MutableActCarrier {
+  act?: unknown;
+}
+
+/** The one React DOM export this module needs — typed narrowly for the same reason. */
+interface FlushSyncCarrier {
+  flushSync: (fn: () => void) => void;
+}
+
+/**
+ * Patch `react-dom/test-utils`'s `act` with a `flushSync`-backed
+ * replacement, but ONLY when the current process is running React's
+ * production build (no real `act` exported). Idempotent — safe to
+ * call more than once or from more than one call site; the actual
+ * patch only ever applies once per process.
+ *
+ * No-op (by design, not by accident) whenever `react`'s own `act`
+ * export is a real function — every dev/test build, including every
+ * vitest run in this repo. This shim changes zero behavior in CI.
+ */
+export function installProductionActShim(): void {
+  if (installed) return;
+  installed = true;
+
+  const require_ = createRequire(import.meta.url);
+
+  let reactCjs: MutableActCarrier;
+  try {
+    reactCjs = require_("react");
+  } catch {
+    // React itself isn't resolvable in this process — the probe
+    // surfaces its own load error; nothing for this shim to patch.
+    return;
+  }
+
+  if (typeof reactCjs.act === "function") {
+    // Dev/test builds export a real `act` — strict no-op.
+    return;
+  }
+
+  try {
+    const testUtils: MutableActCarrier = require_("react-dom/test-utils");
+    const reactDom: FlushSyncCarrier = require_("react-dom");
+    testUtils.act = createFlushSyncAct(reactDom.flushSync);
+  } catch {
+    // Frozen/locked exports (or a react-dom build without flushSync)
+    // — leave it. The probe then surfaces the raw upstream error,
+    // which is the pre-fix behavior: an honest failure, not a
+    // silently-broken patch.
+  }
+}
+
+/**
+ * Build an `act`-compatible replacement backed by `flushSync`, which
+ * — unlike `act` — DOES exist in React's production build.
+ *
+ * `flushSync` is the single property this shim relies on from dev
+ * `act`: it forces the scheduled render to commit SYNCHRONOUSLY
+ * before returning, so a render throw propagates synchronously to the
+ * caller and the DOM is fully committed by the time this resolves.
+ *
+ * Returned function is act-style: if the callback itself returned a
+ * thenable (RTL's async act-wrapped interactions), the result
+ * resolves once that thenable settles (rejecting on its rejection);
+ * otherwise it resolves after one microtask, mirroring `act`'s own
+ * "flush the microtask queue" contract for the synchronous case.
+ *
+ * **Known, documented delta vs. a real dev `act`**: passive effects
+ * (`useEffect`) flush on a LATER task under `flushSync`, not
+ * synchronously at act-exit — `flushSync` only guarantees the
+ * synchronous commit, not effect flushing. The probe's uncaught-error
+ * handlers plus its 100ms teardown grace window (`render-check.ts`'s
+ * `cleanupAsyncInfra`) already cover a late effect throwing after this
+ * resolves, so this delta does not reopen the crash class the probe
+ * exists to catch.
+ *
+ * Exported separately so the flushSync/thenable semantics are unit
+ * testable without a real React runtime.
+ */
+export function createFlushSyncAct(
+  flushSync: (fn: () => void) => void,
+): (callback: () => unknown) => Promise<void> {
+  return (callback: () => unknown): Promise<void> => {
+    let callbackResult: unknown;
+    flushSync(() => {
+      callbackResult = callback();
+    });
+    if (isThenable(callbackResult)) {
+      const pending = callbackResult;
+      return new Promise<void>((resolve, reject) => {
+        pending.then(() => resolve(), reject);
+      });
+    }
+    return new Promise<void>((resolve) => {
+      queueMicrotask(resolve);
+    });
+  };
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}

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

@@ -24,6 +24,7 @@ import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
 import { createProbe, createProbeWireConfig, type Probe } from "./probe.js";
 import { loadComponent } from "./load-component.js";
 import { findWiring, type WiringDetection } from "./find-wiring.js";
+import { installProductionActShim } from "./production-act-shim.js";
 // All happy-dom / RTL / user-event narrowing flows through the typed
 // host boundary (one set of structural interfaces + validating guards;
 // DOM-lib-free — some downstream packages, e.g. cloud/amplify, exclude
@@ -70,7 +71,8 @@ export interface RenderCheckIssue {
     | "render-no-throw"
     | "action-wiring"
     | "prop-coverage"
-    | "stream-rerender";
+    | "stream-rerender"
+    | "optional-props-omitted";
   readonly outcome: CheckOutcome;
   readonly subject?: string;
   readonly reason: string;
@@ -237,6 +239,9 @@ export async function runRenderCheck(
     // internals.
     uninstallSpy = probe.installPostMessageSpy();
 
+    // Must run before RTL's first import in this process — see
+    // production-act-shim.ts's docstring for why.
+    installProductionActShim();
     const { render, cleanup } = await import("@testing-library/react");
     // user-event v14 default export — see https://testing-library.com/docs/user-event/intro/
     const userEventModule = await import("@testing-library/user-event");
@@ -514,6 +519,72 @@ export async function runRenderCheck(
           if (issue) issues.push(issue);
         }
       }
+
+      // ── Check 7: Optional-props omission (BLOCK on crash, ggui#528) ──
+      // The main pass renders with EVERY declared prop filled, so a
+      // component that assumes an optional prop is present always
+      // passes here and crashes only live, when an agent legitimately
+      // omits it (the wire gate requires only `required === true`
+      // props). Render a second instance with the optional props
+      // STRIPPED — a throw is exactly the latent-undefined class this
+      // check exists to surface. Runs only when the contract declares
+      // at least one optional prop that the mockup filled; zero cost
+      // otherwise.
+      const declaredProps = input.contract?.propsSpec?.properties;
+      if (declaredProps) {
+        const optionalFilled = Object.entries(declaredProps)
+          .filter(([name, entry]) =>
+            (entry as { required?: boolean }).required !== true &&
+            input.mockupProps[name] !== undefined,
+          )
+          .map(([name]) => name);
+        if (optionalFilled.length > 0) {
+          const requiredOnlyProps: JsonObject = { ...input.mockupProps };
+          for (const name of optionalFilled) delete requiredOnlyProps[name];
+          const omitBoundaryRef: { error?: Error } = {};
+          class OmitErrorBoundary extends React.Component<
+            { children?: React.ReactNode },
+            { caught: boolean }
+          > {
+            state = { caught: false };
+            static getDerivedStateFromError(): { caught: boolean } {
+              return { caught: true };
+            }
+            componentDidCatch(error: Error): void {
+              omitBoundaryRef.error ??= error;
+            }
+            render(): React.ReactNode {
+              if (this.state.caught) return null;
+              return this.props.children;
+            }
+          }
+          try {
+            render(
+              React.createElement(GguiWireProvider, {
+                config: wireConfig,
+                children: React.createElement(OmitErrorBoundary, {
+                  children: React.createElement(Component, requiredOnlyProps),
+                }),
+              }),
+            );
+          } catch (e) {
+            omitBoundaryRef.error ??=
+              e instanceof Error ? e : new Error(String(e));
+          }
+          if (omitBoundaryRef.error) {
+            issues.push({
+              check: "optional-props-omitted",
+              outcome: "failed",
+              subject: optionalFilled.join(", "),
+              reason:
+                `Render crashed when the optional prop(s) ${optionalFilled
+                  .map((n) => `'${n}'`)
+                  .join(", ")} were omitted: ${omitBoundaryRef.error.message}. ` +
+                `The contract marks them optional (no \`required: true\`), so a legitimate render may leave them out.`,
+            });
+          }
+        }
+      }
     } finally {
       cleanup();
     }

package/src/harness/coding/init-session.ts

@@ -144,7 +144,10 @@ export async function initSession(input: {
   const systemPrompt = input.systemPromptOverride ?? harness.how.systemPrompt;
 
   // ── Create + warm-cache the coding agent ──
-  const codingAgent = createAgent(agents.coding.provider);
+  // Pass the full spec (not just `.provider`) so a caller-supplied
+  // `routeOverride` (#484) reaches the constructed `LLMAgent` instance
+  // and it never falls back to reading `process.env`.
+  const codingAgent = createAgent(agents.coding);
   await codingAgent.warmCache(
     agents.coding.model,
     systemPrompt,