@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/dist/adapters/index.js

@@ -1,3563 +1,27 @@
-import { z } from 'zod';
-import * as esbuild from 'esbuild';
-import Anthropic from '@anthropic-ai/sdk';
-import { FORBIDDEN_IMPORT_SPECIFIERS } from '@ggui-ai/design/rendering';
-import { DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1 } from '@ggui-ai/protocol';
-import '@ggui-ai/protocol/content-hash';
-import ts3 from 'typescript';
-import fs, { existsSync } from 'fs';
-import path from 'path';
-import { createRequire } from 'module';
-import { Linter } from 'eslint';
-import { consumedTokenManifest } from '@ggui-ai/design/themes';
-import { fileURLToPath, pathToFileURL } from 'url';
-import { runSandboxed } from '@ggui-ai/sandbox';
-
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/adapters/base.ts
-function stripModelPrefix(modelId) {
-  const slashIndex = modelId.indexOf("/");
-  return slashIndex >= 0 ? modelId.slice(slashIndex + 1) : modelId;
-}
-function hasCredentials(config, ...envVarNames) {
-  if (config.apiKey) return true;
-  if (config.useBedrock) return true;
-  if (config.claudeCodeLogin) return true;
-  return envVarNames.some((name) => !!process.env[name]);
-}
-var GeneratorAdapter;
-var init_base = __esm({
-  "src/adapters/base.ts"() {
-    GeneratorAdapter = class {
-      constructor(config) {
-        this.config = config;
-      }
-      config;
-      /**
-       * Map a LiteLLM-format model ID to this SDK's native format.
-       * Default: strips the provider prefix (e.g., 'anthropic/claude-sonnet-4-6' -> 'claude-sonnet-4-6').
-       * Override only if the prefix convention differs.
-       */
-      resolveModelId(litellmModelId) {
-        return stripModelPrefix(litellmModelId);
-      }
-    };
-  }
-});
-function zodToJsonSchema(schema) {
-  return z.toJSONSchema(schema);
-}
-function toolArgsToJsonObject(args) {
-  const out = {};
-  for (const [key, value] of Object.entries(args)) {
-    out[key] = value === void 0 ? void 0 : toJsonValue(value, key);
-  }
-  return out;
-}
-function toJsonValue(value, path2) {
-  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item, i) => toJsonValue(item, `${path2}[${i}]`));
-  }
-  if (typeof value === "object") {
-    const out = {};
-    for (const [key, entry] of Object.entries(value)) {
-      out[key] = entry === void 0 ? void 0 : toJsonValue(entry, `${path2}.${key}`);
-    }
-    return out;
-  }
-  throw new Error(
-    `Tool-call arguments contain a non-JSON value at '${path2}' (${typeof value})`
-  );
-}
-var init_tool_bridge = __esm({
-  "src/adapters/tool-bridge.ts"() {
-  }
-});
-function createCapture() {
-  return { compiledCode: "", sourceCode: void 0, stream: void 0, generatorMeta: void 0 };
-}
-function captureSourceCode(capture, toolName, args) {
-  if (toolName === "compile_component" && typeof args.code === "string") {
-    capture.sourceCode = args.code;
-  }
-}
-function captureCompiledCode(capture, toolName, result) {
-  if (toolName !== "compile_component" || result.isError) return;
-  try {
-    const parsed = JSON.parse(result.content[0].text);
-    if (parsed.success && parsed.compiledCode) {
-      capture.compiledCode = parsed.compiledCode;
-    }
-  } catch {
-  }
-}
-function captureMarkers(capture, text) {
-  if (!capture.stream && text.includes("__GGUI_STREAM_SPEC__")) {
-    const match = text.match(/__GGUI_STREAM_SPEC__\s*([\s\S]*?)\s*__GGUI_STREAM_SPEC_END__/);
-    if (match) {
-      try {
-        capture.stream = JSON.parse(
-          match[1].replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\")
-        );
-      } catch {
-      }
-    }
-  }
-  if (!capture.generatorMeta && text.includes("__GGUI_META__")) {
-    const match = text.match(/__GGUI_META__\s*([\s\S]*?)\s*__GGUI_META_END__/);
-    if (match) {
-      try {
-        const stripped = match[1].replace(/```(?:json)?\s*/g, "").trim();
-        const raw = stripped.replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
-        const parsed = JSON.parse(raw);
-        if (parsed.category) {
-          capture.generatorMeta = { category: parsed.category, description: parsed.description ?? "" };
-        }
-      } catch {
-      }
-    }
-  }
-}
-async function extractCodeFromText(finalOutput, tools, capture) {
-  if (finalOutput.length <= 100) return;
-  const codeMatch = finalOutput.match(/```(?:tsx?|jsx?|typescript|javascript)?\s*\n([\s\S]*?)```/) ?? finalOutput.match(/```\s*\n([\s\S]*?)```/);
-  let code = codeMatch ? codeMatch[1].trim() : "";
-  if (!code && (finalOutput.includes("export default") || finalOutput.includes("export function"))) {
-    code = finalOutput;
-  }
-  if (!code || !(code.includes("export default") || code.includes("export function"))) {
-    return;
-  }
-  capture.sourceCode = code;
-  const compileTool = tools.find((t) => t.name === "compile_component");
-  if (!compileTool) return;
-  const compileResult = await compileTool.handler({ code, filename: "Component.tsx" });
-  if (compileResult.isError) {
-    console.warn("[extractCodeFromText] compile_component failed:", compileResult.content[0]?.text?.slice(0, 300));
-  }
-  captureCompiledCode(capture, "compile_component", compileResult);
-}
-async function compileLastResort(capture, allTextOutput) {
-  if (capture.compiledCode) return;
-  let code = capture.sourceCode;
-  if (!code && allTextOutput && allTextOutput.length > 100) {
-    const codeMatch = allTextOutput.match(/```(?:tsx?|jsx?|typescript|javascript)?\s*\n([\s\S]*?)```/) ?? allTextOutput.match(/```\s*\n([\s\S]*?)```/);
-    code = codeMatch ? codeMatch[1].trim() : void 0;
-    if (!code && (allTextOutput.includes("export default") || allTextOutput.includes("export function"))) {
-      code = allTextOutput;
-    }
-  }
-  if (!code || !(code.includes("export default") || code.includes("export function"))) {
-    return;
-  }
-  try {
-    const result = await esbuild.transform(code, {
-      loader: "tsx",
-      target: "es2020",
-      format: "esm",
-      jsx: "automatic",
-      jsxImportSource: "react",
-      minify: true,
-      sourcefile: "Component.tsx"
-    });
-    capture.compiledCode = result.code;
-    capture.sourceCode = code;
-    console.warn("[compileLastResort] Compiled code bypassing self-checks \u2014 may have quality issues");
-  } catch (err) {
-    console.warn("[compileLastResort] esbuild failed:", err instanceof Error ? err.message : String(err));
-  }
-}
-var init_extract_code = __esm({
-  "src/adapters/extract-code.ts"() {
-  }
-});
-function createAnthropicClient(rawKey) {
-  if (rawKey === void 0) {
-    return new Anthropic({
-      baseURL: "https://api.anthropic.com"
-    });
-  }
-  return new Anthropic({
-    apiKey: rawKey,
-    baseURL: "https://api.anthropic.com"
-  });
-}
-var init_client = __esm({
-  "src/adapters/claude/client.ts"() {
-  }
-});
-
-// src/adapters/claude/raw.ts
-var raw_exports = {};
-__export(raw_exports, {
-  ClaudeRawAdapter: () => ClaudeRawAdapter
-});
-function toAnthropicTool(def) {
-  return {
-    name: def.name,
-    description: def.description,
-    input_schema: zodToJsonSchema(def.inputSchema)
-  };
-}
-var ClaudeRawAdapter;
-var init_raw = __esm({
-  "src/adapters/claude/raw.ts"() {
-    init_base();
-    init_tool_bridge();
-    init_extract_code();
-    init_client();
-    ClaudeRawAdapter = class extends GeneratorAdapter {
-      provider = "claude";
-      mode = "raw";
-      displayName = "Claude (Raw API)";
-      client = null;
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "ANTHROPIC_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        if (!this.client) {
-          if (this.config.useBedrock) {
-            this.client = createAnthropicClient(void 0);
-          } else {
-            const rawKey = this.config.apiKey || process.env.ANTHROPIC_API_KEY;
-            this.client = createAnthropicClient(rawKey);
-          }
-        }
-        const anthropicTools = params.tools.map(toAnthropicTool);
-        const capture = createCapture();
-        let totalInputTokens = 0;
-        let totalOutputTokens = 0;
-        let turnsUsed = 0;
-        const messages = [
-          { role: "user", content: params.userPrompt }
-        ];
-        for (let turn = 0; turn < params.maxTurns; turn++) {
-          turnsUsed = turn + 1;
-          const response = await this.client.messages.create({
-            model: params.model,
-            max_tokens: 16384,
-            system: params.systemPrompt,
-            messages,
-            tools: anthropicTools
-          });
-          totalInputTokens += response.usage.input_tokens;
-          totalOutputTokens += response.usage.output_tokens;
-          const toolUseBlocks = response.content.filter(
-            (block) => block.type === "tool_use"
-          );
-          for (const block of response.content) {
-            if (block.type === "text") captureMarkers(capture, block.text);
-          }
-          if (toolUseBlocks.length === 0 || response.stop_reason === "end_turn") {
-            break;
-          }
-          messages.push({
-            role: "assistant",
-            content: response.content.map((block) => {
-              if (block.type === "text") {
-                return { type: "text", text: block.text };
-              }
-              return {
-                type: "tool_use",
-                id: block.id,
-                name: block.name,
-                input: block.input
-              };
-            })
-          });
-          const toolResults = [];
-          for (const toolBlock of toolUseBlocks) {
-            const toolDef = params.tools.find((t) => t.name === toolBlock.name);
-            if (!toolDef) {
-              toolResults.push({
-                type: "tool_result",
-                tool_use_id: toolBlock.id,
-                content: `Tool '${toolBlock.name}' not found`,
-                is_error: true
-              });
-              continue;
-            }
-            const args = toolBlock.input ?? {};
-            captureSourceCode(capture, toolBlock.name, args);
-            const result = await toolDef.handler(args);
-            captureCompiledCode(capture, toolBlock.name, result);
-            toolResults.push({
-              type: "tool_result",
-              tool_use_id: toolBlock.id,
-              content: result.content.map((c) => ({ type: "text", text: c.text })),
-              is_error: result.isError
-            });
-          }
-          messages.push({ role: "user", content: toolResults });
-        }
-        if (!capture.compiledCode) {
-          throw new Error("Claude raw adapter: no compiled code produced after all turns");
-        }
-        return {
-          compiledCode: capture.compiledCode,
-          sourceCode: capture.sourceCode,
-          stream: capture.stream,
-          generatorMeta: capture.generatorMeta,
-          tokens: {
-            input: totalInputTokens,
-            output: totalOutputTokens,
-            total: totalInputTokens + totalOutputTokens
-          },
-          generationTimeMs: Date.now() - startTime,
-          turnsUsed
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/claude/source-capture.ts
-function sourceCodeFromToolUse(name, input) {
-  if (typeof name !== "string") return void 0;
-  const field = name === "Write" ? "content" : name.endsWith(COMPILE_TOOL_SUFFIX) ? "code" : void 0;
-  if (field === void 0 || typeof input !== "object" || input === null) return void 0;
-  const value = Reflect.get(input, field);
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-var COMPILE_TOOL_SUFFIX;
-var init_source_capture = __esm({
-  "src/adapters/claude/source-capture.ts"() {
-    COMPILE_TOOL_SUFFIX = "__compile_component";
-  }
-});
-
-// src/adapters/claude/message-parser.ts
-function createArtifacts() {
-  return {
-    compiledCode: "",
-    sourceCode: void 0,
-    stream: void 0,
-    generatorMeta: void 0,
-    sdkSessionId: void 0,
-    turnCount: 0,
-    inputTokens: 0,
-    outputTokens: 0,
-    cacheCreationTokens: 0,
-    cacheReadTokens: 0,
-    estimatedCostUsd: void 0,
-    subagentsUsed: []
-  };
-}
-function processMessage(message, artifacts, onProgress, maxTurns) {
-  extractSessionId(message, artifacts);
-  trackTurns(message, artifacts, onProgress, maxTurns);
-  trackTokenUsage(message, artifacts);
-  extractCompiledCode(message, artifacts, onProgress);
-  extractSourceCode(message, artifacts);
-  extractStreamSpec(message, artifacts);
-  extractGeneratorMeta(message, artifacts);
-}
-function extractSessionId(message, artifacts) {
-  if (message.type !== "system") return;
-  const systemMsg = message;
-  if (systemMsg.subtype === "init") {
-    artifacts.sdkSessionId = systemMsg.session_id;
-  }
-}
-function trackTurns(message, artifacts, onProgress, maxTurns) {
-  if (message.type !== "assistant") return;
-  const assistantMsg = message;
-  artifacts.turnCount++;
-  const contentBlocks = assistantMsg.message?.content;
-  if (Array.isArray(contentBlocks)) {
-    for (const block of contentBlocks) {
-      if (block.type === "tool_use") {
-        onProgress?.({ type: "tool_call", tool: block.name || "unknown" });
-      }
-    }
-  }
-  onProgress?.({ type: "turn", turn: artifacts.turnCount, maxTurns: maxTurns ?? 0 });
-}
-function trackTokenUsage(message, artifacts) {
-  if (message.type !== "result") return;
-  const resultMsg = message;
-  if (resultMsg.subtype === "success") {
-    const usage = resultMsg.usage;
-    artifacts.inputTokens = usage.input_tokens || 0;
-    artifacts.cacheCreationTokens = usage.cache_creation_input_tokens || 0;
-    artifacts.cacheReadTokens = usage.cache_read_input_tokens || 0;
-    artifacts.outputTokens = usage.output_tokens || 0;
-    artifacts.estimatedCostUsd = resultMsg.total_cost_usd;
-  }
-}
-function extractCompiledCode(message, artifacts, onProgress) {
-  if (artifacts.compiledCode) return;
-  const msgStr = JSON.stringify(message);
-  if (!msgStr.includes("compiledCode")) return;
-  const match = msgStr.match(/"compiledCode"\s*:\s*"([^"\\]*(\\.[^"\\]*)*)"/);
-  if (match) {
-    try {
-      artifacts.compiledCode = JSON.parse(`"${match[1]}"`);
-      onProgress?.({ type: "compiled", bytes: artifacts.compiledCode.length });
-      return;
-    } catch {
-    }
-  }
-  if (message.type === "user") {
-    const userMsg = message;
-    const code = extractFromToolResults(userMsg);
-    if (code) artifacts.compiledCode = code;
-  }
-}
-function extractFromToolResults(message) {
-  const content = message.message?.content;
-  if (!Array.isArray(content)) return void 0;
-  for (const item of content) {
-    if (typeof item === "object" && item !== null && "type" in item && item.type === "tool_result") {
-      const toolResultItem = item;
-      const code = parseCompiledCodeFromContent(toolResultItem.content);
-      if (code) return code;
-    }
-  }
-  return void 0;
-}
-function parseCompiledCodeFromContent(content) {
-  if (Array.isArray(content)) {
-    for (const item of content) {
-      const textItem = item;
-      if (textItem.type === "text" && textItem.text?.includes("compiledCode")) {
-        const code = tryParseCompiledCode(textItem.text);
-        if (code) return code;
-      }
-    }
-  }
-  if (typeof content === "string" && content.includes("compiledCode")) {
-    return tryParseCompiledCode(content);
-  }
-  return void 0;
-}
-function tryParseCompiledCode(text) {
-  try {
-    const parsed = JSON.parse(text);
-    if (parsed.success && parsed.compiledCode) return parsed.compiledCode;
-  } catch {
-  }
-  return void 0;
-}
-function extractSourceCode(message, artifacts) {
-  if (message.type !== "assistant") return;
-  const assistantMsg = message;
-  const content = assistantMsg.message?.content;
-  if (!Array.isArray(content)) return;
-  for (const block of content) {
-    if (block.type !== "tool_use") continue;
-    const value = sourceCodeFromToolUse(block.name, block.input);
-    if (value !== void 0) artifacts.sourceCode = value;
-  }
-}
-function unescapeJsonString(s) {
-  return s.replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
-}
-function extractMarker(msgStr, startMarker, endMarker) {
-  if (!msgStr.includes(startMarker)) return void 0;
-  const match = msgStr.match(new RegExp(`${startMarker}\\s*([\\s\\S]*?)\\s*${endMarker}`));
-  return match?.[1];
-}
-function extractStreamSpec(message, artifacts) {
-  if (artifacts.stream) return;
-  const raw = extractMarker(JSON.stringify(message), "__GGUI_STREAM_SPEC__", "__GGUI_STREAM_SPEC_END__");
-  if (!raw) return;
-  try {
-    artifacts.stream = JSON.parse(unescapeJsonString(raw));
-  } catch {
-  }
-}
-function extractGeneratorMeta(message, artifacts) {
-  if (artifacts.generatorMeta) return;
-  const raw = extractMarker(JSON.stringify(message), "__GGUI_META__", "__GGUI_META_END__");
-  if (!raw) return;
-  try {
-    const stripped = raw.replace(/```(?:json)?\s*/g, "").trim();
-    const parsed = JSON.parse(unescapeJsonString(stripped));
-    if (parsed.category) {
-      artifacts.generatorMeta = {
-        category: parsed.category,
-        description: parsed.description ?? ""
-      };
-    }
-  } catch {
-  }
-}
-var init_message_parser = __esm({
-  "src/adapters/claude/message-parser.ts"() {
-    init_source_capture();
-  }
-});
-
-// src/adapters/claude/tool-bridge.ts
-async function createToolMcpServer(tools) {
-  const { tool, createSdkMcpServer } = await import('@anthropic-ai/claude-agent-sdk');
-  const mcpTools = tools.map((def) => {
-    const shape = def.inputSchema.shape ?? {};
-    return tool(
-      def.name,
-      def.description,
-      shape,
-      async (args) => {
-        const result = await def.handler(args);
-        return {
-          content: result.content.map((c) => ({
-            type: "text",
-            text: c.text
-          })),
-          ...result.isError && { isError: true }
-        };
-      }
-    );
-  });
-  const server = createSdkMcpServer({
-    name: MCP_SERVER_NAME,
-    version: "1.0.0",
-    tools: mcpTools
-  });
-  const allowedToolNames = tools.map((t) => `mcp__${MCP_SERVER_NAME}__${t.name}`);
-  return { server, allowedToolNames };
-}
-var MCP_SERVER_NAME;
-var init_tool_bridge2 = __esm({
-  "src/adapters/claude/tool-bridge.ts"() {
-    MCP_SERVER_NAME = "ggui";
-  }
-});
-
-// src/adapters/claude/claude-code-login.ts
-function loginChildEnv(env) {
-  const out = {};
-  for (const [k, v] of Object.entries(env)) {
-    if (v !== void 0 && (LOGIN_CHILD_ENV.has(k) || k.startsWith("LC_"))) out[k] = v;
-  }
-  return out;
-}
-function claudeCodeLoginQueryOptions() {
-  return { tools: [], settingSources: [] };
-}
-var LOGIN_CHILD_ENV_NAMES, LOGIN_CHILD_ENV;
-var init_claude_code_login = __esm({
-  "src/adapters/claude/claude-code-login.ts"() {
-    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"
-    ];
-    LOGIN_CHILD_ENV = new Set(LOGIN_CHILD_ENV_NAMES);
-  }
-});
-
-// src/adapters/claude/sdk-tool-pins.ts
-function sdkToolPins(input) {
-  const builtins = [...input.builtinTools ?? []];
-  const approved = input.allowedTools !== void 0 ? [...input.allowedTools] : Object.keys(input.mcpServers ?? {}).map((name) => `mcp__${name}`);
-  return { tools: builtins, settingSources: [], allowedTools: [...approved, ...builtins] };
-}
-var init_sdk_tool_pins = __esm({
-  "src/adapters/claude/sdk-tool-pins.ts"() {
-  }
-});
-
-// src/adapters/claude/sdk.ts
-var sdk_exports = {};
-__export(sdk_exports, {
-  ClaudeSdkAdapter: () => ClaudeSdkAdapter
-});
-function buildEnv(configEnv) {
-  if (configEnv) return sanitizeEnv({ ...configEnv });
-  const env = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value !== void 0) env[key] = value;
-  }
-  return sanitizeEnv(env);
-}
-function sanitizeEnv(env) {
-  if (env.ANTHROPIC_BASE_URL?.includes("localhost")) {
-    delete env.ANTHROPIC_BASE_URL;
-  }
-  return env;
-}
-var ClaudeSdkAdapter;
-var init_sdk = __esm({
-  "src/adapters/claude/sdk.ts"() {
-    init_base();
-    init_message_parser();
-    init_tool_bridge2();
-    init_claude_code_login();
-    init_sdk_tool_pins();
-    ClaudeSdkAdapter = class extends GeneratorAdapter {
-      provider = "claude";
-      mode = "sdk";
-      displayName = "Claude (Agent SDK)";
-      constructor(config = {}) {
-        super(config);
-      }
-      /** Narrowed config access for Claude SDK-specific fields. */
-      get sdkConfig() {
-        return this.config;
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "ANTHROPIC_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        const cfg = this.sdkConfig;
-        const { query } = await import('@anthropic-ai/claude-agent-sdk');
-        const login = cfg.claudeCodeLogin === true;
-        const env = login ? loginChildEnv(buildEnv(cfg.env)) : buildEnv(cfg.env);
-        const artifacts = createArtifacts();
-        const onProgress = cfg.onProgress;
-        let mcpServers = cfg.mcpServers;
-        let allowedTools = cfg.allowedTools;
-        if (!mcpServers && params.tools.length > 0) {
-          const bridge = await createToolMcpServer(params.tools);
-          mcpServers = { ggui: bridge.server };
-          allowedTools = bridge.allowedToolNames;
-        }
-        for await (const message of query({
-          prompt: params.userPrompt,
-          options: {
-            cwd: cfg.cwd,
-            env,
-            model: params.model,
-            maxTurns: params.maxTurns,
-            systemPrompt: params.systemPrompt,
-            ...mcpServers && { mcpServers },
-            ...cfg.agents && { agents: cfg.agents },
-            // 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.
-            ...login ? claudeCodeLoginQueryOptions() : {}
-          }
-        })) {
-          processMessage(
-            message,
-            artifacts,
-            onProgress,
-            params.maxTurns
-          );
-        }
-        const generationTimeMs = Date.now() - startTime;
-        const totalCacheIn = artifacts.inputTokens + artifacts.cacheCreationTokens + artifacts.cacheReadTokens;
-        const cacheReadPct = totalCacheIn > 0 ? Math.round(artifacts.cacheReadTokens / totalCacheIn * 100) : 0;
-        console.log(
-          `[claude-sdk] cache: created=${artifacts.cacheCreationTokens} read=${artifacts.cacheReadTokens} input=${artifacts.inputTokens} output=${artifacts.outputTokens} turns=${artifacts.turnCount} cache-read-pct=${cacheReadPct}%`
-        );
-        if (!artifacts.compiledCode) {
-          const wasExhausted = artifacts.turnCount >= params.maxTurns;
-          throw new Error(
-            wasExhausted ? `Generation used all ${params.maxTurns} turns without producing compiled code.` : "Generation completed without compiled code"
-          );
-        }
-        return {
-          compiledCode: artifacts.compiledCode,
-          sourceCode: artifacts.sourceCode,
-          tokens: {
-            input: artifacts.inputTokens,
-            output: artifacts.outputTokens,
-            total: artifacts.inputTokens + artifacts.cacheCreationTokens + artifacts.cacheReadTokens + artifacts.outputTokens
-          },
-          generationTimeMs,
-          turnsUsed: artifacts.turnCount,
-          rawCostUsd: artifacts.estimatedCostUsd,
-          stream: artifacts.stream,
-          generatorMeta: artifacts.generatorMeta,
-          subagentsUsed: artifacts.subagentsUsed,
-          cacheCreationTokens: artifacts.cacheCreationTokens,
-          cacheReadTokens: artifacts.cacheReadTokens,
-          sdkSessionId: artifacts.sdkSessionId
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/openai/tokens.ts
-function splitOpenAiUsage(inputTokensInclCached, outputTokens, cachedTokens) {
-  return splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens);
-}
-function splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens) {
-  const cacheRead = Math.min(
-    Math.max(cachedTokens, 0),
-    Math.max(inputTokensInclCached, 0)
-  );
-  const nonCachedInput = Math.max(inputTokensInclCached, 0) - cacheRead;
-  return {
-    tokens: {
-      input: nonCachedInput,
-      output: outputTokens,
-      total: nonCachedInput + cacheRead + outputTokens
-    },
-    cacheReadTokens: cacheRead
-  };
-}
-var init_tokens = __esm({
-  "src/adapters/openai/tokens.ts"() {
-  }
-});
-
-// src/adapters/openai/raw.ts
-var raw_exports2 = {};
-__export(raw_exports2, {
-  OpenAiRawAdapter: () => OpenAiRawAdapter
-});
-async function loadOpenAI() {
-  return import('openai');
-}
-function toResponsesTool(def) {
-  return {
-    type: "function",
-    name: def.name,
-    description: def.description,
-    parameters: zodToJsonSchema(def.inputSchema),
-    strict: false
-  };
-}
-var OpenAiRawAdapter;
-var init_raw2 = __esm({
-  "src/adapters/openai/raw.ts"() {
-    init_base();
-    init_tool_bridge();
-    init_tokens();
-    init_extract_code();
-    OpenAiRawAdapter = class extends GeneratorAdapter {
-      provider = "openai";
-      mode = "raw";
-      displayName = "OpenAI (Raw API)";
-      client = null;
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "OPENAI_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        if (!this.client) {
-          const { default: OpenAIClient } = await loadOpenAI();
-          this.client = new OpenAIClient({
-            apiKey: this.config.apiKey || process.env.OPENAI_API_KEY
-          });
-        }
-        const tools = params.tools.map(toResponsesTool);
-        const capture = createCapture();
-        let totalInputTokens = 0;
-        let totalOutputTokens = 0;
-        let totalCachedInputTokens = 0;
-        let turnsUsed = 0;
-        let allTextOutput = "";
-        let response = await this.client.responses.create({
-          model: params.model,
-          instructions: params.systemPrompt,
-          input: [{ role: "user", content: params.userPrompt }],
-          tools,
-          store: true
-          // Required for previous_response_id to work on subsequent turns
-        });
-        for (let turn = 0; turn < params.maxTurns; turn++) {
-          turnsUsed = turn + 1;
-          if (response.usage) {
-            totalInputTokens += response.usage.input_tokens ?? 0;
-            totalOutputTokens += response.usage.output_tokens ?? 0;
-            totalCachedInputTokens += response.usage.input_tokens_details?.cached_tokens ?? 0;
-          }
-          const output = response.output ?? [];
-          const functionCalls = output.filter(
-            (item) => item.type === "function_call"
-          );
-          for (const item of output) {
-            if (item.type === "message" && "content" in item && item.content) {
-              for (const part of item.content) {
-                if (part.type === "output_text" && part.text) {
-                  allTextOutput += part.text + "\n";
-                  captureMarkers(capture, part.text);
-                }
-              }
-            }
-          }
-          if (functionCalls.length === 0) break;
-          const nextInput = [];
-          for (const fc of functionCalls) {
-            const toolDef = params.tools.find((t) => t.name === fc.name);
-            if (!toolDef) {
-              nextInput.push({
-                type: "function_call_output",
-                call_id: fc.call_id,
-                output: JSON.stringify({ error: `Tool '${fc.name}' not found` })
-              });
-              continue;
-            }
-            let args = {};
-            try {
-              args = JSON.parse(fc.arguments || "{}");
-            } catch {
-            }
-            captureSourceCode(capture, fc.name, args);
-            const result = await toolDef.handler(args);
-            captureCompiledCode(capture, fc.name, result);
-            nextInput.push({
-              type: "function_call_output",
-              call_id: fc.call_id,
-              output: result.content[0]?.text ?? ""
-            });
-          }
-          response = await this.client.responses.create({
-            model: params.model,
-            instructions: params.systemPrompt,
-            input: nextInput,
-            tools,
-            previous_response_id: response.id,
-            store: true
-          });
-        }
-        if (!capture.compiledCode && allTextOutput) {
-          captureMarkers(capture, allTextOutput);
-          await extractCodeFromText(allTextOutput, params.tools, capture);
-        }
-        if (!capture.compiledCode) {
-          await compileLastResort(capture, allTextOutput);
-        }
-        if (!capture.compiledCode) {
-          throw new Error("OpenAI raw adapter: no compiled code produced after all turns");
-        }
-        return {
-          compiledCode: capture.compiledCode,
-          sourceCode: capture.sourceCode,
-          stream: capture.stream,
-          generatorMeta: capture.generatorMeta,
-          ...splitOpenAiUsage(
-            totalInputTokens,
-            totalOutputTokens,
-            totalCachedInputTokens
-          ),
-          generationTimeMs: Date.now() - startTime,
-          turnsUsed
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/openai/sdk.ts
-var sdk_exports2 = {};
-__export(sdk_exports2, {
-  OpenAiSdkAdapter: () => OpenAiSdkAdapter
-});
-async function loadOpenAIAgents() {
-  return import('@openai/agents');
-}
-var OpenAiSdkAdapter;
-var init_sdk2 = __esm({
-  "src/adapters/openai/sdk.ts"() {
-    init_base();
-    init_tokens();
-    init_extract_code();
-    OpenAiSdkAdapter = class extends GeneratorAdapter {
-      provider = "openai";
-      mode = "sdk";
-      displayName = "OpenAI (Agents SDK)";
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "OPENAI_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        const apiKey = this.config.apiKey || process.env.OPENAI_API_KEY;
-        if (apiKey) process.env.OPENAI_API_KEY = apiKey;
-        const capture = createCapture();
-        const { Agent, run, tool } = await loadOpenAIAgents();
-        const wiredTools = params.tools.map(
-          (def) => tool({
-            name: def.name,
-            description: def.description,
-            parameters: def.inputSchema,
-            execute: async (args) => {
-              const typedArgs = args ?? {};
-              captureSourceCode(capture, def.name, typedArgs);
-              const result2 = await def.handler(typedArgs);
-              captureCompiledCode(capture, def.name, result2);
-              return result2.content[0]?.text ?? "";
-            }
-          })
-        );
-        const agent = new Agent({
-          name: "ui-generator",
-          instructions: params.systemPrompt,
-          model: params.model,
-          tools: wiredTools
-        });
-        const result = await run(agent, params.userPrompt, {
-          maxTurns: params.maxTurns
-        });
-        const finalOutput = String(result.finalOutput ?? "");
-        if (finalOutput) captureMarkers(capture, finalOutput);
-        if (!capture.compiledCode) {
-          await extractCodeFromText(finalOutput, params.tools, capture);
-          if (!capture.compiledCode) {
-            throw new Error("OpenAI SDK adapter: no compiled code produced after all turns");
-          }
-        }
-        const usage = result.state.usage;
-        const inputTokens = usage.inputTokens;
-        const outputTokens = usage.outputTokens;
-        const cachedInputTokens = (usage.inputTokensDetails ?? []).reduce(
-          (sum, details) => sum + (details.cached_tokens ?? 0),
-          0
-        );
-        return {
-          compiledCode: capture.compiledCode,
-          sourceCode: capture.sourceCode,
-          stream: capture.stream,
-          generatorMeta: capture.generatorMeta,
-          ...splitOpenAiUsage(inputTokens, outputTokens, cachedInputTokens),
-          generationTimeMs: Date.now() - startTime,
-          turnsUsed: result.rawResponses?.length ?? 0
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/google/raw.ts
-var raw_exports3 = {};
-__export(raw_exports3, {
-  GoogleRawAdapter: () => GoogleRawAdapter
-});
-async function loadGoogleGenAI() {
-  return import('@google/genai');
-}
-function toInteractionTool(def) {
-  return {
-    type: "function",
-    name: def.name,
-    description: def.description,
-    parameters: zodToJsonSchema(def.inputSchema)
-  };
-}
-var GoogleRawAdapter;
-var init_raw3 = __esm({
-  "src/adapters/google/raw.ts"() {
-    init_base();
-    init_tool_bridge();
-    init_extract_code();
-    GoogleRawAdapter = class extends GeneratorAdapter {
-      provider = "google";
-      mode = "raw";
-      displayName = "Google Gemini (Interactions API)";
-      client = null;
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "GEMINI_API_KEY", "GOOGLE_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        if (!this.client) {
-          const { GoogleGenAI } = await loadGoogleGenAI();
-          this.client = new GoogleGenAI({
-            apiKey: this.config.apiKey || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
-            httpOptions: { timeout: 3e5 }
-            // 5 min — Pro models can be slow
-          });
-        }
-        const tools = params.tools.map(toInteractionTool);
-        const capture = createCapture();
-        let totalInputTokens = 0;
-        let totalOutputTokens = 0;
-        let turnsUsed = 0;
-        const thinkingLevel = this.config.thinkingLevel;
-        const generationConfig = thinkingLevel ? { thinking_level: thinkingLevel } : void 0;
-        let interaction = await this.client.interactions.create({
-          model: params.model,
-          system_instruction: params.systemPrompt,
-          tools,
-          input: params.userPrompt,
-          ...generationConfig ? { generation_config: generationConfig } : {}
-        });
-        for (let turn = 0; turn < params.maxTurns; turn++) {
-          turnsUsed = turn + 1;
-          if (interaction.usage) {
-            totalInputTokens += interaction.usage.total_input_tokens ?? 0;
-            totalOutputTokens += interaction.usage.total_output_tokens ?? 0;
-          }
-          for (const step of interaction.steps) {
-            if (step.type === "model_output") {
-              for (const content of step.content ?? []) {
-                if (content.type === "text") {
-                  captureMarkers(capture, content.text);
-                }
-              }
-            }
-          }
-          const functionCalls = interaction.steps.filter(
-            (s) => s.type === "function_call"
-          );
-          if (functionCalls.length === 0) break;
-          const results = [];
-          for (const fc of functionCalls) {
-            const toolDef = params.tools.find((t) => t.name === fc.name);
-            if (!toolDef) {
-              results.push({
-                type: "function_result",
-                call_id: fc.id,
-                name: fc.name,
-                result: JSON.stringify({ error: `Tool '${fc.name}' not found` }),
-                is_error: true
-              });
-              continue;
-            }
-            const args = toolArgsToJsonObject(fc.arguments);
-            captureSourceCode(capture, fc.name, args);
-            const result = await toolDef.handler(args);
-            captureCompiledCode(capture, fc.name, result);
-            results.push({
-              type: "function_result",
-              call_id: fc.id,
-              name: fc.name,
-              result: result.content[0]?.text ?? ""
-            });
-          }
-          interaction = await this.client.interactions.create({
-            model: params.model,
-            previous_interaction_id: interaction.id,
-            input: results,
-            ...generationConfig ? { generation_config: generationConfig } : {}
-          });
-        }
-        if (!capture.compiledCode) {
-          throw new Error("Google raw adapter: no compiled code produced after all turns");
-        }
-        return {
-          compiledCode: capture.compiledCode,
-          sourceCode: capture.sourceCode,
-          stream: capture.stream,
-          generatorMeta: capture.generatorMeta,
-          tokens: {
-            input: totalInputTokens,
-            output: totalOutputTokens,
-            total: totalInputTokens + totalOutputTokens
-          },
-          generationTimeMs: Date.now() - startTime,
-          turnsUsed
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/google/sdk.ts
-var sdk_exports3 = {};
-__export(sdk_exports3, {
-  GoogleSdkAdapter: () => GoogleSdkAdapter,
-  runAdkLoop: () => runAdkLoop
-});
-async function runAdkLoop(params) {
-  const startTime = Date.now();
-  const { FunctionTool, Gemini, LlmAgent, InMemoryRunner, isFinalResponse } = await import('@google/adk');
-  const capture = createCapture();
-  const adkTools = params.tools.map(
-    (def) => new FunctionTool({
-      name: def.name,
-      description: def.description,
-      // Pass Zod schema directly — ADK accepts ZodObject natively
-      parameters: def.inputSchema,
-      execute: async (args) => {
-        const typedArgs = args ?? {};
-        captureSourceCode(capture, def.name, typedArgs);
-        const result = await def.handler(typedArgs);
-        captureCompiledCode(capture, def.name, result);
-        return result.content[0]?.text ?? "";
-      }
-    })
-  );
-  const model = params.apiKey ? new Gemini({ model: params.model, apiKey: params.apiKey }) : params.model;
-  const agent = new LlmAgent({
-    name: "ui_generator",
-    model,
-    instruction: params.systemPrompt,
-    tools: adkTools
-  });
-  const runner = new InMemoryRunner({ agent, appName: "ggui_generator" });
-  const session = await runner.sessionService.createSession({
-    appName: "ggui_generator",
-    userId: "benchmark"
-  });
-  const userMessage = {
-    role: "user",
-    parts: [{ text: params.userPrompt }]
-  };
-  let finalText = "";
-  let turnCount = 0;
-  let totalInputTokens = 0;
-  let totalOutputTokens = 0;
-  for await (const event of runner.runAsync({
-    userId: "benchmark",
-    sessionId: session.id,
-    newMessage: userMessage
-  })) {
-    turnCount++;
-    const usage = event.usageMetadata;
-    if (usage) {
-      totalInputTokens += usage.promptTokenCount ?? 0;
-      totalOutputTokens += usage.candidatesTokenCount ?? 0;
-    }
-    if (event.content?.parts) {
-      const text = event.content.parts.map((p) => p.text ?? "").join("");
-      if (text) captureMarkers(capture, text);
-    }
-    if (isFinalResponse(event)) {
-      const parts = event.content?.parts;
-      finalText = parts?.map((p) => p.text ?? "").join("") ?? "";
-    }
-  }
-  if (finalText) captureMarkers(capture, finalText);
-  if (!capture.compiledCode) {
-    throw new Error("Google ADK adapter: no compiled code produced after all turns");
-  }
-  return {
-    compiledCode: capture.compiledCode,
-    sourceCode: capture.sourceCode,
-    stream: capture.stream,
-    generatorMeta: capture.generatorMeta,
-    tokens: {
-      input: totalInputTokens,
-      output: totalOutputTokens,
-      total: totalInputTokens + totalOutputTokens
-    },
-    generationTimeMs: Date.now() - startTime,
-    turnsUsed: turnCount
-  };
-}
-var GoogleSdkAdapter;
-var init_sdk3 = __esm({
-  "src/adapters/google/sdk.ts"() {
-    init_base();
-    init_extract_code();
-    GoogleSdkAdapter = class extends GeneratorAdapter {
-      provider = "google";
-      mode = "sdk";
-      displayName = "Google Gemini (ADK)";
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "GEMINI_API_KEY", "GOOGLE_API_KEY");
-      }
-      async generate(params) {
-        const apiKey = this.config.apiKey || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
-        return runAdkLoop({
-          systemPrompt: params.systemPrompt,
-          userPrompt: params.userPrompt,
-          model: params.model,
-          tools: params.tools,
-          apiKey
-        });
-      }
-    };
-  }
-});
-
-// src/adapters/openrouter/types.ts
-var OpenRouterError;
-var init_types = __esm({
-  "src/adapters/openrouter/types.ts"() {
-    OpenRouterError = class extends Error {
-      constructor(message, status, code, headers) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.headers = headers;
-        this.name = "OpenRouterError";
-      }
-      status;
-      code;
-      headers;
-      get isTransient() {
-        return this.status === 408 || this.status === 429 || this.status === 502 || this.status === 503;
-      }
-    };
-  }
-});
-
-// src/adapters/openrouter/client.ts
-var DEFAULT_BASE_URL, OpenRouterClient;
-var init_client2 = __esm({
-  "src/adapters/openrouter/client.ts"() {
-    init_types();
-    DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
-    OpenRouterClient = class {
-      constructor(config) {
-        this.config = config;
-        this.baseUrl = config.baseUrl ?? process.env.OPENROUTER_BASE_URL ?? DEFAULT_BASE_URL;
-        this.headers = {
-          "Authorization": `Bearer ${config.apiKey}`,
-          "Content-Type": "application/json",
-          "HTTP-Referer": config.siteUrl ?? process.env.OPENROUTER_SITE_URL ?? "https://ggui.ai",
-          "X-Title": config.siteName ?? process.env.OPENROUTER_SITE_NAME ?? "ggui"
-        };
-      }
-      config;
-      baseUrl;
-      headers;
-      /**
-       * Non-streaming chat completion.
-       */
-      async chatCompletion(params) {
-        const body = { ...params, stream: false };
-        const response = await fetch(`${this.baseUrl}/chat/completions`, {
-          method: "POST",
-          headers: this.headers,
-          body: JSON.stringify(body)
-        });
-        if (!response.ok) {
-          const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
-          const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status, void 0, response.headers);
-        }
-        return response.json();
-      }
-      /**
-       * Streaming chat completion via SSE.
-       * Yields delta chunks, accumulates the final usage from the last chunk.
-       */
-      async *chatCompletionStream(params) {
-        const body = { ...params, stream: true };
-        const response = await fetch(`${this.baseUrl}/chat/completions`, {
-          method: "POST",
-          headers: this.headers,
-          body: JSON.stringify(body)
-        });
-        if (!response.ok) {
-          const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
-          const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status, void 0, response.headers);
-        }
-        if (!response.body) {
-          throw new OpenRouterError("No response body for streaming request", 500);
-        }
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split("\n");
-            buffer = lines.pop() ?? "";
-            for (const line of lines) {
-              const trimmed = line.trim();
-              if (!trimmed || trimmed.startsWith(":")) continue;
-              if (trimmed === "data: [DONE]") return;
-              if (!trimmed.startsWith("data: ")) continue;
-              const json = trimmed.slice("data: ".length);
-              try {
-                yield JSON.parse(json);
-              } catch {
-              }
-            }
-          }
-        } finally {
-          reader.releaseLock();
-        }
-      }
-    };
-  }
-});
-
-// src/adapters/openrouter/raw.ts
-var raw_exports4 = {};
-__export(raw_exports4, {
-  OpenRouterRawAdapter: () => OpenRouterRawAdapter
-});
-function toOpenRouterTool(def) {
-  return {
-    type: "function",
-    function: {
-      name: def.name,
-      description: def.description,
-      parameters: zodToJsonSchema(def.inputSchema)
-    }
-  };
-}
-var OpenRouterRawAdapter;
-var init_raw4 = __esm({
-  "src/adapters/openrouter/raw.ts"() {
-    init_base();
-    init_tool_bridge();
-    init_extract_code();
-    init_client2();
-    OpenRouterRawAdapter = class extends GeneratorAdapter {
-      provider = "openrouter";
-      mode = "raw";
-      displayName = "OpenRouter (Raw API)";
-      client = null;
-      constructor(config = {}) {
-        super(config);
-      }
-      isAvailable() {
-        return hasCredentials(this.config, "OPENROUTER_API_KEY");
-      }
-      async generate(params) {
-        const startTime = Date.now();
-        if (!this.client) {
-          this.client = new OpenRouterClient({
-            apiKey: this.config.apiKey || process.env.OPENROUTER_API_KEY
-          });
-        }
-        const tools = params.tools.map(toOpenRouterTool);
-        const capture = createCapture();
-        let totalInputTokens = 0;
-        let totalOutputTokens = 0;
-        let cacheCreationTokens;
-        let cacheReadTokens;
-        let turnsUsed = 0;
-        let allTextOutput = "";
-        const modelId = params.model;
-        const isAnthropicModel = modelId.includes("anthropic/") || modelId.includes("claude");
-        const systemMessage = isAnthropicModel ? {
-          role: "system",
-          content: [{ type: "text", text: params.systemPrompt, cache_control: { type: "ephemeral" } }]
-        } : { role: "system", content: params.systemPrompt };
-        const messages = [
-          systemMessage,
-          { role: "user", content: params.userPrompt }
-        ];
-        for (let turn = 0; turn < params.maxTurns; turn++) {
-          turnsUsed = turn + 1;
-          const response = await this.client.chatCompletion({
-            model: modelId,
-            messages,
-            tools: tools.length > 0 ? tools : void 0,
-            tool_choice: tools.length > 0 ? "auto" : void 0,
-            max_tokens: 16384
-          });
-          if (response.usage) {
-            totalInputTokens += response.usage.prompt_tokens;
-            totalOutputTokens += response.usage.completion_tokens;
-            if (response.usage.cache_creation_input_tokens) {
-              cacheCreationTokens = (cacheCreationTokens ?? 0) + response.usage.cache_creation_input_tokens;
-            }
-            if (response.usage.cache_read_input_tokens) {
-              cacheReadTokens = (cacheReadTokens ?? 0) + response.usage.cache_read_input_tokens;
-            }
-          }
-          const choice = response.choices[0];
-          if (!choice) break;
-          if (choice.message.content) {
-            allTextOutput += choice.message.content + "\n";
-            captureMarkers(capture, choice.message.content);
-          }
-          const toolCalls = choice.message.tool_calls;
-          if (!toolCalls || toolCalls.length === 0) break;
-          messages.push({
-            role: "assistant",
-            content: choice.message.content,
-            tool_calls: toolCalls
-          });
-          for (const tc of toolCalls) {
-            const toolDef = params.tools.find((t) => t.name === tc.function.name);
-            if (!toolDef) {
-              messages.push({
-                role: "tool",
-                tool_call_id: tc.id,
-                content: JSON.stringify({ error: `Tool '${tc.function.name}' not found` })
-              });
-              continue;
-            }
-            let args = {};
-            try {
-              args = JSON.parse(tc.function.arguments || "{}");
-            } catch {
-            }
-            captureSourceCode(capture, tc.function.name, args);
-            const result = await toolDef.handler(args);
-            captureCompiledCode(capture, tc.function.name, result);
-            messages.push({
-              role: "tool",
-              tool_call_id: tc.id,
-              content: result.content[0]?.text ?? ""
-            });
-          }
-        }
-        if (!capture.compiledCode && allTextOutput) {
-          captureMarkers(capture, allTextOutput);
-          await extractCodeFromText(allTextOutput, params.tools, capture);
-        }
-        if (!capture.compiledCode) {
-          await compileLastResort(capture, allTextOutput);
-        }
-        if (!capture.compiledCode) {
-          throw new Error("OpenRouter raw adapter: no compiled code produced after all turns");
-        }
-        return {
-          compiledCode: capture.compiledCode,
-          sourceCode: capture.sourceCode,
-          stream: capture.stream,
-          generatorMeta: capture.generatorMeta,
-          tokens: {
-            input: totalInputTokens,
-            output: totalOutputTokens,
-            total: totalInputTokens + totalOutputTokens
-          },
-          generationTimeMs: Date.now() - startTime,
-          turnsUsed,
-          cacheCreationTokens,
-          cacheReadTokens
-        };
-      }
-    };
-  }
-});
-
-// src/adapters/types.ts
-var PROVIDER_DISPLAY_NAMES = {
-  claude: "Anthropic Claude",
-  openai: "OpenAI",
-  google: "Google Gemini",
-  openrouter: "OpenRouter"
-};
-
-// src/adapters/index.ts
-init_base();
-
-// src/adapters/registry.ts
-var ADAPTER_FACTORIES = {};
-function registerProvider(provider, factories) {
-  ADAPTER_FACTORIES[provider] = factories;
-}
-registerProvider("claude", {
-  raw: async (config) => {
-    const { ClaudeRawAdapter: ClaudeRawAdapter2 } = await Promise.resolve().then(() => (init_raw(), raw_exports));
-    return new ClaudeRawAdapter2(config);
-  },
-  sdk: async (config) => {
-    const { ClaudeSdkAdapter: ClaudeSdkAdapter2 } = await Promise.resolve().then(() => (init_sdk(), sdk_exports));
-    return new ClaudeSdkAdapter2(config);
-  }
-});
-registerProvider("openai", {
-  raw: async (config) => {
-    const { OpenAiRawAdapter: OpenAiRawAdapter2 } = await Promise.resolve().then(() => (init_raw2(), raw_exports2));
-    return new OpenAiRawAdapter2(config);
-  },
-  sdk: async (config) => {
-    const { OpenAiSdkAdapter: OpenAiSdkAdapter2 } = await Promise.resolve().then(() => (init_sdk2(), sdk_exports2));
-    return new OpenAiSdkAdapter2(config);
-  }
-});
-registerProvider("google", {
-  raw: async (config) => {
-    const { GoogleRawAdapter: GoogleRawAdapter2 } = await Promise.resolve().then(() => (init_raw3(), raw_exports3));
-    return new GoogleRawAdapter2(config);
-  },
-  sdk: async (config) => {
-    const { GoogleSdkAdapter: GoogleSdkAdapter2 } = await Promise.resolve().then(() => (init_sdk3(), sdk_exports3));
-    return new GoogleSdkAdapter2(config);
-  }
-});
-registerProvider("openrouter", {
-  raw: async (config) => {
-    const { OpenRouterRawAdapter: OpenRouterRawAdapter2 } = await Promise.resolve().then(() => (init_raw4(), raw_exports4));
-    return new OpenRouterRawAdapter2(config);
-  }
-});
-async function getAdapter(provider, mode, config = {}) {
-  const providerFactories = ADAPTER_FACTORIES[provider];
-  if (!providerFactories) {
-    throw new Error(
-      `Unknown provider: ${provider}. Available: ${Object.keys(ADAPTER_FACTORIES).join(", ")}`
-    );
-  }
-  const factory = providerFactories[mode];
-  if (!factory) {
-    throw new Error(
-      `Unknown mode '${mode}' for provider '${provider}'. Available: ${Object.keys(providerFactories).join(", ")}`
-    );
-  }
-  return factory(config);
-}
-async function listAdapters(config = {}) {
-  const result = [];
-  for (const [provider, modes] of Object.entries(ADAPTER_FACTORIES)) {
-    for (const mode of Object.keys(modes)) {
-      try {
-        const factory = ADAPTER_FACTORIES[provider]?.[mode];
-        if (!factory) continue;
-        const adapter = await factory(config);
-        result.push({
-          provider,
-          mode,
-          available: adapter.isAvailable(),
-          displayName: adapter.displayName
-        });
-      } catch {
-        result.push({
-          provider,
-          mode,
-          available: false,
-          displayName: `${provider}/${mode} (not installed)`
-        });
-      }
-    }
-  }
-  return result;
-}
-
-// src/validation/primitives.ts
-var PRIMITIVES_DOCUMENTATION = "# ggui Primitives & Design System Reference\n\n> You are a world-class UI engineer working with ggui's component library for the first time.\n> This reference documents every available component, prop, and convention.\n> Components handle theming automatically via built-in variants \u2014 pick the right variant and the theme does the rest.\n> For custom styling beyond variants, use CSS variables: var(--ggui-*, fallback).\n\n## Primitives\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Container\n\nContainer -- Width-constrained wrapper that centers content horizontally.\n\nRenders a `<div>` with `width: 100%` and a `maxWidth` constraint.\nWhen `center` is true (the default), applies `margin: 0 auto`.\nNo background, border, or shadow -- use Card for visual containment.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| maxWidth | `'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| 'full' \\| string` | `'lg'` | Maximum width constraint. Accepts a preset token or any CSS width string. - `'xs'` -- 320px - `'sm'` -- 480px - `'md'` -- 640px - `'lg'` -- 768px - `'xl'` -- 1024px - `'2xl'` -- 1280px - `'3xl'` -- 1536px - `'full'` -- 100%  Custom strings (e.g., `'900px'`, `'60ch'`) are passed through as-is. |\n| center | `boolean` | `true` | Whether to center the container horizontally via `margin: 0 auto`. |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n```\n\n### Card\n\nCard -- Container with background, shadow, and optional border.\n\nRenders a `<div>` with:\n- Background: `var(--ggui-color-container)`\n- Border (when enabled): `1px solid var(--ggui-color-outlineVariant)`\n- Shadow and radius controlled by design tokens via CSS variables.\n- No built-in transitions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'lg'` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| shadow | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'sm'` | Shadow elevation level. Maps to design tokens: - `'none'` -- no shadow - `'sm'` -- var(--ggui-shape-shadow-sm) -- subtle, default - `'md'` -- var(--ggui-shape-shadow-md) -- dialogs, emphasized sections - `'lg'` -- var(--ggui-shape-shadow-lg) -- floating panels - `'xl'` -- var(--ggui-shape-shadow-xl) -- popovers, modals |\n| border | `boolean` | `true` | Whether to render a 1px border using `var(--ggui-color-outlineVariant)`. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'lg'` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `'default'` | Semantic surface slot. Same vocabulary as ; see that prop's docs for the full slot table. Default Card surface is `'default'` (the active theme's `--ggui-color-container`); pair with `shadow=\"md\"\\|\"lg\"` for elevated cards, `'hero'` for a greeting or hero card (the theme's hero ground, right on a light or a dark host), or `'inverted'` for a dark testimonial-style card on a light theme. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n\n**Example:**\n```tsx\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n```\n\n### Stack\n\nStack -- Flexbox layout primitive for arranging children along a single axis.\n\nRenders a `<div>` with `display: flex`. Default layout is vertical (column).\nAll flex shorthand values (`align`, `justify`, `wrap`) are abstracted into\nsemantic prop names.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Main axis direction. - `'vertical'` -- `flex-direction: column` - `'horizontal'` -- `flex-direction: row` |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'sm'` | Gap between children. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| align | `'start' \\| 'center' \\| 'end' \\| 'stretch'` | `'stretch'` | Cross-axis alignment (maps to `align-items`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'stretch'` -- stretch (children fill cross-axis) |\n| justify | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'` | Main-axis content distribution (maps to `justify-content`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'between'` -- space-between - `'around'` -- space-around - `'evenly'` -- space-evenly |\n| wrap | `boolean` | `false` | Whether children wrap to the next line when they overflow. Maps to `flex-wrap: wrap` when true. |\n\n**Example:**\n```tsx\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n```\n\n### Grid\n\nGrid -- 2-D layout primitive. Arranges children into rows AND\ncolumns; reach for it when Stack/Row's single-axis flow isn't\nenough (card galleries, dashboards, stat grids).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| columns | `number \\| ResponsiveColumns` | `2` | Column count. Three forms: - a number \u2014 that many equal columns at every width (`columns={3}`); - a  map \u2014 explicit counts per breakpoint   (`columns={{ base: 1, md: 3 }}` = 1 column on mobile, 3 from `md`).   Use this when the request names exact per-breakpoint counts   (\"3 per row on desktop, 1 on mobile\"). Ignored entirely when `minColumnWidth` is set. |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'md'` | Gap between cells. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`); a number is pixels. |\n| minColumnWidth | `number \\| string` | `undefined (use `columns`)` | When set, the grid becomes responsive \u2014 it fits as many equal columns as possible, each at least this wide, and `columns` is ignored. A number is treated as pixels. |\n\n**Example:**\n```tsx\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n```\n\n### Skeleton\n\nSkeleton -- a pulsing placeholder for content that has not loaded\nyet. ggui UIs are agent-driven (props arrive late, streams start\nempty), so a loading frame is the rule \u2014 render `Skeleton` instead\nof a blank screen or a hand-rolled pulsing `<div>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| variant | `'rect' \\| 'text' \\| 'circle'` | `'rect'` | Shape preset. - `'rect'` -- a block (default); pair with `width` / `height`. - `'text'` -- a single text line (height ~1em). - `'circle'` -- equal width/height, fully rounded (avatar slot). |\n| width | `number \\| string` | - | Width. A number is pixels. Defaults to `100%` (`2.5rem` for circle). |\n| height | `number \\| string` | - | Height. A number is pixels. Defaults by variant when unset. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'sm'` | Corner radius. Prefer a radius-scale name. Ignored for `variant=\"circle\"` (always fully round). |\n\n**Example:**\n```tsx\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n```\n\n### Box\n\nBox -- Generic container with padding, margin, background, and border-radius.\n\nRenders a plain `<div>`. Unlike Card, Box has no default background, shadow,\nor border -- it is a blank canvas for custom styling. Use it for layout\nspacing, colored sections, or wrapping arbitrary content.\n\nWhen both `paddingX`/`paddingY` and `padding` are provided, the axis-specific\nprops take precedence and `padding` is ignored.\n\nCSS variables used: none (all values are passed through directly).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all four sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. Ignored when `paddingX` or `paddingY` is set. |\n| paddingX | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Horizontal (left + right) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingY`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingY`, vertical padding defaults to 0. |\n| paddingY | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Vertical (top + bottom) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingX`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingX`, horizontal padding defaults to 0. |\n| margin | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no margin)` | Margin applied to all four sides. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `undefined (transparent)` | Semantic surface slot. Picks the right `var(--ggui-color-*)` background token from the active theme. The ONLY way to set a theme-tracking background fill on Box.  Available slots: - `'default'` \u2014 base container surface (most common) - `'elevated'` \u2014 same fill, intended to be paired with shadow   (use Card.shadow for actual elevation) - `'sunken'` \u2014 recessed / inset region (the `sunken` role; `surfaceVariant` was retired by ggui#987) - `'accent'` \u2014 highlighted / branded fill (`primary-50` token) - `'inverted'` \u2014 dark surface in light mode, light in dark   (testimonials, code-snippet cards, hero panels). The surface owns   ALL its inks: body text, `muted` / `subtle` labels, chips and   outlines inside it re-map to inverse-derived values by cascade \u2014   no `tone=\"inverse\"` needed, and no hand-picked greys. - `'hero'` \u2014 the hero panel's ground: brand-tinted on a light host, the   ink pair on a dark one (`heroGround` / `onHeroGround`, derived per mode)   \u2014 reach for it for a greeting or hero card instead of guessing the   host's darkness with `'inverted'`; it owns its subtree's inks likewise. - `'transparent'` \u2014 explicit \"no fill\"  For non-theme-mapped brand colors (e.g. a partner's exact brand hex like Stripe purple) use the  escape \u2014 every other hex / rgba on Box is rejected by tier-0 self-check. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n| assetColor | `string` | `undefined` | Asset color escape \u2014 the typed valve for legitimate non-theme color values (a partner's exact brand hex, a fixed product surface, etc.). Renders as the Box background.  **MUST be paired with .** The semantic name is human-readable documentation of why this color bypasses the theme \u2014 e.g. `\"stripe-brand-purple\"`, `\"slack-aubergine\"`. Tier-0 self-check allows hex / rgba inside `assetColor` ONLY when `assetSemantic` is a non-empty string; one without the other fails the check.  Reach for `surface` first. This escape exists for the small set of cases where the operator's theme MUST NOT override the value (brand identity rendering). |\n| assetSemantic | `string` | `undefined` | Human-readable semantic label that documents why  bypasses the theme. Required when `assetColor` is set; tier-0 self-check rejects empty strings or a missing `assetSemantic` next to a hex `assetColor`.  Examples: `\"stripe-brand-purple\"`, `\"slack-aubergine\"`, `\"partner-logo-orange\"`. Pure documentation \u2014 no rendering effect. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `undefined (no rounding)` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n```\n\n### Divider\n\nDivider -- A 1px line to visually separate content sections.\n\nRenders an `<hr>` (horizontal) or `<div>` (vertical) with `role=\"separator\"`.\n- Horizontal: 1px tall, full width, with vertical margin.\n- Vertical: 1px wide, stretches to parent height via `align-self: stretch`,\n  with horizontal margin. Works best inside a horizontal Stack or Row.\n\nDefault color: `var(--ggui-color-outlineVariant)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Line direction. - `'horizontal'` -- renders `<hr>`, full width, 1px height, margin top/bottom - `'vertical'` -- renders `<div>`, 1px width, `align-self: stretch`, margin left/right |\n| margin | `number \\| string` | `16` | Spacing around the divider. Numbers are treated as pixels. Applied as vertical margin for horizontal dividers, horizontal margin for vertical. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-outlineVariant)`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a quiet outline-variant tint when unset (independent of the tone slots). |\n\n**Example:**\n```tsx\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n```\n\n### Spacer\n\nSpacer -- Invisible spacing element, either fixed-size or flexible.\n\nRenders an empty `<div>`.\n- Fixed mode (number): sets both `width` and `height` to the given pixel\n  value with `flex-shrink: 0`, creating rigid spacing in any direction.\n- Flex mode (`'flex'`): sets `flex: 1`, expanding to fill remaining space\n  in a flex container. Useful for pushing siblings apart.\n\nCSS variables used: none.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number \\| 'flex'` | `16` | Spacing amount. - Number: fixed square spacer (width and height in pixels, `flex-shrink: 0`). - `'flex'`: expands to fill available space (`flex: 1`). |\n\n**Example:**\n```tsx\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n```\n\n### Text\n\nText -- Versatile typography primitive for body copy, captions, and labels.\n\nRenders as `<p>` by default (configurable via `is`). Typography is\ncomposed from three orthogonal axes: `size` (font size, with a\nmatching line-height built in), `weight`, and `tone` (semantic\ncolor). `caps` adds the uppercase, letter-spaced treatment for tiny\nsection labels (the classic overline/eyebrow look) \u2014 the label's text\ncomes from a prop, never from the component: an invented eyebrow is copy\nnothing can change.\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll text renders with `margin: 0` (no default paragraph spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| size | `'xs' \\| 'sm' \\| 'base' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| '4xl'` | `'base'` | Font size. Maps to CSS variables with pixel fallbacks; each size carries a matching line-height (1.5 for `xs`--`base`, 1.625 for `lg`, then tightening on display sizes: 1.375 at `xl`, 1.25 from `2xl` up): - `'xs'` -- var(--ggui-font-size-xs) (12px) - `'sm'` -- var(--ggui-font-size-sm) (14px) - `'base'` -- var(--ggui-font-size-base) (16px) - `'lg'` -- var(--ggui-font-size-lg) (18px) - `'xl'` -- var(--ggui-font-size-xl) (20px) - `'2xl'` -- var(--ggui-font-size-2xl) (24px) - `'3xl'` -- var(--ggui-font-size-3xl) (30px) - `'4xl'` -- var(--ggui-font-size-4xl) (36px) |\n| weight | `'normal' \\| 'medium' \\| 'semibold' \\| 'bold'` | `'normal'` | Font weight. Maps to CSS variables with numeric fallbacks: - `'normal'` -- var(--ggui-font-weight-normal) - `'medium'` -- var(--ggui-font-weight-medium) - `'semibold'` -- var(--ggui-font-weight-semibold) - `'bold'` -- var(--ggui-font-weight-bold) |\n| caps | `boolean` | `false` | When true, uppercases the text and adds 0.05em letter-spacing -- the eyebrow/overline treatment for tiny section labels. Pair with `size=\"xs\" weight=\"semibold\" tone=\"muted\"`. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Picks the right `var(--ggui-color-*)` token from the active theme. The theme decides what each tone LOOKS like \u2014 `'muted'` is a quiet warm grey on Claudic, a cool slate on Indigo, dim cyan on Neon-Noir. Components that use `tone` track the operator's theme switch automatically.  Available slots: `'default'` (primary body text), `'muted'` (secondary / metadata), `'subtle'` (very-low-emphasis hint), `'emphasized'` (branded accent), `'loud'` (strongest accent \u2014 the theme's readable accent ink), `'success'` / `'warning'` / `'error'` / `'info'` (status text), `'inverse'` (text on dark surface), `'inherit'` (parent's color).  `tone` is the ONLY way to set a Text color. The legacy `color?: string` escape was retired \u2014 raw color strings bypass theming and silently override the operator's preset. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n| truncate | `boolean` | `false` | When true, clips overflowing text with an ellipsis. Applies `overflow: hidden`, `text-overflow: ellipsis`, and `white-space: nowrap`. |\n| is | `'p' \\| 'span' \\| 'div' \\| 'label'` | `'p'` | HTML element to render. Choose based on semantic context: - `'p'` -- paragraph (default, block-level) - `'span'` -- inline text within a sentence - `'div'` -- generic block container - `'label'` -- form label (pair with `htmlFor`) |\n| id | `string` | - | `id` for the rendered element \u2014 anchor an in-page link, or pair with a form control's `aria-labelledby`. |\n| htmlFor | `string` | - | Associates an `is=\"label\"` element with a form control by the control's `id`. Only meaningful when `is=\"label\"`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">{props.section}</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n```\n\n### Heading\n\nHeading -- Semantic heading element (h1-h6) with preset typography styles.\n\nRenders the corresponding `<h1>`-`<h6>` HTML element based on `level`.\nEach level has a preset font size, weight, line height, and letter spacing\nfrom the heading typography tokens:\n- Level 1: 36px / bold / 1.25 line-height / -0.025em tracking\n- Level 2: 30px / bold / 1.25 line-height / -0.025em tracking\n- Level 3: 24px / semibold / 1.375 line-height / 0em tracking\n- Level 4: 20px / semibold / 1.375 line-height / 0em tracking\n- Level 5: 18px / semibold / 1.5 line-height / 0em tracking\n- Level 6: 16px / semibold / 1.5 line-height / 0em tracking\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll headings render with `margin: 0` (no default heading spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| level | `1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6` | `2` | Semantic heading level. Determines both the HTML element (`<h1>`-`<h6>`) and the preset typography style. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Same vocabulary as ; see that prop's docs for the full slot table. `tone` is the ONLY way to set a Heading color \u2014 the legacy `color?: string` escape was retired so the operator's theme always wins. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n```\n\n### Button\n\nButton -- A clickable button primitive with multiple visual variants and sizes.\n\nRenders a native `<button>` element styled with inline CSS derived from design-token\nCSS variables. Supports a loading spinner, left/right icon slots, and a cross-platform\n`onPress` alias for `onClick`.\n\nBase styles applied to every variant:\n- `border-radius: var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- `font-weight: var(--ggui-font-weight-medium)`\n- `box-shadow: var(--ggui-shape-shadow-sm)`\n- `gap: var(--ggui-spacing-2)` between icon and text\n- Transitions: background-color, box-shadow, opacity at 200ms ease-in-out\n\nDisabled or loading: `opacity: 0.5`, `cursor: not-allowed`, click handler suppressed.\n\nAlso extends native `ButtonHTMLAttributes` (except `style`/`className`), so props\nlike `type`, `form`, `aria-*`, and `data-*` are forwarded to the `<button>` element.\nThe `type` prop defaults to `'button'` (not `'submit'`), preventing accidental form\nsubmissions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'primary' \\| 'secondary' \\| 'outline' \\| 'ghost' \\| 'danger'` | `'primary'` | Visual style. Maps to CSS variables: - `'primary'` -- `var(--ggui-color-primary-600)` background, white text, no border - `'secondary'` -- `var(--ggui-color-sunken)` background, `var(--ggui-color-onContainer)` text, no border - `'outline'` -- transparent background, `1px solid var(--ggui-color-primary-600)` border, label in the surface's   on-colour (`onContainer`) so it reads on any ground \u2014 the brand shows on the border, never as label ink on a dark theme - `'ghost'` -- transparent background, `var(--ggui-color-onContainer)` text, no border (its rank is the missing   chrome, not a dimmer label, which would read as disabled) - `'danger'` -- `var(--ggui-color-error-600)` background, white text, no border |\n| size | `'xs' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and minimum height: - `'xs'` -- padding `4px 8px`, font `var(--ggui-font-size-xs)`, min-height 24px - `'sm'` -- padding `6px 12px`, font `var(--ggui-font-size-sm)`, min-height 32px - `'md'` -- padding `10px 16px`, font `var(--ggui-font-size-sm)`, min-height 40px - `'lg'` -- padding `12px 24px`, font `var(--ggui-font-size-base)`, min-height 48px |\n| fullWidth | `boolean` | `false` | When true, sets `width: 100%` so the button fills its container. |\n| loading | `boolean` | `false` | When true, replaces children with a 16px `Spinner` (color: `currentColor`) and disables interaction (same effect as `disabled`). |\n| type | `'button' \\| 'submit' \\| 'reset'` | `'button'` | The HTML button type. Defaults to `'button'`, so a Button inside a `<form>` never submits it on click: the ONE control that submits the form sets `type=\"submit\"`; secondary controls keep the default. |\n| leftIcon | `ReactNode` | - | ReactNode rendered before children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| rightIcon | `ReactNode` | - | ReactNode rendered after children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| onPress | `() => void` | - | Alias for `onClick` for cross-platform compatibility (React Native convention). If both `onClick` and `onPress` are provided, `onClick` takes precedence. |\n\n**Example:**\n```tsx\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n```\n\n### Input\n\nInput -- A single-line text input with label, validation, and helper text.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<input>`,\nand an optional message `<span>` for error or helper text.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)`\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n  `var(--ggui-color-onSunken)`\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<input>` via `htmlFor`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\nWhen `required` is true, a red asterisk is appended to the label.\n\nAlso extends native `InputHTMLAttributes` (except `style`, `className`, `onChange`,\n`size`), so props like `autoFocus`, `name`, `pattern`, `aria-*` are forwarded.\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<input>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the input. Linked to the input via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the input is empty. |\n| value | `string` | - | Controlled value of the input. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| type | `'text' \\| 'email' \\| 'password' \\| 'number' \\| 'tel' \\| 'url' \\| 'search' \\| 'date' \\| 'time' \\| 'datetime-local'` | `'text'` | HTML input type. Determines browser behavior (keyboard on mobile, validation, masking). The date/time types render the browser's native, localized, keyboard-accessible picker; their `value` stays an ISO string (`'2026-07-29'`, `'14:30'`, `'2026-07-29T14:30'`) delivered through the usual value-first `onChange`. |\n| error | `string` | - | Error message displayed below the input in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the input in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<input>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n```\n\n### TextArea\n\nTextArea -- A multiline text input with label, validation, character count, and auto-resize.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<textarea>`,\nand a footer row with error/helper text on the left and character count on the right.\n\nStyling:\n- Padding: `10px 12px`, font: `var(--ggui-font-size-sm)`, `font-family: inherit`\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Resize: `vertical` by default, `none` when `autoResize` is true\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: same label/error linking pattern as Input (auto-generated ids,\n`aria-invalid`, `role=\"alert\"` on error message).\n\nAlso extends native `TextareaHTMLAttributes` (except `style`, `className`, `onChange`).\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<textarea>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the textarea. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the textarea is empty. |\n| value | `string` | - | Controlled value of the textarea. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| rows | `number` | `4` | Number of visible text rows (native `rows` attribute on `<textarea>`). |\n| error | `string` | - | Error message displayed below the textarea in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the textarea in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<textarea>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| maxLength | `number` | - | Maximum character length (native `maxLength` attribute). Also used as the denominator in the character count display when `showCount` is true. |\n| showCount | `boolean` | `false` | When true AND `maxLength` is set, displays a `{current}/{max}` character counter in the footer row (right-aligned, `var(--ggui-font-size-xs)`). Has no effect without `maxLength`. |\n| autoResize | `boolean` | `false` | When true, sets CSS `resize: none` on the textarea. The flag disables manual resizing to signal that external logic handles sizing. The component does NOT auto-adjust height based on content in the current implementation. |\n\n**Example:**\n```tsx\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n```\n\n### Select\n\nSelect -- A native dropdown selection primitive with label and validation.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<select>`\nwith custom styling, and an optional message `<span>`.\n\nThe native `<select>` has `appearance: none` with a custom chevron SVG rendered\nas a `background-image` (right-aligned, 12px, onSurfaceVariant color). Extra right\npadding (36px) accommodates the chevron.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)` for the displayed option,\n  `var(--ggui-color-onSunken)` only while the placeholder shows (a\n  `placeholder` with no `value` or `defaultValue`, until the user picks;\n  or with `value=\"\"` / `defaultValue=\"\"`)\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Cursor: `pointer` (normal), `not-allowed` (disabled)\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<select>`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\n\nAlso extends native `SelectHTMLAttributes` (except `style`, `className`,\n`onChange`, `size`).\n\n**IMPORTANT:** `onChange` receives the selected value string directly, NOT a\nReact `ChangeEvent`. This differs from native `<select>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the select. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of the `options[].value` strings. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the selected option's value string directly, NOT a React event. |\n| options | `SelectOption[]` | - | Array of selectable options. Rendered as native `<option>` elements. Must contain at least one option (or use `placeholder` for an empty-state prompt). |\n| placeholder | `string` | - | Placeholder text rendered as a disabled `<option value=\"\">` at the top of the list. With no `value` and no `defaultValue` the select starts on it, so it shows until the user picks; it cannot be picked again after that. |\n| error | `string` | - | Error message displayed below the select in `var(--ggui-color-error-500)`. When set, the border turns red and the message has `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the select in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)` and cursor becomes `not-allowed`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n```\n\n### Checkbox\n\nCheckbox -- A custom-styled checkbox with label and description.\n\nRenders a `<label>` wrapper containing a visually-hidden native `<input type=\"checkbox\">`\noverlaid by a custom 18x18px visual box. Supports checked, unchecked, and indeterminate\nstates, each with a distinct SVG icon (checkmark or horizontal dash).\n\nStyling:\n- Box border: `2px solid var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-outline)` (unchecked)\n- Box fill: `var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-container)` (unchecked)\n- Check/dash icon: white SVG, 12x12px\n- Box radius: `var(--ggui-shape-radius-sm)`\n- Transition: all 0.2s\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`, `var(--ggui-color-onContainer)`\n- Description: `var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`\n- Gap between box and text: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the boolean checked state directly, NOT a\nReact `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary label text rendered beside the checkbox box. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onContainer)`. |\n| checked | `boolean` | - | Controlled checked state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean checked state directly, NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5` and `cursor: not-allowed`. The native input is also disabled, preventing keyboard and click interaction. |\n| description | `string` | - | Secondary description text rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| indeterminate | `boolean` | `false` | When true, displays a horizontal dash instead of a checkmark. Used for \"select all\" states where some (but not all) children are checked. The `indeterminate` property is set via a ref on the native `<input>`. Visually identical to `checked` in terms of border and fill color. |\n\n**Example:**\n```tsx\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n```\n\n### Toggle\n\nToggle -- A switch/toggle input rendered as a pill-shaped track with a sliding knob.\n\nRenders a `<label>` wrapper with a `<div role=\"switch\">` track and an animated\ncircular knob. Does NOT use a native `<input>` -- keyboard interaction is handled\nmanually (Space and Enter keys toggle the state). The element is focusable via\n`tabIndex={0}` and shows a focus ring on focus.\n\nStyling:\n- Track (on): `var(--ggui-color-primary-600)`\n- Track (off): `var(--ggui-color-outline)`\n- Knob: white circle with `var(--ggui-shape-shadow-sm)`\n- Focus ring: `0 0 0 3px var(--ggui-color-primary-200)`\n- Transitions: background-color, box-shadow, knob position at 200ms ease-in-out\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`, `tabIndex: -1`\n- Gap between toggle and label: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the new boolean state directly (inverted from\ncurrent), NOT a React event.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label text rendered to the right of the toggle track. Also used as `aria-label` on the switch element. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onContainer)`. |\n| checked | `boolean` | - | Controlled checked (on/off) state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean state directly (i.e., `!checked`), NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5`, `cursor: not-allowed`, and removes the element from tab order (`tabIndex: -1`). Click and keyboard handlers are suppressed. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track and knob dimensions: - `'sm'` -- track 36x20px, knob 16px diameter - `'md'` -- track 44x24px, knob 20px diameter - `'lg'` -- track 52x28px, knob 24px diameter |\n\n**Example:**\n```tsx\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n```\n\n### RadioGroup\n\nRadioGroup -- A group of mutually exclusive radio options with optional label and error.\n\nRenders a `<div role=\"radiogroup\">` containing a label span, a flex container of\nradio options, and an optional error message. Each option is a `<label>` with a\nvisually-hidden native `<input type=\"radio\">` and a custom 18px circle indicator.\n\nStyling:\n- Selected circle: `2px solid var(--ggui-color-primary-600)` border with\n  an 8px `var(--ggui-color-primary-600)` filled inner dot\n- Unselected circle: `2px solid var(--ggui-color-outline)` border,\n  `var(--ggui-color-container)` fill\n- Circle radius: `var(--ggui-shape-radius-full)`\n- Transition: all 0.2s\n- Vertical gap: `var(--ggui-spacing-2)`, horizontal gap: `var(--ggui-spacing-4)`\n- Error: `var(--ggui-font-size-xs)`, `var(--ggui-color-error-500)`,\n  `role=\"alert\"`\n- Disabled options: `opacity: 0.5`, `cursor: not-allowed`\n\nAccessibility: the group has `role=\"radiogroup\"` with `aria-labelledby` pointing\nto the label and `aria-describedby` pointing to the error message (when present).\nAll radio inputs share a common auto-generated `name` attribute.\n\n**IMPORTANT:** `onChange` receives the selected option's value string directly,\nNOT a React `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Group label rendered above the options. Used as `aria-labelledby` target on the `role=\"radiogroup\"` container. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of `options[].value`. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the newly selected option's value string directly, NOT a React event. |\n| options | `RadioOption[]` | - | Array of radio options. Must contain at least two options for meaningful selection. |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Layout direction for the options container: - `'vertical'` -- column layout, `var(--ggui-spacing-2)` gap - `'horizontal'` -- row layout with `flex-wrap: wrap`, `var(--ggui-spacing-4)` gap |\n| disabled | `boolean` | `false` | When true, disables ALL options (individual `RadioOption.disabled` is additive). Each option gets `opacity: 0.5` and `cursor: not-allowed`. |\n| error | `string` | - | Error message displayed below all options in `var(--ggui-color-error-500)` with `role=\"alert\"`. Linked to the radiogroup via `aria-describedby`. |\n\n**Example:**\n```tsx\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n```\n\n### Slider\n\nSlider -- A range input with a custom-styled track, fill, and thumb.\n\nRenders a `<div>` wrapper containing an optional label/value header, and a\ntrack area with three layers: background track, colored fill, and a circular\nthumb. A native `<input type=\"range\">` is overlaid with `opacity: 0` to\nprovide accessible keyboard and pointer interaction.\n\nStyling:\n- Track: 6px tall, `var(--ggui-color-outlineVariant)` background, `border-radius: 3px`\n- Fill: `var(--ggui-color-primary-600)` (normal),\n  `var(--ggui-color-outline)` (disabled)\n- Thumb: 20px white circle with `2px solid var(--ggui-color-primary-600)`,\n  `var(--ggui-shape-shadow-sm)`; disabled border uses outline\n- Value display (when `showValue`): `var(--ggui-color-primary-600)`,\n  `var(--ggui-font-size-sm)`, right-aligned in the header row\n- Fill and thumb transitions: 0.1s for smooth dragging\n\nAccessibility: the native `<input type=\"range\">` carries `aria-valuenow`,\n`aria-valuemin`, `aria-valuemax`, and is linked to the label via `aria-labelledby`.\nFalls back to `aria-label=\"Slider\"` when no label is provided.\n\n**IMPORTANT:** `onChange` receives the numeric value directly, NOT a React\n`ChangeEvent`. The value is coerced via `Number(e.target.value)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the slider track (left-aligned). Used as `aria-labelledby` target on the native range input. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `number` | `0` | Controlled numeric value. Must be between `min` and `max`. |\n| onChange | `(value: number) => void` | - | Change handler. Receives the new numeric value directly, NOT a React event. |\n| min | `number` | `0` | Minimum allowed value. |\n| max | `number` | `100` | Maximum allowed value. |\n| step | `number` | `1` | Step increment for the slider. Determines the granularity of selectable values. |\n| disabled | `boolean` | `false` | When true, sets `cursor: not-allowed` on the native input. The fill color changes to `var(--ggui-color-outline)` and the thumb border also uses outline. |\n| showValue | `boolean` | `false` | When true, displays the current numeric value right-aligned in the header row (beside the label) in `var(--ggui-color-primary-600)`. |\n\n**Example:**\n```tsx\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n```\n\n### Badge\n\nBadge -- Inline label for status indicators, counts, or categories.\n\nRenders a `<span>` with `display: inline-flex`, centered content, and\n`white-space: nowrap`. Semantic variant colors use background/text pairings\nfrom the 100/700 color scale. Pill shape uses `border-radius: 9999px`;\nnon-pill uses `var(--ggui-shape-radius-sm)`.\n\nFont weight: `var(--ggui-font-weight-medium)` across all variants.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'default' \\| 'primary' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info' \\| 'tertiary'` | `'default'` | Visual style. Maps to background/text color pairings: - `'default'` -- bg `var(--ggui-color-sunken)`, text `var(--ggui-color-onSunken)` - `'primary'` -- bg `var(--ggui-color-primary-100)`, text `var(--ggui-color-primary-700)` - `'secondary'` -- bg `var(--ggui-color-outlineVariant)`, text `var(--ggui-color-onContainer)` - `'success'` -- bg `var(--ggui-color-success-100)`, text `var(--ggui-color-success-700)` - `'warning'` -- bg `var(--ggui-color-warning-100)`, text `var(--ggui-color-warning-700)` - `'error'` -- bg `var(--ggui-color-error-100)`, text `var(--ggui-color-error-700)` - `'info'` -- bg `var(--ggui-color-info-100)`, text `var(--ggui-color-info-700)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `2px 6px`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `2px 8px`, font `var(--ggui-font-size-xs)` - `'lg'` -- padding `4px 10px`, font `var(--ggui-font-size-sm)` |\n| pill | `boolean` | `true` | When true, uses fully rounded corners (`border-radius: 9999px`). When false, uses `var(--ggui-shape-radius-sm)`. |\n\n**Example:**\n```tsx\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n```\n\n### Spinner\n\nSpinner -- Animated SVG loading indicator.\n\nRenders an `<svg>` with `role=\"status\"` and `aria-label=\"Loading\"`.\nThe SVG contains a full outlineVariant background circle and a quarter-arc\nforeground stroke in the spinner color.\n\nAnimation: `ggui-spin 1s linear infinite` (360-degree rotation).\nThe `@keyframes ggui-spin` definition is injected inline via a `<style>` tag.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number` | `24` | Width and height of the SVG element in pixels. The internal viewBox is always `0 0 24 24`, so this controls rendered size only. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the animated foreground arc. Same vocabulary as ; the theme decides the resolved value. The background circle always uses `var(--ggui-color-outlineVariant)`.  Use `'inherit'` when the spinner sits inside a colored container (e.g. inside a Button) \u2014 the stroke picks up `currentColor` from the parent so it tracks the container's foreground. |\n\n**Example:**\n```tsx\n<Spinner size={32} tone=\"success\" />\n```\n\n### Avatar\n\nAvatar -- User or entity representation with image or auto-generated initials.\n\nRenders a `<div role=\"img\">` with `overflow: hidden` and `flex-shrink: 0`.\nWhen `src` is provided and loads successfully, renders an `<img>` with\n`object-fit: cover`. On image error (or when no `src`), falls back to\ninitials derived from `name` (up to 2 characters, uppercase).\n\nInitials background: deterministic color from a 5-color palette based on\nname hash (primary-500, success-500, warning-500, error-500, info-500).\nFalls back to `var(--ggui-color-outline)` when no name is given.\nInitials text: white, `font-weight: var(--ggui-font-weight-semibold)`,\n`font-size: resolvedSize * 0.4`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image URL. When provided and the image loads, it is rendered with `object-fit: cover`. On load error, falls back to initials. |\n| name | `string` | - | Name used for two purposes: 1. Generating initials (splits on spaces, takes first letter of each word, max 2). 2. Deterministic background color selection via character code hash. Also used as `aria-label` on the container. Falls back to `'Avatar'` if omitted. |\n| size | `number \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Avatar dimensions. Named sizes map to pixel values: - `'xs'` -- 24px - `'sm'` -- 32px - `'md'` -- 40px - `'lg'` -- 48px - `'xl'` -- 64px  Numeric values are used directly as pixel dimensions. |\n| shape | `'circle' \\| 'square'` | `'circle'` | Container shape. - `'circle'` -- `border-radius: 50%` - `'square'` -- `border-radius: var(--ggui-shape-radius-md)` |\n\n**Example:**\n```tsx\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n```\n\n### Alert\n\nAlert -- Contextual message box for important information with icon and optional dismiss.\n\nRenders a `<div role=\"alert\">` with flex layout (12px gap), variant-specific\nbackground, border, text color, and a leading icon. Each variant provides a\ndefault SVG icon (info circle, checkmark, warning triangle, or X circle) that\ncan be overridden via the `icon` prop.\n\nLayout: icon (flex-shrink: 0) | content column (title + body) | close button.\nBorder radius: `var(--ggui-shape-radius-lg)`.\nPadding: `12px 16px`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets: - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)`, icon `var(--ggui-color-info-500)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)`, icon `var(--ggui-color-success-500)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)`, icon `var(--ggui-color-warning-500)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)`, icon `var(--ggui-color-error-500)` |\n| title | `string` | - | Optional title rendered above the body in semibold (`var(--ggui-font-weight-semibold)`), `var(--ggui-font-size-sm)`. Title and body are separated by `var(--ggui-spacing-1)` gap. |\n| closable | `boolean` | `false` | When true, renders a close button (X icon) in the top-right area. The button has `min-width: 28px`, `min-height: 28px`, and `opacity: 0.7`. Requires `onClose` to be functional. |\n| onClose | `() => void` | - | Callback fired when the close button is clicked. Only relevant when `closable` is true. |\n| icon | `ReactNode` | - | Custom icon ReactNode to replace the default variant icon. Rendered at the leading position with the variant's icon color applied via `color` CSS property. |\n\n**Example:**\n```tsx\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n```\n\n### Progress\n\nProgress -- Horizontal progress bar with determinate and indeterminate modes.\n\nRenders a track `<div role=\"progressbar\">` with a colored fill child.\nThe track background is `var(--ggui-color-outlineVariant)` with\npill-shaped corners (border-radius = height / 2).\n\nDeterminate mode: fill width transitions smoothly (`width 0.3s ease`).\nIndeterminate mode: fill is 30% width, animated with\n`ggui-progress-indeterminate 1.5s ease-in-out infinite`\n(translateX from -100% to 400%). The `@keyframes` are injected inline.\n\nAccessibility: `aria-valuenow` is set in determinate mode, omitted in\nindeterminate. `aria-valuemin` is always 0, `aria-valuemax` matches `max`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `number` | - | Current progress value. Clamped to `[0, max]` and converted to a percentage for the fill width: `Math.min(100, Math.max(0, (value / max) * 100))`. |\n| max | `number` | `100` | Maximum value representing 100% progress. |\n| variant | `'default' \\| 'success' \\| 'warning' \\| 'error'` | `'default'` | Fill bar color. Maps to CSS variables: - `'default'` -- `var(--ggui-color-primary-600)` - `'success'` -- `var(--ggui-color-success-500)` - `'warning'` -- `var(--ggui-color-warning-500)` - `'error'` -- `var(--ggui-color-error-500)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track height in pixels: - `'sm'` -- 4px - `'md'` -- 8px - `'lg'` -- 12px |\n| label | `string` | - | Accessible name describing what this bar measures, e.g. `\"Survey progress\"` or `\"Upload\"`. Becomes the progressbar's `aria-label` and \u2014 when `showLabel` is set \u2014 the visible header text in place of the generic word \"Progress\". Always pass this when the surrounding context does not already make the meaning obvious. |\n| showLabel | `boolean` | `false` | When true, displays a header row above the track with the `label` text (or \"Progress\" if `label` is unset) on the left, and the rounded percentage value on the right. |\n| indeterminate | `boolean` | `false` | When true, ignores `value` for visual width and plays a looping animation instead. The fill bar is 30% width and slides across the track. Animation: `ggui-progress-indeterminate 1.5s ease-in-out infinite`. `aria-valuenow` is omitted from the progressbar element. |\n\n**Example:**\n```tsx\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n```\n\n### Image\n\nImage -- An `<img>` element with built-in error handling and fallback support.\n\nRenders a native `<img>` with `display: block`. On load error, either renders\nthe `fallback` ReactNode (if provided) or a default placeholder `<div>` with a\nsurfaceVariant background and a centered image SVG icon in outline.\n\nSize values: numbers are treated as pixels, strings are passed through as-is.\nWhen no `width` is set, defaults to `100%`. When no `height` is set, defaults\nto `auto`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image source URL. Load failure triggers the fallback state. |\n| alt | `string` | - | Alt text for the image. Used as `aria-label` in the error placeholder too. |\n| width | `number \\| string` | `'100%' (applied at render time, not on the type)` | Image width. Numbers are pixels, strings are CSS values (e.g., `'100%'`, `'50vw'`). |\n| height | `number \\| string` | `'auto' (applied at render time, not on the type)` | Image height. Numbers are pixels, strings are CSS values. |\n| objectFit | `'cover' \\| 'contain' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | CSS `object-fit` value controlling how the image fills its box. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | - | Corner radius applied to both the image and the error placeholder. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through. |\n| fallback | `ReactNode` | - | Custom ReactNode rendered when the image fails to load. When provided, completely replaces the default error placeholder (no wrapper div). When omitted, a surfaceVariant background div with an image icon is shown. |\n\n**Example:**\n```tsx\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n```\n\n### Icon\n\nIcon -- a curated Lucide subset (~200 names) + emoji passthrough.\n\nThree resolution layers:\n1. **Lucide icon:** pass a name from the curated subset (e.g. `sun`, `cloud-rain`, `heart`, `shopping-cart`, `sparkles`, `arrow-up-right`).\n   Accepts kebab-case, camelCase, or PascalCase. Renders as stroke SVG. ONLY the subset renders: an\n   unknown name renders an empty box (never a placeholder glyph) \u2014 the `get_available_icons` tool lists the exact names.\n2. **Emoji:** pass emoji/unicode directly (e.g. `\u2600\uFE0F`, `\u{1F327}\uFE0F`). Rendered as text.\n3. **Custom SVG:** pass children (`<svg>` element) for full control.\n\nContainer: `<span>` with `display: inline-flex`, centered content.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| name | `string` | - | Lucide icon name from the curated subset (kebab-case, camelCase, or PascalCase all work); a name outside the subset renders an empty box. Also accepts emoji/unicode characters directly. |\n| size | `number` | `24` | Icon dimensions in pixels (applied to both width and height of the wrapper and the inner SVG element). |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (icon uses `currentColor`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Resolves to a CSS `color` on the wrapper which the inner SVG inherits via `currentColor`. Use `'inherit'` (the default behavior when unset) for icons that should pick up the parent's foreground color. |\n| children | `ReactNode` | - | Custom SVG children. When provided, `name` is ignored and children are rendered inside a sized `<span>` wrapper. |\n| 'aria-label' | `string` | - | Accessible name for a standalone, meaning-bearing icon. When set, the icon exposes `role=\"img\"` + this label. When omitted (the default) the icon is decorative and hidden from screen readers (`aria-hidden`) \u2014 the right choice for an icon next to a text label. |\n\n**Example:**\n```tsx\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n```\n\n### Link\n\nLink -- Styled anchor element with external link support.\n\nRenders a native `<a>` element. When `external` is true, sets\n`target=\"_blank\"` and `rel=\"noopener noreferrer\"`, and appends a small\n(12px) external-link SVG icon after the children.\n\nTransition: `color 0.2s`.\nUnderline behavior is controlled via mouseEnter/mouseLeave event handlers\n(for the `'hover'` mode).\n\nAlso extends native `AnchorHTMLAttributes` (except `style`/`className`),\nso props like `aria-*`, `data-*`, `title`, etc. are forwarded to the `<a>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| href | `string` | - | Destination URL. Passed directly to the `<a href>` attribute. |\n| external | `boolean` | `false` | When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`) and appends a 12px external-link icon after children. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the link text. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a primary-tinted accent (`'loud'`-ish) when unset. |\n| underline | `'always' \\| 'hover' \\| 'none'` | `'hover'` | Underline behavior: - `'always'` -- `text-decoration: underline` at all times - `'hover'` -- underline appears on mouse enter, removed on mouse leave - `'none'` -- no underline ever |\n\n**Example:**\n```tsx\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n```\n\n### Tooltip\n\nTooltip -- Hoverable information popup positioned relative to a trigger element.\n\nWraps `children` in a `<div>` trigger (display: inline-block) and renders\na fixed-position tooltip `<div role=\"tooltip\">` when visible.\n\nTooltip appearance:\n- Background: `var(--ggui-color-onContainer)`\n- Text: white, `var(--ggui-font-size-xs)`\n- Padding: `6px 10px`, border-radius: `var(--ggui-shape-radius-md)`\n- Max width: 200px, `white-space: nowrap`, `pointer-events: none`\n- Z-index: `zIndex.tooltip` (1800)\n\nShow/hide: triggered by mouseEnter/mouseLeave AND focus/blur on the\ntrigger element. Uses `position: fixed` with coordinates calculated from\n`getBoundingClientRect()` and an 8px offset from the trigger edge.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Trigger element. Wrapped in a `<div>` with mouseEnter/mouseLeave and focus/blur handlers. |\n| content | `ReactNode` | - | Tooltip content. Can be text or any ReactNode. |\n| position | `'top' \\| 'bottom' \\| 'left' \\| 'right'` | `'top'` | Tooltip placement relative to the trigger element: - `'top'` -- above, centered horizontally, transformed `translateX(-50%) translateY(-100%)` - `'bottom'` -- below, centered horizontally, transformed `translateX(-50%)` - `'left'` -- to the left, centered vertically, transformed `translateX(-100%) translateY(-50%)` - `'right'` -- to the right, centered vertically, transformed `translateY(-50%)` |\n| delay | `number` | `200` | Delay in milliseconds before the tooltip becomes visible after hover/focus. Hiding is immediate (no delay). |\n\n**Example:**\n```tsx\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n```\n\n### Table\n\nTable -- Data table with sortable columns, striped rows, and hover highlights.\n\nRenders a scrollable wrapper `<div>` containing a native `<table>` with\n`border-collapse: collapse` and `width: 100%`. The wrapper has\n`overflow-x: auto` for horizontal scrolling on narrow viewports.\n\nHeader row: 2px bottom border (`var(--ggui-color-outlineVariant)`).\nData rows: 1px bottom border (`var(--ggui-color-sunken)`).\nHover: `var(--ggui-color-container)` background with 150ms ease transition.\nStriped: alternating rows (odd index) get `var(--ggui-color-container)`.\n\nSort behavior: clicking a sortable column header calls `onSort(key, direction)`.\nIf the same column is clicked again while ascending, it toggles to descending.\nThe component does NOT sort data internally -- the parent must sort `data` and\npass updated `sortKey`/`sortDirection`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `TableColumn<T>[]` | - | Array of column definitions controlling header labels, data keys, and rendering. |\n| data | `T[]` | - | Array of row data objects. Each object's keys should match the column `key` values. |\n| sortKey | `string` | - | The `key` of the currently sorted column. Used to highlight the active sort indicator and determine toggle direction on next click. |\n| sortDirection | `SortDirection` | `'asc'` | Current sort direction for the column identified by `sortKey`. Controls which triangle indicator is highlighted in the header. |\n| onSort | `(key: string, direction: SortDirection) => void` | - | Sort change handler. Called when a sortable column header is clicked. Receives the column `key` and the new `SortDirection`. The component does NOT sort data internally -- you must sort `data` in your state and pass updated `sortKey`/`sortDirection`. |\n| striped | `boolean` | `false` | When true, alternating rows (odd index) get a `var(--ggui-color-container)` background. |\n| hoverable | `boolean` | `true` | When true, rows highlight with `var(--ggui-color-container)` on mouse enter, with a 150ms ease background-color transition. |\n| compact | `boolean` | `false` | When true, reduces cell padding: - Compact: `var(--ggui-spacing-1) var(--ggui-spacing-2)` - Normal: `var(--ggui-spacing-2) var(--ggui-spacing-4)` |\n| bordered | `boolean` | `false` | When true, adds a 1px border around the table wrapper and between cells. Wrapper border: `1px solid var(--ggui-color-outlineVariant)`. Cell borders: `1px solid var(--ggui-color-sunken)`. Wrapper border-radius: `var(--ggui-shape-radius-lg)`. |\n| caption | `string` | - | Accessible table caption. Rendered as a `<caption>` element with `caption-side: top`, `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`. |\n\n**Example:**\n```tsx\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n```\n\n### Tabs\n\nTabs -- Accessible tab navigation with panels and keyboard support.\n\nRenders a `<div role=\"tablist\">` with `<button role=\"tab\">` elements and a\n`<div role=\"tabpanel\">` for the active tab's content. Supports controlled\n(`activeKey` + `onChange`) and uncontrolled (internal state) modes.\n\nKeyboard navigation: ArrowLeft/ArrowRight (and ArrowUp/ArrowDown) cycle\nthrough enabled tabs. Home/End jump to first/last. Focus follows selection.\nDisabled tabs are skipped during keyboard navigation.\n\n**IMPORTANT:** `onChange` receives the tab's `key` string directly, NOT a\nReact event.\n\nTab panel padding: `var(--ggui-spacing-4) 0` (top/bottom only).\nTransitions: color, background-color, border-color at 200ms ease-in-out.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `TabItem[]` | - | Array of tab definitions. Must contain at least one item. |\n| activeKey | `string` | - | Controlled active tab key. When provided, the component is controlled and will not manage its own state. Must match one of `items[].key`. When omitted, defaults to the first item's key (uncontrolled mode). |\n| onChange | `(key: string) => void` | - | Tab change handler. Receives the selected tab's `key` string directly, NOT a React event. In controlled mode, you must update `activeKey` in response to this callback. |\n| variant | `'line' \\| 'pills' \\| 'enclosed'` | `'line'` | Visual style of the tab bar: - `'line'` -- underline indicator (2px solid primary-600 on active), border-bottom on tab list - `'pills'` -- filled pill buttons (primary-600 bg, white text on active), surfaceVariant container with radius-lg - `'enclosed'` -- bordered tab buttons with open bottom (card-style), border-bottom on tab list |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls tab button padding and font size: - `'sm'` -- padding `var(--ggui-spacing-1) var(--ggui-spacing-2)`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `var(--ggui-spacing-2) var(--ggui-spacing-4)`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `var(--ggui-spacing-4) var(--ggui-spacing-6)`, font `var(--ggui-font-size-base)` |\n| fullWidth | `boolean` | `false` | When true, tab buttons expand equally to fill the container width (`flex: 1`, `justify-content: center` on each button). |\n\n**Example:**\n```tsx\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n```\n\n### Toast\n\nToast -- Notification banner with auto-dismiss and slide-in animation.\n\nRenders a `<div role=\"alert\" aria-live=\"assertive\">` with a variant-specific\nicon, optional title, message body, and optional close button.\n\nAnimation: `ggui-slideInUp 200ms ease-out both` on mount (from the motion\ntoken system). The keyframes are provided by the MotionKeyframes provider.\n\nAuto-dismiss: when `onClose` is provided and `duration > 0`, a timer calls\n`onClose` after `duration` ms. Setting `duration` to `0` disables auto-dismiss.\nThe timer resets if `visible`, `duration`, or `onClose` changes.\n\nDimensions: `min-width: 280px`, `max-width: 420px`.\nShadow: `var(--ggui-shape-shadow-lg)`.\nBorder radius: `var(--ggui-shape-radius-lg)`.\n\nWhen `visible` is false, renders nothing (returns `null`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| message | `ReactNode` | - | Message body content. Can be text or any ReactNode. |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets (same palette as Alert): - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)` |\n| title | `string` | - | Optional title rendered above the message in semibold (`var(--ggui-font-weight-semibold)`, `var(--ggui-font-size-sm)`). |\n| duration | `number` | `5000` | Auto-dismiss delay in milliseconds. After this duration, `onClose` is called automatically. Set to `0` to disable auto-dismiss (toast stays until manually closed). The timer is only active when both `visible` is true and `onClose` is provided. |\n| onClose | `() => void` | - | Callback fired on auto-dismiss timeout or when the close button is clicked. When provided, a close button (X icon, 16px) is rendered in the top-right area. When omitted, no close button is shown and auto-dismiss is disabled. |\n| visible | `boolean` | `true` | Controls rendering. When false, the component returns `null`. Toggling from false to true triggers the slide-in animation. |\n| position | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-center' \\| 'bottom-center'` | - | Intended screen position. This prop is defined on the interface but is NOT implemented by the Toast component itself -- positioning must be handled by a parent container or toast manager. |\n\n**Example:**\n```tsx\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n```\n\n### Accordion\n\nAccordion -- Collapsible content sections with chevron rotation animation.\n\nRenders a vertical list of items, each with a `<button>` header (inside `<h3>`)\nand a `<div role=\"region\">` panel. Supports controlled (`expandedKeys` + `onChange`)\nand uncontrolled (internal state) modes.\n\nChevron animation: the trailing chevron icon rotates from 0deg (collapsed) to\n180deg (expanded) with `transition: transform var(--ggui-motion-duration-base) var(--ggui-motion-easing-standard)` (ggui#1106).\n\nHeader button: full-width flex layout (`justify-content: space-between`),\n`var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n`var(--ggui-color-onContainer)`.\nHeader padding: `var(--ggui-spacing-2) var(--ggui-spacing-4)`.\nBackground transition: `background-color var(--ggui-motion-duration-fast) var(--ggui-motion-easing-standard)`.\n\n**IMPORTANT:** `onChange` receives the full array of currently expanded keys,\nNOT a single key or a React event. In single mode (`multiple: false`), this\narray will have at most one element.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `AccordionItem[]` | - | Array of collapsible section definitions. |\n| expandedKeys | `string[]` | - | Controlled expanded state. Array of item `key` values that should be open. When provided, the component is controlled and will not manage its own expansion state. When omitted, defaults to `[]` (all collapsed, uncontrolled mode). |\n| onChange | `(expandedKeys: string[]) => void` | - | Expand/collapse handler. Receives the complete array of expanded keys after a toggle. In controlled mode, you must update `expandedKeys` in response to this callback. |\n| multiple | `boolean` | `false` | When true, multiple items can be open simultaneously. When false, opening one item closes any other open item (single-expand mode). |\n| variant | `'default' \\| 'bordered' \\| 'separated'` | `'default'` | Visual style controlling borders and spacing: - `'default'` -- top border on first item, bottom border on all items (`var(--ggui-color-outlineVariant)`), no gap between items - `'bordered'` -- connected card style with left/right/bottom borders on all items, top border on first, shared rounded corners (radius-lg on first/last) - `'separated'` -- each item is an independent card with full border (`1px solid var(--ggui-color-outlineVariant)`), `var(--ggui-shape-radius-lg)` radius, `var(--ggui-spacing-2)` gap between items |\n\n**Example:**\n```tsx\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n```\n\n### Support Types\n\n**ResponsiveColumns:**\n\nExplicit column count per viewport breakpoint, mobile-first. `base`\napplies from 0 up; each named key overrides at and above its\nbreakpoint width (`sm` 640px, `md` 768px, `lg` 1024px, `xl` 1280px).\nOmit `base` to default to a single column on the narrowest screens.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| base | `number` | Columns below the `sm` breakpoint. |\n| sm | `number` | Columns from 640px up. |\n| md | `number` | Columns from 768px up. |\n| lg | `number` | Columns from 1024px up. |\n| xl | `number` | Columns from 1280px up. |\n\n**SelectOption:**\n\nAn individual option within a `Select` dropdown.\n\nRendered as a native `<option>` element. When `disabled` is true, the option\nis visible but not selectable.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value submitted when this option is selected. Must be unique within the options array. |\n| label | `string` | The display text shown in the dropdown. |\n| disabled | `boolean` | When true, the option is visible but cannot be selected (grayed out by the browser). |\n\n**RadioOption:**\n\nAn individual option within a `RadioGroup`.\n\nRendered as a `<label>` containing a visually-hidden `<input type=\"radio\">`\nand a custom 18px circle indicator. Supports an optional description line\nbelow the label text.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value emitted via `RadioGroupProps.onChange` when this option is selected. Must be unique. |\n| label | `string` | Display text for this option. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onContainer)`. |\n| description | `string` | Optional secondary description rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| disabled | `boolean` | When true, this individual option is grayed out (`opacity: 0.5`) and cannot be selected, regardless of the group-level `disabled` prop. |\n\n**TableColumn:**\n\nColumn definition for the Table component.\n\nEach column maps a `key` in the row data object to a table column with\na header label, optional sorting, alignment, width, and custom rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key in the row data object. Used to extract cell values via `row[key]`. Must be unique across all columns in a Table. |\n| header | `string` | Column header text. Rendered in uppercase, `var(--ggui-font-size-xs)`, `var(--ggui-font-weight-semibold)`, `var(--ggui-color-onSunken)`, with `letter-spacing: 0.05em`. |\n| width | `number \\| string` | Fixed column width. Numbers are pixels, strings are CSS values (e.g., `'200px'`, `'30%'`). When omitted, the column auto-sizes based on content. |\n| align | `'left' \\| 'center' \\| 'right'` | Horizontal text alignment for both the header and data cells. |\n| sortable | `boolean` | When true, the header cell becomes clickable and shows sort direction indicators (ascending/descending triangles). Clicking toggles between `'asc'` and `'desc'`. The header gets `cursor: pointer`, `tabIndex: 0`, and keyboard support (Enter/Space to toggle). |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When provided, called instead of rendering `row[key]` directly. Receives the cell value, the full row object, and the row index. |\n\n**TabItem:**\n\nDefinition of a single tab within a Tabs component.\n\nEach item provides a unique `key` for identification, a `label` for the\ntab button, and `content` for the associated panel.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this tab. Used to match `activeKey` and as the value passed to `onChange`. |\n| label | `ReactNode` | Tab button label. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the tab bar when this tab is active. |\n| disabled | `boolean` | When true, the tab button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be selected via click or keyboard navigation. |\n| icon | `ReactNode` | Optional icon rendered before the label inside the tab button, with `var(--ggui-spacing-1)` gap between icon and label. |\n\n**AccordionItem:**\n\nDefinition of a single collapsible section within an Accordion.\n\nEach item provides a unique `key`, a clickable `title` for the header button,\nand `content` revealed when expanded.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this item. Used in `expandedKeys` and passed to `onChange`. |\n| title | `ReactNode` | Header label rendered inside the toggle button. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the header when expanded. Styled with `var(--ggui-font-size-sm)`, `var(--ggui-color-onContainer)`, `line-height: var(--ggui-font-lineHeight-normal)`. Padding: `0 var(--ggui-spacing-4) var(--ggui-spacing-4)`. |\n| disabled | `boolean` | When true, the header button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be toggled. |\n\n\n## Components\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### SearchField\n\nA text input with a leading search icon and optional submit button.\n\nComposes: `Input` (native `<input type=\"search\">`), `Button`, `Spinner`, `Icon`.\n\nSupports controlled and uncontrolled usage. When `value` is `undefined` the\ncomponent tracks its own state internally. Pressing **Enter** triggers\n`onSearch` with the current value. When `loading` is `true` the search icon\nis replaced by a `Spinner` and the input is disabled.\n\nTokens used: `colors.gray[300]` border, `colors.gray[50]` disabled bg,\n`colors.gray[400]` icon color, `colors.gray[900]` text color.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | - | Current search value. When provided, the component is **controlled** and the caller must update this via `onChange`. When omitted, the component manages its own internal state. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React `ChangeEvent`). |\n| onSearch | `(value: string) => void` | - | Called when the user presses **Enter** or clicks the search button (if `showButton` is `true`). Receives the current value directly. |\n| placeholder | `string` | `'Search...'` | Placeholder text shown when the input is empty. |\n| showButton | `boolean` | `false` | When `true`, renders a `Button` primitive to the right of the input. The button's label is set by `buttonText`. |\n| buttonText | `string` | `'Search'` | Label rendered inside the submit button. Only visible when `showButton` is `true`. |\n| loading | `boolean` | - | When `true`, replaces the search icon with a `Spinner`, disables the input, and disables the submit button. |\n| disabled | `boolean` | - | When `true`, the input and button are visually disabled and do not respond to interaction. The input background changes to `colors.gray[50]`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls input height and font size. - `'sm'` -- 6px vertical padding, 14px font - `'md'` -- 10px vertical padding, 14px font - `'lg'` -- 12px vertical padding, 16px font  The Button size maps `sm`->`sm`, `md`->`md`, `lg`->`md`. |\n\n**Example:**\n```tsx\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n```\n\n### FormField\n\nA wrapper that adds a label, optional description, error message,\nand helper text around any form input passed as `children`.\n\nComposes: no other primitives -- pure layout with semantic `<label>` and\n`<span>` elements.\n\nVisual hierarchy (top to bottom):\n1. **Label** (required) -- `fontSize.sm`, `fontWeight.medium`, `colors.gray[700]`\n2. **Required indicator** -- red asterisk (`colors.error[500]`) appended to label\n3. **Description** -- `fontSize.xs`, `colors.gray[500]`, 4px bottom margin\n4. **Children** -- the form control itself\n5. **Error / Helper text** -- `fontSize.xs`; error in `colors.error[500]`,\n   helper in `colors.gray[500]`. Error takes priority when both are provided.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Text rendered inside the `<label>` element above the input. |\n| children | `ReactNode` | - | The form control (typically an `Input`, `Select`, or `Textarea` primitive) rendered between the label/description and the error/helper row. |\n| error | `string` | - | Error message displayed below `children` in `colors.error[500]`. When present, it takes precedence over `helperText`. |\n| helperText | `string` | - | Neutral guidance text displayed below `children` in `colors.gray[500]`. Hidden when `error` is present. |\n| required | `boolean` | - | When `true`, appends a red asterisk (`*`) after the label text. Does **not** add any HTML validation attributes -- handle that on the child input. |\n| description | `string` | - | Secondary description rendered between the label and the child control in `fontSize.xs` / `colors.gray[500]`. Use for longer guidance that does not belong in `helperText`. |\n\n**Example:**\n```tsx\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n```\n\n### MenuItem\n\nA full-width clickable row for menus, sidebars, and action lists.\n\nComposes: none -- renders a native `<button>` element.\n\nBuilt-in transition: `background-color` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on hover (ggui#1106).\n\nColor logic:\n- **Normal**: text `colors.gray[700]`, hover bg `colors.gray[100]`\n- **Active**: bg `colors.primary[50]`, text `colors.gray[700]`, `fontWeight.medium`\n- **Danger**: text `colors.error[600]`, hover bg `colors.error[50]`, active bg `colors.error[100]`\n- **Disabled**: text `colors.gray[400]`, `cursor: not-allowed`\n\nLayout: flexbox row with `8px` gap, `8px 12px` padding, `radius.md` border-radius.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary text content of the menu item. |\n| icon | `ReactNode` | - | Icon or element rendered to the left of the label. Flex-shrink 0. |\n| rightElement | `ReactNode` | - | Element rendered to the right of the label (e.g., a keyboard shortcut badge or a count). Colored `colors.gray[400]`, flex-shrink 0. |\n| onClick | `() => void` | - | Called when the item is clicked. Suppressed when `disabled` is `true`. |\n| disabled | `boolean` | - | When `true`, the item is non-interactive: `colors.gray[400]` text, `cursor: not-allowed`, click handler suppressed. |\n| active | `boolean` | - | Marks this item as the current selection. Applies a tinted background (`colors.primary[50]`, or `colors.error[100]` when `danger` is also set) and `fontWeight.medium`. |\n| danger | `boolean` | - | Switches the item to destructive styling: `colors.error[600]` text, `colors.error[50]` hover background. |\n\n**Example:**\n```tsx\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n```\n\n### Tag\n\nAn inline label for categories, filters, statuses, or selections.\nOptionally dismissable via a close button.\n\nComposes: none -- pure `<span>` with an optional close `<button>`.\n\nEach `variant` maps to a background / text / border color triple from the\ndesign tokens:\n- `'default'`  -- `gray[100]` / `gray[700]` / `gray[200]`\n- `'primary'`  -- `primary[50]` / `primary[700]` / `primary[200]`\n- `'success'`  -- `success[50]` / `success[700]` / `success[200]`\n- `'warning'`  -- `warning[50]` / `warning[700]` / `warning[200]`\n- `'error'`    -- `error[50]` / `error[700]` / `error[200]`\n- `'info'`     -- `info[50]` / `info[700]` / `info[200]`\n\nThe close button renders an inline SVG \"x\" icon (12x12) with `opacity: 0.7`\nand an `aria-label=\"Remove\"`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Tag content -- typically a short text string. |\n| variant | `'default' \\| 'primary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Semantic color variant applied to background, text, and border. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and internal gap. - `'sm'` -- 2px/6px padding, `fontSize.xs`, 4px gap - `'md'` -- 4px/8px padding, `fontSize.xs`, 6px gap - `'lg'` -- 6px/10px padding, `fontSize.sm`, 6px gap |\n| closable | `boolean` | - | When `true`, renders a small close (\"x\") button after the content. Clicking it fires `onClose`. |\n| onClose | `() => void` | - | Called when the close button is clicked. Only relevant when `closable` is `true`. |\n| icon | `ReactNode` | - | Icon or element rendered before the text content. |\n\n**Example:**\n```tsx\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n```\n\n### Dropdown\n\nA click-triggered menu anchored to a trigger element. Manages its own\nopen/close state internally.\n\nComposes: `MenuItem` for each option.\n\nBehavior:\n- Clicking the trigger toggles the menu open/closed.\n- Selecting an option calls `onChange(option.value)` and closes the menu.\n- Clicking outside the container or pressing **Escape** closes the menu.\n- The currently selected option (matching `value`) is rendered with\n  `MenuItem`'s `active` state.\n\nMenu panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, 160px min-width, 4px padding.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| trigger | `ReactNode` | - | The element the user clicks to open the menu. Receives a wrapping `<div>` with `cursor: pointer` (or `not-allowed` when disabled). |\n| options | `DropdownOption[]` | - | Array of selectable options rendered as `MenuItem` rows. |\n| value | `string` | - | The `value` of the currently selected option. The matching `MenuItem` is rendered with `active` styling. |\n| onChange | `(value: string) => void` | - | Called with the `value` string of the selected option (not the full `DropdownOption` object). The menu closes immediately after. |\n| placement | `'bottom-start' \\| 'bottom-end' \\| 'top-start' \\| 'top-end'` | `'bottom-start'` | Where to anchor the menu panel relative to the trigger. - `'bottom-start'` -- below, aligned to left edge - `'bottom-end'`   -- below, aligned to right edge - `'top-start'`    -- above, aligned to left edge - `'top-end'`      -- above, aligned to right edge |\n| disabled | `boolean` | - | When `true`, the trigger shows `cursor: not-allowed` and clicking it does not open the menu. |\n\n**Example:**\n```tsx\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n```\n\n### Autocomplete\n\nA text input with a filterable suggestion dropdown, keyboard navigation,\nand loading/empty states.\n\nComposes: `Input` primitive (with `label`, `error`, `placeholder` forwarded),\n`Spinner` (loading state).\n\nFiltering: options are filtered client-side by case-insensitive substring\nmatch against both `option.label` and `option.value`.\n\nKeyboard support:\n- **ArrowDown / ArrowUp** -- move highlight through filtered options\n  (opens dropdown if closed)\n- **Enter** -- selects the highlighted option\n- **Escape** -- closes the dropdown\n\nOn selection, `onChange` is called with `option.label` (the display text)\nand `onSelect` is called with the full `AutocompleteOption` object.\n\nDropdown panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, max-height 240px with\noverflow scroll.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | `''` | Current text in the input field. On selection, this is set to the selected option's `label`. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React event). Also called on selection with `option.label`. |\n| onSelect | `(option: AutocompleteOption) => void` | - | Called when the user selects an option (click or Enter on highlighted item). Receives the full `AutocompleteOption` object, not just the value string. |\n| options | `AutocompleteOption[]` | - | The full list of available options. Filtering is handled internally via case-insensitive substring match on `label` and `value`. |\n| placeholder | `string` | - | Placeholder text forwarded to the inner `Input` primitive. |\n| label | `string` | - | Label text forwarded to the inner `Input` primitive. |\n| loading | `boolean` | - | When `true`, the dropdown shows a centered `Spinner` instead of the option list. The input remains interactive. |\n| disabled | `boolean` | - | When `true`, the inner `Input` is disabled and the dropdown does not open. |\n| error | `string` | - | Error message forwarded to the inner `Input` primitive. |\n| noResultsText | `string` | `'No results found'` | Text shown in the dropdown when filtering produces zero matches. Rendered centered in `colors.gray[500]` / `fontSize.sm`. |\n\n**Example:**\n```tsx\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n```\n\n### Breadcrumb\n\nA horizontal navigation trail showing the user's location within a\nhierarchy. Renders a `<nav aria-label=\"Breadcrumb\">`.\n\nComposes: `Link` primitive (for items with `href`).\n\nRendering rules per item:\n- **Last item**: static `<span>` with `colors.gray[900]`, `fontWeight: 500`,\n  and `aria-current=\"page\"`.\n- **Non-last with `href`**: `Link` in `colors.gray[500]` with\n  `underline=\"hover\"`. If `onItemClick` is provided, `e.preventDefault()`\n  is called and the handler fires instead of navigating.\n- **Non-last without `href`**: unstyled `<button>` in `colors.gray[500]`.\n\nLayout: flexbox row, `8px` gap, `fontSize.sm`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `BreadcrumbItem[]` | - | Ordered array of breadcrumb segments from root to current page. |\n| separator | `ReactNode` | `'/'` | Separator rendered between each pair of items. Can be a string (e.g., `\"/\"`, `\">\"`) or a ReactNode (e.g., an `Icon`). Rendered in `colors.gray[400]`. |\n| onItemClick | `(item: BreadcrumbItem, index: number) => void` | - | Called when a non-last item is clicked. Receives the `BreadcrumbItem` and its zero-based `index`. When provided on items that have `href`, the default navigation is prevented via `e.preventDefault()`. |\n\n**Example:**\n```tsx\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n```\n\n### Pagination\n\nPage navigation controls with previous/next arrows, numbered page buttons,\nand optional first/last jumps. Renders a `<nav aria-label=\"Pagination\">`.\n\nComposes: `Button` (ghost variant for prev/next/first/last arrows),\n`Icon` (`chevron-left`, `chevron-right`).\n\nBuilt-in transition: `all` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on page number buttons (ggui#1106).\n\nPage windowing: when `totalPages > maxVisible`, the component shows the\nfirst page, last page, a window of pages around `currentPage`, and\nellipsis (\"...\") markers for gaps. The window adjusts when near the\nstart or end of the range.\n\nActive page button: `colors.primary[600]` bg, `colors.white` text,\n`fontWeight.medium`. Inactive: transparent bg, `colors.gray[700]` text.\n\nArrow buttons are automatically disabled at boundary pages (first/last).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| currentPage | `number` | - | Current active page. **1-indexed** (first page is `1`). |\n| totalPages | `number` | - | Total number of pages. Determines when last-page / next-page buttons disable. |\n| onPageChange | `(page: number) => void` | - | Called when the user clicks a page number, arrow, or first/last button. Receives the target page number (1-indexed) directly. |\n| showFirstLast | `boolean` | `true` | When `true`, renders double-chevron buttons for jumping to the first and last page. These buttons are disabled when already on the respective boundary. |\n| maxVisible | `number` | `5` | Maximum number of page buttons visible at once (including the first and last page, but excluding ellipsis markers). When `totalPages` exceeds this value, ellipsis gaps appear. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls button dimensions and icon sizes. - `'sm'` -- 28px buttons, 14px icons, Button size `xs` - `'md'` -- 32px buttons, 16px icons, Button size `sm` - `'lg'` -- 40px buttons, 20px icons, Button size `md` |\n| disabled | `boolean` | - | When `true`, all page buttons and arrows are visually dimmed (`opacity: 0.5`) and clicks are suppressed. |\n\n**Example:**\n```tsx\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n```\n\n### EmptyState\n\nEmptyState -- placeholder for a region with no data: empty lists,\nzero search results, an error fallback. Render it instead of\nnothing whenever a data array could be empty \u2014 a list that shows\nnothing when empty looks broken.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| icon | `string \\| ReactNode` | - | A Lucide icon name (kebab-case), rendered large and subtle above the title, or a custom node. Omit for a text-only empty state. |\n| title | `string` | - | The headline, e.g. \"No results found\". |\n| description | `string` | - | Optional supporting line below the title. |\n| action | `ReactNode` | - | Optional call-to-action, typically a `<Button>`. |\n\n**Example:**\n```tsx\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n```\n\n### Stat\n\nStat -- a single KPI / metric: a label, a large value, an optional\ntrend-coloured delta and icon. Reach for it whenever the UI is\n\"show a number\" \u2014 dashboards, weather and price cards, analytics\ntiles. Drop several into a `<Grid>` for a stat grid.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | The metric name, e.g. \"Revenue\". Rendered small and uppercase above the value. |\n| value | `string \\| number` | - | The headline value \u2014 the big number. A number, or a pre-formatted string (`\"$48.2k\"`, `\"18\xB0C\"`). |\n| delta | `string` | - | Optional change indicator, pre-formatted, e.g. `\"+12.5%\"` or `\"-3\"`. |\n| trend | `'up' \\| 'down' \\| 'neutral'` | `'neutral'` | Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error, `'neutral'` muted. |\n| icon | `string \\| ReactNode` | - | Optional Lucide icon name (kebab-case) or custom node, shown next to the label. |\n\n**Example:**\n```tsx\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n```\n\n### Stepper\n\nStepper -- a display-only step indicator for multi-step flows\n(wizards, checkouts, onboarding): numbered markers joined by\nconnector lines, with completed (check), current (filled), and\nupcoming (outlined) states styled distinctly.\n\nStepper renders step state; it never owns it. Declare the step\nlabels as a top-level `const`, track the current index in\n`useState`, and advance it from your own Next/Back buttons (or\n`onStepClick`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| steps | `string[]` | - | Ordered step labels, one per step. Declare as a top-level `const` array \u2014 never as state. |\n| current | `number` | - | Zero-based index of the active step. Steps before it render as completed (check mark), steps after it as upcoming. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Flow direction. `'horizontal'` joins the markers with connector lines in a row; `'vertical'` stacks the steps with short connector columns \u2014 better for sidebars or long step labels. |\n| onStepClick | `(index: number) => void` | - | When provided, each step becomes a real button and clicks receive the step's zero-based index. Typical use: jumping back to a completed step; guard forward jumps in the handler if the flow validates per step. |\n\n**Example:**\n```tsx\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n```\n\n### Markdown\n\nMarkdown -- renders markdown-formatted text as styled content:\nheadings, paragraphs, **bold** / *italic*, `inline code`, fenced\ncode blocks, bulleted and numbered lists, pipe tables, and links.\n\nUse it whenever a prop or context slot carries prose the agent\nauthors in markdown -- article bodies, AI-generated explanations,\ndescriptions, notes, help text. Pass the raw markdown string\nstraight through; never pre-parse it, never split it into per-line\n`Text` elements, and never rebuild formatting with nested\n`<strong>`/`<em>` markup yourself.\n\nSafe by construction: raw HTML in the source displays as literal\ntext (never markup), and links render inert unless their scheme is\nhttp(s)/mailto. Streaming-tolerant: a mid-stream prefix parses\ncleanly and completed constructs never change shape, so binding a\ngrowing string re-renders correctly.\n\nFor a single line of formatted text INSIDE another element (a table\ncell, a list row, a caption), use `MarkdownInline` instead -- same\n`markdown` prop, inline-level constructs only (no headings, lists,\nor code fences), renders inside the parent's typography.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Markdown source text, passed through verbatim. Supports the conversational subset: `#`-`###` headings, paragraphs, bold, italic, inline code, fenced code blocks, `-`/`1.` lists, `\\|` pipe tables, and `[label](url)` links. Bind stateful or streamed prose directly. |\n\n**Example:**\n```tsx\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n```\n\n### MarkdownInline\n\nMarkdownInline -- renders ONE line of inline-level markdown (bold,\nitalic, inline code, links) inside the parent's typography -- a table\ncell, a list row, a caption, a summary line. Same `markdown` prop as\n`Markdown`; block constructs (headings, lists, code fences) are not\nrendered -- reach for `Markdown` for multi-paragraph bodies.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Inline markdown source -- bold, italic, inline code, and `[label](url)` links. Block-level syntax renders as plain text. |\n\n**Example:**\n```tsx\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n```\n\n### Support Types\n\n**DropdownOption:**\n\nA single option inside a `Dropdown`. Each option maps to one `MenuItem`\ninternally.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier returned to `onChange` when this option is selected. |\n| label | `string` | Human-readable text shown in the menu row. |\n| icon | `ReactNode` | Optional icon rendered to the left of the label via `MenuItem.icon`. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive. |\n| danger | `boolean` | When `true`, the option uses destructive (red) styling via `MenuItem.danger`. |\n\n**AutocompleteOption:**\n\nA single option in the `Autocomplete` suggestion list.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier for this option. Also used for case-insensitive filtering against the input value. |\n| label | `string` | Primary display text. Also used for case-insensitive filtering and is written into the input on selection. |\n| description | `string` | Secondary description rendered below the label in `fontSize.xs` / `colors.gray[500]`. |\n| icon | `ReactNode` | Icon rendered to the left of the label/description block. Flex-shrink 0. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive (`cursor: not-allowed`, `colors.gray[400]` text). |\n\n**BreadcrumbItem:**\n\nA single segment in a `Breadcrumb` trail. Items with `href` render as\n`Link` primitives; items without render as plain `<button>` elements.\nThe last item in the array is always rendered as static text with\n`aria-current=\"page\"`.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for this breadcrumb segment. |\n| href | `string` | URL for this segment. When provided (and this is not the last item), the segment renders as a `Link` primitive with `underline=\"hover\"`. When omitted, it renders as a `<button>`. |\n| icon | `ReactNode` | Icon rendered immediately before the label. Its color follows the segment's text color: `colors.gray[500]` for navigable items, `colors.gray[900]` for the current (last) item. |\n\n\n## Compositions\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Header\n\nProps for the `Header` composition.\n\nA horizontal page header that arranges a logo, navigation, and action slots\nin a flex row (`justify-content: space-between`). Internally renders a `<header>` element;\ndoes not compose other ggui primitives.\n\nWhen `sticky` is true the header gets `position: sticky; top: 0` with `zIndex.sticky`\nand a `shadow.sm` box-shadow.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| logo | `ReactNode` | - | Logo or brand element rendered at the start (flex-shrink: 0). |\n| navigation | `ReactNode` | - | Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px left margin. |\n| actions | `ReactNode` | - | Right-side action elements (buttons, avatar, etc.) rendered with a 12 px gap. |\n| sticky | `boolean` | `false` | When true, the header becomes `position: sticky` at the top of its scroll container with `zIndex.sticky` and `shadow.sm`. |\n| background | `string` | `colors.white` | Background color of the header. |\n| bordered | `boolean` | `true` | When true, renders a 1 px bottom border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n```\n\n### Sidebar\n\nProps for the `Sidebar` composition.\n\nA vertical navigation panel that composes the `Icon` primitive for chevron indicators.\nItems are rendered as `<button>` elements inside a scrollable `<nav>`. Nested items\nare indented 16 px per depth level. The sidebar animates width changes with a 200 ms\nCSS transition. Active items are highlighted with `colors.primary[50]` background\nand `colors.primary[700]` text.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `SidebarItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Matched items get a highlighted background and bold text. |\n| onItemClick | `(item: SidebarItem) => void` | - | Called when any item (including parent items with children) is clicked. |\n| collapsed | `boolean` | `false` | When true, hides labels and badges; only icons remain visible, centered in the collapsed width. Nested children are hidden entirely. |\n| header | `ReactNode` | - | Content rendered above the item list, separated by a bottom border. |\n| footer | `ReactNode` | - | Content rendered below the item list, separated by a top border. |\n| width | `number` | `256` | Width in pixels when expanded. |\n| collapsedWidth | `number` | `64` | Width in pixels when collapsed. |\n\n**Example:**\n```tsx\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n```\n\n### CardGrid\n\nProps for the `CardGrid` composition.\n\nA CSS Grid wrapper that arranges children in equal-width columns. When `columns`\nis a number, it produces `repeat(N, 1fr)`. When it is a responsive object,\nit falls back to `repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive behavior.\n\nDoes not compose any ggui primitives internally \u2014 it is a pure layout container.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Card elements to arrange in the grid. |\n| columns | `number \\| { sm?: number; md?: number; lg?: number }` | `3` | Number of columns, or a responsive breakpoint map.  - `number` \u2014 fixed column count via `repeat(N, 1fr)`. - `{ sm?, md?, lg? }` \u2014 triggers `repeat(auto-fit, minmax(280px, 1fr))` for fluid layout. |\n| gap | `number` | `16` | Gap between grid items in pixels. |\n\n**Example:**\n```tsx\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n```\n\n### CommentThread\n\nProps for the `CommentThread` composition.\n\nA threaded comment section that composes `Avatar`, `Button`, `TextArea`, and `Spinner`\nprimitives. Comments are rendered recursively with 40 px indentation per nesting level.\nEach comment shows author avatar, name, timestamp, content, reactions, and a \"Reply\" toggle.\nWhen `currentUser` is provided, a new-comment input with avatar and submit button is shown\nabove the thread.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| comments | `Comment[]` | - | Array of top-level comments to render. Replies are nested within each comment. |\n| currentUser | `{     /** Display name for the current user's avatar. */     name: string;     /** Avatar image URL for the current user. */     avatar?: string;   }` | - | Current user info. When provided, a new-comment input area is rendered above the thread. |\n| onAddComment | `(content: string, parentId?: string) => void` | - | Called when the user submits a new top-level comment. |\n| onReply | `(commentId: string, content: string) => void` | - | Called when the user submits a reply to an existing comment. |\n| onReaction | `(commentId: string, emoji: string) => void` | - | Called when the user clicks an emoji reaction on a comment. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the comment list. |\n\n**Example:**\n```tsx\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n```\n\n### DataTable\n\nProps for the `DataTable` composition.\n\nA sortable, selectable data table that composes `Checkbox`, `Spinner`, and `Icon`\nprimitives. Renders a `<table>` inside a bordered container with 8 px border-radius.\nThe header row has a `colors.gray[50]` background. Sortable columns show a chevron\nicon on click (toggles asc/desc). Selected rows are highlighted with `colors.primary[50]`.\nRow background transitions use a 150 ms ease. The \"select all\" checkbox supports an\nindeterminate state when a subset of rows is selected.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `DataTableColumn<T>[]` | - | Column definitions that control header, alignment, sorting, and rendering. |\n| data | `T[]` | - | Row data array. Each entry corresponds to one table row. |\n| rowKey | `string \\| ((row: T) => string)` | `'id'` | Property name or function used to derive a unique key for each row. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of table body rows. |\n| emptyText | `string` | `'No data'` | Text shown when `data` is empty and not loading. |\n| onSort | `(key: string, direction: 'asc' \\| 'desc') => void` | - | Called when a sortable column header is clicked. Toggles direction automatically (asc -> desc) if the same column is clicked again. |\n| sortKey | `string` | - | The column key currently being sorted. |\n| sortDirection | `'asc' \\| 'desc'` | - | The current sort direction. |\n| onRowClick | `(row: T, index: number) => void` | - | Called when a row is clicked. Rows get `cursor: pointer` when this handler is provided. |\n| selectable | `boolean` | - | When true, adds a checkbox column at the start of each row. |\n| selectedKeys | `string[]` | `[]` | Array of currently selected row keys. |\n| onSelectionChange | `(keys: string[]) => void` | - | Called when the set of selected row keys changes (via row checkbox or select-all). |\n\n**Example:**\n```tsx\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n```\n\n### ChatWindow\n\nProps for the `ChatWindow` composition.\n\nA messaging interface that composes `Avatar`, `Button`, `Spinner`, and `Icon` primitives.\nLayout is a flex column filling 100% height with a bordered `radius.lg` container.\nMessages from the current user align right with `colors.primary[600]` bubbles and white text.\nOther users' messages align left with `colors.gray[100]` bubbles. The message area\nauto-scrolls to the bottom on new messages via `scrollIntoView({ behavior: 'smooth' })`.\nThe text input sends on Enter (Shift+Enter for newline).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| messages | `ChatMessage[]` | - | Array of chat messages to display in chronological order. |\n| currentUserId | `string` | - | ID of the current user. Messages from this user render right-aligned with a primary color bubble. |\n| onSendMessage | `(content: string) => void` | - | Called when the user submits a message (Enter key or send button). |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the message list. |\n| typing | `{ name: string } \\| null` | - | When non-null, displays a typing indicator below the last message (e.g., \"Alice is typing...\"). |\n| placeholder | `string` | `'Type a message...'` | Placeholder text for the message input field. |\n| header | `ReactNode` | - | Optional header content rendered above the message area, separated by a bottom border. |\n\n**Example:**\n```tsx\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n```\n\n### NavigationBar\n\nProps for the `NavigationBar` composition.\n\nA horizontal or vertical navigation menu. Does not compose other ggui primitives\n(uses plain `<button>` and `<a>` elements). Active items are styled per variant:\n\n- `'default'` \u2014 active item gets `colors.primary[600]` text and medium font weight.\n- `'pills'` \u2014 active item gets a `radius.full` pill with `colors.primary[100]` background.\n- `'underline'` \u2014 active item gets a 2 px bottom border in `colors.primary[600]`.\n  When horizontal, the entire nav also has a 1 px bottom border.\n\nAll items have a 150 ms transition on all properties.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `NavItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Controls visual highlighting per variant style. |\n| onItemClick | `(item: NavItem) => void` | - | Called when a non-disabled item is clicked. For `<a>` elements, `preventDefault` is called first. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Layout direction. - `'horizontal'` \u2014 flex-row with 4 px gap. - `'vertical'` \u2014 flex-column with 2 px gap. |\n| variant | `'default' \\| 'pills' \\| 'underline'` | `'default'` | Visual style for active/inactive items. - `'default'` \u2014 text color change only. - `'pills'` \u2014 rounded pill background on active items. - `'underline'` \u2014 bottom border on active items. |\n\n**Example:**\n```tsx\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n```\n\n### FileUploader\n\nProps for the `FileUploader` composition.\n\nA drag-and-drop file upload area that composes `Button`, `Progress`, and `Icon` primitives.\nThe drop zone is a dashed-border container that highlights in `colors.primary[400]`/`colors.primary[50]`\non drag-over. Below the drop zone, each file in `files` is listed with its name, size,\noptional progress bar (for uploading status), and a remove button.\n\nFile validation (max size, max count) is applied client-side before calling `onFilesSelected`.\nFiles exceeding `maxSize` are silently filtered out; files exceeding `maxFiles` are truncated.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| files | `UploadedFile[]` | `[]` | Array of files currently in the upload queue, shown below the drop zone. |\n| onFilesSelected | `(files: File[]) => void` | - | Called when the user selects files via click or drag-and-drop. Receives native `File` objects after client-side filtering (maxSize, maxFiles). |\n| onFileRemove | `(fileId: string) => void` | - | Called when the user clicks the remove button on a file entry. |\n| accept | `string` | - | Accepted file types passed to the hidden `<input type=\"file\" accept=\"...\">`. E.g., `'image/*,.pdf'`. |\n| multiple | `boolean` | `true` | When true, allows selecting multiple files at once. |\n| maxSize | `number` | - | Maximum file size in bytes. Files exceeding this are silently excluded from the selection. |\n| maxFiles | `number` | - | Maximum number of files. Excess files beyond `maxFiles - files.length` are truncated. |\n| disabled | `boolean` | - | When true, the drop zone is visually dimmed (opacity 0.5) and non-interactive. |\n| dragDrop | `boolean` | `true` | When true, enables drag-and-drop on the drop zone. When false, the prompt text changes to \"Click to browse files\". |\n\n**Example:**\n```tsx\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n```\n\n### NotificationCenter\n\nProps for the `NotificationCenter` composition.\n\nA notification list with a header bar that composes `Button`, `Spinner`, and `Icon`\nprimitives. The header shows a \"Notifications\" title, an unread count badge\n(pill in `colors.primary[100]`), and \"Mark all read\" / \"Clear all\" buttons.\nEach notification item shows a colored status dot, title, message, timestamp,\n\"Mark as read\" link, and optional action. The list is scrollable (`overflowY: auto`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| notifications | `Notification[]` | - | Array of notifications to display, in the order provided. |\n| onMarkAsRead | `(id: string) => void` | - | Called when the user clicks \"Mark as read\" on an individual notification. |\n| onMarkAllAsRead | `() => void` | - | Called when the user clicks the \"Mark all read\" header button. Only shown when there are unread items. |\n| onDismiss | `(id: string) => void` | - | Called when the user clicks the dismiss (X) button on an individual notification. |\n| onClearAll | `() => void` | - | Called when the user clicks the \"Clear all\" header button. Only shown when there are any notifications. |\n| emptyText | `string` | `'No notifications'` | Text shown when `notifications` is empty and not loading. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the notification list. |\n\n**Example:**\n```tsx\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n```\n\n### Modal\n\nProps for the `Modal` composition.\n\nA dialog overlay that composes `Button`, `Icon`, and `Heading` primitives.\nThe overlay uses `animation.fadeIn` (`ggui-fadeIn`) and the dialog panel uses\n`animation.scaleIn` (`ggui-scaleIn`) \u2014 both GPU-composited (opacity + transform).\nWhen open, `document.body.style.overflow` is set to `'hidden'` to prevent background\nscrolling, and restored on close. The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`.\n\nSize widths: `sm` = 400 px, `md` = 500 px, `lg` = 640 px, `xl` = 800 px,\n`full` = 100vw (no border-radius, no padding).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls modal visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the modal (overlay click, escape key, or close button). |\n| title | `string` | - | Optional title rendered in the modal header via the `Heading` primitive (level 4). |\n| children | `ReactNode` | - | Modal body content rendered in a scrollable area (`overflowY: auto`). |\n| footer | `ReactNode` | - | Footer content rendered below the body, right-aligned with an 8 px gap, separated by a top border. |\n| size | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'` | Controls the width of the modal panel. - `'sm'` \u2014 400 px - `'md'` \u2014 500 px - `'lg'` \u2014 640 px - `'xl'` \u2014 800 px - `'full'` \u2014 100vw, no border-radius, stretches to fill viewport |\n| closeOnOverlayClick | `boolean` | `true` | When true, clicking the semi-transparent overlay behind the modal calls `onClose`. |\n| closeOnEscape | `boolean` | `true` | When true, pressing the Escape key calls `onClose`. |\n| showCloseButton | `boolean` | `true` | When true, renders a ghost close button (X icon) in the modal header. |\n\n**Example:**\n```tsx\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n```\n\n### CommandPalette\n\nProps for the `CommandPalette` composition.\n\nA searchable command menu (Cmd+K / Ctrl+K pattern) that composes `Spinner` and `Icon`\nprimitives. Appears as a centered overlay at 15vh from the top. Commands are filtered\nby label and description (case-insensitive substring match). Results are grouped under\nuppercase section headers. Keyboard navigation is fully supported:\nArrow Up/Down to navigate, Enter to select, Escape to close.\n\nWhen `recentIds` are provided and the search query is empty, matching commands appear\nin a \"Recent\" section at the top (deduplicated from their original groups).\n\nThe footer shows navigation hints: \"Up/Down Navigate\", \"Enter Select\", \"Esc Close\".\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls palette visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the palette (overlay click, Escape key, or after command selection). |\n| commands | `Command[]` | - | Full array of available commands. Filtered client-side by the search query. |\n| onSelect | `(command: Command) => void` | - | Called when a non-disabled command is selected (Enter key or click). The palette auto-closes after selection. |\n| placeholder | `string` | `'Search commands...'` | Placeholder text for the search input. |\n| recentIds | `string[]` | `[]` | IDs of recently used commands. When the query is empty, these appear in a \"Recent\" section at the top of the results. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the command list. |\n\n**Example:**\n```tsx\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n```\n\n### Footer\n\nProps for the `Footer` composition.\n\nA site footer with `role=\"contentinfo\"` that lays out a brand slot, link columns,\nsocial icons, and a bottom bar. Does not compose other ggui primitives (uses plain\nHTML elements). Content is constrained to `max-width: 1280px` with auto margins.\nLink columns use a responsive flex layout (`flex: 0 1 180px`). The bottom bar\nincludes copyright text, social links, and bottom-bar links separated by a top border.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| brand | `ReactNode` | - | Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`). |\n| columns | `FooterColumn[]` | - | Array of link columns rendered in a flex-wrap layout with 48 px gap. |\n| socialLinks | `FooterSocialLink[]` | - | Social media icon links rendered in the bottom bar. |\n| bottomText | `string` | - | Text displayed at the start of the bottom bar (e.g., copyright notice). |\n| bottomLinks | `FooterLink[]` | - | Links displayed in the bottom bar after social icons (e.g., Privacy, Terms). |\n| background | `string` | `colors.gray[50]` | Background color of the footer. |\n| bordered | `boolean` | `true` | When true, renders a 1 px top border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n```\n\n### Hero\n\nProps for the `Hero` composition.\n\nA prominent landing-page hero section that renders heading, description, CTA buttons,\nand an optional media slot. Does not compose other ggui primitives (uses plain HTML\nelements styled with design tokens). Content is constrained to `max-width: 1280px`.\n\nLayout modes:\n- `align='center'` \u2014 single-column centered layout with `max-width: 800px` text area.\n- `align='left'` \u2014 two-column side-by-side layout (50/50 split with media slot).\n\nSize controls vertical padding and font sizes:\n- `'sm'` \u2014 48 px vertical padding, 3xl heading, lg description.\n- `'md'` \u2014 80 px vertical padding, 4xl heading, xl description.\n- `'lg'` \u2014 120 px vertical padding, 5xl heading, xl description.\n\nThe primary action button uses `colors.primary[600]` fill; the secondary action uses\nan outlined style. When `overlay` is true with a `backgroundImage`, text switches to white\nand borders become semi-transparent.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| heading | `string` | - | Main heading text rendered as an `<h1>` with bold weight and tight line-height. |\n| description | `string` | - | Description paragraph rendered below the heading with relaxed line-height. |\n| primaryAction | `HeroAction` | - | Primary CTA button rendered with `colors.primary[600]` background and white text. |\n| secondaryAction | `HeroAction` | - | Secondary CTA button rendered with a transparent background and a 1 px border. |\n| media | `ReactNode` | - | Media element (image, video, illustration) rendered beside or below the text content. |\n| align | `'center' \\| 'left'` | `'center'` | Text and layout alignment. - `'center'` \u2014 centered single-column layout. - `'left'` \u2014 left-aligned text with media in a right column (50/50 split). |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls vertical padding and heading/description font sizes. - `'sm'` \u2014 compact (48 px padding, 3xl/lg fonts). - `'md'` \u2014 standard (80 px padding, 4xl/xl fonts). - `'lg'` \u2014 spacious (120 px padding, 5xl/xl fonts). |\n| background | `string` | `colors.white (when no backgroundImage is set)` | Background color of the hero section. |\n| backgroundImage | `string` | - | Background image URL applied as `background-size: cover; background-position: center`. |\n| overlay | `boolean` | `false` | When true and `backgroundImage` is set, renders a semi-transparent black overlay (`rgba(0,0,0,0.5)`) and switches text to white/semi-transparent white for contrast. |\n\n**Example:**\n```tsx\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n```\n\n### Support Types\n\n**SidebarItem:**\n\nA single navigation entry in a `Sidebar`. Supports nested children for\ncollapsible sub-menus and an optional badge slot.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the item. Hidden when the sidebar is collapsed. |\n| icon | `ReactNode` | Leading icon rendered before the label. Remains visible when collapsed. |\n| href | `string` | Optional URL associated with this item (not rendered as a link by default). |\n| badge | `ReactNode` | Trailing badge element (e.g., unread count). Hidden when collapsed. |\n| children | `SidebarItem[]` | Nested child items. When present, the item acts as a collapsible section (chevron indicator shown). |\n| disabled | `boolean` | When true, the item is visually dimmed and non-interactive (`cursor: not-allowed`). |\n\n**Comment:**\n\nA single comment entry in a `CommentThread`. Supports nested replies\nand emoji reactions with counts.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this comment. |\n| author | `{     /** Display name of the author. */     name: string;     /** URL for the author's avatar image. Passed to the `Avatar` primitive. */     avatar?: string;   }` | Comment author metadata. |\n| content | `string` | The comment body text. |\n| timestamp | `string \\| Date` | Timestamp of the comment. Rendered via `toLocaleString()` when a `Date` object. |\n| replies | `Comment[]` | Nested reply comments. Each reply is rendered indented 40 px deeper. |\n| reactions | `{ emoji: string; count: number }[]` | Emoji reactions with their aggregated counts (e.g., `{ emoji: \"\u{1F44D}\", count: 3 }`). |\n\n**DataTableColumn:**\n\nColumn definition for a `DataTable`. Controls header text, width, alignment,\nsorting, and custom cell rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key on the row object used to extract cell values. Also serves as the sort key. |\n| header | `string` | Column header text displayed in the `<thead>`. |\n| width | `number \\| string` | Column width as a CSS value (number for pixels, string for any CSS unit). |\n| sortable | `boolean` | When true, the column header is clickable and triggers `onSort`. An arrow icon indicates direction. |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When omitted, the raw value is stringified via `String()`. |\n| align | `'left' \\| 'center' \\| 'right'` | Text alignment for both header and body cells. |\n\n**ChatMessage:**\n\nA single message in a `ChatWindow`. Includes sender metadata, delivery status,\nand a timestamp.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this message. |\n| content | `string` | The message body text. |\n| sender | `{     /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */     id: string;     /** Display name of the sender. */     name: string;     /** Avatar image URL. Only shown for non-current-user messages (xs size). */     avatar?: string;   }` | Sender metadata used for avatar rendering and alignment. |\n| timestamp | `string \\| Date` | Message timestamp. Rendered as `HH:MM` via `toLocaleTimeString` when a `Date` object. |\n| status | `'sending' \\| 'sent' \\| 'delivered' \\| 'read' \\| 'error'` | Delivery status indicator shown on the current user's messages. - `'sending'` \u2014 shows a dot bullet - `'sent'` \u2014 shows a single checkmark - `'delivered'` \u2014 shows double checkmarks - `'read'` \u2014 shows double checkmarks (same visual as delivered) - `'error'` \u2014 shows an exclamation mark |\n\n**NavItem:**\n\nA single navigation entry in a `NavigationBar`. Supports nested children\nfor sub-menus (rendered by the parent via dropdown, not built-in).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the navigation link. |\n| href | `string` | URL for the item. When provided, renders an `<a>` element instead of `<button>`. |\n| icon | `ReactNode` | Optional icon rendered before the label. |\n| children | `NavItem[]` | Nested child items (for sub-menu structures; rendering is consumer-defined). |\n| disabled | `boolean` | When true, the item is visually dimmed (opacity 0.5) and non-interactive. |\n\n**UploadedFile:**\n\nA file entry in the `FileUploader` composition. Tracks upload progress,\nstatus, and optional error messages.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this file entry. Used as a key and for removal callbacks. |\n| name | `string` | Original file name. Rendered with text-overflow ellipsis when too long. |\n| size | `number` | File size in bytes. Formatted as B/KB/MB/GB for display. |\n| type | `string` | MIME type of the file (e.g., `'image/png'`). |\n| progress | `number` | Upload progress as a percentage (0-100). Shown via the `Progress` primitive when status is `'uploading'`. |\n| status | `'pending' \\| 'uploading' \\| 'success' \\| 'error'` | Current upload lifecycle status. - `'pending'` \u2014 file selected but upload not started. - `'uploading'` \u2014 upload in progress; `progress` bar is shown. - `'success'` \u2014 upload completed. - `'error'` \u2014 upload failed; `error` message is shown in `colors.error[500]`. |\n| error | `string` | Error message displayed when status is `'error'`. |\n| url | `string` | The remote URL of the uploaded file after successful upload. |\n\n**Notification:**\n\nA single notification entry in the `NotificationCenter`. Supports semantic type coloring,\nread state, and an optional inline action button.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this notification. |\n| title | `string` | Notification title rendered in medium weight. |\n| message | `string` | Optional body text rendered below the title in a smaller font. |\n| timestamp | `string \\| Date` | Timestamp of the notification. Rendered via `toLocaleString()` when a `Date` object. |\n| read | `boolean` | Read state. Unread notifications get a `colors.primary[50]` background and a colored status dot matching the notification type. |\n| type | `'info' \\| 'success' \\| 'warning' \\| 'error'` | Semantic type that controls the status dot color on unread notifications. - `'info'` \u2014 `colors.info[500]` (blue) - `'success'` \u2014 `colors.success[500]` (green) - `'warning'` \u2014 `colors.warning[500]` (amber) - `'error'` \u2014 `colors.error[500]` (red) |\n| icon | `ReactNode` | Optional icon rendered alongside the notification (not used by the default implementation). |\n| action | `{     /** Button label text. */     label: string;     /** Click handler for the action. */     onClick: () => void;   }` | Optional inline action button rendered next to the timestamp. |\n\n**Command:**\n\nA single command entry in a `CommandPalette`. Commands can be grouped,\nhave keyboard shortcuts, and support a disabled state.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this command. |\n| label | `string` | Display label for the command. Searchable by the palette's query filter. |\n| description | `string` | Optional description text shown below the label. Also searchable. |\n| icon | `ReactNode` | Icon rendered at the start of the command row. |\n| shortcut | `string` | Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element. |\n| group | `string` | Group name for visual sectioning. Commands with the same group are rendered under a shared header. Defaults to `'Commands'` if omitted. |\n| disabled | `boolean` | When true, the command is visually dimmed and cannot be selected. |\n\n**FooterLink:**\n\nA single link entry in a footer column or the bottom bar. Supports both\n`href` navigation and `onClick` handlers (onClick takes precedence via `preventDefault`).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for the link. |\n| href | `string` | URL for the link. |\n| onClick | `() => void` | Click handler. When provided, `preventDefault` is called on the anchor click. |\n\n**FooterColumn:**\n\nA named column of links in the `Footer` layout. Each column has an optional title\nand a list of links rendered as a vertical stack with 10 px gap.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| title | `string` | Column heading rendered as an `<h4>` with semibold weight. |\n| links | `FooterLink[]` | Links displayed in this column. |\n\n**FooterSocialLink:**\n\nA social media link in the `Footer` bottom bar. Rendered as an icon-only anchor\nwith `aria-label` for accessibility.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Accessible label for the social link (used as `aria-label`). |\n| href | `string` | URL for the social media profile or page. |\n| icon | `ReactNode` | Icon element rendered inside the anchor (typically an SVG or `Icon` primitive). |\n\n**HeroAction:**\n\nA call-to-action button definition for the `Hero` composition.\nUsed for both the primary (filled) and secondary (outlined) action buttons.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Button label text. |\n| onClick | `() => void` | Click handler for the button. |\n| href | `string` | Optional URL (not used by the default implementation; available for consumer routing). |\n\n\n## System Conventions\n\n### onChange Behavior (CRITICAL)\n\nAll form control onChange handlers receive the VALUE DIRECTLY, not a React event object.\n\n```tsx\n// CORRECT \u2014 onChange receives value directly\n<Input value={name} onChange={setName} />\n<Input value={email} onChange={(value) => setEmail(value)} />\n<Select value={country} onChange={setCountry} options={countries} />\n<Checkbox checked={agreed} onChange={setAgreed} />\n\n// WRONG \u2014 DO NOT use e.target.value!\n<Input value={name} onChange={(e) => setName(e.target.value)} /> // WILL BREAK\n```\n\nApplies to: Input, TextArea, Select, Checkbox, RadioGroup, Slider, Tabs, Accordion.\n\n### Available Motion & Animation\n\nRender `<MotionKeyframes />` once (anywhere in tree) to enable all keyframes.\n\n**Entrance/exit:** fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n**State feedback:** flash (background-color highlight), pulse (opacity breathing), bounce (scale overshoot)\n**Easing:** linear, easeIn, easeOut, easeInOut, spring (bouncy)\n**Durations:** instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n\n```tsx\n// Entrance animation on mount\n<div style={{ animation: 'ggui-fadeIn 200ms ease-out' }}>Content</div>\n\n// Stagger list items\n{items.map((item, i) => (\n  <div key={item.id} style={{ animation: \\`ggui-slideInUp 300ms ease-out \\${i * 50}ms both\\` }}>\n    {item.name}\n  </div>\n))}\n\n// Flash highlight when data changes (e.g., stock price update)\n// useAnimationKey returns a key that increments when dep changes \u2192 remounts element \u2192 replays animation\nconst priceKey = useAnimationKey(stock.price);\n<div key={priceKey} style={{\n  animation: animation.flash,\n  '--ggui-flash-color': stock.change > 0 ? 'var(--ggui-color-success-100)' : 'var(--ggui-color-error-100)',\n} as React.CSSProperties}>\n  {stock.price}\n</div>\n\n// Respect reduced-motion preference\nconst { motionEnabled } = useMotion();\n<div style={motionEnabled ? { animation: 'ggui-scaleIn 200ms ease-out' } : undefined}>\n  Content\n</div>\n```\n\n### Elevation System\n\n6 levels mapping shadow intensity to z-index for layering:\n- Level 0: flat (no shadow, z: auto) \u2014 inline content\n- Level 1: sm shadow (z: auto) \u2014 cards, sections\n- Level 2: md shadow (z: 1000) \u2014 dropdowns, popovers\n- Level 3: lg shadow (z: 1200) \u2014 sticky banners\n- Level 4: xl shadow (z: 1400) \u2014 modals, dialogs\n- Level 5: 2xl shadow (z: 1800) \u2014 tooltips, toasts\n\n### Import Constraints\n\nOnly these imports are allowed:\n- `react`\n- `@ggui-ai/design` \u2014 the whole design system (primitives, components, compositions, and the `Clickable` / `Hoverable` / `Pressable` traits) is one import; there are no subpaths\n- `@ggui-ai/wire` (wire hooks)\n\nNo external libraries (lodash, date-fns, etc.). No fetch(). No eval().";
-var VALID_PRIMITIVES = [
-  "Container",
-  "Card",
-  "Stack",
-  "Row",
-  "Grid",
-  "Box",
-  "Divider",
-  "Spacer",
-  "Text",
-  "Heading",
-  "Button",
-  "Input",
-  "TextArea",
-  "Select",
-  "Checkbox",
-  "Toggle",
-  "RadioGroup",
-  "Slider",
-  "Badge",
-  "Spinner",
-  "Skeleton",
-  "Avatar",
-  "Alert",
-  "Progress",
-  "Image",
-  "Icon",
-  "Link",
-  "Tooltip",
-  "Table",
-  "Tabs",
-  "Toast",
-  "Accordion",
-  "MotionKeyframes",
-  "SearchField",
-  "FormField",
-  "MenuItem",
-  "Tag",
-  "Dropdown",
-  "Autocomplete",
-  "Breadcrumb",
-  "Pagination",
-  "EmptyState",
-  "Stat",
-  "Stepper",
-  "Markdown",
-  "MarkdownInline",
-  "Header",
-  "Sidebar",
-  "CardGrid",
-  "CommentThread",
-  "DataTable",
-  "ChatWindow",
-  "NavigationBar",
-  "FileUploader",
-  "NotificationCenter",
-  "Modal",
-  "CommandPalette",
-  "Footer",
-  "Hero"
-];
-var ALLOWED_IMPORT_BASES = [
-  "react",
-  "react-dom",
-  "@ggui-ai/design",
-  "@ggui-ai/wire",
-  "@ggui-ai/gadgets"
-];
-function isAllowedImport(specifier, gadgetPackages) {
-  if (FORBIDDEN_IMPORT_SPECIFIERS.includes(specifier)) return false;
-  for (const base of ALLOWED_IMPORT_BASES) {
-    if (specifier === base || specifier.startsWith(`${base}/`)) return true;
-  }
-  return gadgetPackages?.has(specifier) ?? false;
-}
-function describeAllowedImports() {
-  return "react, @ggui-ai/design, @ggui-ai/wire, @ggui-ai/gadgets, or a gadget package declared on the contract \u2014 never @ggui-ai/wire/internal (the writer side of the wire; components read useRender().isConnected)";
-}
-var MAX_FILE_SIZE = 50 * 1024;
-var MAX_LINE_COUNT = 500;
-var DANGEROUS_PATTERNS = DANGEROUS_PATTERNS$1;
-function getLineNumber(code, match) {
-  const upToMatch = code.substring(0, match.index);
-  return upToMatch.split("\n").length;
-}
-function extractImports(code) {
-  const imports = [];
-  const importRegex = /import\s+(?:[\w\s{},*]+\s+from\s+)?['"]([^'"]+)['"]/g;
-  let match;
-  while ((match = importRegex.exec(code)) !== null) {
-    imports.push({
-      source: match[1],
-      line: getLineNumber(code, match)
-    });
-  }
-  return imports;
-}
-function extractPrimitivesUsed(code) {
-  const jsxTagRegex = /<([A-Z][a-zA-Z0-9]*)/g;
-  const used = /* @__PURE__ */ new Set();
-  let match;
-  while ((match = jsxTagRegex.exec(code)) !== null) {
-    used.add(match[1]);
-  }
-  return Array.from(used);
-}
-function validateComponentDetailed(code, options = {}) {
-  const errors = [];
-  const warnings = [];
-  const suggestions = [];
-  const lines = code.split("\n");
-  const lineCount = lines.length;
-  const charCount = code.length;
-  if (!options.skipSizeLimits) {
-    if (charCount > MAX_FILE_SIZE) {
-      errors.push({
-        type: "size",
-        message: `Component is too large: ${(charCount / 1024).toFixed(1)}KB exceeds ${MAX_FILE_SIZE / 1024}KB limit`,
-        suggestion: "Split the component into smaller sub-components or simplify the implementation."
-      });
-    }
-    if (lineCount > MAX_LINE_COUNT) {
-      errors.push({
-        type: "size",
-        message: `Component has too many lines: ${lineCount} exceeds ${MAX_LINE_COUNT} line limit`,
-        suggestion: "Split the component into smaller sub-components."
-      });
-    }
-  }
-  const imports = extractImports(code);
-  if (!options.skipImportValidation) {
-    for (const imp of imports) {
-      const isAllowed = isAllowedImport(imp.source);
-      const isAppComponents = imp.source === "@app/components" || imp.source.startsWith("@app/components/");
-      if (!isAllowed && !isAppComponents) {
-        errors.push({
-          type: "import",
-          message: `Invalid import: "${imp.source}" is not allowed`,
-          line: imp.line,
-          suggestion: `Only import from: ${describeAllowedImports()}. Remove this import and use ggui primitives instead.`
-        });
-      }
-    }
-    if (!imports.some((i) => i.source === "react")) {
-      if (/\buseState\b|\buseEffect\b|\buseMemo\b|\buseCallback\b|\buseRef\b/.test(code)) {
-        warnings.push({
-          type: "best-practice",
-          message: "React hooks are used but react is not explicitly imported",
-          suggestion: "Add: import { useState } from 'react';"
-        });
-      }
-    }
-    if (!imports.some((i) => i.source === "@ggui-ai/design")) {
-      warnings.push({
-        type: "best-practice",
-        message: "No primitives imported from @ggui-ai/design",
-        suggestion: "Import primitives: import { Container, Card, Stack, Text, Button } from '@ggui-ai/design';"
-      });
-    }
-  }
-  const primitivesUsed = extractPrimitivesUsed(code);
-  const hasAppComponentImport = imports.some((i) => i.source.startsWith("@app/components"));
-  const importedComponentNames = /* @__PURE__ */ new Set();
-  if (hasAppComponentImport) {
-    const namedImportRegex = /import\s*\{([^}]+)\}\s*from\s*['"]@app\/components['"]/g;
-    let match;
-    while ((match = namedImportRegex.exec(code)) !== null) {
-      const names = match[1].split(",").map((n) => n.trim().split(" as ")[0].trim());
-      for (const name of names) {
-        if (name) importedComponentNames.add(name);
-      }
-    }
-    const defaultImportRegex = /import\s+(\w+)\s+from\s*['"]@app\/components\/[^'"]+['"]/g;
-    while ((match = defaultImportRegex.exec(code)) !== null) {
-      importedComponentNames.add(match[1]);
-    }
-  }
-  for (const primitive of primitivesUsed) {
-    if (!VALID_PRIMITIVES.includes(primitive)) {
-      if (importedComponentNames.has(primitive)) {
-        continue;
-      }
-      const isImported = code.includes(`import`) && code.includes(primitive);
-      if (!isImported) {
-        errors.push({
-          type: "primitive",
-          message: `Unknown component: "${primitive}" is not a valid ggui primitive`,
-          suggestion: `Use one of the valid primitives: ${VALID_PRIMITIVES.slice(0, 10).join(", ")}... or import from @app/components, or define it within this component.`
-        });
-      }
-    }
-  }
-  if (!options.skipSecurityPatterns) {
-    for (const { pattern, name, suggestion } of DANGEROUS_PATTERNS) {
-      const match = pattern.exec(code);
-      if (match) {
-        errors.push({
-          type: "security",
-          message: `Security violation: ${name} is not allowed`,
-          line: getLineNumber(code, match),
-          suggestion,
-          code: match[0]
-        });
-      }
-    }
-  }
-  if (!code.includes("export default")) {
-    errors.push({
-      type: "structure",
-      message: "Component must have a default export",
-      suggestion: 'Add "export default" before your main component function.'
-    });
-  }
-  if (/class\s+\w+\s+extends\s+(React\.)?Component/.test(code)) {
-    errors.push({
-      type: "structure",
-      message: "Class components are not allowed",
-      suggestion: "Convert to a functional component using hooks."
-    });
-  }
-  if (!code.includes("interface") && !code.includes("type ") && code.includes("Props")) {
-    warnings.push({
-      type: "best-practice",
-      message: "Props are used but no TypeScript interface is defined",
-      suggestion: "Define a Props interface: interface Props { onSubmit: (data: FormData) => void; }"
-    });
-  }
-  if (/e\.target\.value|event\.target\.value/.test(code)) {
-    errors.push({
-      type: "syntax",
-      message: "Using e.target.value with ggui primitives will fail - onChange receives value directly",
-      suggestion: "Change from onChange={(e) => setValue(e.target.value)} to onChange={setValue} or onChange={(value) => setValue(value)}"
-    });
-  }
-  if (code.includes(".map(") && !code.includes("key=")) {
-    warnings.push({
-      type: "best-practice",
-      message: "List rendering detected but no key prop found",
-      suggestion: "Add key prop to mapped elements: {items.map(item => <Card key={item.id}>...)}"
-    });
-  }
-  if (code.includes("<Image") && !code.includes("alt=")) {
-    warnings.push({
-      type: "accessibility",
-      message: "Image without alt attribute",
-      suggestion: 'Add alt attribute to Image: <Image src={...} alt="Description" />'
-    });
-  }
-  const hasInputs = /<Input\b/.test(code) || /<TextArea\b/.test(code) || /<Select\b/.test(code);
-  if (hasInputs) {
-    const hasLabels = /label=/.test(code) || /htmlFor=/.test(code) || /aria-label=/.test(code) || /aria-labelledby=/.test(code);
-    if (!hasLabels) {
-      warnings.push({
-        type: "accessibility",
-        message: "Form inputs detected without labels",
-        suggestion: 'Add label prop to inputs or associate with <Text is="label" htmlFor="id">. Screen readers need labels to identify form fields.'
-      });
-    }
-  }
-  if ((code.includes("onSubmit") || code.includes('role="form"')) && !code.includes("aria-label")) {
-    warnings.push({
-      type: "accessibility",
-      message: "Form without aria-label",
-      suggestion: 'Add aria-label to your form container: <Stack role="form" aria-label="Contact form">'
-    });
-  }
-  const iconButtonPattern = /<Button(?![^>]*aria-label)[^>]*>\s*.\s*<\/Button>/;
-  if (iconButtonPattern.test(code)) {
-    warnings.push({
-      type: "accessibility",
-      message: "Icon-only button detected without text content",
-      suggestion: 'Add aria-label to icon-only buttons: <Button aria-label="Close">\xD7</Button>'
-    });
-  }
-  if (code.includes("<Button") && !/disabled=|loading=/.test(code)) {
-    if (code.includes("onSubmit") || code.includes("submit")) {
-      warnings.push({
-        type: "best-practice",
-        message: "Submit button without disabled state",
-        suggestion: "Consider adding disabled={isSubmitting || !isValid} to prevent double submission"
-      });
-    }
-  }
-  if (errors.length > 0) {
-    suggestions.push("Fix all errors before compiling - the component will not work with errors.");
-  }
-  if (errors.some((e) => e.type === "import")) {
-    suggestions.push(
-      "Only react and @ggui-ai/design imports are allowed. All UI should be built with primitives."
-    );
-  }
-  if (errors.some((e) => e.type === "security")) {
-    suggestions.push("Avoid browser APIs - use props and callbacks for data flow.");
-  }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-    suggestions,
-    stats: {
-      lineCount,
-      charCount,
-      importCount: imports.length,
-      primitiveCount: primitivesUsed.filter(
-        (p) => VALID_PRIMITIVES.includes(p)
-      ).length
-    }
-  };
-}
-function formatValidationResultForClaude(result) {
-  if (result.valid && result.warnings.length === 0) {
-    return "Validation passed. Component is ready for compilation.";
-  }
-  const parts = [];
-  if (!result.valid) {
-    parts.push("## Validation Errors (must fix)\n");
-    for (const error of result.errors) {
-      const lineInfo = error.line ? ` (line ${error.line})` : "";
-      parts.push(`- **${error.type.toUpperCase()}**${lineInfo}: ${error.message}`);
-      parts.push(`  - Fix: ${error.suggestion}`);
-      if (error.code) {
-        parts.push(`  - Code: \`${error.code}\``);
-      }
-    }
-  }
-  if (result.warnings.length > 0) {
-    parts.push("\n## Warnings (recommended to fix)\n");
-    for (const warning of result.warnings) {
-      const lineInfo = warning.line ? ` (line ${warning.line})` : "";
-      parts.push(`- **${warning.type}**${lineInfo}: ${warning.message}`);
-      parts.push(`  - Suggestion: ${warning.suggestion}`);
-    }
-  }
-  if (result.suggestions.length > 0) {
-    parts.push("\n## General Suggestions\n");
-    for (const suggestion of result.suggestions) {
-      parts.push(`- ${suggestion}`);
-    }
-  }
-  parts.push(
-    `
-## Stats: ${result.stats.lineCount} lines, ${result.stats.primitiveCount} primitives used`
-  );
-  return parts.join("\n");
-}
-
-// src/design-system-docs.ts
-var DEFAULT_DESIGN_SYSTEM_DOCS = `# Design System - Default Light Theme
-
-**IMPORTANT:** Always use CSS variables (var(--ggui-*)) for styling to ensure components respect the app theme.
-
-## Colors
-
-### Primary
-- var(--ggui-color-primary-50) - #f0f9ff
-- var(--ggui-color-primary-100) - #e0f2fe
-- var(--ggui-color-primary-200) - #bae6fd
-- var(--ggui-color-primary-300) - #7dd3fc
-- var(--ggui-color-primary-400) - #38bdf8
-- var(--ggui-color-primary-500) - #0ea5e9
-- var(--ggui-color-primary-600) - #0284c7 (main action FILL \u2014 buttons, borders, icon fills; accent TEXT takes the link role below)
-- var(--ggui-color-primary-700) - #0369a1
-- var(--ggui-color-primary-800) - #075985
-- var(--ggui-color-primary-900) - #0c4a6e
-
-### Semantic Surface & Text Colors (REQUIRED for theme compatibility)
-These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS use these for surfaces and text \u2014 never use raw neutral-* scale values.**
-
-| Token | CSS Variable | Default | Role |
-|-------|-------------|---------|------|
-| ground | var(--ggui-color-ground) | The page / canvas behind everything |
-| onGround | var(--ggui-color-onGround) | Text on the canvas |
-| container | var(--ggui-color-container) | A card, a bubble, a panel \u2014 the unit of content |
-| onContainer | var(--ggui-color-onContainer) | Body text on a card |
-| elevated | var(--ggui-color-elevated) | Menus, popovers, modals, toasts \u2014 floats above a card |
-| onElevated | var(--ggui-color-onElevated) | Text on an elevated surface |
-| heroGround | var(--ggui-color-heroGround) | A hero / greeting panel's ground \u2014 brand-tinted on a light host, the ink pair on a dark one (Card surface="hero") |
-| onHeroGround | var(--ggui-color-onHeroGround) | Text on the hero ground |
-| sunken | var(--ggui-color-sunken) | Wells, inputs at rest, code blocks \u2014 recessed inside a card |
-| onSunken | var(--ggui-color-onSunken) | Muted / secondary text |
-| link | var(--ggui-color-link) | Accent TEXT \u2014 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 \u2014 clears 3:1 on its surface; kit controls draw it themselves |
-
-**Usage pattern:**
-- Page/section background \u2192 \`var(--ggui-color-ground)\`
-- Body text \u2192 \`var(--ggui-color-onContainer)\`
-- Card/panel background \u2192 \`var(--ggui-color-container)\`; recessed wells / inputs \u2192 \`var(--ggui-color-sunken)\`
-- Secondary/muted text \u2192 \`var(--ggui-color-onSunken)\`
-- Accent / branded text (eyebrow, tagline, link, label, inline arrow) \u2192 \`var(--ggui-color-link)\` or \`<Text tone="emphasized">\` \u2014 never a bare \`primary-<stop>\` as a text color
-- Branded section/header \u2192 \`var(--ggui-color-container)\` bg + \`var(--ggui-color-onContainer)\` text
-- Borders/dividers \u2192 \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
-
-### State Colors
-Semantic families ship as SCALES; the \`500\` stop is the role color (per-mode brightness), \`50\` the tint, \`800\` the on-tint text:
-- var(--ggui-color-success-500) \u2014 success states (tint bg: success-50, text on tint: success-800)
-- var(--ggui-color-warning-500) \u2014 warning states (warning-50 / warning-800)
-- var(--ggui-color-error-500) \u2014 error states, destructive actions (error-50 / error-800)
-- var(--ggui-color-info-500) \u2014 informational (info-50 / info-800)
-Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-written vars \u2014 it resolves to the same stops.
-
-### IMPORTANT: Color Rules
-- **NEVER** use hardcoded hex colors. ONLY use var(--ggui-color-*) tokens.
-- **NEVER** use rgba(), hsl(), or other CSS color functions with hardcoded values.
-- **NEVER** use raw neutral-* or gray-* scale tokens (neutral-50, neutral-900, etc.) \u2014 these are internal to the theme and break in dark mode.
-- **ALWAYS** use semantic tokens for text and backgrounds:
-  - Text: \`var(--ggui-color-onContainer)\` or \`var(--ggui-color-onSunken)\`
-  - Backgrounds: \`var(--ggui-color-container)\` or \`var(--ggui-color-sunken)\`
-  - Borders: \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
-- For branded elements use \`var(--ggui-color-primary-*)\` scale tokens \u2014 these ARE safe because primary adapts per theme.
-- For card backgrounds use \`var(--ggui-color-container)\` or \`var(--ggui-color-primary-50)\`
-
-## Spacing
-
-Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never use raw numbers** like \`padding={16}\` \u2014 always use the token: \`padding="var(--ggui-spacing-4)"\`.
-
-| Token | Value | Common use |
-|-------|-------|------------|
-| var(--ggui-spacing-1) | 4px | Icon gaps, tight spacing |
-| var(--ggui-spacing-2) | 8px | Button padding, small gaps |
-| var(--ggui-spacing-3) | 12px | List item spacing, form gaps |
-| var(--ggui-spacing-4) | 16px | Card padding, section gaps |
-| var(--ggui-spacing-5) | 20px | Medium padding |
-| var(--ggui-spacing-6) | 24px | Container padding, large gaps |
-| var(--ggui-spacing-8) | 32px | Section spacing |
-| var(--ggui-spacing-10) | 40px | Page margins |
-| var(--ggui-spacing-12) | 48px | Hero/large section spacing |
-
-**Quick lookup (px \u2192 token):** 4\u21921, 8\u21922, 12\u21923, 16\u21924, 20\u21925, 24\u21926, 28\u21927, 32\u21928, 36\u21929, 40\u219210, 48\u219212
-
-**Usage on primitives:**
-\`\`\`tsx
-<Container padding="var(--ggui-spacing-6)">
-  <Stack gap="var(--ggui-spacing-4)">
-    <Card padding="var(--ggui-spacing-4)">
-      <Row gap="var(--ggui-spacing-2)">...</Row>
-    </Card>
-  </Stack>
-</Container>
-\`\`\`
-
-## Typography
-
-### Font Sizes
-- var(--ggui-font-size-xs) - 12px
-- var(--ggui-font-size-sm) - 14px
-- var(--ggui-font-size-base) - 16px
-- var(--ggui-font-size-lg) - 18px
-- var(--ggui-font-size-xl) - 20px
-- var(--ggui-font-size-2xl) - 24px
-- var(--ggui-font-size-3xl) - 30px
-- var(--ggui-font-size-4xl) - 36px
-
-### Font Weights
-- var(--ggui-font-weight-normal) - 400
-- var(--ggui-font-weight-medium) - 500
-- var(--ggui-font-weight-semibold) - 600
-- var(--ggui-font-weight-bold) - 700
-
-## Border Radius
-- var(--ggui-shape-radius-sm) - 4px
-- var(--ggui-shape-radius-md) - 8px
-- var(--ggui-shape-radius-lg) - 12px
-- var(--ggui-shape-radius-xl) - 16px
-- var(--ggui-shape-radius-full) - 9999px
-
-## Shadows
-- var(--ggui-shape-shadow-sm) - 0 1px 2px rgba(0,0,0,0.05)
-- var(--ggui-shape-shadow-md) - 0 4px 6px -1px rgba(0,0,0,0.1)
-- var(--ggui-shape-shadow-lg) - 0 10px 15px -3px rgba(0,0,0,0.1)
-- var(--ggui-shape-shadow-xl) - 0 20px 25px -5px rgba(0,0,0,0.1)
-
-## Usage Examples (always use ggui primitives \u2014 never raw <div>, <button>, <input>)
-
-### Branded section header
-\`\`\`tsx
-<Box padding="var(--ggui-spacing-4)" surface="accent">
-  <Heading level={2} tone="emphasized">Contact Us</Heading>
-  <Text tone="emphasized">We'd love to hear from you</Text>
-</Box>
-\`\`\`
-
-### Form input
-\`\`\`tsx
-<Input label="Email" placeholder="you@example.com" />
-\`\`\`
-
-### Buttons
-\`\`\`tsx
-<Button variant="primary">Submit</Button>
-<Button variant="outline">Cancel</Button>
-<Button variant="ghost">Skip</Button>
-\`\`\`
-
-### Card with spacing tokens
-\`\`\`tsx
-<Card padding="var(--ggui-spacing-4)" shadow="md">
-  <Stack gap="var(--ggui-spacing-3)">
-    <Heading level={3}>Title</Heading>
-    <Text tone="muted">Description</Text>
-  </Stack>
-</Card>
-\`\`\`
-
-### Color usage guide
-- **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each \u2014 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**: Dividers and section rules \u2014 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 \u2014 fills and borders, NOT a text color
-- **link**: Accent TEXT \u2014 eyebrows, taglines, links, labels, inline arrows; the brand's readable ink per mode (a bare \`primary-300\u2026600\` as a text color fails tier-0: \`universal.accent_text_ink\`)
-- **primary-700/800/900**: Headings and text on light primary backgrounds
-- **neutral-***: Only when you need a specific shade that semantic tokens don't cover
-
-The primary palette is the app's brand \u2014 use it throughout (headers, accents, borders, interactive elements), not just on the submit button.
-
-**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-container, #fafafa)). Just use var(--ggui-color-container) \u2014 the theme provides all values.
-
-## Motion & Animation
-
-### Duration Scale
-- \`instant\`: 0ms
-- \`fast\`: 100ms
-- \`normal\`: 200ms
-- \`slow\`: 300ms
-- \`slower\`: 500ms
-
-### Easing Curves
-- \`linear\`: linear
-- \`easeIn\`: cubic-bezier(0.4, 0, 1, 1)
-- \`easeOut\`: cubic-bezier(0, 0, 0.2, 1)
-- \`easeInOut\`: cubic-bezier(0.4, 0, 0.2, 1)
-- \`spring\`: cubic-bezier(0.175, 0.885, 0.32, 1.275)
-
-### Transition Presets (import from '@ggui-ai/design/tokens')
-\`\`\`tsx
-import { duration, easing, transition } from '@ggui-ai/design/tokens';
-// transition.fast    \u2192 "100ms cubic-bezier(0.4, 0, 0.2, 1)"
-// transition.normal  \u2192 "200ms cubic-bezier(0.4, 0, 0.2, 1)"
-// transition.slow    \u2192 "300ms cubic-bezier(0.4, 0, 0.2, 1)"
-// transition.colors  \u2192 color + background-color + border-color (200ms each)
-// transition.opacity \u2192 opacity 200ms
-// transition.transform \u2192 transform 200ms
-\`\`\`
-
-### Animation Keyframes
-Use \`<MotionKeyframes />\` once in your component to inject all keyframes, then reference by name.
-
-**Entrance / exit** (GPU-composited, transform + opacity):
-- \`ggui-fadeIn\` / \`ggui-fadeOut\`
-- \`ggui-slideInUp\` / \`ggui-slideInDown\`
-- \`ggui-scaleIn\` / \`ggui-scaleOut\`
-
-**State feedback** (color-based, for data-change highlights):
-- \`ggui-flash\` \u2014 background-color highlight that fades out. Set \`--ggui-flash-color\` on the element (default: \`var(--ggui-color-primary-100)\`)
-- \`ggui-pulse\` \u2014 gentle opacity breathing (infinite, for "live" indicators)
-- \`ggui-bounce\` \u2014 subtle scale overshoot (one-shot, for confirmations)
-
-\`\`\`tsx
-import { MotionKeyframes, useMotion, useAnimationKey } from '@ggui-ai/design';
-import { animation } from '@ggui-ai/design/tokens';
-
-function MyComponent() {
-  const { motionEnabled } = useMotion(); // respects prefers-reduced-motion
-  return (
-    <>
-      <MotionKeyframes />
-      {/* Entrance animation */}
-      <div style={{ animation: motionEnabled ? animation.slideInUp : 'none' }}>
-        Content slides in
-      </div>
-    </>
-  );
-}
-\`\`\`
-
-### Retriggering Animations on Data Changes
-When data updates (e.g., stock price from a stream), CSS animations don't replay automatically.
-Use \`useAnimationKey(dep)\` \u2014 returns a key that increments when \`dep\` changes, causing React to remount the element and replay the animation.
-
-\`\`\`tsx
-import { MotionKeyframes, useAnimationKey } from '@ggui-ai/design';
-import { animation } from '@ggui-ai/design/tokens';
-
-// Flash a stock card green/red when the price changes
-const priceKey = useAnimationKey(stock.price);
-<div
-  key={priceKey}
-  style={{
-    animation: animation.flash,
-    '--ggui-flash-color': stock.change > 0
-      ? 'var(--ggui-color-success-100)'
-      : 'var(--ggui-color-error-100)',
-  } as React.CSSProperties}
->
-  {stock.price}
-</div>
-\`\`\`
-
-## Chart / Data Visualization Colors
-Semantic chart tokens for data visualizations:
-- \`var(--ggui-color-primary-600)\` \u2014 primary series
-- \`var(--ggui-color-success-500)\` \u2014 positive / success
-- \`var(--ggui-color-error-500)\` \u2014 negative / error
-- \`var(--ggui-color-warning-500)\` \u2014 warning / caution
-- \`var(--ggui-color-info-500)\` \u2014 informational
-- \`var(--ggui-color-neutral-400)\` \u2014 neutral series
-- \`var(--ggui-color-neutral-200)\` \u2014 light background series
-- \`var(--ggui-color-neutral-600)\` \u2014 dark series
-
-## Accessibility Tokens
-
-### Focus Ring (for keyboard focus states)
-- Color: \`var(--ggui-color-primary-600)\`
-- Width: 2px
-- Offset: 2px
-- Style: solid
-\`\`\`tsx
-// Apply to focusable elements:
-outline: '2px solid var(--ggui-color-primary-600)',
-outlineOffset: '2px',
-\`\`\`
-
-### Reduced Motion
-Use \`useMotion()\` hook to check user preference. If disabled, set animation/transition to \`none\`.
-
-## Elevation System
-Semantic depth levels combining shadow + z-index:
-| Level | Shadow | Z-Index | Use For |
-|-------|--------|---------|---------|
-| 0 | none | 0 | Flat content |
-| 1 | sm | auto | Cards, slight lift |
-| 2 | md | 1000 | Dropdowns, popovers |
-| 3 | lg | 1200 | Banners, sticky bars |
-| 4 | xl | 1400 | Modals, dialogs |
-| 5 | 2xl | 1800 | Tooltips, toasts |
-
-\`\`\`tsx
-import { elevation } from '@ggui-ai/design/tokens';
-// elevation.level1 \u2192 { shadow: 'var(--ggui-shape-shadow-sm)', zIndex: 'auto' }
-// elevation.level2 \u2192 { shadow: 'var(--ggui-shape-shadow-md)', zIndex: 1000 }
-<div style={{ boxShadow: elevation.level1.shadow, zIndex: elevation.level1.zIndex }}>
-  Card content
-</div>
-\`\`\`
-
-## Typography Presets
-
-### Heading Styles (import { headingStyles } from '@ggui-ai/design/tokens')
-| Level | Size | Weight | Line Height | Letter Spacing |
-|-------|------|--------|-------------|----------------|
-| h1 | 36px | bold (700) | 1.25 | -0.025em |
-| h2 | 30px | bold (700) | 1.25 | -0.025em |
-| h3 | 24px | semibold (600) | 1.375 | 0 |
-| h4 | 20px | semibold (600) | 1.375 | 0 |
-| h5 | 18px | semibold (600) | 1.5 | 0 |
-| h6 | 16px | semibold (600) | 1.5 | 0 |
-
-### Text Sizing
-\`<Text>\` composes from \`size\` / \`weight\` / \`tone\` (+ \`caps\` for the
-uppercase eyebrow look) \u2014 there is no preset text-style table. Line
-height derives from \`size\` automatically (1.5 for xs-base, 1.625 at lg,
-tighter on display sizes).
-
-### Letter Spacing Scale
-- \`tighter\`: -0.05em
-- \`tight\`: -0.025em
-- \`normal\`: 0
-- \`wide\`: 0.025em
-- \`wider\`: 0.05em
-- \`widest\`: 0.1em
-
-### Line Height Scale
-- \`none\`: 1
-- \`tight\`: 1.25
-- \`snug\`: 1.375
-- \`normal\`: 1.5
-- \`relaxed\`: 1.625
-- \`loose\`: 2`;
-
-// src/boilerplate/json-schema-ts.ts
-function jsonSchemaTypeToTs(schema) {
-  const unionMembers = schema.oneOf ?? schema.anyOf;
-  if (unionMembers?.length) {
-    const types = [...new Set(unionMembers.map((s) => jsonSchemaTypeToTs(s)))];
-    return types.length === 1 ? types[0] : types.join(" | ");
-  }
-  if (schema.const !== void 0) {
-    return typeof schema.const === "string" ? `'${schema.const}'` : String(schema.const);
-  }
-  if (schema.enum?.length) {
-    return schema.enum.map((v) => typeof v === "string" ? `'${v}'` : String(v)).join(" | ");
-  }
-  if (Array.isArray(schema.type)) {
-    const { nullable: _nullable, ...rest } = schema;
-    const members = [...new Set(schema.type)].map(
-      (member) => jsonSchemaTypeToTs({ ...rest, type: member })
-    );
-    const unique = [...new Set(members)];
-    if (schema.nullable && !unique.includes("null")) unique.push("null");
-    return unique.join(" | ");
-  }
-  let result;
-  switch (schema.type) {
-    case "string":
-      result = "string";
-      break;
-    case "number":
-    case "integer":
-      result = "number";
-      break;
-    case "boolean":
-      result = "boolean";
-      break;
-    case "null":
-      return "null";
-    case "array": {
-      if (schema.items) {
-        const itemType = jsonSchemaTypeToTs(schema.items);
-        const itemsDeclareObject = Array.isArray(schema.items.type) ? schema.items.type.includes("object") : schema.items.type === "object";
-        result = itemsDeclareObject && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
-      } else {
-        result = "unknown[]";
-      }
-      break;
-    }
-    case "object": {
-      if (schema.properties) {
-        const required = schema.required ?? [];
-        const fields = Object.entries(schema.properties).map(([key, prop]) => {
-          const opt = !required.includes(key);
-          return `${key}${opt ? "?" : ""}: ${jsonSchemaTypeToTs(prop)}`;
-        }).join("; ");
-        result = `{ ${fields} }`;
-      } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-        result = `Record<string, ${jsonSchemaTypeToTs(schema.additionalProperties)}>`;
-      } else {
-        result = "Record<string, unknown>";
-      }
-      break;
-    }
-    default:
-      result = "unknown";
-  }
-  if (schema.nullable && result !== "unknown") {
-    return `${result} | null`;
-  }
-  return result;
-}
-
-// src/check/contract-validation.ts
-function extractPropsInterface(code) {
-  const sf = ts3.createSourceFile("component.tsx", code, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
-  const props = [];
-  function visitMembers(members) {
-    for (const member of members) {
-      if (ts3.isPropertySignature(member) && member.name) {
-        const name = member.name.getText(sf);
-        const type = member.type ? member.type.getText(sf) : "unknown";
-        const optional = !!member.questionToken;
-        props.push({ name, type, optional });
-      }
-    }
-  }
-  function visit(node) {
-    if (ts3.isInterfaceDeclaration(node) && node.name.text === "Props") {
-      visitMembers(node.members);
-      return;
-    }
-    if (ts3.isTypeAliasDeclaration(node) && node.name.text === "Props") {
-      if (ts3.isTypeLiteralNode(node.type)) {
-        visitMembers(node.type.members);
-      }
-      return;
-    }
-    ts3.forEachChild(node, visit);
-  }
-  visit(sf);
-  return props.length > 0 ? props : null;
-}
-function validatePropsAgainstSchema(code, spec) {
-  const issues = [];
-  const extracted = extractPropsInterface(code);
-  if (!extracted) {
-    return [];
-  }
-  const extractedMap = new Map(extracted.map((p) => [p.name, p]));
-  for (const [propName, entry] of Object.entries(spec.properties)) {
-    const extractedProp = extractedMap.get(propName);
-    if (!extractedProp) {
-      if (entry.required) {
-        issues.push({
-          severity: "error",
-          field: propName,
-          message: `Props interface is missing required field '${propName}' from the data contract`,
-          fix: `Add \`${propName}${entry.required ? "" : "?"}: ${jsonSchemaTypeToTs(entry.schema)}\` to your Props interface`
-        });
-      } else {
-        issues.push({
-          severity: "warning",
-          field: propName,
-          message: `Props interface is missing optional field '${propName}' from the data contract`,
-          fix: `Consider adding \`${propName}?: ${jsonSchemaTypeToTs(entry.schema)}\` to your Props interface`
-        });
-      }
-      continue;
-    }
-    if (extractedProp.type !== "unknown") {
-      const expectedTsType = jsonSchemaTypeToTs(entry.schema);
-      if (!isTypeCompatible(extractedProp.type, expectedTsType, entry.schema)) {
-        issues.push({
-          severity: "warning",
-          field: propName,
-          message: `Field '${propName}' has type '${extractedProp.type}' but contract expects '${expectedTsType}'`,
-          fix: `Change \`${propName}\` type to \`${expectedTsType}\``
-        });
-      }
-    }
-  }
-  return issues;
-}
-function isTypeCompatible(tsType, expectedTsType, schema) {
-  const normalized = tsType.replace(/\s/g, "").toLowerCase();
-  switch (schema.type) {
-    case "string":
-      return normalized.includes("string");
-    case "number":
-    case "integer":
-      return normalized.includes("number");
-    case "boolean":
-      return normalized.includes("boolean");
-    case "array":
-      return normalized.includes("[]") || normalized.includes("array");
-    case "object":
-      return !["string", "number", "boolean"].some((t) => normalized === t);
-    default:
-      return true;
-  }
-}
-function validateStreamSpecConformance(code, spec) {
-  const issues = [];
-  const usesWireStream = code.includes("useStream");
-  if (!usesWireStream) {
-    issues.push({
-      severity: "error",
-      field: "__streamSpec__",
-      message: "Component does not handle stream events \u2014 use useStream() from the boilerplate wire hooks",
-      fix: "Use the useStream('eventName') hook from the boilerplate to receive real-time data from the agent"
-    });
-    return issues;
-  }
-  for (const [channelName, entry] of Object.entries(spec)) {
-    if (!code.includes(`'${channelName}'`) && !code.includes(`"${channelName}"`)) {
-      issues.push({
-        severity: "warning",
-        field: channelName,
-        message: `StreamSpec declares channel '${channelName}' but component doesn't reference it`,
-        fix: `Add useStream('${channelName}') to receive ${entry.description || channelName} events`
-      });
-    }
-  }
-  return issues;
-}
-function validateActionSpecConformance(code, spec) {
-  const issues = [];
-  for (const [actionId, entry] of Object.entries(spec)) {
-    const idReferenced = code.includes(`'${actionId}'`) || code.includes(`"${actionId}"`);
-    const labelReferenced = code.includes(entry.label);
-    const callbackName = `on${actionId.charAt(0).toUpperCase()}${actionId.slice(1)}`;
-    const callbackReferenced = code.includes(callbackName);
-    if (!idReferenced && !labelReferenced && !callbackReferenced) {
-      issues.push({
-        severity: "error",
-        field: actionId,
-        message: `ActionSpec declares action '${actionId}' ("${entry.label}") but component doesn't wire it`,
-        fix: `Use the useAction('${actionId}') hook from the boilerplate and wire it to a button or form submit`
-      });
-    }
-  }
-  return issues;
-}
-function validateAllContracts(code, contract) {
-  const issues = [];
-  if (contract.propsSpec) {
-    issues.push(...validatePropsAgainstSchema(code, contract.propsSpec));
-  }
-  if (contract.streamSpec) {
-    issues.push(...validateStreamSpecConformance(code, contract.streamSpec));
-  }
-  if (contract.actionSpec) {
-    issues.push(...validateActionSpecConformance(code, contract.actionSpec));
-  }
-  return issues;
-}
-var BLOCKING_CODES = /* @__PURE__ */ new Set([
-  2304,
-  // Cannot find name
-  // 2307 (Cannot find module) is NOT blocking — Lambda bundles code without
-  // type declarations, so the VFS can't resolve react/@ggui-ai/design.
-  // Forbidden imports are caught by runSelfChecks regex instead.
-  2305,
-  // Module has no exported member
-  2322,
-  // Type not assignable
-  2339,
-  // Property does not exist on type
-  2741,
-  // Missing required property
-  2769,
-  // No overload matches this call
-  17004,
-  // Cannot use JSX unless '--jsx' flag
-  18047,
-  // 'X' is possibly 'null' — causes runtime crash
-  18048
-  // 'X' is possibly 'undefined' — causes runtime crash
-]);
-function generateFix(code, message, sourceLine) {
-  const sourceHint = sourceLine && sourceLine.length > 0 && sourceLine.length <= 140 ? ` Offending line: \`${sourceLine}\`` : "";
-  if ((code === 2322 || code === 2339) && message && /onClick|onDoubleClick|onMouseEnter|onMouseLeave|onPress/.test(message)) {
-    return `This structural primitive has no event handlers of its own \u2014 add the trait as a PROP: as={Clickable} (then onClick works), imported from @ggui-ai/design. Do NOT wrap it in <Clickable>\u2026</Clickable>; as is a prop, not a wrapper element.${sourceHint}`;
-  }
-  if (code === 2339 && message && /Property '_[a-zA-Z]/.test(message)) {
-    return `You renamed a prop with a leading underscore to silence \`no-unused-vars\`, but the prop on \`Props\` doesn't have that prefix. Restore the original name; better, don't destructure props you won't render \u2014 access them via \`props.fieldName\` only when needed.${sourceHint}`;
-  }
-  if (code === 2304 && message && !message.includes("module") && !message.includes("import")) {
-    return `This name is not defined in scope. Either you destructured props (use \`props.fieldName\` directly instead) OR you removed a helper declaration in this patch but kept a JSX/expression reference to it. Read your full patch and either restore the declaration or remove the reference.${sourceHint}`;
-  }
-  if ((code === 2322 || code === 2769) && message && /unknown.*ReactNode|ReactNode.*unknown/.test(message)) {
-    return `This value has type 'unknown' and cannot be rendered in JSX. Cast it: String(value) or add a type annotation.${sourceHint}`;
-  }
-  switch (code) {
-    case 2307:
-      return `Only these imports are allowed: ${describeAllowedImports()}${sourceHint}`;
-    case 2322:
-    case 2769:
-      return `Type mismatch on this expression. Check the offending line below \u2014 the prop name in JSX is what TypeScript is rejecting; the message tells you the expected type.${sourceHint}`;
-    case 2339:
-      return `This prop doesn't exist on this component \u2014 check the available props on the component's interface (visible at the top of the file, or in the design-system reference).${sourceHint}`;
-    case 2305:
-      return `This name is not defined. Check your imports and variable declarations.${sourceHint}`;
-    case 2741:
-      return `A required prop is missing. Check the component's Props interface.${sourceHint}`;
-    case 18047:
-    case 18048:
-      return `This value might be null/undefined. Every dereference on the same nullable still needs \`?.\` \u2014 \`x?.foo && x?.bar\`, NOT \`x?.foo && x.bar\`. Or hoist: \`const v = x; if (!v) return null;\` then access \`v.foo\`/\`v.bar\` unguarded.${sourceHint}`;
-    default:
-      return `Review the TypeScript error and fix the type issue.${sourceHint}`;
-  }
-}
-var vfsCache = null;
-function parseAndStore(vfs, virtualPath, content) {
-  const sourceFile = ts3.createSourceFile(
-    virtualPath,
-    content,
-    ts3.ScriptTarget.ES2020,
-    true,
-    virtualPath.endsWith(".tsx") ? ts3.ScriptKind.TSX : ts3.ScriptKind.TS
-  );
-  vfs.set(virtualPath, { content, sourceFile });
-}
-function walkDir(dir, filter) {
-  const results = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      results.push(...walkDir(full, filter));
-    } else if (filter(full)) {
-      results.push(full);
-    }
-  }
-  return results;
-}
-function findReactTypesDir() {
-  try {
-    const indexDts = createRequire(import.meta.url).resolve("@types/react/index.d.ts");
-    return path.dirname(indexDts);
-  } catch {
-    return null;
-  }
-}
-function findPackageDistDir(pkg) {
-  try {
-    const pkgJson = createRequire(import.meta.url).resolve(`${pkg}/package.json`);
-    const dist = path.join(path.dirname(pkgJson), "dist");
-    return fs.existsSync(dist) ? dist : null;
-  } catch {
-    return null;
-  }
-}
-async function loadVfs() {
-  if (vfsCache) return vfsCache;
-  const vfs = /* @__PURE__ */ new Map();
-  const require_ = createRequire(import.meta.url);
-  const tsDir = path.dirname(require_.resolve("typescript/lib/typescript.js"));
-  const libFiles = fs.readdirSync(tsDir).filter((f) => /^lib\..*\.d\.ts$/.test(f));
-  for (const file of libFiles) {
-    const content = fs.readFileSync(path.join(tsDir, file), "utf-8");
-    parseAndStore(vfs, file, content);
-  }
-  const reactDir = findReactTypesDir();
-  if (reactDir) {
-    const reactDts = fs.readdirSync(reactDir).filter((f) => f.endsWith(".d.ts"));
-    for (const file of reactDts) {
-      const content = fs.readFileSync(path.join(reactDir, file), "utf-8");
-      parseAndStore(vfs, `node_modules/@types/react/${file}`, content);
-    }
-  }
-  const designDist = findPackageDistDir("@ggui-ai/design");
-  if (designDist) {
-    const dtsFiles = walkDir(designDist, (f) => f.endsWith(".d.ts") && !f.endsWith(".d.ts.map"));
-    for (const file of dtsFiles) {
-      const rel = path.relative(designDist, file);
-      const content = fs.readFileSync(file, "utf-8");
-      parseAndStore(vfs, `node_modules/@ggui-ai/design/${rel}`, content);
-    }
-  }
-  const wireDist = findPackageDistDir("@ggui-ai/wire");
-  if (wireDist) {
-    const dtsFiles = walkDir(wireDist, (f) => f.endsWith(".d.ts") && !f.endsWith(".d.ts.map"));
-    for (const file of dtsFiles) {
-      const rel = path.relative(wireDist, file);
-      const content = fs.readFileSync(file, "utf-8");
-      parseAndStore(vfs, `node_modules/@ggui-ai/wire/${rel}`, content);
-    }
-  }
-  const clientLibsDist = findPackageDistDir("@ggui-ai/gadgets");
-  if (clientLibsDist) {
-    const dtsFiles = walkDir(
-      clientLibsDist,
-      (f) => f.endsWith(".d.ts") && !f.endsWith(".d.ts.map")
-    );
-    for (const file of dtsFiles) {
-      const rel = path.relative(clientLibsDist, file);
-      const content = fs.readFileSync(file, "utf-8");
-      parseAndStore(vfs, `node_modules/@ggui-ai/gadgets/${rel}`, content);
-    }
-  }
-  vfsCache = vfs;
-  return vfs;
-}
-function resolveRelativeInVfs(vfs, containingFile, importPath) {
-  const normalized = containingFile.startsWith("/") ? containingFile.slice(1) : containingFile;
-  const dir = path.posix.dirname(normalized);
-  const specifier = importPath.replace(/\.(?:m|c)?js$/, "");
-  const resolved2 = path.posix.normalize(`${dir}/${specifier}`);
-  const withDts = `${resolved2}.d.ts`;
-  if (vfs.has(withDts)) return withDts;
-  const withIndexDts = `${resolved2}/index.d.ts`;
-  if (vfs.has(withIndexDts)) return withIndexDts;
-  const withTs = `${resolved2}.ts`;
-  if (vfs.has(withTs)) return withTs;
-  if (vfs.has(resolved2)) return resolved2;
-  return void 0;
-}
-var COMPILER_OPTIONS = {
-  target: ts3.ScriptTarget.ES2020,
-  module: ts3.ModuleKind.ESNext,
-  // Classic React JSX mode. The synthetic prefix (SYNTHETIC_PREFIX)
-  // supplies `import React from 'react'` plus a `declare global` JSX
-  // namespace shim: `@types/react` v19 removed the *global* `JSX`
-  // namespace (it lives at `React.JSX` now), which classic mode needs
-  // for `JSX.IntrinsicElements` and the `key`/`ref` carve-out. Without
-  // the shim, `<div>` degrades to `any` and every typed component
-  // falsely rejects the intrinsic `key` prop.
-  jsx: ts3.JsxEmit.React,
-  moduleResolution: ts3.ModuleResolutionKind.Bundler,
-  strict: false,
-  strictNullChecks: true,
-  // Catch undefined.foo() errors that cause runtime crashes
-  noEmit: true,
-  skipLibCheck: true,
-  noImplicitAny: true,
-  types: [],
-  esModuleInterop: true
-};
-function normalizeVfsPath(f) {
-  if (f.startsWith("/")) {
-    return f.slice(1);
-  }
-  return null;
-}
-function resolveModuleName(vfs, name, containingFile) {
-  if (name === "react") {
-    return resolved("node_modules/@types/react/index.d.ts");
-  }
-  if (name === "react/jsx-runtime") {
-    return resolved("node_modules/@types/react/jsx-runtime.d.ts");
-  }
-  if (name === "react/jsx-dev-runtime") {
-    const p = "node_modules/@types/react/jsx-dev-runtime.d.ts";
-    if (vfs.has(p)) return resolved(p);
-    return resolved("node_modules/@types/react/jsx-runtime.d.ts");
-  }
-  const designPrefix = "@ggui-ai/design/";
-  if (name.startsWith(designPrefix)) {
-    const subpath = name.slice(designPrefix.length);
-    const indexPath = `node_modules/@ggui-ai/design/${subpath}/index.d.ts`;
-    if (vfs.has(indexPath)) return resolved(indexPath);
-    const directPath = `node_modules/@ggui-ai/design/${subpath}.d.ts`;
-    if (vfs.has(directPath)) return resolved(directPath);
-  }
-  if (name === "@ggui-ai/design") {
-    return resolved("node_modules/@ggui-ai/design/index.d.ts");
-  }
-  if (name === "@ggui-ai/wire") {
-    return resolved("node_modules/@ggui-ai/wire/index.d.ts");
-  }
-  if (name === "@ggui-ai/gadgets") {
-    return resolved("node_modules/@ggui-ai/gadgets/index.d.ts");
-  }
-  if (name.startsWith("./") || name.startsWith("../")) {
-    const resolvedPath = resolveRelativeInVfs(vfs, containingFile, name);
-    if (resolvedPath) return resolved(resolvedPath);
-  }
-  const bareIndex = `node_modules/${name}/index.d.ts`;
-  if (vfs.has(bareIndex)) return resolved(bareIndex);
-  return { resolvedModule: void 0 };
-}
-function createVfsHost(vfs, componentCode) {
-  const componentFile = ts3.createSourceFile(
-    "Component.tsx",
-    componentCode,
-    ts3.ScriptTarget.ES2020,
-    true,
-    ts3.ScriptKind.TSX
-  );
-  const host = {
-    getSourceFile(fileName) {
-      if (fileName === "Component.tsx") return componentFile;
-      const entry = vfs.get(fileName);
-      if (entry) return entry.sourceFile;
-      const normalized = normalizeVfsPath(fileName);
-      if (normalized) return vfs.get(normalized)?.sourceFile;
-      return void 0;
-    },
-    getDefaultLibFileName() {
-      return "lib.es2020.full.d.ts";
-    },
-    writeFile() {
-    },
-    getCurrentDirectory() {
-      return "/";
-    },
-    getCanonicalFileName(f) {
-      return f;
-    },
-    useCaseSensitiveFileNames() {
-      return true;
-    },
-    getNewLine() {
-      return "\n";
-    },
-    fileExists(f) {
-      if (f === "Component.tsx" || vfs.has(f)) return true;
-      const normalized = normalizeVfsPath(f);
-      if (normalized && vfs.has(normalized)) return true;
-      return false;
-    },
-    readFile(f) {
-      if (f === "Component.tsx") return componentCode;
-      const direct = vfs.get(f);
-      if (direct) return direct.content;
-      const normalized = normalizeVfsPath(f);
-      if (normalized) return vfs.get(normalized)?.content;
-      return void 0;
-    },
-    resolveModuleNameLiterals(moduleLiterals, containingFile) {
-      return moduleLiterals.map(
-        (literal) => resolveModuleName(vfs, literal.text, containingFile)
-      );
-    }
-  };
-  return host;
-}
-function resolved(resolvedFileName) {
-  return {
-    resolvedModule: {
-      resolvedFileName,
-      isExternalLibraryImport: true,
-      extension: ts3.Extension.Dts
-    }
-  };
-}
-async function typecheck(code, dtsMap) {
-  const vfs = await loadVfs();
-  const effectiveVfs = (() => {
-    const dtsEntries = [];
-    if (dtsEntries.length === 0) {
-      return vfs;
-    }
-    const overlay = new Map(vfs);
-    for (const [pkg, content] of dtsEntries) {
-      parseAndStore(overlay, `node_modules/${pkg}/index.d.ts`, content);
-    }
-    return overlay;
-  })();
-  const globalJsxShim = "declare global { namespace JSX { type ElementType = string | ((props: any) => any) | (new (props: any) => any); interface Element { type: any; props: any; key: string | number | null; } interface ElementClass { render(): any; } interface ElementAttributesProperty { props: object; } interface ElementChildrenAttribute { children: object; } interface IntrinsicAttributes { key?: string | number | bigint | null; } interface IntrinsicClassAttributes<T> { ref?: any; } interface IntrinsicElements { [elem: string]: any; } } }\n";
-  const SYNTHETIC_PREFIX = "import React from 'react';\n" + globalJsxShim;
-  const prefixedCode = SYNTHETIC_PREFIX + code;
-  const lineOffset = SYNTHETIC_PREFIX.split("\n").length - 1;
-  const host = createVfsHost(effectiveVfs, prefixedCode);
-  const program = ts3.createProgram(["Component.tsx"], COMPILER_OPTIONS, host);
-  const diagnostics = ts3.getPreEmitDiagnostics(program);
-  const errors = [];
-  const warnings = [];
-  for (const diag of diagnostics) {
-    if (diag.file && diag.file.fileName !== "Component.tsx") continue;
-    if (!diag.file) continue;
-    const diagLine = ts3.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line;
-    if (diagLine < lineOffset) continue;
-    const rawLine = diag.file ? ts3.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line + 1 : 0;
-    const line = Math.max(1, rawLine - lineOffset);
-    const message = ts3.flattenDiagnosticMessageText(diag.messageText, "\n");
-    const code_ = diag.code;
-    const sourceLines = diag.file.text.split("\n");
-    const sourceLine = rawLine >= 1 && rawLine <= sourceLines.length ? sourceLines[rawLine - 1]?.trim() ?? "" : "";
-    const entry = {
-      code: code_,
-      line,
-      message,
-      fix: generateFix(code_, message, sourceLine)
-    };
-    if (BLOCKING_CODES.has(code_)) {
-      errors.push(entry);
-    } else {
-      warnings.push(entry);
-    }
-  }
-  return { errors, warnings };
-}
-var linterInstance = null;
-async function getLinter() {
-  if (!linterInstance) {
-    linterInstance = new Linter();
-    const tsParser = await import('@typescript-eslint/parser');
-    linterInstance.defineParser("@typescript-eslint/parser", tsParser);
-    const reactHooksPlugin = await import('eslint-plugin-react-hooks');
-    const hooksRules = reactHooksPlugin.default?.rules ?? reactHooksPlugin.rules;
-    for (const [name, rule] of Object.entries(hooksRules)) {
-      linterInstance.defineRule(`react-hooks/${name}`, rule);
-    }
-    const reactPlugin = await import('eslint-plugin-react');
-    const reactRules = reactPlugin.default?.rules ?? reactPlugin.rules;
-    for (const [name, rule] of Object.entries(reactRules)) {
-      linterInstance.defineRule(`react/${name}`, rule);
-    }
-  }
-  return linterInstance;
-}
-async function lintReactHooks(code) {
-  const linter = await getLinter();
-  let messages;
-  try {
-    const config = {
-      parser: "@typescript-eslint/parser",
-      parserOptions: {
-        ecmaVersion: 2022,
-        sourceType: "module",
-        ecmaFeatures: { jsx: true }
-      },
-      rules: {
-        "react-hooks/rules-of-hooks": 2,
-        "react-hooks/exhaustive-deps": 1,
-        // React rules
-        "react/jsx-no-undef": 2,
-        // undefined JSX components
-        "react/jsx-key": 1,
-        // missing key in lists
-        "react/no-direct-mutation-state": 2,
-        // direct state mutation
-        // An unused `const submit = useAction('submit')` is a
-        // dead contract wire. Narrow the rule to variable bindings we
-        // care about: skip function args (LLMs legitimately omit unused
-        // params), skip destructured `rest` collectors, respect a `_`-
-        // prefix escape hatch for intentionally-ignored declarations,
-        // and silence the caught-error slot (async error handling can
-        // leave `catch (err)` unused at a boundary).
-        "no-unused-vars": [2, {
-          vars: "all",
-          args: "none",
-          ignoreRestSiblings: true,
-          varsIgnorePattern: "^_",
-          caughtErrors: "none"
-        }]
-      },
-      settings: {
-        react: { version: "19.0" }
-      }
-    };
-    messages = linter.verify(code, config, { filename: "component.tsx" });
-  } catch {
-    return [];
-  }
-  const diagnostics = [];
-  const ADMITTED_RULES = (id) => id.startsWith("react-hooks/") || id.startsWith("react/") || id === "no-unused-vars";
-  for (const msg of messages) {
-    if (!msg.ruleId) continue;
-    if (!ADMITTED_RULES(msg.ruleId)) continue;
-    diagnostics.push({
-      rule: msg.ruleId,
-      line: msg.line,
-      message: msg.message,
-      fix: generateReactFix(msg.ruleId, msg.message),
-      severity: resolveSeverity(msg, code)
-    });
-  }
-  return diagnostics;
-}
-function resolveSeverity(msg, code) {
-  const base = msg.severity === 2 ? "error" : "warning";
-  if (msg.ruleId !== "no-unused-vars" || base !== "error") return base;
-  const name = msg.message.match(/'([^']+)'/)?.[1];
-  if (name === void 0) return "warning";
-  const safe = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const directRe = new RegExp(
-    `\\bconst\\s+${safe}\\s*=\\s*use(Action|Stream|GguiContext)\\s*[<(]`
-  );
-  const destructuredRe = new RegExp(
-    `\\bconst\\s+\\[[^\\]]*\\b${safe}\\b[^\\]]*\\]\\s*=\\s*use(Action|Stream|GguiContext)\\s*[<(]`
-  );
-  return directRe.test(code) || destructuredRe.test(code) ? "error" : "warning";
-}
-function generateReactFix(ruleId, message) {
-  if (ruleId === "react-hooks/rules-of-hooks") {
-    if (message.includes("called conditionally")) {
-      return "Move this hook to the top level of the component, before any early returns or conditionals. Hooks must run in the same order every render.";
-    }
-    return "Hooks can only be called at the top level of a React function component or custom hook. Move it out of any conditional, loop, nested function, or callback.";
-  }
-  if (ruleId === "react-hooks/exhaustive-deps") {
-    return "Add the missing dependencies to the dependency array, or remove the array to run on every render.";
-  }
-  if (ruleId === "react/jsx-no-undef") {
-    const match = message.match(/'(\w+)'/);
-    const name = match?.[1] ?? "Component";
-    return `'${name}' is not defined. Import it from the design system or define it in the file.`;
-  }
-  if (ruleId === "react/jsx-key") {
-    return 'Add a unique "key" prop to each element rendered inside a .map() or iterator.';
-  }
-  if (ruleId === "react/no-direct-mutation-state") {
-    return "Do not mutate state directly. Use setState or the setter from useState instead.";
-  }
-  if (ruleId === "no-unused-vars") {
-    const match = message.match(/'([^']+)'/);
-    const name = match?.[1] ?? "variable";
-    const isLikelyWireBinding = /\bconst\s+[A-Za-z_$][\w$]*\s*=\s*use(Action|Stream)\s*\(/.test(message);
-    if (isLikelyWireBinding || /^(submit|cancel|search|progress|snapshot)$/.test(name)) {
-      return `'${name}' is declared but never used. If this binding came from a wire hook (useAction / useStream) or a clientCapabilities hook (useGeolocation / useCamera / etc. from @ggui-ai/gadgets), consume it somewhere in the component \u2014 render its value in JSX, bind it to a callback prop, or use it in an effect. A contract-declared hook without consumption is a dead wire.`;
-    }
-    return `'${name}' is declared but never used. Remove the declaration, or consume it somewhere in the component. Prefix with '_' (e.g. '_${name}') to mark it intentionally unused.`;
-  }
-  return "Fix the React violation.";
-}
-var NOT_YET_TAUGHT_TOKENS = /* @__PURE__ */ new Set([]);
-consumedTokenManifest.filter(
-  (token) => !NOT_YET_TAUGHT_TOKENS.has(token)
-);
-
-// src/check/run-tier0.ts
-new Set(consumedTokenManifest);
-
-// src/check/sample-props.ts
-function generateSampleProps(spec) {
-  const props = {};
-  for (const [name, entry] of Object.entries(spec.properties)) {
-    if (entry.example !== void 0) {
-      props[name] = entry.example;
-      continue;
-    }
-    if (entry.default !== void 0) {
-      props[name] = entry.default;
-      continue;
-    }
-    props[name] = synthesizeFromSchema(entry.schema);
-  }
-  return props;
-}
-function synthesizeFromSchema(schema) {
-  const declared = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type;
-  switch (declared) {
-    case "string":
-      return "sample";
-    case "number":
-    case "integer":
-      return 0;
-    case "boolean":
-      return false;
-    case "null":
-      return null;
-    case "array": {
-      if (schema.items) return [synthesizeFromSchema(schema.items) ?? null];
-      return [];
-    }
-    case "object": {
-      const obj = {};
-      if (schema.properties) {
-        for (const [k, v] of Object.entries(schema.properties)) {
-          obj[k] = synthesizeFromSchema(v);
-        }
-      }
-      return obj;
-    }
-    default:
-      return void 0;
-  }
-}
-
-// src/internal/verdict-line.ts
-var VERDICT_PREFIX = "@@ggui-render-check-verdict@@";
-function parseVerdictLine(stdout) {
-  const lines = stdout.split("\n");
-  for (let i = lines.length - 1; i >= 0; i -= 1) {
-    const line = lines[i];
-    if (line.startsWith(`${VERDICT_PREFIX} `)) return JSON.parse(line.slice(VERDICT_PREFIX.length + 1));
-  }
-  return void 0;
-}
-
-// src/tools/render-check.ts
-var RENDER_TIMEOUT_MS = 12e3;
-var RENDER_STDOUT_CAP = 512 * 1024;
-var RENDER_NODE_HEAP_MB = 256;
-function resolveWorkerSpawn() {
-  const jsCandidates = [
-    new URL("./render-check-worker.js", import.meta.url),
-    new URL("../tools/render-check-worker.js", import.meta.url)
-  ];
-  const tsCandidates = [
-    new URL("./render-check-worker.ts", import.meta.url),
-    new URL("../tools/render-check-worker.ts", import.meta.url)
-  ];
-  for (const jsUrl of jsCandidates) {
-    const jsPath = fileURLToPath(jsUrl);
-    if (existsSync(jsPath)) {
-      return { command: process.execPath, args: [jsPath] };
-    }
-  }
-  for (const tsUrl of tsCandidates) {
-    const tsPath = fileURLToPath(tsUrl);
-    if (existsSync(tsPath)) {
-      const require_ = createRequire(import.meta.url);
-      const tsxLoader = pathToFileURL(require_.resolve("tsx")).href;
-      return {
-        command: process.execPath,
-        args: ["--import", tsxLoader, tsPath]
-      };
-    }
-  }
-  const tried = [...jsCandidates, ...tsCandidates].map((u) => fileURLToPath(u)).join(", ");
-  throw new Error(
-    `render-check: worker not found at any of: ${tried}. Did \`pnpm build\` run?`
-  );
-}
-async function tryRender(compiledCode, sourceCode, sampleProps) {
-  const payload = JSON.stringify({ sourceCode, sampleProps });
-  const spawn = resolveWorkerSpawn();
-  const result = await runSandboxed({
-    command: spawn.command,
-    args: spawn.args,
-    timeoutMs: RENDER_TIMEOUT_MS,
-    maxStdoutBytes: RENDER_STDOUT_CAP,
-    nodeHeapMb: RENDER_NODE_HEAP_MB,
-    stdin: payload,
-    // Forward only what the worker needs. NODE_ENV lets React pick
-    // production vs development builds; everything else stays at the
-    // sandbox's default allowlist (PATH/HOME/TMPDIR bootstrap).
-    env: {
-      NODE_ENV: process.env.NODE_ENV ?? "production"
-    }
-  });
-  if (result.outcome === "timeout") {
-    return `Render timeout: component did not finish within ${RENDER_TIMEOUT_MS}ms (likely infinite loop or runaway recursion).`;
-  }
-  if (result.outcome === "overflow-stdout" || result.outcome === "overflow-stderr") {
-    return `Render error: worker produced excessive output (${result.outcome}). The component is likely in a pathological state.`;
-  }
-  if (result.outcome === "canceled") {
-    return "Render error: smoke test was canceled before completing.";
-  }
-  if (result.outcome === "spawn-error") {
-    return `Render error: failed to start worker \u2014 ${result.errorMessage}`;
-  }
-  if (result.outcome !== "exit") {
-    return `Render error: unexpected sandbox outcome '${result.outcome}'.`;
-  }
-  if (result.exitCode !== 0) {
-    const tail = result.stderr.trim() || result.stdout.trim();
-    return `Render error: worker exited ${result.exitCode}${tail ? ` \u2014 ${tail}` : ""}`;
-  }
-  let verdict;
-  try {
-    verdict = parseVerdictLine(result.stdout);
-  } catch (err) {
-    return `Render error: malformed worker verdict \u2014 ${err instanceof Error ? err.message : String(err)}`;
-  }
-  if (verdict === void 0) {
-    return "Render error: worker exited without producing a verdict.";
-  }
-  return verdict.ok ? null : verdict.error;
-}
-
-// src/adapters/tools.ts
-function createGeneratorTools(context = {}) {
-  const tools = [
-    // --- get_primitives ---
-    {
-      name: "get_primitives",
-      description: "Get the list of available ggui UI primitives (Container, Card, Stack, Button, Input, etc.) that can be used in components. Call this first to understand what components are available.",
-      inputSchema: z.object({}),
-      handler: async () => ({
-        content: [{ type: "text", text: PRIMITIVES_DOCUMENTATION }]
-      })
-    },
-    // --- get_design_system ---
-    {
-      name: "get_design_system",
-      description: "Get the design system tokens and CSS variables for this app. Use these CSS variables (var(--ggui-*)) for colors, spacing, typography, etc.",
-      inputSchema: z.object({}),
-      handler: async () => ({
-        content: [{
-          type: "text",
-          text: context.designContext ? `# App Theme Configuration
-
-${context.designContext}
-
-**IMPORTANT:** Always use CSS variables (var(--ggui-*)) for colors, spacing, etc.` : DEFAULT_DESIGN_SYSTEM_DOCS
-        }]
-      })
-    },
-    // --- get_app_components ---
-    {
-      name: "get_app_components",
-      description: "Get predefined reusable components specific to this app. These can be imported and used in your generated component.",
-      inputSchema: z.object({}),
-      handler: async () => ({
-        content: [{
-          type: "text",
-          text: context.componentContext || "No predefined components available for this app."
-        }]
-      })
-    },
-    // --- validate_component ---
-    {
-      name: "validate_component",
-      description: "Validate component code before compilation. Checks for security issues, syntax errors, and best practices. Returns detailed feedback.",
-      inputSchema: z.object({
-        code: z.string().describe("The TypeScript/TSX component code to validate")
-      }),
-      handler: async (args) => {
-        const result = validateComponentDetailed(args.code);
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatValidationResultForClaude(result)
-            }
-          ],
-          isError: !result.valid
-        };
-      }
-    },
-    // --- self_check ---
-    {
-      name: "self_check",
-      description: "Run deterministic quality checks on your code BEFORE compiling. Catches common issues instantly (zero cost). Returns pass/fail per check with line numbers and fix instructions. Call this after writing code, fix any failures, then compile.",
-      inputSchema: z.object({
-        code: z.string().describe("The TypeScript/TSX component code to check")
-      }),
-      handler: async (args) => {
-        const code = args.code;
-        const { issues, typeWarnings } = await runSelfChecks(code, context.contract);
-        if (context.contract) {
-          const contractIssues = validateAllContracts(code, context.contract);
-          for (const ci of contractIssues) {
-            issues.push({
-              check: `contract:${ci.field}`,
-              line: 0,
-              message: `[${ci.severity}] ${ci.message}`,
-              fix: ci.fix
-            });
-          }
-        }
-        if (issues.length === 0) {
-          const warningText = typeWarnings.length > 0 ? `
-
-Type warnings (non-blocking):
-${typeWarnings.map((w) => `[${w.check}] ${w.line ? `Line ${w.line}: ` : ""}${w.message}`).join("\n")}` : "";
-          return {
-            content: [{ type: "text", text: `All checks passed. Ready to compile.${warningText}` }]
-          };
-        }
-        const report = issues.map((i) => `[${i.check}] ${i.line ? `Line ${i.line}: ` : ""}${i.message}
-  Fix: ${i.fix}`).join("\n\n");
-        return {
-          content: [{ type: "text", text: `${issues.length} issue(s) found:
-
-${report}` }],
-          isError: true
-        };
-      }
-    },
-    // --- compile_component ---
-    {
-      name: "compile_component",
-      description: "Compile a TypeScript/TSX component to JavaScript using esbuild. Returns the compiled code ready for browser execution. On failure, returns detailed error context with line numbers and fix suggestions.",
-      inputSchema: z.object({
-        code: z.string().describe("The TypeScript/TSX component code to compile"),
-        filename: z.string().default("Component.tsx").describe("Filename for error messages")
-      }),
-      handler: async (args) => {
-        const code = args.code;
-        const filename = args.filename || "Component.tsx";
-        const { issues: selfCheckIssues } = await runSelfChecks(code, context.contract);
-        if (context.contract) {
-          const contractIssues = validateAllContracts(code, context.contract);
-          for (const ci of contractIssues) {
-            selfCheckIssues.push({
-              check: `contract:${ci.field}`,
-              line: 0,
-              message: `[${ci.severity}] ${ci.message}`,
-              fix: ci.fix
-            });
-          }
-        }
-        if (selfCheckIssues.length > 0) {
-          const report = selfCheckIssues.map((i) => `[${i.check}] ${i.line ? `Line ${i.line}: ` : ""}${i.message}
-  Fix: ${i.fix}`).join("\n\n");
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify({
-                success: false,
-                phase: "self_check",
-                error: `${selfCheckIssues.length} issue(s) found \u2014 fix these before recompiling:
-
-${report}`
-              }, null, 2)
-            }],
-            isError: true
-          };
-        }
-        const validation = validateComponentDetailed(code);
-        if (!validation.valid) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  {
-                    success: false,
-                    phase: "validation",
-                    error: formatValidationResultForClaude(validation)
-                  },
-                  null,
-                  2
-                )
-              }
-            ],
-            isError: true
-          };
-        }
-        try {
-          const result = await esbuild.transform(code, {
-            loader: "tsx",
-            target: "es2020",
-            format: "esm",
-            jsx: "automatic",
-            jsxImportSource: "react",
-            minify: true,
-            sourcefile: filename
-          });
-          const warnings = [
-            ...result.warnings.map((w) => w.text),
-            ...validation.warnings.map(
-              (w) => `[${w.type}] ${w.message}: ${w.suggestion}`
-            )
-          ];
-          if (context.contract) {
-            const contractIssues = validateAllContracts(code, context.contract);
-            const errors = contractIssues.filter((i) => i.severity === "error");
-            const contractWarnings = contractIssues.filter((i) => i.severity === "warning");
-            if (errors.length > 0) {
-              const report = errors.map((i) => `- [${i.field}] ${i.message}
-  Fix: ${i.fix}`).join("\n");
-              return {
-                content: [{
-                  type: "text",
-                  text: JSON.stringify({
-                    success: false,
-                    phase: "contract_validation",
-                    error: `Compilation succeeded but data contract validation failed:
-
-${report}
-
-Fix the Props interface to match the data contract, then recompile.`
-                  }, null, 2)
-                }],
-                isError: true
-              };
-            }
-            warnings.push(...contractWarnings.map((i) => `[contract:${i.field}] ${i.message}`));
-          }
-          const sampleProps = context.sampleProps ?? (context.contract?.propsSpec ? generateSampleProps(context.contract.propsSpec) : void 0);
-          const renderError = await tryRender(result.code, code, sampleProps);
-          if (renderError) {
-            return {
-              content: [{
-                type: "text",
-                text: JSON.stringify({
-                  success: false,
-                  phase: "render_smoke_test",
-                  compiledCode: result.code,
-                  error: `${renderError}
-
-The component compiled but crashes at runtime. Fix the null/undefined access and recompile.`,
-                  warnings
-                }, null, 2)
-              }],
-              isError: true
-            };
-          }
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  {
-                    success: true,
-                    compiledCode: result.code,
-                    warnings
-                  },
-                  null,
-                  2
-                )
-              }
-            ]
-          };
-        } catch (error) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  { success: false, phase: "compilation", error: formatEsbuildError(error, code) },
-                  null,
-                  2
-                )
-              }
-            ],
-            isError: true
-          };
-        }
-      }
-    }
-  ];
-  return tools;
-}
-function formatEsbuildError(error, sourceCode) {
-  const parts = [];
-  if (error && typeof error === "object" && "errors" in error && Array.isArray(error.errors)) {
-    const esbuildError = error;
-    for (const err of esbuildError.errors) {
-      const line = err.location?.line;
-      const col = err.location?.column;
-      parts.push(`**Error:** ${err.text}`);
-      if (line) {
-        parts.push(`**Location:** Line ${line}, Column ${col ?? 0}`);
-        const lines = sourceCode.split("\n");
-        const start = Math.max(0, line - 3);
-        const end = Math.min(lines.length, line + 2);
-        const context = lines.slice(start, end).map((l, i) => {
-          const ln = start + i + 1;
-          return `${ln === line ? ">>> " : "    "}${ln} | ${l}`;
-        }).join("\n");
-        parts.push(`**Code:**
-\`\`\`
-${context}
-\`\`\``);
-      }
-    }
-  } else {
-    parts.push(`**Error:** ${error instanceof Error ? error.message : "Compilation failed"}`);
-  }
-  parts.push("\n**How to fix:** Review the error above, fix the code, then call compile_component again.");
-  return parts.join("\n");
-}
-var LABELED_COMPONENTS = /* @__PURE__ */ new Set(["Input", "TextArea", "Select"]);
-function checkReactRules(code) {
-  const sf = ts3.createSourceFile("component.tsx", code, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
-  const issues = [];
-  function visit(node) {
-    if (ts3.isJsxSelfClosingElement(node) || ts3.isJsxOpeningElement(node)) {
-      const tagName = node.tagName.getText(sf);
-      if (LABELED_COMPONENTS.has(tagName)) {
-        const propNames = /* @__PURE__ */ new Set();
-        let hasSpread = false;
-        for (const attr of node.attributes.properties) {
-          if (ts3.isJsxAttribute(attr)) {
-            propNames.add(attr.name.getText(sf));
-          } else if (ts3.isJsxSpreadAttribute(attr)) {
-            hasSpread = true;
-          }
-        }
-        if (!hasSpread && !propNames.has("label") && !propNames.has("aria-label")) {
-          const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
-          issues.push({
-            check: "accessibility",
-            line,
-            message: `${tagName} missing label prop`,
-            fix: `Add label="..." prop directly on the ${tagName} component. The label prop is built into the primitive.`
-          });
-        }
-      }
-    }
-    ts3.forEachChild(node, visit);
-  }
-  visit(sf);
-  return issues;
-}
-async function runSelfChecks(code, contract) {
-  const issues = [];
-  const lines = code.split("\n");
-  const allowedGadgetPackages = new Set(
-    Object.keys(contract?.clientCapabilities?.gadgets ?? {})
-  );
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const lineNum = i + 1;
-    const hexMatch = line.match(/#[0-9a-fA-F]{3,8}\b/);
-    if (hexMatch && !line.includes("var(--ggui-") && !line.includes("// fallback")) {
-      issues.push({
-        check: "hex-color",
-        line: lineNum,
-        message: `Hardcoded color "${hexMatch[0]}" \u2014 must use design tokens`,
-        fix: `Replace "${hexMatch[0]}" with a primitive variant OR a bare token reference such as var(--ggui-color-primary-500) \u2014 never a literal fallback inside var()`
-      });
-    }
-    const colorFnMatch = line.match(/\b(rgba?|hsla?)\s*\(/);
-    if (colorFnMatch && !line.includes("var(--ggui-") && !line.includes("// fallback") && !line.includes("$value")) {
-      issues.push({
-        check: "hardcoded-color-fn",
-        line: lineNum,
-        message: `Hardcoded ${colorFnMatch[1]}() \u2014 use design tokens instead`,
-        fix: `Replace with the layering roles: var(--ggui-color-container), var(--ggui-color-onContainer), var(--ggui-color-outline), etc.`
-      });
-    }
-    if (/--ggui-color-neutral-50[^0-9]/.test(line) && /background/i.test(line)) {
-      issues.push({
-        check: "prefer-semantic",
-        line: lineNum,
-        message: `neutral-50 for background \u2014 prefer semantic token for dark-theme compatibility`,
-        fix: `Replace with var(--ggui-color-container) or var(--ggui-color-sunken)`
-      });
-    }
-    if (/--ggui-color-neutral-900[^0-9]/.test(line) && /color/i.test(line) && !/background/i.test(line)) {
-      issues.push({
-        check: "prefer-semantic",
-        line: lineNum,
-        message: `neutral-900 for text color \u2014 prefer semantic token for dark-theme compatibility`,
-        fix: `Replace with var(--ggui-color-onContainer) or var(--ggui-color-onSunken)`
-      });
-    }
-    const pxMatch = line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/);
-    if (pxMatch && !line.includes("var(--ggui-")) {
-      issues.push({
-        check: "raw-pixels",
-        line: lineNum,
-        message: `Raw pixel value in spacing \u2014 must use design tokens`,
-        fix: `Replace with a bare var(--ggui-spacing-*) token \u2014 no literal fallback \u2014 or the scale name on the primitive prop (gap="md", padding="lg")`
-      });
-    }
-    if (/\beval\s*\(/.test(line)) {
-      issues.push({ check: "security", line: lineNum, message: "eval() is forbidden", fix: "Remove eval() call entirely" });
-    }
-    if (/\bfetch\s*\(/.test(line)) {
-      issues.push({ check: "security", line: lineNum, message: "fetch() is forbidden \u2014 use props for data", fix: "Remove fetch() and pass data via props" });
-    }
-    const importMatch = line.match(/import\s+.*from\s+['"]([^'"]+)['"]/);
-    if (importMatch) {
-      const pkg = importMatch[1];
-      if (!isAllowedImport(pkg, allowedGadgetPackages)) {
-        issues.push({
-          check: "import",
-          line: lineNum,
-          message: `Import from "${pkg}" is not allowed`,
-          fix: `Only import from: ${describeAllowedImports()}`
-        });
-      }
-    }
-  }
-  try {
-    const jsxIssues = checkReactRules(code);
-    issues.push(...jsxIssues);
-  } catch {
-  }
-  if (!code.includes("interface Props") && !code.includes("type Props")) {
-    issues.push({
-      check: "props-interface",
-      line: 1,
-      message: "No Props interface found \u2014 data is likely hardcoded",
-      fix: "Add interface Props { ... } with typed fields and default values in the function signature"
-    });
-  }
-  if (!code.includes("export default function")) {
-    issues.push({
-      check: "export",
-      line: 1,
-      message: "Missing default export function",
-      fix: "Add export default function GeneratedComponent(props: Props) { ... }"
-    });
-  }
-  const typeWarnings = [];
-  const [typeResult, reactResult] = await Promise.all([
-    typecheck(code).catch((err) => {
-      console.warn("[runSelfChecks] TypeChecker failed:", err instanceof Error ? err.message : String(err));
-      return null;
-    }),
-    lintReactHooks(code).catch((err) => {
-      console.warn("[runSelfChecks] React linter failed:", err instanceof Error ? err.message : String(err));
-      return [];
-    })
-  ]);
-  if (typeResult) {
-    for (const error of typeResult.errors) {
-      issues.push({
-        check: `ts${error.code}`,
-        line: error.line,
-        message: error.message,
-        fix: error.fix
-      });
-    }
-    for (const warning of typeResult.warnings) {
-      typeWarnings.push({
-        check: `ts${warning.code}`,
-        line: warning.line,
-        message: warning.message,
-        fix: warning.fix
-      });
-    }
-  }
-  const hasStateSetter = /\b(set[A-Z]\w*|dispatch)\s*\(/.test(code);
-  const isSetterLoopRisk = (diag) => {
-    if (diag.rule !== "react-hooks/exhaustive-deps") return false;
-    if (!hasStateSetter) return false;
-    return /missing dependenc|changes on every render|object makes the dependencies|array makes the dependencies/i.test(
-      diag.message
-    );
-  };
-  for (const diag of reactResult) {
-    const blocking = diag.severity === "error" || isSetterLoopRisk(diag);
-    if (blocking) {
-      issues.push({
-        check: diag.rule,
-        line: diag.line,
-        message: isSetterLoopRisk(diag) ? `${diag.message} (promoted to error: effect mutates state \u2014 missing/unstable deps cause infinite render loops)` : diag.message,
-        fix: diag.fix
-      });
-    } else {
-      typeWarnings.push({
-        check: diag.rule,
-        line: diag.line,
-        message: diag.message,
-        fix: diag.fix
-      });
-    }
-  }
-  const lineMap = /* @__PURE__ */ new Map();
-  for (const i of issues) {
-    const list = lineMap.get(i.line) ?? [];
-    list.push(i);
-    lineMap.set(i.line, list);
-  }
-  const deduped = [];
-  for (const [, group] of lineMap) {
-    if (group.length === 1) {
-      deduped.push(group[0]);
-      continue;
-    }
-    const primary = group.find((i) => !i.check.startsWith("ts")) ?? group[0];
-    const others = group.filter((i) => i !== primary);
-    if (others.length > 0) {
-      const alsoTags = others.map((o) => o.check).join(", ");
-      deduped.push({
-        ...primary,
-        message: `${primary.message} [also flagged by: ${alsoTags}]`
-      });
-    } else {
-      deduped.push(primary);
-    }
-  }
-  return { issues: deduped, typeWarnings };
-}
-
-// src/adapters/index.ts
-init_tool_bridge();
-init_raw();
-init_sdk();
-init_raw2();
-init_sdk2();
-init_raw3();
-init_sdk3();
-
-export { ClaudeRawAdapter, ClaudeSdkAdapter, GeneratorAdapter, GoogleRawAdapter, GoogleSdkAdapter, OpenAiRawAdapter, OpenAiSdkAdapter, PROVIDER_DISPLAY_NAMES, createGeneratorTools, getAdapter, listAdapters, zodToJsonSchema };
+export { getAdapter, listAdapters } from '../chunk-MKMDQFZ7.js';
+export { OpenAiSdkAdapter } from '../chunk-PJFH7QWA.js';
+export { GoogleRawAdapter } from '../chunk-6VDRWAP6.js';
+export { GoogleSdkAdapter } from '../chunk-PBOYHGSD.js';
+export { ClaudeRawAdapter } from '../chunk-3ZSSDV3L.js';
+export { ClaudeSdkAdapter } from '../chunk-XGLO5LGG.js';
+export { OpenAiRawAdapter } from '../chunk-AOU33EFS.js';
+import '../chunk-YJZTUY7B.js';
+export { GeneratorAdapter } from '../chunk-XRBCRKA2.js';
+export { createGeneratorTools } from '../chunk-3HSGA6NI.js';
+export { PROVIDER_DISPLAY_NAMES } from '../chunk-A375NNWN.js';
+import '../chunk-56NJFD55.js';
+import '../chunk-HD6ABIK7.js';
+import '../chunk-FWJIMKFZ.js';
+import '../chunk-33B3BAWS.js';
+import '../chunk-GAJI7Y3P.js';
+import '../chunk-QLXXPGTV.js';
+import '../chunk-JDH5EGNZ.js';
+import '../chunk-OVLH5ICV.js';
+export { zodToJsonSchema } from '../chunk-7QE3AHLE.js';
+import '../chunk-FLRNMZV2.js';
+import '../chunk-Z3CXME3K.js';
+import '../chunk-PUH4CXGZ.js';
+import '../chunk-3T2HMTON.js';
+import '../chunk-G3PMV62Z.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map