@ggui-ai/ui-gen 0.16.0 → 0.17.0

package/src/create-ui-generator.ts

@@ -31,6 +31,7 @@
  * Callers who want a lightweight single-shot path can build it
  * themselves.
  */
+import type { SingleComponentParams } from './harness/runtime.js';
 import type {
   GadgetDescriptor,
   GenerationError,
@@ -55,6 +56,8 @@ import {
 } from '@ggui-ai/mcp-server-core';
 import { createGeneratorTools } from './adapters/index.js';
 import { dispatchGeneration } from './adapters/generation-dispatch.js';
+import { hasProfile } from './boilerplate/styling-profile.js';
+import { effortDials } from './effort.js';
 import type { ProviderName } from './adapters/types.js';
 import type { GenerationResult } from './harness/result-types.js';
 import {
@@ -67,6 +70,7 @@ import type { RenderingContext } from './contract-context.js';
 import type { DesignMode } from './design-mode.js';
 import { resolveRoute, applyRouteToEnv } from './adapters/provider-router.js';
 import type { QualityConfig } from './evaluation/types-public.js';
+import type { EvaluationConfig } from './evaluation/types.js';
 import type { AgentConfig } from './harness/llm-router.js';
 
 /** The slug for the OSS default seed generator. */
@@ -89,6 +93,20 @@ export interface CreateUiGeneratorOptions {
   readonly maxAttempts?: number;
   /** Maximum evaluation rounds. */
   readonly maxEvalRounds?: number;
+  /**
+   * In-loop LLM evaluation config (ggui#1001). When set, every generation
+   * runs the evaluator tiers after the coding leg (`maxRounds` defaults to
+   * `maxEvalRounds`) and the harness result carries `evalResult` — the
+   * probe verdict a downstream judge reads. Default: none, as today —
+   * a serving deployment leaves it unset; offline minting jobs set a round.
+   */
+  readonly evaluation?: EvaluationConfig;
+  /**
+   * In-loop visual round config (per-canvas judging, a sample, the
+   * stylesheet to render under). Forwarded verbatim; never part of the
+   * prompt or the identity. Default: none — the round runs as today.
+   */
+  readonly visualEvaluation?: SingleComponentParams['visualEvaluation'];
   /** Quality config controlling eval tiers + improvement behavior. */
   readonly qualityConfig?: QualityConfig;
   /**
@@ -208,6 +226,8 @@ export function createUiGenerator(
     enableRuntimeRender = false,
     maxAttempts,
     maxEvalRounds,
+    evaluation,
+    visualEvaluation,
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
@@ -313,6 +333,7 @@ export function createUiGenerator(
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance,
+          { profileDeclared: hasProfile(input.profile) },
         );
 
         // Resolve appGadgets by precedence:
@@ -335,6 +356,19 @@ export function createUiGenerator(
           resolvedAppGadgets,
         );
 
+        // `effort` (ggui#1059): a named level's dials override the
+        // deployment's options for THIS generation; absent ⇒ untouched.
+        // Prompt bytes never move with it (dials only).
+        const dials = effortDials(input.profile?.effort);
+        const effectiveMaxAttempts = dials?.maxAttempts ?? maxAttempts;
+        const effectiveMaxEvalRounds = dials?.maxEvalRounds ?? maxEvalRounds;
+        const effectiveEvaluation =
+          dials !== undefined && evaluation !== undefined ? { ...evaluation, maxRounds: dials.maxEvalRounds } : evaluation;
+        const effectiveVisualEvaluation =
+          dials !== undefined && visualEvaluation !== undefined
+            ? { ...visualEvaluation, passThreshold: dials.selfEvalPassThreshold }
+            : visualEvaluation;
+
         const result = await dispatchGeneration({
           provider,
           userPrompt,
@@ -342,8 +376,10 @@ export function createUiGenerator(
           tools,
           ...(input.contract ? { contract: input.contract } : {}),
           originalPrompt: input.request.prompt,
-          ...(maxAttempts !== undefined ? { maxAttempts } : {}),
-          ...(maxEvalRounds !== undefined ? { maxEvalRounds } : {}),
+          ...(effectiveMaxAttempts !== undefined ? { maxAttempts: effectiveMaxAttempts } : {}),
+          ...(effectiveMaxEvalRounds !== undefined ? { maxEvalRounds: effectiveMaxEvalRounds } : {}),
+          ...(effectiveEvaluation !== undefined ? { evaluation: effectiveEvaluation } : {}),
+          ...(effectiveVisualEvaluation !== undefined ? { visualEvaluation: effectiveVisualEvaluation } : {}),
           ...(qualityConfig !== undefined ? { qualityConfig } : {}),
           ...(resolvedAppGadgets !== undefined
             ? { appGadgets: resolvedAppGadgets }
@@ -360,6 +396,9 @@ export function createUiGenerator(
           ...(onRetry !== undefined ? { onRetry } : {}),
           ...(designMode !== undefined ? { designMode } : {}),
           ...(canvas !== undefined ? { canvas } : {}),
+          ...(input.profile !== undefined ? { profile: input.profile } : {}),
+          // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
+          ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
         });
 
         onGenerated?.(result);

package/src/design-mode.ts

@@ -77,6 +77,16 @@ export type CanvasDisplayMode = "inline" | "fullscreen";
  * canvas display mode. Only `chat` and `inline` are the inline card;
  * everything else is width-governed.
  */
+/**
+ * The display mode a JUDGE canvas stands for (ggui#1100): the inline chat
+ * card is `xs-chat-card`; every other canvas is a surface the component
+ * owns edge to edge, which the served runtime composes with `fit: 'fill'`
+ * — so the judge must too, or it scores a picture the user never sees.
+ */
+export function displayModeForCanvas(canvas: CanvasClass): CanvasDisplayMode {
+  return canvas === "xs-chat-card" ? "inline" : "fullscreen";
+}
+
 export function canvasDisplayModeForShell(shell: string | undefined): CanvasDisplayMode {
   return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
 }
@@ -177,6 +187,6 @@ export function describeCanvas(canvas: CanvasClass): string {
   return (
     `This component renders on the \`${canvas}\` canvas (${d.label}): ` +
     `${d.minWidthPx}–${d.maxWidthPx}px wide, ${d.host}. ` +
-    `Design for the whole range — the host may size the iframe anywhere inside it.`
+    `Design for the whole range — the host may size the iframe anywhere inside it, and the host owns the height: size to your content, never to the viewport.`
   );
 }

package/src/design-system-docs.ts

@@ -26,7 +26,7 @@ export const DEFAULT_DESIGN_SYSTEM_DOCS = `# Design System - Default Light Theme
 - var(--ggui-color-primary-300) - #7dd3fc
 - var(--ggui-color-primary-400) - #38bdf8
 - var(--ggui-color-primary-500) - #0ea5e9
-- var(--ggui-color-primary-600) - #0284c7 (main action color)
+- var(--ggui-color-primary-600) - #0284c7 (main action FILL — buttons, borders, icon fills; accent TEXT takes the link role below)
 - var(--ggui-color-primary-700) - #0369a1
 - var(--ggui-color-primary-800) - #075985
 - var(--ggui-color-primary-900) - #0c4a6e
@@ -42,10 +42,11 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 | onContainer | var(--ggui-color-onContainer) | Body text on a card |
 | elevated | var(--ggui-color-elevated) | Menus, popovers, modals, toasts — floats above a card |
 | onElevated | var(--ggui-color-onElevated) | Text on an elevated surface |
+| heroGround | var(--ggui-color-heroGround) | A hero / greeting panel's ground — brand-tinted on a light host, the ink pair on a dark one (Card surface="hero") |
+| onHeroGround | var(--ggui-color-onHeroGround) | Text on the hero ground |
 | sunken | var(--ggui-color-sunken) | Wells, inputs at rest, code blocks — recessed inside a card |
 | onSunken | var(--ggui-color-onSunken) | Muted / secondary text |
-| container | var(--ggui-color-container) | Primary-branded containers |
-| onContainer | var(--ggui-color-onContainer) | Text on branded containers |
+| link | var(--ggui-color-link) | Accent TEXT — eyebrows, taglines, links, labels, inline arrows: the brand's readable ink, derived per mode to clear 4.5:1 on the container and the ground |
 | outline | var(--ggui-color-outline) | Borders, dividers |
 | outlineVariant | var(--ggui-color-outlineVariant) | Subtle borders |
 
@@ -54,6 +55,7 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 - Body text → \`var(--ggui-color-onContainer)\`
 - Card/panel background → \`var(--ggui-color-container)\`; recessed wells / inputs → \`var(--ggui-color-sunken)\`
 - Secondary/muted text → \`var(--ggui-color-onSunken)\`
+- Accent / branded text (eyebrow, tagline, link, label, inline arrow) → \`var(--ggui-color-link)\` or \`<Text tone="emphasized">\` — never a bare \`primary-<stop>\` as a text color
 - Branded section/header → \`var(--ggui-color-container)\` bg + \`var(--ggui-color-onContainer)\` text
 - Borders/dividers → \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
@@ -172,7 +174,8 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 - **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each — use them for every background/text/border decision; they adapt to any theme
 - **primary-50/100**: Section backgrounds, highlight strips, card headers
 - **primary-200/300**: Borders, dividers, focus rings, input outlines
-- **primary-500/600**: Icons, links, labels, badges, buttons, CTAs
+- **primary-500/600**: Filled buttons, CTAs, badges, icon fills, active indicators — fills and borders, NOT a text color
+- **link**: Accent TEXT — eyebrows, taglines, links, labels, inline arrows; the brand's readable ink per mode (a bare \`primary-300…600\` as a text color fails tier-0: \`universal.accent_text_ink\`)
 - **primary-700/800/900**: Headings and text on light primary backgrounds
 - **neutral-***: Only when you need a specific shade that semantic tokens don't cover
 

package/src/effort.ts

@@ -0,0 +1,48 @@
+// The `effort` reader table (ggui#1059, A2). The wire carries ONLY the level
+// name (`generation.profile.effort`, protocol #1058); this table is the
+// cold-gen READER that maps a name onto the harness's dials, versioned here
+// so a level's meaning (and its price line) can move without a wire change.
+//
+// Boundaries, stated once:
+//  - `effort` renders NO prompt text — the prompt is byte-identical under any
+//    level (`profile-cross.pin.test.ts`). Dials only.
+//  - Absent ⇒ the deployment's own options, untouched. The table is applied
+//    only when a level is named.
+//  - `selfEvalPassThreshold` is the GENERATOR's in-loop visual
+//    self-evaluation threshold (`visualEvaluation.passThreshold`). A serving
+//    layer's own acceptance bar is a different number and does not move with
+//    `effort`.
+//  - `modelTier` / `judgeTier` are REQUESTS to the deployment's router
+//    (`fast | balanced | premium`), never a model id: a deployment with one
+//    key is never promoted by a profile. The harness does not act on them;
+//    the caller that owns model selection reads them from this table.
+import type { AppGenerationProfileEffort, ModelTier } from "@ggui-ai/protocol";
+
+/** Bump when a level's meaning changes; the price line beside it follows. */
+export const EFFORT_TABLE_VERSION = 1;
+
+export interface EffortDials {
+  /** Coding-loop turn cap (`maxAttempts`). */
+  readonly maxAttempts: number;
+  /** Evaluation rounds the harness may spend (`maxEvalRounds`). */
+  readonly maxEvalRounds: number;
+  /** The generator's in-loop visual self-evaluation threshold, 0–100 — not a serving layer's acceptance bar. */
+  readonly selfEvalPassThreshold: number;
+  /** Requested coding-model tier — a request to the deployment's router, never a model id. */
+  readonly modelTier: ModelTier;
+  /** Requested judge-model tier — same nature. */
+  readonly judgeTier: ModelTier;
+}
+
+export const EFFORT_DIALS: Readonly<Record<AppGenerationProfileEffort, EffortDials>> = {
+  low: { maxAttempts: 5, maxEvalRounds: 1, selfEvalPassThreshold: 65, modelTier: "fast", judgeTier: "fast" },
+  medium: { maxAttempts: 8, maxEvalRounds: 2, selfEvalPassThreshold: 70, modelTier: "fast", judgeTier: "balanced" },
+  high: { maxAttempts: 8, maxEvalRounds: 3, selfEvalPassThreshold: 75, modelTier: "balanced", judgeTier: "balanced" },
+  xhigh: { maxAttempts: 10, maxEvalRounds: 3, selfEvalPassThreshold: 80, modelTier: "premium", judgeTier: "balanced" },
+  ultra: { maxAttempts: 12, maxEvalRounds: 4, selfEvalPassThreshold: 85, modelTier: "premium", judgeTier: "premium" },
+};
+
+/** The dials for a named level; `undefined` when no level is named (the deployment's options stand). */
+export function effortDials(effort: AppGenerationProfileEffort | undefined): EffortDials | undefined {
+  return effort === undefined ? undefined : EFFORT_DIALS[effort];
+}

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

@@ -0,0 +1,148 @@
+// packages/ui-gen/src/evaluation/axis-checks/checks/grid.ts
+//
+// Checks gated on `render=grid`.
+//
+// ── grid.board_columns_side_by_side (ggui#1046) ─────────────────────────
+// A kanban classifies as `render=grid` (the classifier's GRID_RX carries
+// `kanban`), and three of four constrained mints on the candidate-15 image
+// composed the board's columns as a vertical <Stack> of sections — no <Grid>
+// anywhere — then read below the judge's bar; the tier-2 evaluator saw the
+// stacking only as a `warn`, which never costs a fix turn. This check reads
+// the source the way the fix turn must: find the JSX map over the board's
+// columns array and name the layout primitive that ENCLOSES it. <Grid> or
+// <Row> = side by side; <Stack> / <Card> / <Box> / a bare block / nothing =
+// stacked. Stands down in `free` design mode, where the primitive is optional.
+
+import type { EvalIssue } from "../../types-public.js";
+import type { AxisCheck, AxisCheckInput } from "../types.js";
+import { axisCheckTraceEnabled, mkIssue } from "../helpers.js";
+
+/** Prop names a board's column array goes by. */
+const BOARD_PROP_RX = /^(columns?|lanes?|stages?|lists?|buckets?|swimlanes?)$/i;
+const BOARD_PROMPT_RX = /\b(kanban|board)\b/i;
+/** The names a board's column array goes by, for the prompt and source paths. */
+const BOARD_NAMES = ["columns", "lanes", "stages", "lists", "buckets", "swimlanes"] as const;
+/** Layout primitives whose nesting decides side-by-side vs stacked. */
+const LAYOUT_TAG_RX = /<(\/?)(Grid|Row|Stack|Card|Box|Container|ScrollArea|div|section)\b([^<>]*?)>/g;
+const SIDE_BY_SIDE = new Set(["Grid", "Row"]);
+
+interface PropShapeLike {
+  type?: string;
+  schema?: { type?: string };
+}
+
+/** The board prop names the contract declares as arrays. */
+export function boardPropNames(contract: AxisCheckInput["contract"]): string[] {
+  const propsField = contract?.propsSpec as { properties?: Record<string, PropShapeLike> } | undefined;
+  const properties = propsField?.properties ?? {};
+  return Object.entries(properties)
+    .filter(([name, p]) => BOARD_PROP_RX.test(name) && (p?.type === "array" || p?.schema?.type === "array"))
+    .map(([name]) => name);
+}
+
+/**
+ * Every JSX map over `name`, by index — an expression-body arrow (`name.map((col) => (<…`)
+ * or a block-body one (`name.map((col) => { … return (<…`); the serving deployment's candidate-18 kanban
+ * mints composed two of three stacked boards through the block form (ggui#1046), which the
+ * first reader never matched.
+ */
+function jsxMapPositions(sourceCode: string, name: string): number[] {
+  const rx = new RegExp(
+    `\\b${name}(?:\\?\\.)?\\.map\\(\\s*\\(?\\s*\\w+(?:\\s*,\\s*\\w+)?\\s*\\)?\\s*=>\\s*(?:\\(?\\s*<|\\{[^{}]{0,600}?\\breturn\\s*\\(?\\s*<)`,
+    "g",
+  );
+  return [...sourceCode.matchAll(rx)].map((m) => m.index ?? 0);
+}
+
+/** The layout primitive enclosing `pos`, walked as a tag stack over the source before it. */
+export function enclosingLayoutTag(sourceCode: string, pos: number): string | undefined {
+  const stack: string[] = [];
+  for (const m of sourceCode.slice(0, pos).matchAll(LAYOUT_TAG_RX)) {
+    const closing = m[1] === "/";
+    const name = m[2] ?? "";
+    const attrs = m[3] ?? "";
+    if (closing) {
+      if (stack[stack.length - 1] === name) stack.pop();
+      continue;
+    }
+    if (attrs.trimEnd().endsWith("/")) continue; // self-closing
+    stack.push(name);
+  }
+  return stack[stack.length - 1];
+}
+
+/** What the check read (ggui#1046): the board names it walked and, per name, every JSX map's enclosing layout tag. */
+export interface BoardRead {
+  readonly declared: readonly string[];
+  readonly names: readonly string[];
+  readonly perName: ReadonlyArray<{ readonly name: string; readonly maps: number; readonly enclosing: readonly string[] }>;
+}
+
+/** The board check's own trace line (ggui#1046). */
+export interface BoardColumnsTrace extends BoardRead {
+  readonly designMode: string;
+  readonly standDown: boolean;
+  readonly result: "pass" | "fail" | "stand-down";
+}
+
+export function describeBoardRead(input: AxisCheckInput): BoardRead {
+  // Which array the board's columns are: the contract names it; else the prompt says
+  // "board" / "kanban"; else the SOURCE itself does — a JSX map over a board-shaped name
+  // (ggui#1046: on candidate 20 the check flagged every stacked source locally and none on
+  // the serving deployment, where the contract and prompt reach it in another shape; the
+  // source is the one input every path hands over verbatim).
+  const declared = boardPropNames(input.contract);
+  const names = declared.length > 0
+    ? declared
+    : BOARD_PROMPT_RX.test(input.originalPrompt)
+      ? [...BOARD_NAMES]
+      : BOARD_NAMES.filter((n) => jsxMapPositions(input.sourceCode, n).length > 0);
+  const perName = names.map((name) => {
+    const positions = jsxMapPositions(input.sourceCode, name);
+    return { name, maps: positions.length, enclosing: positions.map((pos) => enclosingLayoutTag(input.sourceCode, pos) ?? "nothing") };
+  });
+  return { declared, names, perName };
+}
+
+/** Board maps composed under something other than <Grid> / <Row>: `[propName, enclosing tag or "nothing"]`. */
+export function findStackedBoardColumns(input: AxisCheckInput): Array<readonly [string, string]> {
+  const stacked: Array<readonly [string, string]> = [];
+  for (const { name, enclosing } of describeBoardRead(input).perName) {
+    for (const tag of enclosing) if (!SIDE_BY_SIDE.has(tag)) stacked.push([name, tag]);
+  }
+  return stacked;
+}
+
+function runBoardColumnsSideBySide(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const standDown = input.designMode === "free";
+  const stacked = standDown ? [] : findStackedBoardColumns(input);
+  if (axisCheckTraceEnabled()) {
+    // The check's own line beside the dispatcher's (ggui#1046): what it read, PASS and stand-down included.
+    const line: BoardColumnsTrace = {
+      ...describeBoardRead(input),
+      designMode: input.designMode ?? "constrained",
+      standDown,
+      result: standDown ? "stand-down" : stacked.length > 0 ? "fail" : "pass",
+    };
+    console.log(JSON.stringify({ boardColumnsTrace: line }));
+  }
+  if (stacked.length === 0) return [];
+  const [name, tag] = stacked[0]!;
+  return [
+    mkIssue(
+      "grid.board_columns_side_by_side",
+      `The board's \`${name}\` are composed under <${tag}> — a vertical stack of column sections; at md and wider the columns must sit side by side.`,
+      `Wrap the ${name} map in <Grid columns={{ base: 1, md: ${name}.length }} gap="md"> (each column its own <Stack> of cards); never a <Stack> of column sections.`,
+    ),
+  ];
+}
+
+export const GRID_CHECKS: readonly AxisCheck[] = [
+  {
+    id: "grid.board_columns_side_by_side",
+    axis: "render",
+    values: ["grid"],
+    run: runBoardColumnsSideBySide,
+  },
+];

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

@@ -4,6 +4,7 @@
 // component. Dispatched via a "universal" gate that matches every render
 // value.
 
+import { LUCIDE_ICON_NAMES } from "@ggui-ai/design";
 import type { EvalIssue } from "../../types-public.js";
 import type { AxisCheck, AxisCheckInput } from "../types.js";
 import {
@@ -119,7 +120,250 @@ function runPropSeedNoResync(input: AxisCheckInput): EvalIssue[] {
   return issues;
 }
 
+// ── universal.icon_name_known (ggui#1015) ────────────────────────────
+// The Icon primitive renders ONLY its curated Lucide subset; an unknown
+// name renders an empty box. The model reaches for names from the full
+// Lucide set ("sparkles", "arrow-up-right" on the hello frames), so the
+// check flags every string-literal `<Icon name>` outside the subset —
+// the fix turn has `get_available_icons`. Dynamic names (`name={x}`)
+// and emoji/unicode (rendered as text) are outside the check's scope.
+
+/** Icon.tsx's resolver rule: exact key, else dashes/underscores stripped + lowercased. */
+const KNOWN_ICON_KEYS: ReadonlySet<string> = new Set(
+  LUCIDE_ICON_NAMES.map((n) => n.replace(/[-_]/g, "").toLowerCase()),
+);
+
+export function isKnownIconName(name: string): boolean {
+  return KNOWN_ICON_KEYS.has(name.replace(/[-_]/g, "").toLowerCase());
+}
+
+const ICON_NAME_LITERAL_RX =
+  /<Icon\b[^>]*?\bname\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*"([^"]*)"\s*\}|\{\s*'([^']*)'\s*\})/g;
+
+export function findUnknownIconNames(sourceCode: string): string[] {
+  const unknown = new Set<string>();
+  for (const m of sourceCode.matchAll(ICON_NAME_LITERAL_RX)) {
+    const name = m[1] ?? m[2] ?? m[3] ?? m[4] ?? "";
+    if (name.length === 0) continue;
+    if (/[^\x20-\x7e]/.test(name)) continue; // emoji / unicode passthrough renders as text
+    if (!isKnownIconName(name)) unknown.add(name);
+  }
+  return [...unknown];
+}
+
+function runIconNameKnown(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const unknown = findUnknownIconNames(input.sourceCode);
+  if (unknown.length === 0) return [];
+  const list = unknown.map((n) => `"${n}"`).join(", ");
+  return [
+    mkIssue(
+      "universal.icon_name_known",
+      `<Icon name=…> uses ${unknown.length} name(s) outside the design system's Lucide subset: ${list} — an unknown name renders an empty box.`,
+      "Call get_available_icons and pick a listed name (kebab-case), or use an emoji directly.",
+    ),
+  ];
+}
+
+// ── universal.accent_text_ink (ggui#1039) ────────────────────────────
+// The brand ladder's mid stops (300–600) are FILL colours. On a
+// low-saturation brand the 600 stop is mid-grey on the surface, and every
+// one of four brand-directed hello frames painted its eyebrow and inline
+// arrows with it — two of them at 3.5:1 and 2.91:1 on the ground. Accent
+// TEXT is the theme's readable ink `--ggui-color-link` (derived per mode to
+// clear 4.5:1, ggui#1035) or `<Text tone="emphasized">`; `link` resolves to
+// the very same 600 wherever 600 already reads, so the fix never regresses a
+// saturated brand. Out of scope by design: tints as text (50–200 — the
+// on-fill idiom, `primary-50` on a `primary-600` bubble) and the deep stops
+// (700–900 — text on a light primary tint), both documented uses. Matches the
+// `color` property in every spelling the model writes — JSX prop, style
+// object (source and compiled), CSS declaration — and never a compound
+// property (`backgroundColor`, `border-color`, `accent-color`).
+
+const LADDER_STOP_AS_TEXT_RX =
+  /(?<![\w-])color\s*(?:=\s*\{?\s*|:\s*)["'`]?\s*var\(--ggui-color-primary-(\d{2,3})\s*[,)]/g;
+const TEXT_INK_STOP_MIN = 300;
+const TEXT_INK_STOP_MAX = 600;
+
+/** Distinct `primary-<stop>` tokens (300–600) the source paints as a text `color`, in source order. */
+export function findLadderStopsAsText(sourceCode: string): string[] {
+  const found = new Set<string>();
+  for (const m of sourceCode.matchAll(LADDER_STOP_AS_TEXT_RX)) {
+    const digits = m[1] ?? "";
+    const stop = Number(digits);
+    if (stop >= TEXT_INK_STOP_MIN && stop <= TEXT_INK_STOP_MAX) found.add(`primary-${digits}`);
+  }
+  return [...found];
+}
+
+function runAccentTextInk(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const stops = findLadderStopsAsText(input.sourceCode);
+  if (stops.length === 0) return [];
+  const list = stops.map((s) => `\`${s}\``).join(", ");
+  return [
+    mkIssue(
+      "universal.accent_text_ink",
+      `Text is painted with a brand-ladder fill stop as its color (${list}) — on a low-saturation brand these stops are mid-grey on the surface and the text fails readability.`,
+      'Accent text (eyebrows, taglines, links, labels, inline arrows) takes var(--ggui-color-link) or <Text tone="emphasized">; body text takes var(--ggui-color-onContainer); keep primary-* stops on fills and borders.',
+    ),
+  ];
+}
+
+// ── universal.scoped_surface_owns_ground (ggui#1047) ─────────────────
+// A SCOPED surface — `surface="inverted"` or `"hero"` on Card / Box — owns its
+// ground: the primitive paints it, the scope rule swaps every ink beneath it.
+// The served Mosaic hello repainted an inverted card's ground with the page's
+// (`style={{ background: 'var(--ggui-color-ground)' }}`) and its hero text
+// read 1:1 — the swapped inks over a ground the scope did not own. The design
+// package now strips that background at render; this check makes the fix turn
+// remove it at the source, so the author's intent never silently vanishes.
+// Stands down in `free` design mode (the primitive is optional there).
+
+const SCOPED_SURFACE_TAG_RX = /<(Card|Box)\b([^<>]*?)surface\s*=\s*["'](inverted|hero)["']([^<>]*?)>/g;
+const STYLE_BACKGROUND_RX = /\bstyle\s*=\s*\{\{[^}]*\b(background|backgroundColor|backgroundImage)\s*:/;
+
+/** `[tag, surface]` for every scoped Card / Box whose own `style` sets a background. */
+export function findScopedSurfaceBackgrounds(sourceCode: string): Array<readonly [string, string]> {
+  const hits: Array<readonly [string, string]> = [];
+  for (const m of sourceCode.matchAll(SCOPED_SURFACE_TAG_RX)) {
+    const attrs = `${m[2] ?? ""} ${m[4] ?? ""}`;
+    if (STYLE_BACKGROUND_RX.test(attrs)) hits.push([m[1] ?? "", m[3] ?? ""]);
+  }
+  return hits;
+}
+
+function runScopedSurfaceOwnsGround(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  if (input.designMode === "free") return [];
+  const hits = findScopedSurfaceBackgrounds(input.sourceCode);
+  if (hits.length === 0) return [];
+  const [tag, surface] = hits[0]!;
+  return [
+    mkIssue(
+      "universal.scoped_surface_owns_ground",
+      `<${tag} surface="${surface}"> sets its own background in style — a scoped surface owns its ground; repainting it puts the scope's swapped inks over the wrong ground (ink on ink).`,
+      `Remove the background from that ${tag}'s style — surface="${surface}" paints the ground; pick another surface if a different ground is wanted.`,
+    ),
+  ];
+}
+
+// ── universal.caps_label_invented (ggui#1075 Track A) ─────────────────
+// A caps label (`<Text caps>` — the eyebrow / kicker / overline treatment)
+// whose entire content is a string literal is copy the model INVENTED: the
+// contract carries no such member, so nothing the agent sends can change
+// it, and every served card wears it ("LET'S BEGIN", "WELCOME" — 59 of 63
+// generated sources in one sample, none bound to a prop). Copy comes from the
+// props; a caps label exists only when a prop supplies its text. A label
+// whose content is an expression (`{props.section}`, `{label ?? …}`) is
+// bound and passes; a `<Text caps>` with no text children is not a label.
+const CAPS_TEXT_RX = /<Text\b(?=[^>]*\bcaps\b)[^>]*>([\s\S]*?)<\/Text>/g;
+
+/** Every `<Text caps>` whose content is nothing but literal text: `[literal]`. */
+export function findInventedCapsLabels(sourceCode: string): string[] {
+  const out: string[] = [];
+  for (const m of sourceCode.matchAll(CAPS_TEXT_RX)) {
+    const inner = (m[1] ?? "").trim();
+    if (inner.length === 0) continue;
+    if (inner.includes("{")) continue; // bound to an expression — the props speak
+    out.push(inner.replace(/\s+/g, " ").slice(0, 60));
+  }
+  return out;
+}
+
+function runCapsLabelInvented(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const invented = findInventedCapsLabels(input.sourceCode);
+  if (invented.length === 0) return [];
+  const list = invented.map((t) => `"${t}"`).join(", ");
+  return [
+    mkIssue(
+      "universal.caps_label_invented",
+      `${invented.length} caps label(s) carry invented copy the props do not supply: ${list} — an eyebrow, kicker or overline the agent cannot change is chatter on every render.`,
+      "Remove the label, or bind its text to a prop (`<Text caps>{props.section}</Text>`); copy comes from the contract, never from the component.",
+    ),
+  ];
+}
+
+// ── universal.viewport_sized (ggui#1075 Track A/B, receipted on #1096) ─
+// An element sized to the viewport — `100vh` / `100dvh` / `100svh` / `100lvh`
+// (bare or inside `calc()`) as a `height` / `min-height`, or the `h-screen` /
+// `min-h-screen` utility classes. The frame owns the height: a content-sized
+// frame is measured FROM the content, so a viewport-sized root can never
+// shrink and grows the frame on every re-measure; under fullscreen the frame
+// already stretches the root to its height. 20 of 48 minted cells in one
+// sample carried `minHeight: "100vh"` on their root — one an inline chat
+// card told "compact". A `max-height` cap on a scroll region is not sizing
+// and passes; so do `height: 100%`, `flex: 1` and pixel heights.
+// The unit, with a `calc(…)` wrapper closed when present — so the quoted
+// snippet reads whole (`height: "calc(100dvh - 64px)"`).
+const VIEWPORT_UNIT = String.raw`(?:calc\(\s*)?100(?:vh|dvh|svh|lvh)\b(?:[^)"'\x60;\n]*\))?`;
+const VIEWPORT_STYLE_OBJECT_RX = new RegExp(
+  String.raw`\b(?:minHeight|height|minBlockSize|blockSize)\s*:\s*["'\x60]\s*${VIEWPORT_UNIT}["'\x60]?`,
+  "g",
+);
+const VIEWPORT_CSS_RX = new RegExp(
+  String.raw`(?<![\w-])(?:min-)?(?:height|block-size)\s*:\s*${VIEWPORT_UNIT}`,
+  "g",
+);
+const VIEWPORT_CLASS_RX = /(?<![\w-])(?:min-)?h-(?:screen|dvh|svh|lvh)\b/g;
+
+/** Every viewport-sized height in the source, as written (trimmed, ≤ 60 chars), in order. */
+export function findViewportSizing(sourceCode: string): string[] {
+  const hits: Array<{ at: number; text: string }> = [];
+  for (const rx of [VIEWPORT_STYLE_OBJECT_RX, VIEWPORT_CSS_RX, VIEWPORT_CLASS_RX]) {
+    for (const m of sourceCode.matchAll(rx)) {
+      hits.push({ at: m.index ?? 0, text: m[0].replace(/\s+/g, " ").trim().slice(0, 60) });
+    }
+  }
+  return hits.sort((a, b) => a.at - b.at).map((h) => h.text);
+}
+
+function runViewportSized(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const sized = findViewportSizing(input.sourceCode);
+  if (sized.length === 0) return [];
+  const list = sized.map((t) => "`" + t + "`").join(", ");
+  return [
+    mkIssue(
+      "universal.viewport_sized",
+      `${sized.length} element(s) are sized to the viewport: ${list} — the frame owns the height; a content-sized frame is measured from the content, so a viewport-sized root never shrinks and grows the frame on every re-measure.`,
+      "Remove the viewport height — size to content, never to the viewport. Under fullscreen the frame stretches your root already (centre inside it with `display: flex; flex-direction: column; justify-content: center`); to fill a parent that has a height use `height: 100%` or `flex: 1`.",
+    ),
+  ];
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
+  {
+    id: "universal.icon_name_known",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runIconNameKnown,
+  },
+  {
+    id: "universal.caps_label_invented",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runCapsLabelInvented,
+  },
+  {
+    id: "universal.viewport_sized",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runViewportSized,
+  },
+  {
+    id: "universal.accent_text_ink",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runAccentTextInk,
+  },
+  {
+    id: "universal.scoped_surface_owns_ground",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runScopedSurfaceOwnsGround,
+  },
   {
     id: "universal.prop_coverage",
     axis: "render",