@ggui-ai/ui-gen 0.15.0 → 0.17.0

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",

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

@@ -6,37 +6,106 @@ import type { DataContract } from "@ggui-ai/protocol";
 import type { Classification } from "../../classifier/index.js";
 import type { EvalIssue } from "../types-public.js";
 import { REGISTRY } from "./registry.js";
-import { matches, type AxisCheckInput } from "./types.js";
+import { matches, type AxisCheck, type AxisCheckInput } from "./types.js";
+import { axisCheckTraceEnabled } from "./helpers.js";
+import { createHash } from "node:crypto";
+import type { DesignMode } from "../../design-mode.js";
 
 export interface RunAxisChecksInput {
   sourceCode: string;
   compiledCode: string | null;
   contract?: DataContract;
   originalPrompt: string;
+  /** Which triad produced the source — see `AxisCheckInput.designMode`. */
+  designMode?: DesignMode;
 }
 
 export function runAxisChecks(
   classification: Classification,
   input: RunAxisChecksInput,
 ): EvalIssue[] {
-  if (input.compiledCode === null) return [];
-
-  const axisInput: AxisCheckInput = {
+  const facts: AxisTraceFacts = {
     sourceCode: input.sourceCode,
-    compiledCode: input.compiledCode,
     ...(input.contract !== undefined ? { contract: input.contract } : {}),
     originalPrompt: input.originalPrompt,
     classification,
+    ...(input.designMode !== undefined ? { designMode: input.designMode } : {}),
   };
+  if (input.compiledCode === null) {
+    traceAxisChecksSkipped(facts, "compiledCode null — no check ran");
+    return [];
+  }
+  const axisInput: AxisCheckInput = { ...facts, compiledCode: input.compiledCode };
+  return runGatedAxisChecks(
+    REGISTRY.filter((check) => matches(classification.vector, check)),
+    axisInput,
+  ).issues;
+}
+
+export interface AxisRunResult {
+  readonly issues: EvalIssue[];
+  /** Check ids run, in registry order, each once. */
+  readonly firedIds: string[];
+}
 
+/**
+ * Run a PRE-GATED list of checks once each — the one runner the served
+ * loop (`run-check.ts`, over the harness's pre-filtered `axisChecks`) and
+ * `runAxisChecks` (gate + run) share, so the ggui#1046 trace line prints on
+ * both paths.
+ */
+export function runGatedAxisChecks(checks: readonly AxisCheck[], input: AxisCheckInput): AxisRunResult {
   const issues: EvalIssue[] = [];
-  const firedIds = new Set<string>();
-  for (const check of REGISTRY) {
-    if (!matches(classification.vector, check)) continue;
-    // Dedup by id — a check may be registered under multiple gates.
-    if (firedIds.has(check.id)) continue;
-    firedIds.add(check.id);
-    issues.push(...check.run(axisInput));
+  const firedIds: string[] = [];
+  const seen = new Set<string>();
+  for (const check of checks) {
+    if (seen.has(check.id)) continue;
+    seen.add(check.id);
+    firedIds.push(check.id);
+    issues.push(...check.run(input));
+  }
+  if (axisCheckTraceEnabled()) {
+    const line: AxisCheckTrace = {
+      ...traceFacts(input),
+      matched: [...firedIds],
+      issues: issues.map((i) => ({ id: i.subcategory ?? i.category, result: i.result })),
+    };
+    console.log(JSON.stringify({ axisCheckTrace: line }));
   }
-  return issues;
+  return { issues, firedIds };
+}
+
+/** The dispatcher's line for a round where no check could run (a null compile), flag-gated like the rest. */
+export function traceAxisChecksSkipped(facts: AxisTraceFacts, note: string): void {
+  if (!axisCheckTraceEnabled()) return;
+  const line: AxisCheckTrace = { ...traceFacts(facts), matched: [], issues: [], note };
+  console.log(JSON.stringify({ axisCheckTrace: line }));
+}
+
+/** The input facts a round's verdict is built from — `AxisCheckInput` minus the compile. */
+export type AxisTraceFacts = Omit<AxisCheckInput, "compiledCode">;
+
+/** One trace line per round (ggui#1046): the input facts a verdict was built from, the gates that matched, the issues that came out. */
+export interface AxisCheckTrace {
+  readonly sourceSha256: string;
+  readonly originalPrompt: string;
+  readonly designMode: string;
+  readonly classification: Classification["vector"];
+  readonly propsSpecKeys: readonly string[];
+  readonly propsSpecPropertyKeys: readonly string[];
+  readonly matched: readonly string[];
+  readonly issues: ReadonlyArray<{ readonly id: string; readonly result: EvalIssue["result"] }>;
+  readonly note?: string;
+}
+
+function traceFacts(input: AxisTraceFacts): Omit<AxisCheckTrace, "matched" | "issues"> {
+  const propsSpec = input.contract?.propsSpec;
+  return {
+    sourceSha256: createHash("sha256").update(input.sourceCode, "utf8").digest("hex"),
+    originalPrompt: input.originalPrompt,
+    designMode: input.designMode ?? "constrained",
+    classification: input.classification.vector,
+    propsSpecKeys: Object.keys(propsSpec ?? {}),
+    propsSpecPropertyKeys: Object.keys(propsSpec?.properties ?? {}),
+  };
 }

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

@@ -145,6 +145,11 @@ const stepperAdopted: AxisCheck = {
   values: ["multi-step"],
   run(input: AxisCheckInput): EvalIssue[] {
     if (input.compiledCode === null) return [];
+    // `free` design mode: the Stepper composite is optional (the prompt
+    // names it as a default, not a requirement), so the adoption
+    // mandate stands down. `layout.multi_step.state_present` — the
+    // behavioural rule — still fires in both modes.
+    if (input.designMode === "free") return [];
     if (/<Stepper[\s/>]/.test(input.sourceCode)) return [];
     return [
       mkIssue(

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

@@ -300,3 +300,15 @@ export function mkIssue(
 export function cap(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
+
+/**
+ * Trace flag (ggui#1046): `GGUI_AXIS_CHECK_TRACE=1` makes the dispatcher and the checks
+ * that opt in print one JSON line per evaluation round with the facts their verdict was
+ * built from — what a reader of a served cell cannot recover from the round's result
+ * alone (the source the checks saw, the prompt, the design mode, the classification,
+ * the contract's prop keys, which gates matched, which issues came out). Off by default;
+ * a diagnostic channel, never part of the result.
+ */
+export function axisCheckTraceEnabled(): boolean {
+  return process.env["GGUI_AXIS_CHECK_TRACE"] === "1";
+}

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

@@ -11,6 +11,7 @@ import { REALTIME_CHECKS } from "./checks/realtime.js";
 import { WRITES_CHECKS } from "./checks/writes.js";
 import { STATE_PAYLOAD_CHECKS } from "./checks/state-payload.js";
 import { TOOLING_CHECKS } from "./checks/tooling.js";
+import { GRID_CHECKS } from "./checks/grid.js";
 import { EXTRA_CHECKS } from "./extras.js";
 
 export const REGISTRY: readonly AxisCheck[] = [
@@ -21,5 +22,6 @@ export const REGISTRY: readonly AxisCheck[] = [
   ...WRITES_CHECKS,
   ...STATE_PAYLOAD_CHECKS,
   ...TOOLING_CHECKS,
+  ...GRID_CHECKS,
   ...EXTRA_CHECKS,
 ];

package/src/evaluation/cost-tracker.ts

@@ -15,9 +15,8 @@ import { MODEL_REGISTRY, type ModelId } from '@ggui-ai/protocol';
  * This table used to hand-maintain its own per-1K prices, and drifted:
  * on 2026-07-31 four of its six rows were wrong (Haiku 4.5 20% low,
  * gemini-3-flash-preview 5-7x low, gpt-5.4-mini ~3x low, Luna 5x high
- * after OpenAI's cut). Deriving from the registry — which the pod's
- * pricing test now pins against the vendored LiteLLM snapshot — means
- * one place to update and one place that can be wrong.
+ * after OpenAI's cut). Deriving from the registry — whose Anthropic rows
+ * `@ggui-ai/protocol`'s own tests pin — means one place to update and one place that can be wrong.
  *
  * Resolution order mirrors the benchmark harness's
  * `resolveJudgeCostModelId`: exact key, unique `/<model>` suffix, then