@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/src/evaluation/criteria/resolve.ts

@@ -8,6 +8,8 @@
  * id; a tie or an unanswered id reads `n/a` (the CTO's A2) — a `must` at `n/a` is never a pass when
  * a gate later reads the set.
  */
+import { EDGE_INSTRUMENT_IDS } from './edge-instruments.js';
+import type { MountFit } from '@ggui-ai/design/rendering';
 import type { CriteriaAnswer } from '../types.js';
 import type { CriteriaAnswerCounts, CriteriaBlock, CriteriaContext, CriteriaVerdict, CriterionVerdict } from '../types-public.js';
 import type { VisionFinishReason } from '../../harness/llm-router.js';
@@ -50,14 +52,20 @@ export interface CriteriaMeasurements {
    * `null` when the probe ran and failed.
    */
   readonly edge?: EdgeVerdict | null;
+  /** #1765 — the v2 edge rule on the same capture, read beside v1: absent / `null` as for `edge`. */
+  readonly edgeV2?: EdgeVerdict | null;
   /** ggui#1711 — the capture includes a state after an action ran. Absent = no (every capture today). */
   readonly postActionCapture?: boolean;
 }
 
 function besideRead(kind: 'edge', m: CriteriaMeasurements): Read {
-  if (m.edge === undefined) return { verdict: 'n/a', evidence: 'not measured: this capture had no page to read' };
-  if (m.edge === null) return { verdict: 'n/a', evidence: 'edge probe failed on this capture' };
-  return { verdict: m.edge.verdict, evidence: m.edge.evidence };
+  return edgeRead(m.edge);
+}
+
+function edgeRead(e: EdgeVerdict | null | undefined): Read {
+  if (e === undefined) return { verdict: 'n/a', evidence: 'not measured: this capture had no page to read' };
+  if (e === null) return { verdict: 'n/a', evidence: 'edge probe failed on this capture' };
+  return { verdict: e.verdict, evidence: e.evidence };
 }
 
 type Read = { verdict: CriteriaVerdict; evidence: string };
@@ -122,7 +130,13 @@ export function resolveCriteriaBlock(args: {
       source: s.source,
       verdict: read.verdict,
       evidence: read.evidence,
-      ...(beside !== undefined && row.evaluation === 'judge' ? { instrument: besideRead(beside, args.measurements) } : {}),
+      ...(beside !== undefined && row.evaluation === 'judge'
+        ? {
+            instrument: { ...besideRead(beside, args.measurements), id: EDGE_INSTRUMENT_IDS.v1 },
+            // #1765 — v2 beside v1 on the same capture, report-only, until its own fresh sealed draw.
+            instrumentV2: { ...edgeRead(args.measurements.edgeV2), id: EDGE_INSTRUMENT_IDS.v2 },
+          }
+        : {}),
     });
   }
   return {
@@ -153,6 +167,8 @@ export interface CriteriaJudgeFrame {
   readonly height: number;
   /** ggui#1492 — the host whose presentation framed this canvas (e.g. "a chat widget, inline, reference theme"); absent ⇒ the judge's own stand-in. */
   readonly hostLabel?: string;
+  /** How the card was composed on this frame (`resolveMountFit`, the one rule the runtime serves by); the sentence follows it. */
+  readonly fit: MountFit;
 }
 
 /** What the block carries besides the selected rows: the frame's box, and the props the card was rendered with. */
@@ -178,7 +194,10 @@ export const CRITERIA_PROPS_MAX_CHARS = 2000;
  */
 export function criteriaFrameLine(frame: CriteriaJudgeFrame): string {
   const box = `${frame.width}×${frame.height}`;
-  if (frame.canvas === 'xs-chat-card') {
+  if (frame.fit === 'framed-card') {
+    return `This frame is ${box}${frame.hostLabel !== undefined ? ` (${frame.hostLabel})` : ''} with the card at its natural height at the top, inside the card's own frame — its surface, a thin ring of its ink and rounded corners — on the host's ground: the card is sized to its content, so judge composition and space within the card's own extent, and read the ground round it as the host's, not the card's.`;
+  }
+  if (frame.fit === 'card') {
     const framedBy =
       frame.hostLabel !== undefined
         ? `inside the host's own frame (${frame.hostLabel}), on the host's ground`

package/src/evaluation/index.ts

@@ -11,8 +11,8 @@
 //   - `./types.js` — the post-eval result shape (`DimensionScores`,
 //     `EvaluationResult`, `EvaluationIssue`, `QualityMetadata`,
 //     `EvaluationConfig`, `EvaluationContext`).
-// Plus the runtime cluster (`runEvaluationLoop`, `runEvaluation`,
-// `runAxisChecks`, evaluator MCP server, prompts, message parsing).
+// Plus the runtime cluster (`runEvaluation`, `runAxisChecks`, score
+// arithmetic, prompts, message parsing).
 
 // Vocabulary the harness legs depend on (was: flat `packages/ui-gen/src/evaluation.ts`).
 export type {
@@ -55,10 +55,8 @@ export {
 } from './types-public.js';
 
 // Cloud-ported runtime cluster.
-export { runEvaluationLoop } from './loop.js';
-export type { EvaluationLoopOptions, EvaluationLoopResult } from './loop.js';
 export { runEvaluation } from './evaluator.js';
-export { createEvaluationToolsServer, computeEvaluationScore } from './mcp-server.js';
+export { computeEvaluationScore } from './mcp-server.js';
 export type { EvaluateScoreInput } from './mcp-server.js';
 export { getEvaluatorSystemPrompt, buildFixPrompt } from './prompts.js';
 export {

package/src/evaluation/mcp-server.ts

@@ -1,7 +1,5 @@
 // packages/ui-gen/src/evaluation/mcp-server.ts
 
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
 import type { EvaluationIssue, EvaluationResult } from './types';
 
 /**
@@ -51,51 +49,3 @@ export function computeEvaluationScore(
     ...(args.critique && { critique: args.critique }),
   };
 }
-
-/**
- * Create the evaluation MCP server with the evaluate_score tool.
- *
- * The evaluator LLM provides qualitative scores per dimension.
- * This tool handles the arithmetic (average, pass/fail) so the LLM
- * doesn't need to do math.
- */
-export function createEvaluationToolsServer(passThreshold = 70) {
-  return createSdkMcpServer({
-    name: 'eval-tools',
-    version: '1.0.0',
-    tools: [
-      tool(
-        'evaluate_score',
-        'Compute evaluation score from dimension ratings. Call this after analyzing the component code against all 5 dimensions.',
-        {
-          completeness: z.number().min(0).max(100).describe('Score for feature completeness (0-100)'),
-          visualPolish: z.number().min(0).max(100).describe('Score for visual polish and design (0-100)'),
-          interactivity: z.number().min(0).max(100).describe('Score for interactivity and state management (0-100)'),
-          accessibility: z.number().min(0).max(100).describe('Score for accessibility (ARIA, keyboard nav, contrast) (0-100)'),
-          codeQuality: z.number().min(0).max(100).describe('Score for code quality and structure (0-100)'),
-          issues: z.array(
-            z.object({
-              dimension: z.string().describe('Which dimension this issue affects'),
-              description: z.string().describe('What the issue is'),
-              severity: z.enum(['critical', 'major', 'minor']).describe('Issue severity'),
-              fix: z.string().describe('How to fix this issue'),
-            })
-          ).describe('List of specific issues found'),
-          critique: z.string().optional().describe('Optional overall critique summary'),
-        },
-        async (args) => {
-          const result = computeEvaluationScore(args, passThreshold);
-
-          return {
-            content: [
-              {
-                type: 'text',
-                text: JSON.stringify(result, null, 2),
-              },
-            ],
-          };
-        }
-      ),
-    ],
-  });
-}

package/src/evaluation/types-public.ts

@@ -477,7 +477,12 @@ export interface CriterionVerdict {
    * ggui#1663 — a measured reading beside a judge row, REPORT-ONLY: the row's `verdict` stays the judge's, so this
    * changes no verdict, score or bar. Present only on rows an instrument answers beside the judge (`space.edge`).
    */
-  instrument?: { verdict: CriteriaVerdict; evidence: string };
+  instrument?: { verdict: CriteriaVerdict; evidence: string; id?: string };
+  /**
+   * #1765 — the rewritten edge rule (`space.edge.v2`), a SEPARATE instrument read beside v1 on the same capture,
+   * REPORT-ONLY like `instrument`; `id` names the probe that produced it. Present only beside `space.edge`.
+   */
+  instrumentV2?: { verdict: CriteriaVerdict; evidence: string; id: string };
 }
 /** ggui#1687 — the criteria call as it came back: its answer's counts, ids it answered outside the bank, its stop. */
 export interface CriteriaCallRecord {

package/src/evaluation/visual-evaluator.ts

@@ -21,13 +21,13 @@ import type { CriteriaContextInput } from './criteria/context.js';
 import { selectCriteria } from './criteria/select.js';
 import { buildCriteriaJudgeBlock, resolveCriteriaBlock } from './criteria/resolve.js';
 import { build } from 'esbuild';
-import { EXPANDED_FRAME, expandedFramePanelRule, expandedFrameScrimDecls, fillFitRule, getCssTokens } from '@ggui-ai/design/rendering';
+import { EXPANDED_FRAME, FRAMED_CARD_GROUND, GGUI_MOUNT_CANVAS_EXPORT, mountFitCss, expandedFramePanelDecls, expandedFramePanelRule, expandedFrameScrimDecls, getCssTokens, inlineCardRadius, resolveMountFit, type MountFit } from '@ggui-ai/design/rendering';
 import { readInkExtent, type InkExtent } from './ink-extent.js';
 import { judgeDesignIdentity, type JudgeDesignIdentity } from './design-identity.js';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'node:module';
-import { existsSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'os';
 import { createVisionAgent, type AgentConfig, type VisionFinishReason } from '../harness/llm-router';
@@ -45,6 +45,8 @@ import type { LaunchOptions } from 'puppeteer-core';
 import { CANVAS_VIEWPORTS, displayModeForCanvas, type CanvasClass, type CanvasViewport } from '../design-mode.js';
 import { judgeEdges, type EdgeVerdict } from './criteria/edge.js';
 import { EDGE_BLOCKS_EXPRESSION, parseEdgeProbe } from './criteria/edge-probe.js';
+import { EDGE_BLOCKS_V2_EXPRESSION, parseEdgeProbeV2 } from './criteria/edge-probe-v2.js';
+import { judgeEdgesV2 } from './criteria/edge-v2.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -176,7 +178,12 @@ export interface CanvasVisualResult {
 }
 
 /** How a canvas is captured for the judge and what an overflow means there (ggui#1027). */
-export type CaptureMode = 'viewport' | 'full-page' | 'natural';
+/**
+ * How a canvas is captured. `card-box` (ggui#1953): a framed card (a chat-width card on a fullscreen surface,
+ * ggui#1924) is captured as the inline card is — its OWN box at its natural extent, plus the frame ground's margin on
+ * every side, ring and corners visible — never the pane round it, whose empty ground is the host's, not the card's.
+ */
+export type CaptureMode = 'viewport' | 'full-page' | 'natural' | 'card-box';
 export interface CanvasFitPolicy {
   /**
    * `viewport` = the whole box; `full-page` = the whole scrolled document; `natural` (ggui#1475) = the
@@ -501,8 +508,24 @@ export interface VisualEvalContext {
  * same place the harness's own imports come from.
  */
 export function resolveUiGenPackageDir(): string {
-  const selfDir = dirname(fileURLToPath(import.meta.url));
-  return resolve(selfDir, '..', '..');
+  // ggui#1769: found by walking up to this package's own manifest, never by counting directories. The code moves
+  // with the bundle's layout: under `src/evaluation/` and the old per-entry `dist/evaluation/` the package root
+  // was two levels up, but a shared chunk sits at `dist/` itself, one level up.
+  return findPackageRootAbove(dirname(fileURLToPath(import.meta.url)), '@ggui-ai/ui-gen');
+}
+
+/** The nearest directory at or above `start` whose `package.json` is named `name`; throws when there is none. */
+export function findPackageRootAbove(start: string, name: string): string {
+  for (let dir = start; ; dir = dirname(dir)) {
+    const manifest = resolve(dir, 'package.json');
+    if (existsSync(manifest) && readPackageName(manifest) === name) return dir;
+    if (dirname(dir) === dir) throw new Error(`${name}: no package.json named ${name} at or above ${start}`);
+  }
+}
+
+function readPackageName(manifest: string): string | undefined {
+  const parsed: unknown = JSON.parse(readFileSync(manifest, 'utf8'));
+  return typeof parsed === 'object' && parsed !== null && 'name' in parsed && typeof parsed.name === 'string' ? parsed.name : undefined;
 }
 
 /**
@@ -686,8 +709,11 @@ function buildRenderHTML(
   fit?: 'fill',
   chrome?: CanvasChrome,
   presentation?: CanvasHostPresentation,
+  /** Set for a `framed-card` mount: the card frame's radius ({@link inlineCardRadius}); `null` keeps the theme's `lg` token. */
+  framedCardRadiusPx?: number | null,
 ): string {
-  if (chrome === 'panel' && fit !== 'fill') throw new Error("the judge's panel frames a fill canvas only (ggui#1083 cut 3)");
+  const framedCard = framedCardRadiusPx !== undefined;
+  if (chrome === 'panel' && fit !== 'fill' && !framedCard) throw new Error("the judge's panel frames a fill canvas only (ggui#1083 cut 3)");
   if (chrome === 'ground' && fit === 'fill') throw new Error("the host ground frames an inline card only — a fill canvas has no natural height (ggui#1475)");
   // Default to the design tokens production's no-theme branch injects
   // (getCssTokens → default theme, light) — ggui#613: under the s4
@@ -714,12 +740,15 @@ 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) + (chrome === 'panel' ? expandedFramePanelRule(JUDGE_PANEL_CLASS, JUDGE_SCOPE_CLASS) : '') : ''}
+    ${/* ggui#1765 — the fit's rules come from the ONE selection the runtime's composeThemeCss uses. */ mountFitCss(JUDGE_SCOPE_CLASS, fit === 'fill' ? 'fill' : framedCard ? 'framed-card' : 'card', framedCardRadiusPx ?? null)}
+    ${fit === 'fill' && chrome === 'panel' ? expandedFramePanelRule(JUDGE_PANEL_CLASS, JUDGE_SCOPE_CLASS) : ''}
+    ${framedCard ? `.${JUDGE_PANEL_CLASS} { ${expandedFramePanelDecls()} background: ${FRAMED_CARD_GROUND}; display: flow-root; } body > .${JUDGE_PANEL_CLASS} { margin: ${EXPANDED_FRAME.insetPx}px; height: calc(100vh - ${2 * EXPANDED_FRAME.insetPx}px); }` : ''}
+    ${framedCard && chrome !== 'panel' ? `body { background: ${FRAMED_CARD_GROUND}; }` : ''}
     ${chrome === 'ground' ? `.${JUDGE_GROUND_CLASS} { padding: ${JUDGE_GROUND_MARGIN_PX}px; } .${JUDGE_INLINE_FRAME_CLASS} { ${inlineFrameDecls(presentation?.frame)} }` : ''}
   </style>
 </head>
 <body>
-  ${chrome === 'panel' ? `<div class="${JUDGE_PANEL_CLASS}">` : chrome === 'ground' ? `<div class="${JUDGE_GROUND_CLASS}"><div class="${JUDGE_INLINE_FRAME_CLASS}">` : ''}<div id="root"${fit === 'fill' ? ` class="${JUDGE_SCOPE_CLASS}"` : ''}></div>${chrome === 'panel' ? '</div>' : chrome === 'ground' ? '</div></div>' : ''}
+  ${chrome === 'panel' ? `<div class="${JUDGE_PANEL_CLASS}">` : chrome === 'ground' ? `<div class="${JUDGE_GROUND_CLASS}"><div class="${JUDGE_INLINE_FRAME_CLASS}">` : ''}<div id="root" class="${JUDGE_SCOPE_CLASS}"></div>${chrome === 'panel' ? '</div>' : chrome === 'ground' ? '</div></div>' : ''}
   <script type="importmap">
   {
     "imports": {
@@ -856,6 +885,8 @@ export interface ScreenshotAttempt {
    * probe failed. Absent on a failed capture.
    */
   readonly edge?: EdgeVerdict | null;
+  /** #1765 — the v2 edge rule on the same DOM, read beside `edge` (report-only); `null` when its probe failed. */
+  readonly edgeV2?: EdgeVerdict | null;
 }
 
 /** The expression the fit measurement evaluates in the page — the taller of the two scroll heights. */
@@ -902,6 +933,33 @@ export function naturalClip(window: { width: number; height: number }, cardHeigh
   return { x: 0, y: 0, width: window.width, height: Math.max(1, Math.min(Math.ceil(cardHeightPx), box)) + 2 * m };
 }
 
+/** The expression a card-box capture reads: the mount's own border box, in page CSS px (ggui#1953). */
+export const CARD_BOX_EXPRESSION = `(() => { const r = document.querySelector('.${JUDGE_SCOPE_CLASS}'); if (!r) return null; const b = r.getBoundingClientRect(); return { x: b.x, y: b.y, width: b.width, height: b.height }; })()`;
+
+async function measureCardBox(page: ScreenshotPage): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  try {
+    const v: unknown = await page.evaluate(CARD_BOX_EXPRESSION);
+    if (typeof v !== 'object' || v === null) return null;
+    const n = (k: string): number | null => { const x = Reflect.get(v, k); return typeof x === 'number' && Number.isFinite(x) ? x : null; };
+    const [x, y, width, height] = [n('x'), n('y'), n('width'), n('height')];
+    return x === null || y === null || width === null || height === null || width <= 0 || height <= 0 ? null : { x, y, width, height };
+  } catch (e) {
+    console.warn(`[visual-eval] card box unavailable: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+
+/**
+ * The card-box capture's region (ggui#1953): the card's own box with the frame ground's margin on every side, clamped
+ * to the window. The card is never cropped above its own bottom edge while the window can hold it.
+ */
+export function cardBoxClip(window: { width: number; height: number }, box: { x: number; y: number; width: number; height: number }): ScreenshotClip {
+  const m = JUDGE_GROUND_MARGIN_PX;
+  const x = Math.max(0, Math.floor(box.x - m));
+  const y = Math.max(0, Math.floor(box.y - m));
+  return { x, y, width: Math.min(window.width - x, Math.ceil(box.width + 2 * m)), height: Math.max(1, Math.min(window.height - y, Math.ceil(box.height + 2 * m))) };
+}
+
 /** Measure the rendered document's height (or the card's, for a natural capture); a failed measurement is reported, never a failed capture. */
 async function measureContentHeight(page: ScreenshotPage, expression: string = CONTENT_HEIGHT_EXPRESSION): Promise<number | null> {
   try {
@@ -917,7 +975,26 @@ async function measureContentHeight(page: ScreenshotPage, expression: string = C
  * ggui#1663 — read the edge rule off the page the screenshot is about to take. The probe only reads layout (it never
  * writes to the DOM), so the frame is unchanged; a failed read is reported and returns `null`, never a failed capture.
  */
-async function measureEdges(page: ScreenshotPage): Promise<EdgeVerdict | null> {
+async function measureEdges(page: ScreenshotPage): Promise<{ edge: EdgeVerdict | null; edgeV2: EdgeVerdict | null }> {
+  return { edge: await measureEdgesV1(page), edgeV2: await measureEdgesV2(page) };
+}
+
+/** #1765 — the v2 rule on the same page, beside v1; a failed read is reported and returns `null`, never a failed capture. */
+async function measureEdgesV2(page: ScreenshotPage): Promise<EdgeVerdict | null> {
+  try {
+    const probe = parseEdgeProbeV2(await page.evaluate(EDGE_BLOCKS_V2_EXPRESSION));
+    if (probe === null) {
+      console.warn('[visual-eval] edge probe v2 unavailable: the page returned no readable blocks');
+      return null;
+    }
+    return judgeEdgesV2(probe.blocks, { cardContent: probe.cardContent, placeholdersOnly: probe.placeholdersOnly });
+  } catch (e) {
+    console.warn(`[visual-eval] edge probe v2 unavailable: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+
+async function measureEdgesV1(page: ScreenshotPage): Promise<EdgeVerdict | null> {
   try {
     const probe = parseEdgeProbe(await page.evaluate(EDGE_BLOCKS_EXPRESSION));
     if (probe === null) {
@@ -969,14 +1046,26 @@ export async function captureScreenshotDetailed(
         }
         const framed = cardHeightPx === null ? viewport.height - 2 * natural.padPx : floorPx !== undefined ? Math.max(cardHeightPx, floorPx) : cardHeightPx;
         const clip = naturalClip(viewport, framed, natural.padPx);
-        const edge = await measureEdges(page);
+        const edges = await measureEdges(page);
         const screenshot = await page.screenshot({ type: 'png', fullPage: false, clip });
-        return { png: Buffer.from(screenshot), contentHeight: cardHeightPx, overflowX, edge };
+        return { png: Buffer.from(screenshot), contentHeight: cardHeightPx, overflowX, ...edges };
+      }
+      if (capture === 'card-box') {
+        // ggui#1953 — the card's own box (the mount, which wears the card frame), so a root that stretches itself still
+        // shows its void, and the host's empty ground below a short card is never in the frame.
+        const box = await measureCardBox(page);
+        // Fail closed, named: a card-box capture that cannot find the card's own box never falls back to the pane, which
+        // is the frame this capture exists to stop judging (and would read as the old defect, silently).
+        if (box === null) return { png: null, reason: `card-box capture: the card's own box (.${JUDGE_SCOPE_CLASS}) could not be measured`, contentHeight: null };
+        const clip = cardBoxClip(viewport, box);
+        const edges = await measureEdges(page);
+        const screenshot = await page.screenshot({ type: 'png', fullPage: false, clip });
+        return { png: Buffer.from(screenshot), contentHeight: Math.round(box.height), ...edges };
       }
       const contentHeight = await measureContentHeight(page);
-      const edge = await measureEdges(page);
+      const edges = await measureEdges(page);
       const screenshot = await page.screenshot({ type: 'png', fullPage: capture === 'full-page' });
-      return { png: Buffer.from(screenshot), contentHeight, edge };
+      return { png: Buffer.from(screenshot), contentHeight, ...edges };
     } finally {
       await browser.close();
     }
@@ -1137,9 +1226,29 @@ export interface VisualEvalDetailed {
  * ({@link runVisualFit}) frame through this ONE function, so a fit verdict
  * reached without the judge is taken on the frame the judge would have seen.
  */
+/**
+ * The canvas a compiled bundle declares in its {@link GGUI_MOUNT_CANVAS_EXPORT} export, read from the code as the runtime
+ * reads it from the module: the binding exported under that name (`export{r as gguiMountCanvas}` minified, or the plain
+ * `const gguiMountCanvas`) and its string literal. Untrusted: `resolveMountFit` narrows it, and anything unread is `undefined`.
+ */
+export function mountCanvasOf(compiledCode: string): string | undefined {
+  const name = GGUI_MOUNT_CANVAS_EXPORT;
+  const binding = new RegExp(`([A-Za-z_$][\\w$]*)\\s+as\\s+${name}\\b`).exec(compiledCode)?.[1] ?? name;
+  return new RegExp(`(?:^|[^\\w$.])${binding.replace(/\$/g, '\\$')}\\s*=\\s*"([^"\\\\]*)"`).exec(compiledCode)?.[1];
+}
+/** The `--ggui-*` custom properties a composed token block declares (the last declaration of a name wins, as in CSS). */
+function themeVarsOf(css: string): Readonly<Record<string, string>> {
+  const vars: Record<string, string> = {};
+  for (const [, name, value] of css.matchAll(/(--ggui-[\w-]+)\s*:\s*([^;}]+)/g)) {
+    if (name !== undefined && value !== undefined) vars[name] = value.trim();
+  }
+  return vars;
+}
 interface CanvasFrame {
   readonly viewport: CanvasViewport;
   readonly policy: CanvasFitPolicy;
+  /** How the runtime would compose this card on this canvas (`resolveMountFit`) — the capture and the frame statement follow it. */
+  readonly mountFit: MountFit;
   readonly fit: 'fill' | undefined;
   /** The host stand-in drawn round the scope (ggui#1083 cut 3) — the window is padded by its gap; `viewport` stays the card's box. */
   readonly chrome: CanvasChrome;
@@ -1174,7 +1283,6 @@ function blankVerdict(canvas: CanvasClass, frame: CanvasFrame): VisualIssue | nu
 async function frameCanvas(
   bundledCode: string,
   context: VisualEvalContext,
-  html: string,
   canvas: CanvasClass,
   canvasViewports: VisualEvalConfig['canvasViewports'],
   deps: ScreenshotDeps,
@@ -1182,27 +1290,48 @@ async function frameCanvas(
 ): Promise<CanvasFrame> {
   const declaredBox = canvasViewports?.[canvas];
   const viewport = declaredBox !== undefined ? integerBox(declaredBox) : CANVAS_VIEWPORTS[canvas];
-  const policy = canvasFitPolicy(canvas);
-  const fit = canvasFit(canvas);
+  // The ONE fit rule the runtime serves by: the bundle's canvas export + the display mode this canvas stands for.
+  const mountFit = resolveMountFit({ canvas: mountCanvasOf(context.compiledCode), displayMode: displayModeForCanvas(canvas) });
+  // ggui#1953 — the fit decides the overflow posture: a framed card is a card, seen whole in its room, so a card that
+  // cannot fit its pane fails the canvas as the inline card does (#1475), never scrolls as a page.
+  const policy: CanvasFitPolicy = mountFit === 'framed-card' ? { capture: 'card-box', overflow: 'fail' } : canvasFitPolicy(canvas);
+  const fit = mountFit === 'framed-card' ? undefined : canvasFit(canvas);
   const chrome = canvasChrome(canvas);
   const outcome = resolvePresentation(canvas, hostPresentations?.[canvas]);
   const presentation = outcome?.status === 'applied' ? outcome.applied : undefined;
   const geometry = inlineGeometry(presentation?.frame);
-  const canvasHtml =
-    fit !== undefined || chrome !== undefined ? buildRenderHTML(bundledCode, context.cssTokens, fit, chrome, presentation) : html;
-  const captured = await captureScreenshotDetailed(canvasHtml, judgeWindow(viewport, chrome, geometry.padPx), deps, policy.capture, {
+  const framedCardRadiusPx = mountFit === 'framed-card' ? inlineCardRadius(themeVarsOf(context.cssTokens ?? getCssTokens())).radiusPx : undefined;
+  // Every canvas's page is composed by the one builder, from this canvas's fit, chrome and frame: a framed card on a
+  // canvas with no chrome (the phone, ggui#1953) is still composed as the runtime serves it, never the plain page.
+  const canvasHtml = buildRenderHTML(bundledCode, context.cssTokens, fit, chrome, presentation, framedCardRadiusPx);
+  // ggui#1953 — a framed card is captured as a card, on its own box, at every canvas it is framed on.
+  const capture: CaptureMode = policy.capture;
+  const captured = await captureScreenshotDetailed(canvasHtml, judgeWindow(viewport, chrome, geometry.padPx), deps, capture, {
     padPx: geometry.padPx,
     ...(geometry.floorPx !== undefined ? { floorPx: geometry.floorPx } : {}),
   });
   // ggui#1083 cut 3 — on a panelled page the document is the panel plus its gap; every verdict reads the CARD's height.
-  const attempt: ScreenshotAttempt = { ...captured, contentHeight: cardHeight(captured.contentHeight, chrome) };
+  // A card-box capture already measured the card itself; only the full-page document carries the panel's gap.
+  const attempt: ScreenshotAttempt = { ...captured, contentHeight: capture === 'card-box' ? captured.contentHeight : cardHeight(captured.contentHeight, chrome) };
+  // A card-box frame has the inline card's geometry (margin, ring, corner), so its ink is read past the same inset.
+  const cardBoxInk = JUDGE_GROUND_MARGIN_PX + JUDGE_INLINE_FRAME_BORDER_PX + (framedCardRadiusPx ?? JUDGE_INLINE_FRAME_RADIUS_PX);
   return {
-    viewport, policy, fit, chrome, declared: declaredBox !== undefined, attempt,
-    ink: readInk(captured.png, chrome, canvas, geometry.inkInsetPx),
+    viewport, policy, mountFit, fit, chrome, declared: declaredBox !== undefined, attempt,
+    ink: capture === 'card-box' ? readInk(captured.png, 'ground', canvas, cardBoxInk) : readInk(captured.png, chrome, canvas, geometry.inkInsetPx),
     ...(outcome !== undefined ? { presentation: outcome } : {}),
   };
 }
 
+/**
+ * The box a frame's card must fit (ggui#1953): the canvas box, except for a framed card, which sits in its pane with
+ * the frame's gap above and below — so its ceiling is the pane less that gap on both sides (704 in a 736 pane).
+ */
+export function fitCeiling(frame: Pick<CanvasFrame, 'viewport' | 'mountFit'>): { width: number; height: number } {
+  return frame.mountFit === 'framed-card'
+    ? { width: frame.viewport.width, height: frame.viewport.height - 2 * EXPANDED_FRAME.insetPx }
+    : frame.viewport;
+}
+
 /**
  * The deterministic fit verdict on one frame (ggui#1027): the issue the
  * canvas's policy gives an overflow, or `null` when the content fits, could
@@ -1210,8 +1339,9 @@ async function frameCanvas(
  */
 function fitVerdict(canvas: CanvasClass, frame: CanvasFrame): VisualIssue | null {
   const contentHeight = frame.attempt.contentHeight;
-  if (contentHeight === null || contentHeight <= frame.viewport.height || frame.policy.overflow === 'none') return null;
-  return canvasOverflowIssue(canvas, frame.viewport, contentHeight, frame.policy.overflow);
+  const ceiling = fitCeiling(frame);
+  if (contentHeight === null || contentHeight <= ceiling.height || frame.policy.overflow === 'none') return null;
+  return canvasOverflowIssue(canvas, ceiling, contentHeight, frame.policy.overflow);
 }
 
 /**
@@ -1471,7 +1601,7 @@ export async function runVisualEvaluationDetailed(
     const perCanvas: CanvasVisualResult[] = [];
     const perCanvasResults: EvaluationResult[] = [];
     for (const canvas of config.canvases) {
-      const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps, config.hostPresentations);
+      const frame = await frameCanvas(bundledCode, context, canvas, config.canvasViewports, deps, config.hostPresentations);
       const { viewport, policy, fit, attempt } = frame;
       const screenshot = attempt.png;
       if (!screenshot) {
@@ -1490,7 +1620,7 @@ export async function runVisualEvaluationDetailed(
       const criteriaBlock =
         context.criteria !== undefined && criteriaSelected !== undefined
           ? buildCriteriaJudgeBlock(context.criteria.bank, criteriaSelected, {
-              frame: { canvas, width: viewport.width, height: viewport.height, ...(frame.presentation?.status === 'applied' ? { hostLabel: frame.presentation.applied.label } : {}) },
+              frame: { canvas, width: viewport.width, height: viewport.height, fit: frame.mountFit, ...(frame.presentation?.status === 'applied' ? { hostLabel: frame.presentation.applied.label } : {}) },
               ...(config.sampleProps !== undefined ? { propsJson: JSON.stringify(config.sampleProps) } : {}),
             })
           : '';
@@ -1541,7 +1671,7 @@ export async function runVisualEvaluationDetailed(
               context: criteriaContext,
               selected: criteriaSelected,
               answers: criteriaReads(criteriaAnswer),
-              measurements: { overflow, contentHeight, viewportHeight: viewport.height, inkRatio, edge: attempt.edge ?? null },
+              measurements: { overflow, contentHeight, viewportHeight: viewport.height, inkRatio, edge: attempt.edge ?? null, edgeV2: attempt.edgeV2 ?? null },
               ...criteriaUnansweredReason(criteriaAnswer),
               ...criteriaCallOf(criteriaAnswer),
             })
@@ -1736,6 +1866,8 @@ export function summarizeVisualResult(result: VisualEvaluationResult): VisualEva
 
 /** One stored capture to judge: the frame the judge saw at capture time, plus what the capture measured. */
 export interface StoredCaptureInput {
+  /** How the stored capture was composed. Absent ⇒ the canvas's composition before mount fits existed (`fill` on a fullscreen canvas, else `card`). */
+  readonly mountFit?: MountFit;
   readonly canvas: CanvasClass;
   /** The capture as saved (`canvas-<class>.png`). */
   readonly png: Buffer;
@@ -1800,7 +1932,7 @@ export async function judgeStoredCapture(
   const criteriaBlock =
     input.criteria !== undefined && criteriaSelected !== undefined
       ? buildCriteriaJudgeBlock(input.criteria.bank, criteriaSelected, {
-          frame: { canvas, width: viewport.width, height: viewport.height },
+          frame: { canvas, width: viewport.width, height: viewport.height, fit: input.mountFit ?? (canvasFit(canvas) === 'fill' ? 'fill' : 'card') },
           ...(input.sampleProps !== undefined ? { propsJson: JSON.stringify(input.sampleProps) } : {}),
         })
       : '';
@@ -2151,11 +2283,10 @@ export async function runVisualFit(
   } catch (e) {
     return { status: 'unavailable', reason: `bundle failed: ${e instanceof Error ? e.message : String(e)}` };
   }
-  const html = buildRenderHTML(bundledCode, context.cssTokens);
   const issues: EvalIssue[] = [];
   const readings: CanvasFitReading[] = [];
   for (const canvas of config.canvases) {
-    const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps, config.hostPresentations);
+    const frame = await frameCanvas(bundledCode, context, canvas, config.canvasViewports, deps, config.hostPresentations);
     if (!frame.attempt.png) {
       return { status: 'unavailable', reason: `${frame.attempt.reason ?? 'no browser available'} at canvas ${canvas}` };
     }

package/src/harness/check/runtime-render/index.ts

@@ -90,6 +90,28 @@ export async function warmupRuntimeRenderProbe(): Promise<{
  */
 const WARMUP_COMPONENT = "export default function Warmup() { return <div>warm</div>; }";
 
+/**
+ * Why a worker warm-up failed (ggui#1839), one kind per exit of
+ * {@link warmupRuntimeRenderWorker}:
+ *
+ * - `incomplete`: the check started and ran out of its bound before it
+ *   finished. The worker may be fine and the machine slow (a cold node's
+ *   first spawn); it says nothing about whether a check can pass.
+ * - `blocking`: the check ran to an end and reported a `failed` or
+ *   `unverified` issue: the worker cannot render a trivial component.
+ * - `spawn`: the spawn layer refused to run the worker at all (an invalid
+ *   bound, a missing binary).
+ *
+ * Branch on this, never on `reason`, which is prose for a human.
+ */
+export const RUNTIME_RENDER_WARMUP_FAILURE_KINDS = ["incomplete", "blocking", "spawn"] as const;
+export type RuntimeRenderWarmupFailureKind = (typeof RUNTIME_RENDER_WARMUP_FAILURE_KINDS)[number];
+
+/** The result of {@link warmupRuntimeRenderWorker}. */
+export type RuntimeRenderWorkerWarmup =
+  | { ok: true; ms: number }
+  | { ok: false; ms: number; kind: RuntimeRenderWarmupFailureKind; reason: string };
+
 /**
  * Warm the PROCESS that runs every probe (ggui#1380): spawn one real check
  * worker on a trivial component through the same host every probe uses.
@@ -100,12 +122,12 @@ const WARMUP_COMPONENT = "export default function Warmup() { return <div>warm</d
  *
  * `bounds` are the subprocess bounds for the one run; a serving deployment
  * passes the same bounds it will probe with. Never throws: a worker that
- * cannot run is `{ ok: false, reason }`, so a boot sequence can log it and
- * decide, instead of dying in a fire-and-forget.
+ * cannot run is `{ ok: false, kind, reason }`, so a boot sequence can log
+ * it and decide by `kind`, instead of dying in a fire-and-forget.
  */
 export async function warmupRuntimeRenderWorker(
   bounds?: Partial<RenderCheckHostBounds>
-): Promise<{ ok: true; ms: number } | { ok: false; ms: number; reason: string }> {
+): Promise<RuntimeRenderWorkerWarmup> {
   const start = Date.now();
   try {
     // Lazy: the host pulls `@ggui-ai/sandbox` (spawn machinery); keep it off
@@ -120,6 +142,7 @@ export async function warmupRuntimeRenderWorker(
       return {
         ok: false,
         ms,
+        kind: "incomplete",
         reason: `the warm-up check did not finish within ${result.incomplete.boundMs} ms (stopped at ${result.incomplete.elapsedMs} ms)`,
       };
     }
@@ -127,7 +150,7 @@ export async function warmupRuntimeRenderWorker(
       (i) => i.outcome === "failed" || i.outcome === "unverified"
     );
     if (blocking !== undefined) {
-      return { ok: false, ms, reason: `${blocking.check} ${blocking.outcome}: ${blocking.reason}` };
+      return { ok: false, ms, kind: "blocking", reason: `${blocking.check} ${blocking.outcome}: ${blocking.reason}` };
     }
     return { ok: true, ms };
   } catch (err) {
@@ -136,6 +159,7 @@ export async function warmupRuntimeRenderWorker(
     return {
       ok: false,
       ms: Date.now() - start,
+      kind: "spawn",
       reason: err instanceof Error ? err.message : String(err),
     };
   }