@ggui-ai/ui-gen 0.18.0 → 0.20.0

package/dist/workflows.d.ts

@@ -2,7 +2,7 @@ import { C as Classification } from './axes-CzLEMDeB.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './styling-profile-CxfvV48g.js';
-import './types-public-DVSssdc-.js';
+import './types-public-DKR_h70H.js';
 import './design-mode-DLufhrNp.js';
 import './types-BOvHNG7K.js';
 import './llm.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.18.0",
+  "version": "0.20.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": [
@@ -188,9 +188,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/mcp-server-core": "0.18.0",
-    "@ggui-ai/project-config": "0.18.0",
-    "@ggui-ai/protocol": "0.18.0"
+    "@ggui-ai/project-config": "0.20.0",
+    "@ggui-ai/mcp-server-core": "0.20.0",
+    "@ggui-ai/protocol": "0.20.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -229,11 +229,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.18.0",
-    "@ggui-ai/sandbox": "0.18.0",
-    "@ggui-ai/ui-visual-tester": "0.18.0",
-    "@ggui-ai/wire": "0.18.0",
-    "@ggui-ai/gadgets": "0.18.0"
+    "@ggui-ai/gadgets": "0.20.0",
+    "@ggui-ai/design": "0.20.0",
+    "@ggui-ai/sandbox": "0.20.0",
+    "@ggui-ai/ui-visual-tester": "0.20.0",
+    "@ggui-ai/wire": "0.20.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -248,9 +248,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/project-config": "0.18.0",
-    "@ggui-ai/protocol": "0.18.0",
-    "@ggui-ai/mcp-server-core": "0.18.0"
+    "@ggui-ai/project-config": "0.20.0",
+    "@ggui-ai/protocol": "0.20.0",
+    "@ggui-ai/mcp-server-core": "0.20.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/google/sdk.ts

@@ -62,15 +62,10 @@ export async function runAdkLoop(
 ): Promise<AdapterResult> {
   const startTime = Date.now();
 
-  const { FunctionTool, LlmAgent, InMemoryRunner, isFinalResponse } = await import('@google/adk');
+  const { FunctionTool, Gemini, LlmAgent, InMemoryRunner, isFinalResponse } = await import('@google/adk');
 
   const capture = createCapture();
 
-  // Ensure ADK can find the API key
-  if (params.apiKey && !process.env.GOOGLE_GENAI_API_KEY) {
-    process.env.GOOGLE_GENAI_API_KEY = params.apiKey;
-  }
-
   // Build tools with capture wrappers
   const adkTools = params.tools.map((def) =>
     new FunctionTool({
@@ -88,9 +83,18 @@ export async function runAdkLoop(
     }),
   );
 
+  // The key the caller passed WINS, handed to the model directly (ggui#1132).
+  // The ADK resolves GOOGLE_GENAI_API_KEY || GOOGLE_API_KEY || GEMINI_API_KEY
+  // on its own when no key is given, so writing GOOGLE_GENAI_API_KEY here —
+  // a variable this adapter does not own — let a stale ambient value beat a
+  // fresh key, and no rotation could reach it. Precedence is fixed at the
+  // source: an explicit key never touches process.env; no key defers to the
+  // ADK's order untouched.
+  const model = params.apiKey ? new Gemini({ model: params.model, apiKey: params.apiKey }) : params.model;
+
   const agent = new LlmAgent({
     name: 'ui_generator',
-    model: params.model,
+    model,
     instruction: params.systemPrompt,
     tools: adkTools,
   });

package/src/adapters/openai/raw.ts

@@ -10,6 +10,7 @@ import { GeneratorAdapter, hasCredentials } from '../base';
 import type { AdapterConfig, GenerateParams } from '../base';
 import type { AdapterResult, ToolDefinition, ProviderName, AdapterMode } from '../types';
 import { zodToJsonSchema } from '../tool-bridge';
+import { splitOpenAiUsage } from './tokens';
 import {
   createCapture,
   captureSourceCode,
@@ -54,6 +55,9 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
     const capture = createCapture();
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
+    // OpenAI's input token count INCLUDES cached tokens; track the cached
+    // subset so tokens.input reports NON-cached input (ggui#1186).
+    let totalCachedInputTokens = 0;
     let turnsUsed = 0;
     let allTextOutput = '';
 
@@ -74,6 +78,8 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
       if (response.usage) {
         totalInputTokens += response.usage.input_tokens ?? 0;
         totalOutputTokens += response.usage.output_tokens ?? 0;
+        totalCachedInputTokens +=
+          response.usage.input_tokens_details?.cached_tokens ?? 0;
       }
 
       // Process output items
@@ -156,11 +162,11 @@ export class OpenAiRawAdapter extends GeneratorAdapter {
       sourceCode: capture.sourceCode,
       stream: capture.stream,
       generatorMeta: capture.generatorMeta,
-      tokens: {
-        input: totalInputTokens,
-        output: totalOutputTokens,
-        total: totalInputTokens + totalOutputTokens,
-      },
+      ...splitOpenAiUsage(
+        totalInputTokens,
+        totalOutputTokens,
+        totalCachedInputTokens,
+      ),
       generationTimeMs: Date.now() - startTime,
       turnsUsed,
     };

package/src/adapters/openai/sdk.ts

@@ -6,6 +6,7 @@
 import { GeneratorAdapter, hasCredentials } from '../base';
 import type { AdapterConfig, GenerateParams } from '../base';
 import type { AdapterResult, ProviderName, AdapterMode } from '../types';
+import { splitOpenAiUsage } from './tokens';
 import {
   createCapture,
   captureSourceCode,
@@ -87,17 +88,19 @@ export class OpenAiSdkAdapter extends GeneratorAdapter {
     const usage = result.state.usage;
     const inputTokens = usage.inputTokens;
     const outputTokens = usage.outputTokens;
+    // OpenAI's input token count INCLUDES cached tokens; sum the cached
+    // subset across per-request details (ggui#1186).
+    const cachedInputTokens = (usage.inputTokensDetails ?? []).reduce(
+      (sum, details) => sum + (details.cached_tokens ?? 0),
+      0,
+    );
 
     return {
       compiledCode: capture.compiledCode,
       sourceCode: capture.sourceCode,
       stream: capture.stream,
       generatorMeta: capture.generatorMeta,
-      tokens: {
-        input: inputTokens,
-        output: outputTokens,
-        total: inputTokens + outputTokens,
-      },
+      ...splitOpenAiUsage(inputTokens, outputTokens, cachedInputTokens),
       generationTimeMs: Date.now() - startTime,
       turnsUsed: result.rawResponses?.length ?? 0,
     };

package/src/adapters/openai/tokens.ts

@@ -0,0 +1,49 @@
+import type { AdapterResult } from '../types';
+
+/**
+ * Split an OpenAI usage report into the shared cross-adapter token
+ * convention (ggui#1186).
+ *
+ * OpenAI reports the cached prompt tokens as a SUBSET already counted
+ * inside its input token total (`usage.input_tokens` on the Responses
+ * API, `usage.inputTokens` on the Agents SDK, both INCLUDING cached
+ * tokens). Anthropic (and OpenRouter's Anthropic passthrough) instead
+ * report `input_tokens` EXCLUDING cache reads, with cache reads as a
+ * separate field.
+ *
+ * The whole fleet reads one convention: **`tokens.input` is the
+ * NON-cached input; `cacheReadTokens` is the cache-hit subset.** Cost
+ * and observability consumers price/aggregate `input` at the full input
+ * rate and `cacheReadTokens` at the cache-read rate, so the cached
+ * portion must appear in exactly one of the two — never both. Reporting
+ * OpenAI's cache-inclusive `input_tokens` as `tokens.input` while also
+ * populating `cacheReadTokens` would double-count the cached tokens (it
+ * inflates `$/gen` and breaks `render_cache_metric`'s `cacheReadPct`
+ * denominator). So the OpenAI adapters subtract the cached subset here.
+ *
+ * `total` is the full processed footprint (non-cached input + cache
+ * reads + output = `inputTokensInclCached + outputTokens`), matching the
+ * Claude adapter's `total` (input + cacheCreation + cacheRead + output);
+ * OpenAI has no explicit cache-creation step, so there is no
+ * `cacheCreationTokens` term.
+ */
+export function splitOpenAiUsage(
+  inputTokensInclCached: number,
+  outputTokens: number,
+  cachedTokens: number,
+): { tokens: AdapterResult['tokens']; cacheReadTokens: number } {
+  // Never let a malformed usage report drive input negative.
+  const cacheRead = Math.min(
+    Math.max(cachedTokens, 0),
+    Math.max(inputTokensInclCached, 0),
+  );
+  const nonCachedInput = Math.max(inputTokensInclCached, 0) - cacheRead;
+  return {
+    tokens: {
+      input: nonCachedInput,
+      output: outputTokens,
+      total: nonCachedInput + cacheRead + outputTokens,
+    },
+    cacheReadTokens: cacheRead,
+  };
+}

package/src/adapters/types.ts

@@ -88,7 +88,7 @@ export interface AdapterResult {
   subagentsUsed?: string[];
   /** Tokens written to prompt cache (Claude-specific) */
   cacheCreationTokens?: number;
-  /** Tokens read from prompt cache (Claude-specific) */
+  /** Tokens read from prompt cache (Claude / OpenRouter / OpenAI). */
   cacheReadTokens?: number;
   /** SDK session ID for evaluation loop resume (Claude SDK-specific) */
   sdkSessionId?: string;

package/src/boilerplate/hard-sections.ts

@@ -213,7 +213,7 @@ Rules:
 1. All request-specific data → props with defaults. City names, tickers, user names, dates, counts.
 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. A caps label exists only when a prop supplies its text (\`<Text caps>{props.section}</Text>\`); 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.
+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.
 5. Props interface must be typed and exported.`;
 
 /**

package/src/boilerplate/system-prompt.ts

@@ -603,7 +603,7 @@ Don't render text-only metrics. A weather widget without a sun/cloud, a stock ca
 </Row>
 \`\`\`
 
-Use \`<Icon name="..." />\` for line icons — ONLY the curated Lucide subset renders (call \`get_available_icons\` for the exact kebab-case names; a name outside it renders an empty box and fails the check); emoji directly for status/weather/mood. Both are valid. For per-stat tiny accents, use a small icon next to the label.
+Use \`<Icon name="..." />\` for line icons — ONLY the design system's curated set renders (~200 kebab-case Lucide names); a name OUTSIDE it renders an empty box and fails the check. On a single-pass render you cannot look the set up, so use ONLY a name you are sure is in it. Safe common names: \`check\` \`x\` \`plus\` \`minus\` \`search\` \`settings\` \`user\` \`users\` \`calendar\` \`clock\` \`arrow-right\` \`arrow-left\` \`chevron-right\` \`chevron-down\` \`trash-2\` \`edit\` \`info\` \`alert-circle\` \`bell\` \`home\` \`file\` \`file-text\` \`star\` \`heart\` \`mail\` \`send\` \`download\` \`upload\` \`external-link\` \`filter\` \`check-circle\`. The numbered variants (\`edit-2\`, \`edit-3\`) and synonyms (\`pencil\`, \`pen\`, \`trash\`, \`x-circle\`) are NOT in the set — use \`edit\` and \`trash-2\`. If the icon you want is not clearly one of these, OMIT it: a card with no icon beats one with an empty box. Emoji render directly for status/weather/mood. For per-stat tiny accents, use a small icon next to the label.
 
 ### Spacing — generosity beats compactness
 

package/src/coding-agent/tools.ts

@@ -12,6 +12,10 @@ import * as esbuild from 'esbuild';
 import { AgentWorkspace } from './workspace';
 import { getSoftWarnings } from './self-check';
 import { runTier0Checks } from '../check/index.js';
+import { runGatedAxisChecks, traceAxisChecksSkipped } from '../evaluation/axis-checks/dispatch.js';
+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 {
@@ -46,6 +50,22 @@ function getComponentDocumentation(name: string): string {
 // Auto-commit helper (shared by write and apply_changes)
 // =============================================================================
 
+/**
+ * The deterministic axis family at auto-commit (ggui#1122) — what a caller with a
+ * harness hands `executeTool` so the checks run on EVERY commit the coding agent
+ * makes, i.e. on the serve path, not only inside the eval round a serving deployment
+ * never enters. `checks` is the harness's pre-filtered list (`harness.check.axisChecks`)
+ * — the same list `run-check.ts` feeds the same pure runner. Absent: nothing runs.
+ */
+export interface AutoCommitAxisChecks {
+  readonly checks: readonly AxisCheck[];
+  readonly classification: Classification;
+  /** The ORIGINAL request — several checks read it (labels invented past the copy, terminal words). */
+  readonly originalPrompt: string;
+  /** The canvas the harness was built for (ggui#1117); absent = no rendering context, never a default. */
+  readonly canvas?: CanvasClass;
+}
+
 async function autoCommit(
   workspace: AgentWorkspace,
   commitMeta: Map<string, CommitMetadata>,
@@ -72,6 +92,8 @@ async function autoCommit(
   gadgetTypes?: Readonly<Record<string, string>>,
   /** Which tier-0 legs fire — see `runTier0Checks`'s `designMode`. */
   designMode: DesignMode = DEFAULT_DESIGN_MODE,
+  /** ggui#1122: run the harness's axis checks here too; absent, none run. */
+  axis?: AutoCommitAxisChecks,
 ): Promise<ToolResult> {
   const commitStart = Date.now();
   const raw = workspace.read();
@@ -123,17 +145,45 @@ async function autoCommit(
     gadgetTypes,
     designMode,
   );
-  const tier0Fails = tier0Issues.filter(i => i.result === 'fail');
+  // ggui#1122: the deterministic axis family runs HERE — on every commit the coding
+  // agent makes, which is the serve path — through the one pure runner `run-check.ts`
+  // feeds (the ggui#1046 trace line prints on both paths). Posture is the founder's:
+  // warn-as-warn, fail-as-fail. A WARN that started blocking a served generation
+  // because it moved surface would be a posture change, not a relocation, and comes
+  // to him as a named item. Only a source that BUILT is judged: on a build failure
+  // the checks are not asked (the same stand-down the gate+run wrapper makes) and
+  // the ggui#1046 trace says so — a skipped round never reads as a clean one.
+  const axisFacts = axis !== undefined
+    ? {
+        sourceCode: formatted,
+        ...(contract !== undefined ? { contract } : {}),
+        originalPrompt: axis.originalPrompt,
+        classification: axis.classification,
+        designMode,
+        ...(axis.canvas !== undefined ? { canvas: axis.canvas } : {}),
+      }
+    : undefined;
+  if (axisFacts !== undefined && !buildSuccess) traceAxisChecksSkipped(axisFacts, 'build failed — no check ran');
+  const axisRun = axis !== undefined && axisFacts !== undefined && buildSuccess
+    ? runGatedAxisChecks(axis.checks, { ...axisFacts, compiledCode } satisfies AxisCheckInput)
+    : undefined;
+  const axisIssues = axisRun?.issues ?? [];
+  const checkIssues = [...tier0Issues, ...axisIssues];
+  const tier0Fails = checkIssues.filter(i => i.result === 'fail');
   const selfCheckPassed = tier0Fails.length === 0;
   // When contextPolicy.labeledTier0 is set, prefix each violation with
   // its P0/P1/P2 priority so the LLM can rank against the prompt's
   // schema. The default (off) emits unlabeled feedback.
-  const violations = tier0Issues
+  const violations = checkIssues
     .filter(i => i.result === 'fail')
     .map(i => contextPolicy?.labeledTier0
       ? `[${i.priority ?? 'P0'}-${i.category}] ${i.description}\n  Fix: ${i.fix}`
       : `[${i.category}] ${i.description}\n  Fix: ${i.fix}`);
-  const softWarnings = getSoftWarnings(raw);
+  // Axis WARNs ride the existing non-blocking channel — feedback the model sees, never a block.
+  const axisWarnings = axisIssues
+    .filter(i => i.result === 'warn')
+    .map(i => `[${i.subcategory}] ${i.description} Fix: ${i.fix}`);
+  const softWarnings = [...getSoftWarnings(raw), ...axisWarnings];
   const selfCheckMs = Date.now() - selfCheckStart;
 
   // Always commit (preserves history)
@@ -144,7 +194,7 @@ async function autoCommit(
 
   const status = buildSuccess && selfCheckPassed ? 'PASS' : 'FAIL';
   console.log(
-    `[coding-agent] auto-commit: ${status} | build=${buildMs}ms self-check=${selfCheckMs}ms git=${gitMs}ms total=${Date.now() - commitStart}ms | violations=${violations.length}`,
+    `[coding-agent] auto-commit: ${status} | build=${buildMs}ms self-check=${selfCheckMs}ms git=${gitMs}ms total=${Date.now() - commitStart}ms | violations=${violations.length} | axis=${axisRun === undefined ? 'off' : `${axisIssues.length - axisWarnings.length}F/${axisWarnings.length}W`}`,
   );
   if (violations.length > 0) {
     for (const v of violations) {
@@ -202,6 +252,8 @@ export async function executeTool(
   gadgetTypes?: Readonly<Record<string, string>>,
   /** Which tier-0 legs fire on auto-commit — see `runTier0Checks`'s `designMode`. */
   designMode: DesignMode = DEFAULT_DESIGN_MODE,
+  /** ggui#1122: the harness's axis checks, run at every auto-commit — see `AutoCommitAxisChecks`. */
+  axis?: AutoCommitAxisChecks,
 ): Promise<ToolResult> {
   switch (tool) {
     case 'write':
@@ -222,7 +274,7 @@ export async function executeTool(
       const message = (input.commit_message as string) || `write ${lineCount} lines`;
 
       console.log(`[coding-agent] write: ${lineCount} lines → auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode, axis);
     }
 
     case 'apply_changes': {
@@ -529,7 +581,7 @@ export async function executeTool(
       const message = (input.commit_message as string) || 'apply changes';
 
       console.log(`[coding-agent] apply_changes: ${changes.length} changes applied → auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode, axis);
     }
 
     case 'get_components_info': {

package/src/contract-context.ts

@@ -213,7 +213,7 @@ export function buildContractsContext(
         // model reads it that way. Emitted only when true, so an absent flag
         // leaves the prompt bytes identical to before this line existed.
         if (entry.confirm === true) {
-          line += `\n    Author flag: \`confirm\` — the author marked this action grave enough to confirm before it fires, so a second press is a mistake.`;
+          line += `\n    Author flag: \`confirm\` — the author marked this action as one to confirm with the user before it fires.`;
         }
         return line;
       })

package/src/create-harness.ts

@@ -224,6 +224,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
     name,
     classification,
     designMode,
+    ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
     ...(input.profile !== undefined ? { profile: input.profile } : {}),
     how,
     what,

package/src/evaluation/axis-checks/checks/universal.ts

@@ -4,9 +4,11 @@
 // component. Dispatched via a "universal" gate that matches every render
 // value.
 
-import { LUCIDE_ICON_NAMES } from "@ggui-ai/design";
+import { LUCIDE_ICON_NAMES, maxWidth as CONTAINER_MAX_WIDTH } from "@ggui-ai/design";
+import { CANVAS_VIEWPORTS, type CanvasClass } from "../../../design-mode.js";
 import type { EvalIssue } from "../../types-public.js";
 import type { AxisCheck, AxisCheckInput } from "../types.js";
+import type { DataContract } from "@ggui-ai/protocol";
 import {
   getRequiredPropNames,
   mkIssue,
@@ -391,6 +393,198 @@ function runTerminalActionUnguarded(input: AxisCheckInput): EvalIssue[] {
   ];
 }
 
+// ── universal.root_width_cap (ggui#1117 — the eval leg ggui#1113 left out) ─
+// FRAME_SIZING's width half: the outermost element FILLS the frame; a width
+// cap belongs INSIDE it, on the column that holds text. A cap on the root is
+// the defect on a wide canvas (the card becomes a narrow strip with the
+// frame's ground on either side) and a no-op in a chat bubble (~400 px; a
+// 480 px cap never binds) — so the check reads `input.canvas`: it stands
+// down with no canvas (never a guess) and below `md`, and fires only for a
+// cap SMALLER than the canvas. A bare `<Container>` is a cap too — its
+// default preset is `lg`, 768 px — so it binds on `lg` / `xl` and not on
+// `md`. A cap the check cannot resolve to pixels (a `max-w-*` class, `rem`,
+// `%`) is reported because the prompt forbids it on the root. WARN, not
+// fail: the prompt names the one shape never to write; whether a centred
+// column was the right composition stays the model's call.
+export interface RootWidthCap {
+  /** The outermost element's tag name as written. */
+  readonly element: string;
+  /** The cap as written (`maxWidth="sm"`, `maxWidth: '480px'`, `max-w-md`, or `lg (Container default)`). */
+  readonly cap: string;
+  /** The cap in pixels when it resolves (a Container preset, an `Npx` value); `null` otherwise. */
+  readonly px: number | null;
+}
+
+/** The opening tag of the OUTERMOST element the default export returns, as written; `null` for none or a fragment. */
+function rootOpeningTag(sourceCode: string): { readonly name: string; readonly attrs: string } | null {
+  const start = sourceCode.indexOf("export default function");
+  const body = start >= 0 ? sourceCode.slice(start) : sourceCode;
+  const ret = /\breturn\s*\(?\s*</.exec(body);
+  if (ret === null) return null;
+  const at = ret.index + ret[0].length - 1;
+  const nameMatch = /^<([A-Za-z][\w.]*)/.exec(body.slice(at));
+  if (nameMatch === null) return null;
+  let j = at + nameMatch[0].length;
+  let depth = 0;
+  let quote: string | null = null;
+  for (; j < body.length; j++) {
+    const ch = body[j]!;
+    if (quote !== null) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+    else if (ch === ">" && depth === 0) break;
+  }
+  return { name: nameMatch[1]!, attrs: body.slice(at + nameMatch[0].length, j) };
+}
+
+const CONTAINER_PRESETS: Readonly<Record<string, string>> = CONTAINER_MAX_WIDTH;
+const NOT_A_CAP = new Set(["full", "none", "100%", "unset", "initial", "inherit"]);
+
+/** `sm` → 480; `480px` → 480; `100%` / `full` → not a cap (`undefined`); anything else → a cap of unknown size (`null`). */
+function capPx(value: string): number | null | undefined {
+  const v = value.trim();
+  if (NOT_A_CAP.has(v)) return undefined;
+  const resolved = CONTAINER_PRESETS[v] ?? v;
+  if (NOT_A_CAP.has(resolved)) return undefined;
+  const px = /^(\d+(?:\.\d+)?)px$/.exec(resolved);
+  return px === null ? null : Number(px[1]);
+}
+
+/** The width cap the outermost returned element carries, or `null` when it fills the frame. */
+export function findRootWidthCap(sourceCode: string): RootWidthCap | null {
+  const root = rootOpeningTag(sourceCode);
+  if (root === null) return null;
+  const { name, attrs } = root;
+  const prop = /\bmaxWidth\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|(\d+(?:\.\d+)?))\s*\})/.exec(attrs);
+  if (prop !== null) {
+    const raw = prop[1] ?? prop[2] ?? prop[3] ?? prop[4] ?? `${prop[5]!}px`;
+    const px = capPx(raw);
+    return px === undefined ? null : { element: name, cap: `maxWidth="${raw}"`, px };
+  }
+  const style = /\bmaxWidth\s*:\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`|(\d+(?:\.\d+)?))/.exec(attrs);
+  if (style !== null) {
+    const raw = style[1] ?? style[2] ?? style[3] ?? `${style[4]!}px`;
+    const px = capPx(raw);
+    return px === undefined ? null : { element: name, cap: `maxWidth: '${raw}'`, px };
+  }
+  const cls = /(?<![\w-])max-w-([\w[\]%.-]+)/.exec(attrs);
+  if (cls !== null) {
+    if (cls[1] === "full" || cls[1] === "none") return null;
+    return { element: name, cap: `max-w-${cls[1]!}`, px: null };
+  }
+  if (name === "Container") return { element: name, cap: "lg (Container default)", px: capPx("lg") ?? null };
+  return null;
+}
+
+const WIDE_CANVASES: ReadonlySet<CanvasClass> = new Set<CanvasClass>(["md", "lg", "xl"]);
+
+function runRootWidthCap(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  if (input.canvas === undefined || !WIDE_CANVASES.has(input.canvas)) return [];
+  const cap = findRootWidthCap(input.sourceCode);
+  if (cap === null) return [];
+  const width = CANVAS_VIEWPORTS[input.canvas].width;
+  if (cap.px !== null && cap.px >= width) return [];
+  const sized = cap.px !== null ? `${cap.px}px on a ${width}px canvas` : `on a ${width}px canvas`;
+  return [
+    mkIssue(
+      "universal.root_width_cap",
+      `The outermost element <${cap.element}> carries a width cap (${cap.cap}, ${sized}): on this canvas the card becomes a narrow strip with the frame's ground on either side. The frame owns the width; a cap belongs INSIDE the root, on the column that holds text.`,
+      'Let the root fill the frame — drop the cap on the element you return at the top (or `maxWidth="full"`) — and put the reading measure on an inner column: `<Box padding="lg"><Container maxWidth="sm">…</Container></Box>`.',
+      "warn",
+    ),
+  ];
+}
+
+// ── universal.action_label_dropped (ggui#1190 — the transcription-drop guard) ─
+// The GUARD half of #1190: the model transcribes an actionSpec label onto a
+// control but DROPS a special character ("Confirm & Schedule" → "Confirm
+// Schedule"), because the verbatim label is not at the write-site. This check
+// NAMES that class on the bench and guards regression; the fix (carry the
+// verbatim label / render it from data) lands separately, so #1190 stays open.
+// WARN-class, deterministic, and tuned to flag ONLY the high-confidence drop.
+
+const LABEL_SPECIAL_CHAR = /[^a-z0-9\s]/i;
+const normText = (s: string): string => s.toLowerCase().replace(/\s+/g, " ").trim();
+const alnumText = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+
+/**
+ * Extract the VISIBLE rendered text of a component — JSX text nodes (with `{…}`
+ * expression containers stripped, nesting-aware) plus visible string
+ * attributes (aria-label / placeholder / title / alt). Deliberately excludes
+ * identifiers and call args: `useAction('confirmSchedule')` and the `const
+ * confirmSchedule` binding must NOT count as the label "Confirm & Schedule"
+ * appearing, or every action would false-match its own camelCase name.
+ */
+function visibleText(sourceCode: string): string {
+  // JSX text nodes: `>text<`. Excluding `>` from the run (`[^<>]`) skips the
+  // `=>` arrow-body conflation — an arrow's `>` is followed by code then a
+  // `>`, never text then a `<`, so only true tag-close→text→tag runs match,
+  // and identifiers (`const confirmSchedule`, `useAction('confirmSchedule')`)
+  // are never between `>` and `<`. `{…}` expression children are stripped so an
+  // expression's identifiers don't count as visible text.
+  const jsx = (sourceCode.match(/>([^<>]*)</g) ?? [])
+    .map((m) => m.slice(1, -1).replace(/\{[^}]*\}/g, " "))
+    .join(" ");
+  let attrs = "";
+  const attrRx = /\b(?:aria-label|placeholder|title|alt)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+  let m: RegExpExecArray | null;
+  while ((m = attrRx.exec(sourceCode)) !== null) attrs += " " + (m[1] ?? m[2] ?? "");
+  return jsx + " " + attrs;
+}
+
+/**
+ * Find actionSpec labels whose special-character content was dropped from the
+ * generated source. FALSE-POSITIVE-SAFE by construction — flags ONLY when the
+ * label's alphanumeric words appear CONTIGUOUSLY in the source but the full
+ * label (with its "&", "/", "+" …) does not, i.e. a clean transcription drop.
+ * Every ambiguous shape is exempt: labels rendered from data (`.label`
+ * anywhere), labels with no special char (nothing to drop), labels present
+ * verbatim, entity-encoded `&` (`&amp;` — the words stop being contiguous, so
+ * no flag), and very short labels. Presence-ANYWHERE, not wiring-scoped, on
+ * purpose: if the label's text appears anywhere we never flag.
+ */
+export function findDroppedActionLabels(
+  sourceCode: string,
+  contract: DataContract | undefined,
+): Array<{ readonly name: string; readonly label: string }> {
+  const actionSpec = contract?.actionSpec;
+  if (actionSpec === undefined) return [];
+  // Component renders any label from data → it does not transcribe → exempt all.
+  if (/\.label\b/.test(sourceCode)) return [];
+  const vis = visibleText(sourceCode);
+  const normVis = normText(vis);
+  const alnumVis = alnumText(vis);
+  const out: Array<{ name: string; label: string }> = [];
+  for (const [name, entry] of Object.entries(actionSpec)) {
+    const label = entry.label;
+    if (typeof label !== "string" || label.length === 0 || label === name) continue;
+    if (!LABEL_SPECIAL_CHAR.test(label)) continue; // no special char → nothing to drop
+    if (alnumText(label).length < 3) continue; // too short to match confidently
+    if (normVis.includes(normText(label))) continue; // present verbatim in visible text → correct
+    // The label's words appear contiguously in the VISIBLE text but the full
+    // label (with its punctuation) does not → a character was dropped.
+    if (alnumVis.includes(alnumText(label))) out.push({ name, label });
+  }
+  return out;
+}
+
+function runActionLabelDropped(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  return findDroppedActionLabels(input.sourceCode, input.contract).map(({ name, label }) =>
+    mkIssue(
+      "universal.action_label_dropped",
+      `The action "${name}" declares label "${label}", but the rendered control appears to drop its "${label.replace(/[a-z0-9\s]/gi, "").trim()}": the label's words are in the generated source, the full label is not — a transcription drop (ggui#1190).`,
+      `Render the label EXACTLY as the contract states it — button text should be the verbatim \`actionSpec.${name}.label\`, or render it from data (\`{x.label}\`), never a re-typed copy that drops "&", "/", "+", etc.`,
+      "warn",
+    ),
+  );
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.icon_name_known",
@@ -410,6 +604,18 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runViewportSized,
   },
+  {
+    id: "universal.root_width_cap",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runRootWidthCap,
+  },
+  {
+    id: "universal.action_label_dropped",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runActionLabelDropped,
+  },
   {
     id: "universal.terminal_action_unguarded",
     axis: "render",