@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.24.0",
+  "version": "0.26.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/mcp-server-core": "0.26.0",
+    "@ggui-ai/protocol": "0.26.0",
+    "@ggui-ai/project-config": "0.26.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.26.0",
+    "@ggui-ai/gadgets": "0.26.0",
+    "@ggui-ai/ui-visual-tester": "0.26.0",
+    "@ggui-ai/sandbox": "0.26.0",
+    "@ggui-ai/wire": "0.26.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/project-config": "0.26.0",
+    "@ggui-ai/mcp-server-core": "0.26.0",
+    "@ggui-ai/protocol": "0.26.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,11 @@ 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;
+    /** ggui#1542 — see `SingleComponentParams.visualEvaluation.actOn`. */
+    actOn?: "critical" | "major";
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;
@@ -190,6 +209,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 +294,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 +461,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

@@ -18,7 +18,7 @@
 // for raw elements · the one-gesture-surface invariant restated for raw
 // elements · a regenerated quality checklist.
 
-import { consumedTokenManifest } from "@ggui-ai/design/themes";
+import { taughtTokenManifest } from "../taught-tokens.js";
 import { describeCanvas, type CanvasClass } from "../design-mode.js";
 import {
   ANTI_PATTERNS,
@@ -136,7 +136,7 @@ function renderRamp(r: ColorRamp): string {
  * every role the prose names exists on `:root`; nothing is implied by a
  * `50…800` range that the manifest does not carry step for step.
  */
-export function renderFreeColorRule(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderFreeColorRule(manifest: readonly string[] = taughtTokenManifest): string {
   const { ramps, roles } = colorVocabularyFromManifest(manifest);
   const brand = ramps.filter((r) => r.family === "primary" || r.family === "neutral");
   const state = ramps.filter((r) => r.family !== "primary" && r.family !== "neutral");
@@ -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.`;
 
@@ -260,7 +260,7 @@ const TOKEN_GROUPS: readonly TokenGroup[] = [
  * does not define. Grouped by prefix; anything outside the known
  * prefixes lands under "Other".
  */
-export function renderTokenVocabulary(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderTokenVocabulary(manifest: readonly string[] = taughtTokenManifest): string {
   const sorted = [...manifest].sort();
   const claimed = new Set<string>();
   const lines: string[] = [

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
@@ -257,7 +257,7 @@ The width works the same way, and the mistake is the mirror image: **your outerm
 
 - Never put \`maxWidth\` (or a \`max-w-*\` class) on the element you return at the top. On a wide canvas that turns your card into a narrow strip with the frame's ground on either side of it, and on a narrow one it does nothing — the same composition reading differently at two sizes.
 - DO cap the reading measure inside: a column of prose is easiest to read at 60–70 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
-- Centre that inner column with the container's own centring, not by shrinking the root.
+- Centre that inner column with the container's own centring, not by shrinking the root — and give the card ONE column: every block of the reading flow (a heading, its text, and the chips or buttons that answer it) sits in a \`<Container>\` of the same \`maxWidth\`, so their left edges line up even where a full-width band runs between them.
 - **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it — \`<Box padding="lg"><Container maxWidth="sm">…</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
 
 /** Helper-component structure guidance (JSX depth 3–5, helpers above `Component`). Identical in both modes. */

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/boilerplate/templates/layouts/chat-mobile.tsx.tmpl

@@ -3,5 +3,7 @@
           provides the chrome, so add no shadow or outer radius of your own.
           Compact and natural height; stack vertically. This root fills the
           bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
-          measure (inert at bubble width, composed on a wider frame). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/boilerplate/templates/layouts/chat-universal.tsx.tmpl

@@ -3,5 +3,7 @@
           provides the chrome, so add no shadow or outer radius of your own.
           Compact and natural height; stack vertically. This root fills the
           bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
-          measure (inert at bubble width, composed on a wider frame). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/boilerplate/templates/layouts/fullscreen-desktop.tsx.tmpl

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/boilerplate/templates/layouts/fullscreen-universal.tsx.tmpl

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

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/run-tier0.ts

@@ -17,6 +17,7 @@ import type { DataContract } from '@ggui-ai/protocol';
 import { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
+import { taughtTokenManifest } from '../taught-tokens.js';
 import { validateAllContracts, type ContractIssue } from './contract-validation.js';
 import { typecheck } from './type-checker.js';
 import { lintReactHooks, type ReactLintDiagnostic } from './react-linter.js';
@@ -315,7 +316,9 @@ const RETIRED_TOKEN_SUCCESSORS: ReadonlyMap<string, string> = new Map([
  * (`--ggui-motion-duration-normal` → fast, base, slow); otherwise the names
  * sharing any of its segments of four letters or more
  * (`--ggui-duration-slow` → the motion durations). Empty when nothing is
- * near, so the hint falls back to the manifest's general shape.
+ * near, so the hint falls back to the manifest's general shape. A hint
+ * teaches, so it draws only on the names the model may be taught
+ * (`taughtTokenManifest`); the closed-set check above admits the full manifest.
  */
 export function suggestManifestTokens(name: string): readonly string[] {
   const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
@@ -328,7 +331,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
   const own = name.endsWith('-') ? segments.length : segments.length - 1;
   for (let n = own; n >= 2; n--) {
     const prefix = `--${segments.slice(0, n).join('-')}-`;
-    const family = consumedTokenManifest.filter((token) => token.startsWith(prefix));
+    const family = taughtTokenManifest.filter((token) => token.startsWith(prefix));
     if (family.length > 0) return wordHitsFirst(name, rolesFirst(family));
   }
   const words = new Set(
@@ -338,7 +341,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
       .map((segment) => segment.toLowerCase()),
   );
   return rolesFirst(
-    consumedTokenManifest.filter((token) =>
+    taughtTokenManifest.filter((token) =>
       token.split('-').some((segment) => words.has(segment.toLowerCase())),
     ),
   );

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/contract-context.ts

@@ -59,7 +59,7 @@ const SHELL_HINTS: Record<string, string> = {
 - Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.
 - Scrolling: parent scrolls (chat feed) — component should NOT have internal scroll
 - Layout: single column, compact. No sidebar. Stack everything vertically.
-- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width.`,
+- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width; the chips or buttons that answer the prose sit in a Container of the same maxWidth, so they share its left edge.`,
 
   fullscreen: `**Fullscreen Shell — Takes over entire viewport**
 - Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)

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 {