@ggui-ai/ui-gen 0.23.0 → 0.24.0

package/dist/adapters/generation-dispatch.js

@@ -1,4 +1,4 @@
-import { classifyUi, MODEL_REGISTRY, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, listContractGadgets, HOOK_NAME_RE, STDLIB_GADGETS_PACKAGE, resolveAppGadgets, APP_GENERATION_PROFILE_BOUNDS, anthropicRejectsForcedToolChoice, normalizeAnthropicModelId, anthropicRejectsSamplingParams, isRecord } from '@ggui-ai/protocol';
+import { listContractGadgets, HOOK_NAME_RE, classifyUi, MODEL_REGISTRY, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, STDLIB_GADGETS_PACKAGE, resolveAppGadgets, APP_GENERATION_PROFILE_BOUNDS, anthropicRejectsForcedToolChoice, normalizeAnthropicModelId, anthropicRejectsSamplingParams, isRecord } from '@ggui-ai/protocol';
 import Anthropic from '@anthropic-ai/sdk';
 import { z } from 'zod';
 import { getCssTokens, fillFitRule, FORBIDDEN_IMPORT_SPECIFIERS } from '@ggui-ai/design/rendering';
@@ -2812,6 +2812,14 @@ function resolveRunPolicyForProfile(profile, harness, runtimeCtx) {
       }
     };
   }
+  if (profile === "ctx-slice-primitives-v2") {
+    return {
+      context: {
+        ...harness.policy.context,
+        primitiveDocSlice: "axis-keyed+contract"
+      }
+    };
+  }
   return resolveRunPolicy2(harness, runtimeCtx);
 }
 var init_policy2 = __esm({
@@ -3360,9 +3368,25 @@ var init_validation = __esm({
 // src/harness/check/runtime-render/render-check-host.ts
 var render_check_host_exports = {};
 __export(render_check_host_exports, {
+  DEFAULT_RENDER_CHECK_HOST_BOUNDS: () => DEFAULT_RENDER_CHECK_HOST_BOUNDS,
   mapSandboxResultToCheckResult: () => mapSandboxResultToCheckResult,
+  resolveRenderCheckHostBounds: () => resolveRenderCheckHostBounds,
+  resolveWorkerSpawn: () => resolveWorkerSpawn,
   runRenderCheckViaWorker: () => runRenderCheckViaWorker
 });
+function resolveRenderCheckHostBounds(bounds = {}) {
+  const timeoutMs = bounds.timeoutMs ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.timeoutMs;
+  const heapMb = bounds.heapMb ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.heapMb;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 2) {
+    throw new RangeError(`render-check: timeoutMs must be an integer \u2265 2, got ${timeoutMs}`);
+  }
+  if (!Number.isInteger(heapMb) || heapMb < 1) {
+    throw new RangeError(`render-check: heapMb must be a positive integer, got ${heapMb}`);
+  }
+  const requestedGrace = bounds.gracePeriodMs ?? DEFAULT_RENDER_CHECK_HOST_BOUNDS.gracePeriodMs;
+  const gracePeriodMs = Math.max(1, Math.min(requestedGrace, Math.floor(timeoutMs / 2)));
+  return { timeoutMs, heapMb, gracePeriodMs };
+}
 function resolveWorkerSpawn() {
   const jsCandidates = [
     // Sibling — when import.meta.url is already .../harness/check/runtime-render/.
@@ -3411,12 +3435,12 @@ function unverified(reason, t0) {
     stats: { actionsChecked: 0, streamsChecked: 0, renderMs: Date.now() - t0 }
   };
 }
-function mapSandboxResultToCheckResult(result, t0) {
+function mapSandboxResultToCheckResult(result, t0, boundMs = DEFAULT_RENDER_CHECK_HOST_BOUNDS.timeoutMs) {
   if (result.outcome === "timeout") {
     return {
       ok: false,
       issues: [],
-      incomplete: { kind: "timeout", elapsedMs: result.durationMs, boundMs: CHECK_TIMEOUT_MS },
+      incomplete: { kind: "timeout", elapsedMs: result.durationMs, boundMs },
       stats: { actionsChecked: 0, streamsChecked: 0, renderMs: Date.now() - t0 }
     };
   }
@@ -3461,8 +3485,9 @@ function mapSandboxResultToCheckResult(result, t0) {
     );
   }
 }
-async function runRenderCheckViaWorker(input) {
+async function runRenderCheckViaWorker(input, options = {}) {
   const t0 = Date.now();
+  const bounds = resolveRenderCheckHostBounds(options.bounds);
   let spawn;
   try {
     spawn = resolveWorkerSpawn();
@@ -3473,9 +3498,10 @@ async function runRenderCheckViaWorker(input) {
   const result = await runSandboxed({
     command: spawn.command,
     args: spawn.args,
-    timeoutMs: CHECK_TIMEOUT_MS,
+    timeoutMs: bounds.timeoutMs,
+    gracePeriodMs: bounds.gracePeriodMs,
     maxStdoutBytes: CHECK_STDOUT_CAP,
-    nodeHeapMb: CHECK_NODE_HEAP_MB,
+    nodeHeapMb: bounds.heapMb,
     stdin: JSON.stringify(input),
     // NODE_ENV steers React's production vs development build — keep
     // parity with the caller; everything else stays on the sandbox's
@@ -3487,15 +3513,18 @@ async function runRenderCheckViaWorker(input) {
     end: loadavg()[0] ?? 0,
     cores: availableParallelism()
   };
-  const mapped = mapSandboxResultToCheckResult(result, t0);
+  const mapped = mapSandboxResultToCheckResult(result, t0, bounds.timeoutMs);
   return { ...mapped, stats: { ...mapped.stats, hostLoad } };
 }
-var CHECK_TIMEOUT_MS, CHECK_STDOUT_CAP, CHECK_NODE_HEAP_MB, WORKER_BASENAME;
+var DEFAULT_RENDER_CHECK_HOST_BOUNDS, CHECK_STDOUT_CAP, WORKER_BASENAME;
 var init_render_check_host = __esm({
   "src/harness/check/runtime-render/render-check-host.ts"() {
-    CHECK_TIMEOUT_MS = 3e4;
+    DEFAULT_RENDER_CHECK_HOST_BOUNDS = {
+      timeoutMs: 3e4,
+      heapMb: 512,
+      gracePeriodMs: 2e3
+    };
     CHECK_STDOUT_CAP = 2 * 1024 * 1024;
-    CHECK_NODE_HEAP_MB = 512;
     WORKER_BASENAME = "render-check-worker";
   }
 });
@@ -4429,6 +4458,46 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
   visit(sf);
   return issues;
 }
+function suggestManifestTokens(name) {
+  const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
+  if (successor !== void 0) return [successor];
+  const segments = name.split("-").filter((segment) => segment.length > 0);
+  const own = name.endsWith("-") ? segments.length : segments.length - 1;
+  for (let n = own; n >= 2; n--) {
+    const prefix = `--${segments.slice(0, n).join("-")}-`;
+    const family = consumedTokenManifest.filter((token) => token.startsWith(prefix));
+    if (family.length > 0) return wordHitsFirst(name, rolesFirst(family));
+  }
+  const words = new Set(
+    segments.slice(1).filter((segment) => segment.length >= 4).map((segment) => segment.toLowerCase())
+  );
+  return rolesFirst(
+    consumedTokenManifest.filter(
+      (token) => token.split("-").some((segment) => words.has(segment.toLowerCase()))
+    )
+  );
+}
+function wordHitsFirst(name, family) {
+  const word = name.slice(name.lastIndexOf("-") + 1).toLowerCase();
+  if (word.length < 4) return family;
+  const hit = (token) => token.slice(token.lastIndexOf("-") + 1).toLowerCase().includes(word);
+  return [...family.filter(hit), ...family.filter((token) => !hit(token))];
+}
+function rolesFirst(tokens) {
+  const isRole = (token) => !/^\d+$/.test(token.slice(token.lastIndexOf("-") + 1));
+  return [...tokens.filter(isRole), ...tokens.filter((token) => !isRole(token))];
+}
+function offManifestHint(name) {
+  const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
+  if (successor !== void 0) {
+    return `"${name}" was retired (ggui#987); the current name is var(${successor}). `;
+  }
+  const near = suggestManifestTokens(name);
+  if (near.length === 0) return "";
+  const shown = near.slice(0, 8).map((token) => `var(${token})`).join(", ");
+  const more = near.length > 8 ? ` (and ${near.length - 8} more in that family)` : "";
+  return `Nearest names in the manifest: ${shown}${more}. `;
+}
 function isGadgetExportImported(source, pkg, exportName) {
   const esc = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const re = new RegExp(
@@ -4651,7 +4720,7 @@ ${errorDetail}`,
         subcategory: "off-manifest-token",
         severity: "critical",
         description: `Token "${name}" is not in the design system's token manifest \u2014 no theme defines it, so it renders unset.`,
-        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), \u2026; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
+        fix: `${offManifestHint(name)}Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), \u2026; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
         line: lineNum
       });
     }
@@ -5168,7 +5237,7 @@ async function runTier0(sourceCode, contract, designMode = DEFAULT_DESIGN_MODE)
   }
   return { issues, pass };
 }
-var MANIFEST_TOKENS, TOKEN_REF_RE, HOOK_NAME_FOR, CONTRACT_FIELD_FOR;
+var MANIFEST_TOKENS, RETIRED_TOKEN_SUCCESSORS, TOKEN_REF_RE, HOOK_NAME_FOR, CONTRACT_FIELD_FOR;
 var init_run_tier0 = __esm({
   "src/check/run-tier0.ts"() {
     init_design_mode();
@@ -5179,6 +5248,12 @@ var init_run_tier0 = __esm({
     init_extract_wire_calls();
     init_types_public();
     MANIFEST_TOKENS = new Set(consumedTokenManifest);
+    RETIRED_TOKEN_SUCCESSORS = /* @__PURE__ */ new Map([
+      ["--ggui-color-surface", "--ggui-color-container"],
+      ["--ggui-color-onSurface", "--ggui-color-onContainer"],
+      ["--ggui-color-surfaceVariant", "--ggui-color-sunken"],
+      ["--ggui-color-onSurfaceVariant", "--ggui-color-onSunken"]
+    ]);
     TOKEN_REF_RE = /var\(\s*(--ggui-[a-zA-Z0-9-]+)/g;
     HOOK_NAME_FOR = {
       action: "useAction",
@@ -7020,11 +7095,25 @@ Respond with ONLY a JSON object (no markdown, no explanation):
   }
 });
 
+// src/tools/get-primitives-ts.ts
+var get_primitives_ts_exports = {};
+__export(get_primitives_ts_exports, {
+  PRIMITIVES_DOCUMENTATION_TS: () => PRIMITIVES_DOCUMENTATION_TS
+});
+var PRIMITIVES_DOCUMENTATION_TS;
+var init_get_primitives_ts = __esm({
+  "src/tools/get-primitives-ts.ts"() {
+    PRIMITIVES_DOCUMENTATION_TS = "// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// GGUI DESIGN SYSTEM \u2014 COMPONENT REFERENCE\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// CRITICAL \u2014 Props take enum STRING LITERALS, not CSS variables:\n//   <Text size=\"sm\" weight=\"bold\" />                         \u2713\n//   <Text size=\"var(--ggui-font-size-sm)\" />                 \u2717  (breaks)\n//   The enum strings map to CSS variables internally.\n//\n// CRITICAL \u2014 onChange receives the VALUE directly, not an event:\n//   <Input value={x} onChange={setX} />                      \u2713\n//   <Input onChange={(e) => setX(e.target.value)} />         \u2717\n//\n// Imports allowed: 'react', '@ggui-ai/design', '@ggui-ai/wire'.\n//   The WHOLE design system \u2014 primitives, components, compositions,\n//   traits \u2014 is one import: import { Card, Grid, Modal, Clickable }\n//   from '@ggui-ai/design'. No subpaths. No external libs, no\n//   fetch(), no eval().\n//\n// All components accept 'style' + 'className' (omitted below).\n// Structural primitives (Box, Stack, Row, Card) also take a trait via\n// 'as': 'as={Clickable}' adds onClick + keyboard a11y; likewise\n// 'as={Hoverable}' and 'as={Pressable}'. Semantic components\n// (Button/Link/Input) are already interactive and take no 'as'.\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Primitives   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Container \u2014 Width-constrained wrapper that centers content horizontally\ninterface ContainerProps {\n  children?: ReactNode;\n  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full' | string;  // default 'lg'; Maximum width constraint\n  center?: boolean;  // default true; Whether to center the container horizontally via `margin: 0 auto`\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all sides\n}\n\n// Example:\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// Card \u2014 Container with background, shadow, and optional border\ninterface CardProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'lg'; Padding applied to all sides\n  shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl';  // default 'sm'; Shadow elevation level\n  border?: boolean;  // default true; Whether to render a 1px border using `var(--ggui-color-outlineVariant)`\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'lg'; Corner radius\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'hero' | 'transparent';  // default 'default'; Semantic surface slot\n  bleed?: boolean;  // default false; Span the expanded frame's inset edge to edge (ggui#1083)\n}\n\n// Example:\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// Stack \u2014 Flexbox layout primitive for arranging children along a single axis\ninterface StackProps {\n  children?: ReactNode;\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Main axis direction\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\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// Grid \u2014 2-D layout primitive\ninterface GridProps {\n  children?: ReactNode;\n  columns?: number | ResponsiveColumns;  // default 2; Column count\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'md'; Gap between cells\n  minColumnWidth?: number | string;  // default undefined (use `columns`); When set, the grid becomes responsive \u2014 it fits as many equal\n}\n\n// Example:\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n\n// Skeleton \u2014 a pulsing placeholder for content that has not loaded\ninterface SkeletonProps {\n  variant?: 'rect' | 'text' | 'circle';  // default 'rect'; Shape preset\n  width?: number | string;\n  height?: number | string;\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'sm'; Corner radius\n}\n\n// Example:\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n\n// Box \u2014 Generic container with padding, margin, background, and border-radius\ninterface BoxProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all four sides\n  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Horizontal (left + right) padding\n  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Vertical (top + bottom) padding\n  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no margin); Margin applied to all four sides\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'hero' | 'transparent';  // default undefined (transparent); Semantic surface slot\n  bleed?: boolean;  // default false; Span the expanded frame's inset edge to edge (ggui#1083)\n  assetColor?: string;  // default undefined; Asset color escape \u2014 the typed valve for legitimate non-theme\n  assetSemantic?: string;  // default undefined; Human-readable semantic label that documents why\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default undefined (no rounding); Corner radius\n}\n\n// Example:\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// Divider \u2014 A 1px line to visually separate content sections\ninterface DividerProps {\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Line direction\n  margin?: number | string;  // default 16; Spacing around the divider\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-outlineVariant)`); Semantic color slot\n}\n\n// Example:\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// Spacer \u2014 Invisible spacing element, either fixed-size or flexible\ninterface SpacerProps {\n  size?: number | 'flex';  // default 16; Spacing amount\n}\n\n// Example:\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// Text \u2014 Versatile typography primitive for body copy, captions, and labels\ninterface TextProps {\n  children?: ReactNode;\n  size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';  // default 'base'; Font size\n  weight?: 'normal' | 'medium' | 'semibold' | 'bold';  // default 'normal'; Font weight\n  caps?: boolean;  // default false; When true, uppercases the text and adds 0\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n  truncate?: boolean;  // default false; When true, clips overflowing text with an ellipsis\n  is?: 'p' | 'span' | 'div' | 'label';  // default 'p'; HTML element to render\n  id?: string;  // `id` for the rendered element \u2014 anchor an in-page link, or pair\n  htmlFor?: string;  // Associates an `is=\"label\"` element with a form control by the\n}\n\n// Example:\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// Heading \u2014 Semantic heading element (h1-h6) with preset typography styles\ninterface HeadingProps {\n  children?: ReactNode;\n  level?: 1 | 2 | 3 | 4 | 5 | 6;  // default 2; Semantic heading level\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n}\n\n// Example:\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// Button \u2014 A clickable button primitive with multiple visual variants and sizes\ninterface ButtonProps {\n  children?: ReactNode;\n  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';  // default 'primary'; Visual style\n  size?: 'xs' | 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and minimum height:\n  fullWidth?: boolean;  // default false; When true, sets `width: 100%` so the button fills its container\n  loading?: boolean;  // default false; When true, replaces children with a 16px `Spinner` (color: `currentColor`)\n  leftIcon?: ReactNode;  // ReactNode rendered before children, inside the flex layout with `var(--ggui-s...\n  rightIcon?: ReactNode;  // ReactNode rendered after children, inside the flex layout with `var(--ggui-sp...\n  onPress?: () => void;  // Alias for `onClick` for cross-platform compatibility (React Native convention)\n}\n\n// Example:\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n\n// Input \u2014 A single-line text input with label, validation, and helper text\ninterface InputProps {\n  label?: string;  // Label rendered above the input\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\n  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local';  // default 'text'; HTML input type\n  error?: string;  // Error message displayed below the input in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the input in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n\n// TextArea \u2014 A multiline text input with label, validation, character count, a...\ninterface TextAreaProps {\n  label?: string;  // Label rendered above the textarea\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\n  rows?: number;  // default 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)`\n  helperText?: string;  // Helper text displayed below the textarea in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  maxLength?: number;  // Maximum character length (native `maxLength` attribute)\n  showCount?: boolean;  // default false; When true AND `maxLength` is set, displays a `{current}/{max}` character\n  autoResize?: boolean;  // default false; When true, sets CSS `resize: none` on the textarea\n}\n\n// Example:\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n\n// Select \u2014 A native dropdown selection primitive with label and validation\ninterface SelectProps {\n  label?: string;  // Label rendered above the select\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: SelectOption[];  // Array of selectable options\n  placeholder?: string;  // Placeholder text rendered as a disabled `<option value=\"\">` at the top of the\n  error?: string;  // Error message displayed below the select in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the select in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\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// Checkbox \u2014 A custom-styled checkbox with label and description\ninterface CheckboxProps {\n  label?: string;  // Primary label text rendered beside the checkbox box\n  checked?: boolean;  // Controlled checked state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  description?: string;  // Secondary description text rendered below the label in smaller, muted type\n  indeterminate?: boolean;  // default false; When true, displays a horizontal dash instead of a checkmark\n}\n\n// Example:\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// Toggle \u2014 A switch/toggle input rendered as a pill-shaped track with a slidin...\ninterface ToggleProps {\n  label?: string;  // Label text rendered to the right of the toggle track\n  checked?: boolean;  // Controlled checked (on/off) state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track and knob dimensions:\n}\n\n// Example:\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n\n// RadioGroup \u2014 A group of mutually exclusive radio options with optional label...\ninterface RadioGroupProps {\n  label?: string;  // Group label rendered above the options\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: RadioOption[];  // Array of radio options\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Layout direction for the options container:\n  disabled?: boolean;  // default false; When true, disables ALL options (individual `RadioOption\n  error?: string;  // Error message displayed below all options in `var(--ggui-color-error-500)`\n}\n\n// Example:\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// Slider \u2014 A range input with a custom-styled track, fill, and thumb\ninterface SliderProps {\n  label?: string;  // Label rendered above the slider track (left-aligned)\n  value?: number;  // default 0; Controlled numeric value\n  onChange?: (value: number) => void;  // Change handler\n  min?: number;  // default 0; Minimum allowed value\n  max?: number;  // default 100; Maximum allowed value\n  step?: number;  // default 1; Step increment for the slider\n  disabled?: boolean;  // default false; When true, sets `cursor: not-allowed` on the native input\n  showValue?: boolean;  // default false; When true, displays the current numeric value right-aligned in the header row\n}\n\n// Example:\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n\n// Badge \u2014 Inline label for status indicators, counts, or categories\ninterface BadgeProps {\n  children?: ReactNode;\n  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'tertiary';  // default 'default'; Visual style\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n  pill?: boolean;  // default true; When true, uses fully rounded corners (`border-radius: 9999px`)\n}\n\n// Example:\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n\n// Spinner \u2014 Animated SVG loading indicator\ninterface SpinnerProps {\n  size?: number;  // default 24; Width and height of the SVG element in pixels\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the animated foreground arc\n}\n\n// Example:\n<Spinner size={32} tone=\"success\" />\n\n// Avatar \u2014 User or entity representation with image or auto-generated initials\ninterface AvatarProps {\n  src?: string;  // Image URL\n  name?: string;  // Name used for two purposes:\n  size?: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl';  // default 'md'; Avatar dimensions\n  shape?: 'circle' | 'square';  // default 'circle'; Container shape\n}\n\n// Example:\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n\n// Alert \u2014 Contextual message box for important information with icon and optio...\ninterface AlertProps {\n  children?: ReactNode;\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the body in semibold (`var(--ggui-font-weight-s...\n  closable?: boolean;  // default false; When true, renders a close button (X icon) in the top-right area\n  onClose?: () => void;  // Callback fired when the close button is clicked\n  icon?: ReactNode;  // Custom icon ReactNode to replace the default variant icon\n}\n\n// Example:\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n\n// Progress \u2014 Horizontal progress bar with determinate and indeterminate modes\ninterface ProgressProps {\n  value: number;  // Current progress value\n  max?: number;  // default 100; Maximum value representing 100% progress\n  variant?: 'default' | 'success' | 'warning' | 'error';  // default 'default'; Fill bar color\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track height in pixels:\n  label?: string;  // Accessible name describing what this bar measures, e\n  showLabel?: boolean;  // default false; When true, displays a header row above the track with the `label` text\n  indeterminate?: boolean;  // default false; When true, ignores `value` for visual width and plays a looping animation\n}\n\n// Example:\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n\n// Image \u2014 An `<img>` element with built-in error handling and fallback support\ninterface ImageProps {\n  src: string;  // Image source URL\n  alt: string;  // Alt text for the image\n  width?: number | string;  // default '100%' (applied at render time, not on the type); Image width\n  height?: number | string;  // default 'auto' (applied at render time, not on the type); Image height\n  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';  // default '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\n  fallback?: ReactNode;  // Custom ReactNode rendered when the image fails to load\n}\n\n// Example:\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n\n// Icon \u2014 a curated Lucide subset (~200 names) + emoji passthrough\ninterface IconProps {\n  name?: string;  // Lucide icon name from the curated subset (kebab-case, camelCase, or\n  size?: number;  // default 24; Icon dimensions in pixels (applied to both width and height of the wrapper\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (icon uses `currentColor`); Semantic color slot\n  children?: ReactNode;  // Custom SVG children\n  'aria-label'?: string;  // Accessible name for a standalone, meaning-bearing icon\n}\n\n// Example:\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n\n// Link \u2014 Styled anchor element with external link support\ninterface LinkProps {\n  children?: ReactNode;\n  href: string;  // Destination URL\n  external?: boolean;  // default false; When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener norefer...\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the link text\n  underline?: 'always' | 'hover' | 'none';  // default 'hover'; Underline behavior:\n}\n\n// Example:\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n\n// Tooltip \u2014 Hoverable information popup positioned relative to a trigger element\ninterface TooltipProps {\n  children: ReactNode;  // Trigger element\n  content: ReactNode;  // Tooltip content\n  position?: 'top' | 'bottom' | 'left' | 'right';  // default 'top'; Tooltip placement relative to the trigger element:\n  delay?: number;  // default 200; Delay in milliseconds before the tooltip becomes visible after hover/focus\n}\n\n// Example:\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n\n// Table \u2014 Data table with sortable columns, striped rows, and hover highlights\ninterface TableProps {\n  columns: TableColumn<T>[];  // Array of column definitions controlling header labels, data keys, and rendering\n  data: T[];  // Array of row data objects\n  sortKey?: string;  // The `key` of the currently sorted column\n  sortDirection?: SortDirection;  // default 'asc'; Current sort direction for the column identified by `sortKey`\n  onSort?: (key: string, direction: SortDirection) => void;  // Sort change handler\n  striped?: boolean;  // default false; When true, alternating rows (odd index) get a\n  hoverable?: boolean;  // default true; When true, rows highlight with `var(--ggui-color-container)`\n  compact?: boolean;  // default false; When true, reduces cell padding:\n  bordered?: boolean;  // default false; When true, adds a 1px border around the table wrapper and between cells\n  caption?: string;  // Accessible table caption\n}\n\n// Example:\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// Tabs \u2014 Accessible tab navigation with panels and keyboard support\ninterface TabsProps {\n  items: TabItem[];  // Array of tab definitions\n  activeKey?: string;  // Controlled active tab key\n  onChange?: (key: string) => void;  // Tab change handler\n  variant?: 'line' | 'pills' | 'enclosed';  // default 'line'; Visual style of the tab bar:\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls tab button padding and font size:\n  fullWidth?: boolean;  // default false; When true, tab buttons expand equally to fill the container width\n}\n\n// Example:\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// Toast \u2014 Notification banner with auto-dismiss and slide-in animation\ninterface ToastProps {\n  message: ReactNode;  // Message body content\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the message in semibold\n  duration?: number;  // default 5000; Auto-dismiss delay in milliseconds\n  onClose?: () => void;  // Callback fired on auto-dismiss timeout or when the close button is clicked\n  visible?: boolean;  // default true; Controls rendering\n  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';  // Intended screen position\n}\n\n// Example:\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n\n// Accordion \u2014 Collapsible content sections with chevron rotation animation\ninterface AccordionProps {\n  items: AccordionItem[];  // Array of collapsible section definitions\n  expandedKeys?: string[];  // Controlled expanded state\n  onChange?: (expandedKeys: string[]) => void;  // Expand/collapse handler\n  multiple?: boolean;  // default false; When true, multiple items can be open simultaneously\n  variant?: 'default' | 'bordered' | 'separated';  // default 'default'; Visual style controlling borders and spacing:\n}\n\n// Example:\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// Row \u2014 Convenience alias for a horizontal Stack\ninterface RowProps {\n  children?: ReactNode;\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Row gap=\"md\" align=\"center\" justify=\"between\">\n  <Text size=\"sm\" weight=\"medium\">Total</Text>\n  <Text weight=\"bold\">$42.00</Text>\n</Row>\n\n// Support types:\n// ResponsiveColumns \u2014 Explicit column count per viewport breakpoint, mobile-first\ninterface ResponsiveColumns {\n  base?: number;  // default 1; 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\n// SelectOption \u2014 An individual option within a `Select` dropdown\ninterface SelectOption {\n  value: string;  // The value submitted when this option is selected\n  label: string;  // The display text shown in the dropdown\n  disabled?: boolean;  // default false; When true, the option is visible but cannot be selected (grayed out by the br...\n}\n\n// RadioOption \u2014 An individual option within a `RadioGroup`\ninterface RadioOption {\n  value: string;  // The value emitted via `RadioGroupProps\n  label: string;  // Display text for this option\n  description?: string;  // Optional secondary description rendered below the label in smaller, muted type\n  disabled?: boolean;  // default false; When true, this individual option is grayed out (`opacity: 0\n}\n\n// TableColumn \u2014 Column definition for the Table component\ninterface TableColumn {\n  key: string;  // Property key in the row data object\n  header: string;  // Column header text\n  width?: number | string;  // Fixed column width\n  align?: 'left' | 'center' | 'right';  // default 'left'; Horizontal text alignment for both the header and data cells\n  sortable?: boolean;  // default false; When true, the header cell becomes clickable and shows sort direction\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n}\n\n// TabItem \u2014 Definition of a single tab within a Tabs component\ninterface TabItem {\n  key: string;  // Unique identifier for this tab\n  label: ReactNode;  // Tab button label\n  content: ReactNode;  // Panel content rendered below the tab bar when this tab is active\n  disabled?: boolean;  // default false; When true, the tab button shows `opacity: 0\n  icon?: ReactNode;  // Optional icon rendered before the label inside the tab button, with\n}\n\n// AccordionItem \u2014 Definition of a single collapsible section within an Accordion\ninterface AccordionItem {\n  key: string;  // Unique identifier for this item\n  title: ReactNode;  // Header label rendered inside the toggle button\n  content: ReactNode;  // Panel content rendered below the header when expanded\n  disabled?: boolean;  // default false; When true, the header button shows `opacity: 0\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Components   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// SearchField \u2014 A text input with a leading search icon and optional submit button\ninterface SearchFieldProps {\n  value?: string;  // Current search value\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly, not\n  onSearch?: (value: string) => void;  // Called when the user presses **Enter** or clicks the search button\n  placeholder?: string;  // default 'Search...'; Placeholder text shown when the input is empty\n  showButton?: boolean;  // default false; When `true`, renders a `Button` primitive to the right of the input\n  buttonText?: string;  // default 'Search'; Label rendered inside the submit button\n  loading?: boolean;  // When `true`, replaces the search icon with a `Spinner`, disables the\n  disabled?: boolean;  // When `true`, the input and button are visually disabled and do not\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls input height and font size\n}\n\n// Example:\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// FormField \u2014 A wrapper that adds a label, optional description, error message,\ninterface FormFieldProps {\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) re...\n  error?: string;  // Error message displayed below `children` in `colors\n  helperText?: string;  // Neutral guidance text displayed below `children` in `colors\n  required?: boolean;  // When `true`, appends a red asterisk (`*`) after the label text\n  description?: string;  // Secondary description rendered between the label and the child control\n}\n\n// Example:\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// MenuItem \u2014 A full-width clickable row for menus, sidebars, and action lists\ninterface MenuItemProps {\n  label: string;  // Primary text content of the menu item\n  icon?: ReactNode;  // Icon or element rendered to the left of the label\n  rightElement?: ReactNode;  // Element rendered to the right of the label (e\n  onClick?: () => void;  // Called when the item is clicked\n  disabled?: boolean;  // When `true`, the item is non-interactive: `colors\n  active?: boolean;  // Marks this item as the current selection\n  danger?: boolean;  // Switches the item to destructive styling: `colors\n}\n\n// Example:\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// Tag \u2014 An inline label for categories, filters, statuses, or selections\ninterface TagProps {\n  children: ReactNode;  // Tag content -- typically a short text string\n  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';  // default 'default'; Semantic color variant applied to background, text, and border\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and internal gap\n  closable?: boolean;  // When `true`, renders a small close (\"x\") button after the content\n  onClose?: () => void;  // Called when the close button is clicked\n  icon?: ReactNode;  // Icon or element rendered before the text content\n}\n\n// Example:\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n\n// Dropdown \u2014 A click-triggered menu anchored to a trigger element\ninterface DropdownProps {\n  trigger: ReactNode;  // The element the user clicks to open the menu\n  options: DropdownOption[];  // Array of selectable options rendered as `MenuItem` rows\n  value?: string;  // The `value` of the currently selected option\n  onChange?: (value: string) => void;  // Called with the `value` string of the selected option (not the full\n  placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';  // default 'bottom-start'; Where to anchor the menu panel relative to the trigger\n  disabled?: boolean;  // When `true`, the trigger shows `cursor: not-allowed` and clicking\n}\n\n// Example:\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// Autocomplete \u2014 A text input with a filterable suggestion dropdown, keyboard navigation,\ninterface AutocompleteProps {\n  value?: string;  // default ''; Current text in the input field\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly,\n  onSelect?: (option: AutocompleteOption) => void;  // Called when the user selects an option (click or Enter on highlighted\n  options: AutocompleteOption[];  // The full list of available options\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\n  disabled?: boolean;  // When `true`, the inner `Input` is disabled and the dropdown\n  error?: string;  // Error message forwarded to the inner `Input` primitive\n  noResultsText?: string;  // default 'No results found'; Text shown in the dropdown when filtering produces zero matches\n}\n\n// Example:\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// Breadcrumb \u2014 A horizontal navigation trail showing the user's location within a\ninterface BreadcrumbProps {\n  items: BreadcrumbItem[];  // Ordered array of breadcrumb segments from root to current page\n  separator?: ReactNode;  // default '/'; Separator rendered between each pair of items\n  onItemClick?: (item: BreadcrumbItem, index: number) => void;  // Called when a non-last item is clicked\n}\n\n// Example:\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// Pagination \u2014 Page navigation controls with previous/next arrows, numbered page buttons,\ninterface PaginationProps {\n  currentPage: number;  // Current active page\n  totalPages: number;  // Total number of pages\n  onPageChange?: (page: number) => void;  // Called when the user clicks a page number, arrow, or first/last button\n  showFirstLast?: boolean;  // default true; When `true`, renders double-chevron buttons for jumping to the first\n  maxVisible?: number;  // default 5; Maximum number of page buttons visible at once (including the first\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls button dimensions and icon sizes\n  disabled?: boolean;  // When `true`, all page buttons and arrows are visually dimmed\n}\n\n// Example:\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n\n// EmptyState \u2014 placeholder for a region with no data: empty lists,\ninterface EmptyStateProps {\n  icon?: string | ReactNode;  // A Lucide icon name (kebab-case), rendered large and subtle above\n  title: string;  // The headline, e\n  description?: string;  // Optional supporting line below the title\n  action?: ReactNode;  // Optional call-to-action, typically a `<Button>`\n}\n\n// Example:\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// Stat \u2014 a single KPI / metric: a label, a large value, an optional\ninterface StatProps {\n  label: string;  // The metric name, e\n  value: string | number;  // The headline value \u2014 the big number\n  delta?: string;  // Optional change indicator, pre-formatted, e\n  trend?: 'up' | 'down' | 'neutral';  // default 'neutral'; Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error,\n  icon?: string | ReactNode;  // Optional Lucide icon name (kebab-case) or custom node, shown next\n}\n\n// Example:\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n\n// Stepper \u2014 a display-only step indicator for multi-step flows\ninterface StepperProps {\n  steps: string[];  // Ordered step labels, one per step\n  current: number;  // Zero-based index of the active step\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Flow direction\n  onStepClick?: (index: number) => void;  // When provided, each step becomes a real button and clicks receive\n}\n\n// Example:\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// Markdown \u2014 renders markdown-formatted text as styled content:\ninterface MarkdownProps {\n  markdown: string;  // Markdown source text, passed through verbatim\n}\n\n// Example:\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n\n// MarkdownInline \u2014 renders ONE line of inline-level markdown (bold,\ninterface MarkdownInlineProps {\n  markdown: string;  // Inline markdown source -- bold, italic, inline code, and\n}\n\n// Example:\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n\n// Support types:\n// DropdownOption \u2014 A single option inside a `Dropdown`\ninterface DropdownOption {\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\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive\n  danger?: boolean;  // When `true`, the option uses destructive (red) styling via\n}\n\n// AutocompleteOption \u2014 A single option in the `Autocomplete` suggestion list\ninterface AutocompleteOption {\n  value: string;  // Unique identifier for this option\n  label: string;  // Primary display text\n  description?: string;  // Secondary description rendered below the label in `fontSize\n  icon?: ReactNode;  // Icon rendered to the left of the label/description block\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive (`cursor: not-allowed`...\n}\n\n// BreadcrumbItem \u2014 A single segment in a `Breadcrumb` trail\ninterface BreadcrumbItem {\n  label: string;  // Display text for this breadcrumb segment\n  href?: string;  // URL for this segment\n  icon?: ReactNode;  // Icon rendered immediately before the label\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Compositions   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Header \u2014 Props for the `Header` composition\ninterface HeaderProps {\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 l...\n  actions?: ReactNode;  // Right-side action elements (buttons, avatar, etc\n  sticky?: boolean;  // default false; When true, the header becomes `position: sticky` at the top of its scroll con...\n  background?: string;  // default colors.white; Background color of the header\n  bordered?: boolean;  // default true; When true, renders a 1 px bottom border in `colors\n}\n\n// Example:\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// Sidebar \u2014 Props for the `Sidebar` composition\ninterface SidebarProps {\n  items: SidebarItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: SidebarItem) => void;  // Called when any item (including parent items with children) is clicked\n  collapsed?: boolean;  // default false; When true, hides labels and badges; only icons remain visible, centered in th...\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;  // default 256; Width in pixels when expanded\n  collapsedWidth?: number;  // default 64; Width in pixels when collapsed\n}\n\n// Example:\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// CardGrid \u2014 Props for the `CardGrid` composition\ninterface CardGridProps {\n  children: ReactNode;  // Card elements to arrange in the grid\n  columns?: number | { sm?: number; md?: number; lg?: number };  // default 3; Number of columns, or a responsive breakpoint map\n  gap?: number;  // default 16; Gap between grid items in pixels\n}\n\n// Example:\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// CommentThread \u2014 Props for the `CommentThread` composition\ninterface CommentThreadProps {\n  comments: Comment[];  // Array of top-level comments to render\n  currentUser?: { /** Display name for the current user's avatar. */ name: string; /** Avatar image URL for the current user. */ avatar?: string; };  // Current user info\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\n// Example:\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// DataTable \u2014 Props for the `DataTable` composition\ninterface DataTableProps {\n  columns: DataTableColumn<T>[];  // Column definitions that control header, alignment, sorting, and rendering\n  data: T[];  // Row data array\n  rowKey?: string | ((row: T) => string);  // default '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;  // default '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\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\n  selectable?: boolean;  // When true, adds a checkbox column at the start of each row\n  selectedKeys?: string[];  // default []; 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-...\n}\n\n// Example:\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// ChatWindow \u2014 Props for the `ChatWindow` composition\ninterface ChatWindowProps {\n  messages: ChatMessage[];  // Array of chat messages to display in chronological order\n  currentUserId: string;  // ID of the current user\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\n  placeholder?: string;  // default 'Type a message...'; Placeholder text for the message input field\n  header?: ReactNode;  // Optional header content rendered above the message area, separated by a botto...\n}\n\n// Example:\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// NavigationBar \u2014 Props for the `NavigationBar` composition\ninterface NavigationBarProps {\n  items: NavItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: NavItem) => void;  // Called when a non-disabled item is clicked\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Layout direction\n  variant?: 'default' | 'pills' | 'underline';  // default 'default'; Visual style for active/inactive items\n}\n\n// Example:\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// FileUploader \u2014 Props for the `FileUploader` composition\ninterface FileUploaderProps {\n  files?: UploadedFile[];  // default []; 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\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=\"\n  multiple?: boolean;  // default true; When true, allows selecting multiple files at once\n  maxSize?: number;  // Maximum file size in bytes\n  maxFiles?: number;  // Maximum number of files\n  disabled?: boolean;  // When true, the drop zone is visually dimmed (opacity 0\n  dragDrop?: boolean;  // default true; When true, enables drag-and-drop on the drop zone\n}\n\n// Example:\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// NotificationCenter \u2014 Props for the `NotificationCenter` composition\ninterface NotificationCenterProps {\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\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\n  emptyText?: string;  // default '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\n// Example:\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// Modal \u2014 Props for the `Modal` composition\ninterface ModalProps {\n  open: boolean;  // Controls modal visibility\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 (leve...\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, separ...\n  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';  // default 'md'; Controls the width of the modal panel\n  closeOnOverlayClick?: boolean;  // default true; When true, clicking the semi-transparent overlay behind the modal calls `onCl...\n  closeOnEscape?: boolean;  // default true; When true, pressing the Escape key calls `onClose`\n  showCloseButton?: boolean;  // default true; When true, renders a ghost close button (X icon) in the modal header\n}\n\n// Example:\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// CommandPalette \u2014 Props for the `CommandPalette` composition\ninterface CommandPaletteProps {\n  open: boolean;  // Controls palette visibility\n  onClose: () => void;  // Called to close the palette (overlay click, Escape key, or after command sele...\n  commands: Command[];  // Full array of available commands\n  onSelect: (command: Command) => void;  // Called when a non-disabled command is selected (Enter key or click)\n  placeholder?: string;  // default 'Search commands...'; Placeholder text for the search input\n  recentIds?: string[];  // default []; IDs of recently used commands\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the command list\n}\n\n// Example:\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// Footer \u2014 Props for the `Footer` composition\ninterface FooterProps {\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\n  bottomLinks?: FooterLink[];  // Links displayed in the bottom bar after social icons (e\n  background?: string;  // default colors.gray[50]; Background color of the footer\n  bordered?: boolean;  // default true; When true, renders a 1 px top border in `colors\n}\n\n// Example:\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// Hero \u2014 Props for the `Hero` composition\ninterface HeroProps {\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\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 ...\n  align?: 'center' | 'left';  // default 'center'; Text and layout alignment\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls vertical padding and heading/description font sizes\n  background?: string;  // default 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:...\n  overlay?: boolean;  // default false; When true and `backgroundImage` is set, renders a semi-transparent black overlay\n}\n\n// Example:\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// Support types:\n// SidebarItem \u2014 A single navigation entry in a `Sidebar`\ninterface SidebarItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the item\n  icon?: ReactNode;  // Leading icon rendered before the label\n  href?: string;  // Optional URL associated with this item (not rendered as a link by default)\n  badge?: ReactNode;  // Trailing badge element (e\n  children?: SidebarItem[];  // Nested child items\n  disabled?: boolean;  // When true, the item is visually dimmed and non-interactive (`cursor: not-allo...\n}\n\n// Comment \u2014 A single comment entry in a `CommentThread`\ninterface Comment {\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\n  replies?: Comment[];  // Nested reply comments\n  reactions?: { emoji: string; count: number }[];  // Emoji reactions with their aggregated counts (e\n}\n\n// DataTableColumn \u2014 Column definition for a `DataTable`\ninterface DataTableColumn {\n  key: string;  // Property key on the row object used to extract cell values\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`\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n  align?: 'left' | 'center' | 'right';  // default 'left'; Text alignment for both header and body cells\n}\n\n// ChatMessage \u2014 A single message in a `ChatWindow`\ninterface ChatMessage {\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\n  status?: 'sending' | 'sent' | 'delivered' | 'read' | 'error';  // Delivery status indicator shown on the current user's messages\n}\n\n// NavItem \u2014 A single navigation entry in a `NavigationBar`\ninterface NavItem {\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\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\n}\n\n// UploadedFile \u2014 A file entry in the `FileUploader` composition\ninterface UploadedFile {\n  id: string;  // Unique identifier for this file entry\n  name: string;  // Original file name\n  size: number;  // File size in bytes\n  type: string;  // MIME type of the file (e\n  progress?: number;  // Upload progress as a percentage (0-100)\n  status: 'pending' | 'uploading' | 'success' | 'error';  // Current upload lifecycle status\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\n// Notification \u2014 A single notification entry in the `NotificationCenter`\ninterface Notification {\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\n  read?: boolean;  // default false; Read state\n  type?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Semantic type that controls the status dot color on unread notifications\n  icon?: ReactNode;  // Optional icon rendered alongside the notification (not used by the default im...\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\n// Command \u2014 A single command entry in a `CommandPalette`\ninterface Command {\n  id: string;  // Unique identifier for this command\n  label: string;  // Display label for the command\n  description?: string;  // Optional description text shown below the label\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\n  disabled?: boolean;  // When true, the command is visually dimmed and cannot be selected\n}\n\n// FooterLink \u2014 A single link entry in a footer column or the bottom bar\ninterface FooterLink {\n  label: string;  // Display text for the link\n  href?: string;  // URL for the link\n  onClick?: () => void;  // Click handler\n}\n\n// FooterColumn \u2014 A named column of links in the `Footer` layout\ninterface FooterColumn {\n  title?: string;  // Column heading rendered as an `<h4>` with semibold weight\n  links: FooterLink[];  // Links displayed in this column\n}\n\n// FooterSocialLink \u2014 A social media link in the `Footer` bottom bar\ninterface FooterSocialLink {\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\n// HeroAction \u2014 A call-to-action button definition for the `Hero` composition\ninterface HeroAction {\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 ...\n}\n\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// System Conventions\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// Motion: render <MotionKeyframes /> once to enable keyframes.\n//   Entrance/exit: fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n//   State feedback: flash, pulse, bounce\n//   Easing: linear, easeIn, easeOut, easeInOut, spring\n//   Durations: instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n//\n// Elevation levels (shadow \u2192 z-index):\n//   0: flat          1: sm (cards)     2: md z=1000 (dropdowns, popovers)\n//   3: lg z=1200     4: xl z=1400      5: 2xl z=1800 (tooltips, toasts)\n//\n// useAnimationKey(dep) returns a key that bumps when dep changes \u2014\n// apply to <div key={...}> to replay CSS animations on data update.\n//\n// useMotion() returns { motionEnabled } \u2014 respect prefers-reduced-motion.\n";
+  }
+});
+
 // src/harness/primitive-slice.ts
 var primitive_slice_exports = {};
 __export(primitive_slice_exports, {
+  computeContractPrimitives: () => computeContractPrimitives,
   computePrimitiveAllowlist: () => computePrimitiveAllowlist,
-  slicePrimitiveDocumentation: () => slicePrimitiveDocumentation
+  slicePrimitiveDocumentation: () => slicePrimitiveDocumentation,
+  slicePrimitiveDocumentationTs: () => slicePrimitiveDocumentationTs
 });
 function computePrimitiveAllowlist(classification) {
   const set = new Set(CORE_PRIMITIVES);
@@ -7044,6 +7133,42 @@ function computePrimitiveAllowlist(classification) {
   }
   return [...set].sort();
 }
+function computeContractPrimitives(contract) {
+  const out = /* @__PURE__ */ new Set();
+  if (!contract) return [];
+  for (const slot of Object.values(contract.contextSpec ?? {})) addLeaves(slot.schema, out);
+  for (const action of Object.values(contract.actionSpec ?? {})) {
+    if (action.schema) addLeaves(action.schema, out);
+  }
+  if (Object.keys(contract.streamSpec ?? {}).length > 0) {
+    out.add("Spinner");
+    out.add("Badge");
+  }
+  return [...out].sort();
+}
+function addLeaves(schema, out) {
+  for (const child of Object.values(schema.properties ?? {})) addLeaves(child, out);
+  if (schema.items) addLeaves(schema.items, out);
+  if (schema.enum && schema.enum.length > 0) {
+    out.add("Select");
+    out.add("RadioGroup");
+    return;
+  }
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  for (const t of types) {
+    if (t === "string") {
+      out.add("Input");
+      out.add("TextArea");
+      out.add("FormField");
+    } else if (t === "number" || t === "integer") {
+      out.add("Input");
+      out.add("Slider");
+    } else if (t === "boolean") {
+      out.add("Checkbox");
+      out.add("Toggle");
+    }
+  }
+}
 function slicePrimitiveDocumentation(fullDoc, allowlist) {
   const allow = new Set(allowlist);
   const firstSection = fullDoc.search(/^### \S/m);
@@ -7067,7 +7192,26 @@ function slicePrimitiveDocumentation(fullDoc, allowlist) {
   }
   return preamble + kept.join("");
 }
-var CORE_PRIMITIVES, KNOWN_PRIMITIVE_SECTIONS, AXIS_PRIMITIVES;
+function slicePrimitiveDocumentationTs(fullDoc, allowlist) {
+  const allow = new Set(allowlist);
+  const lines = fullDoc.split("\n");
+  let sawHeader = false;
+  let keep = true;
+  const kept = [];
+  for (const line of lines) {
+    const header = TS_SECTION_HEADER.exec(line);
+    if (header !== null) {
+      sawHeader = true;
+      const name = header[1];
+      keep = !KNOWN_PRIMITIVE_SECTIONS.has(name) || allow.has(name);
+    } else if (TS_SECTION_BANNER.test(line)) {
+      keep = true;
+    }
+    if (keep) kept.push(line);
+  }
+  return sawHeader ? kept.join("\n") : fullDoc;
+}
+var CORE_PRIMITIVES, KNOWN_PRIMITIVE_SECTIONS, AXIS_PRIMITIVES, TS_SECTION_HEADER, TS_SECTION_BANNER;
 var init_primitive_slice = __esm({
   "src/harness/primitive-slice.ts"() {
     CORE_PRIMITIVES = [
@@ -7200,6 +7344,8 @@ var init_primitive_slice = __esm({
       "tooling:both": ["Alert"],
       "tooling:none": []
     };
+    TS_SECTION_HEADER = /^\/\/ ([A-Za-z]+) — /;
+    TS_SECTION_BANNER = /^\/\/ ═/;
   }
 });
 
@@ -7338,18 +7484,6 @@ var init_primitive_index = __esm({
   }
 });
 
-// src/tools/get-primitives-ts.ts
-var get_primitives_ts_exports = {};
-__export(get_primitives_ts_exports, {
-  PRIMITIVES_DOCUMENTATION_TS: () => PRIMITIVES_DOCUMENTATION_TS
-});
-var PRIMITIVES_DOCUMENTATION_TS;
-var init_get_primitives_ts = __esm({
-  "src/tools/get-primitives-ts.ts"() {
-    PRIMITIVES_DOCUMENTATION_TS = "// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// GGUI DESIGN SYSTEM \u2014 COMPONENT REFERENCE\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// CRITICAL \u2014 Props take enum STRING LITERALS, not CSS variables:\n//   <Text size=\"sm\" weight=\"bold\" />                         \u2713\n//   <Text size=\"var(--ggui-font-size-sm)\" />                 \u2717  (breaks)\n//   The enum strings map to CSS variables internally.\n//\n// CRITICAL \u2014 onChange receives the VALUE directly, not an event:\n//   <Input value={x} onChange={setX} />                      \u2713\n//   <Input onChange={(e) => setX(e.target.value)} />         \u2717\n//\n// Imports allowed: 'react', '@ggui-ai/design', '@ggui-ai/wire'.\n//   The WHOLE design system \u2014 primitives, components, compositions,\n//   traits \u2014 is one import: import { Card, Grid, Modal, Clickable }\n//   from '@ggui-ai/design'. No subpaths. No external libs, no\n//   fetch(), no eval().\n//\n// All components accept 'style' + 'className' (omitted below).\n// Structural primitives (Box, Stack, Row, Card) also take a trait via\n// 'as': 'as={Clickable}' adds onClick + keyboard a11y; likewise\n// 'as={Hoverable}' and 'as={Pressable}'. Semantic components\n// (Button/Link/Input) are already interactive and take no 'as'.\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Primitives   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Container \u2014 Width-constrained wrapper that centers content horizontally\ninterface ContainerProps {\n  children?: ReactNode;\n  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full' | string;  // default 'lg'; Maximum width constraint\n  center?: boolean;  // default true; Whether to center the container horizontally via `margin: 0 auto`\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all sides\n}\n\n// Example:\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// Card \u2014 Container with background, shadow, and optional border\ninterface CardProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'lg'; Padding applied to all sides\n  shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl';  // default 'sm'; Shadow elevation level\n  border?: boolean;  // default true; Whether to render a 1px border using `var(--ggui-color-outlineVariant)`\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'lg'; Corner radius\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'hero' | 'transparent';  // default 'default'; Semantic surface slot\n  bleed?: boolean;  // default false; Span the expanded frame's inset edge to edge (ggui#1083)\n}\n\n// Example:\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// Stack \u2014 Flexbox layout primitive for arranging children along a single axis\ninterface StackProps {\n  children?: ReactNode;\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Main axis direction\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\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// Grid \u2014 2-D layout primitive\ninterface GridProps {\n  children?: ReactNode;\n  columns?: number | ResponsiveColumns;  // default 2; Column count\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'md'; Gap between cells\n  minColumnWidth?: number | string;  // default undefined (use `columns`); When set, the grid becomes responsive \u2014 it fits as many equal\n}\n\n// Example:\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n\n// Skeleton \u2014 a pulsing placeholder for content that has not loaded\ninterface SkeletonProps {\n  variant?: 'rect' | 'text' | 'circle';  // default 'rect'; Shape preset\n  width?: number | string;\n  height?: number | string;\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'sm'; Corner radius\n}\n\n// Example:\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n\n// Box \u2014 Generic container with padding, margin, background, and border-radius\ninterface BoxProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all four sides\n  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Horizontal (left + right) padding\n  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Vertical (top + bottom) padding\n  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no margin); Margin applied to all four sides\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'hero' | 'transparent';  // default undefined (transparent); Semantic surface slot\n  bleed?: boolean;  // default false; Span the expanded frame's inset edge to edge (ggui#1083)\n  assetColor?: string;  // default undefined; Asset color escape \u2014 the typed valve for legitimate non-theme\n  assetSemantic?: string;  // default undefined; Human-readable semantic label that documents why\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default undefined (no rounding); Corner radius\n}\n\n// Example:\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// Divider \u2014 A 1px line to visually separate content sections\ninterface DividerProps {\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Line direction\n  margin?: number | string;  // default 16; Spacing around the divider\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-outlineVariant)`); Semantic color slot\n}\n\n// Example:\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// Spacer \u2014 Invisible spacing element, either fixed-size or flexible\ninterface SpacerProps {\n  size?: number | 'flex';  // default 16; Spacing amount\n}\n\n// Example:\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// Text \u2014 Versatile typography primitive for body copy, captions, and labels\ninterface TextProps {\n  children?: ReactNode;\n  size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';  // default 'base'; Font size\n  weight?: 'normal' | 'medium' | 'semibold' | 'bold';  // default 'normal'; Font weight\n  caps?: boolean;  // default false; When true, uppercases the text and adds 0\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n  truncate?: boolean;  // default false; When true, clips overflowing text with an ellipsis\n  is?: 'p' | 'span' | 'div' | 'label';  // default 'p'; HTML element to render\n  id?: string;  // `id` for the rendered element \u2014 anchor an in-page link, or pair\n  htmlFor?: string;  // Associates an `is=\"label\"` element with a form control by the\n}\n\n// Example:\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// Heading \u2014 Semantic heading element (h1-h6) with preset typography styles\ninterface HeadingProps {\n  children?: ReactNode;\n  level?: 1 | 2 | 3 | 4 | 5 | 6;  // default 2; Semantic heading level\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n}\n\n// Example:\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// Button \u2014 A clickable button primitive with multiple visual variants and sizes\ninterface ButtonProps {\n  children?: ReactNode;\n  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';  // default 'primary'; Visual style\n  size?: 'xs' | 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and minimum height:\n  fullWidth?: boolean;  // default false; When true, sets `width: 100%` so the button fills its container\n  loading?: boolean;  // default false; When true, replaces children with a 16px `Spinner` (color: `currentColor`)\n  leftIcon?: ReactNode;  // ReactNode rendered before children, inside the flex layout with `var(--ggui-s...\n  rightIcon?: ReactNode;  // ReactNode rendered after children, inside the flex layout with `var(--ggui-sp...\n  onPress?: () => void;  // Alias for `onClick` for cross-platform compatibility (React Native convention)\n}\n\n// Example:\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n\n// Input \u2014 A single-line text input with label, validation, and helper text\ninterface InputProps {\n  label?: string;  // Label rendered above the input\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\n  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local';  // default 'text'; HTML input type\n  error?: string;  // Error message displayed below the input in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the input in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n\n// TextArea \u2014 A multiline text input with label, validation, character count, a...\ninterface TextAreaProps {\n  label?: string;  // Label rendered above the textarea\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\n  rows?: number;  // default 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)`\n  helperText?: string;  // Helper text displayed below the textarea in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  maxLength?: number;  // Maximum character length (native `maxLength` attribute)\n  showCount?: boolean;  // default false; When true AND `maxLength` is set, displays a `{current}/{max}` character\n  autoResize?: boolean;  // default false; When true, sets CSS `resize: none` on the textarea\n}\n\n// Example:\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n\n// Select \u2014 A native dropdown selection primitive with label and validation\ninterface SelectProps {\n  label?: string;  // Label rendered above the select\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: SelectOption[];  // Array of selectable options\n  placeholder?: string;  // Placeholder text rendered as a disabled `<option value=\"\">` at the top of the\n  error?: string;  // Error message displayed below the select in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the select in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\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// Checkbox \u2014 A custom-styled checkbox with label and description\ninterface CheckboxProps {\n  label?: string;  // Primary label text rendered beside the checkbox box\n  checked?: boolean;  // Controlled checked state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  description?: string;  // Secondary description text rendered below the label in smaller, muted type\n  indeterminate?: boolean;  // default false; When true, displays a horizontal dash instead of a checkmark\n}\n\n// Example:\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// Toggle \u2014 A switch/toggle input rendered as a pill-shaped track with a slidin...\ninterface ToggleProps {\n  label?: string;  // Label text rendered to the right of the toggle track\n  checked?: boolean;  // Controlled checked (on/off) state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track and knob dimensions:\n}\n\n// Example:\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n\n// RadioGroup \u2014 A group of mutually exclusive radio options with optional label...\ninterface RadioGroupProps {\n  label?: string;  // Group label rendered above the options\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: RadioOption[];  // Array of radio options\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Layout direction for the options container:\n  disabled?: boolean;  // default false; When true, disables ALL options (individual `RadioOption\n  error?: string;  // Error message displayed below all options in `var(--ggui-color-error-500)`\n}\n\n// Example:\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// Slider \u2014 A range input with a custom-styled track, fill, and thumb\ninterface SliderProps {\n  label?: string;  // Label rendered above the slider track (left-aligned)\n  value?: number;  // default 0; Controlled numeric value\n  onChange?: (value: number) => void;  // Change handler\n  min?: number;  // default 0; Minimum allowed value\n  max?: number;  // default 100; Maximum allowed value\n  step?: number;  // default 1; Step increment for the slider\n  disabled?: boolean;  // default false; When true, sets `cursor: not-allowed` on the native input\n  showValue?: boolean;  // default false; When true, displays the current numeric value right-aligned in the header row\n}\n\n// Example:\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n\n// Badge \u2014 Inline label for status indicators, counts, or categories\ninterface BadgeProps {\n  children?: ReactNode;\n  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'tertiary';  // default 'default'; Visual style\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n  pill?: boolean;  // default true; When true, uses fully rounded corners (`border-radius: 9999px`)\n}\n\n// Example:\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n\n// Spinner \u2014 Animated SVG loading indicator\ninterface SpinnerProps {\n  size?: number;  // default 24; Width and height of the SVG element in pixels\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the animated foreground arc\n}\n\n// Example:\n<Spinner size={32} tone=\"success\" />\n\n// Avatar \u2014 User or entity representation with image or auto-generated initials\ninterface AvatarProps {\n  src?: string;  // Image URL\n  name?: string;  // Name used for two purposes:\n  size?: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl';  // default 'md'; Avatar dimensions\n  shape?: 'circle' | 'square';  // default 'circle'; Container shape\n}\n\n// Example:\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n\n// Alert \u2014 Contextual message box for important information with icon and optio...\ninterface AlertProps {\n  children?: ReactNode;\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the body in semibold (`var(--ggui-font-weight-s...\n  closable?: boolean;  // default false; When true, renders a close button (X icon) in the top-right area\n  onClose?: () => void;  // Callback fired when the close button is clicked\n  icon?: ReactNode;  // Custom icon ReactNode to replace the default variant icon\n}\n\n// Example:\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n\n// Progress \u2014 Horizontal progress bar with determinate and indeterminate modes\ninterface ProgressProps {\n  value: number;  // Current progress value\n  max?: number;  // default 100; Maximum value representing 100% progress\n  variant?: 'default' | 'success' | 'warning' | 'error';  // default 'default'; Fill bar color\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track height in pixels:\n  label?: string;  // Accessible name describing what this bar measures, e\n  showLabel?: boolean;  // default false; When true, displays a header row above the track with the `label` text\n  indeterminate?: boolean;  // default false; When true, ignores `value` for visual width and plays a looping animation\n}\n\n// Example:\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n\n// Image \u2014 An `<img>` element with built-in error handling and fallback support\ninterface ImageProps {\n  src: string;  // Image source URL\n  alt: string;  // Alt text for the image\n  width?: number | string;  // default '100%' (applied at render time, not on the type); Image width\n  height?: number | string;  // default 'auto' (applied at render time, not on the type); Image height\n  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';  // default '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\n  fallback?: ReactNode;  // Custom ReactNode rendered when the image fails to load\n}\n\n// Example:\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n\n// Icon \u2014 a curated Lucide subset (~200 names) + emoji passthrough\ninterface IconProps {\n  name?: string;  // Lucide icon name from the curated subset (kebab-case, camelCase, or\n  size?: number;  // default 24; Icon dimensions in pixels (applied to both width and height of the wrapper\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (icon uses `currentColor`); Semantic color slot\n  children?: ReactNode;  // Custom SVG children\n  'aria-label'?: string;  // Accessible name for a standalone, meaning-bearing icon\n}\n\n// Example:\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n\n// Link \u2014 Styled anchor element with external link support\ninterface LinkProps {\n  children?: ReactNode;\n  href: string;  // Destination URL\n  external?: boolean;  // default false; When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener norefer...\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the link text\n  underline?: 'always' | 'hover' | 'none';  // default 'hover'; Underline behavior:\n}\n\n// Example:\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n\n// Tooltip \u2014 Hoverable information popup positioned relative to a trigger element\ninterface TooltipProps {\n  children: ReactNode;  // Trigger element\n  content: ReactNode;  // Tooltip content\n  position?: 'top' | 'bottom' | 'left' | 'right';  // default 'top'; Tooltip placement relative to the trigger element:\n  delay?: number;  // default 200; Delay in milliseconds before the tooltip becomes visible after hover/focus\n}\n\n// Example:\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n\n// Table \u2014 Data table with sortable columns, striped rows, and hover highlights\ninterface TableProps {\n  columns: TableColumn<T>[];  // Array of column definitions controlling header labels, data keys, and rendering\n  data: T[];  // Array of row data objects\n  sortKey?: string;  // The `key` of the currently sorted column\n  sortDirection?: SortDirection;  // default 'asc'; Current sort direction for the column identified by `sortKey`\n  onSort?: (key: string, direction: SortDirection) => void;  // Sort change handler\n  striped?: boolean;  // default false; When true, alternating rows (odd index) get a\n  hoverable?: boolean;  // default true; When true, rows highlight with `var(--ggui-color-container)`\n  compact?: boolean;  // default false; When true, reduces cell padding:\n  bordered?: boolean;  // default false; When true, adds a 1px border around the table wrapper and between cells\n  caption?: string;  // Accessible table caption\n}\n\n// Example:\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// Tabs \u2014 Accessible tab navigation with panels and keyboard support\ninterface TabsProps {\n  items: TabItem[];  // Array of tab definitions\n  activeKey?: string;  // Controlled active tab key\n  onChange?: (key: string) => void;  // Tab change handler\n  variant?: 'line' | 'pills' | 'enclosed';  // default 'line'; Visual style of the tab bar:\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls tab button padding and font size:\n  fullWidth?: boolean;  // default false; When true, tab buttons expand equally to fill the container width\n}\n\n// Example:\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// Toast \u2014 Notification banner with auto-dismiss and slide-in animation\ninterface ToastProps {\n  message: ReactNode;  // Message body content\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the message in semibold\n  duration?: number;  // default 5000; Auto-dismiss delay in milliseconds\n  onClose?: () => void;  // Callback fired on auto-dismiss timeout or when the close button is clicked\n  visible?: boolean;  // default true; Controls rendering\n  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';  // Intended screen position\n}\n\n// Example:\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n\n// Accordion \u2014 Collapsible content sections with chevron rotation animation\ninterface AccordionProps {\n  items: AccordionItem[];  // Array of collapsible section definitions\n  expandedKeys?: string[];  // Controlled expanded state\n  onChange?: (expandedKeys: string[]) => void;  // Expand/collapse handler\n  multiple?: boolean;  // default false; When true, multiple items can be open simultaneously\n  variant?: 'default' | 'bordered' | 'separated';  // default 'default'; Visual style controlling borders and spacing:\n}\n\n// Example:\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// Row \u2014 Convenience alias for a horizontal Stack\ninterface RowProps {\n  children?: ReactNode;\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Row gap=\"md\" align=\"center\" justify=\"between\">\n  <Text size=\"sm\" weight=\"medium\">Total</Text>\n  <Text weight=\"bold\">$42.00</Text>\n</Row>\n\n// Support types:\n// ResponsiveColumns \u2014 Explicit column count per viewport breakpoint, mobile-first\ninterface ResponsiveColumns {\n  base?: number;  // default 1; 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\n// SelectOption \u2014 An individual option within a `Select` dropdown\ninterface SelectOption {\n  value: string;  // The value submitted when this option is selected\n  label: string;  // The display text shown in the dropdown\n  disabled?: boolean;  // default false; When true, the option is visible but cannot be selected (grayed out by the br...\n}\n\n// RadioOption \u2014 An individual option within a `RadioGroup`\ninterface RadioOption {\n  value: string;  // The value emitted via `RadioGroupProps\n  label: string;  // Display text for this option\n  description?: string;  // Optional secondary description rendered below the label in smaller, muted type\n  disabled?: boolean;  // default false; When true, this individual option is grayed out (`opacity: 0\n}\n\n// TableColumn \u2014 Column definition for the Table component\ninterface TableColumn {\n  key: string;  // Property key in the row data object\n  header: string;  // Column header text\n  width?: number | string;  // Fixed column width\n  align?: 'left' | 'center' | 'right';  // default 'left'; Horizontal text alignment for both the header and data cells\n  sortable?: boolean;  // default false; When true, the header cell becomes clickable and shows sort direction\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n}\n\n// TabItem \u2014 Definition of a single tab within a Tabs component\ninterface TabItem {\n  key: string;  // Unique identifier for this tab\n  label: ReactNode;  // Tab button label\n  content: ReactNode;  // Panel content rendered below the tab bar when this tab is active\n  disabled?: boolean;  // default false; When true, the tab button shows `opacity: 0\n  icon?: ReactNode;  // Optional icon rendered before the label inside the tab button, with\n}\n\n// AccordionItem \u2014 Definition of a single collapsible section within an Accordion\ninterface AccordionItem {\n  key: string;  // Unique identifier for this item\n  title: ReactNode;  // Header label rendered inside the toggle button\n  content: ReactNode;  // Panel content rendered below the header when expanded\n  disabled?: boolean;  // default false; When true, the header button shows `opacity: 0\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Components   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// SearchField \u2014 A text input with a leading search icon and optional submit button\ninterface SearchFieldProps {\n  value?: string;  // Current search value\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly, not\n  onSearch?: (value: string) => void;  // Called when the user presses **Enter** or clicks the search button\n  placeholder?: string;  // default 'Search...'; Placeholder text shown when the input is empty\n  showButton?: boolean;  // default false; When `true`, renders a `Button` primitive to the right of the input\n  buttonText?: string;  // default 'Search'; Label rendered inside the submit button\n  loading?: boolean;  // When `true`, replaces the search icon with a `Spinner`, disables the\n  disabled?: boolean;  // When `true`, the input and button are visually disabled and do not\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls input height and font size\n}\n\n// Example:\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// FormField \u2014 A wrapper that adds a label, optional description, error message,\ninterface FormFieldProps {\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) re...\n  error?: string;  // Error message displayed below `children` in `colors\n  helperText?: string;  // Neutral guidance text displayed below `children` in `colors\n  required?: boolean;  // When `true`, appends a red asterisk (`*`) after the label text\n  description?: string;  // Secondary description rendered between the label and the child control\n}\n\n// Example:\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// MenuItem \u2014 A full-width clickable row for menus, sidebars, and action lists\ninterface MenuItemProps {\n  label: string;  // Primary text content of the menu item\n  icon?: ReactNode;  // Icon or element rendered to the left of the label\n  rightElement?: ReactNode;  // Element rendered to the right of the label (e\n  onClick?: () => void;  // Called when the item is clicked\n  disabled?: boolean;  // When `true`, the item is non-interactive: `colors\n  active?: boolean;  // Marks this item as the current selection\n  danger?: boolean;  // Switches the item to destructive styling: `colors\n}\n\n// Example:\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// Tag \u2014 An inline label for categories, filters, statuses, or selections\ninterface TagProps {\n  children: ReactNode;  // Tag content -- typically a short text string\n  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';  // default 'default'; Semantic color variant applied to background, text, and border\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and internal gap\n  closable?: boolean;  // When `true`, renders a small close (\"x\") button after the content\n  onClose?: () => void;  // Called when the close button is clicked\n  icon?: ReactNode;  // Icon or element rendered before the text content\n}\n\n// Example:\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n\n// Dropdown \u2014 A click-triggered menu anchored to a trigger element\ninterface DropdownProps {\n  trigger: ReactNode;  // The element the user clicks to open the menu\n  options: DropdownOption[];  // Array of selectable options rendered as `MenuItem` rows\n  value?: string;  // The `value` of the currently selected option\n  onChange?: (value: string) => void;  // Called with the `value` string of the selected option (not the full\n  placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';  // default 'bottom-start'; Where to anchor the menu panel relative to the trigger\n  disabled?: boolean;  // When `true`, the trigger shows `cursor: not-allowed` and clicking\n}\n\n// Example:\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// Autocomplete \u2014 A text input with a filterable suggestion dropdown, keyboard navigation,\ninterface AutocompleteProps {\n  value?: string;  // default ''; Current text in the input field\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly,\n  onSelect?: (option: AutocompleteOption) => void;  // Called when the user selects an option (click or Enter on highlighted\n  options: AutocompleteOption[];  // The full list of available options\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\n  disabled?: boolean;  // When `true`, the inner `Input` is disabled and the dropdown\n  error?: string;  // Error message forwarded to the inner `Input` primitive\n  noResultsText?: string;  // default 'No results found'; Text shown in the dropdown when filtering produces zero matches\n}\n\n// Example:\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// Breadcrumb \u2014 A horizontal navigation trail showing the user's location within a\ninterface BreadcrumbProps {\n  items: BreadcrumbItem[];  // Ordered array of breadcrumb segments from root to current page\n  separator?: ReactNode;  // default '/'; Separator rendered between each pair of items\n  onItemClick?: (item: BreadcrumbItem, index: number) => void;  // Called when a non-last item is clicked\n}\n\n// Example:\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// Pagination \u2014 Page navigation controls with previous/next arrows, numbered page buttons,\ninterface PaginationProps {\n  currentPage: number;  // Current active page\n  totalPages: number;  // Total number of pages\n  onPageChange?: (page: number) => void;  // Called when the user clicks a page number, arrow, or first/last button\n  showFirstLast?: boolean;  // default true; When `true`, renders double-chevron buttons for jumping to the first\n  maxVisible?: number;  // default 5; Maximum number of page buttons visible at once (including the first\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls button dimensions and icon sizes\n  disabled?: boolean;  // When `true`, all page buttons and arrows are visually dimmed\n}\n\n// Example:\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n\n// EmptyState \u2014 placeholder for a region with no data: empty lists,\ninterface EmptyStateProps {\n  icon?: string | ReactNode;  // A Lucide icon name (kebab-case), rendered large and subtle above\n  title: string;  // The headline, e\n  description?: string;  // Optional supporting line below the title\n  action?: ReactNode;  // Optional call-to-action, typically a `<Button>`\n}\n\n// Example:\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// Stat \u2014 a single KPI / metric: a label, a large value, an optional\ninterface StatProps {\n  label: string;  // The metric name, e\n  value: string | number;  // The headline value \u2014 the big number\n  delta?: string;  // Optional change indicator, pre-formatted, e\n  trend?: 'up' | 'down' | 'neutral';  // default 'neutral'; Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error,\n  icon?: string | ReactNode;  // Optional Lucide icon name (kebab-case) or custom node, shown next\n}\n\n// Example:\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n\n// Stepper \u2014 a display-only step indicator for multi-step flows\ninterface StepperProps {\n  steps: string[];  // Ordered step labels, one per step\n  current: number;  // Zero-based index of the active step\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Flow direction\n  onStepClick?: (index: number) => void;  // When provided, each step becomes a real button and clicks receive\n}\n\n// Example:\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// Markdown \u2014 renders markdown-formatted text as styled content:\ninterface MarkdownProps {\n  markdown: string;  // Markdown source text, passed through verbatim\n}\n\n// Example:\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n\n// MarkdownInline \u2014 renders ONE line of inline-level markdown (bold,\ninterface MarkdownInlineProps {\n  markdown: string;  // Inline markdown source -- bold, italic, inline code, and\n}\n\n// Example:\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n\n// Support types:\n// DropdownOption \u2014 A single option inside a `Dropdown`\ninterface DropdownOption {\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\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive\n  danger?: boolean;  // When `true`, the option uses destructive (red) styling via\n}\n\n// AutocompleteOption \u2014 A single option in the `Autocomplete` suggestion list\ninterface AutocompleteOption {\n  value: string;  // Unique identifier for this option\n  label: string;  // Primary display text\n  description?: string;  // Secondary description rendered below the label in `fontSize\n  icon?: ReactNode;  // Icon rendered to the left of the label/description block\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive (`cursor: not-allowed`...\n}\n\n// BreadcrumbItem \u2014 A single segment in a `Breadcrumb` trail\ninterface BreadcrumbItem {\n  label: string;  // Display text for this breadcrumb segment\n  href?: string;  // URL for this segment\n  icon?: ReactNode;  // Icon rendered immediately before the label\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Compositions   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Header \u2014 Props for the `Header` composition\ninterface HeaderProps {\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 l...\n  actions?: ReactNode;  // Right-side action elements (buttons, avatar, etc\n  sticky?: boolean;  // default false; When true, the header becomes `position: sticky` at the top of its scroll con...\n  background?: string;  // default colors.white; Background color of the header\n  bordered?: boolean;  // default true; When true, renders a 1 px bottom border in `colors\n}\n\n// Example:\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// Sidebar \u2014 Props for the `Sidebar` composition\ninterface SidebarProps {\n  items: SidebarItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: SidebarItem) => void;  // Called when any item (including parent items with children) is clicked\n  collapsed?: boolean;  // default false; When true, hides labels and badges; only icons remain visible, centered in th...\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;  // default 256; Width in pixels when expanded\n  collapsedWidth?: number;  // default 64; Width in pixels when collapsed\n}\n\n// Example:\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// CardGrid \u2014 Props for the `CardGrid` composition\ninterface CardGridProps {\n  children: ReactNode;  // Card elements to arrange in the grid\n  columns?: number | { sm?: number; md?: number; lg?: number };  // default 3; Number of columns, or a responsive breakpoint map\n  gap?: number;  // default 16; Gap between grid items in pixels\n}\n\n// Example:\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// CommentThread \u2014 Props for the `CommentThread` composition\ninterface CommentThreadProps {\n  comments: Comment[];  // Array of top-level comments to render\n  currentUser?: { /** Display name for the current user's avatar. */ name: string; /** Avatar image URL for the current user. */ avatar?: string; };  // Current user info\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\n// Example:\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// DataTable \u2014 Props for the `DataTable` composition\ninterface DataTableProps {\n  columns: DataTableColumn<T>[];  // Column definitions that control header, alignment, sorting, and rendering\n  data: T[];  // Row data array\n  rowKey?: string | ((row: T) => string);  // default '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;  // default '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\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\n  selectable?: boolean;  // When true, adds a checkbox column at the start of each row\n  selectedKeys?: string[];  // default []; 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-...\n}\n\n// Example:\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// ChatWindow \u2014 Props for the `ChatWindow` composition\ninterface ChatWindowProps {\n  messages: ChatMessage[];  // Array of chat messages to display in chronological order\n  currentUserId: string;  // ID of the current user\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\n  placeholder?: string;  // default 'Type a message...'; Placeholder text for the message input field\n  header?: ReactNode;  // Optional header content rendered above the message area, separated by a botto...\n}\n\n// Example:\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// NavigationBar \u2014 Props for the `NavigationBar` composition\ninterface NavigationBarProps {\n  items: NavItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: NavItem) => void;  // Called when a non-disabled item is clicked\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Layout direction\n  variant?: 'default' | 'pills' | 'underline';  // default 'default'; Visual style for active/inactive items\n}\n\n// Example:\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// FileUploader \u2014 Props for the `FileUploader` composition\ninterface FileUploaderProps {\n  files?: UploadedFile[];  // default []; 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\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=\"\n  multiple?: boolean;  // default true; When true, allows selecting multiple files at once\n  maxSize?: number;  // Maximum file size in bytes\n  maxFiles?: number;  // Maximum number of files\n  disabled?: boolean;  // When true, the drop zone is visually dimmed (opacity 0\n  dragDrop?: boolean;  // default true; When true, enables drag-and-drop on the drop zone\n}\n\n// Example:\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// NotificationCenter \u2014 Props for the `NotificationCenter` composition\ninterface NotificationCenterProps {\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\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\n  emptyText?: string;  // default '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\n// Example:\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// Modal \u2014 Props for the `Modal` composition\ninterface ModalProps {\n  open: boolean;  // Controls modal visibility\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 (leve...\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, separ...\n  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';  // default 'md'; Controls the width of the modal panel\n  closeOnOverlayClick?: boolean;  // default true; When true, clicking the semi-transparent overlay behind the modal calls `onCl...\n  closeOnEscape?: boolean;  // default true; When true, pressing the Escape key calls `onClose`\n  showCloseButton?: boolean;  // default true; When true, renders a ghost close button (X icon) in the modal header\n}\n\n// Example:\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// CommandPalette \u2014 Props for the `CommandPalette` composition\ninterface CommandPaletteProps {\n  open: boolean;  // Controls palette visibility\n  onClose: () => void;  // Called to close the palette (overlay click, Escape key, or after command sele...\n  commands: Command[];  // Full array of available commands\n  onSelect: (command: Command) => void;  // Called when a non-disabled command is selected (Enter key or click)\n  placeholder?: string;  // default 'Search commands...'; Placeholder text for the search input\n  recentIds?: string[];  // default []; IDs of recently used commands\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the command list\n}\n\n// Example:\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// Footer \u2014 Props for the `Footer` composition\ninterface FooterProps {\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\n  bottomLinks?: FooterLink[];  // Links displayed in the bottom bar after social icons (e\n  background?: string;  // default colors.gray[50]; Background color of the footer\n  bordered?: boolean;  // default true; When true, renders a 1 px top border in `colors\n}\n\n// Example:\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// Hero \u2014 Props for the `Hero` composition\ninterface HeroProps {\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\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 ...\n  align?: 'center' | 'left';  // default 'center'; Text and layout alignment\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls vertical padding and heading/description font sizes\n  background?: string;  // default 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:...\n  overlay?: boolean;  // default false; When true and `backgroundImage` is set, renders a semi-transparent black overlay\n}\n\n// Example:\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// Support types:\n// SidebarItem \u2014 A single navigation entry in a `Sidebar`\ninterface SidebarItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the item\n  icon?: ReactNode;  // Leading icon rendered before the label\n  href?: string;  // Optional URL associated with this item (not rendered as a link by default)\n  badge?: ReactNode;  // Trailing badge element (e\n  children?: SidebarItem[];  // Nested child items\n  disabled?: boolean;  // When true, the item is visually dimmed and non-interactive (`cursor: not-allo...\n}\n\n// Comment \u2014 A single comment entry in a `CommentThread`\ninterface Comment {\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\n  replies?: Comment[];  // Nested reply comments\n  reactions?: { emoji: string; count: number }[];  // Emoji reactions with their aggregated counts (e\n}\n\n// DataTableColumn \u2014 Column definition for a `DataTable`\ninterface DataTableColumn {\n  key: string;  // Property key on the row object used to extract cell values\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`\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n  align?: 'left' | 'center' | 'right';  // default 'left'; Text alignment for both header and body cells\n}\n\n// ChatMessage \u2014 A single message in a `ChatWindow`\ninterface ChatMessage {\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\n  status?: 'sending' | 'sent' | 'delivered' | 'read' | 'error';  // Delivery status indicator shown on the current user's messages\n}\n\n// NavItem \u2014 A single navigation entry in a `NavigationBar`\ninterface NavItem {\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\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\n}\n\n// UploadedFile \u2014 A file entry in the `FileUploader` composition\ninterface UploadedFile {\n  id: string;  // Unique identifier for this file entry\n  name: string;  // Original file name\n  size: number;  // File size in bytes\n  type: string;  // MIME type of the file (e\n  progress?: number;  // Upload progress as a percentage (0-100)\n  status: 'pending' | 'uploading' | 'success' | 'error';  // Current upload lifecycle status\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\n// Notification \u2014 A single notification entry in the `NotificationCenter`\ninterface Notification {\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\n  read?: boolean;  // default false; Read state\n  type?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Semantic type that controls the status dot color on unread notifications\n  icon?: ReactNode;  // Optional icon rendered alongside the notification (not used by the default im...\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\n// Command \u2014 A single command entry in a `CommandPalette`\ninterface Command {\n  id: string;  // Unique identifier for this command\n  label: string;  // Display label for the command\n  description?: string;  // Optional description text shown below the label\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\n  disabled?: boolean;  // When true, the command is visually dimmed and cannot be selected\n}\n\n// FooterLink \u2014 A single link entry in a footer column or the bottom bar\ninterface FooterLink {\n  label: string;  // Display text for the link\n  href?: string;  // URL for the link\n  onClick?: () => void;  // Click handler\n}\n\n// FooterColumn \u2014 A named column of links in the `Footer` layout\ninterface FooterColumn {\n  title?: string;  // Column heading rendered as an `<h4>` with semibold weight\n  links: FooterLink[];  // Links displayed in this column\n}\n\n// FooterSocialLink \u2014 A social media link in the `Footer` bottom bar\ninterface FooterSocialLink {\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\n// HeroAction \u2014 A call-to-action button definition for the `Hero` composition\ninterface HeroAction {\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 ...\n}\n\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// System Conventions\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// Motion: render <MotionKeyframes /> once to enable keyframes.\n//   Entrance/exit: fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n//   State feedback: flash, pulse, bounce\n//   Easing: linear, easeIn, easeOut, easeInOut, spring\n//   Durations: instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n//\n// Elevation levels (shadow \u2192 z-index):\n//   0: flat          1: sm (cards)     2: md z=1000 (dropdowns, popovers)\n//   3: lg z=1200     4: xl z=1400      5: 2xl z=1800 (tooltips, toasts)\n//\n// useAnimationKey(dep) returns a key that bumps when dep changes \u2014\n// apply to <div key={...}> to replay CSS animations on data update.\n//\n// useMotion() returns { motionEnabled } \u2014 respect prefers-reduced-motion.\n";
-  }
-});
-
 // src/classifier/inspect.ts
 function resolveSchema(node) {
   if (!node || typeof node !== "object") return void 0;
@@ -13103,13 +13237,22 @@ function editableSurface(el) {
 function parentLink(node) {
   return node;
 }
-async function runRenderCheck(input) {
+var RENDER_CHECK_KINDS = [
+  "render-no-throw",
+  "prop-sensitivity",
+  "action-wiring",
+  "selection-identity",
+  "prop-coverage",
+  "optional-props-omitted",
+  "stream-rerender"
+];
+async function runRenderCheck(input, options = {}) {
   const g = hostGlobals();
   if ("window" in g && "document" in g) {
     return runRenderCheckInProcess(input);
   }
   const { runRenderCheckViaWorker: runRenderCheckViaWorker2 } = await Promise.resolve().then(() => (init_render_check_host(), render_check_host_exports));
-  return runRenderCheckViaWorker2(input);
+  return runRenderCheckViaWorker2(input, options);
 }
 async function runRenderCheckInProcess(input) {
   const t0 = Date.now();
@@ -13123,7 +13266,7 @@ async function runRenderCheckInProcess(input) {
     const Wire = await import('@ggui-ai/wire');
     const { GguiWireProvider } = Wire;
     const moduleResolutions = {
-      "react": React,
+      react: React,
       "react/jsx-runtime": ReactJsxRuntime,
       "@ggui-ai/wire": Wire
     };
@@ -13239,14 +13382,23 @@ async function runRenderCheckInProcess(input) {
         )
       );
       const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error(`[runtime-render] render exceeded ${RENDER_TIMEOUT_MS}ms \u2014 classified as runtime-hang`)), RENDER_TIMEOUT_MS).unref?.();
+        setTimeout(
+          () => reject(
+            new Error(
+              `[runtime-render] render exceeded ${RENDER_TIMEOUT_MS}ms \u2014 classified as runtime-hang`
+            )
+          ),
+          RENDER_TIMEOUT_MS
+        ).unref?.();
       });
       renderResult = await Promise.race([renderPromise, timeoutPromise]);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       const errStack = e instanceof Error ? e.stack ?? "" : "";
       const baseReason = loopSignature ? `Infinite render loop (${loopSignature}) \u2014 likely setState/dispatch inside useEffect with missing or unstable dependency` : /runtime-hang/.test(msg) ? `Render wall-clock exceeded ${RENDER_TIMEOUT_MS}ms \u2014 likely async effect loop or unresolved promise` : `Render threw: ${msg}`;
-      const userFrames = errStack.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ")).filter((l) => !/(node_modules|happy-dom|@testing-library|react-dom|node:internal|node:async)/.test(l)).slice(0, 5);
+      const userFrames = errStack.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ")).filter(
+        (l) => !/(node_modules|happy-dom|@testing-library|react-dom|node:internal|node:async)/.test(l)
+      ).slice(0, 5);
       const stackSource = boundaryRef.stack ?? capturedComponentStack ?? "";
       const componentFrames = stackSource.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ")).slice(0, 4);
       const stackBlock = userFrames.length ? `
@@ -13711,9 +13863,7 @@ function idLikeRequiredStringField(schema) {
   const required = schema["required"];
   if (properties === null || typeof properties !== "object") return null;
   if (!Array.isArray(required)) return null;
-  for (const [propName, propSchema] of Object.entries(
-    properties
-  )) {
+  for (const [propName, propSchema] of Object.entries(properties)) {
     if (!/id$/i.test(propName)) continue;
     if (!required.includes(propName)) continue;
     const t = propSchema !== null && typeof propSchema === "object" ? propSchema["type"] : void 0;
@@ -13744,9 +13894,7 @@ async function checkSelectionIdentity(input) {
         return void 0;
       }
       await flushPromises();
-      const events = probe.getFireLog().slice(before).filter(
-        (e) => e.kind === "action.fired" && e.name === actionName
-      );
+      const events = probe.getFireLog().slice(before).filter((e) => e.kind === "action.fired" && e.name === actionName);
       return events.length > 0 ? events[events.length - 1].payload : void 0;
     };
     const first = await payloadFor(group[0]);
@@ -13807,7 +13955,10 @@ async function dispatchTrigger(el, kind, user) {
     case "submit": {
       const form = closestForm(el);
       if (!form) return;
-      const ev = new globalThis.Event("submit", { bubbles: true, cancelable: true });
+      const ev = new globalThis.Event("submit", {
+        bubbles: true,
+        cancelable: true
+      });
       toEventDispatcher(form).dispatchEvent(ev);
       return;
     }
@@ -14012,6 +14163,9 @@ function flushPromises() {
   return new Promise((resolve4) => setTimeout(resolve4, 0));
 }
 
+// src/harness/check/runtime-render/adapter.ts
+init_render_check_host();
+
 // src/harness/check/runtime-render/prepare-mockup.ts
 function prepareMockupProps(input) {
   const { contract, fixtureProps } = input;
@@ -14144,47 +14298,111 @@ function synthesizeFromSchema(schema, hint, warnings, depth, ordinal) {
 }
 
 // src/harness/check/runtime-render/adapter.ts
-var DEFAULT_RUNTIME_RENDER_CHECK = {
-  id: "runtime-render",
-  run: async (input) => {
-    const { sourceCode, compiledCode, contract, fixtureProps } = input;
-    if (compiledCode === null) {
-      return { status: "not-applicable", issues: [], reason: "no compiled code" };
-    }
-    if (!contract) {
-      return { status: "not-applicable", issues: [], reason: "no contract surface" };
-    }
-    const mockup = prepareMockupProps({ contract, fixtureProps });
-    let result;
-    try {
-      result = await runRenderCheck({
-        sourceCode,
-        mockupProps: mockup.props,
-        contract
+function createSlotLimiter(maxConcurrent) {
+  if (maxConcurrent === void 0) return (task) => task(0);
+  if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1) {
+    throw new RangeError(
+      `createRuntimeRenderCheck: maxConcurrent must be a positive integer, got ${maxConcurrent}`
+    );
+  }
+  let active = 0;
+  const waiting = [];
+  const acquire = () => {
+    if (active < maxConcurrent) {
+      active += 1;
+      return Promise.resolve(0);
+    }
+    const enqueuedAt = Date.now();
+    return new Promise((resolve4) => {
+      waiting.push(() => {
+        active += 1;
+        resolve4(Date.now() - enqueuedAt);
       });
-    } catch (e) {
-      const message = e instanceof Error ? e.message : String(e);
-      console.warn(
-        `[runtime-render] probe skipped \u2014 infra failure: ${message}`
-      );
-      return { status: "infra-skipped", issues: [], reason: message };
+    });
+  };
+  const release = () => {
+    active -= 1;
+    const next = waiting.shift();
+    if (next !== void 0) next();
+  };
+  return async (task) => {
+    const waitedMs = await acquire();
+    try {
+      return await task(waitedMs);
+    } finally {
+      release();
     }
-    const hostLoad = result.stats.hostLoad;
-    const load = hostLoad !== void 0 ? { hostLoad } : {};
-    if (result.incomplete !== void 0) {
-      const { elapsedMs, boundMs } = result.incomplete;
-      const loadNote = hostLoad !== void 0 ? `; host load ${hostLoad.start.toFixed(1)} \u2192 ${hostLoad.end.toFixed(1)} on ${hostLoad.cores} CPUs` : "";
-      const reason = `render check did not finish within ${boundMs} ms (stopped at ${elapsedMs} ms)${loadNote}`;
-      console.warn(`[runtime-render] probe timed out \u2014 ${reason}`);
-      return { status: "timed-out", issues: [], reason, elapsedMs, ...load };
+  };
+}
+function queuedField(queuedMs) {
+  return queuedMs > 0 ? { queuedMs } : {};
+}
+function toRenderCheckOptions(config) {
+  if (config.timeoutMs === void 0 && config.heapMb === void 0) return void 0;
+  return {
+    bounds: {
+      ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
+      ...config.heapMb !== void 0 ? { heapMb: config.heapMb } : {}
     }
-    return {
-      status: "ran",
-      issues: result.issues.map(toEvalIssue).filter((x) => x !== null),
-      ...load
-    };
-  }
-};
+  };
+}
+function createRuntimeRenderCheck(config = {}) {
+  const limit = createSlotLimiter(config.maxConcurrent);
+  const options = toRenderCheckOptions(config);
+  if (options !== void 0) resolveRenderCheckHostBounds(options.bounds);
+  return {
+    id: "runtime-render",
+    run: async (input) => {
+      const { sourceCode, compiledCode, contract, fixtureProps } = input;
+      if (compiledCode === null) {
+        return { status: "not-applicable", issues: [], reason: "no compiled code" };
+      }
+      if (!contract) {
+        return { status: "not-applicable", issues: [], reason: "no contract surface" };
+      }
+      const mockup = prepareMockupProps({ contract, fixtureProps });
+      let queuedMs = 0;
+      let t0 = Date.now();
+      let result;
+      try {
+        result = await limit((waitedMs) => {
+          queuedMs = waitedMs;
+          t0 = Date.now();
+          return runRenderCheck(
+            {
+              sourceCode,
+              mockupProps: mockup.props,
+              contract
+            },
+            options
+          );
+        });
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        console.warn(`[runtime-render] probe skipped \u2014 infra failure: ${message}`);
+        return { status: "infra-skipped", issues: [], reason: message, elapsedMs: Date.now() - t0, ...queuedField(queuedMs) };
+      }
+      const hostLoad = result.stats.hostLoad;
+      const load = hostLoad !== void 0 ? { hostLoad } : {};
+      if (result.incomplete !== void 0) {
+        const { elapsedMs, boundMs } = result.incomplete;
+        const loadNote = hostLoad !== void 0 ? `; host load ${hostLoad.start.toFixed(1)} \u2192 ${hostLoad.end.toFixed(1)} on ${hostLoad.cores} CPUs` : "";
+        const reason = `render check did not finish within ${boundMs} ms (stopped at ${elapsedMs} ms)${loadNote}`;
+        console.warn(`[runtime-render] probe timed out \u2014 ${reason}`);
+        return { status: "timed-out", issues: [], reason, elapsedMs: Date.now() - t0, ...queuedField(queuedMs), ...load };
+      }
+      return {
+        status: "ran",
+        issues: result.issues.map(toEvalIssue).filter((x) => x !== null),
+        elapsedMs: Date.now() - t0,
+        ...queuedField(queuedMs),
+        renderMs: result.stats.renderMs,
+        ...load
+      };
+    }
+  };
+}
+var DEFAULT_RUNTIME_RENDER_CHECK = createRuntimeRenderCheck();
 var CLASS_SPECIFIC_PATTERNS = [
   /too many re-renders/i,
   /maximum update depth/i,
@@ -14223,6 +14441,14 @@ function classifyRenderCrashFix(reason) {
   }
   return "Add null guards on optional props, handle empty arrays/strings, and verify all hook outputs before destructuring.";
 }
+var RUNTIME_SUBCATEGORY_PREFIX = "runtime:";
+function parseRuntimeSubcategory(subcategory) {
+  if (!subcategory.startsWith(RUNTIME_SUBCATEGORY_PREFIX)) return void 0;
+  const rest = subcategory.slice(RUNTIME_SUBCATEGORY_PREFIX.length);
+  const separator = rest.indexOf(":");
+  const check = separator === -1 ? rest : rest.slice(0, separator);
+  return RENDER_CHECK_KINDS.find((kind) => kind === check);
+}
 function toEvalIssue(issue) {
   if (issue.outcome === "verified" || issue.outcome === "skipped") return null;
   const result = issue.outcome === "failed" ? "fail" : "warn";
@@ -15472,6 +15698,14 @@ function formatFitFeedback(issue) {
   Fix: ${issue.fix ?? ""}`;
 }
 var EVAL_ROUND_THREW_REASON = "eval round threw";
+var PROBE_ONLY_CRITERIA_REASON = "probe-only round: no evaluator configured";
+var PROBE_ONLY_VISUAL_REASON = "probe-only round: no visual evaluator configured";
+var PROBE_ONLY_PASS = "probe-only";
+var COST_TRACKER_ABSENT_REASON = "cost tracker absent on an evaluation round";
+function requireCostTracker(costTracker) {
+  if (costTracker === null) throw new Error(COST_TRACKER_ABSENT_REASON);
+  return costTracker;
+}
 function runVisualLeg(visualEvalAgent, run, measureFit) {
   const provider = visionJudgeProvider(visualEvalAgent.provider);
   if (provider === void 0) {
@@ -15514,6 +15748,36 @@ function fingerprintFail(issue) {
   const desc = (issue.description ?? "").toLowerCase().replace(/line\s+\d+/g, "line N").replace(/\s+/g, " ").trim().slice(0, 40);
   return `${cat}|${sub}|${desc}`;
 }
+function failedCheckKinds(probeIssues) {
+  const failed2 = /* @__PURE__ */ new Set();
+  for (const issue of probeIssues) {
+    if (issue.result !== "fail" || issue.subcategory === void 0) continue;
+    const kind = parseRuntimeSubcategory(issue.subcategory);
+    if (kind !== void 0) failed2.add(kind);
+  }
+  return RENDER_CHECK_KINDS.filter((kind) => failed2.has(kind));
+}
+function probeMetaOf(outcome, probeIssues) {
+  const detail = {
+    ...outcome.reason !== void 0 ? { reason: outcome.reason } : {},
+    ...outcome.renderMs !== void 0 ? { renderMs: outcome.renderMs } : {},
+    ...outcome.hostLoad !== void 0 ? { hostLoad: outcome.hostLoad } : {},
+    ...outcome.queuedMs !== void 0 ? { queuedMs: outcome.queuedMs } : {}
+  };
+  const elapsed = outcome.elapsedMs !== void 0 ? { elapsedMs: outcome.elapsedMs } : {};
+  if (outcome.status !== "ran") {
+    return { status: outcome.status, ...elapsed, ...detail };
+  }
+  const [first, ...rest] = failedCheckKinds(probeIssues);
+  if (first === void 0) {
+    return { status: "ran", verdict: "pass", ...elapsed, ...detail };
+  }
+  return { status: "ran", verdict: "fail", failChecks: [first, ...rest], ...elapsed, ...detail };
+}
+function describeProbeMeta(meta) {
+  if (meta.verdict === void 0) return meta.status;
+  return meta.verdict === "pass" ? "ran, verdict pass" : `ran, verdict fail (${meta.failChecks.join(", ")})`;
+}
 async function runProbeAtExit(input) {
   const { harness, sourceCode, compiledCode, contract, fixtureProps } = input;
   const probe = harness.check.runtimeRender;
@@ -15546,12 +15810,7 @@ async function runProbeAtExit(input) {
       meta: { status: "infra-skipped", reason: message }
     };
   }
-  const meta = {
-    status: outcome.status,
-    ...outcome.reason !== void 0 ? { reason: outcome.reason } : {},
-    ...outcome.elapsedMs !== void 0 ? { elapsedMs: outcome.elapsedMs } : {},
-    ...outcome.hostLoad !== void 0 ? { hostLoad: outcome.hostLoad } : {}
-  };
+  const meta = probeMetaOf(outcome, outcome.issues);
   if (outcome.status !== "ran") {
     return { fired: false, recoverableFail: false, probeIssues: [], meta };
   }
@@ -15594,11 +15853,13 @@ async function runEvalRound(ctx, input) {
     visualThreshold,
     qualityMode,
     maxEvalRounds,
-    costTracker,
     llmEvalMod,
     visualMod,
     preWarmPromise,
-    onProgress
+    onProgress,
+    probeOnly,
+    probeRepairUsed,
+    probeRepairTrigger
   } = ctx;
   const { compiledCode, prevModeSubcats, prevFailFingerprints } = input;
   let { evalRoundsUsed, preWarmedContext } = input;
@@ -15609,6 +15870,88 @@ async function runEvalRound(ctx, input) {
   let evalTokens = { input: 0, output: 0 };
   let evalLlmMs = 0;
   try {
+    if (probeOnly) {
+      const exitProbe = await runProbeAtExit({
+        harness,
+        sourceCode: currentSource,
+        compiledCode,
+        contract,
+        fixtureProps
+      });
+      const probeOnlyResult = {
+        issues: [...exitProbe.probeIssues],
+        pass: [PROBE_ONLY_PASS],
+        runtimeProbe: exitProbe.meta,
+        criteriaCoverage: notApplicableCoverage(PROBE_ONLY_CRITERIA_REASON),
+        visualCoverage: { status: "not-applicable", reason: PROBE_ONLY_VISUAL_REASON }
+      };
+      const recoverableFail = exitProbe.fired && exitProbe.recoverableFail;
+      if (probeRepairUsed) {
+        if (probeRepairTrigger === void 0) {
+          throw new Error("harness defect: a probe-only re-probe round without the probe that bought the repair turn");
+        }
+        const repair = { attempted: true, compiled: true, trigger: probeRepairTrigger };
+        evalResult = { ...probeOnlyResult, runtimeProbeRepair: repair };
+        console.log(
+          `[simple] eval round ${evalRoundsUsed}: probe-only re-probe after the repair turn \u2014 ${describeProbeMeta(exitProbe.meta)}${recoverableFail ? ", recoverable crash still present" : ""} \u2014 serving`
+        );
+        return {
+          control: "break",
+          evalDone: true,
+          evalResult,
+          evalRoundsUsed,
+          prevModeSubcats,
+          prevFailFingerprints,
+          preWarmedContext,
+          evalTokens,
+          evalLlmMs,
+          lastResultText: "",
+          isEvalFeedback: false,
+          lastDiffFailed: false
+        };
+      }
+      evalResult = probeOnlyResult;
+      if (recoverableFail) {
+        const runtimeFails = exitProbe.probeIssues.filter(
+          (i) => i.result === "fail" && i.subcategory?.startsWith("runtime:")
+        );
+        const lines = runtimeFails.slice(0, MAX_FEEDBACK_ISSUES).map(formatRuntimeProbeFeedback);
+        console.log(
+          `[simple] eval round ${evalRoundsUsed}: probe-only round \u2014 runtime probe fail (recoverable) \u2014 granting the one repair turn`
+        );
+        return {
+          control: "feedback",
+          evalDone: false,
+          evalResult,
+          evalRoundsUsed,
+          prevModeSubcats,
+          prevFailFingerprints,
+          preWarmedContext,
+          evalTokens,
+          evalLlmMs,
+          lastResultText: lines.join("\n\n"),
+          isEvalFeedback: true,
+          lastDiffFailed: false
+        };
+      }
+      console.log(
+        `[simple] eval round ${evalRoundsUsed}: probe-only round \u2014 probe ${describeProbeMeta(exitProbe.meta)} \u2014 serving`
+      );
+      return {
+        control: "break",
+        evalDone: true,
+        evalResult,
+        evalRoundsUsed,
+        prevModeSubcats,
+        prevFailFingerprints,
+        preWarmedContext,
+        evalTokens,
+        evalLlmMs,
+        lastResultText: "",
+        isEvalFeedback: false,
+        lastDiffFailed: false
+      };
+    }
     const checkResult = await runCheck({
       harness,
       sourceCode: currentSource,
@@ -15683,6 +16026,7 @@ async function runEvalRound(ctx, input) {
         lastDiffFailed: false
       };
     }
+    const costTracker = requireCostTracker(ctx.costTracker);
     if (evalRoundsUsed === 1 && !preWarmedContext && preWarmPromise) {
       preWarmedContext = await preWarmPromise;
     }
@@ -16168,6 +16512,8 @@ function createTelemetry() {
     totalIn: 0,
     totalOut: 0,
     evalResult: void 0,
+    probeRepairUsed: false,
+    probeRepairTrigger: void 0,
     contractFeedback: void 0,
     sameExchangeBreak: void 0,
     compiledCode: "",
@@ -16267,6 +16613,15 @@ function createGenerateTaskRunner(input) {
       absorbTurn(telemetry, turn);
       iconNamesCache = turn.iconNamesCache;
       preWarmedContext = turn.preWarmedContext;
+      if (turn.control !== "proceed" && session.probeOnlyEnabled && telemetry.probeRepairUsed) {
+        if (telemetry.evalResult !== void 0) {
+          telemetry.evalResult = { ...telemetry.evalResult, runtimeProbeRepair: { attempted: true, compiled: false } };
+        }
+        console.log(
+          `[simple] probe-only repair turn did not compile (${turn.outcome ?? "no tool call"}) \u2014 serving the pre-repair card`
+        );
+        break;
+      }
       if (turn.control === "break") break;
       if (turn.control === "continue") {
         lastResultText = turn.lastResultText;
@@ -16305,7 +16660,7 @@ function createGenerateTaskRunner(input) {
           `[simple] initial result delivered | ${codingDoneMs}ms | turns=${telemetry.turnsUsed} | tokens=${telemetry.totalIn + telemetry.totalOut} | compiled=${telemetry.compiledCode.length}B`
         );
       }
-      if (!evalDone && telemetry.compiledCode && session.tiersMod && (session.codeEvalEnabled || session.visualEvalEnabled)) {
+      if (!evalDone && telemetry.compiledCode && (session.tiersMod && (session.codeEvalEnabled || session.visualEvalEnabled) || session.probeOnlyEnabled)) {
         const evalRoundStart = Date.now();
         const round = await runEvalRound(
           {
@@ -16325,7 +16680,10 @@ function createGenerateTaskRunner(input) {
             llmEvalMod: session.llmEvalMod,
             visualMod: session.visualMod,
             preWarmPromise: session.preWarmPromise,
-            onProgress: params.onProgress
+            onProgress: params.onProgress,
+            probeOnly: session.probeOnlyEnabled,
+            probeRepairUsed: telemetry.probeRepairUsed,
+            ...telemetry.probeRepairTrigger !== void 0 ? { probeRepairTrigger: telemetry.probeRepairTrigger } : {}
           },
           {
             compiledCode: telemetry.compiledCode,
@@ -16346,6 +16704,10 @@ function createGenerateTaskRunner(input) {
         evalDone = round.evalDone;
         absorbTokens(telemetry, round.evalTokens);
         if (round.control === "break") break;
+        if (session.probeOnlyEnabled) {
+          telemetry.probeRepairUsed = true;
+          telemetry.probeRepairTrigger = round.evalResult?.runtimeProbe;
+        }
         lastResultText = round.lastResultText;
         isEvalFeedback = round.isEvalFeedback;
         lastDiffFailed = round.lastDiffFailed;
@@ -16353,6 +16715,9 @@ function createGenerateTaskRunner(input) {
         break;
       }
     } while (telemetry.turnsUsed < maxTurns && !evalDone);
+    if (session.probeOnlyEnabled && telemetry.probeRepairUsed && telemetry.evalResult !== void 0 && telemetry.evalResult.runtimeProbeRepair === void 0) {
+      console.log(`[simple] probe-only repair turn not taken \u2014 turn cap (${maxTurns}) reached before it`);
+    }
     telemetry.codingMs = Date.now() - telemetry.codingStartedAtMs;
     if (!telemetry.compiledCode) {
       for (const [, meta] of session.commitMeta) {
@@ -16579,6 +16944,7 @@ async function initSession(input) {
   const qualityMode = qualityConfig?.quality ?? "fast";
   const codeEvalEnabled = !!params.evaluation?.enabled;
   const visualEvalEnabled = !!(params.visualEvaluation?.enabled || qualityConfig?.visualEval);
+  const probeOnlyEnabled = harness.check.runtimeRender !== void 0 && !codeEvalEnabled && !visualEvalEnabled;
   const maxEvalRounds = qualityMode === "high-quality" ? params.evaluation?.maxRounds ?? 3 : params.evaluation?.maxRounds ?? 2;
   const visualThreshold = params.visualEvaluation?.passThreshold ?? 70;
   let tiersMod = null;
@@ -16609,6 +16975,7 @@ async function initSession(input) {
     systemPrompt,
     codeEvalEnabled,
     visualEvalEnabled,
+    probeOnlyEnabled,
     maxEvalRounds,
     visualThreshold,
     qualityMode,
@@ -16713,7 +17080,15 @@ async function dispatchGeneration(params) {
     // prompt's gadget catalog renders a `Type:` line per third-party
     // gadget (the LLM sees a wrapper's real call shape it otherwise
     // can't know).
-    systemPromptBuilder: ({ userRequest, shellType, screen, axisDelta, designMode, canvas, profile }) => buildSystemPrompt2(
+    systemPromptBuilder: ({
+      userRequest,
+      shellType,
+      screen,
+      axisDelta,
+      designMode,
+      canvas,
+      profile
+    }) => buildSystemPrompt2(
       userRequest,
       shellType,
       screen,
@@ -16729,14 +17104,14 @@ async function dispatchGeneration(params) {
     axisChecks: REGISTRY.filter(
       (check) => matches(classification.vector, check)
     ),
-    // The default runtime-render check. Heavy deps (happy-dom + wire +
-    // design) stay on the dispatch side of the boundary; the skeleton
-    // createHarness defaults this to undefined.
+    // The runtime-render check, built under the caller's probe config.
+    // Heavy deps (happy-dom + wire + design) stay on the dispatch side of
+    // the boundary; the skeleton createHarness defaults this to undefined.
     //
     // Gated behind `enableRuntimeRender` (default true) so
     // benchmark/dev callers can opt out of in-loop probe execution and
     // run the probe externally as a final post-generation check.
-    runtimeRender: params.enableRuntimeRender ?? true ? DEFAULT_RUNTIME_RENDER_CHECK : void 0
+    runtimeRender: params.enableRuntimeRender ?? true ? params.runtimeRender ?? DEFAULT_RUNTIME_RENDER_CHECK : void 0
   });
   console.log(
     `[harness] id=${harness.id} name=${harness.name} workflow=${harness.process.workflow.name} overrides=${harness.meta.overrides.join(",") || "none"}`
@@ -16754,67 +17129,70 @@ async function dispatchGeneration(params) {
     evaluationAgent
   });
   const { resolveRunPolicyForProfile: resolveRunPolicyForProfile2 } = await Promise.resolve().then(() => (init_policy2(), policy_exports));
-  const resolvedPolicy = resolveRunPolicyForProfile2(
-    process.env.GGUI_POLICY_PROFILE,
-    harness,
-    { provider: routerProvider, modelId: resolvedModel }
-  );
+  const resolvedPolicy = resolveRunPolicyForProfile2(process.env.GGUI_POLICY_PROFILE, harness, {
+    provider: routerProvider,
+    modelId: resolvedModel
+  });
   let systemPromptOverride;
   {
     const { PRIMITIVES_DOCUMENTATION: PRIMITIVES_DOCUMENTATION2 } = await Promise.resolve().then(() => (init_validation(), validation_exports));
     const fullBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION2, "utf8");
+    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
+    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
     const mode = resolvedPolicy.context.primitiveDocSlice ?? "full";
-    if (mode === "axis-keyed") {
-      const { computePrimitiveAllowlist: computePrimitiveAllowlist2, slicePrimitiveDocumentation: slicePrimitiveDocumentation2 } = await Promise.resolve().then(() => (init_primitive_slice(), primitive_slice_exports));
+    let doc = PRIMITIVES_DOCUMENTATION2;
+    if (docFormat === "ts" && indexMode === "off") {
+      const { PRIMITIVES_DOCUMENTATION_TS: PRIMITIVES_DOCUMENTATION_TS2 } = await Promise.resolve().then(() => (init_get_primitives_ts(), get_primitives_ts_exports));
+      doc = PRIMITIVES_DOCUMENTATION_TS2;
+      const tsBytes = Buffer.byteLength(doc, "utf8");
+      console.log(
+        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`
+      );
+    }
+    const formatBytes = Buffer.byteLength(doc, "utf8");
+    if (mode === "axis-keyed" || mode === "axis-keyed+contract") {
+      const {
+        computePrimitiveAllowlist: computePrimitiveAllowlist2,
+        computeContractPrimitives: computeContractPrimitives2,
+        slicePrimitiveDocumentation: slicePrimitiveDocumentation2,
+        slicePrimitiveDocumentationTs: slicePrimitiveDocumentationTs2
+      } = await Promise.resolve().then(() => (init_primitive_slice(), primitive_slice_exports));
       let allowlist = computePrimitiveAllowlist2(classification);
+      if (mode === "axis-keyed+contract") {
+        const fromContract = computeContractPrimitives2(effectiveContract);
+        allowlist = [.../* @__PURE__ */ new Set([...allowlist, ...fromContract])].sort();
+      }
       const excludes = resolvedPolicy.context.primitiveDocExcludes ?? [];
       if (excludes.length > 0) {
         const excludeSet = new Set(excludes);
         allowlist = allowlist.filter((p) => !excludeSet.has(p));
       }
-      const sliced = slicePrimitiveDocumentation2(
-        PRIMITIVES_DOCUMENTATION2,
-        allowlist
-      );
-      const slicedBytes = Buffer.byteLength(sliced, "utf8");
+      doc = docFormat === "ts" && indexMode === "off" ? slicePrimitiveDocumentationTs2(doc, allowlist) : slicePrimitiveDocumentation2(doc, allowlist);
+      const slicedBytes = Buffer.byteLength(doc, "utf8");
       const excludeTag = excludes.length ? ` excludes=${excludes.join(",")}` : "";
       console.log(
-        `[simple] primitive-doc-bytes=${slicedBytes} mode=axis-keyed baseline=${fullBytes} drop=${((1 - slicedBytes / fullBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`
-      );
-      systemPromptOverride = harness.how.systemPrompt.replace(
-        PRIMITIVES_DOCUMENTATION2,
-        sliced
+        `[simple] primitive-doc-bytes=${slicedBytes} mode=${mode} baseline=${formatBytes} drop=${((1 - slicedBytes / formatBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`
       );
     } else {
       console.log(
-        `[simple] primitive-doc-bytes=${fullBytes} mode=full baseline=${fullBytes} drop=0.0%`
+        `[simple] primitive-doc-bytes=${formatBytes} mode=full baseline=${formatBytes} drop=0.0%`
       );
     }
-    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
     if (indexMode !== "off") {
       const { buildPrimitiveIndex: buildPrimitiveIndex2 } = await Promise.resolve().then(() => (init_primitive_index(), primitive_index_exports));
-      const index = buildPrimitiveIndex2(PRIMITIVES_DOCUMENTATION2, indexMode);
-      const indexBytes = Buffer.byteLength(index, "utf8");
+      doc = buildPrimitiveIndex2(PRIMITIVES_DOCUMENTATION2, indexMode);
+      const indexBytes = Buffer.byteLength(doc, "utf8");
       console.log(
         `[simple] primitive-index-bytes=${indexBytes} mode=${indexMode} baseline=${fullBytes} drop=${((1 - indexBytes / fullBytes) * 100).toFixed(1)}%`
       );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION2,
-        index
-      );
     }
-    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
-    if (docFormat === "ts" && indexMode === "off") {
-      const { PRIMITIVES_DOCUMENTATION_TS: PRIMITIVES_DOCUMENTATION_TS2 } = await Promise.resolve().then(() => (init_get_primitives_ts(), get_primitives_ts_exports));
-      const tsBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION_TS2, "utf8");
-      console.log(
-        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`
-      );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION2,
-        PRIMITIVES_DOCUMENTATION_TS2
-      );
+    if (doc !== PRIMITIVES_DOCUMENTATION2) {
+      systemPromptOverride = harness.how.systemPrompt.replace(PRIMITIVES_DOCUMENTATION2, doc);
     }
+    const sentPrompt = systemPromptOverride ?? harness.how.systemPrompt;
+    console.log(
+      `[simple] system-prompt-bytes=${Buffer.byteLength(sentPrompt, "utf8")} doc-format=${docFormat === "ts" && indexMode === "off" ? "ts" : docFormat} doc-bytes=${Buffer.byteLength(doc, "utf8")} mode=${indexMode !== "off" ? `index:${indexMode}` : mode}`
+    );
     if (resolvedPolicy.context.planFirstTurn) {
       const phaseGuidance = `
 
@@ -16866,7 +17244,11 @@ Your plan is a commitment, not a design doc. Keep it tight. Do not over-plan; ju
     );
   }
   const finalSource = runResult.finalSource ?? "";
-  const result = await assembleGenerationResult({ session, telemetry, source: finalSource });
+  const result = await assembleGenerationResult({
+    session,
+    telemetry,
+    source: finalSource
+  });
   return withArmRecord(result, params);
 }
 function withArmRecord(result, params) {