@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/src/evaluation/design-identity.ts

@@ -0,0 +1,96 @@
+// The design tree a judge paints with is an INPUT to the judgement and a
+// part of its identity (ggui#1042, D3): a judge-only re-judge renders every
+// arm with the tree on disk, so the row must say WHICH tree — `srcSha256`
+// over every RENDERING INPUT under the design package's `src`, sorted by
+// relative path — and the local judge path must accept the tree explicitly.
+// A served hello is compared to a judged one only when this hash and the
+// runtime's design agree (`design@judge == design@runtime`, generation-triad.md).
+//
+// Rendering inputs only: tests (`*.test.*`, `__tests__/`), stories
+// (`*.stories.*`) and docs (`*.md`) paint nothing, and a built image ships
+// the design package without them — the first rows on candidate 34 stamped
+// `e2dc89e4…` (123 files) while a checkout of the same git tree computed
+// `2cd62cb7…` (199 files). One identity must read the same on every host
+// that carries the same rendering inputs.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface JudgeDesignIdentity {
+  /** Absolute path of the design `src` tree the judge bundled against. */
+  readonly src: string;
+  /** sha256 over every rendering input under `src` (see {@link isDesignRenderingInput}) — sorted relative path, then contents. */
+  readonly srcSha256: string;
+}
+
+/**
+ * Whether a file under the design `src` tree is something the judge PAINTS
+ * with. Tests, stories and docs are not — and a built image carries the
+ * package without them, so they must not move the identity.
+ */
+export function isDesignRenderingInput(relativePath: string): boolean {
+  const rel = relativePath.split('\\').join('/');
+  if (rel.startsWith('__tests__/') || rel.includes('/__tests__/')) return false;
+  if (/\.test\.[cm]?[jt]sx?$/.test(rel)) return false;
+  if (/\.stories\.[cm]?[jt]sx?$/.test(rel)) return false;
+  if (rel.endsWith('.md')) return false;
+  return true;
+}
+
+/** sha256 over every rendering input under `root` (sorted relative path + contents) — the identity of a design tree as it paints. */
+export function designTreeSha256(root: string): string {
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir).sort()) {
+      const full = resolve(dir, name);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (isDesignRenderingInput(full.slice(root.length + 1))) files.push(full);
+    }
+  };
+  walk(root);
+  const h = createHash('sha256');
+  for (const f of files) {
+    h.update(f.slice(root.length + 1) + '\n');
+    h.update(readFileSync(f));
+    h.update('\n');
+  }
+  return h.digest('hex');
+}
+
+const identityCache = new Map<string, JudgeDesignIdentity | null>();
+
+/**
+ * The identity of the tree at `src`, computed once per process per path (a
+ * judge run paints hundreds of frames from one tree).
+ *
+ * `null` when the tree cannot be READ (ggui#1110): a deployed image ships the
+ * design package as built output with no `src/`, and an identity is a receipt
+ * about a judgement — never a precondition for making one. Before this,
+ * `scandir` threw ENOENT inside the evaluation round wherever the package ships
+ * built output only, the round returned no evaluation at all, and a bar refused
+ * a card that had cleared it. A row without the receipt says so; a round that cannot
+ * stamp one still runs.
+ */
+export function judgeDesignIdentity(src: string): JudgeDesignIdentity | null {
+  const key = resolve(src);
+  const cached = identityCache.get(key);
+  if (cached !== undefined) return cached;
+  let identity: JudgeDesignIdentity | null;
+  try {
+    identity = { src: key, srcSha256: designTreeSha256(key) };
+  } catch (e) {
+    // Unreadable tree: no source directory (a built package), no permission,
+    // a path that is not a directory. The reason is logged ONCE per path —
+    // the judgement proceeds unstamped rather than not at all.
+    const reason = e instanceof Error ? e.message : String(e);
+    console.warn(`[visual-eval] design tree unreadable at ${key} — the judgement carries no design identity (${reason})`);
+    identity = null;
+  }
+  identityCache.set(key, identity);
+  return identity;
+}
+
+/** Test seam: forget cached identities (a test that rewrites a tree between runs). */
+export function resetJudgeDesignIdentityCache(): void {
+  identityCache.clear();
+}

package/src/evaluation/index.ts

@@ -22,6 +22,9 @@ export type {
   EvalOutcome,
   EvalCategory,
   EvalResult,
+  VisualEvalSummary,
+  CanvasJudgeRecord,
+  CanvasVisualSummary,
   EvalCriterion,
   CriterionCoverage,
   CriterionRunStatus,
@@ -39,6 +42,7 @@ export {
   priorityForIssue,
   isBlocked,
   getActionableIssues,
+  criteriaFor,
   getCriteriaByPriority,
   getCriterionById,
   getLLMCriteria,
@@ -84,5 +88,62 @@ export type { RunAxisChecksInput } from './axis-checks/index.js';
 // rubric — scoring generation on criteria the generator was never taught
 // is a constraint-alignment violation, so out-of-loop judges get this
 // seam instead of a rubric extension.
-export { callMultimodalLLM } from './visual-evaluator.js';
-export type { VisualEvalConfig } from './visual-evaluator.js';
+export {
+  callMultimodalLLM,
+  captureScreenshot,
+  resolveLaunchOptions,
+  runVisualEvaluation,
+  resolveDesignPackageDir,
+  runVisualEvaluationDetailed,
+  VISUAL_JUDGE_MAX_OUTPUT_TOKENS,
+  VISUAL_JUDGE_PROMPT_VERSION,
+  VISUAL_JUDGE_PROMPT_DIGEST,
+  VISUAL_EVAL_PROMPT,
+  captureScreenshotDetailed,
+  canvasFitPolicy,
+  canvasOverflowIssue,
+  CONTENT_HEIGHT_EXPRESSION,
+  runVisualEval,
+  summarizeVisualResult,
+} from './visual-evaluator.js';
+export type {
+  VisualEvalConfig,
+  VisualEvalContext,
+  VisualEvalDeps,
+  VisualEvalOutcome,
+  VisualEvaluationResult,
+  VisualEvalDetailed,
+  ScreenshotAttempt,
+  CanvasVisualResult,
+  CanvasFitPolicy,
+  CaptureMode,
+  ScreenshotDeps,
+  ScreenshotLauncher,
+  ScreenshotBrowser,
+  ScreenshotPage,
+  ChromiumProvider,
+} from './visual-evaluator.js';
+
+// Canvas vocabulary — the per-canvas visual evaluation speaks it
+// (`VisualEvalConfig.canvases`, `CanvasVisualResult.canvas`); re-exported
+// here so a caller driving `runVisualEvaluation` from this subpath never
+// has to reach the package root for the class names, viewports or
+// descriptors.
+export {
+  CANVAS_CLASSES,
+  CANVAS_VIEWPORTS,
+  CANVAS_BREAKPOINTS,
+  CANVAS_DESCRIPTORS,
+  canvasForViewportWidth,
+  canvasForRendering,
+  canvasDisplayModeForShell,
+  describeCanvas,
+} from '../design-mode.js';
+export type {
+  CanvasClass,
+  CanvasViewport,
+  CanvasDisplayMode,
+  CanvasDescriptor,
+} from '../design-mode.js';
+export { cssTokensForAppTheme } from './theme-css.js';
+export { designTreeSha256, judgeDesignIdentity, resetJudgeDesignIdentityCache, type JudgeDesignIdentity } from './design-identity.js';

package/src/evaluation/llm-evaluator.ts

@@ -14,6 +14,8 @@
 // Caching: Anthropic ephemeral cache, OpenAI auto-cache, Google explicit cache.
 // Same system prompt across all 7 calls → first call caches, 6 remaining hit cache.
 
+import { buildStylingProfileJudgeBlock } from '../boilerplate/styling-profile.js';
+import type { GenerationProfileInput } from '../boilerplate/styling-profile.js';
 import type {
   EvalIssue,
   EvalResult,
@@ -26,6 +28,7 @@ import { createAgent } from '../harness/llm-router';
 import type { AgentConfig, LLMToolDef, LLMAgent } from '../harness/llm-router';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { getCriterionById } from './types-public.js';
+import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
 
 // =============================================================================
 // Helpers
@@ -66,6 +69,16 @@ export interface LLMEvalContext {
   originalPrompt: string;
   designContext?: string;
   contract?: unknown;
+  /**
+   * Which triad produced the source. Selects the criteria text
+   * (`criteriaFor`) and the mother prompt's styling rules: in `free`
+   * mode the `tokens` criterion narrows to color and the `visual`
+   * criterion + "Design System Rules" block become arm-neutral. Absent
+   * means `constrained` (byte-identical to the pre-`designMode` prompt).
+   */
+  designMode?: DesignMode;
+  /** The app's generation profile (#991) — the judge reads the same text the coder was given. */
+  profile?: GenerationProfileInput;
 }
 
 export interface LLMEvalConfig {
@@ -108,14 +121,66 @@ export interface EvalContext {
   originalPrompt: string;
   contract?: unknown;
   designSystemSummary?: string;
+  /** See `LLMEvalContext.designMode`. */
+  designMode?: DesignMode;
+  /** See `LLMEvalContext.profile`. */
+  profile?: GenerationProfileInput;
 }
 
+/**
+ * Arm-neutral styling rules for `designMode: 'free'` — replaces the
+ * constrained "Design System Rules" block. Mirrors the free prompt: color
+ * on the closed token manifest, everything else may be literal, raw HTML
+ * + CSS is a first-class choice.
+ */
+const FREE_STYLING_RULES = `## Styling Rules (important for evaluation)
+- Color: every color must be a bare \`var(--ggui-color-*)\` token — a hardcoded #hex, rgb()/hsl() or CSS named color is a fail, and so is a literal fallback inside \`var(--ggui-*, …)\`.
+- Accent text (eyebrow, tagline, link, label) painted with a bare \`var(--ggui-color-primary-300…600)\` is a readability fail — the accent ink is \`var(--ggui-color-link)\`; a tint as text on a primary fill and a deep stop (700–900) on a light tint are fine
+- Spacing, typography, radius, shadow geometry and layout values MAY be literals (\`padding: '20px'\`, \`fontSize: 18\`, \`borderRadius: 12\`) — NEVER flag them.
+- Raw HTML elements with inline styles or \`<style>\` blocks are a first-class choice — never flag "not using the design system" or reward using it.
+- When \`@ggui-ai/design\` primitives ARE used, their enum/scale props (\`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`tone="muted"\`, \`surface="accent"\`) are valid.
+- One \`export default function Component\` — helper components as named functions above it are fine`;
+
+const CONSTRAINED_STYLING_RULES = `## Design System Rules (important for evaluation)
+- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** — each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
+- All colors must use CSS variables: \`color="var(--ggui-color-onContainer)"\` — hardcoded #hex or rgb() is a fail
+- Accent text (eyebrow, tagline, link, label) painted with a bare \`primary-300…600\` stop is a readability fail — the accent ink is \`var(--ggui-color-link)\` (or \`tone="emphasized"\`); tints as text on a primary fill and deep stops on a light tint are fine
+- Component props that take enum/scale values — \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` — are all design system tokens and are always valid
+- One \`export default function Component\` — helper components as named functions above it are fine`;
+
+const CONSTRAINED_VISUAL_REFERENCE = `**visual**: Design system consistency.
+- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
+- Consistent use of spacing tokens
+- Proper use of component variants (primary, outline, ghost)
+- Shadow, border-radius from design system tokens`;
+
+const FREE_VISUAL_REFERENCE = `**visual**: Visual composition.
+- Clear hierarchy (one focal point, headings distinct from body), consistent spacing rhythm
+- Coherent palette drawn from the theme color tokens
+- Fit to the canvas: fluid width, nothing cramped or stretched
+- No reward or penalty for using (or not using) the design-system primitives`;
+
+const CONSTRAINED_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
+  (no role, no keyboard) — or any hand-rolled interactive element.`;
+
+const FREE_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target with no \`role="button"\`,
+  \`tabIndex\` and keyboard handler — a real \`<button>\` / \`<a href>\` is the
+  correct raw element and is never a gap.`;
+
 export function buildMotherPrompt(ctx: EvalContext): string {
   const parts: string[] = [];
-
-  parts.push(`You are evaluating a generated React component built with the ggui design system.
+  const designMode = ctx.designMode ?? DEFAULT_DESIGN_MODE;
+  const free = designMode === 'free';
+
+  parts.push(
+    free
+      ? `You are evaluating a generated React component. It was composed freely — raw HTML elements, inline styles and <style> blocks are allowed and the ggui design package is optional — against a data contract and a theme-token color rule.
+The code has already passed automated checks (compilation, security, imports, color tokens).
+Your job is to evaluate ONE specific quality criterion per call.`
+      : `You are evaluating a generated React component built with the ggui design system.
 The code has already passed automated checks (compilation, security, imports, design tokens).
-Your job is to evaluate ONE specific quality criterion per call.`);
+Your job is to evaluate ONE specific quality criterion per call.`,
+  );
 
   parts.push(`## About This Prompt
 This system prompt has 2 sections:
@@ -173,11 +238,7 @@ ${JSON.stringify(ctx.contract).slice(0, 6000)}
 ${ctx.designSystemSummary}`);
   }
 
-  parts.push(`## Design System Rules (important for evaluation)
-- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** — each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
-- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` — hardcoded #hex or rgb() is a fail
-- Component props that take enum/scale values — \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` — are all design system tokens and are always valid
-- One \`export default function Component\` — helper components as named functions above it are fine
+  parts.push(`${free ? FREE_STYLING_RULES : CONSTRAINED_STYLING_RULES}
 
 ## Evaluation Criteria Reference
 
@@ -221,11 +282,7 @@ ${ctx.designSystemSummary}`);
 - Error boundaries or error messages for failure cases
 - Empty states ("No items found") when data arrays could be empty
 
-**visual**: Design system consistency.
-- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
-- Consistent use of spacing tokens
-- Proper use of component variants (primary, outline, ghost)
-- Shadow, border-radius from design system tokens
+${free ? FREE_VISUAL_REFERENCE : CONSTRAINED_VISUAL_REFERENCE}
 
 ## Primitive Accessibility (built-in — do NOT flag as missing)
 
@@ -259,8 +316,7 @@ role, aria-*, label, or keyboard support — it is already there:
   to text is CORRECTLY silent — never ask for \`aria-hidden\`, it is there.
 
 REAL accessibility gaps worth flagging:
-- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
-  (no role, no keyboard) — or any hand-rolled interactive element.
+${free ? FREE_RAW_CLICK_TARGET_GAP : CONSTRAINED_RAW_CLICK_TARGET_GAP}
 - A hand-rolled control whose state (checked / selected / expanded /
   pressed) is conveyed ONLY by styling — e.g. a styled-div "checkbox"
   with a check icon + strikethrough label but no \`role="checkbox"\` /
@@ -275,6 +331,8 @@ REAL accessibility gaps worth flagging:
 - Inverted or skipped heading levels (an \`<Heading level={3}>\` rendered
   before the page's \`<Heading level={1}>\`).`);
 
+  const profileBlock = buildStylingProfileJudgeBlock(ctx.profile);
+  if (profileBlock.length > 0) parts.push(profileBlock);
   return parts.join('\n\n');
 }
 
@@ -329,11 +387,15 @@ function makeTier2Tool(criterion: string): LLMToolDef {
 // Per-criterion user prompts
 // =============================================================================
 
-function getCriterionPrompt(criterion: string, numberedSource: string): string {
+function getCriterionPrompt(
+  criterion: string,
+  numberedSource: string,
+  designMode: DesignMode,
+): string {
   const sourceBlock = `\nSource code (with line numbers):\n\`\`\`tsx\n${numberedSource}\n\`\`\``;
 
   // Use criteria.ts as single source of truth when available
-  const criterionDef = getCriterionById(criterion);
+  const criterionDef = getCriterionById(criterion, designMode);
   if (criterionDef && criterionDef.tier > 0) {
     return `${criterionDef.evalInstruction}
 ${sourceBlock}
@@ -489,7 +551,7 @@ Return your evaluation using the evaluate_visual tool.
 
 Example outputs:
 - Clean: {"result": "pass"}
-- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-surfaceVariant)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
+- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-sunken)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
 - Severe: {"result": "fail", "issues": ["Component uses entirely custom styling with no design system tokens"]}
 
 Use 'fail' only for pervasive design system violations. Use 'warn' for isolated cases.`;
@@ -553,10 +615,11 @@ async function evalCriterion(
   numberedSource: string,
   agent: LLMAgent,
   model: string,
+  designMode: DesignMode,
 ): Promise<CriterionResult> {
   const start = Date.now();
   const tool = tier === 1 ? makeTier1Tool(criterion) : makeTier2Tool(criterion);
-  const userPrompt = getCriterionPrompt(criterion, numberedSource);
+  const userPrompt = getCriterionPrompt(criterion, numberedSource, designMode);
 
   try {
     const response = await agent.callTools(
@@ -679,6 +742,8 @@ export async function preWarmEval(
     originalPrompt: context.originalPrompt,
     contract: context.contract,
     designSystemSummary: context.designContext,
+    designMode: context.designMode,
+    profile: context.profile,
   });
 
   return { motherPrompt, dynamicCriteria: [] };
@@ -777,10 +842,13 @@ export async function runLLMEvaluation(
       : (providerName as 'openai' | 'google');
 
   // Use pre-warmed context if available, otherwise build fresh
+  const designMode = context.designMode ?? DEFAULT_DESIGN_MODE;
   const motherPrompt = preWarmedContext?.motherPrompt ?? buildMotherPrompt({
     originalPrompt: context.originalPrompt,
     contract: context.contract,
     designSystemSummary: context.designContext,
+    designMode,
+    profile: context.profile,
   });
 
   // Add line numbers to source
@@ -810,8 +878,8 @@ export async function runLLMEvaluation(
 
   // Run ALL criteria in parallel: 7 static (2 tier 1 + 5 tier 2)
   const results = await Promise.all([
-    ...TIER_1_CRITERIA.map(c => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model)),
-    ...TIER_2_CRITERIA.map(c => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model)),
+    ...TIER_1_CRITERIA.map(c => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model, designMode)),
+    ...TIER_2_CRITERIA.map(c => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model, designMode)),
   ]);
 
   // Merge results

package/src/evaluation/theme-css.ts

@@ -0,0 +1,14 @@
+import type { AppTheme } from '@ggui-ai/protocol';
+import { composeThemeCss, getCssTokens } from '@ggui-ai/design/rendering';
+
+/**
+ * The stylesheet a visual judge renders under for an app: the app's theme
+ * composed the way the runtime composes it (`composeThemeCss`, layer `page`
+ * — one composition, never a second), so a judged canvas paints the tokens a
+ * visitor's page paints. Absent theme ⇒ the design's default tokens,
+ * byte-for-byte what the judge used before.
+ */
+export function cssTokensForAppTheme(theme: AppTheme | undefined, mode: 'light' | 'dark' = 'light'): string {
+  if (theme === undefined) return getCssTokens(mode);
+  return composeThemeCss({ layer: 'page', mode: theme.mode ?? mode, appTheme: theme });
+}

package/src/evaluation/types-public.ts

@@ -20,6 +20,8 @@
 
 export type Priority = "P0" | "P1" | "P2";
 
+import type { CanvasClass, DesignMode } from "../design-mode.js";
+
 // ─── Issue shape ───────────────────────────────────────────────────────────
 
 export type EvalTier = 0 | 1 | 2;
@@ -174,6 +176,68 @@ export interface EvalResult {
    * probe runner; absent on eval paths that never invoke the probe.
    */
   runtimeProbe?: RuntimeProbeMeta;
+  /**
+   * Per-canvas visual verdicts. Stamped by the harness ONLY when the
+   * visual leg ran with `visualEvaluation.canvases` set (arm-neutral —
+   * the same judge in every design mode); absent on the single-shot
+   * visual path and whenever the visual leg did not run. PNGs stay on
+   * `runVisualEvaluation`'s own result (`VisualEvaluationResult.canvases[*].screenshotPng`),
+   * never here — this object is serialized into reports.
+   */
+  visual?: VisualEvalSummary;
+}
+
+/** One canvas's visual verdict, PNG-free — see `EvalResult.visual`. */
+/**
+ * How one canvas's `score` was reached (ggui#1072): `k` vision calls on the
+ * SAME captured frame, aggregated by `rule`. Always present — `k: 1` ⇒
+ * `samples: [score]`, `sigma: 0`, `notes: [critique]` — so one shape serves
+ * a single judgement and a median of many. `samples`/`notes` carry only the
+ * calls the judge could parse (in call order); `k` stays the requested count,
+ * so a short `samples` is visible on the row rather than filled in.
+ */
+export interface CanvasJudgeRecord {
+  readonly k: number;
+  readonly rule: 'median';
+  readonly samples: number[];
+  /** Population σ of `samples` (0 when one sample). */
+  readonly sigma: number;
+  /** The judge's per-canvas critique per sample — the words beside a swing. */
+  readonly notes: string[];
+}
+
+export interface CanvasVisualSummary {
+  canvas: CanvasClass;
+  viewport: { width: number; height: number };
+  /** The judge's weighted score at this canvas (0-100). */
+  score: number;
+  /** `score >= passThreshold`, and on the inline card: no overflow (ggui#1027). */
+  passed: boolean;
+  /** The document's scroll height at this canvas, CSS px; `null` when unmeasurable (ggui#1027). */
+  contentHeight: number | null;
+  /** `contentHeight > viewport.height` — measured on every canvas, judged per `canvasFitPolicy`. */
+  overflow: boolean;
+  /** How `score` was reached — always present (ggui#1072). */
+  judge: CanvasJudgeRecord;
+  /**
+   * How the judge composed the mount (ggui#1100): `'fill'` on every
+   * fullscreen canvas — the served runtime's fit, the root stretched to
+   * the frame; absent on the inline card, which keeps its natural height.
+   */
+  fit?: 'fill';
+}
+
+/** The visual leg's per-canvas summary — see `EvalResult.visual`. */
+export interface VisualEvalSummary {
+  /** Mean of the canvas scores (rounded). */
+  score: number;
+  /** Every canvas passed. */
+  passed: boolean;
+  canvases: CanvasVisualSummary[];
+  /** The design tree the judge painted with (ggui#1042): `src` + `srcSha256` — `design@judge`. */
+  design?: { readonly src: string; readonly srcSha256: string };
+  /** The mode the judge's tokens were composed in, when the caller said (ggui#1076). */
+  themeMode?: 'light' | 'dark';
 }
 
 // ─── Quality mode ──────────────────────────────────────────────────────────
@@ -209,6 +273,13 @@ export interface AxisCheckInput {
   originalPrompt: string;
   /** Full classification — checks may read sibling axes. */
   classification: Classification;
+  /**
+   * Which triad produced the source. Checks that assert a design-package
+   * component (e.g. `layout.multi_step.stepper_adopted`) read it and
+   * stand down in `free` mode, where the primitive is optional. Absent
+   * means `constrained`.
+   */
+  designMode?: DesignMode;
 }
 
 /**
@@ -506,26 +577,84 @@ Only list ACTUAL violations. Use 'fail' only for pervasive violations.`,
   },
 ] as const;
 
+/**
+ * `designMode: 'free'` overrides — ONLY the two criteria whose text
+ * encodes the design vocabulary. `tokens` narrows to COLOR (the free arm
+ * relaxes spacing / typography / radius / shadow to literals but keeps
+ * brand-bearing color on the closed `--ggui-color-*` manifest, no
+ * fallbacks); `visual` becomes arm-neutral (composition, hierarchy,
+ * consistency, fit to canvas — no reward or penalty for design-system
+ * usage). Every other criterion is shared verbatim between the modes.
+ * Constraint alignment: what the free prompt says, the free evaluator
+ * checks — and nothing more.
+ */
+const FREE_DESIGN_CRITERIA_OVERRIDES: readonly EvalCriterion[] = [
+  {
+    id: "tokens",
+    name: "Color tokens",
+    priority: "P1",
+    tier: 0,
+    failOutcome: "warn",
+    codingGuidance:
+      "Every color is a bare var(--ggui-color-*) from the token manifest — no hex, rgb()/hsl(), CSS named colors or literal fallbacks, in style props and <style> blocks alike. Spacing, typography, radius and shadow geometry may be literals.",
+    evalInstruction:
+      "Flag hardcoded hex colors, rgba/hsl functions, CSS named colors, and literal fallbacks inside var(--ggui-*) references. Do NOT flag literal spacing, font sizes, radii or pixel values — they are allowed in this mode.",
+  },
+  {
+    id: "visual",
+    name: "Visual composition",
+    priority: "P2",
+    tier: 2,
+    failOutcome: "warn",
+    codingGuidance:
+      "Compose deliberately: one clear focal point, consistent spacing rhythm, a coherent theme-token palette, a fit to the rendering canvas.",
+    evalInstruction: `Evaluate VISUAL COMPOSITION: Is the component composed deliberately for its canvas?
+
+Judge: visual hierarchy (one clear focal point, headings distinct from body text), consistent spacing rhythm and alignment, a coherent palette drawn from the theme tokens, fit to the canvas (fluid width, no fixed widths, nothing cramped or stretched).
+Do NOT reward or penalise the use of design-system primitives — raw HTML with inline CSS is a first-class choice here. Literal spacing / typography / radius values are fine.
+
+Only list ACTUAL composition problems. Use 'fail' only for a fundamentally incoherent composition.`,
+  },
+];
+
+/**
+ * The criteria registry for a design mode. `constrained` IS `CRITERIA`
+ * (same array, byte-identical summary); `free` swaps in the two
+ * overrides above by id, preserving order.
+ */
+export function criteriaFor(designMode: DesignMode = "constrained"): readonly EvalCriterion[] {
+  if (designMode === "constrained") return CRITERIA;
+  return CRITERIA.map(
+    (c) => FREE_DESIGN_CRITERIA_OVERRIDES.find((o) => o.id === c.id) ?? c,
+  );
+}
+
 /** Get all criteria for a specific priority level */
-export function getCriteriaByPriority(priority: Priority): EvalCriterion[] {
-  return CRITERIA.filter((c) => c.priority === priority);
+export function getCriteriaByPriority(
+  priority: Priority,
+  designMode: DesignMode = "constrained",
+): EvalCriterion[] {
+  return criteriaFor(designMode).filter((c) => c.priority === priority);
 }
 
 /** Get a specific criterion by ID */
-export function getCriterionById(id: string): EvalCriterion | undefined {
-  return CRITERIA.find((c) => c.id === id);
+export function getCriterionById(
+  id: string,
+  designMode: DesignMode = "constrained",
+): EvalCriterion | undefined {
+  return criteriaFor(designMode).find((c) => c.id === id);
 }
 
 /** Get all LLM-evaluated criteria (tier 1 + 2) */
-export function getLLMCriteria(): EvalCriterion[] {
-  return CRITERIA.filter((c) => c.tier > 0);
+export function getLLMCriteria(designMode: DesignMode = "constrained"): EvalCriterion[] {
+  return criteriaFor(designMode).filter((c) => c.tier > 0);
 }
 
 /**
  * Build the coding agent's criteria summary from the single source of truth.
  * Grouped by priority for the P0→P1→P2 hierarchy.
  */
-export function buildCodingCriteriaSummary(): string {
+export function buildCodingCriteriaSummary(designMode: DesignMode = "constrained"): string {
   const lines: string[] = ["## Priority (P0 first, then P1, then P2)", ""];
 
   for (const priority of ["P0", "P1", "P2"] as Priority[]) {
@@ -535,7 +664,7 @@ export function buildCodingCriteriaSummary(): string {
         : priority === "P1"
           ? "Should (safety)"
           : "Nice (quality)";
-    const criteria = getCriteriaByPriority(priority);
+    const criteria = getCriteriaByPriority(priority, designMode);
     lines.push(`**${priority} — ${label}:**`);
     for (const c of criteria) {
       lines.push(`- ${c.codingGuidance}`);