@ggui-ai/ui-gen 0.16.0 → 0.18.0

package/src/evaluation/visual-evaluator.ts

@@ -11,17 +11,22 @@
 // issues only visible when rendered: broken layouts, overlapping elements,
 // poor visual hierarchy, missing whitespace.
 
+import { buildStylingProfileJudgeBlock } from '../boilerplate/styling-profile.js';
+import type { GenerationProfileInput } from '../boilerplate/styling-profile.js';
 import { build } from 'esbuild';
-import { getCssTokens } from '@ggui-ai/design/rendering';
+import { fillFitRule, getCssTokens } from '@ggui-ai/design/rendering';
+import { judgeDesignIdentity, type JudgeDesignIdentity } from './design-identity.js';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { createRequire } from 'node:module';
+import { existsSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { createHash } from 'node:crypto';
 import { tmpdir } from 'os';
 import { createVisionAgent, type AgentConfig } from '../harness/llm-router';
 import type { EvaluationResult, EvaluationIssue, DimensionScores } from './types';
-import type { CanvasVisualSummary, EvalIssue, VisualEvalSummary } from './types-public.js';
+import type { CanvasJudgeRecord, CanvasVisualSummary, EvalIssue, VisualEvalSummary } from './types-public.js';
 import type { LaunchOptions } from 'puppeteer-core';
-import { CANVAS_VIEWPORTS, type CanvasClass, type CanvasViewport } from '../design-mode.js';
+import { CANVAS_VIEWPORTS, displayModeForCanvas, type CanvasClass, type CanvasViewport } from '../design-mode.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -56,6 +61,23 @@ export interface VisualEvalConfig {
    * evaluator constructs so its multimodal call never falls back to
    * `process.env` for credentials or model routing.
    */
+  /**
+   * Vision calls per judged canvas on the SAME captured frame, aggregated by
+   * the median (ggui#1072). Default 1 — a single judgement, byte-identical to
+   * the instrument before this option existed. K is an instrument dial: a
+   * run mixes K at its own peril.
+   */
+  judgeK?: number;
+  /** The canvases sampled `judgeK` times; default = every judged canvas when `judgeK > 1`. */
+  judgeKCanvases?: readonly CanvasClass[];
+  /**
+   * The design `src` tree the judge bundles the component against
+   * (ggui#1042): an explicit input, so a judge-only re-judge names the tree
+   * it painted with. Default: the design package beside this one.
+   */
+  designSrcDir?: string;
+  /** The mode the caller composed `cssTokens` in — a receipt on the row, never a switch (ggui#1076: judge and runtime must name the same mode). */
+  themeMode?: 'light' | 'dark';
   routeOverride?: AgentConfig['routeOverride'];
   /**
    * Provider-429-retry observer — see `AgentConfig.onRetry`.
@@ -76,6 +98,84 @@ export interface CanvasVisualResult {
   passed: boolean;
   /** The PNG the judge saw — kept for artefact persistence + the human look. */
   screenshotPng: Buffer;
+  /**
+   * The document's scroll height at this canvas's viewport, CSS px — what
+   * the box would have to be for nothing to be hidden (ggui#1027). `null`
+   * when the page could not be measured.
+   */
+  contentHeight: number | null;
+  /** `contentHeight > viewport.height` — a measurement; what it MEANS is {@link canvasFitPolicy}'s. */
+  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, absent on the inline card. */
+  fit?: 'fill';
+}
+
+/** How a canvas is captured for the judge and what an overflow means there (ggui#1027). */
+export type CaptureMode = 'viewport' | 'full-page';
+export interface CanvasFitPolicy {
+  /** `viewport` = the judge sees the box the user sees; `full-page` = the whole scrolled document. */
+  readonly capture: CaptureMode;
+  /** The verdict an overflow earns on this canvas. */
+  readonly overflow: 'fail' | 'warn' | 'none';
+}
+
+/**
+ * The inline chat card is a BOX — the bubble bounds the component and it
+ * does not scroll — so the judge captures the viewport (a 1289 px hello on
+ * a 640 px card was scored 86 from a full-page capture that showed the
+ * judge what no user sees) and an overflow is a critical layout issue that
+ * fails the canvas. A phone's first screen may scroll, so the overflow is
+ * reported as a major issue and the score stands. Pages (`md`/`lg`/`xl`)
+ * scroll by design: measured, never judged.
+ */
+export function canvasFitPolicy(canvas: CanvasClass): CanvasFitPolicy {
+  switch (canvas) {
+    case 'xs-chat-card':
+      return { capture: 'viewport', overflow: 'fail' };
+    case 'mobile-fullscreen-small':
+      return { capture: 'full-page', overflow: 'warn' };
+    default:
+      return { capture: 'full-page', overflow: 'none' };
+  }
+}
+
+/**
+ * The mount element of the judge page (ggui#1100). Its class is the scope
+ * `fillFitRule` targets — the judge's counterpart of the runtime's mount list.
+ */
+export const JUDGE_SCOPE_CLASS = 'ggui-judge-scope';
+
+/**
+ * How the judge composes a canvas (ggui#1100): the served runtime stretches
+ * the mounted root to the frame on every fullscreen surface (`fit: 'fill'`,
+ * ggui#1041/#1073/#1096) and leaves the inline card at its natural height —
+ * the judge does the same, or it scores a picture the user never sees (a
+ * content-sized hello on an empty 768×1024 page; candidate 34's hellos).
+ */
+export function canvasFit(canvas: CanvasClass): 'fill' | undefined {
+  return displayModeForCanvas(canvas) === 'fullscreen' ? 'fill' : undefined;
+}
+
+/** The deterministic fit issue — one per overflowing canvas, in the judge's issue shape so it rides the same channel. */
+export function canvasOverflowIssue(
+  canvas: CanvasClass,
+  viewport: CanvasViewport,
+  contentHeight: number,
+  verdict: 'fail' | 'warn',
+): EvaluationIssue {
+  const hidden = contentHeight - viewport.height;
+  return {
+    dimension: 'canvas-overflow',
+    severity: verdict === 'fail' ? 'critical' : 'major',
+    description:
+      `Rendered content is ${contentHeight}px tall on the ${canvas} canvas (${viewport.width}×${viewport.height}) — ` +
+      `${hidden}px ${verdict === 'fail' ? 'is cut off: the inline card does not scroll' : 'sits below the first screen'}.`,
+    fix:
+      'Fit the composition to the canvas: fewer and shorter sections, one compact row of chips, no hero taller than ' +
+      'a third of the box, no fixed min-heights or tall paddings — measure against the canvas, not the page.',
+  };
 }
 
 /**
@@ -86,6 +186,10 @@ export interface CanvasVisualResult {
  */
 export interface VisualEvaluationResult extends EvaluationResult {
   canvases?: CanvasVisualResult[];
+  /** The design tree the judge painted with (ggui#1042) — present on every per-canvas judgement. */
+  design?: JudgeDesignIdentity;
+  /** The mode `cssTokens` were composed in, when the caller said (ggui#1076). */
+  themeMode?: 'light' | 'dark';
 }
 
 /** Injection points for `runVisualEvaluation` — screenshot deps plus the judge call (tests). */
@@ -101,6 +205,8 @@ export interface VisualEvalContext {
   originalPrompt: string;
   /** Design system CSS tokens */
   cssTokens?: string;
+  /** The app's generation profile (#991) — judged relative to, never against. */
+  profile?: GenerationProfileInput;
 }
 
 // ---------------------------------------------------------------------------
@@ -135,14 +241,70 @@ export function resolveUiGenPackageDir(): string {
   return resolve(selfDir, '..', '..');
 }
 
+/**
+ * Where `@ggui-ai/wire` actually is, from ui-gen's OWN module graph —
+ * layout-proof: a workspace checkout links it under `node_modules/`, a
+ * `pnpm deploy` tree puts it beside ui-gen under `.pnpm/…/node_modules/`,
+ * and a plain install nests it; `import.meta.resolve` answers for all
+ * three (directory candidates first, module graph last). Aliased
+ * explicitly in the judge's bundle so the generated component's wire
+ * import never depends on the directory layout the evaluator runs in.
+ */
+export function resolveWirePackageDir(): string | null {
+  const uiGenDir = resolveUiGenPackageDir();
+  const candidates = [
+    resolve(uiGenDir, 'node_modules', '@ggui-ai', 'wire'), // workspace / nested install
+    resolve(uiGenDir, '..', 'wire'), // pnpm deploy: `.pnpm/<ui-gen>@<ver>/node_modules/@ggui-ai/{ui-gen,wire}`
+    resolve(uiGenDir, '..', '..', '@ggui-ai', 'wire'), // hoisted flat install beside the scope dir
+  ];
+  for (const dir of candidates) {
+    if (existsSync(resolve(dir, 'package.json'))) return dir;
+  }
+  try {
+    // Last resort: ask the module graph (Node ≥ 20.6). Not every runner
+    // supports it synchronously, hence the guarded position.
+    const entry = fileURLToPath(import.meta.resolve('@ggui-ai/wire'));
+    let dir = dirname(entry);
+    for (let i = 0; i < 6; i++) {
+      if (existsSync(resolve(dir, 'package.json'))) return dir;
+      dir = dirname(dir);
+    }
+  } catch {
+    // fall through — nodePaths still gets a chance
+  }
+  return null;
+}
+
+/**
+ * The `@ggui-ai/design` package root — resolved by MODULE ID, never by counting
+ * directories (ggui#1110).
+ *
+ * The arithmetic this replaced (`…/'..','..','..','design'`) was correct only
+ * for the layout it was written against — `node_modules/@ggui-ai/ui-gen/dist/
+ * evaluation` → `node_modules/@ggui-ai/` + `design`. Under a deploy-flattened
+ * layout it landed one level too high, at `node_modules/design`, a path that is
+ * not the design package at all: the judge then walked a directory that does not
+ * exist, threw ENOENT inside every evaluation round on that deployment, and a
+ * bar refused cards no one could judge. `@ggui-ai/design` exports `./package.json`,
+ * so the module resolver answers correctly in every layout — scoped, flattened,
+ * hoisted — and the receipt keeps working inside the image.
+ */
 export function resolveDesignPackageDir(): string {
-  const selfDir = dirname(fileURLToPath(import.meta.url));
-  return resolve(selfDir, '..', '..', '..', 'design');
+  try {
+    return dirname(createRequire(import.meta.url).resolve('@ggui-ai/design/package.json'));
+  } catch {
+    // A runner whose module graph cannot see the package (a bundled judge, a
+    // test double). The layout guess is the last resort, and a wrong answer is
+    // now a NAMED absent receipt rather than a thrown round (`judgeDesignIdentity`).
+    const selfDir = dirname(fileURLToPath(import.meta.url));
+    return resolve(selfDir, '..', '..', '..', 'design');
+  }
 }
 
 async function bundleForRendering(
   compiledCode: string,
   sampleProps: Record<string, unknown>,
+  designSrc: string = resolve(resolveDesignPackageDir(), 'src'),
 ): Promise<string> {
   // Write component + entry to temp files for esbuild
   const tmpDir = resolve(tmpdir(), 'ggui-visual-eval-' + Date.now());
@@ -150,7 +312,8 @@ async function bundleForRendering(
   const componentFile = resolve(tmpDir, 'component.tsx');
   const entryFile = resolve(tmpDir, 'entry.tsx');
 
-  const designPkgDir = resolveDesignPackageDir();
+  const designPkgDir = resolve(designSrc, '..');
+  const wirePkgDir = resolveWirePackageDir();
 
   // Write the compiled component as a separate module
   writeFileSync(componentFile, compiledCode);
@@ -212,6 +375,10 @@ try {
       jsxImportSource: 'react',
       external: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime'],
       alias: {
+        // The wire hooks: resolved from ui-gen's own module graph so the
+        // alias holds in a workspace checkout AND in a `pnpm deploy` image
+        // (where deps are siblings, not children, of this package).
+        ...(wirePkgDir !== null ? { '@ggui-ai/wire': wirePkgDir } : {}),
         // D1: generated code imports the single `@ggui-ai/design` barrel.
         // The subpath aliases stay for any first-party / legacy code.
         '@ggui-ai/design': resolve(designPkgDir, 'src', 'index.ts'),
@@ -223,7 +390,10 @@ try {
       // 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')],
+      // Workspace layout (deps under this package's node_modules) and the
+      // `pnpm deploy` layout (deps as siblings of this package) — both
+      // searched for any other allowlisted bare import.
+      nodePaths: [resolve(resolveUiGenPackageDir(), 'node_modules'), resolve(resolveUiGenPackageDir(), '..')],
       logLevel: 'silent',
     });
 
@@ -237,6 +407,7 @@ try {
 function buildRenderHTML(
   bundledCode: string,
   cssTokens?: string,
+  fit?: 'fill',
 ): string {
   // Default to the design tokens production's no-theme branch injects
   // (getCssTokens → default theme, light) — ggui#613: under the s4
@@ -260,10 +431,11 @@ function buildRenderHTML(
       color: var(--ggui-color-neutral-900, #111827);
     }
     .error { color: #dc2626; padding: 16px; font-family: monospace; white-space: pre-wrap; }
+    ${fit === 'fill' ? fillFitRule(JUDGE_SCOPE_CLASS) : ''}
   </style>
 </head>
 <body>
-  <div id="root"></div>
+  <div id="root"${fit === 'fill' ? ` class="${JUDGE_SCOPE_CLASS}"` : ''}></div>
   <script type="importmap">
   {
     "imports": {
@@ -290,6 +462,8 @@ 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>;
+  /** Evaluates a JS expression in the page and returns its serialised value — the fit measurement (ggui#1027). */
+  evaluate(expression: string): Promise<unknown>;
   screenshot(options: { type: 'png'; fullPage: boolean }): Promise<Uint8Array>;
 }
 
@@ -375,11 +549,35 @@ async function launchWithPuppeteer(options: LaunchOptions): Promise<ScreenshotBr
  * Take a screenshot of the rendered component.
  * Returns the PNG bytes, or null if no browser could be launched.
  */
-export async function captureScreenshot(
+/** Screenshot plus the reason when none could be taken — the judge's `unavailableReason`. */
+export interface ScreenshotAttempt {
+  readonly png: Buffer | null;
+  readonly reason?: string;
+  /** The document's scroll height at the viewport (ggui#1027); `null` when unmeasurable. */
+  readonly contentHeight: number | null;
+}
+
+/** The expression the fit measurement evaluates in the page — the taller of the two scroll heights. */
+export const CONTENT_HEIGHT_EXPRESSION =
+  'Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0)';
+
+/** Measure the rendered document's height; a failed measurement is reported, never a failed capture. */
+async function measureContentHeight(page: ScreenshotPage): Promise<number | null> {
+  try {
+    const h = await page.evaluate(CONTENT_HEIGHT_EXPRESSION);
+    return typeof h === 'number' && Number.isFinite(h) ? Math.round(h) : null;
+  } catch (e) {
+    console.warn(`[visual-eval] content height unavailable: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+
+export async function captureScreenshotDetailed(
   html: string,
   viewport: { width: number; height: number } = DEFAULT_SCREENSHOT_VIEWPORT,
   deps: ScreenshotDeps = {},
-): Promise<Buffer | null> {
+  capture: CaptureMode = 'full-page',
+): Promise<ScreenshotAttempt> {
   try {
     const launchOptions = await resolveLaunchOptions(viewport, deps);
     const browser = await (deps.launch ?? launchWithPuppeteer)(launchOptions);
@@ -393,22 +591,32 @@ export async function captureScreenshot(
       await page.waitForSelector('#root > *', { timeout: 10000 }).catch(() => {});
       // Wait a bit for CSS/fonts to settle
       await new Promise((r) => setTimeout(r, deps.settleMs ?? 1000));
-      const screenshot = await page.screenshot({ type: 'png', fullPage: true });
-      return Buffer.from(screenshot);
+      const contentHeight = await measureContentHeight(page);
+      const screenshot = await page.screenshot({ type: 'png', fullPage: capture === 'full-page' });
+      return { png: Buffer.from(screenshot), contentHeight };
     } finally {
       await browser.close();
     }
   } catch (e) {
-    console.warn(`[visual-eval] screenshot failed: ${e instanceof Error ? e.message : e}`);
-    return null;
+    const reason = `screenshot failed: ${e instanceof Error ? e.message : String(e)}`;
+    console.warn(`[visual-eval] ${reason}`);
+    return { png: null, reason, contentHeight: null };
   }
 }
 
+export async function captureScreenshot(
+  html: string,
+  viewport: { width: number; height: number } = DEFAULT_SCREENSHOT_VIEWPORT,
+  deps: ScreenshotDeps = {},
+): Promise<Buffer | null> {
+  return (await captureScreenshotDetailed(html, viewport, deps)).png;
+}
+
 // ---------------------------------------------------------------------------
 // Multimodal LLM evaluation
 // ---------------------------------------------------------------------------
 
-const VISUAL_EVAL_PROMPT = `You are a visual quality evaluator for ggui — a platform where AI agents generate React UI components on demand.
+export const VISUAL_EVAL_PROMPT = `You are a visual quality evaluator for ggui — a platform where AI agents generate React UI components on demand.
 
 ## Context
 The screenshot shows a generated React component built from a design system with CSS variable theming. The component was created by an LLM to fulfill a user's request. Your job is to evaluate whether the generated UI achieves the user's goal AND looks professionally designed.
@@ -435,6 +643,8 @@ The screenshot shows a generated React component built from a design system with
 - Error messages like "Render error" or blank white space = rendering score 0
 - A component that renders but is just a wall of text with no structure should score low on layout and hierarchy
 
+List AT MOST 6 issues, most severe first, one sentence each for "description" and "fix" — a longer list is cut off and lost.
+
 Respond with ONLY a JSON object (no markdown, no explanation):
 {
   "completeness": <0-100>,
@@ -457,14 +667,37 @@ Respond with ONLY a JSON object (no markdown, no explanation):
  * governs credentials and model routing (including the Anthropic
  * Bedrock path) instead of `process.env`.
  */
+/**
+ * Output budget for the judge's answer. 1500 cut a board's issue list
+ * mid-array (`Expected ',' or ']' after array element`, six kanban cells
+ * on 2026-09-11) — deterministic on the content, so a same-prompt retry
+ * could never clear it. 4096 fits the bounded list the prompt now asks for
+ * with room; the salvage path covers the remainder.
+ */
+export const VISUAL_JUDGE_MAX_OUTPUT_TOKENS = 4096;
+
+/**
+ * The judge instrument's name and content digest, for the record a run
+ * stamps beside every visual score. The NAME is for readers; the DIGEST
+ * is computed from the prompt text at module load, so a stamped row can
+ * never claim a prompt version it did not run — change the prompt and the
+ * digest moves with it (the pin ties the name to the bounded-list text).
+ */
+export const VISUAL_JUDGE_PROMPT_VERSION = 'v2-bounded-issues';
+export const VISUAL_JUDGE_PROMPT_DIGEST = createHash('sha256').update(VISUAL_EVAL_PROMPT, 'utf8').digest('hex');
+
 async function callMultimodalLLM(
   config: VisualEvalConfig,
   model: string,
   prompt: string,
   screenshot: Buffer,
   originalPrompt: string,
+  profileBlock = '',
 ) {
-  const userPrompt = `## Original Request\n${originalPrompt}\n\nEvaluate the screenshot of the generated component.`;
+  const userPrompt =
+    `## Original Request\n${originalPrompt}\n\n` +
+    (profileBlock.length > 0 ? `${profileBlock}\n\n` : '') +
+    'Evaluate the screenshot of the generated component.';
   const agent = createVisionAgent({
     provider: config.provider === 'claude' ? 'anthropic' : config.provider,
     model,
@@ -476,7 +709,7 @@ async function callMultimodalLLM(
     prompt,
     userPrompt,
     { mediaType: 'image/png', base64: screenshot.toString('base64') },
-    1500,
+    VISUAL_JUDGE_MAX_OUTPUT_TOKENS,
   );
 }
 
@@ -493,19 +726,117 @@ async function callMultimodalLLM(
  *
  * Returns null if puppeteer is not available (graceful fallback).
  */
+/**
+ * The judge's answer WITH the reason when it could not judge: `result` is
+ * null exactly when no screenshot could be taken (no browser, a launch or
+ * in-page failure) or the component could not be bundled; `unavailableReason`
+ * names why in words and `canvas` the canvas it happened at. A production
+ * caller records the reason in its receipt — a `judge_unavailable` that only
+ * says "null" cost a log dive on 2026-09-10 (puppeteer-core missing in the
+ * deploy image).
+ */
+export interface VisualEvalDetailed {
+  readonly result: VisualEvaluationResult | null;
+  readonly unavailableReason?: string;
+  readonly canvas?: CanvasClass;
+}
+
+
+/** One judge call parsed, retried ONCE on a malformed answer (#1017); the FIRST reason is kept verbatim. */
+type JudgedAnswer =
+  | { readonly kind: 'ok'; readonly result: EvaluationResult; readonly inputTokens: number; readonly outputTokens: number }
+  | { readonly kind: 'unparsable'; readonly reason: string };
+
+/** How many vision calls this canvas gets (ggui#1072): `judgeK` when the canvas is sampled, else 1. */
+function judgeCountFor(config: VisualEvalConfig, canvas: CanvasClass): number {
+  const k = Math.max(1, Math.floor(config.judgeK ?? 1));
+  if (k === 1) return 1;
+  return config.judgeKCanvases === undefined || config.judgeKCanvases.includes(canvas) ? k : 1;
+}
+
+/** The median of a non-empty list — the lower middle for an even count, so the decision is always one judge's number. */
+function medianOf(values: readonly number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor((sorted.length - 1) / 2)]!;
+}
+
+/** Population σ, rounded to one decimal; 0 for one sample. */
+function populationSigma(values: readonly number[]): number {
+  if (values.length < 2) return 0;
+  const mean = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((a, b) => a + (b - mean) ** 2, 0) / values.length;
+  return Math.round(Math.sqrt(variance) * 10) / 10;
+}
+
+async function judgeAndParse(
+  judge: typeof callMultimodalLLM,
+  config: VisualEvalConfig,
+  model: string,
+  screenshot: Buffer,
+  originalPrompt: string,
+  profileBlock: string,
+  canvas?: CanvasClass,
+): Promise<JudgedAnswer> {
+  let firstReason: string | undefined;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const response = await judge(config, model, VISUAL_EVAL_PROMPT, screenshot, originalPrompt, profileBlock);
+    try {
+      const result = parseVisualResponse(response.text, config.passThreshold);
+      return { kind: 'ok', result, inputTokens: response.inputTokens, outputTokens: response.outputTokens };
+    } catch (e) {
+      // A TRUNCATED answer (cut inside `issues` at the output cap) is deterministic on
+      // the content — retrying the same prompt reproduces it. The four dimensions are
+      // emitted before `issues`, so the score is recoverable from the closed prefix.
+      const salvaged = salvageTruncatedVisualAnswer(response.text, config.passThreshold);
+      if (salvaged !== null) {
+        console.warn(`[visual-eval] visual_judge_truncated${canvas ? ` canvas=${canvas}` : ''}: answer cut after ${response.text.length} chars — score recovered from the closed prefix, issues list partial`);
+        return { kind: 'ok', result: salvaged, inputTokens: response.inputTokens, outputTokens: response.outputTokens };
+      }
+      const reason = `judge answer unparsable: ${e instanceof Error ? e.message : String(e)}`;
+      if (attempt === 1) {
+        firstReason = reason;
+        console.warn(`[visual-eval] visual_judge_retry${canvas ? ` canvas=${canvas}` : ''}: ${reason}`);
+      } else {
+        console.warn(`[visual-eval] visual_judge_retry failed again${canvas ? ` canvas=${canvas}` : ''}: ${reason}`);
+      }
+    }
+  }
+  return { kind: 'unparsable', reason: firstReason ?? 'judge answer unparsable' };
+}
+
 export async function runVisualEvaluation(
   context: VisualEvalContext,
   config: VisualEvalConfig,
   deps: VisualEvalDeps = {},
 ): Promise<VisualEvaluationResult | null> {
+  return (await runVisualEvaluationDetailed(context, config, deps)).result;
+}
+
+export async function runVisualEvaluationDetailed(
+  context: VisualEvalContext,
+  config: VisualEvalConfig,
+  deps: VisualEvalDeps = {},
+): Promise<VisualEvalDetailed> {
   const startTime = Date.now();
   const judge = deps.judge ?? callMultimodalLLM;
+  // ggui#1042: the design tree is an input and a part of the judgement's identity.
+  const designSrc = config.designSrcDir ?? resolve(resolveDesignPackageDir(), 'src');
+  const design = judgeDesignIdentity(designSrc);
+  const stamp = <T extends VisualEvaluationResult>(r: T): T => ({
+    ...r,
+    ...(design !== null ? { design } : {}),
+    ...(config.themeMode !== undefined ? { themeMode: config.themeMode } : {}),
+  });
 
   // Bundle component + design system into a single JS file
-  const bundledCode = await bundleForRendering(
-    context.compiledCode,
-    config.sampleProps ?? {},
-  );
+  let bundledCode: string;
+  try {
+    bundledCode = await bundleForRendering(context.compiledCode, config.sampleProps ?? {}, designSrc);
+  } catch (e) {
+    const unavailableReason = `bundle failed: ${e instanceof Error ? e.message : String(e)}`;
+    console.warn(`[visual-eval] ${unavailableReason}`);
+    return { result: null, unavailableReason };
+  }
   console.log(`[visual-eval] bundled: ${bundledCode.length}B (${Date.now() - startTime}ms)`);
 
   // Build the HTML page — ONE shell; per-canvas mode re-renders it at each viewport.
@@ -518,15 +849,51 @@ export async function runVisualEvaluation(
     const perCanvasResults: EvaluationResult[] = [];
     for (const canvas of config.canvases) {
       const viewport = CANVAS_VIEWPORTS[canvas];
-      const screenshot = await captureScreenshot(html, viewport, deps);
+      const policy = canvasFitPolicy(canvas);
+      // ggui#1100: the page is composed per canvas with the runtime's fit — fullscreen canvases fill, the inline card does not.
+      const fit = canvasFit(canvas);
+      const canvasHtml = fit !== undefined ? buildRenderHTML(bundledCode, context.cssTokens, fit) : html;
+      const attempt = await captureScreenshotDetailed(canvasHtml, viewport, deps, policy.capture);
+      const screenshot = attempt.png;
       if (!screenshot) {
-        console.warn(`[visual-eval] no browser available at canvas ${canvas} — skipping visual evaluation`);
-        return null;
+        const unavailableReason = attempt.reason ?? 'no browser available';
+        console.warn(`[visual-eval] ${unavailableReason} at canvas ${canvas} — skipping visual evaluation`);
+        return { result: null, unavailableReason, canvas };
+      }
+      // ggui#1072: k vision calls on the SAME frame; the decision value is the median.
+      const k = judgeCountFor(config, canvas);
+      const profileBlock = buildStylingProfileJudgeBlock(context.profile);
+      const answers = await Promise.all(
+        Array.from({ length: k }, () => judgeAndParse(judge, config, model, screenshot, context.originalPrompt, profileBlock, canvas)),
+      );
+      const parsed = answers.filter((a): a is Extract<JudgedAnswer, { kind: 'ok' }> => a.kind === 'ok');
+      if (parsed.length === 0) {
+        const first = answers.find((a): a is Extract<JudgedAnswer, { kind: 'unparsable' }> => a.kind === 'unparsable');
+        return { result: null, unavailableReason: first?.reason ?? 'judge answer unparsable', canvas };
+      }
+      const samples = parsed.map((a) => a.result.finalScore);
+      const median = medianOf(samples);
+      const representative = parsed[samples.indexOf(median)]!;
+      const result = representative.result;
+      result.finalScore = median;
+      result.passed = median >= config.passThreshold;
+      result.inputTokens = parsed.reduce((sum, a) => sum + a.inputTokens, 0);
+      result.outputTokens = parsed.reduce((sum, a) => sum + a.outputTokens, 0);
+      const response = { inputTokens: result.inputTokens, outputTokens: result.outputTokens };
+      const judgeRecord: CanvasJudgeRecord = {
+        k,
+        rule: 'median',
+        samples,
+        sigma: populationSigma(samples),
+        notes: parsed.map((a) => a.result.critique ?? ''),
+      };
+      // The fit verdict (ggui#1027): deterministic, in the judge's issue channel.
+      const contentHeight = attempt.contentHeight;
+      const overflow = contentHeight !== null && contentHeight > viewport.height;
+      if (contentHeight !== null && contentHeight > viewport.height && policy.overflow !== 'none') {
+        result.issues.push(canvasOverflowIssue(canvas, viewport, contentHeight, policy.overflow));
+        if (policy.overflow === 'fail') result.passed = false;
       }
-      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,
@@ -534,10 +901,15 @@ export async function runVisualEvaluation(
         score: result.finalScore,
         passed: result.passed,
         screenshotPng: screenshot,
+        contentHeight,
+        overflow,
+        judge: judgeRecord,
+        ...(fit !== undefined ? { fit } : {}),
       });
       console.log(
-        `[visual-eval] canvas=${canvas} ${viewport.width}×${viewport.height} score=${result.finalScore} ` +
-          `${result.passed ? 'pass' : 'FAIL'} | in=${response.inputTokens} out=${response.outputTokens}`,
+        `[visual-eval] canvas=${canvas} ${viewport.width}×${viewport.height} score=${result.finalScore}${k > 1 ? ` (median of ${judgeRecord.samples.length}/${k}: ${judgeRecord.samples.join(',')} σ=${judgeRecord.sigma})` : ''} ` +
+          `${result.passed ? 'pass' : 'FAIL'} | content=${contentHeight ?? '?'}px${overflow ? ` OVERFLOW (${policy.overflow})` : ''} ` +
+          `| in=${response.inputTokens} out=${response.outputTokens}`,
       );
     }
     const aggregate = aggregateCanvasResults(perCanvas, perCanvasResults);
@@ -546,35 +918,40 @@ export async function runVisualEvaluation(
       `[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;
+    return { result: stamp(aggregate) };
   }
 
   // ── Single-shot mode (today's path) ──
-  const screenshot = await captureScreenshot(html, config.viewport, deps);
+  const attempt = await captureScreenshotDetailed(html, config.viewport, deps);
+  const screenshot = attempt.png;
   if (!screenshot) {
-    console.warn('[visual-eval] no browser available — skipping visual evaluation');
-    return null;
+    const unavailableReason = attempt.reason ?? 'no browser available';
+    console.warn(`[visual-eval] ${unavailableReason} — skipping visual evaluation`);
+    return { result: null, unavailableReason };
   }
   console.log(`[visual-eval] screenshot: ${screenshot.length}B (${Date.now() - startTime}ms)`);
 
-  // Send to multimodal LLM
-  const response = await judge(
+  // Send to multimodal LLM (one retry on a malformed answer — #1017)
+  const answer = await judgeAndParse(
+    judge,
     config,
     model,
-    VISUAL_EVAL_PROMPT,
     screenshot,
     context.originalPrompt,
+    buildStylingProfileJudgeBlock(context.profile),
   );
-
-  // Parse response
-  const result = parseVisualResponse(response.text, config.passThreshold);
-  result.inputTokens = response.inputTokens;
-  result.outputTokens = response.outputTokens;
+  if (answer.kind === 'unparsable') {
+    return { result: null, unavailableReason: answer.reason };
+  }
+  const result = answer.result;
+  result.inputTokens = answer.inputTokens;
+  result.outputTokens = answer.outputTokens;
+  const response = { inputTokens: answer.inputTokens, outputTokens: answer.outputTokens };
 
   const elapsed = Date.now() - startTime;
   console.log(`[visual-eval] score=${result.finalScore} (${elapsed}ms) | in=${response.inputTokens} out=${response.outputTokens}`);
 
-  return result;
+  return { result: stamp(result) };
 }
 
 /**
@@ -628,8 +1005,18 @@ export function summarizeVisualResult(result: VisualEvaluationResult): VisualEva
     viewport: c.viewport,
     score: c.score,
     passed: c.passed,
+    contentHeight: c.contentHeight,
+    overflow: c.overflow,
+    judge: c.judge,
+    ...(c.fit !== undefined ? { fit: c.fit } : {}),
   }));
-  return { score: result.finalScore, passed: result.passed, canvases };
+  return {
+    score: result.finalScore,
+    passed: result.passed,
+    canvases,
+    ...(result.design !== undefined ? { design: result.design } : {}),
+    ...(result.themeMode !== undefined ? { themeMode: result.themeMode } : {}),
+  };
 }
 
 /**
@@ -643,6 +1030,52 @@ export { bundleForRendering, buildRenderHTML, callMultimodalLLM };
 // Response parsing
 // ---------------------------------------------------------------------------
 
+/**
+ * Recover a judge answer cut off inside its `issues` array: all four
+ * dimensions must be present in the prefix (else null); issue objects
+ * that closed are kept; `critique` (emitted last) is usually lost and is
+ * replaced by a truncation note so the receipt says what happened.
+ */
+export function salvageTruncatedVisualAnswer(text: string, passThreshold: number): EvaluationResult | null {
+  const dim = (name: string): number | null => {
+    const m = text.match(new RegExp(`"${name}"\\s*:\\s*(\\d+(?:\\.\\d+)?)`));
+    return m ? Number(m[1]) : null;
+  };
+  const completeness = dim('completeness');
+  const layout = dim('layout');
+  const hierarchy = dim('hierarchy');
+  const aesthetics = dim('aesthetics');
+  if (completeness === null || layout === null || hierarchy === null || aesthetics === null) return null;
+  const issues: Array<{ dimension: string; severity: string; description: string; fix: string }> = [];
+  const issuesAt = text.indexOf('"issues"');
+  if (issuesAt >= 0) {
+    for (const m of text.slice(issuesAt).matchAll(/\{[^{}]*\}/g)) {
+      try {
+        const o = JSON.parse(m[0]) as { dimension?: unknown; severity?: unknown; description?: unknown; fix?: unknown };
+        if (typeof o.description === 'string') {
+          issues.push({
+            dimension: typeof o.dimension === 'string' ? o.dimension : 'layout',
+            severity: typeof o.severity === 'string' ? o.severity : 'minor',
+            description: o.description,
+            fix: typeof o.fix === 'string' ? o.fix : '',
+          });
+        }
+      } catch {
+        // an unclosed object at the cut — skipped by construction
+      }
+    }
+  }
+  const rebuilt = JSON.stringify({
+    completeness,
+    layout,
+    hierarchy,
+    aesthetics,
+    issues,
+    critique: `[truncated judge answer — score recovered from the closed prefix; ${issues.length} issue(s) kept, the rest and the critique were cut]`,
+  });
+  return parseVisualResponse(rebuilt, passThreshold);
+}
+
 function parseVisualResponse(text: string, passThreshold: number): EvaluationResult {
   const jsonMatch = text.match(/\{[\s\S]*\}/);
   if (!jsonMatch) {