@ggui-ai/ui-gen 0.8.0 → 0.10.0

package/dist/workflows.d.ts

@@ -1,7 +1,7 @@
 import { C as Classification } from './axes-CzLEMDeB.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
-import './types-public-C36k1q6s.js';
+import './types-public-DIpjC-OA.js';
 import './types-BOvHNG7K.js';
 import './llm.js';
 import './policy.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -185,12 +185,12 @@
   "peerDependencies": {
     "@google/adk": "^0.5.0",
     "@openai/agents": "^0.7.1",
-    "puppeteer-core": "^24.40.0",
+    "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.8.0",
-    "@ggui-ai/project-config": "0.8.0",
-    "@ggui-ai/protocol": "0.8.0"
+    "@ggui-ai/mcp-server-core": "0.10.0",
+    "@ggui-ai/project-config": "0.10.0",
+    "@ggui-ai/protocol": "0.10.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -210,9 +210,9 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/bedrock-sdk": "^0.29.0",
-    "@anthropic-ai/claude-agent-sdk": "0.2.76",
-    "@anthropic-ai/sdk": "^0.91.1",
+    "@anthropic-ai/bedrock-sdk": "^0.32.1",
+    "@anthropic-ai/claude-agent-sdk": "0.3.229",
+    "@anthropic-ai/sdk": "^0.116.0",
     "@google/genai": "^2.8.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.0.0",
@@ -229,28 +229,28 @@
     "openai": "^6.29.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.8.0",
-    "@ggui-ai/gadgets": "0.8.0",
-    "@ggui-ai/ui-visual-tester": "0.8.0",
-    "@ggui-ai/wire": "0.8.0",
-    "@ggui-ai/sandbox": "0.8.0"
+    "@ggui-ai/gadgets": "0.10.0",
+    "@ggui-ai/design": "0.10.0",
+    "@ggui-ai/sandbox": "0.10.0",
+    "@ggui-ai/ui-visual-tester": "0.10.0",
+    "@ggui-ai/wire": "0.10.0"
   },
   "devDependencies": {
     "@google/adk": "^0.5.0",
     "@openai/agents": "^0.7.1",
-    "@sparticuz/chromium": "^143.0.4",
+    "@sparticuz/chromium": "^149.0.0",
     "@types/eslint": "^9.6.1",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "puppeteer-core": "^24.40.0",
+    "puppeteer-core": "^25.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/project-config": "0.8.0",
-    "@ggui-ai/protocol": "0.8.0",
-    "@ggui-ai/mcp-server-core": "0.8.0"
+    "@ggui-ai/mcp-server-core": "0.10.0",
+    "@ggui-ai/project-config": "0.10.0",
+    "@ggui-ai/protocol": "0.10.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/adapters/generation-dispatch.ts

@@ -53,6 +53,7 @@ import type {
 } from "../harness/result-types.js";
 import type { AdapterResult, ProviderName, ToolDefinition } from "./types.js";
 import type { QualityConfig } from "../evaluation/types-public.js";
+import type { AgentConfig } from "../harness/llm-router.js";
 import {
   type GadgetDescriptor,
   type JsonObject,
@@ -147,6 +148,21 @@ export interface GenerationDispatchParams {
    * STDLIB-only / bench / direct callers.
    */
   gadgetTypes?: Readonly<Record<string, string>>;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded onto the coding + evaluation
+   * agent specs so `resolveSessionAgents` → `createAgent` never falls
+   * back to reading `process.env`. Absent (default) preserves
+   * existing behavior for callers that don't set it.
+   */
+  routeOverride?: AgentConfig["routeOverride"];
+  /**
+   * Retry observer (#489) — see `AgentConfig.onRetry`. Threaded onto
+   * the coding + evaluation agent specs so a rate-limited retry inside
+   * either agent's `apiCall()` reaches the caller. Absent (default) is
+   * a no-op.
+   */
+  onRetry?: AgentConfig["onRetry"];
 }
 
 /**
@@ -186,9 +202,19 @@ export async function dispatchGeneration(
 
   const routerProvider = mapProviderForLLMRouter(params.provider);
   const resolvedModel = params.models?.coding ?? params.models?.default ?? params.model;
-  const codingAgent = { provider: routerProvider, model: resolvedModel };
+  const codingAgent = {
+    provider: routerProvider,
+    model: resolvedModel,
+    routeOverride: params.routeOverride,
+    onRetry: params.onRetry,
+  };
   const evaluationAgent = params.models?.evaluation
-    ? { provider: routerProvider, model: params.models.evaluation }
+    ? {
+        provider: routerProvider,
+        model: params.models.evaluation,
+        routeOverride: params.routeOverride,
+        onRetry: params.onRetry,
+      }
     : undefined;
   // ModelRoles doesn't currently expose a visualEval slot — falls through
   // to the documented evaluation → coding chain inside resolveSessionAgents.

package/src/adapters/openrouter/client.ts

@@ -49,7 +49,7 @@ export class OpenRouterClient {
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
       const message = (errorBody as { error?: { message?: string } }).error?.message ?? response.statusText;
-      throw new OpenRouterError(message, response.status);
+      throw new OpenRouterError(message, response.status, undefined, response.headers);
     }
 
     return response.json() as Promise<OpenRouterChatResponse>;
@@ -72,7 +72,7 @@ export class OpenRouterClient {
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
       const message = (errorBody as { error?: { message?: string } }).error?.message ?? response.statusText;
-      throw new OpenRouterError(message, response.status);
+      throw new OpenRouterError(message, response.status, undefined, response.headers);
     }
 
     if (!response.body) {

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

@@ -347,13 +347,15 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 ## Defensive coding for absent / late-arriving data
 
-Props arrive via \`ggui_update\` and may be partial on first render. 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.**
+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\`.
 - **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives — guard before reading \`.foo\`.
 - **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed — your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list — and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
+- **Props re-sync on repaint**: props the agent owns are the source of truth for display — prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change — \`useEffect(() => setCount(props.count ?? 0), [props.count])\` — or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
 - **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders — never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
 - **Empty state**: when a list or results array is empty, render \`<EmptyState title="…" description="…" />\` — a region that renders nothing when empty looks broken to the user.
 
@@ -481,7 +483,7 @@ Every value change is mirrored to the host LLM's context automatically (debounce
 
 **When NOT to use it.** Local UI state the contract did NOT declare — \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
 
-**\`contextSpec\` direction is one-way: client → agent.** The agent uses \`propsSpec\` (via \`ggui_update\`) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` — there is no return path.
+**\`contextSpec\` direction is one-way: client → agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` — there is no return path.
 
 **Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
 

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';
@@ -138,6 +139,30 @@ export interface CreateUiGeneratorOptions {
    * `appGadgets` themselves; the legacy handler path stays unchanged.
    */
   readonly gadgetCatalog?: GadgetCatalogAdapter;
+  /**
+   * When `true`, `generate()` never mutates `process.env` — the
+   * resolved provider route is threaded structurally into the
+   * dispatch call instead of being written to and restored from the
+   * process environment. Use this when running concurrent
+   * generations in one process (the default backup/mutate/restore
+   * dance is NOT concurrency-safe: two simultaneous calls race on
+   * the shared `process.env`).
+   *
+   * Default `false` — preserves the original env-mutation behavior
+   * 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(
@@ -149,6 +174,8 @@ export function createUiGenerator(
     maxEvalRounds,
     qualityConfig,
     gadgetCatalog,
+    disableEnvMutation = false,
+    onRetry,
   } = options;
 
   const identity = resolveIdentity(options);
@@ -193,19 +220,37 @@ export function createUiGenerator(
       }
 
       const envBackup: Record<string, string | undefined> = {};
-      for (const k of Object.keys(route.env)) envBackup[k] = process.env[k];
-      const baseEnvForApply: Record<string, string> = {};
-      for (const [k, v] of Object.entries(process.env)) {
-        if (v !== undefined) baseEnvForApply[k] = v;
-      }
-      const routedEnv = applyRouteToEnv(baseEnvForApply, route);
-      for (const [k, v] of Object.entries(routedEnv)) process.env[k] = v;
-      // Also delete any keys the route asked to clear (route.env values
-      // marked undefined).
-      for (const [k, v] of Object.entries(route.env)) {
-        if (v === undefined) delete process.env[k];
+      if (!disableEnvMutation) {
+        for (const k of Object.keys(route.env)) envBackup[k] = process.env[k];
+        const baseEnvForApply: Record<string, string> = {};
+        for (const [k, v] of Object.entries(process.env)) {
+          if (v !== undefined) baseEnvForApply[k] = v;
+        }
+        const routedEnv = applyRouteToEnv(baseEnvForApply, route);
+        for (const [k, v] of Object.entries(routedEnv)) process.env[k] = v;
+        // Also delete any keys the route asked to clear (route.env values
+        // marked undefined).
+        for (const [k, v] of Object.entries(route.env)) {
+          if (v === undefined) delete process.env[k];
+        }
       }
 
+      // #484 — when `disableEnvMutation` is set, skip the process-env
+      // mutation above entirely and thread the resolved route
+      // structurally into the dispatch call instead. `route.env`
+      // already carries exactly the key(s) that would have gone into
+      // `process.env`, so no extra resolution work is needed here.
+      const routeOverride = disableEnvMutation
+        ? {
+            apiKey:
+              route.env['ANTHROPIC_API_KEY'] ??
+              route.env['OPENAI_API_KEY'] ??
+              route.env['GEMINI_API_KEY'] ??
+              route.env['OPENROUTER_API_KEY'],
+            useBedrock: route.env['CLAUDE_CODE_USE_BEDROCK'] === '1',
+          }
+        : undefined;
+
       try {
         const tools = createGeneratorTools({
           ...(input.contract ? { contract: input.contract } : {}),
@@ -269,6 +314,8 @@ export function createUiGenerator(
             ? { gadgetTypes: input.gadgetTypes }
             : {}),
           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-merge.ts

@@ -29,7 +29,7 @@ function runStateSeededFromProps(input: AxisCheckInput): EvalIssue[] {
       mkIssue(
         "state.merge.seeded_from_props",
         `Entity collection "${e.name}" is not seeded from props — no useState initializer reads props.${e.name}.`,
-        `Add \`const [${e.name}, set${cap(e.name)}] = useState(props.${e.name});\` so stream/action updates can merge into live state.`,
+        `Add \`const [${e.name}, set${cap(e.name)}] = useState(props.${e.name});\` paired with \`useEffect(() => set${cap(e.name)}(props.${e.name}), [props.${e.name}]);\` so stream/action updates merge into live state AND agent repaints (ggui_amend) re-seed it (#480).`,
       ),
     );
   }

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/checks/universal.ts

@@ -86,6 +86,39 @@ function runNoPhantomUseState(input: AxisCheckInput): EvalIssue[] {
   return issues;
 }
 
+function runPropSeedNoResync(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const issues: EvalIssue[] = [];
+  const re =
+    /const\s*\[\s*(\w+)\s*,\s*(\w+)\s*\]\s*=\s*useState(?:<[^>]*>)?\s*\(\s*props\??\.(\w+)/g;
+  for (const m of src.matchAll(re)) {
+    const [full, stateVar, setter, propName] = m;
+    const idx = m.index ?? 0;
+    const after = src.slice(idx + full.length);
+    // Never-called setter is `no_prop_mirror`'s case — this check is
+    // its #480 complement: the setter IS used (real optimistic state)
+    // but nothing re-seeds when the agent repaints the prop.
+    if (!new RegExp(`\\b${setter}\\s*\\(`).test(after)) continue;
+    // A re-seed effect names the prop in a dependency array. Bracket
+    // shape is the pragmatic signal (same looseness as the sibling
+    // checks): any `[... props.X ...]` array in the source counts.
+    const resync = new RegExp(
+      `\\[[^\\[\\]]*props\\??\\.${propName}\\b[^\\[\\]]*\\]`,
+    );
+    if (resync.test(src)) continue;
+    issues.push(
+      mkIssue(
+        "universal.prop_seed_no_resync",
+        `useState(props.${propName}) seeds "${stateVar}" and mutates it, but no effect depends on [props.${propName}] — a ggui_amend repaint pushes new props that never reach this display (#480).`,
+        `Add \`useEffect(() => ${setter}(props.${propName}), [props.${propName}]);\` so agent repaints re-seed the state, or derive the display directly from props.${propName}.`,
+        "warn",
+      ),
+    );
+  }
+  return issues;
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.prop_coverage",
@@ -105,4 +138,10 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runNoPhantomUseState,
   },
+  {
+    id: "universal.prop_seed_no_resync",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runPropSeedNoResync,
+  },
 ];