@ggui-ai/ui-gen 0.15.0 → 0.16.0

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,34 @@ 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`. */
+export interface CanvasVisualSummary {
+  canvas: CanvasClass;
+  viewport: { width: number; height: number };
+  /** The judge's weighted score at this canvas (0-100). */
+  score: number;
+  /** `score >= passThreshold`. */
+  passed: boolean;
+}
+
+/** 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[];
 }
 
 // ─── Quality mode ──────────────────────────────────────────────────────────
@@ -209,6 +239,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 +543,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 +630,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}`);

package/src/evaluation/visual-evaluator.ts

@@ -19,7 +19,9 @@ import { writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { createVisionAgent, type AgentConfig } from '../harness/llm-router';
 import type { EvaluationResult, EvaluationIssue, DimensionScores } from './types';
-import type { EvalIssue } from './types-public.js';
+import type { CanvasVisualSummary, EvalIssue, VisualEvalSummary } from './types-public.js';
+import type { LaunchOptions } from 'puppeteer-core';
+import { CANVAS_VIEWPORTS, type CanvasClass, type CanvasViewport } from '../design-mode.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -36,6 +38,18 @@ export interface VisualEvalConfig {
   sampleProps?: Record<string, unknown>;
   /** Viewport dimensions for screenshot */
   viewport?: { width: number; height: number };
+  /**
+   * Per-canvas judging — ARM-NEUTRAL (the same judge, prompt and
+   * threshold in every design mode). When set, the SAME rendered HTML
+   * shell is screenshotted once per class at `CANVAS_VIEWPORTS[class]`
+   * and judged once per class; the result carries one entry per class
+   * in `canvases`, and the single-shot fields aggregate: `finalScore` =
+   * mean of the canvas scores (rounded), `passed` = every canvas passed,
+   * `dimensions` = per-dimension means, `issues` = every canvas's issues
+   * (description prefixed `[<canvas>]`). Unset (or empty) = today's
+   * single screenshot at `viewport`; no `canvases` field on the result.
+   */
+  canvases?: readonly CanvasClass[];
   /**
    * Optional provider-routing override — see
    * `AgentConfig.routeOverride`. Threaded onto the agent this
@@ -52,6 +66,34 @@ export interface VisualEvalConfig {
   onRetry?: AgentConfig['onRetry'];
 }
 
+/** One canvas's verdict — screenshot + judge score at that class's viewport. */
+export interface CanvasVisualResult {
+  canvas: CanvasClass;
+  viewport: CanvasViewport;
+  /** The judge's weighted score for this canvas (0-100). */
+  score: number;
+  /** `score >= passThreshold`. */
+  passed: boolean;
+  /** The PNG the judge saw — kept for artefact persistence + the human look. */
+  screenshotPng: Buffer;
+}
+
+/**
+ * `runVisualEvaluation`'s result. Identical to `EvaluationResult` when
+ * `config.canvases` is unset; with canvases set, `canvases` holds the
+ * per-class verdicts and the base fields aggregate them (see
+ * `VisualEvalConfig.canvases`).
+ */
+export interface VisualEvaluationResult extends EvaluationResult {
+  canvases?: CanvasVisualResult[];
+}
+
+/** Injection points for `runVisualEvaluation` — screenshot deps plus the judge call (tests). */
+export interface VisualEvalDeps extends ScreenshotDeps {
+  /** The multimodal judge call (default: `callMultimodalLLM`). */
+  judge?: typeof callMultimodalLLM;
+}
+
 export interface VisualEvalContext {
   /** Compiled JavaScript code (ESM with imports) */
   compiledCode: string;
@@ -81,6 +123,18 @@ export interface VisualEvalContext {
  * `<pkg>/dist/evaluation`) is `oss/packages/`; the design package is
  * its direct child.
  */
+/**
+ * The on-disk root of `@ggui-ai/ui-gen` itself. The bundle's entry lives
+ * in a temp dir, so bare imports in the GENERATED component (`@ggui-ai/wire`
+ * and every other allowlisted package) resolve nowhere from there — they
+ * resolve from this package's `node_modules` instead (`nodePaths`), the
+ * same place the harness's own imports come from.
+ */
+export function resolveUiGenPackageDir(): string {
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(selfDir, '..', '..');
+}
+
 export function resolveDesignPackageDir(): string {
   const selfDir = dirname(fileURLToPath(import.meta.url));
   return resolve(selfDir, '..', '..', '..', 'design');
@@ -102,15 +156,43 @@ async function bundleForRendering(
   writeFileSync(componentFile, compiledCode);
 
   // Entry file imports the component and renders it
+  // The generated component is rendered the way a host renders it: inside
+  // `GguiWireProvider` with a stub config (dispatch/subscribe are no-ops —
+  // the judge sees the first paint, not the wire round-trip). Without the
+  // provider every `useAction` / `useStream` bearer threw
+  // "useWireContext must be used within a WireProvider", React unmounted
+  // the root and the judge scored a blank page. An error boundary turns a
+  // render throw into visible "Render error" text (which the rubric
+  // scores 0) instead of the same blank.
   const entryCode = `
 import React from 'react';
 import { createRoot } from 'react-dom/client';
+import { GguiWireProvider } from '@ggui-ai/wire';
 import Component from './component.tsx';
 
 const props = ${JSON.stringify(sampleProps)};
+const wireConfig = {
+  app: { appId: 'visual-eval', appName: 'Visual evaluation' },
+  render: { sessionId: 'visual-eval', isConnected: true },
+  auth: { isAuthenticated: false },
+  dispatch: () => {},
+  subscribe: () => () => {},
+};
+class RenderErrorBoundary extends React.Component<{ children: React.ReactNode }, { message: string | null }> {
+  state = { message: null as string | null };
+  static getDerivedStateFromError(err: unknown) { return { message: err instanceof Error ? err.message : String(err) }; }
+  render() {
+    return this.state.message === null
+      ? this.props.children
+      : React.createElement('div', { className: 'error' }, 'Render error: ' + this.state.message);
+  }
+}
 const root = createRoot(document.getElementById('root')!);
 try {
-  root.render(React.createElement(Component, props));
+  root.render(
+    React.createElement(GguiWireProvider, { config: wireConfig },
+      React.createElement(RenderErrorBoundary, null, React.createElement(Component, props))),
+  );
 } catch (err) {
   root.render(React.createElement('div', { className: 'error' }, 'Render error: ' + (err as Error).message));
 }
@@ -138,6 +220,10 @@ try {
         '@ggui-ai/design/compositions': resolve(designPkgDir, 'src', 'compositions', 'index.ts'),
         '@ggui-ai/design/interact': resolve(designPkgDir, 'src', 'interact', 'index.ts'),
       },
+      // Bare imports in the generated component resolve against ui-gen's
+      // own node_modules — the temp entry dir has none. Without this every
+      // wire-bearing component (`@ggui-ai/wire`) failed to bundle.
+      nodePaths: [resolve(resolveUiGenPackageDir(), 'node_modules')],
       logLevel: 'silent',
     });
 
@@ -199,27 +285,104 @@ ${bundledCode}
 // Screenshot capture (optional puppeteer dependency)
 // ---------------------------------------------------------------------------
 
+/** The page surface the capture uses — a structural subset of puppeteer's `Page`. */
+export interface ScreenshotPage {
+  setContent(html: string, options: { waitUntil: 'load'; timeout: number }): Promise<void>;
+  waitForNetworkIdle(options: { idleTime: number; timeout: number }): Promise<void>;
+  waitForSelector(selector: string, options: { timeout: number }): Promise<unknown>;
+  screenshot(options: { type: 'png'; fullPage: boolean }): Promise<Uint8Array>;
+}
+
+/** The browser surface the capture uses — a structural subset of puppeteer's `Browser`. */
+export interface ScreenshotBrowser {
+  newPage(): Promise<ScreenshotPage>;
+  close(): Promise<void>;
+}
+
+export type ScreenshotLauncher = (options: LaunchOptions) => Promise<ScreenshotBrowser>;
+
+/** The two members of `@sparticuz/chromium` the fallback launch path reads. */
+export interface ChromiumProvider {
+  readonly args: string[];
+  executablePath(): Promise<string>;
+}
+
 /**
- * Take a screenshot of the rendered component.
- * Returns base64-encoded PNG or null if puppeteer is not available.
+ * Injection points for the capture — every default is the production
+ * path; tests replace them to pin branch selection without launching a
+ * browser.
  */
-async function captureScreenshot(
-  html: string,
-  viewport: { width: number; height: number } = { width: 1280, height: 800 },
-): Promise<Buffer | null> {
-  try {
-    // puppeteer-core + @sparticuz/chromium — works on both local dev & Lambda
-    const puppeteer = await import('puppeteer-core');
-    const chromium = await import('@sparticuz/chromium');
+export interface ScreenshotDeps {
+  /** Launches the browser (default: `puppeteer-core`'s `launch`). */
+  launch?: ScreenshotLauncher;
+  /** Environment the executable-path override is read from (default: `process.env`). */
+  env?: NodeJS.ProcessEnv;
+  /** Loads `@sparticuz/chromium` (default: dynamic import) — only consulted when no override is set. */
+  loadChromium?: () => Promise<ChromiumProvider>;
+  /** Post-load settle time before the screenshot, ms (default 1000). */
+  settleMs?: number;
+}
+
+/**
+ * Chromium flags the `PUPPETEER_EXECUTABLE_PATH` launch adds: a system
+ * Chromium inside a container has no user namespace for the sandbox and
+ * `/dev/shm` is too small for a render surface.
+ */
+export const EXECUTABLE_PATH_LAUNCH_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
 
-    const launchOptions = {
-      args: chromium.default.args,
+const DEFAULT_SCREENSHOT_VIEWPORT = { width: 1280, height: 800 } as const;
+
+async function loadSparticuzChromium(): Promise<ChromiumProvider> {
+  const chromium = await import('@sparticuz/chromium');
+  return chromium.default;
+}
+
+/**
+ * Pick the browser binary. `PUPPETEER_EXECUTABLE_PATH` (a system
+ * Chromium — the bench runner image, a dev box) wins and skips the
+ * `@sparticuz/chromium` load entirely; otherwise the bundled Lambda
+ * Chromium supplies both binary and flags, as before.
+ */
+export async function resolveLaunchOptions(
+  viewport: { width: number; height: number },
+  deps: Pick<ScreenshotDeps, 'env' | 'loadChromium'> = {},
+): Promise<LaunchOptions> {
+  const env = deps.env ?? process.env;
+  const override = env.PUPPETEER_EXECUTABLE_PATH?.trim();
+  if (override) {
+    return {
+      executablePath: override,
+      args: [...EXECUTABLE_PATH_LAUNCH_ARGS],
       defaultViewport: viewport,
-      executablePath: await chromium.default.executablePath(),
       headless: true,
     };
+  }
+  const chromium = await (deps.loadChromium ?? loadSparticuzChromium)();
+  return {
+    args: chromium.args,
+    defaultViewport: viewport,
+    executablePath: await chromium.executablePath(),
+    headless: true,
+  };
+}
 
-    const browser = await puppeteer.default.launch(launchOptions);
+async function launchWithPuppeteer(options: LaunchOptions): Promise<ScreenshotBrowser> {
+  const puppeteer = await import('puppeteer-core');
+  return puppeteer.default.launch(options);
+}
+
+/**
+ * Take a screenshot of the rendered component.
+ * Returns the PNG bytes, or null if no browser could be launched.
+ */
+export async function captureScreenshot(
+  html: string,
+  viewport: { width: number; height: number } = DEFAULT_SCREENSHOT_VIEWPORT,
+  deps: ScreenshotDeps = {},
+): Promise<Buffer | null> {
+  try {
+    const launchOptions = await resolveLaunchOptions(viewport, deps);
+    const browser = await (deps.launch ?? launchWithPuppeteer)(launchOptions);
     try {
       const page = await browser.newPage();
       // puppeteer ≥24.43 narrowed setContent's waitUntil to
@@ -229,9 +392,9 @@ async function captureScreenshot(
       await page.waitForNetworkIdle({ idleTime: 500, timeout: 15000 }).catch(() => {});
       await page.waitForSelector('#root > *', { timeout: 10000 }).catch(() => {});
       // Wait a bit for CSS/fonts to settle
-      await new Promise(r => setTimeout(r, 1000));
-      const screenshot = await page.screenshot({ type: 'png', fullPage: true }) as Buffer;
-      return screenshot;
+      await new Promise((r) => setTimeout(r, deps.settleMs ?? 1000));
+      const screenshot = await page.screenshot({ type: 'png', fullPage: true });
+      return Buffer.from(screenshot);
     } finally {
       await browser.close();
     }
@@ -333,8 +496,10 @@ async function callMultimodalLLM(
 export async function runVisualEvaluation(
   context: VisualEvalContext,
   config: VisualEvalConfig,
-): Promise<EvaluationResult | null> {
+  deps: VisualEvalDeps = {},
+): Promise<VisualEvaluationResult | null> {
   const startTime = Date.now();
+  const judge = deps.judge ?? callMultimodalLLM;
 
   // Bundle component + design system into a single JS file
   const bundledCode = await bundleForRendering(
@@ -343,11 +508,49 @@ export async function runVisualEvaluation(
   );
   console.log(`[visual-eval] bundled: ${bundledCode.length}B (${Date.now() - startTime}ms)`);
 
-  // Build the HTML page
+  // Build the HTML page — ONE shell; per-canvas mode re-renders it at each viewport.
   const html = buildRenderHTML(bundledCode, context.cssTokens);
+  const model = config.model ?? getDefaultVisualModel(config.provider);
 
-  // Take screenshot
-  const screenshot = await captureScreenshot(html, config.viewport);
+  // ── Per-canvas mode: one screenshot + one judge call per class ──
+  if (config.canvases !== undefined && config.canvases.length > 0) {
+    const perCanvas: CanvasVisualResult[] = [];
+    const perCanvasResults: EvaluationResult[] = [];
+    for (const canvas of config.canvases) {
+      const viewport = CANVAS_VIEWPORTS[canvas];
+      const screenshot = await captureScreenshot(html, viewport, deps);
+      if (!screenshot) {
+        console.warn(`[visual-eval] no browser available at canvas ${canvas} — skipping visual evaluation`);
+        return null;
+      }
+      const response = await judge(config, model, VISUAL_EVAL_PROMPT, screenshot, context.originalPrompt);
+      const result = parseVisualResponse(response.text, config.passThreshold);
+      result.inputTokens = response.inputTokens;
+      result.outputTokens = response.outputTokens;
+      perCanvasResults.push(result);
+      perCanvas.push({
+        canvas,
+        viewport,
+        score: result.finalScore,
+        passed: result.passed,
+        screenshotPng: screenshot,
+      });
+      console.log(
+        `[visual-eval] canvas=${canvas} ${viewport.width}×${viewport.height} score=${result.finalScore} ` +
+          `${result.passed ? 'pass' : 'FAIL'} | in=${response.inputTokens} out=${response.outputTokens}`,
+      );
+    }
+    const aggregate = aggregateCanvasResults(perCanvas, perCanvasResults);
+    const elapsed = Date.now() - startTime;
+    console.log(
+      `[visual-eval] score=${aggregate.finalScore} (mean of ${perCanvas.length} canvases; ` +
+        `${aggregate.passed ? 'every canvas passed' : `${perCanvas.filter((c) => !c.passed).length} failed`}) (${elapsed}ms)`,
+    );
+    return aggregate;
+  }
+
+  // ── Single-shot mode (today's path) ──
+  const screenshot = await captureScreenshot(html, config.viewport, deps);
   if (!screenshot) {
     console.warn('[visual-eval] no browser available — skipping visual evaluation');
     return null;
@@ -355,8 +558,7 @@ export async function runVisualEvaluation(
   console.log(`[visual-eval] screenshot: ${screenshot.length}B (${Date.now() - startTime}ms)`);
 
   // Send to multimodal LLM
-  const model = config.model ?? getDefaultVisualModel(config.provider);
-  const response = await callMultimodalLLM(
+  const response = await judge(
     config,
     model,
     VISUAL_EVAL_PROMPT,
@@ -375,6 +577,61 @@ export async function runVisualEvaluation(
   return result;
 }
 
+/**
+ * Fold per-canvas verdicts into the single-shot fields: `finalScore` =
+ * rounded mean, `passed` = every canvas passed, `dimensions` = rounded
+ * per-dimension means, `issues` = union (description prefixed with the
+ * canvas), `critique` = one line per canvas, tokens summed.
+ */
+function aggregateCanvasResults(
+  perCanvas: readonly CanvasVisualResult[],
+  results: readonly EvaluationResult[],
+): VisualEvaluationResult {
+  const n = results.length;
+  const mean = (pick: (r: EvaluationResult) => number): number =>
+    Math.round(results.reduce((sum, r) => sum + pick(r), 0) / n);
+  const dimensions: DimensionScores = {
+    completeness: mean((r) => r.dimensions.completeness),
+    visualPolish: mean((r) => r.dimensions.visualPolish),
+    interactivity: mean((r) => r.dimensions.interactivity),
+    accessibility: mean((r) => r.dimensions.accessibility),
+    codeQuality: mean((r) => r.dimensions.codeQuality),
+  };
+  const issues: EvaluationIssue[] = [];
+  const critiques: string[] = [];
+  let inputTokens = 0;
+  let outputTokens = 0;
+  results.forEach((r, i) => {
+    const canvas = perCanvas[i]!.canvas;
+    for (const issue of r.issues) issues.push({ ...issue, description: `[${canvas}] ${issue.description}` });
+    if (r.critique) critiques.push(`${canvas}: ${r.critique}`);
+    inputTokens += r.inputTokens ?? 0;
+    outputTokens += r.outputTokens ?? 0;
+  });
+  return {
+    passed: perCanvas.every((c) => c.passed),
+    finalScore: mean((r) => r.finalScore),
+    dimensions,
+    issues,
+    ...(critiques.length > 0 ? { critique: critiques.join('\n') } : {}),
+    inputTokens,
+    outputTokens,
+    canvases: [...perCanvas],
+  };
+}
+
+/** The per-canvas verdicts without the PNGs — what the harness stamps on `EvalResult.visual`. */
+export function summarizeVisualResult(result: VisualEvaluationResult): VisualEvalSummary | undefined {
+  if (result.canvases === undefined) return undefined;
+  const canvases: CanvasVisualSummary[] = result.canvases.map((c) => ({
+    canvas: c.canvas,
+    viewport: c.viewport,
+    score: c.score,
+    passed: c.passed,
+  }));
+  return { score: result.finalScore, passed: result.passed, canvases };
+}
+
 /**
  * Exported for testing — bundles and builds the HTML for rendering;
  * `callMultimodalLLM` so the #504 routing contract (config →
@@ -448,17 +705,30 @@ function getDefaultVisualModel(provider: 'claude' | 'google'): string {
 // Tier 2 adapter — returns EvalIssue[]
 // ---------------------------------------------------------------------------
 
+/** What the harness's eval round consumes from the visual leg. */
+export interface VisualEvalOutcome {
+  /** Tier-2 issues (empty when no browser is available). */
+  issues: EvalIssue[];
+  /**
+   * Per-canvas summary — present ONLY when `config.canvases` was set and
+   * the leg ran; the harness stamps it on `EvalResult.visual`. Absent on
+   * the single-shot path (byte-identical to the pre-canvas result).
+   */
+  summary?: VisualEvalSummary;
+}
+
 /**
- * Run visual evaluation and return tier 2 EvalIssues.
+ * Run visual evaluation and return tier 2 EvalIssues (+ the per-canvas
+ * summary when canvases were requested).
  */
 export async function runVisualEval(
   context: VisualEvalContext,
   config: VisualEvalConfig,
-): Promise<EvalIssue[]> {
+): Promise<VisualEvalOutcome> {
   const result = await runVisualEvaluation(context, config);
-  if (!result) return []; // puppeteer not available
+  if (!result) return { issues: [] }; // puppeteer not available
 
-  return (result.issues || []).map(issue => ({
+  const issues: EvalIssue[] = (result.issues || []).map(issue => ({
     tier: 2 as const,
     result: (issue.severity === 'critical' ? 'fail' : 'warn') as 'fail' | 'warn',
     category: 'visual' as const,
@@ -467,4 +737,6 @@ export async function runVisualEval(
     description: issue.description,
     fix: issue.fix || '',
   }));
+  const summary = summarizeVisualResult(result);
+  return summary === undefined ? { issues } : { issues, summary };
 }

package/src/harness/coding/init-session.ts

@@ -168,6 +168,7 @@ export async function initSession(input: {
             originalPrompt: params.userPrompt,
             contract: params.contract,
             designContext: undefined,
+            designMode: harness.designMode,
           },
           {
             provider: mapProviderForEvaluator(evalSpec.provider),

package/src/harness/coding/run-coding-turn.ts

@@ -674,6 +674,9 @@ ${closingInstruction}`;
     // typecheck overlays the real wrapper declarations and a generated
     // direct gadget import gets strict option/return narrowing.
     harness.what.gadgetTypes,
+    // Which tier-0 legs fire — the design-vocabulary legs stand down in
+    // `free` mode; every contract leg runs in both.
+    harness.designMode,
   );
   const toolMs = Date.now() - toolStart;
 

package/src/harness/coding/run-eval-round.ts

@@ -22,7 +22,7 @@ import { listContractGadgets } from "@ggui-ai/protocol";
 import type { Classification } from "../../classifier/index.js";
 import type { AgentWorkspace } from "../../coding-agent/workspace.js";
 import type { CostTracker } from "../../evaluation/cost-tracker.js";
-import type { EvalIssue, EvalResult, RuntimeProbeMeta } from "../../evaluation/types-public.js";
+import type { EvalIssue, EvalResult, RuntimeProbeMeta, VisualEvalSummary } from "../../evaluation/types-public.js";
 import { notApplicableCoverage } from "../../evaluation/types-public.js";
 import { mapProviderForEvaluator } from "../enforced-coding.js";
 import { runCheck } from "../index.js";
@@ -453,6 +453,10 @@ export async function runEvalRound(
               sourceCode: currentSource,
               originalPrompt: userPrompt,
               contract,
+              // Criteria + mother prompt follow the triad that produced
+              // the source (free mode: color-only tokens, arm-neutral
+              // visual judging).
+              designMode: harness.designMode,
             },
             {
               provider: mapProviderForEvaluator(evaluationAgent.provider),
@@ -483,6 +487,10 @@ export async function runEvalRound(
               passThreshold: visualThreshold,
               sampleProps: visualEvaluation?.sampleProps,
               viewport: visualEvaluation?.viewport,
+              // Per-canvas judging (arm-neutral) — absent = single shot.
+              ...(visualEvaluation?.canvases !== undefined
+                ? { canvases: visualEvaluation.canvases }
+                : {}),
               // #484/#489 — same threading as the LLM-eval leg above:
               // the visual eval's multimodal call runs inside the same
               // concurrent generation, so it needs the same routing
@@ -497,7 +505,8 @@ export async function runEvalRound(
     ]);
     evalLlmMs = Date.now() - evalLlmStart;
     llmResult = llm;
-    visualIssues = visual;
+    visualIssues = visual?.issues ?? null;
+    const visualSummary: VisualEvalSummary | undefined = visual?.summary;
 
     // Track costs from LLM eval calls
     if (llmResult) {
@@ -524,6 +533,10 @@ export async function runEvalRound(
       ...(llmResult?.criteriaCoverage !== undefined
         ? { criteriaCoverage: llmResult.criteriaCoverage }
         : {}),
+      // Per-canvas visual summary — present only when canvases were
+      // requested and the leg ran; every later re-stamp spreads this
+      // base so it survives to the assembled result.
+      ...(visualSummary !== undefined ? { visual: visualSummary } : {}),
     };
 
     // ── Log merged results, with mode-check subcategory breakdown ──