@ggui-ai/ui-gen 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.25.0",
+  "version": "0.27.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": [
@@ -189,9 +189,9 @@
     "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.25.0",
-    "@ggui-ai/mcp-server-core": "0.25.0",
-    "@ggui-ai/protocol": "0.25.0"
+    "@ggui-ai/mcp-server-core": "0.27.0",
+    "@ggui-ai/project-config": "0.27.0",
+    "@ggui-ai/protocol": "0.27.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -233,11 +233,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.25.0",
-    "@ggui-ai/ui-visual-tester": "0.25.0",
-    "@ggui-ai/gadgets": "0.25.0",
-    "@ggui-ai/sandbox": "0.25.0",
-    "@ggui-ai/wire": "0.25.0"
+    "@ggui-ai/design": "0.27.0",
+    "@ggui-ai/sandbox": "0.27.0",
+    "@ggui-ai/gadgets": "0.27.0",
+    "@ggui-ai/ui-visual-tester": "0.27.0",
+    "@ggui-ai/wire": "0.27.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -252,9 +252,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.25.0",
-    "@ggui-ai/project-config": "0.25.0",
-    "@ggui-ai/protocol": "0.25.0"
+    "@ggui-ai/mcp-server-core": "0.27.0",
+    "@ggui-ai/project-config": "0.27.0",
+    "@ggui-ai/protocol": "0.27.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/adapters/base.ts

@@ -45,8 +45,13 @@ export interface ClaudeSdkConfig extends AdapterConfig {
   env?: Record<string, string>;
   /** MCP server configs for Claude Agent SDK (keyed by name) */
   mcpServers?: Record<string, McpServerConfig>;
-  /** Allowed tool names for Claude Agent SDK */
+  /** Tool names to approve. Absent → every tool of every server in `mcpServers` (ggui#1714). */
   allowedTools?: string[];
+  /**
+   * CLI built-in tools to offer the model (e.g. `['Write']`). Default: none.
+   * An explicit opt-in: a built-in that writes or executes acts on the host (ggui#1714).
+   */
+  builtinTools?: readonly string[];
   /** Subagent definitions for Claude Agent SDK */
   agents?: Record<string, AgentDefinition>;
   /** Custom CLI path for Docker deployments */

package/src/adapters/claude/message-parser.ts

@@ -13,6 +13,7 @@ import type {
   SDKUserMessage,
 } from '@anthropic-ai/claude-agent-sdk';
 import type { JsonObject } from '@ggui-ai/protocol';
+import { sourceCodeFromToolUse } from './source-capture';
 
 /**
  * Mutable accumulator for artifacts extracted from the SDK message stream.
@@ -197,12 +198,10 @@ function extractSourceCode(message: SDKMessage, artifacts: MessageArtifacts): vo
   if (!Array.isArray(content)) return;
 
   for (const block of content) {
-    if (block.type === 'tool_use' && block.name === 'Write') {
-      const input = block.input as { content?: string } | undefined;
-      if (input?.content) {
-        artifacts.sourceCode = input.content;
-      }
-    }
+    if (block.type !== 'tool_use') continue;
+    // ggui#1714 — the rule lives in source-capture.ts, shared with the evaluation loop.
+    const value = sourceCodeFromToolUse(block.name, block.input);
+    if (value !== undefined) artifacts.sourceCode = value;
   }
 }
 

package/src/adapters/claude/sdk-tool-pins.ts

@@ -0,0 +1,44 @@
+// packages/ui-gen/src/adapters/claude/sdk-tool-pins.ts
+//
+// ggui#1714 — the tool surface of every Agent SDK `query()` this package runs.
+//
+// Left to its defaults, a `query()` session offers the model the CLI's whole
+// built-in set (Bash, Edit, Read, Write, WebFetch, Task, …) and loads the host
+// user's own Claude configuration (plugins, MCP servers from `~/.claude`).
+// `allowedTools` does not narrow that: it only approves the names it lists.
+// Measured on SDK 0.3.229 from the session's `system`/`init` message:
+//
+//   as before this file           → every built-in + the caller's tools
+//   `tools: []` alone             → the caller's tools + a user-level plugin server
+//   `tools: []` + `settingSources: []` → the caller's tools only
+//
+// So the pins are both, on every path. With them in place no permission
+// bypass is needed: a tool named in `allowedTools` runs, and a server-level
+// entry (`mcp__<server>`) approves every tool of that server (both measured
+// on a live turn; with no entry the call is denied and the run reports it).
+
+import type { McpServerConfig, Options } from '@anthropic-ai/claude-agent-sdk';
+
+export type SdkToolPins = Required<Pick<Options, 'tools' | 'settingSources' | 'allowedTools'>>;
+
+export interface SdkToolPinInput {
+  /** The MCP servers the session gets, keyed by name. */
+  readonly mcpServers?: Record<string, McpServerConfig>;
+  /** Tool names to approve. Absent → every tool of every server in `mcpServers`. */
+  readonly allowedTools?: readonly string[];
+  /**
+   * The CLI built-ins to offer (e.g. `['Write']`) — an explicit opt-in.
+   * Each one is also approved, so it runs without a prompt; a built-in that
+   * writes or executes acts on the host with the session's permissions.
+   */
+  readonly builtinTools?: readonly string[];
+}
+
+export function sdkToolPins(input: SdkToolPinInput): SdkToolPins {
+  const builtins = [...(input.builtinTools ?? [])];
+  const approved =
+    input.allowedTools !== undefined
+      ? [...input.allowedTools]
+      : Object.keys(input.mcpServers ?? {}).map((name) => `mcp__${name}`);
+  return { tools: builtins, settingSources: [], allowedTools: [...approved, ...builtins] };
+}

package/src/adapters/claude/sdk.ts

@@ -14,6 +14,7 @@ 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';
+import { sdkToolPins } from './sdk-tool-pins';
 
 export class ClaudeSdkAdapter extends GeneratorAdapter {
   readonly provider: ProviderName = 'claude';
@@ -73,9 +74,8 @@ export class ClaudeSdkAdapter extends GeneratorAdapter {
         systemPrompt: params.systemPrompt,
         ...(mcpServers && { mcpServers }),
         ...(cfg.agents && { agents: cfg.agents }),
-        ...(allowedTools && { allowedTools }),
-        permissionMode: 'bypassPermissions',
-        allowDangerouslySkipPermissions: true,
+        // ggui#1714 — no CLI built-ins unless asked for, no host settings, no permission bypass.
+        ...sdkToolPins({ mcpServers, allowedTools, builtinTools: cfg.builtinTools }),
         ...(cfg.cliPath && { pathToClaudeCodeExecutable: cfg.cliPath }),
         ...(cfg.stderr && { stderr: cfg.stderr }),
         // ggui#1185 — tool-less, config-less, non-bare; the model is pinned above.

package/src/adapters/claude/source-capture.ts

@@ -0,0 +1,20 @@
+// packages/ui-gen/src/adapters/claude/source-capture.ts
+//
+// ggui#1714 — which tool call carries a component's source, decided once.
+// Both Agent SDK paths (ClaudeSdkAdapter's message parser and the evaluation
+// loop's extractor) read source through this function, so the rule cannot be
+// fixed on one path and left stale on the other.
+//
+//   `*__compile_component` → `input.code`    (the bridged compile tool)
+//   `Write`                → `input.content` (a CLI built-in, offered only by opt-in)
+
+const COMPILE_TOOL_SUFFIX = '__compile_component';
+
+/** The source a tool_use block carries, or undefined when it carries none. */
+export function sourceCodeFromToolUse(name: unknown, input: unknown): string | undefined {
+  if (typeof name !== 'string') return undefined;
+  const field = name === 'Write' ? 'content' : name.endsWith(COMPILE_TOOL_SUFFIX) ? 'code' : undefined;
+  if (field === undefined || typeof input !== 'object' || input === null) return undefined;
+  const value: unknown = Reflect.get(input, field);
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/adapters/generation-dispatch.ts

@@ -126,6 +126,8 @@ export interface GenerationDispatchParams {
     /** ggui#1436 — see `SingleComponentParams.visualEvaluation.criteriaBank`. */
     criteriaBank?: CriteriaBank;
     criteriaKind?: string;
+    /** ggui#1542 — see `SingleComponentParams.visualEvaluation.actOn`. */
+    actOn?: "critical" | "major";
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;

package/src/boilerplate/free-design-prompt.ts

@@ -18,7 +18,7 @@
 // for raw elements · the one-gesture-surface invariant restated for raw
 // elements · a regenerated quality checklist.
 
-import { consumedTokenManifest } from "@ggui-ai/design/themes";
+import { taughtTokenManifest } from "../taught-tokens.js";
 import { describeCanvas, type CanvasClass } from "../design-mode.js";
 import {
   ANTI_PATTERNS,
@@ -136,7 +136,7 @@ function renderRamp(r: ColorRamp): string {
  * every role the prose names exists on `:root`; nothing is implied by a
  * `50…800` range that the manifest does not carry step for step.
  */
-export function renderFreeColorRule(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderFreeColorRule(manifest: readonly string[] = taughtTokenManifest): string {
   const { ramps, roles } = colorVocabularyFromManifest(manifest);
   const brand = ramps.filter((r) => r.family === "primary" || r.family === "neutral");
   const state = ramps.filter((r) => r.family !== "primary" && r.family !== "neutral");
@@ -260,7 +260,7 @@ const TOKEN_GROUPS: readonly TokenGroup[] = [
  * does not define. Grouped by prefix; anything outside the known
  * prefixes lands under "Other".
  */
-export function renderTokenVocabulary(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderTokenVocabulary(manifest: readonly string[] = taughtTokenManifest): string {
   const sorted = [...manifest].sort();
   const claimed = new Set<string>();
   const lines: string[] = [

package/src/boilerplate/hard-sections.ts

@@ -257,7 +257,7 @@ The width works the same way, and the mistake is the mirror image: **your outerm
 
 - Never put \`maxWidth\` (or a \`max-w-*\` class) on the element you return at the top. On a wide canvas that turns your card into a narrow strip with the frame's ground on either side of it, and on a narrow one it does nothing — the same composition reading differently at two sizes.
 - DO cap the reading measure inside: a column of prose is easiest to read at 60–70 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
-- Centre that inner column with the container's own centring, not by shrinking the root.
+- Centre that inner column with the container's own centring, not by shrinking the root — and give the card ONE column: every block of the reading flow (a heading, its text, and the chips or buttons that answer it) sits in a \`<Container>\` of the same \`maxWidth\`, so their left edges line up even where a full-width band runs between them.
 - **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it — \`<Box padding="lg"><Container maxWidth="sm">…</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
 
 /** Helper-component structure guidance (JSX depth 3–5, helpers above `Component`). Identical in both modes. */

package/src/boilerplate/system-prompt.ts

@@ -481,13 +481,14 @@ MANDATORY:
 2. NEVER use CSS gradients with custom colors. If you need a gradient: \`linear-gradient(to bottom, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
 3. NEVER invent your own palette. The system provides primary, neutral, success, warning, error, and info — use ONLY these.
 4. NEVER include literal fallback values in ANY token reference — colors, spacing, typography, radius, shadows alike. Write \`var(--ggui-spacing-4)\` bare, never \`var(--ggui-spacing-4, 16px)\`; \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\`. The runtime injects every token; a literal fallback paints the wrong value exactly when the operator's theme matters most.
+5. NEVER set an inline \`border\`, \`borderColor\`, \`borderWidth\` or \`borderStyle\` on a kit control — \`Button\`, \`Input\`, \`Select\`, \`TextArea\`, \`Checkbox\`, \`RadioGroup\`, \`Toggle\`, \`SearchField\`. The control draws its own boundary, and it clears 3:1 on its surface in every theme: an outline chip is \`<Button variant="outline">\` exactly as it comes (its edge is \`controlAccentOutline\`). Where you draw a control-like edge on your own element, use \`var(--ggui-color-controlOutline)\`. A ramp step such as \`primary-200\` as a control's border is nearly invisible (about 1.1:1).
 
 Token categories:
 - Brand fills: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
 - Accent text: \`var(--ggui-color-link)\` — eyebrows, taglines, links, labels; readable per mode (never a bare \`primary-<stop>\` as a text color)
 - Text: \`var(--ggui-color-onContainer)\`, \`var(--ggui-color-onSunken)\`
 - Backgrounds: \`var(--ggui-color-container)\`, \`var(--ggui-color-sunken)\`
-- Borders: \`var(--ggui-color-outline)\`
+- Borders: \`var(--ggui-color-outline)\` — dividers and the edges of non-interactive boxes; a control's edge is the kit's (rule 5)
 - Spacing: \`var(--ggui-spacing-4)\`, \`var(--ggui-spacing-6)\`
 - Typography: \`var(--ggui-font-size-sm)\`, \`var(--ggui-font-weight-semibold)\`
 - Shadows: \`var(--ggui-shape-shadow-sm)\`, \`var(--ggui-shape-shadow-md)\`, \`var(--ggui-shape-shadow-lg)\`
@@ -502,7 +503,7 @@ Use the FULL primary palette throughout the component — NOT only on submit but
 | Element | Token | Purpose |
 |---------|-------|---------|
 | Section headers, hero areas, highlight strips | \`primary-50\` / \`primary-100\` | Subtle branded backgrounds |
-| Borders, dividers, focus rings, input focus | \`primary-200\` / \`primary-300\` | Branded structure |
+| Dividers, section rules, edges of non-interactive boxes | \`primary-200\` / \`primary-300\` | Branded structure — never a control's border (rule 5) |
 | Accent TEXT — eyebrows, taglines, links, labels, inline arrows | \`link\` (\`var(--ggui-color-link)\`) or \`<Text tone="emphasized">\` | The brand's READABLE ink, derived per mode to clear 4.5:1 — a bare \`primary-300…600\` as a text color fails tier-0 |
 | Icon fills, badges, active indicators | \`primary-500\` / \`primary-600\` | Core accent fill |
 | Buttons, CTAs, filled interactive elements | \`primary-600\` / \`primary-700\` | Primary actions |

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

@@ -3,5 +3,7 @@
           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). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

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

@@ -3,5 +3,7 @@
           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). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/boilerplate/templates/layouts/fullscreen-desktop.tsx.tmpl

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

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

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/check/run-tier0.ts

@@ -17,6 +17,7 @@ import type { DataContract } from '@ggui-ai/protocol';
 import { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
+import { taughtTokenManifest } from '../taught-tokens.js';
 import { validateAllContracts, type ContractIssue } from './contract-validation.js';
 import { typecheck } from './type-checker.js';
 import { lintReactHooks, type ReactLintDiagnostic } from './react-linter.js';
@@ -315,7 +316,9 @@ const RETIRED_TOKEN_SUCCESSORS: ReadonlyMap<string, string> = new Map([
  * (`--ggui-motion-duration-normal` → fast, base, slow); otherwise the names
  * sharing any of its segments of four letters or more
  * (`--ggui-duration-slow` → the motion durations). Empty when nothing is
- * near, so the hint falls back to the manifest's general shape.
+ * near, so the hint falls back to the manifest's general shape. A hint
+ * teaches, so it draws only on the names the model may be taught
+ * (`taughtTokenManifest`); the closed-set check above admits the full manifest.
  */
 export function suggestManifestTokens(name: string): readonly string[] {
   const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
@@ -328,7 +331,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
   const own = name.endsWith('-') ? segments.length : segments.length - 1;
   for (let n = own; n >= 2; n--) {
     const prefix = `--${segments.slice(0, n).join('-')}-`;
-    const family = consumedTokenManifest.filter((token) => token.startsWith(prefix));
+    const family = taughtTokenManifest.filter((token) => token.startsWith(prefix));
     if (family.length > 0) return wordHitsFirst(name, rolesFirst(family));
   }
   const words = new Set(
@@ -338,7 +341,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
       .map((segment) => segment.toLowerCase()),
   );
   return rolesFirst(
-    consumedTokenManifest.filter((token) =>
+    taughtTokenManifest.filter((token) =>
       token.split('-').some((segment) => words.has(segment.toLowerCase())),
     ),
   );
@@ -568,6 +571,50 @@ function detectComponentNeverReturns(
  * Wraps the same logic as runSelfChecks (adapters/tools.ts) but emits EvalIssue[].
  * Also runs contract validation when contract are provided.
  */
+/** The kit controls whose boundary the design system draws (ggui#1697). */
+const KIT_CONTROLS = ['Button', 'Input', 'Select', 'TextArea', 'Checkbox', 'RadioGroup', 'Toggle', 'SearchField'] as const;
+
+/**
+ * Opening tags of kit controls, read brace- and quote-aware: an attribute like `onClick={() => x}` holds a `>` that a
+ * plain `[^>]*` pattern stops at, which would hide every attribute after it.
+ */
+function kitControlTags(source: string): { name: string; attrs: string; line: number }[] {
+  const out: { name: string; attrs: string; line: number }[] = [];
+  const open = new RegExp(`<(${KIT_CONTROLS.join('|')})\\b`, 'g');
+  for (const m of source.matchAll(open)) {
+    const start = (m.index ?? 0) + m[0].length;
+    let depth = 0;
+    let quote: string | null = null;
+    let i = start;
+    for (; i < source.length; i += 1) {
+      const c = source[i];
+      if (quote !== null) {
+        if (c === quote && source[i - 1] !== '\\') quote = null;
+      } else if (c === '"' || c === "'" || c === '`') quote = c;
+      else if (c === '{') depth += 1;
+      else if (c === '}') depth -= 1;
+      else if (c === '>' && depth === 0) break;
+    }
+    out.push({ name: m[1] ?? '', attrs: source.slice(start, i), line: source.slice(0, m.index ?? 0).split('\n').length });
+  }
+  return out;
+}
+
+/** A border key (not a radius) in the tag's inline style, or in a same-file object its `style={name}` points at. */
+function inlineBorderKey(attrs: string, source: string): string | null {
+  const BORDER = /\b(border(?:Top|Right|Bottom|Left)?(?:Color|Width|Style)?)\s*:/;
+  const style = attrs.match(/\bstyle=\{\{([\s\S]*)\}\}/);
+  if (style !== null) {
+    const hit = (style[1] ?? '').match(BORDER);
+    if (hit !== null) return hit[1] ?? null;
+  }
+  const named = attrs.match(/\bstyle=\{\s*([A-Za-z_$][\w$]*)\s*\}/);
+  if (named === null) return null;
+  const decl = source.match(new RegExp(`\\b(?:const|let)\\s+${named[1]}\\b[^=]*=\\s*\\{([^{}]*)\\}`));
+  const hit = decl !== null ? (decl[1] ?? '').match(BORDER) : null;
+  return hit !== null ? hit[1] ?? null : null;
+}
+
 export async function runTier0Checks(
   sourceCode: string,
   contract?: DataContract,
@@ -1166,6 +1213,23 @@ export async function runTier0Checks(
     }
   }
 
+  // ── A kit control's boundary is the kit's (ggui#1697) ──────
+  // A control draws its own edge, derived to clear 3:1 on its surface (`controlOutline`, or
+  // `controlAccentOutline` on an outline Button); an inline border paints over it, and the ramp step
+  // the model reached for (`primary-200`) measured about 1.1:1. The prompt's rule 5 says the same, so
+  // this check enforces what the model was told. The description starts with the check's id so the
+  // generator's logged violation lines (`✗ …`) count its fires per generation, in-turn repairs included.
+  for (const tag of enforceDesignVocabulary ? kitControlTags(sourceCode) : []) {
+    const key = inlineBorderKey(tag.attrs, sourceCode);
+    if (key === null) continue;
+    issues.push({
+      tier: 0, result: 'fail', category: 'tokens', subcategory: 'control-inline-border', severity: 'critical',
+      description: `control-inline-border: <${tag.name}> sets an inline \`${key}\` — a kit control draws its own boundary, and an inline border paints over it`,
+      fix: `Remove the border from <${tag.name}>'s style (keep borderRadius if you need it). An outline chip is <Button variant="outline"> exactly as it comes; a control-like edge on your own element uses var(--ggui-color-controlOutline).`,
+      line: tag.line,
+    });
+  }
+
   // ── Missing Props interface ───────────────────────────────
   if (!sourceCode.includes('interface Props') && !sourceCode.includes('type Props')) {
     issues.push({

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: 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.`,
+- 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; the chips or buttons that answer the prose sit in a Container of the same maxWidth, so they share its left edge.`,
 
   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/design-system-docs.ts

@@ -49,6 +49,7 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 | link | var(--ggui-color-link) | Accent TEXT — eyebrows, taglines, links, labels, inline arrows: the brand's readable ink, derived per mode to clear 4.5:1 on the container and the ground |
 | outline | var(--ggui-color-outline) | Borders, dividers |
 | outlineVariant | var(--ggui-color-outlineVariant) | Subtle borders |
+| controlOutline | var(--ggui-color-controlOutline) | A control's edge — clears 3:1 on its surface; kit controls draw it themselves |
 
 **Usage pattern:**
 - Page/section background → \`var(--ggui-color-ground)\`
@@ -173,7 +174,7 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 ### Color usage guide
 - **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each — use them for every background/text/border decision; they adapt to any theme
 - **primary-50/100**: Section backgrounds, highlight strips, card headers
-- **primary-200/300**: Borders, dividers, focus rings, input outlines
+- **primary-200/300**: Dividers and section rules — never a control's border: kit controls draw their own edge (\`controlOutline\` / \`controlAccentOutline\`), so set no inline border on them
 - **primary-500/600**: Filled buttons, CTAs, badges, icon fills, active indicators — fills and borders, NOT a text color
 - **link**: Accent TEXT — eyebrows, taglines, links, labels, inline arrows; the brand's readable ink per mode (a bare \`primary-300…600\` as a text color fails tier-0: \`universal.accent_text_ink\`)
 - **primary-700/800/900**: Headings and text on light primary backgrounds

package/src/evaluation/cost-tracker.ts

@@ -31,15 +31,54 @@ function resolveRegistryId(model: string): ModelId | null {
   return keys.find((id) => id.endsWith(`/${undated}`)) ?? null;
 }
 
+/**
+ * ggui#1524 — the largest cache-WRITE premium any registry model states (`cacheWritePer1M / inputPer1M`), never
+ * below 1. A cost CAP errs toward over-counting, so a model that states no write rate is priced at this bound
+ * times its input rate: a write costs a premium over input wherever one is charged, and pricing it at the bare
+ * input rate would slip that premium under the cap. Derived from the registry, so it moves with it.
+ */
+export const CACHE_WRITE_PREMIUM_BOUND: number = Math.max(
+  1,
+  ...Object.values(MODEL_REGISTRY).flatMap(({ costs }) =>
+    costs.cacheWritePer1M !== undefined && costs.inputPer1M > 0 ? [costs.cacheWritePer1M / costs.inputPer1M] : [],
+  ),
+);
+
+/** Per-1K USD for each kind of token a call can spend. */
+export interface PricePer1k {
+  readonly input: number;
+  readonly output: number;
+  /** Cache reads: the model's stated rate, else its input rate — over-counts a read, the safe side for a cap. */
+  readonly cacheRead: number;
+  /** Cache writes: the model's stated rate, else its input rate × {@link CACHE_WRITE_PREMIUM_BOUND}. */
+  readonly cacheWrite: number;
+}
+
 /** Fallback when a model has no registry entry — Sonnet-class rates. */
-const FALLBACK_PER_1K = { input: 0.003, output: 0.015 };
+const FALLBACK_PER_1K: PricePer1k = {
+  input: 0.003,
+  output: 0.015,
+  cacheRead: 0.003,
+  cacheWrite: 0.003 * CACHE_WRITE_PREMIUM_BOUND,
+};
 
-/** Per-1K input/output USD for a bare wire model id. */
-export function pricePer1k(model: string): { input: number; output: number } {
+/** Per-1K USD for a bare wire model id: input, output, and the two cache kinds. */
+export function pricePer1k(model: string): PricePer1k {
   const id = resolveRegistryId(model);
   if (id === null) return FALLBACK_PER_1K;
   const { costs } = MODEL_REGISTRY[id];
-  return { input: costs.inputPer1M / 1000, output: costs.outputPer1M / 1000 };
+  return {
+    input: costs.inputPer1M / 1000,
+    output: costs.outputPer1M / 1000,
+    cacheRead: (costs.cacheReadPer1M ?? costs.inputPer1M) / 1000,
+    cacheWrite: (costs.cacheWritePer1M ?? costs.inputPer1M * CACHE_WRITE_PREMIUM_BOUND) / 1000,
+  };
+}
+
+/** ggui#1524 — the cache tokens a call spent, as its provider reported them; absent = unreported. */
+export interface CacheSpend {
+  readonly read?: number;
+  readonly write?: number;
 }
 
 export class CostTracker {
@@ -47,9 +86,18 @@ export class CostTracker {
 
   constructor(private maxBudget: number | null) {}
 
-  record(model: string, inputTokens: number, outputTokens: number): number {
+  /**
+   * Record one call. `inputTokens` is the provider's UNCACHED input; a call that read or wrote the prompt cache
+   * passes those counts in `cache` (ggui#1524), priced at the cache rates — until then a turn with a long cached
+   * prefix cost the cap almost nothing while the provider billed its reads and writes.
+   */
+  record(model: string, inputTokens: number, outputTokens: number, cache: CacheSpend = {}): number {
     const prices = pricePer1k(model);
-    const cost = (inputTokens / 1000) * prices.input + (outputTokens / 1000) * prices.output;
+    const cost =
+      (inputTokens / 1000) * prices.input +
+      (outputTokens / 1000) * prices.output +
+      ((cache.read ?? 0) / 1000) * prices.cacheRead +
+      ((cache.write ?? 0) / 1000) * prices.cacheWrite;
     this.totalCost += cost;
     return cost;
   }