@ggui-ai/ui-gen 0.24.0 → 0.25.0

package/dist/workflows.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -189,9 +189,9 @@
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/project-config": "0.24.0",
-    "@ggui-ai/protocol": "0.24.0",
-    "@ggui-ai/mcp-server-core": "0.24.0"
+    "@ggui-ai/project-config": "0.25.0",
+    "@ggui-ai/mcp-server-core": "0.25.0",
+    "@ggui-ai/protocol": "0.25.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -233,11 +233,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.24.0",
-    "@ggui-ai/gadgets": "0.24.0",
-    "@ggui-ai/sandbox": "0.24.0",
-    "@ggui-ai/ui-visual-tester": "0.24.0",
-    "@ggui-ai/wire": "0.24.0"
+    "@ggui-ai/design": "0.25.0",
+    "@ggui-ai/ui-visual-tester": "0.25.0",
+    "@ggui-ai/gadgets": "0.25.0",
+    "@ggui-ai/sandbox": "0.25.0",
+    "@ggui-ai/wire": "0.25.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -252,9 +252,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.24.0",
-    "@ggui-ai/project-config": "0.24.0",
-    "@ggui-ai/protocol": "0.24.0"
+    "@ggui-ai/mcp-server-core": "0.25.0",
+    "@ggui-ai/project-config": "0.25.0",
+    "@ggui-ai/protocol": "0.25.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/generation-dispatch.ts

@@ -60,8 +60,22 @@ import type { QualityConfig } from "../evaluation/types-public.js";
 import type { AgentConfig } from "../harness/llm-router.js";
 import { type GadgetDescriptor, type JsonObject } from "@ggui-ai/protocol";
 import { canvasForRendering, type CanvasClass, type DesignMode } from "../design-mode.js";
+import type { VisionProvider } from "../harness/llm-router.js";
+import type { CriteriaBank } from "../evaluation/criteria/bank.js";
 import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 
+/**
+ * ggui#1250 — the in-loop VISUAL judge as its own agent: a vision provider (typed so an OpenAI judge cannot
+ * be written), a model, and — when the caller resolves provider keys itself — that provider's key, which
+ * becomes the agent's own `routeOverride`. Never the coding agent's route: where this exists (an OpenAI
+ * coding lane), the coding key is another provider's.
+ */
+export interface VisualEvalAgentSpec {
+  readonly provider: VisionProvider;
+  readonly model: string;
+  readonly apiKey?: string;
+}
+
 export interface GenerationDispatchParams {
   provider: ProviderName;
   model: string;
@@ -109,6 +123,9 @@ export interface GenerationDispatchParams {
      * the same box. See `VisualEvalConfig.canvasViewports`.
      */
     canvasViewports?: Partial<Readonly<Record<CanvasClass, { width: number; height: number }>>>;
+    /** ggui#1436 — see `SingleComponentParams.visualEvaluation.criteriaBank`. */
+    criteriaBank?: CriteriaBank;
+    criteriaKind?: string;
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;
@@ -190,6 +207,13 @@ export interface GenerationDispatchParams {
    * existing behavior for callers that don't set it.
    */
   routeOverride?: AgentConfig["routeOverride"];
+  /**
+   * ggui#1250 — the in-loop visual judge named as its own agent (see {@link VisualEvalAgentSpec}).
+   * Absent (default, every existing caller): today's chain, `visualEval ← evaluation ← coding`, which on
+   * a lane without a vision path records the score half as skipped (#1248). Off by default; a measurement
+   * knob first, a product knob only by ruling.
+   */
+  visualEvalAgent?: VisualEvalAgentSpec;
   /**
    * Retry observer (#489) — see `AgentConfig.onRetry`. Threaded onto
    * the coding + evaluation agent specs so a rate-limited retry inside
@@ -268,8 +292,17 @@ export async function dispatchGeneration(
         onRetry: params.onRetry,
       }
     : undefined;
-  // ModelRoles doesn't currently expose a visualEval slot — falls through
-  // to the documented evaluation → coding chain inside resolveSessionAgents.
+  // ggui#1250 — the in-loop visual judge as its own agent when named: its own provider and its own key
+  // route, never the coding agent's. Absent: today's chain, visualEval ← evaluation ← coding, inside
+  // resolveSessionAgents (ModelRoles has no visualEval slot — a role is a model, and this needs a provider).
+  const visualEvalAgent = params.visualEvalAgent
+    ? {
+        provider: params.visualEvalAgent.provider,
+        model: params.visualEvalAgent.model,
+        ...(params.visualEvalAgent.apiKey !== undefined ? { routeOverride: { apiKey: params.visualEvalAgent.apiKey } } : {}),
+        onRetry: params.onRetry,
+      }
+    : undefined;
 
   // ── Contract enrichment ──────────────────────────────────────────────
   // The contract is used as-is: `clientCapabilities.gadgets`
@@ -426,6 +459,7 @@ export async function dispatchGeneration(
   const agents = resolveSessionAgents({
     codingAgent,
     evaluationAgent,
+    ...(visualEvalAgent !== undefined ? { visualEvalAgent } : {}),
   });
 
   // ── Runtime policy resolution ──

package/src/adapters/tools.ts

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

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

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

package/src/boilerplate/generate.ts

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

package/src/boilerplate/hard-sections.ts

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

package/src/boilerplate/system-prompt.ts

@@ -469,7 +469,7 @@ The design-system primitives are accessible by construction — they emit their
 3. **Icons are decorative by default** — \`<Icon name="check" />\` is hidden from screen readers, which is correct for an icon sitting next to text. Add \`aria-label\` ONLY for a standalone, meaning-bearing icon with no adjacent text. Icon-only \`Button\`s still need \`aria-label\` on the **Button** itself.
 4. **Live & streaming data** — wrap any region whose content updates on its own (a \`useStream\` \`.latest\` value, a live clock, an "N new" counter, a flashing price) in an element with \`aria-live="polite"\` so screen readers announce the change.
 5. **Headings nest** — one \`<Heading level={1}>\` per screen, \`level={2}\` for sections, \`level={3}\` for subsections. Never skip or invert levels.
-6. **Buttons** — descriptive text content; icon-only buttons need \`aria-label\`. Announce busy state: \`<Button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting…' : 'Submit'}</Button>\`.
+6. **Buttons** — descriptive text content; icon-only buttons need \`aria-label\`. Announce busy state. EVERY control that dispatches an action — a Button, a Select whose change dispatches, an Input that sends on Enter — stays pending from that action's \`useActionPending\` until the agent's answer repaints the card: with \`const sendPending = useActionPending('send');\`, write \`<Button disabled={sendPending} aria-busy={sendPending} onClick={() => send({ text })}>{sendPending ? 'Sending…' : 'Send'}</Button>\`, and give a dispatching Select or Input the same \`disabled={sendPending} aria-busy={sendPending}\`. Only a control that dispatches the action carries its \`aria-busy\` and a working label. While it is pending, other controls of the SAME record may be \`disabled\` — nothing more; controls of other records, creation controls and the action's own cancel stay enabled. Busy state the card owns (a local \`isLoading\`) is announced the same way.
 7. **Stateful controls announce their state.** Toggleable / selectable / expandable things use the primitive that carries the semantics (\`Checkbox\`, \`Toggle\`, \`Tabs\`, \`Accordion\`) — never a styled \`Box\`/\`Icon\` that only *looks* checked. When you hand-roll one with \`as={Clickable}\`, \`Clickable\` adds button + keyboard semantics but NOT state — add it yourself: \`role="checkbox"\` + \`aria-checked={done}\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check icon) must never be the only carrier of state.
 
 ## Design System Usage (CRITICAL)

package/src/check/index.ts

@@ -51,3 +51,4 @@ export {
 
 // runTier0 orchestrator
 export { runTier0, runTier0Checks } from "./run-tier0.js";
+export { generateSampleProps } from "./sample-props.js";

package/src/check/sample-props.ts

@@ -0,0 +1,63 @@
+// Sample props from a PropsSpec — `example` first, then `default`, then a type-driven fill from the JSON
+// Schema. Pure: protocol types only, no sandbox, no node modules, so `@ggui-ai/ui-gen/check` can export it and a
+// caller outside the harness (an experiment's judge input, ggui#1386) synthesizes the SAME props the coding
+// agent's own render check falls back to. Moved verbatim out of `tools/render-check.ts` (2026-09-26).
+import type { JsonObject, JsonSchema, JsonValue, PropsSpec } from '@ggui-ai/protocol';
+
+/**
+ * Generate sample props from a PropsSpec contract.
+ * Uses `example` values from each PropEntry when available,
+ * otherwise synthesizes plausible defaults from the JSON Schema.
+ */
+export function generateSampleProps(spec: PropsSpec): JsonObject {
+  const props: JsonObject = {};
+
+  for (const [name, entry] of Object.entries(spec.properties)) {
+    // Prefer explicit example value
+    if (entry.example !== undefined) {
+      props[name] = entry.example;
+      continue;
+    }
+
+    // Prefer explicit default value
+    if (entry.default !== undefined) {
+      props[name] = entry.default;
+      continue;
+    }
+
+    // Synthesize from JSON Schema
+    props[name] = synthesizeFromSchema(entry.schema);
+  }
+
+  return props;
+}
+
+function synthesizeFromSchema(schema: JsonSchema): JsonValue | undefined {
+  // Draft-07 type arrays (`['string','null']`) synthesize from the
+  // first non-null member — the canonical nullability form the
+  // enforced-props-schema emission produces.
+  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': {
+      if (schema.items) return [synthesizeFromSchema(schema.items) ?? null];
+      return [];
+    }
+    case 'object': {
+      const obj: JsonObject = {};
+      if (schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+          obj[k] = synthesizeFromSchema(v);
+        }
+      }
+      return obj;
+    }
+    default: return undefined;
+  }
+}

package/src/coding-agent/tools.ts

@@ -17,7 +17,7 @@ import type { AxisCheck, AxisCheckInput } from '../evaluation/types-public.js';
 import type { Classification } from '../classifier/axes.js';
 import type { CanvasClass } from '../design-mode.js';
 import { PRIMITIVES_DOCUMENTATION } from '../validation/index.js';
-import type { DataContract } from '@ggui-ai/protocol';
+import type { DataContract, JsonObject } from '@ggui-ai/protocol';
 import type {
   ToolResult,
   CommitMetadata,
@@ -64,6 +64,8 @@ export interface AutoCommitAxisChecks {
   readonly originalPrompt: string;
   /** The canvas the harness was built for (ggui#1117); absent = no rendering context, never a default. */
   readonly canvas?: CanvasClass;
+  /** The props the probe and judge render with (ggui#1285); absent = the fixture-echo check stands down. */
+  readonly fixtureProps?: JsonObject;
 }
 
 async function autoCommit(
@@ -161,6 +163,7 @@ async function autoCommit(
         classification: axis.classification,
         designMode,
         ...(axis.canvas !== undefined ? { canvas: axis.canvas } : {}),
+        ...(axis.fixtureProps !== undefined ? { fixtureProps: axis.fixtureProps } : {}),
       }
     : undefined;
   if (axisFacts !== undefined && !buildSuccess) traceAxisChecksSkipped(axisFacts, 'build failed — no check ran');

package/src/create-harness.ts

@@ -16,7 +16,7 @@ import { hasProfile } from "./boilerplate/styling-profile.js";
 import type { CacheTier } from "./fragments/index.js";
 import { compose } from "./compose.js";
 import { buildSystemPrompt, generateBoilerplate } from "./boilerplate.js";
-import { APPLY_CHANGES_TOOL, APPLY_CHANGES_TOOL_SCOPED } from "./tools.js";
+import { HARNESS_CODING_TOOLS, HARNESS_SCOPED_TOOLS } from "./harness-tool-names.js";
 import { defaultApplyPatch } from "./patch.js";
 import { computeHarnessId, computeHarnessName, hashClassification } from "./hash.js";
 import { pickWorkflow } from "./workflows.js";
@@ -128,8 +128,8 @@ export function createHarness(input: CreateHarnessInput): Harness {
   const baseWhat: WhatLeg = {
     boilerplate,
     fragments: whatFragments,
-    codingTools: [APPLY_CHANGES_TOOL],
-    scopedTools: [APPLY_CHANGES_TOOL_SCOPED],
+    codingTools: [...HARNESS_CODING_TOOLS],
+    scopedTools: [...HARNESS_SCOPED_TOOLS],
     applyPatch: defaultPatchFn,
     // Registered gadget catalog — drives the system prompt's gadget
     // table + the boilerplate's direct-import emission. Omitted when no

package/src/create-ui-generator.ts

@@ -38,6 +38,7 @@ import type {
   JsonObject,
   GeneratorId,
   ModelRef,
+  AppGenerationProfileEffort,
 } from "@ggui-ai/protocol";
 import { isGeneratorId, modelRefOfRoute } from "@ggui-ai/protocol";
 import type { GadgetCatalogAdapter } from "@ggui-ai/gadgets";
@@ -58,7 +59,7 @@ import {
   parseGeneratorSlug,
 } from "@ggui-ai/mcp-server-core";
 import { createGeneratorTools } from "./adapters/index.js";
-import { dispatchGeneration } from "./adapters/generation-dispatch.js";
+import { dispatchGeneration, type VisualEvalAgentSpec } from "./adapters/generation-dispatch.js";
 import {
   createRuntimeRenderCheck,
   type RuntimeRenderProbeConfig,
@@ -139,6 +140,13 @@ export interface CreateUiGeneratorOptions {
    * prompt or the identity. Default: none — the round runs as today.
    */
   readonly visualEvaluation?: SingleComponentParams["visualEvaluation"];
+  /**
+   * ggui#1250 — the in-loop VISUAL judge as its own agent (a vision provider, a model, and that
+   * provider's key when the caller resolves keys itself). Absent (default): the judge is the
+   * evaluation agent's provider, which on a lane without a vision path records the score half as
+   * skipped (#1248). Forwarded verbatim to the dispatch; never part of the prompt or the identity.
+   */
+  readonly visualEvalAgent?: VisualEvalAgentSpec;
   /** Quality config controlling eval tiers + improvement behavior. */
   readonly qualityConfig?: QualityConfig;
   /**
@@ -259,6 +267,7 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
     maxEvalRounds,
     evaluation,
     visualEvaluation,
+    visualEvalAgent,
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
@@ -354,6 +363,9 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
               }
             : undefined;
 
+      // ggui#1459 — the named level whose dials this generation applied; set
+      // where the dials are resolved, read by both metadata arms below.
+      let effortRan: AppGenerationProfileEffort | undefined;
       try {
         const tools = createGeneratorTools({
           ...(input.contract ? { contract: input.contract } : {}),
@@ -400,6 +412,7 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
         // deployment's options for THIS generation; absent ⇒ untouched.
         // Prompt bytes never move with it (dials only).
         const dials = effortDials(input.profile?.effort);
+        if (dials !== undefined) effortRan = input.profile?.effort;
         const effectiveMaxAttempts = dials?.maxAttempts ?? maxAttempts;
         const effectiveMaxEvalRounds = dials?.maxEvalRounds ?? maxEvalRounds;
         const effectiveEvaluation =
@@ -442,6 +455,8 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
           // ggui#1279 — the shell the declared rendering composes for (chat only; see harnessShellForRendering).
           ...(shellType !== undefined ? { shellType } : {}),
           ...(input.profile !== undefined ? { profile: input.profile } : {}),
+          // ggui#1250 — the named in-loop visual judge, when this generator was built with one.
+          ...(visualEvalAgent !== undefined ? { visualEvalAgent } : {}),
           // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
           ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
         });
@@ -461,6 +476,8 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
           attempts: result.turnsUsed,
           // ggui#1280 — the build that made this generation (template keys, never per-request).
           build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
+          // ggui#1459 — the level that ran; absent when none was applied.
+          ...(effortRan !== undefined ? { effort: effortRan } : {}),
           // Prompt-cache counters are provider-specific (Claude reports
           // them; others omit). Pass through truthfully — absent on the
           // adapter result stays absent here, never defaulted to 0.
@@ -507,6 +524,8 @@ export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGen
             cacheHit: false,
             // ggui#1280 — a failed generation still names the build that failed.
             build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
+            // ggui#1459 — and the level it ran, when one was applied.
+            ...(effortRan !== undefined ? { effort: effortRan } : {}),
           },
         };
       } finally {

package/src/evaluation/__fixtures__/png.ts

@@ -0,0 +1,100 @@
+/**
+ * A PNG writer for tests (ggui#1120): 8-bit RGB / RGBA, non-interlaced, one scanline filter for the
+ * whole image — the shapes the judge's browser writes, so `decodePng` is exercised on every filter it
+ * must undo. Test-only: nothing in `src` imports it.
+ */
+import { crc32, deflateSync } from 'node:zlib';
+
+export type Rgb = readonly [number, number, number];
+
+export interface PngSpec {
+  readonly width: number;
+  readonly height: number;
+  readonly channels: 3 | 4;
+  /** The colour at (x, y). */
+  readonly pixel: (x: number, y: number) => Rgb;
+  /** The scanline filter applied to every row (0 none, 1 sub, 2 up, 3 average, 4 paeth). */
+  readonly filter?: 0 | 1 | 2 | 3 | 4;
+  /** Overrides for the malformed cases. */
+  readonly bitDepth?: number;
+  readonly colorType?: number;
+  readonly interlace?: number;
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, 'latin1');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(data, crc32(Buffer.from(type, 'latin1'))) >>> 0, 0);
+  return Buffer.concat([head, data, crc]);
+}
+
+export function encodePng(spec: PngSpec): Buffer {
+  const { width, height, channels } = spec;
+  const filter = spec.filter ?? 0;
+  const stride = width * channels;
+  const rows: number[][] = [];
+  for (let y = 0; y < height; y++) {
+    const row: number[] = [];
+    for (let x = 0; x < width; x++) {
+      const [r, g, b] = spec.pixel(x, y);
+      row.push(r, g, b);
+      if (channels === 4) row.push(255);
+    }
+    rows.push(row);
+  }
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = filter;
+    for (let i = 0; i < stride; i++) {
+      const x = rows[y]![i]!;
+      const a = i >= channels ? rows[y]![i - channels]! : 0;
+      const b = y > 0 ? rows[y - 1]![i]! : 0;
+      const c = y > 0 && i >= channels ? rows[y - 1]![i - channels]! : 0;
+      let out: number;
+      switch (filter) {
+        case 0:
+          out = x;
+          break;
+        case 1:
+          out = x - a;
+          break;
+        case 2:
+          out = x - b;
+          break;
+        case 3:
+          out = x - ((a + b) >> 1);
+          break;
+        case 4: {
+          const p = a + b - c;
+          const pa = Math.abs(p - a);
+          const pb = Math.abs(p - b);
+          const pc = Math.abs(p - c);
+          out = x - (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+          break;
+        }
+      }
+      raw[y * (stride + 1) + 1 + i] = out & 0xff;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = spec.bitDepth ?? 8;
+  ihdr[9] = spec.colorType ?? (channels === 4 ? 6 : 2);
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = spec.interlace ?? 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw)),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** One flat colour — the blank. */
+export function flatPng(width: number, height: number, colour: Rgb, channels: 3 | 4 = 3, filter: PngSpec['filter'] = 0): Buffer {
+  return encodePng({ width, height, channels, pixel: () => colour, filter });
+}

package/src/evaluation/axis-checks/checks/state-merge.ts

@@ -108,7 +108,7 @@ function runMapKeyIsId(input: AxisCheckInput): EvalIssue[] {
       mkIssue(
         "render.map_key_is_id",
         `Array key uses index variable "${key}" — reorders and stream merges will break React reconciliation.`,
-        `Replace key={${key}} with key={item.id} (or item.symbol / whatever the entity id field is).`,
+        `Replace key={${key}} with key={item.id} — or, when the items carry no id, with the field that names each one (item.label / item.symbol / item.name).`,
       ),
     );
   }