@ggui-ai/ui-gen 0.20.0 → 0.22.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-mM_-1Yk3.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.22.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/mcp-server-core": "0.22.0",
+    "@ggui-ai/project-config": "0.22.0",
+    "@ggui-ai/protocol": "0.22.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.22.0",
+    "@ggui-ai/sandbox": "0.22.0",
+    "@ggui-ai/gadgets": "0.22.0",
+    "@ggui-ai/ui-visual-tester": "0.22.0",
+    "@ggui-ai/wire": "0.22.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.22.0",
+    "@ggui-ai/project-config": "0.22.0",
+    "@ggui-ai/protocol": "0.22.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,128 @@
+/**
+ * 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 loginChildEnv} — the spawned process sees an ALLOWLIST of the
+ *      parent's env, never the parent's env minus a few names: no provider
+ *      key (the binary prefers an env key over its login, so a stale
+ *      `ANTHROPIC_API_KEY` would silently take the run off the login path),
+ *      no other secret the parent merely holds, and no switch that would
+ *      change what the binary does (ggui#1278).
+ *   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;
+
+/**
+ * The only env names the login child inherits (ggui#1278), plus every
+ * `LC_*` locale name. The spawned binary sees a property of this code, not
+ * whatever the parent happened to load: a parent that sourced a whole
+ * `.env` holds every provider's key, and a denylist would pass all of them
+ * on, together with switches such as `CLAUDE_CODE_USE_BEDROCK` that would
+ * silently re-route the run.
+ *
+ * - Process basics: `PATH` (the binary runs helpers, e.g. the macOS
+ *   keychain tool), `HOME`/`USER`/`LOGNAME` (where and whose the login
+ *   store is), `SHELL`, temp dirs, `TERM`, `TZ`, locale.
+ * - Where the login lives: `CLAUDE_CONFIG_DIR`, the XDG base dirs.
+ * - `CLAUDE_CODE_OAUTH_TOKEN`: the login ITSELF when a headless host
+ *   supplies it by env (`claude setup-token`). It is the one credential
+ *   this path may use; every provider key stays out
+ *   ({@link PROVIDER_KEY_ENV_NAMES} is never on this list).
+ * - Network reach: proxy variables in both spellings, and the extra-CA
+ *   and certificate paths a corporate network needs.
+ */
+export const LOGIN_CHILD_ENV_NAMES = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "TERM",
+  "TZ",
+  "LANG",
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_STATE_HOME",
+  "XDG_RUNTIME_DIR",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+] as const;
+
+const LOGIN_CHILD_ENV: ReadonlySet<string> = new Set(LOGIN_CHILD_ENV_NAMES);
+
+/** The env the login child is spawned with: the allowlisted names present in `env`, nothing else. */
+export function loginChildEnv(
+  env: Readonly<Record<string, string | undefined>>
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined && (LOGIN_CHILD_ENV.has(k) || k.startsWith("LC_"))) 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, loginChildEnv } from './claude-code-login';
 
 export class ClaudeSdkAdapter extends GeneratorAdapter {
   readonly provider: ProviderName = 'claude';
@@ -40,7 +41,12 @@ 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/#1278 — on the login path the binary sees an allowlisted
+    // env: no provider key (it prefers an env key over its login, so a stale
+    // one would take the run off this path without a word), and nothing
+    // else the parent merely holds.
+    const login = cfg.claudeCodeLogin === true;
+    const env = login ? loginChildEnv(buildEnv(cfg.env)) : buildEnv(cfg.env);
 
     const artifacts = createArtifacts();
     const onProgress = cfg.onProgress;
@@ -72,6 +78,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/boilerplate/templates/layouts/chat-mobile.tsx.tmpl

@@ -1,3 +1,7 @@
-    <Card padding="sm" shadow="sm">
-      {/* implement your UI here */}
-    </Card>
+    <Box padding="md">
+      {/* implement your UI here — an inline card: the chat bubble around it
+          provides the chrome, so add no shadow or outer radius of your own.
+          Compact and natural height; stack vertically. This root fills the
+          bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
+          measure (inert at bubble width, composed on a wider frame). */}
+    </Box>

package/src/boilerplate/templates/layouts/chat-universal.tsx.tmpl

@@ -1,3 +1,7 @@
-    <Card padding="sm" shadow="sm">
-      {/* implement your UI here */}
-    </Card>
+    <Box padding="md">
+      {/* implement your UI here — an inline card: the chat bubble around it
+          provides the chrome, so add no shadow or outer radius of your own.
+          Compact and natural height; stack vertically. This root fills the
+          bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
+          measure (inert at bubble width, composed on a wider frame). */}
+    </Box>

package/src/contract-context.ts

@@ -59,7 +59,7 @@ const SHELL_HINTS: Record<string, string> = {
 - Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.
 - Scrolling: parent scrolls (chat feed) — component should NOT have internal scroll
 - Layout: single column, compact. No sidebar. Stack everything vertically.
-- Width: width: 100% (fills parent bubble). Do NOT set max-width.`,
+- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width.`,
 
   fullscreen: `**Fullscreen Shell — Takes over entire viewport**
 - Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)

package/src/create-ui-generator.ts

@@ -56,6 +56,7 @@ import {
 } from '@ggui-ai/mcp-server-core';
 import { createGeneratorTools } from './adapters/index.js';
 import { dispatchGeneration } from './adapters/generation-dispatch.js';
+import { generatorBuild } from './generator-build.js';
 import { hasProfile } from './boilerplate/styling-profile.js';
 import { effortDials } from './effort.js';
 import type { ProviderName } from './adapters/types.js';
@@ -68,6 +69,7 @@ import {
 } from './contract-context.js';
 import type { RenderingContext } from './contract-context.js';
 import type { DesignMode } from './design-mode.js';
+import { DEFAULT_DESIGN_MODE } from './design-mode.js';
 import { resolveRoute, applyRouteToEnv } from './adapters/provider-router.js';
 import type { QualityConfig } from './evaluation/types-public.js';
 import type { EvaluationConfig } from './evaluation/types.js';
@@ -298,16 +300,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({
@@ -330,6 +341,7 @@ export function createUiGenerator(
         // Ignored by the constrained prompt (its shell/screen
         // descriptors stay byte-identical).
         const canvas = rendering ? canvasForRenderingContext(rendering) : undefined;
+        const shellType = harnessShellForRendering(rendering);
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance,
@@ -396,6 +408,8 @@ export function createUiGenerator(
           ...(onRetry !== undefined ? { onRetry } : {}),
           ...(designMode !== undefined ? { designMode } : {}),
           ...(canvas !== undefined ? { canvas } : {}),
+          // ggui#1279 — the shell the declared rendering composes for (chat only; see harnessShellForRendering).
+          ...(shellType !== undefined ? { shellType } : {}),
           ...(input.profile !== undefined ? { profile: input.profile } : {}),
           // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
           ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
@@ -412,6 +426,8 @@ export function createUiGenerator(
           latencyMs: Date.now() - startedAt,
           cacheHit: false,
           attempts: result.turnsUsed,
+          // ggui#1280 — the build that made this generation (template keys, never per-request).
+          build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
           // Prompt-cache counters are provider-specific (Claude reports
           // them; others omit). Pass through truthfully — absent on the
           // adapter result stays absent here, never defaulted to 0.
@@ -452,6 +468,8 @@ export function createUiGenerator(
             outputTokens: 0,
             latencyMs: Date.now() - startedAt,
             cacheHit: false,
+            // ggui#1280 — a failed generation still names the build that failed.
+            build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
           },
         };
       } finally {
@@ -514,6 +532,27 @@ function mapLlmProviderToDispatchProvider(provider: LlmProvider): ProviderName {
   }
 }
 
+/**
+ * ggui#1279 — the harness shell a declared rendering composes for. The canvas
+ * (`canvasForRenderingContext`) already follows the rendering; the WHAT leg's
+ * layout and the HOW leg's shell descriptor did not, so a declared chat card
+ * was scaffolded to "fill the frame" while the user prompt and the fit verdict
+ * treated it as an inline card. Only a declared CHAT shell changes anything.
+ * `fullscreen` IS the harness default, and `partial` has no layout of its own
+ * yet, so both pass no shell and those generations stay byte-identical — named
+ * here rather than guessed.
+ */
+function harnessShellForRendering(rendering: RenderingContext | undefined): 'chat' | undefined {
+  if (rendering === undefined) return undefined;
+  switch (rendering.shell) {
+    case 'chat':
+      return 'chat';
+    case 'fullscreen':
+    case 'partial':
+      return undefined;
+  }
+}
+
 function mapRendering(
   rendering: UiGenerateInput['rendering'],
 ): RenderingContext | undefined {

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/index.ts

@@ -22,6 +22,7 @@ export type {
   EvalOutcome,
   EvalCategory,
   EvalResult,
+  ContractFeedbackRecord,
   VisualEvalSummary,
   CanvasJudgeRecord,
   CanvasVisualSummary,