@ggui-ai/ui-gen 0.9.0 → 0.10.0

package/dist/advanced/index.js

@@ -1154,14 +1154,16 @@ var OpenRouterError;
 var init_types = __esm({
   "src/adapters/openrouter/types.ts"() {
     OpenRouterError = class extends Error {
-      constructor(message, status, code) {
+      constructor(message, status, code, headers) {
         super(message);
         this.status = status;
         this.code = code;
+        this.headers = headers;
         this.name = "OpenRouterError";
       }
       status;
       code;
+      headers;
       get isTransient() {
         return this.status === 408 || this.status === 429 || this.status === 502 || this.status === 503;
       }
@@ -1206,7 +1208,7 @@ var init_client2 = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         return response.json();
       }
@@ -1224,7 +1226,7 @@ var init_client2 = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         if (!response.body) {
           throw new OpenRouterError("No response body for streaming request", 500);
@@ -2077,6 +2079,15 @@ function jsonSchemaTypeToTs(schema) {
   if (schema.enum?.length) {
     return schema.enum.map((v) => typeof v === "string" ? `'${v}'` : String(v)).join(" | ");
   }
+  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;
   switch (schema.type) {
     case "string":
@@ -2094,7 +2105,8 @@ function jsonSchemaTypeToTs(schema) {
     case "array": {
       if (schema.items) {
         const itemType = jsonSchemaTypeToTs(schema.items);
-        result = schema.items.type === "object" && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
+        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 {
         result = "unknown[]";
       }
@@ -4112,6 +4124,29 @@ function errorSummary(e) {
   }
   return `${e.constructor.name}${status}${code}: ${e.message.slice(0, 120)}${body}`;
 }
+function isRateLimited(e) {
+  if (!(e instanceof Error) || !("status" in e)) return false;
+  return e.status === 429;
+}
+function extractStatus(e) {
+  if (!(e instanceof Error) || !("status" in e)) return void 0;
+  const status = e.status;
+  return typeof status === "number" ? status : void 0;
+}
+function extractRetryAfterSec(e) {
+  if (!(e instanceof Error) || !("headers" in e)) return void 0;
+  const headers = e.headers;
+  if (headers === null || typeof headers !== "object" || !("get" in headers) || typeof headers.get !== "function") {
+    return void 0;
+  }
+  const raw = headers.get("retry-after");
+  if (raw === null) return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
 function interactionText(interaction) {
   let text = "";
   for (const step of interaction.steps ?? []) {
@@ -4136,24 +4171,38 @@ function toUserInputStep(text) {
 function createAgent(providerOrConfig) {
   const provider = typeof providerOrConfig === "string" ? providerOrConfig : providerOrConfig.provider;
   const routeOverride = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.routeOverride;
+  const onRetry = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.onRetry;
   switch (provider) {
     case "anthropic":
-      return new AnthropicAgent(routeOverride);
+      return new AnthropicAgent(routeOverride, onRetry);
     case "openai":
-      return new OpenAIAgent(routeOverride);
+      return new OpenAIAgent(routeOverride, onRetry);
     case "google":
-      return new GoogleAgent(routeOverride);
+      return new GoogleAgent(routeOverride, onRetry);
     case "openrouter":
-      return new OpenRouterAgent(routeOverride);
+      return new OpenRouterAgent(routeOverride, onRetry);
   }
 }
-var LLMAgent, AnthropicAgent, OpenAIAgent, GoogleAgent, OpenRouterAgent;
+function createVisionAgent(config) {
+  switch (config.provider) {
+    case "anthropic":
+      return new AnthropicAgent(config.routeOverride, config.onRetry);
+    case "google":
+      return new GoogleAgent(config.routeOverride, config.onRetry);
+  }
+}
+var MAX_RETRY_ATTEMPTS, RETRY_AFTER_CAP_SEC, DEFAULT_BACKOFF_BASE_MS, DEFAULT_BACKOFF_MAX_MS, MAX_TOTAL_RETRY_DELAY_MS, LLMAgent, AnthropicAgent, OpenAIAgent, GoogleAgent, OpenRouterAgent;
 var init_llm_router = __esm({
   "src/harness/llm-router.ts"() {
     init_client();
     init_provider_router();
     init_tool_bridge();
     init_llm_trace_sink();
+    MAX_RETRY_ATTEMPTS = 2;
+    RETRY_AFTER_CAP_SEC = 15;
+    DEFAULT_BACKOFF_BASE_MS = 1e3;
+    DEFAULT_BACKOFF_MAX_MS = 8e3;
+    MAX_TOTAL_RETRY_DELAY_MS = 2e4;
     LLMAgent = class {
       client = null;
       // ── Session state for server-side chaining ──────────────
@@ -4168,8 +4217,11 @@ var init_llm_router = __esm({
        * back to `process.env` exactly as before.
        */
       routeOverride;
-      constructor(routeOverride) {
+      /** See `AgentConfig.onRetry` (#489). Absent is a no-op. */
+      onRetry;
+      constructor(routeOverride, onRetry) {
         this.routeOverride = routeOverride;
+        this.onRetry = onRetry;
       }
       async getClient() {
         if (!this.client) {
@@ -4204,17 +4256,83 @@ var init_llm_router = __esm({
       async sendToolResult(_results) {
       }
       /**
-       * Execute an API call. No retry — if it fails, it fails.
-       * Logs the error with provider context and re-throws.
+       * Execute an API call, retrying once or twice on HTTP 429
+       * (rate-limited) before giving up (#489).
+       *
+       * Policy: on a 429, honor the provider's `Retry-After` header when
+       * present (capped at `RETRY_AFTER_CAP_SEC` — a provider asking for a
+       * longer wait is treated as "don't retry", not "wait longer": making
+       * the caller sit through 15+ more seconds on a single failed call is
+       * a bad experience regardless of what's driving the request);
+       * otherwise fall back to exponential backoff with jitter, capped at
+       * `DEFAULT_BACKOFF_MAX_MS` per attempt. Stops after
+       * `MAX_RETRY_ATTEMPTS` retries OR once the cumulative delay would
+       * exceed `MAX_TOTAL_RETRY_DELAY_MS`, whichever comes first. Any
+       * non-429 error, or a 429 with no attempts left, is logged and
+       * re-thrown immediately — unchanged from the pre-#489 behavior.
+       *
+       * **Budget scope (final-review correction):** `MAX_TOTAL_RETRY_DELAY_MS`
+       * bounds a single `apiCall()` invocation, not a whole generation. A
+       * generation issues many sequential `apiCall()` calls (coding turns,
+       * tool-result round-trips, eval rounds); under sustained throttling
+       * each one can independently add up to `MAX_TOTAL_RETRY_DELAY_MS`, so
+       * a generation with k rate-limited calls can add up to roughly `k *
+       * MAX_TOTAL_RETRY_DELAY_MS` to how long it holds its caller's
+       * resources (e.g. the caller's concurrency slot) — not a flat 20s
+       * ceiling. No shared per-generation budget is threaded here by
+       * design (accepted ruling, not an oversight): the caller's own
+       * queue/admission backstop is what bounds how long other
+       * queued work waits, independent of any one generation's retry
+       * total.
        */
       async apiCall(fn) {
         const start = Date.now();
-        try {
-          return await fn();
-        } catch (e) {
-          const ms = Date.now() - start;
-          console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
-          throw e;
+        let totalDelayMs = 0;
+        for (let attempt = 0; ; attempt++) {
+          try {
+            return await fn();
+          } catch (e) {
+            const ms = Date.now() - start;
+            if (attempt >= MAX_RETRY_ATTEMPTS || !isRateLimited(e)) {
+              console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
+              throw e;
+            }
+            const retryAfterSec = extractRetryAfterSec(e);
+            if (retryAfterSec !== void 0 && retryAfterSec > RETRY_AFTER_CAP_SEC) {
+              console.error(
+                `[${this.provider}] API error after ${ms}ms (retry-after ${retryAfterSec}s exceeds ${RETRY_AFTER_CAP_SEC}s cap, not retrying): ${errorSummary(e)}`
+              );
+              throw e;
+            }
+            const delayMs = retryAfterSec !== void 0 ? retryAfterSec * 1e3 : Math.min(DEFAULT_BACKOFF_BASE_MS * 2 ** attempt, DEFAULT_BACKOFF_MAX_MS) + Math.floor(Math.random() * 250);
+            if (totalDelayMs + delayMs > MAX_TOTAL_RETRY_DELAY_MS) {
+              console.error(
+                `[${this.provider}] API error after ${ms}ms (retry budget exhausted, not retrying): ${errorSummary(e)}`
+              );
+              throw e;
+            }
+            totalDelayMs += delayMs;
+            const info = {
+              provider: this.provider,
+              attempt: attempt + 1,
+              maxAttempts: MAX_RETRY_ATTEMPTS,
+              status: extractStatus(e),
+              retryAfterSec,
+              delayMs,
+              message: errorSummary(e)
+            };
+            console.warn(
+              `[${this.provider}] rate-limited (attempt ${info.attempt}/${info.maxAttempts}), retrying in ${delayMs}ms`
+            );
+            try {
+              this.onRetry?.(info);
+            } catch (observerError) {
+              console.warn(
+                `[${this.provider}] onRetry observer threw (ignored, retry proceeds): ${errorSummary(observerError)}`
+              );
+            }
+            await sleep(delayMs);
+          }
         }
       }
     };
@@ -4307,6 +4425,73 @@ var init_llm_router = __esm({
           throw e;
         }
       }
+      async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+        const client = await this.getClient();
+        const traceId = newLlmTraceId();
+        const startedAt = Date.now();
+        const resolvedModel = this.resolveModel(model);
+        const imageBlock = {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: image.mediaType,
+            data: image.base64
+          }
+        };
+        try {
+          const response = await this.apiCall(
+            () => client.messages.create({
+              model: resolvedModel,
+              max_tokens: maxTokens ?? 1500,
+              system: systemPrompt,
+              messages: [
+                {
+                  role: "user",
+                  content: [imageBlock, { type: "text", text: userPrompt }]
+                }
+              ]
+            })
+          );
+          const text = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+          const endedAt = Date.now();
+          emitLlmTraceEvent({
+            id: traceId,
+            at: startedAt,
+            endedAt,
+            durationMs: endedAt - startedAt,
+            provider: "anthropic",
+            model: resolvedModel,
+            kind: "callVision",
+            systemPrompt,
+            userPrompt,
+            result: {
+              inputTokens: response.usage.input_tokens,
+              outputTokens: response.usage.output_tokens,
+              text
+            }
+          });
+          return {
+            text,
+            inputTokens: response.usage.input_tokens,
+            outputTokens: response.usage.output_tokens
+          };
+        } catch (e) {
+          const endedAt = Date.now();
+          emitLlmTraceEvent({
+            id: traceId,
+            at: startedAt,
+            endedAt,
+            durationMs: endedAt - startedAt,
+            provider: "anthropic",
+            model: resolvedModel,
+            kind: "callVision",
+            systemPrompt,
+            userPrompt,
+            error: { message: e instanceof Error ? e.message : String(e) }
+          });
+          throw e;
+        }
+      }
       async callTools(model, systemPrompt, userPrompt, tools, toolChoice = "required", _scopedTools) {
         const client = await this.getClient();
         const traceId = newLlmTraceId();
@@ -4681,6 +4866,72 @@ var init_llm_router = __esm({
           outputTokens: interaction.usage?.total_output_tokens ?? 0
         };
       }
+      async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+        const client = await this.getClient();
+        const traceId = newLlmTraceId();
+        const startedAt = Date.now();
+        const resolvedModel = this.resolveModel(model);
+        try {
+          const response = await this.apiCall(
+            () => client.models.generateContent({
+              model: resolvedModel,
+              contents: [
+                {
+                  role: "user",
+                  parts: [
+                    { inlineData: { mimeType: image.mediaType, data: image.base64 } },
+                    { text: userPrompt }
+                  ]
+                }
+              ],
+              config: {
+                systemInstruction: systemPrompt,
+                ...maxTokens ? { maxOutputTokens: maxTokens } : {}
+              }
+            })
+          );
+          const text = response.candidates?.[0]?.content?.parts?.map((p) => p.text || "").join("") || "";
+          const usage = response.usageMetadata;
+          const result = {
+            text,
+            inputTokens: usage?.promptTokenCount ?? 0,
+            outputTokens: usage?.candidatesTokenCount ?? 0
+          };
+          const endedAt = Date.now();
+          emitLlmTraceEvent({
+            id: traceId,
+            at: startedAt,
+            endedAt,
+            durationMs: endedAt - startedAt,
+            provider: "google",
+            model: resolvedModel,
+            kind: "callVision",
+            systemPrompt,
+            userPrompt,
+            result: {
+              inputTokens: result.inputTokens,
+              outputTokens: result.outputTokens,
+              text
+            }
+          });
+          return result;
+        } catch (e) {
+          const endedAt = Date.now();
+          emitLlmTraceEvent({
+            id: traceId,
+            at: startedAt,
+            endedAt,
+            durationMs: endedAt - startedAt,
+            provider: "google",
+            model: resolvedModel,
+            kind: "callVision",
+            systemPrompt,
+            userPrompt,
+            error: { message: e instanceof Error ? e.message : String(e) }
+          });
+          throw e;
+        }
+      }
       async callTools(model, systemPrompt, userPrompt, tools, _toolChoice = "required", scopedTools) {
         const client = await this.getClient();
         const interactionTools = tools.map((t) => ({
@@ -6025,7 +6276,11 @@ async function runLLMEvaluation(context, config, preWarmedContext) {
     designSystemSummary: context.designContext
   });
   const numberedSource = context.sourceCode.split("\n").map((line, i) => `${String(i + 1).padStart(4)} | ${line}`).join("\n");
-  const agent = createAgent({ provider: routerProvider, routeOverride: config.routeOverride });
+  const agent = createAgent({
+    provider: routerProvider,
+    routeOverride: config.routeOverride,
+    onRetry: config.onRetry
+  });
   const evalStart = Date.now();
   const totalCriteriaCount = TIER_1_CRITERIA.length + TIER_2_CRITERIA.length;
   const results = await Promise.all([
@@ -9393,6 +9648,7 @@ var visual_evaluator_exports = {};
 __export(visual_evaluator_exports, {
   buildRenderHTML: () => buildRenderHTML,
   bundleForRendering: () => bundleForRendering,
+  callMultimodalLLM: () => callMultimodalLLM,
   runVisualEval: () => runVisualEval,
   runVisualEvaluation: () => runVisualEvaluation
 });
@@ -9517,63 +9773,23 @@ async function captureScreenshot(html, viewport = { width: 1280, height: 800 })
     return null;
   }
 }
-async function callMultimodalLLM(provider, model, prompt, screenshot, originalPrompt) {
+async function callMultimodalLLM(config, model, prompt, screenshot, originalPrompt) {
   const userPrompt = `## Original Request
 ${originalPrompt}
 
 Evaluate the screenshot of the generated component.`;
-  if (provider === "claude") {
-    const { default: Anthropic2 } = await import('@anthropic-ai/sdk');
-    const client2 = new Anthropic2({
-      apiKey: process.env.ANTHROPIC_API_KEY,
-      baseURL: "https://api.anthropic.com"
-    });
-    const response2 = await client2.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: response2.content.filter((b) => b.type === "text").map((b) => b.text).join(""),
-      inputTokens: response2.usage.input_tokens,
-      outputTokens: response2.usage.output_tokens
-    };
-  }
-  const { GoogleGenAI } = await import('@google/genai');
-  const client = new GoogleGenAI({
-    apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY
+  const agent = createVisionAgent({
+    provider: config.provider === "claude" ? "anthropic" : config.provider,
+    routeOverride: config.routeOverride,
+    onRetry: config.onRetry
   });
-  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 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
+  );
 }
 async function runVisualEvaluation(context, config) {
   const startTime = Date.now();
@@ -9591,7 +9807,7 @@ async function runVisualEvaluation(context, config) {
   console.log(`[visual-eval] screenshot: ${screenshot.length}B (${Date.now() - startTime}ms)`);
   const model = config.model ?? getDefaultVisualModel(config.provider);
   const response = await callMultimodalLLM(
-    config.provider,
+    config,
     model,
     VISUAL_EVAL_PROMPT,
     screenshot,
@@ -9665,6 +9881,7 @@ async function runVisualEval(context, config) {
 var VISUAL_EVAL_PROMPT;
 var init_visual_evaluator = __esm({
   "src/evaluation/visual-evaluator.ts"() {
+    init_llm_router();
     VISUAL_EVAL_PROMPT = `You are a visual quality evaluator for ggui \u2014 a platform where AI agents generate React UI components on demand.
 
 ## Context
@@ -10127,10 +10344,12 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 - Borders/dividers \u2192 \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
 ### State Colors
-- var(--ggui-color-success) \u2014 success states
-- var(--ggui-color-warning) \u2014 warning states
-- var(--ggui-color-error) \u2014 error states, destructive actions
-- var(--ggui-color-info) \u2014 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) \u2014 success states (tint bg: success-50, text on tint: success-800)
+- var(--ggui-color-warning-500) \u2014 warning states (warning-50 / warning-800)
+- var(--ggui-color-error-500) \u2014 error states, destructive actions (error-50 / error-800)
+- var(--ggui-color-info-500) \u2014 informational (info-50 / info-800)
+Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-written vars \u2014 it resolves to the same stops.
 
 ### IMPORTANT: Color Rules
 - **NEVER** use hardcoded hex colors. ONLY use var(--ggui-color-*) tokens.
@@ -10430,16 +10649,19 @@ function generateSampleProps(spec) {
   return props;
 }
 function synthesizeFromSchema(schema) {
-  switch (schema.type) {
+  const declared = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type;
+  switch (declared) {
     case "string":
       return "sample";
     case "number":
+    case "integer":
       return 0;
     case "boolean":
       return false;
+    case "null":
+      return null;
     case "array": {
-      const itemSchema = schema.items;
-      if (itemSchema) return [synthesizeFromSchema(itemSchema) ?? null];
+      if (schema.items) return [synthesizeFromSchema(schema.items) ?? null];
       return [];
     }
     case "object": {
@@ -12362,13 +12584,14 @@ function generateBoilerplate(_userPrompt, contract, shellType, screen, composedS
   const propsFields = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
-    const required = entry.required !== false;
+    const required = entry.required === true;
     const nullable = entry.schema.nullable === true;
     const tsType = jsonSchemaTypeToTs(entry.schema);
     const fullType = nullable ? `${tsType} | null` : tsType;
     const parts = [];
     if (entry.description) parts.push(entry.description);
     if (entry.default !== void 0) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    if (!required) parts.push("(optional \u2014 the agent may omit it; guard or fall back)");
     const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
     propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }
@@ -12927,6 +13150,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 \u2014 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\`.
@@ -14339,6 +14563,106 @@ var STATE_MERGE_CHECKS = [
   }
 ];
 
+// src/evaluation/axis-checks/checks/state-ui-affordance.ts
+var STATE_ARIA_OR_ROLE = /aria-(checked|pressed|selected|expanded|current)\s*=|role\s*=/;
+var STATE_PRIMITIVE_IN_SUBTREE = /<(Checkbox|Toggle|Tabs|Accordion)[\s/>]/;
+var SEMANTIC_PRIMITIVES = /* @__PURE__ */ new Set(["Button", "Checkbox", "Toggle", "Link", "MenuItem"]);
+function collectSetters(src) {
+  const setters = /* @__PURE__ */ new Set();
+  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;
+}
+function collectHandlers(src, setters) {
+  const handlers = /* @__PURE__ */ new Set();
+  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;
+}
+function attrBlock(src, start) {
+  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 };
+}
+function onClickValue(block) {
+  const m = block.match(/onClick\s*=\s*\{/);
+  if (!m || m.index === void 0) 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, pos, tag) {
+  const close = src.indexOf(`</${tag}>`, pos);
+  return src.slice(pos, close === -1 ? pos + 700 : close);
+}
+function runStateAriaPresent(input) {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const setters = collectSetters(src);
+  const handlers = collectHandlers(src, setters);
+  const issues = [];
+  const flaggedLines = /* @__PURE__ */ new Set();
+  const localComponents = /* @__PURE__ */ new Set();
+  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 === void 0) 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 \u2014 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={\u2026}\` for a toggle row, \`aria-pressed\` for a toggle button, \`aria-selected\` for a selection, \`aria-expanded\` for an open/close affordance \u2014 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;
+}
+var STATE_UI_AFFORDANCE_CHECKS = [
+  {
+    id: "state.ui_affordance.state_aria_present",
+    axis: "state",
+    values: ["ui-affordance"],
+    run: runStateAriaPresent
+  }
+];
+
 // src/evaluation/axis-checks/checks/realtime.ts
 var REALTIME_ACTIVE = ["merge", "append", "status", "presence", "mixed"];
 function runStreamHandlerPerEvent(input) {
@@ -15028,6 +15352,7 @@ var EXTRA_CHECKS = [
 var REGISTRY = [
   ...UNIVERSAL_CHECKS,
   ...STATE_MERGE_CHECKS,
+  ...STATE_UI_AFFORDANCE_CHECKS,
   ...REALTIME_CHECKS,
   ...WRITES_CHECKS,
   ...STATE_PAYLOAD_CHECKS,
@@ -15198,8 +15523,8 @@ ${cjsResult.code}
 // src/harness/check/runtime-render/load-component.ts
 async function loadComponent(input) {
   const { sourceCode, moduleResolutions = {} } = input;
-  const { createRequire: createRequire3 } = await import('module');
-  const require_ = createRequire3(import.meta.url);
+  const { createRequire: createRequire4 } = await import('module');
+  const require_ = createRequire4(import.meta.url);
   const sandboxRequire = (id) => {
     if (id in moduleResolutions) return moduleResolutions[id];
     if (id === "react/jsx-runtime" || id === "react/jsx-dev-runtime") {
@@ -15455,6 +15780,47 @@ function wrapDetection(kind, jsx, native, custom) {
 function dedupe(arr) {
   return Array.from(new Set(arr));
 }
+var installed = false;
+function installProductionActShim() {
+  if (installed) return;
+  installed = true;
+  const require_ = createRequire(import.meta.url);
+  let reactCjs;
+  try {
+    reactCjs = require_("react");
+  } catch {
+    return;
+  }
+  if (typeof reactCjs.act === "function") {
+    return;
+  }
+  try {
+    const testUtils = require_("react-dom/test-utils");
+    const reactDom = require_("react-dom");
+    testUtils.act = createFlushSyncAct(reactDom.flushSync);
+  } catch {
+  }
+}
+function createFlushSyncAct(flushSync) {
+  return (callback) => {
+    let callbackResult;
+    flushSync(() => {
+      callbackResult = callback();
+    });
+    if (isThenable(callbackResult)) {
+      const pending = callbackResult;
+      return new Promise((resolve3, reject) => {
+        pending.then(() => resolve3(), reject);
+      });
+    }
+    return new Promise((resolve3) => {
+      queueMicrotask(resolve3);
+    });
+  };
+}
+function isThenable(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
 
 // src/internal/open-record.ts
 function openRecord(o) {
@@ -15572,6 +15938,7 @@ async function runRenderCheck(input) {
     const probe = createProbe();
     const wireConfig = createProbeWireConfig(probe);
     uninstallSpy = probe.installPostMessageSpy();
+    installProductionActShim();
     const { render, cleanup } = await import('@testing-library/react');
     const userEventModule = await import('@testing-library/user-event');
     const userEvent = userEventModule.default ?? userEventModule;
@@ -15727,6 +16094,50 @@ async function runRenderCheck(input) {
           if (issue) issues.push(issue);
         }
       }
+      const declaredProps = input.contract?.propsSpec?.properties;
+      if (declaredProps) {
+        const optionalFilled = Object.entries(declaredProps).filter(
+          ([name, entry]) => entry.required !== true && input.mockupProps[name] !== void 0
+        ).map(([name]) => name);
+        if (optionalFilled.length > 0) {
+          const requiredOnlyProps = { ...input.mockupProps };
+          for (const name of optionalFilled) delete requiredOnlyProps[name];
+          const omitBoundaryRef = {};
+          class OmitErrorBoundary extends React.Component {
+            state = { caught: false };
+            static getDerivedStateFromError() {
+              return { caught: true };
+            }
+            componentDidCatch(error) {
+              omitBoundaryRef.error ??= error;
+            }
+            render() {
+              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();
     }
@@ -16298,6 +16709,15 @@ function synthesizeFromSchema2(schema, hint, warnings, depth) {
   if (schema.anyOf && schema.anyOf.length > 0) {
     return synthesizeFromSchema2(schema.anyOf[0], hint, warnings, depth + 1);
   }
+  if (Array.isArray(schema.type)) {
+    const primary = schema.type.find((t) => t !== "null") ?? "null";
+    return synthesizeFromSchema2(
+      { ...schema, type: primary },
+      hint,
+      warnings,
+      depth + 1
+    );
+  }
   switch (schema.type) {
     case "string": {
       switch (schema.format) {
@@ -16468,6 +16888,16 @@ function toEvalIssue(issue) {
         description: `Component crashed at runtime: ${issue.reason}`,
         fix: classifyRenderCrashFix(issue.reason)
       };
+    case "optional-props-omitted":
+      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 \u2014 manual/browser verification is required to confirm. Otherwise wire to a native onClick={() => ${subject}(payload)} on <button> or design-system <Button>.` : `Wire ${subject}() to a native event prop. Common fix: <Button onClick={() => ${subject}(payload)}>Label</Button>. Source-AST analysis didn't find this wiring in your JSX.`;
       return {
@@ -16514,6 +16944,7 @@ async function warmupRuntimeRenderProbe() {
       missing += 1;
     }
   };
+  installProductionActShim();
   await Promise.all([
     tryLoad("happy-dom"),
     tryLoad("@testing-library/react"),
@@ -17590,6 +18021,14 @@ function mapProviderForEvaluator(provider) {
 
 // src/harness/coding/run-eval-round.ts
 var MAX_FEEDBACK_ISSUES = 3;
+function selectActionableFeedback(issues) {
+  const pool = issues.filter((i) => i.result === "fail" || i.result === "warn");
+  const reserved = pool.find((i) => i.tier === 0 && i.result === "fail");
+  return [
+    ...reserved ? [reserved] : [],
+    ...pool.filter((i) => i !== reserved).sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1))
+  ].slice(0, MAX_FEEDBACK_ISSUES);
+}
 function fingerprintFail(issue) {
   const cat = issue.category ?? "";
   const sub = issue.subcategory ?? "";
@@ -17764,7 +18203,14 @@ async function runEvalRound(ctx, input) {
           // back to `process.env` either (the eval calls run
           // inside the same concurrent generation, so the race is
           // real here too, not just on the coding turn).
-          routeOverride: evaluationAgent.routeOverride
+          routeOverride: evaluationAgent.routeOverride,
+          // #489 — thread the same provider-429-retry observer.
+          // Without this, a rate-limited retry inside the
+          // evaluation agent's apiCall() happens (the base-class
+          // retry loop is unconditional) but never reaches the
+          // caller, silently missing the host application's
+          // structured log.
+          onRetry: evaluationAgent.onRetry
         },
         preWarmedContext
       ) : null,
@@ -17775,7 +18221,15 @@ async function runEvalRound(ctx, input) {
           model: visualEvalAgent.model,
           passThreshold: visualThreshold,
           sampleProps: visualEvaluation?.sampleProps,
-          viewport: visualEvaluation?.viewport
+          viewport: visualEvaluation?.viewport,
+          // #484/#489 — same threading as the LLM-eval leg above:
+          // the visual eval's multimodal call runs inside the same
+          // concurrent generation, so it needs the same routing
+          // override (never fall back to `process.env`) and the
+          // same provider-429-retry observer (retries reach the
+          // host application's structured log).
+          routeOverride: visualEvalAgent.routeOverride,
+          onRetry: visualEvalAgent.onRetry
         }
       ) : null
     ]);
@@ -17994,7 +18448,7 @@ async function runEvalRound(ctx, input) {
         lastDiffFailed: false
       };
     }
-    const allActionable = evalResult.issues.filter((i) => i.result === "fail" || i.result === "warn").sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1)).slice(0, MAX_FEEDBACK_ISSUES);
+    const allActionable = selectActionableFeedback(evalResult.issues);
     const issueLines = allActionable.map((issue) => {
       const tag = issue.result === "fail" ? "FAIL" : "WARN";
       return `[${tag}] ${issue.category}${issue.subcategory ? "/" + issue.subcategory : ""}: ${issue.description}
@@ -18009,7 +18463,16 @@ async function runEvalRound(ctx, input) {
       evalResult,
       evalRoundsUsed,
       prevModeSubcats: updatedPrevModeSubcats,
-      prevFailFingerprints: currFailFingerprints,
+      // DELIVERED fails only (Exp 54 P1 addendum, proposal 2): the
+      // stuck detector's premise is "the LLM saw these and did not
+      // resolve them" — recording fails that the MAX_FEEDBACK_ISSUES
+      // cap cut from the feedback turns truncation into a premature
+      // stuck-exit (the model never saw the issue it is blamed for
+      // not fixing). An undelivered fail recurring next round now
+      // reads as NEW, gets delivered, and earns its fix round.
+      prevFailFingerprints: new Set(
+        allActionable.filter((i) => i.result === "fail").map(fingerprintFail)
+      ),
       preWarmedContext,
       evalTokens,
       evalLlmMs,
@@ -18504,12 +18967,14 @@ async function dispatchGeneration(params) {
   const codingAgent = {
     provider: routerProvider,
     model: resolvedModel,
-    routeOverride: params.routeOverride
+    routeOverride: params.routeOverride,
+    onRetry: params.onRetry
   };
   const evaluationAgent = params.models?.evaluation ? {
     provider: routerProvider,
     model: params.models.evaluation,
-    routeOverride: params.routeOverride
+    routeOverride: params.routeOverride,
+    onRetry: params.onRetry
   } : void 0;
   const effectiveContract = params.contract;
   const sessionParams = {
@@ -18870,11 +19335,15 @@ ${JSON.stringify(clientCapabilities, null, 2)}
   const uiRequirements = [];
   if (contract.propsSpec?.properties) {
     for (const [name, entry] of Object.entries(contract.propsSpec.properties)) {
-      const required = entry.required;
-      if (required !== false) {
+      const required = entry.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 \u2014 the component must render without it (guard the access or apply its default) and must display it when it IS provided.`
+        );
       }
     }
   }
@@ -18958,7 +19427,8 @@ function createUiGenerator(options = {}) {
     maxEvalRounds,
     qualityConfig,
     gadgetCatalog,
-    disableEnvMutation = false
+    disableEnvMutation = false,
+    onRetry
   } = options;
   const identity = resolveIdentity(options);
   return {
@@ -19036,7 +19506,8 @@ function createUiGenerator(options = {}) {
           // `dispatchGeneration`.
           ...input.gadgetTypes !== void 0 ? { gadgetTypes: input.gadgetTypes } : {},
           enableRuntimeRender,
-          ...routeOverride !== void 0 ? { routeOverride } : {}
+          ...routeOverride !== void 0 ? { routeOverride } : {},
+          ...onRetry !== void 0 ? { onRetry } : {}
         });
         const metadata = {
           provider: input.llm.provider,