@ggui-ai/ui-gen 0.9.0 → 0.11.0

package/src/adapters/openrouter/types.ts

@@ -127,6 +127,16 @@ export class OpenRouterError extends Error {
     message: string,
     public readonly status: number,
     public readonly code?: string,
+    /**
+     * Response headers, when the caller had access to them at throw
+     * time (#489). Only `client.ts`'s two HTTP-response-driven throw
+     * sites populate this — the "no response body" throw has no
+     * response to read headers from. Duck-typed against the same
+     * `{ get(name): string | null }` shape `llm-router.ts`'s
+     * `extractRetryAfterSec` already reads from Anthropic/OpenAI SDK
+     * errors, so OpenRouter gets retry-after support for free.
+     */
+    public readonly headers?: { get(name: string): string | null },
   ) {
     super(message);
     this.name = 'OpenRouterError';

package/src/boilerplate/generate.ts

@@ -191,14 +191,22 @@ export function generateBoilerplate(
   const propsFields: string[] = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
-    const required = entry.required !== false;
+    // Required is OPT-IN (`required === true`) — the same reading the
+    // wire gate applies (`contract-validator.ts` builds the JSON-Schema
+    // `required` list from `=== true`), the contract summary's `!`
+    // marker uses, and coverage annotates with. The old `!== false`
+    // reading typed omitted-`required` props as always-present, so a
+    // render the gate legitimately accepts (agent omits an optional
+    // prop) crashed on `props.x.map(...)` — ggui#528.
+    const required = entry.required === true;
     const nullable = entry.schema.nullable === true;
     const tsType = jsonSchemaTypeToTs(entry.schema);
     const fullType = nullable ? `${tsType} | null` : tsType;
-    // Build comment: description + default value hint
+    // Build comment: description + default hint + optionality contract
     const parts: string[] = [];
     if (entry.description) parts.push(entry.description);
     if (entry.default !== undefined) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    if (!required) parts.push("(optional — the agent may omit it; guard or fall back)");
     const desc = parts.length > 0 ? ` // ${parts.join(' ')}` : "";
     propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }

package/src/boilerplate/json-schema-ts.ts

@@ -35,6 +35,21 @@ export function jsonSchemaTypeToTs(schema: JsonSchema): string {
       .join(' | ');
   }
 
+  // ── Draft-07 type array (`['string','null']` — the canonical
+  // nullable form since draft-2026-08-19): members' TS union. Each
+  // member re-enters with the single type so object/array members
+  // keep their properties/items; `nullable` is folded in here (not in
+  // the recursion) so it can't double-append. ──
+  if (Array.isArray(schema.type)) {
+    const { nullable: _nullable, ...rest } = schema;
+    const members = [...new Set(schema.type)].map((member) =>
+      jsonSchemaTypeToTs({ ...rest, type: member }),
+    );
+    const unique = [...new Set(members)];
+    if (schema.nullable && !unique.includes('null')) unique.push('null');
+    return unique.join(' | ');
+  }
+
   let result: string;
 
   switch (schema.type) {
@@ -54,8 +69,13 @@ export function jsonSchemaTypeToTs(schema: JsonSchema): string {
     case 'array': {
       if (schema.items) {
         const itemType = jsonSchemaTypeToTs(schema.items);
-        // Use Array<T> for complex object types, T[] for simple
-        result = (schema.items.type === 'object' && schema.items.properties)
+        // Use Array<T> for complex object types, T[] for simple.
+        // `items.type` may be a type SET — treat any set containing
+        // 'object' like the single-string form.
+        const itemsDeclareObject = Array.isArray(schema.items.type)
+          ? schema.items.type.includes('object')
+          : schema.items.type === 'object';
+        result = (itemsDeclareObject && schema.items.properties)
           ? `Array<${itemType}>`
           : (itemType.includes('|') ? `(${itemType})[]` : `${itemType}[]`);
       } else {

package/src/boilerplate/system-prompt.ts

@@ -349,6 +349,7 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
 
+- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY — the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
 - **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
 - **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
 - **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.

package/src/compile.ts

@@ -153,7 +153,7 @@ export async function compileComponentCode(source: string): Promise<string> {
  * `response.sourceCode` so downstream consumers that want human-readable
  * source (benchmarks, blueprint cache seeding) still have it.
  *
- *   const raw = createUiGenerator({ adapter });
+ *   const raw = createUiGenerator();
  *   const oss = withBrowserCompile(raw);
  *   const out = await oss.generate({ ... });
  *   // out.response.componentCode → ESM (browser-ready)

package/src/contract-context.ts

@@ -257,11 +257,19 @@ export function buildContractsContext(
   const uiRequirements: string[] = [];
   if (contract.propsSpec?.properties) {
     for (const [name, entry] of Object.entries(contract.propsSpec.properties)) {
-      const required = (entry as { required?: boolean }).required;
-      if (required !== false) {
+      // Opt-in required (`=== true`) — the wire gate's reading, ggui#528.
+      // An omitted-`required` prop is OPTIONAL: the agent may leave it
+      // out of a legitimate render, so the derived instruction must
+      // demand a presence-safe component, not unconditional display.
+      const required = (entry as { required?: boolean }).required === true;
+      if (required) {
         uiRequirements.push(
           `- **Required prop \`${name}\`** must appear somewhere in rendered DOM (display the value, or use it to drive a label/aria/key).`,
         );
+      } else {
+        uiRequirements.push(
+          `- **Optional prop \`${name}\`** may be ABSENT at runtime — the component must render without it (guard the access or apply its default) and must display it when it IS provided.`,
+        );
       }
     }
   }

package/src/create-ui-generator.ts

@@ -61,6 +61,7 @@ import {
 import type { RenderingContext } from './contract-context.js';
 import { resolveRoute, applyRouteToEnv } from './adapters/provider-router.js';
 import type { QualityConfig } from './evaluation/types-public.js';
+import type { AgentConfig } from './harness/llm-router.js';
 
 /** The slug for the OSS default seed generator. */
 const DEFAULT_TIER: GeneratorTier = 'default';
@@ -151,6 +152,17 @@ export interface CreateUiGeneratorOptions {
    * for callers that don't need concurrent generations in-process.
    */
   readonly disableEnvMutation?: boolean;
+  /**
+   * Retry observer (#489) — see `AgentConfig.onRetry`. Bound ONCE at
+   * factory construction time (mirrors `disableEnvMutation`), not
+   * per-call: `generate()` is invoked once per request, but the
+   * generator instance itself is typically long-lived and cached by
+   * the caller, so a single observer covers every generation it runs.
+   * Fires whenever any agent's `apiCall()` retries a rate-limited
+   * request. Absent (default) is a no-op — retries still happen and
+   * still log via `console.warn`, just without a caller-side hook.
+   */
+  readonly onRetry?: AgentConfig['onRetry'];
 }
 
 export function createUiGenerator(
@@ -163,6 +175,7 @@ export function createUiGenerator(
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
+    onRetry,
   } = options;
 
   const identity = resolveIdentity(options);
@@ -302,6 +315,7 @@ export function createUiGenerator(
             : {}),
           enableRuntimeRender,
           ...(routeOverride !== undefined ? { routeOverride } : {}),
+          ...(onRetry !== undefined ? { onRetry } : {}),
         });
 
         const metadata: GenerationMetadata = {

package/src/design-system-docs.ts

@@ -54,10 +54,12 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 - Borders/dividers → \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
 ### State Colors
-- var(--ggui-color-success) — success states
-- var(--ggui-color-warning) — warning states
-- var(--ggui-color-error) — error states, destructive actions
-- var(--ggui-color-info) — informational
+Semantic families ship as SCALES; the \`500\` stop is the role color (per-mode brightness), \`50\` the tint, \`800\` the on-tint text:
+- var(--ggui-color-success-500) — success states (tint bg: success-50, text on tint: success-800)
+- var(--ggui-color-warning-500) — warning states (warning-50 / warning-800)
+- var(--ggui-color-error-500) — error states, destructive actions (error-50 / error-800)
+- var(--ggui-color-info-500) — informational (info-50 / info-800)
+Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-written vars — it resolves to the same stops.
 
 ### IMPORTANT: Color Rules
 - **NEVER** use hardcoded hex colors. ONLY use var(--ggui-color-*) tokens.

package/src/evaluation/axis-checks/checks/state-ui-affordance.ts

@@ -0,0 +1,162 @@
+// packages/ui-gen/src/evaluation/axis-checks/checks/state-ui-affordance.ts
+//
+// `state.ui_affordance.state_aria_present` (ggui#408) — a hand-rolled
+// stateful control must expose its state in ARIA.
+//
+// Why this is a DETERMINISTIC check and not (only) an LLM criterion:
+// the Experiment-53 baseline showed the defect class is structurally
+// invisible to the LLM leg — `state=ui-affordance` with no writes
+// classifies `riskTier=low`, and the low-risk bypass skips tier-1+2
+// entirely, so 10/10 ARIA-less generations were never evaluated at
+// all. Axis checks run BEFORE the bypass decision, and a `fail` among
+// them disables the bypass for that round — which both surfaces the
+// finding and routes it into the coding loop. Prototype validation
+// against the 27-cell baseline corpus: precision 1.00, recall 0.80
+// (both false negatives closed here: lowercase tags — `<div
+// as={Clickable}>` is the WORSE variant since `as` is inert on a
+// native element — and callback-prop indirection in extracted
+// subcomponents).
+//
+// Detection predicate (v2 — "the element's own onClick mutates the
+// affordance state"; v1's styling-dataflow precondition scored recall
+// 0.30, do not resurrect it): an element fires when its `onClick`
+// references a `useState` setter, a local handler that calls one, or
+// an `on[A-Z]…` callback prop (extracted-subcomponent shape) — AND it
+// is not a semantics-owning primitive, carries no state ARIA
+// (`aria-checked/pressed/selected/expanded/current` or any `role=`),
+// and contains no state-carrying primitive in its subtree (pushing
+// duplicate ARIA onto a wrapper around `<Checkbox>` is itself a
+// defect the judge fails — never demand it).
+//
+// Gate: `{axis: "state", values: ["ui-affordance"]}` ONLY. The
+// predicate must not reach `state=payload/draft` (form-field wrappers
+// with onClick would false-flag) or `state=merge` (kanban's per-item
+// onClick is a MOVE, not a boolean affordance).
+
+import type { EvalIssue } from "../../types-public.js";
+import type { AxisCheck, AxisCheckInput } from "../types.js";
+import { mkIssue } from "../helpers.js";
+
+const STATE_ARIA_OR_ROLE = /aria-(checked|pressed|selected|expanded|current)\s*=|role\s*=/;
+const STATE_PRIMITIVE_IN_SUBTREE = /<(Checkbox|Toggle|Tabs|Accordion)[\s/>]/;
+/** Primitives that own their own interaction semantics — never flagged. */
+const SEMANTIC_PRIMITIVES = new Set(["Button", "Checkbox", "Toggle", "Link", "MenuItem"]);
+
+/** Collect `const [x, setX] = useState(...)` setter names. */
+function collectSetters(src: string): Set<string> {
+  const setters = new Set<string>();
+  for (const m of src.matchAll(/const\s*\[\s*\w+\s*,\s*(set\w+)\s*\]\s*=\s*useState/g)) {
+    setters.add(m[1]);
+  }
+  return setters;
+}
+
+/** Collect local handler names whose body (nearby) calls a setter. */
+function collectHandlers(src: string, setters: Set<string>): Set<string> {
+  const handlers = new Set<string>();
+  for (const m of src.matchAll(/const\s+(\w+)\s*=\s*(?:\([^)]*\)|\w+)\s*=>\s*\{?/g)) {
+    const body = src.slice(m.index + m[0].length, m.index + m[0].length + 400);
+    for (const s of setters) {
+      if (body.includes(s)) {
+        handlers.add(m[1]);
+        break;
+      }
+    }
+  }
+  return handlers;
+}
+
+/** The attribute block of an opening tag: from after the tag name to its `>` (brace-aware). */
+function attrBlock(src: string, start: number): { block: string; end: number } {
+  let depth = 0;
+  for (let i = start; i < src.length; i++) {
+    const c = src[i];
+    if (c === "{") depth++;
+    else if (c === "}") depth--;
+    else if (c === ">" && depth === 0) return { block: src.slice(start, i), end: i };
+  }
+  return { block: src.slice(start, start + 900), end: start + 900 };
+}
+
+/** The brace-balanced expression of `onClick={…}`, or null when absent. */
+function onClickValue(block: string): string | null {
+  const m = block.match(/onClick\s*=\s*\{/);
+  if (!m || m.index === undefined) return null;
+  const open = m.index + m[0].length - 1;
+  let depth = 0;
+  for (let i = open; i < block.length; i++) {
+    if (block[i] === "{") depth++;
+    else if (block[i] === "}") {
+      depth--;
+      if (depth === 0) return block.slice(open + 1, i);
+    }
+  }
+  return block.slice(open + 1);
+}
+
+function subtree(src: string, pos: number, tag: string): string {
+  const close = src.indexOf(`</${tag}>`, pos);
+  return src.slice(pos, close === -1 ? pos + 700 : close);
+}
+
+function runStateAriaPresent(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const setters = collectSetters(src);
+  const handlers = collectHandlers(src, setters);
+  const issues: EvalIssue[] = [];
+  const flaggedLines = new Set<number>();
+
+  // Locally-defined components: their CALL SITES can never satisfy the
+  // check (the ARIA lives inside the definition, which this check
+  // already covers via the callback-prop clause) — flagging the call
+  // site is a permanently-unresolvable finding that stalls the
+  // eval-fix loop in the recurrence guard (Experiment 54: exactly the
+  // 2/27 stuck cells). Skip call sites of components defined in this
+  // file; the definition's own inner element carries the check.
+  const localComponents = new Set<string>();
+  for (const m of src.matchAll(/(?:function\s+([A-Z]\w*)\s*\(|const\s+([A-Z]\w*)\s*=)/g)) {
+    localComponents.add(m[1] ?? m[2]);
+  }
+
+  for (const m of src.matchAll(/<([A-Za-z][A-Za-z0-9]*)\b/g)) {
+    const tag = m[1];
+    if (m.index === undefined) continue;
+    if (localComponents.has(tag)) continue;
+    const { block, end } = attrBlock(src, m.index + m[0].length);
+    const clickValue = onClickValue(block);
+    if (clickValue === null) continue;
+    const mutatesAffordance =
+      [...setters].some((s) => clickValue.includes(s)) ||
+      [...handlers].some((h) => new RegExp(`\\b${h}\\b`).test(clickValue)) ||
+      // Extracted-subcomponent shape: the toggle handler arrives as an
+      // `on[A-Z]…` callback prop and is invoked from onClick — inside a
+      // ui-affordance component that IS the affordance mutation.
+      /\bon[A-Z]\w*\b/.test(clickValue);
+    if (!mutatesAffordance) continue;
+    if (SEMANTIC_PRIMITIVES.has(tag)) continue;
+    if (STATE_ARIA_OR_ROLE.test(block)) continue;
+    if (STATE_PRIMITIVE_IN_SUBTREE.test(subtree(src, end, tag))) continue;
+
+    const line = src.slice(0, m.index).split("\n").length;
+    if (flaggedLines.has(line)) continue;
+    flaggedLines.add(line);
+    issues.push(
+      mkIssue(
+        "state.ui_affordance.state_aria_present",
+        `Line ${line}: <${tag}> toggles the UI affordance from its onClick but exposes no state ARIA — its checked/selected/expanded state is invisible to assistive technology (styling is the only carrier).`,
+        `Add the matching state attribute to the SAME element that carries the onClick: \`role="checkbox"\` + \`aria-checked={…}\` for a toggle row, \`aria-pressed\` for a toggle button, \`aria-selected\` for a selection, \`aria-expanded\` for an open/close affordance — or replace the hand-rolled control with the state-carrying primitive (Checkbox / Toggle / Tabs / Accordion). \`as={Clickable}\` adds button + keyboard semantics but NOT state.`,
+      ),
+    );
+  }
+  return issues;
+}
+
+export const STATE_UI_AFFORDANCE_CHECKS: readonly AxisCheck[] = [
+  {
+    id: "state.ui_affordance.state_aria_present",
+    axis: "state",
+    values: ["ui-affordance"],
+    run: runStateAriaPresent,
+  },
+];

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

@@ -71,6 +71,14 @@ export interface LLMEvalConfig {
    * `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. */
@@ -756,7 +764,12 @@ export async function runLLMEvaluation(
   // 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 });
+  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 {
@@ -247,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,
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -358,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,
@@ -377,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/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