@ggui-ai/ui-gen 0.20.0 → 0.21.0

package/dist/workflows.d.ts

@@ -2,7 +2,7 @@ import { C as Classification } from './axes-CzLEMDeB.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './styling-profile-CxfvV48g.js';
-import './types-public-DKR_h70H.js';
+import './types-public-CzYqZclY.js';
 import './design-mode-DLufhrNp.js';
 import './types-BOvHNG7K.js';
 import './llm.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -185,12 +185,13 @@
   "peerDependencies": {
     "@google/adk": "^2.0.0",
     "@openai/agents": "^0.17.0",
+    "@sparticuz/chromium": "^149.0.0",
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/project-config": "0.20.0",
-    "@ggui-ai/mcp-server-core": "0.20.0",
-    "@ggui-ai/protocol": "0.20.0"
+    "@ggui-ai/protocol": "0.21.0",
+    "@ggui-ai/mcp-server-core": "0.21.0",
+    "@ggui-ai/project-config": "0.21.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -199,6 +200,9 @@
     "@openai/agents": {
       "optional": true
     },
+    "@sparticuz/chromium": {
+      "optional": true
+    },
     "puppeteer-core": {
       "optional": true
     },
@@ -229,11 +233,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/gadgets": "0.20.0",
-    "@ggui-ai/design": "0.20.0",
-    "@ggui-ai/sandbox": "0.20.0",
-    "@ggui-ai/ui-visual-tester": "0.20.0",
-    "@ggui-ai/wire": "0.20.0"
+    "@ggui-ai/design": "0.21.0",
+    "@ggui-ai/gadgets": "0.21.0",
+    "@ggui-ai/sandbox": "0.21.0",
+    "@ggui-ai/ui-visual-tester": "0.21.0",
+    "@ggui-ai/wire": "0.21.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -248,9 +252,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/project-config": "0.20.0",
-    "@ggui-ai/protocol": "0.20.0",
-    "@ggui-ai/mcp-server-core": "0.20.0"
+    "@ggui-ai/mcp-server-core": "0.21.0",
+    "@ggui-ai/project-config": "0.21.0",
+    "@ggui-ai/protocol": "0.21.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/base.ts

@@ -14,6 +14,13 @@ export interface AdapterConfig {
   apiKey?: string;
   /** Use Bedrock instead of direct API (Claude only) */
   useBedrock?: boolean;
+  /**
+   * ggui#1185 — run on the machine's own Claude Code login instead of a key.
+   * Claude SDK adapter only. The adapter strips every provider key from the
+   * spawned env and pins the run tool-less, config-less and non-bare (see
+   * `claude/claude-code-login.ts`). Opt-in; absent ⇒ key-based auth.
+   */
+  claudeCodeLogin?: boolean;
   /**
    * Thinking level for models with extended thinking (Gemini 3.x Flash
    * via the Interactions API). Mirrors the API's `thinking_level` enum —
@@ -129,5 +136,6 @@ export function hasCredentials(
 ): boolean {
   if (config.apiKey) return true;
   if (config.useBedrock) return true;
+  if (config.claudeCodeLogin) return true;
   return envVarNames.some((name) => !!process.env[name]);
 }

package/src/adapters/claude/claude-code-login.ts

@@ -0,0 +1,73 @@
+/**
+ * ggui#1185 — generation through the machine's own Claude Code login.
+ *
+ * The Claude SDK adapter spawns the Claude Code binary. Given no provider
+ * key, that binary authenticates with whatever `claude` is logged in as on
+ * the machine — the operator's own plan. This module holds the three
+ * things that make such a run honest and reproducible:
+ *
+ *   1. {@link CLAUDE_CODE_LOGIN_CREDENTIAL} — the sentinel a `ProviderKeyRef`
+ *      carries in place of a key, the same shape `bedrock-iam` already uses
+ *      for "authenticate with ambient credentials, not a key I hold".
+ *   2. {@link stripProviderKeyEnv} — no provider key may reach the spawned
+ *      process: the binary prefers an env key over its login, so a stale
+ *      `ANTHROPIC_API_KEY` would silently take the run off the login path.
+ *   3. {@link claudeCodeLoginQueryOptions} — the SDK options that keep the
+ *      run bounded: no built-in tool (`tools: []`), no `~/.claude` settings,
+ *      hooks or MCP servers leaking in (`settingSources: []`). Not
+ *      `--bare`, either: on the SDK's bundled binary `-p` reads the login
+ *      store as it always has, so no flag is needed — and the flag it
+ *      would be (`--no-bare`) is one that binary rejects; see the note on
+ *      the function below.
+ *
+ * Opt-in, off by default; the default stays a provider key. The copy that
+ * names what this does lives with the CLI flag that enables it.
+ */
+
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+
+/** Sentinel credential: "no key — use the machine's Claude Code login". */
+export const CLAUDE_CODE_LOGIN_CREDENTIAL = "claude-code-login" as const;
+
+/**
+ * Every env name the spawned binary would read as a credential or an
+ * endpoint override ahead of its login. Stripped whole, never rewritten.
+ */
+export const PROVIDER_KEY_ENV_NAMES = [
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+] as const;
+
+/** A copy of `env` without any provider key or endpoint override. */
+export function stripProviderKeyEnv(
+  env: Readonly<Record<string, string | undefined>>
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const drop: ReadonlySet<string> = new Set(PROVIDER_KEY_ENV_NAMES);
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined && !drop.has(k)) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * The SDK `query()` options a login-path run is pinned to — typed as the
+ * SDK's own `Options` members, so a change in the SDK's shape is a compile
+ * error here and never a silently ignored key.
+ *
+ * NOT pinned: `--no-bare`. The SDK spawns its BUNDLED binary (2.1.229 for
+ * SDK 0.3.229), which has no bare mode and rejects the flag outright
+ * (`error: unknown option '--no-bare'`, measured 2026-09-21 on the first
+ * live turn of the login client); the machine's own `claude` (2.1.274)
+ * accepts it, which is where the earlier probe measured it. On the
+ * bundled binary `-p` reads the login store as it always has. If a later
+ * SDK bundles a binary where bare becomes the `-p` default, the flag
+ * comes back here — with the SDK version bump, measured again.
+ */
+export type ClaudeCodeLoginQueryOptions = Required<Pick<Options, "tools" | "settingSources">>;
+
+export function claudeCodeLoginQueryOptions(): ClaudeCodeLoginQueryOptions {
+  return { tools: [], settingSources: [] };
+}

package/src/adapters/claude/sdk.ts

@@ -13,6 +13,7 @@ import type { ClaudeSdkConfig, GenerateParams } from '../base';
 import type { AdapterResult, ProviderName, AdapterMode } from '../types';
 import { createArtifacts, processMessage } from './message-parser';
 import { createToolMcpServer } from './tool-bridge';
+import { claudeCodeLoginQueryOptions, stripProviderKeyEnv } from './claude-code-login';
 
 export class ClaudeSdkAdapter extends GeneratorAdapter {
   readonly provider: ProviderName = 'claude';
@@ -40,7 +41,11 @@ export class ClaudeSdkAdapter extends GeneratorAdapter {
     const { query } = await import('@anthropic-ai/claude-agent-sdk');
 
     // Build environment from config or process.env
-    const env = buildEnv(cfg.env);
+    // ggui#1185 — on the login path no provider key may reach the binary:
+    // it prefers an env key over its login, so a stale one would take the
+    // run off this path without a word.
+    const login = cfg.claudeCodeLogin === true;
+    const env = login ? stripProviderKeyEnv(buildEnv(cfg.env)) : buildEnv(cfg.env);
 
     const artifacts = createArtifacts();
     const onProgress = cfg.onProgress;
@@ -72,6 +77,8 @@ export class ClaudeSdkAdapter extends GeneratorAdapter {
         allowDangerouslySkipPermissions: true,
         ...(cfg.cliPath && { pathToClaudeCodeExecutable: cfg.cliPath }),
         ...(cfg.stderr && { stderr: cfg.stderr }),
+        // ggui#1185 — tool-less, config-less, non-bare; the model is pinned above.
+        ...(login ? claudeCodeLoginQueryOptions() : {}),
       },
     })) {
       processMessage(

package/src/adapters/generation-dispatch.ts

@@ -102,6 +102,12 @@ export interface GenerationDispatchParams {
      * today's single screenshot at `viewport`.
      */
     canvases?: readonly CanvasClass[];
+    /**
+     * ggui#1195 — per-canvas viewport override for the in-loop round: the
+     * box the composer targeted (`rendering.viewport`) so the round judges
+     * the same box. See `VisualEvalConfig.canvasViewports`.
+     */
+    canvasViewports?: Partial<Readonly<Record<CanvasClass, { width: number; height: number }>>>;
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;
@@ -179,7 +185,12 @@ export interface GenerationDispatchParams {
    * means `constrained` (byte-identical to the pre-`designMode` path).
    */
   designMode?: DesignMode;
-  /** Rendering canvas class for the `free` prompt — see `CreateHarnessInput.canvas`. */
+  /**
+   * Rendering canvas class — see `CreateHarnessInput.canvas`. Absent, the
+   * harness derives it from `shellType` × `screen` (ggui#1117), so the axis
+   * checks always judge for the canvas the generation renders on; the
+   * `free` prompt renders it, the constrained prompt ignores it.
+   */
   canvas?: CanvasClass;
   /** The app's generation profile (#991). */
   profile?: GenerationProfileInput;
@@ -296,7 +307,13 @@ export async function dispatchGeneration(
       : {}),
     // Design mode + canvas — the harness carries them to every leg.
     ...(params.designMode !== undefined ? { designMode: params.designMode } : {}),
-    ...(params.canvas !== undefined ? { canvas: params.canvas } : {}),
+    // ggui#1117 — the canvas is ALWAYS carried: a stated one, else the class
+    // shell × screen renders on. The axis checks judge for it
+    // (`universal.root_width_cap` stands down without one — which is what every
+    // served generation got, since the serving runtime states no canvas); the
+    // constrained prompt ignores it (INVARIANT 1, `design-mode.pin.test.ts`),
+    // so the prompt digests do not move; the free prompt renders it as before.
+    canvas: params.canvas ?? canvasForRendering(params.shellType, params.screen),
     ...(params.profile !== undefined ? { profile: params.profile } : {}),
     // Policy is pre-resolved at the dispatch boundary so `createHarness`
     // stays free of experiment plumbing. `resolveHarnessPolicy` applies

package/src/adapters/openai/tokens.ts

@@ -31,6 +31,24 @@ export function splitOpenAiUsage(
   inputTokensInclCached: number,
   outputTokens: number,
   cachedTokens: number,
+): { tokens: AdapterResult['tokens']; cacheReadTokens: number } {
+  return splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens);
+}
+
+/**
+ * The provider-neutral form of the split above (ggui#1186, third site): any
+ * provider whose reported input token count INCLUDES the cached part of the
+ * prompt — OpenAI's `input_tokens` + `input_tokens_details.cached_tokens`,
+ * Gemini's `total_input_tokens` + `total_cached_tokens` and
+ * `promptTokenCount` + `cachedContentTokenCount` ("the cached part of the
+ * prompt", per the SDK) — is split the same way into the non-cached input and
+ * the cached subset, so `input` is never double-counted and `total` stays the
+ * full footprint.
+ */
+export function splitCacheInclusiveUsage(
+  inputTokensInclCached: number,
+  outputTokens: number,
+  cachedTokens: number,
 ): { tokens: AdapterResult['tokens']; cacheReadTokens: number } {
   // Never let a malformed usage report drive input negative.
   const cacheRead = Math.min(

package/src/adapters/provider-router.ts

@@ -12,6 +12,7 @@
 // legacy) still needs the wire-canonical anthropic id → cross-region
 // profile id upcast.
 
+import { CLAUDE_CODE_LOGIN_CREDENTIAL, PROVIDER_KEY_ENV_NAMES } from './claude/claude-code-login';
 import type { LlmRoute } from '@ggui-ai/protocol';
 
 /**
@@ -58,6 +59,13 @@ export function getBedrockModelId(model: string): string {
 }
 
 export interface RoutingDecision {
+  /**
+   * Named only for the Claude Code login path (ggui#1185): the caller passed
+   * {@link CLAUDE_CODE_LOGIN_CREDENTIAL} as the key, every provider key is
+   * cleared from the env below, and the adapter pins the SDK options that keep
+   * the run tool-less, config-less and non-bare. Absent ⇒ key-based auth.
+   */
+  readonly auth?: 'claude-code-login';
   /**
    * Upstream model id the dispatch adapter will pass to the provider
    * SDK. For most routes this is `route.model` verbatim — the typed
@@ -143,6 +151,13 @@ function clearSiblings(
  */
 export function resolveRoute(input: RoutingInput): RoutingDecision {
   const { route, apiKey, env } = input;
+  if (apiKey === CLAUDE_CODE_LOGIN_CREDENTIAL && route.provider !== 'anthropic') {
+    throw new Error(
+      `${route.provider}:${route.model} cannot use the claude-code-login credential — ` +
+        `the machine's Claude Code login authenticates the Claude Code binary only; ` +
+        `pick an anthropic route or supply a ${route.provider} API key.`,
+    );
+  }
 
   switch (route.provider) {
     case 'openai': {
@@ -215,6 +230,19 @@ export function resolveRoute(input: RoutingInput): RoutingDecision {
     }
 
     case 'anthropic': {
+      if (apiKey === CLAUDE_CODE_LOGIN_CREDENTIAL) {
+        // ggui#1185: no key reaches the spawned binary — it authenticates with
+        // the machine's own Claude Code login. Every provider key AND every
+        // sibling is cleared, because the binary prefers an env key over its
+        // login and a stale one would silently take the run off this path.
+        const cleared: Record<string, undefined> = {};
+        for (const k of PROVIDER_KEY_ENV_NAMES) cleared[k] = undefined;
+        return {
+          model: route.model,
+          env: { ...cleared, ...clearSiblings(new Set()) },
+          auth: 'claude-code-login',
+        };
+      }
       if (apiKey) {
         return {
           model: route.model,

package/src/boilerplate/generate.ts

@@ -246,8 +246,20 @@ export function generateBoilerplate(
     }
 
     const toolNote = tool ? ` (label "${label}", nextStep hint → ${tool})` : "";
+    // ggui#1190: the control's copy is the contract's label, VERBATIM — stated for
+    // EVERY action (it used to appear only beside a `nextStep` hint), because the
+    // model given `"Confirm & Schedule"` in the contract block wrote
+    // `'Confirm Schedule'`. The rule lives in DATA_PARAMETERIZATION rule 4; this is
+    // its reminder beside the action, and the axis check
+    // `universal.action_label_dropped` names the drop when both are ignored.
+    // ggui#1244: it rides the payload type's doc comment, NOT the hook line. Placed
+    // on the hook line directly before the once-hint below, the two read as the
+    // control's spec and gemini-3.5-flash-lite guarded the repeatable Save 8/8;
+    // here, with the hook line back to its earlier bytes, 5/24 — within noise of
+    // the rate before either hint moved (1/8) — while one-time commitments stayed
+    // guarded 40/40 across three providers and every label stayed verbatim (Exp 009).
     actionTypeAliases.push(
-      `/** Action payload: ${desc || label}${toolNote} */\ntype ${typeName} = ${tsType};`
+      `/** Action payload: ${desc || label}${toolNote} — control copy: "${label}" VERBATIM */\ntype ${typeName} = ${tsType};`
     );
     // Inline signature tells the LLM exactly how to call this action
     const callSig = tsType === "void" ? "() => void — fire and forget" : `(data: ${tsType}) => void`;
@@ -255,9 +267,12 @@ export function generateBoilerplate(
     // ggui#1108 (mitigation): the reminder sits at the EXACT site the model
     // writes the handler. It is a hint, not the rule — the rule is the prompt's
     // `TERMINAL_ACTIONS` section, because only the request and the contract say
-    // which actions are meant once. A site comment alone moves generation by
-    // roughly nothing (Exp 002b: adoption 1/36), which is why it is the
-    // smallest of the three legs and never the one relied on.
+    // which actions are meant once. It is NOT inert, whatever Exp 002b measured
+    // for a different site comment (adoption 1/36): Exp 009 (ggui#1244) removed
+    // it and one-time scheduling went armed on all three providers (guarded 9/12
+    // against 24/24), and a second hint placed beside it turned it into an
+    // instruction for every action. So it stays, ALONE on the hook line — what
+    // sits next to it is part of what it says.
     const onceHint = " — if this is meant ONCE, disable its control after it fires";
     actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
     actionReturnFields.push(key);

package/src/boilerplate/hard-sections.ts

@@ -213,7 +213,7 @@ Rules:
 1. All request-specific data → props with defaults. City names, tickers, user names, dates, counts.
 2. Layout and styling are universal. Colors, spacing, structure — these are the reusable part.
 3. Default values come from the current request — so the component renders correctly standalone.
-4. Copy comes from the props. NEVER invent display text the contract does not carry — no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** — not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` — UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it.
+4. Copy comes from the props. NEVER invent display text the contract does not carry — no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** — not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` — UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it. An action's control shows the contract's \`label\` VERBATIM — every character, including \`&\`, \`/\`, \`–\` and quotes — never paraphrased, shortened or re-cased (\`"Confirm & Schedule"\` is not \`"Confirm Schedule"\`).
 5. Props interface must be typed and exported.`;
 
 /**

package/src/create-ui-generator.ts

@@ -298,16 +298,25 @@ export function createUiGenerator(
       // structurally into the dispatch call instead. `route.env`
       // already carries exactly the key(s) that would have gone into
       // `process.env`, so no extra resolution work is needed here.
-      const routeOverride = disableEnvMutation
-        ? {
-            apiKey:
-              route.env['ANTHROPIC_API_KEY'] ??
-              route.env['OPENAI_API_KEY'] ??
-              route.env['GEMINI_API_KEY'] ??
-              route.env['OPENROUTER_API_KEY'],
-            useBedrock: route.env['CLAUDE_CODE_USE_BEDROCK'] === '1',
-          }
-        : undefined;
+      //
+      // ggui#1185 — the login path has NO key to write anywhere: the
+      // route decision `auth: 'claude-code-login'` is carried as
+      // `routeOverride.claudeCodeLogin` in BOTH env modes, because the
+      // flag is the only way the decision reaches `createAgent` /
+      // `createVisionAgent` (which select the login client on it).
+      const routeOverride =
+        route.auth === 'claude-code-login'
+          ? { claudeCodeLogin: true }
+          : disableEnvMutation
+            ? {
+                apiKey:
+                  route.env['ANTHROPIC_API_KEY'] ??
+                  route.env['OPENAI_API_KEY'] ??
+                  route.env['GEMINI_API_KEY'] ??
+                  route.env['OPENROUTER_API_KEY'],
+                useBedrock: route.env['CLAUDE_CODE_USE_BEDROCK'] === '1',
+              }
+            : undefined;
 
       try {
         const tools = createGeneratorTools({

package/src/evaluation/design-identity.ts

@@ -14,7 +14,7 @@
 // that carries the same rendering inputs.
 import { createHash } from 'node:crypto';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { relative, resolve } from 'node:path';
 
 export interface JudgeDesignIdentity {
   /** Absolute path of the design `src` tree the judge bundled against. */
@@ -37,20 +37,31 @@ export function isDesignRenderingInput(relativePath: string): boolean {
   return true;
 }
 
-/** sha256 over every rendering input under `root` (sorted relative path + contents) — the identity of a design tree as it paints. */
+/**
+ * sha256 over every rendering input under `root` (sorted relative path +
+ * contents) — the identity of a design tree as it paints.
+ *
+ * A function of the TREE, not of the spelling of `root`: the relative keys
+ * are taken against the RESOLVED root, so `…/design/src`, `…/design/src/` and
+ * `…/ui-gen/../design/src` hash the same bytes. Before this the key was
+ * sliced by the unresolved root's length while each entry had already been
+ * resolved, so an un-normalised root produced a different hash for the same
+ * tree — a phantom design skew for any caller composing the path.
+ */
 export function designTreeSha256(root: string): string {
+  const base = resolve(root);
   const files: string[] = [];
   const walk = (dir: string): void => {
     for (const name of readdirSync(dir).sort()) {
       const full = resolve(dir, name);
       if (statSync(full).isDirectory()) walk(full);
-      else if (isDesignRenderingInput(full.slice(root.length + 1))) files.push(full);
+      else if (isDesignRenderingInput(relative(base, full))) files.push(full);
     }
   };
-  walk(root);
+  walk(base);
   const h = createHash('sha256');
   for (const f of files) {
-    h.update(f.slice(root.length + 1) + '\n');
+    h.update(relative(base, f) + '\n');
     h.update(readFileSync(f));
     h.update('\n');
   }

package/src/evaluation/types-public.ts

@@ -123,6 +123,24 @@ export interface CriterionCoverage {
   readonly reason?: string;
 }
 
+/**
+ * Coverage of the screenshot JUDGE leg for one eval round (ggui#1221) — a
+ * different surface from the `visual` CRITERION in `criteriaCoverage` (the
+ * LLM evaluator's read of the source). `ran` = a frame was captured and
+ * judged; `skipped` = the leg was configured but produced no verdict
+ * (no browser, a launch or in-page failure, an unbundlable component, an
+ * unparsable judge answer) with `reason` naming why; `not-applicable` =
+ * the round had no visual leg configured. Before this row a skipped leg
+ * left NO trace on the result — `{ issues: [] }` read exactly like a
+ * clean run, and every bootstrap mint on a browserless runtime "passed"
+ * its visual round that way.
+ */
+export interface VisualCoverage {
+  readonly status: CriterionRunStatus;
+  /** Populated for `skipped` / `not-applicable` — why no verdict. */
+  readonly reason?: string;
+}
+
 /**
  * The static criteria `runLLMEvaluation` runs, in stamp order — the
  * ONE list both the evaluator's coverage stamp and the harness's
@@ -185,6 +203,13 @@ export interface EvalResult {
    * never here — this object is serialized into reports.
    */
   visual?: VisualEvalSummary;
+  /**
+   * Whether the screenshot judge leg ran, was skipped (with the reason) or
+   * was not configured — ALWAYS stamped by the harness's eval round
+   * (ggui#1221), so a consumer can tell a clean visual run from a leg
+   * that silently could not run. See {@link VisualCoverage}.
+   */
+  visualCoverage?: VisualCoverage;
 }
 
 /** One canvas's visual verdict, PNG-free — see `EvalResult.visual`. */
@@ -227,6 +252,21 @@ export interface CanvasVisualSummary {
   fit?: 'fill';
 }
 
+/**
+ * ggui#1195 — the fit reading on the canvas whose policy FAILS an overflow
+ * (the inline chat card): the box it was judged at (`ceiling` — the order's
+ * declared viewport when one was carried, else the class box), whether that
+ * box was declared, and how many px of content sit below it (0 = fits).
+ * Present only when such a canvas was judged with a measurable height, so
+ * the bar and the ledger read one number for "does the hello fit".
+ */
+export interface VisualFitStamp {
+  readonly canvas: CanvasClass;
+  readonly ceiling: { readonly width: number; readonly height: number };
+  readonly declared: boolean;
+  readonly overflowPx: number;
+}
+
 /** The visual leg's per-canvas summary — see `EvalResult.visual`. */
 export interface VisualEvalSummary {
   /** Mean of the canvas scores (rounded). */
@@ -234,6 +274,8 @@ export interface VisualEvalSummary {
   /** Every canvas passed. */
   passed: boolean;
   canvases: CanvasVisualSummary[];
+  /** ggui#1195 — see {@link VisualFitStamp}; absent when no fail-policy canvas was judged. */
+  fit?: VisualFitStamp;
   /** The design tree the judge painted with (ggui#1042): `src` + `srcSha256` — `design@judge`. */
   design?: { readonly src: string; readonly srcSha256: string };
   /** The mode the judge's tokens were composed in, when the caller said (ggui#1076). */