@ggui-ai/ui-gen 0.24.0 → 0.25.0

package/dist/adapters/generation-dispatch.js

@@ -1,7 +1,7 @@
 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';
+import { EXPANDED_FRAME, getCssTokens, expandedFrameScrimDecls, fillFitRule, expandedFramePanelRule, FORBIDDEN_IMPORT_SPECIFIERS } from '@ggui-ai/design/rendering';
 import * as esbuild from 'esbuild';
 import { build } from 'esbuild';
 import fs, { existsSync, mkdtempSync, writeFileSync, rmSync, readFileSync, readdirSync, statSync } from 'fs';
@@ -15,6 +15,7 @@ import path, { dirname, resolve, relative } from 'path';
 import { Linter } from 'eslint';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import { createHash } from 'crypto';
+import { inflateSync } from 'zlib';
 import { LUCIDE_ICON_NAMES, maxWidth } from '@ggui-ai/design';
 import { primeInputs } from '@ggui-ai/ui-visual-tester/prime-inputs';
 import git from 'isomorphic-git';
@@ -2834,7 +2835,7 @@ var init_policy2 = __esm({
 var PRIMITIVES_DOCUMENTATION, VALID_PRIMITIVES;
 var init_primitives = __esm({
   "src/validation/primitives.ts"() {
-    PRIMITIVES_DOCUMENTATION = "# ggui Primitives & Design System Reference\n\n> You are a world-class UI engineer working with ggui's component library for the first time.\n> This reference documents every available component, prop, and convention.\n> Components handle theming automatically via built-in variants \u2014 pick the right variant and the theme does the rest.\n> For custom styling beyond variants, use CSS variables: var(--ggui-*, fallback).\n\n## Primitives\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Container\n\nContainer -- Width-constrained wrapper that centers content horizontally.\n\nRenders a `<div>` with `width: 100%` and a `maxWidth` constraint.\nWhen `center` is true (the default), applies `margin: 0 auto`.\nNo background, border, or shadow -- use Card for visual containment.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| maxWidth | `'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| 'full' \\| string` | `'lg'` | Maximum width constraint. Accepts a preset token or any CSS width string. - `'xs'` -- 320px - `'sm'` -- 480px - `'md'` -- 640px - `'lg'` -- 768px - `'xl'` -- 1024px - `'2xl'` -- 1280px - `'3xl'` -- 1536px - `'full'` -- 100%  Custom strings (e.g., `'900px'`, `'60ch'`) are passed through as-is. |\n| center | `boolean` | `true` | Whether to center the container horizontally via `margin: 0 auto`. |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n```\n\n### Card\n\nCard -- Container with background, shadow, and optional border.\n\nRenders a `<div>` with:\n- Background: `var(--ggui-color-container)`\n- Border (when enabled): `1px solid var(--ggui-color-outlineVariant)`\n- Shadow and radius controlled by design tokens via CSS variables.\n- No built-in transitions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'lg'` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| shadow | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'sm'` | Shadow elevation level. Maps to design tokens: - `'none'` -- no shadow - `'sm'` -- var(--ggui-shape-shadow-sm) -- subtle, default - `'md'` -- var(--ggui-shape-shadow-md) -- dialogs, emphasized sections - `'lg'` -- var(--ggui-shape-shadow-lg) -- floating panels - `'xl'` -- var(--ggui-shape-shadow-xl) -- popovers, modals |\n| border | `boolean` | `true` | Whether to render a 1px border using `var(--ggui-color-outlineVariant)`. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'lg'` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `'default'` | Semantic surface slot. Same vocabulary as ; see that prop's docs for the full slot table. Default Card surface is `'default'` (the active theme's `--ggui-color-container`); pair with `shadow=\"md\"\\|\"lg\"` for elevated cards, `'hero'` for a greeting or hero card (the theme's hero ground, right on a light or a dark host), or `'inverted'` for a dark testimonial-style card on a light theme. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n\n**Example:**\n```tsx\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n```\n\n### Stack\n\nStack -- Flexbox layout primitive for arranging children along a single axis.\n\nRenders a `<div>` with `display: flex`. Default layout is vertical (column).\nAll flex shorthand values (`align`, `justify`, `wrap`) are abstracted into\nsemantic prop names.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Main axis direction. - `'vertical'` -- `flex-direction: column` - `'horizontal'` -- `flex-direction: row` |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'sm'` | Gap between children. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| align | `'start' \\| 'center' \\| 'end' \\| 'stretch'` | `'stretch'` | Cross-axis alignment (maps to `align-items`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'stretch'` -- stretch (children fill cross-axis) |\n| justify | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'` | Main-axis content distribution (maps to `justify-content`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'between'` -- space-between - `'around'` -- space-around - `'evenly'` -- space-evenly |\n| wrap | `boolean` | `false` | Whether children wrap to the next line when they overflow. Maps to `flex-wrap: wrap` when true. |\n\n**Example:**\n```tsx\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n```\n\n### Grid\n\nGrid -- 2-D layout primitive. Arranges children into rows AND\ncolumns; reach for it when Stack/Row's single-axis flow isn't\nenough (card galleries, dashboards, stat grids).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| columns | `number \\| ResponsiveColumns` | `2` | Column count. Three forms: - a number \u2014 that many equal columns at every width (`columns={3}`); - a  map \u2014 explicit counts per breakpoint   (`columns={{ base: 1, md: 3 }}` = 1 column on mobile, 3 from `md`).   Use this when the request names exact per-breakpoint counts   (\"3 per row on desktop, 1 on mobile\"). Ignored entirely when `minColumnWidth` is set. |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'md'` | Gap between cells. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`); a number is pixels. |\n| minColumnWidth | `number \\| string` | `undefined (use `columns`)` | When set, the grid becomes responsive \u2014 it fits as many equal columns as possible, each at least this wide, and `columns` is ignored. A number is treated as pixels. |\n\n**Example:**\n```tsx\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n```\n\n### Skeleton\n\nSkeleton -- a pulsing placeholder for content that has not loaded\nyet. ggui UIs are agent-driven (props arrive late, streams start\nempty), so a loading frame is the rule \u2014 render `Skeleton` instead\nof a blank screen or a hand-rolled pulsing `<div>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| variant | `'rect' \\| 'text' \\| 'circle'` | `'rect'` | Shape preset. - `'rect'` -- a block (default); pair with `width` / `height`. - `'text'` -- a single text line (height ~1em). - `'circle'` -- equal width/height, fully rounded (avatar slot). |\n| width | `number \\| string` | - | Width. A number is pixels. Defaults to `100%` (`2.5rem` for circle). |\n| height | `number \\| string` | - | Height. A number is pixels. Defaults by variant when unset. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'sm'` | Corner radius. Prefer a radius-scale name. Ignored for `variant=\"circle\"` (always fully round). |\n\n**Example:**\n```tsx\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n```\n\n### Box\n\nBox -- Generic container with padding, margin, background, and border-radius.\n\nRenders a plain `<div>`. Unlike Card, Box has no default background, shadow,\nor border -- it is a blank canvas for custom styling. Use it for layout\nspacing, colored sections, or wrapping arbitrary content.\n\nWhen both `paddingX`/`paddingY` and `padding` are provided, the axis-specific\nprops take precedence and `padding` is ignored.\n\nCSS variables used: none (all values are passed through directly).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all four sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. Ignored when `paddingX` or `paddingY` is set. |\n| paddingX | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Horizontal (left + right) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingY`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingY`, vertical padding defaults to 0. |\n| paddingY | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Vertical (top + bottom) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingX`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingX`, horizontal padding defaults to 0. |\n| margin | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no margin)` | Margin applied to all four sides. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `undefined (transparent)` | Semantic surface slot. Picks the right `var(--ggui-color-*)` background token from the active theme. The ONLY way to set a theme-tracking background fill on Box.  Available slots: - `'default'` \u2014 base container surface (most common) - `'elevated'` \u2014 same fill, intended to be paired with shadow   (use Card.shadow for actual elevation) - `'sunken'` \u2014 recessed / inset region (`surfaceVariant` token) - `'accent'` \u2014 highlighted / branded fill (`primary-50` token) - `'inverted'` \u2014 dark surface in light mode, light in dark   (testimonials, code-snippet cards, hero panels). The surface owns   ALL its inks: body text, `muted` / `subtle` labels, chips and   outlines inside it re-map to inverse-derived values by cascade \u2014   no `tone=\"inverse\"` needed, and no hand-picked greys. - `'hero'` \u2014 the hero panel's ground: brand-tinted on a light host, the   ink pair on a dark one (`heroGround` / `onHeroGround`, derived per mode)   \u2014 reach for it for a greeting or hero card instead of guessing the   host's darkness with `'inverted'`; it owns its subtree's inks likewise. - `'transparent'` \u2014 explicit \"no fill\"  For non-theme-mapped brand colors (e.g. a partner's exact brand hex like Stripe purple) use the  escape \u2014 every other hex / rgba on Box is rejected by tier-0 self-check. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n| assetColor | `string` | `undefined` | Asset color escape \u2014 the typed valve for legitimate non-theme color values (a partner's exact brand hex, a fixed product surface, etc.). Renders as the Box background.  **MUST be paired with .** The semantic name is human-readable documentation of why this color bypasses the theme \u2014 e.g. `\"stripe-brand-purple\"`, `\"slack-aubergine\"`. Tier-0 self-check allows hex / rgba inside `assetColor` ONLY when `assetSemantic` is a non-empty string; one without the other fails the check.  Reach for `surface` first. This escape exists for the small set of cases where the operator's theme MUST NOT override the value (brand identity rendering). |\n| assetSemantic | `string` | `undefined` | Human-readable semantic label that documents why  bypasses the theme. Required when `assetColor` is set; tier-0 self-check rejects empty strings or a missing `assetSemantic` next to a hex `assetColor`.  Examples: `\"stripe-brand-purple\"`, `\"slack-aubergine\"`, `\"partner-logo-orange\"`. Pure documentation \u2014 no rendering effect. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `undefined (no rounding)` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n```\n\n### Divider\n\nDivider -- A 1px line to visually separate content sections.\n\nRenders an `<hr>` (horizontal) or `<div>` (vertical) with `role=\"separator\"`.\n- Horizontal: 1px tall, full width, with vertical margin.\n- Vertical: 1px wide, stretches to parent height via `align-self: stretch`,\n  with horizontal margin. Works best inside a horizontal Stack or Row.\n\nDefault color: `var(--ggui-color-outlineVariant)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Line direction. - `'horizontal'` -- renders `<hr>`, full width, 1px height, margin top/bottom - `'vertical'` -- renders `<div>`, 1px width, `align-self: stretch`, margin left/right |\n| margin | `number \\| string` | `16` | Spacing around the divider. Numbers are treated as pixels. Applied as vertical margin for horizontal dividers, horizontal margin for vertical. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-outlineVariant)`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a quiet outline-variant tint when unset (independent of the tone slots). |\n\n**Example:**\n```tsx\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n```\n\n### Spacer\n\nSpacer -- Invisible spacing element, either fixed-size or flexible.\n\nRenders an empty `<div>`.\n- Fixed mode (number): sets both `width` and `height` to the given pixel\n  value with `flex-shrink: 0`, creating rigid spacing in any direction.\n- Flex mode (`'flex'`): sets `flex: 1`, expanding to fill remaining space\n  in a flex container. Useful for pushing siblings apart.\n\nCSS variables used: none.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number \\| 'flex'` | `16` | Spacing amount. - Number: fixed square spacer (width and height in pixels, `flex-shrink: 0`). - `'flex'`: expands to fill available space (`flex: 1`). |\n\n**Example:**\n```tsx\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n```\n\n### Text\n\nText -- Versatile typography primitive for body copy, captions, and labels.\n\nRenders as `<p>` by default (configurable via `is`). Typography is\ncomposed from three orthogonal axes: `size` (font size, with a\nmatching line-height built in), `weight`, and `tone` (semantic\ncolor). `caps` adds the uppercase, letter-spaced treatment for tiny\nsection labels (the classic overline/eyebrow look) \u2014 the label's text\ncomes from a prop, never from the component: an invented eyebrow is copy\nnothing can change.\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll text renders with `margin: 0` (no default paragraph spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| size | `'xs' \\| 'sm' \\| 'base' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| '4xl'` | `'base'` | Font size. Maps to CSS variables with pixel fallbacks; each size carries a matching line-height (1.5 for `xs`--`base`, 1.625 for `lg`, then tightening on display sizes: 1.375 at `xl`, 1.25 from `2xl` up): - `'xs'` -- var(--ggui-font-size-xs) (12px) - `'sm'` -- var(--ggui-font-size-sm) (14px) - `'base'` -- var(--ggui-font-size-base) (16px) - `'lg'` -- var(--ggui-font-size-lg) (18px) - `'xl'` -- var(--ggui-font-size-xl) (20px) - `'2xl'` -- var(--ggui-font-size-2xl) (24px) - `'3xl'` -- var(--ggui-font-size-3xl) (30px) - `'4xl'` -- var(--ggui-font-size-4xl) (36px) |\n| weight | `'normal' \\| 'medium' \\| 'semibold' \\| 'bold'` | `'normal'` | Font weight. Maps to CSS variables with numeric fallbacks: - `'normal'` -- var(--ggui-font-weight-normal) - `'medium'` -- var(--ggui-font-weight-medium) - `'semibold'` -- var(--ggui-font-weight-semibold) - `'bold'` -- var(--ggui-font-weight-bold) |\n| caps | `boolean` | `false` | When true, uppercases the text and adds 0.05em letter-spacing -- the eyebrow/overline treatment for tiny section labels. Pair with `size=\"xs\" weight=\"semibold\" tone=\"muted\"`. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Picks the right `var(--ggui-color-*)` token from the active theme. The theme decides what each tone LOOKS like \u2014 `'muted'` is a quiet warm grey on Claudic, a cool slate on Indigo, dim cyan on Neon-Noir. Components that use `tone` track the operator's theme switch automatically.  Available slots: `'default'` (primary body text), `'muted'` (secondary / metadata), `'subtle'` (very-low-emphasis hint), `'emphasized'` (branded accent), `'loud'` (strongest accent \u2014 the theme's readable accent ink), `'success'` / `'warning'` / `'error'` / `'info'` (status text), `'inverse'` (text on dark surface), `'inherit'` (parent's color).  `tone` is the ONLY way to set a Text color. The legacy `color?: string` escape was retired \u2014 raw color strings bypass theming and silently override the operator's preset. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n| truncate | `boolean` | `false` | When true, clips overflowing text with an ellipsis. Applies `overflow: hidden`, `text-overflow: ellipsis`, and `white-space: nowrap`. |\n| is | `'p' \\| 'span' \\| 'div' \\| 'label'` | `'p'` | HTML element to render. Choose based on semantic context: - `'p'` -- paragraph (default, block-level) - `'span'` -- inline text within a sentence - `'div'` -- generic block container - `'label'` -- form label (pair with `htmlFor`) |\n| id | `string` | - | `id` for the rendered element \u2014 anchor an in-page link, or pair with a form control's `aria-labelledby`. |\n| htmlFor | `string` | - | Associates an `is=\"label\"` element with a form control by the control's `id`. Only meaningful when `is=\"label\"`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">{props.section}</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n```\n\n### Heading\n\nHeading -- Semantic heading element (h1-h6) with preset typography styles.\n\nRenders the corresponding `<h1>`-`<h6>` HTML element based on `level`.\nEach level has a preset font size, weight, line height, and letter spacing\nfrom the heading typography tokens:\n- Level 1: 36px / bold / 1.25 line-height / -0.025em tracking\n- Level 2: 30px / bold / 1.25 line-height / -0.025em tracking\n- Level 3: 24px / semibold / 1.375 line-height / 0em tracking\n- Level 4: 20px / semibold / 1.375 line-height / 0em tracking\n- Level 5: 18px / semibold / 1.5 line-height / 0em tracking\n- Level 6: 16px / semibold / 1.5 line-height / 0em tracking\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll headings render with `margin: 0` (no default heading spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| level | `1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6` | `2` | Semantic heading level. Determines both the HTML element (`<h1>`-`<h6>`) and the preset typography style. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Same vocabulary as ; see that prop's docs for the full slot table. `tone` is the ONLY way to set a Heading color \u2014 the legacy `color?: string` escape was retired so the operator's theme always wins. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n```\n\n### Button\n\nButton -- A clickable button primitive with multiple visual variants and sizes.\n\nRenders a native `<button>` element styled with inline CSS derived from design-token\nCSS variables. Supports a loading spinner, left/right icon slots, and a cross-platform\n`onPress` alias for `onClick`.\n\nBase styles applied to every variant:\n- `border-radius: var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- `font-weight: var(--ggui-font-weight-medium)`\n- `box-shadow: var(--ggui-shape-shadow-sm)`\n- `gap: var(--ggui-spacing-2)` between icon and text\n- Transitions: background-color, box-shadow, opacity at 200ms ease-in-out\n\nDisabled or loading: `opacity: 0.5`, `cursor: not-allowed`, click handler suppressed.\n\nAlso extends native `ButtonHTMLAttributes` (except `style`/`className`), so props\nlike `type`, `form`, `aria-*`, and `data-*` are forwarded to the `<button>` element.\nThe `type` prop defaults to `'button'` (not `'submit'`), preventing accidental form\nsubmissions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'primary' \\| 'secondary' \\| 'outline' \\| 'ghost' \\| 'danger'` | `'primary'` | Visual style. Maps to CSS variables: - `'primary'` -- `var(--ggui-color-primary-600)` background, white text, no border - `'secondary'` -- `var(--ggui-color-sunken)` background, `var(--ggui-color-onSunken)` text, no border - `'outline'` -- transparent background, `1px solid var(--ggui-color-primary-600)` border, label in the surface's   on-colour (`onContainer`) so it reads on any ground \u2014 the brand shows on the border, never as label ink on a dark theme - `'ghost'` -- transparent background, `var(--ggui-color-onSunken)` text, no border - `'danger'` -- `var(--ggui-color-error-600)` background, white text, no border |\n| size | `'xs' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and minimum height: - `'xs'` -- padding `4px 8px`, font `var(--ggui-font-size-xs)`, min-height 24px - `'sm'` -- padding `6px 12px`, font `var(--ggui-font-size-sm)`, min-height 32px - `'md'` -- padding `10px 16px`, font `var(--ggui-font-size-sm)`, min-height 40px - `'lg'` -- padding `12px 24px`, font `var(--ggui-font-size-base)`, min-height 48px |\n| fullWidth | `boolean` | `false` | When true, sets `width: 100%` so the button fills its container. |\n| loading | `boolean` | `false` | When true, replaces children with a 16px `Spinner` (color: `currentColor`) and disables interaction (same effect as `disabled`). |\n| leftIcon | `ReactNode` | - | ReactNode rendered before children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| rightIcon | `ReactNode` | - | ReactNode rendered after children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| onPress | `() => void` | - | Alias for `onClick` for cross-platform compatibility (React Native convention). If both `onClick` and `onPress` are provided, `onClick` takes precedence. |\n\n**Example:**\n```tsx\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n```\n\n### Input\n\nInput -- A single-line text input with label, validation, and helper text.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<input>`,\nand an optional message `<span>` for error or helper text.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)`\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n  `var(--ggui-color-onSunken)`\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<input>` via `htmlFor`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\nWhen `required` is true, a red asterisk is appended to the label.\n\nAlso extends native `InputHTMLAttributes` (except `style`, `className`, `onChange`,\n`size`), so props like `autoFocus`, `name`, `pattern`, `aria-*` are forwarded.\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<input>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the input. Linked to the input via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the input is empty. |\n| value | `string` | - | Controlled value of the input. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| type | `'text' \\| 'email' \\| 'password' \\| 'number' \\| 'tel' \\| 'url' \\| 'search' \\| 'date' \\| 'time' \\| 'datetime-local'` | `'text'` | HTML input type. Determines browser behavior (keyboard on mobile, validation, masking). The date/time types render the browser's native, localized, keyboard-accessible picker; their `value` stays an ISO string (`'2026-07-29'`, `'14:30'`, `'2026-07-29T14:30'`) delivered through the usual value-first `onChange`. |\n| error | `string` | - | Error message displayed below the input in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the input in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<input>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n```\n\n### TextArea\n\nTextArea -- A multiline text input with label, validation, character count, and auto-resize.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<textarea>`,\nand a footer row with error/helper text on the left and character count on the right.\n\nStyling:\n- Padding: `10px 12px`, font: `var(--ggui-font-size-sm)`, `font-family: inherit`\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Resize: `vertical` by default, `none` when `autoResize` is true\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: same label/error linking pattern as Input (auto-generated ids,\n`aria-invalid`, `role=\"alert\"` on error message).\n\nAlso extends native `TextareaHTMLAttributes` (except `style`, `className`, `onChange`).\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<textarea>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the textarea. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the textarea is empty. |\n| value | `string` | - | Controlled value of the textarea. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| rows | `number` | `4` | Number of visible text rows (native `rows` attribute on `<textarea>`). |\n| error | `string` | - | Error message displayed below the textarea in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the textarea in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<textarea>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| maxLength | `number` | - | Maximum character length (native `maxLength` attribute). Also used as the denominator in the character count display when `showCount` is true. |\n| showCount | `boolean` | `false` | When true AND `maxLength` is set, displays a `{current}/{max}` character counter in the footer row (right-aligned, `var(--ggui-font-size-xs)`). Has no effect without `maxLength`. |\n| autoResize | `boolean` | `false` | When true, sets CSS `resize: none` on the textarea. The flag disables manual resizing to signal that external logic handles sizing. The component does NOT auto-adjust height based on content in the current implementation. |\n\n**Example:**\n```tsx\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n```\n\n### Select\n\nSelect -- A native dropdown selection primitive with label and validation.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<select>`\nwith custom styling, and an optional message `<span>`.\n\nThe native `<select>` has `appearance: none` with a custom chevron SVG rendered\nas a `background-image` (right-aligned, 12px, onSurfaceVariant color). Extra right\npadding (36px) accommodates the chevron.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)` when a value is selected,\n  `var(--ggui-color-onSunken)` when showing placeholder\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Cursor: `pointer` (normal), `not-allowed` (disabled)\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<select>`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\n\nAlso extends native `SelectHTMLAttributes` (except `style`, `className`,\n`onChange`, `size`).\n\n**IMPORTANT:** `onChange` receives the selected value string directly, NOT a\nReact `ChangeEvent`. This differs from native `<select>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the select. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of the `options[].value` strings. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the selected option's value string directly, NOT a React event. |\n| options | `SelectOption[]` | - | Array of selectable options. Rendered as native `<option>` elements. Must contain at least one option (or use `placeholder` for an empty-state prompt). |\n| placeholder | `string` | - | Placeholder text rendered as a disabled `<option value=\"\">` at the top of the list. Shown when no value is selected. |\n| error | `string` | - | Error message displayed below the select in `var(--ggui-color-error-500)`. When set, the border turns red and the message has `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the select in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)` and cursor becomes `not-allowed`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n```\n\n### Checkbox\n\nCheckbox -- A custom-styled checkbox with label and description.\n\nRenders a `<label>` wrapper containing a visually-hidden native `<input type=\"checkbox\">`\noverlaid by a custom 18x18px visual box. Supports checked, unchecked, and indeterminate\nstates, each with a distinct SVG icon (checkmark or horizontal dash).\n\nStyling:\n- Box border: `2px solid var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-outline)` (unchecked)\n- Box fill: `var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-container)` (unchecked)\n- Check/dash icon: white SVG, 12x12px\n- Box radius: `var(--ggui-shape-radius-sm)`\n- Transition: all 0.2s\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`\n- Description: `var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`\n- Gap between box and text: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the boolean checked state directly, NOT a\nReact `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary label text rendered beside the checkbox box. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean checked state directly, NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5` and `cursor: not-allowed`. The native input is also disabled, preventing keyboard and click interaction. |\n| description | `string` | - | Secondary description text rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| indeterminate | `boolean` | `false` | When true, displays a horizontal dash instead of a checkmark. Used for \"select all\" states where some (but not all) children are checked. The `indeterminate` property is set via a ref on the native `<input>`. Visually identical to `checked` in terms of border and fill color. |\n\n**Example:**\n```tsx\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n```\n\n### Toggle\n\nToggle -- A switch/toggle input rendered as a pill-shaped track with a sliding knob.\n\nRenders a `<label>` wrapper with a `<div role=\"switch\">` track and an animated\ncircular knob. Does NOT use a native `<input>` -- keyboard interaction is handled\nmanually (Space and Enter keys toggle the state). The element is focusable via\n`tabIndex={0}` and shows a focus ring on focus.\n\nStyling:\n- Track (on): `var(--ggui-color-primary-600)`\n- Track (off): `var(--ggui-color-outline)`\n- Knob: white circle with `var(--ggui-shape-shadow-sm)`\n- Focus ring: `0 0 0 3px var(--ggui-color-primary-200)`\n- Transitions: background-color, box-shadow, knob position at 200ms ease-in-out\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`, `tabIndex: -1`\n- Gap between toggle and label: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the new boolean state directly (inverted from\ncurrent), NOT a React event.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label text rendered to the right of the toggle track. Also used as `aria-label` on the switch element. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked (on/off) state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean state directly (i.e., `!checked`), NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5`, `cursor: not-allowed`, and removes the element from tab order (`tabIndex: -1`). Click and keyboard handlers are suppressed. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track and knob dimensions: - `'sm'` -- track 36x20px, knob 16px diameter - `'md'` -- track 44x24px, knob 20px diameter - `'lg'` -- track 52x28px, knob 24px diameter |\n\n**Example:**\n```tsx\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n```\n\n### RadioGroup\n\nRadioGroup -- A group of mutually exclusive radio options with optional label and error.\n\nRenders a `<div role=\"radiogroup\">` containing a label span, a flex container of\nradio options, and an optional error message. Each option is a `<label>` with a\nvisually-hidden native `<input type=\"radio\">` and a custom 18px circle indicator.\n\nStyling:\n- Selected circle: `2px solid var(--ggui-color-primary-600)` border with\n  an 8px `var(--ggui-color-primary-600)` filled inner dot\n- Unselected circle: `2px solid var(--ggui-color-outline)` border,\n  `var(--ggui-color-container)` fill\n- Circle radius: `var(--ggui-shape-radius-full)`\n- Transition: all 0.2s\n- Vertical gap: `var(--ggui-spacing-2)`, horizontal gap: `var(--ggui-spacing-4)`\n- Error: `var(--ggui-font-size-xs)`, `var(--ggui-color-error-500)`,\n  `role=\"alert\"`\n- Disabled options: `opacity: 0.5`, `cursor: not-allowed`\n\nAccessibility: the group has `role=\"radiogroup\"` with `aria-labelledby` pointing\nto the label and `aria-describedby` pointing to the error message (when present).\nAll radio inputs share a common auto-generated `name` attribute.\n\n**IMPORTANT:** `onChange` receives the selected option's value string directly,\nNOT a React `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Group label rendered above the options. Used as `aria-labelledby` target on the `role=\"radiogroup\"` container. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of `options[].value`. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the newly selected option's value string directly, NOT a React event. |\n| options | `RadioOption[]` | - | Array of radio options. Must contain at least two options for meaningful selection. |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Layout direction for the options container: - `'vertical'` -- column layout, `var(--ggui-spacing-2)` gap - `'horizontal'` -- row layout with `flex-wrap: wrap`, `var(--ggui-spacing-4)` gap |\n| disabled | `boolean` | `false` | When true, disables ALL options (individual `RadioOption.disabled` is additive). Each option gets `opacity: 0.5` and `cursor: not-allowed`. |\n| error | `string` | - | Error message displayed below all options in `var(--ggui-color-error-500)` with `role=\"alert\"`. Linked to the radiogroup via `aria-describedby`. |\n\n**Example:**\n```tsx\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n```\n\n### Slider\n\nSlider -- A range input with a custom-styled track, fill, and thumb.\n\nRenders a `<div>` wrapper containing an optional label/value header, and a\ntrack area with three layers: background track, colored fill, and a circular\nthumb. A native `<input type=\"range\">` is overlaid with `opacity: 0` to\nprovide accessible keyboard and pointer interaction.\n\nStyling:\n- Track: 6px tall, `var(--ggui-color-outlineVariant)` background, `border-radius: 3px`\n- Fill: `var(--ggui-color-primary-600)` (normal),\n  `var(--ggui-color-outline)` (disabled)\n- Thumb: 20px white circle with `2px solid var(--ggui-color-primary-600)`,\n  `var(--ggui-shape-shadow-sm)`; disabled border uses outline\n- Value display (when `showValue`): `var(--ggui-color-primary-600)`,\n  `var(--ggui-font-size-sm)`, right-aligned in the header row\n- Fill and thumb transitions: 0.1s for smooth dragging\n\nAccessibility: the native `<input type=\"range\">` carries `aria-valuenow`,\n`aria-valuemin`, `aria-valuemax`, and is linked to the label via `aria-labelledby`.\nFalls back to `aria-label=\"Slider\"` when no label is provided.\n\n**IMPORTANT:** `onChange` receives the numeric value directly, NOT a React\n`ChangeEvent`. The value is coerced via `Number(e.target.value)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the slider track (left-aligned). Used as `aria-labelledby` target on the native range input. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `number` | `0` | Controlled numeric value. Must be between `min` and `max`. |\n| onChange | `(value: number) => void` | - | Change handler. Receives the new numeric value directly, NOT a React event. |\n| min | `number` | `0` | Minimum allowed value. |\n| max | `number` | `100` | Maximum allowed value. |\n| step | `number` | `1` | Step increment for the slider. Determines the granularity of selectable values. |\n| disabled | `boolean` | `false` | When true, sets `cursor: not-allowed` on the native input. The fill color changes to `var(--ggui-color-outline)` and the thumb border also uses outline. |\n| showValue | `boolean` | `false` | When true, displays the current numeric value right-aligned in the header row (beside the label) in `var(--ggui-color-primary-600)`. |\n\n**Example:**\n```tsx\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n```\n\n### Badge\n\nBadge -- Inline label for status indicators, counts, or categories.\n\nRenders a `<span>` with `display: inline-flex`, centered content, and\n`white-space: nowrap`. Semantic variant colors use background/text pairings\nfrom the 100/700 color scale. Pill shape uses `border-radius: 9999px`;\nnon-pill uses `var(--ggui-shape-radius-sm)`.\n\nFont weight: `var(--ggui-font-weight-medium)` across all variants.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'default' \\| 'primary' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info' \\| 'tertiary'` | `'default'` | Visual style. Maps to background/text color pairings: - `'default'` -- bg `var(--ggui-color-sunken)`, text `var(--ggui-color-onSunken)` - `'primary'` -- bg `var(--ggui-color-primary-100)`, text `var(--ggui-color-primary-700)` - `'secondary'` -- bg `var(--ggui-color-outlineVariant)`, text `var(--ggui-color-onContainer)` - `'success'` -- bg `var(--ggui-color-success-100)`, text `var(--ggui-color-success-700)` - `'warning'` -- bg `var(--ggui-color-warning-100)`, text `var(--ggui-color-warning-700)` - `'error'` -- bg `var(--ggui-color-error-100)`, text `var(--ggui-color-error-700)` - `'info'` -- bg `var(--ggui-color-info-100)`, text `var(--ggui-color-info-700)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `2px 6px`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `2px 8px`, font `var(--ggui-font-size-xs)` - `'lg'` -- padding `4px 10px`, font `var(--ggui-font-size-sm)` |\n| pill | `boolean` | `true` | When true, uses fully rounded corners (`border-radius: 9999px`). When false, uses `var(--ggui-shape-radius-sm)`. |\n\n**Example:**\n```tsx\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n```\n\n### Spinner\n\nSpinner -- Animated SVG loading indicator.\n\nRenders an `<svg>` with `role=\"status\"` and `aria-label=\"Loading\"`.\nThe SVG contains a full outlineVariant background circle and a quarter-arc\nforeground stroke in the spinner color.\n\nAnimation: `ggui-spin 1s linear infinite` (360-degree rotation).\nThe `@keyframes ggui-spin` definition is injected inline via a `<style>` tag.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number` | `24` | Width and height of the SVG element in pixels. The internal viewBox is always `0 0 24 24`, so this controls rendered size only. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the animated foreground arc. Same vocabulary as ; the theme decides the resolved value. The background circle always uses `var(--ggui-color-outlineVariant)`.  Use `'inherit'` when the spinner sits inside a colored container (e.g. inside a Button) \u2014 the stroke picks up `currentColor` from the parent so it tracks the container's foreground. |\n\n**Example:**\n```tsx\n<Spinner size={32} tone=\"success\" />\n```\n\n### Avatar\n\nAvatar -- User or entity representation with image or auto-generated initials.\n\nRenders a `<div role=\"img\">` with `overflow: hidden` and `flex-shrink: 0`.\nWhen `src` is provided and loads successfully, renders an `<img>` with\n`object-fit: cover`. On image error (or when no `src`), falls back to\ninitials derived from `name` (up to 2 characters, uppercase).\n\nInitials background: deterministic color from a 5-color palette based on\nname hash (primary-500, success-500, warning-500, error-500, info-500).\nFalls back to `var(--ggui-color-outline)` when no name is given.\nInitials text: white, `font-weight: var(--ggui-font-weight-semibold)`,\n`font-size: resolvedSize * 0.4`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image URL. When provided and the image loads, it is rendered with `object-fit: cover`. On load error, falls back to initials. |\n| name | `string` | - | Name used for two purposes: 1. Generating initials (splits on spaces, takes first letter of each word, max 2). 2. Deterministic background color selection via character code hash. Also used as `aria-label` on the container. Falls back to `'Avatar'` if omitted. |\n| size | `number \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Avatar dimensions. Named sizes map to pixel values: - `'xs'` -- 24px - `'sm'` -- 32px - `'md'` -- 40px - `'lg'` -- 48px - `'xl'` -- 64px  Numeric values are used directly as pixel dimensions. |\n| shape | `'circle' \\| 'square'` | `'circle'` | Container shape. - `'circle'` -- `border-radius: 50%` - `'square'` -- `border-radius: var(--ggui-shape-radius-md)` |\n\n**Example:**\n```tsx\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n```\n\n### Alert\n\nAlert -- Contextual message box for important information with icon and optional dismiss.\n\nRenders a `<div role=\"alert\">` with flex layout (12px gap), variant-specific\nbackground, border, text color, and a leading icon. Each variant provides a\ndefault SVG icon (info circle, checkmark, warning triangle, or X circle) that\ncan be overridden via the `icon` prop.\n\nLayout: icon (flex-shrink: 0) | content column (title + body) | close button.\nBorder radius: `var(--ggui-shape-radius-lg)`.\nPadding: `12px 16px`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets: - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)`, icon `var(--ggui-color-info-500)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)`, icon `var(--ggui-color-success-500)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)`, icon `var(--ggui-color-warning-500)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)`, icon `var(--ggui-color-error-500)` |\n| title | `string` | - | Optional title rendered above the body in semibold (`var(--ggui-font-weight-semibold)`), `var(--ggui-font-size-sm)`. Title and body are separated by `var(--ggui-spacing-1)` gap. |\n| closable | `boolean` | `false` | When true, renders a close button (X icon) in the top-right area. The button has `min-width: 28px`, `min-height: 28px`, and `opacity: 0.7`. Requires `onClose` to be functional. |\n| onClose | `() => void` | - | Callback fired when the close button is clicked. Only relevant when `closable` is true. |\n| icon | `ReactNode` | - | Custom icon ReactNode to replace the default variant icon. Rendered at the leading position with the variant's icon color applied via `color` CSS property. |\n\n**Example:**\n```tsx\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n```\n\n### Progress\n\nProgress -- Horizontal progress bar with determinate and indeterminate modes.\n\nRenders a track `<div role=\"progressbar\">` with a colored fill child.\nThe track background is `var(--ggui-color-outlineVariant)` with\npill-shaped corners (border-radius = height / 2).\n\nDeterminate mode: fill width transitions smoothly (`width 0.3s ease`).\nIndeterminate mode: fill is 30% width, animated with\n`ggui-progress-indeterminate 1.5s ease-in-out infinite`\n(translateX from -100% to 400%). The `@keyframes` are injected inline.\n\nAccessibility: `aria-valuenow` is set in determinate mode, omitted in\nindeterminate. `aria-valuemin` is always 0, `aria-valuemax` matches `max`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `number` | - | Current progress value. Clamped to `[0, max]` and converted to a percentage for the fill width: `Math.min(100, Math.max(0, (value / max) * 100))`. |\n| max | `number` | `100` | Maximum value representing 100% progress. |\n| variant | `'default' \\| 'success' \\| 'warning' \\| 'error'` | `'default'` | Fill bar color. Maps to CSS variables: - `'default'` -- `var(--ggui-color-primary-600)` - `'success'` -- `var(--ggui-color-success-500)` - `'warning'` -- `var(--ggui-color-warning-500)` - `'error'` -- `var(--ggui-color-error-500)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track height in pixels: - `'sm'` -- 4px - `'md'` -- 8px - `'lg'` -- 12px |\n| label | `string` | - | Accessible name describing what this bar measures, e.g. `\"Survey progress\"` or `\"Upload\"`. Becomes the progressbar's `aria-label` and \u2014 when `showLabel` is set \u2014 the visible header text in place of the generic word \"Progress\". Always pass this when the surrounding context does not already make the meaning obvious. |\n| showLabel | `boolean` | `false` | When true, displays a header row above the track with the `label` text (or \"Progress\" if `label` is unset) on the left, and the rounded percentage value on the right. |\n| indeterminate | `boolean` | `false` | When true, ignores `value` for visual width and plays a looping animation instead. The fill bar is 30% width and slides across the track. Animation: `ggui-progress-indeterminate 1.5s ease-in-out infinite`. `aria-valuenow` is omitted from the progressbar element. |\n\n**Example:**\n```tsx\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n```\n\n### Image\n\nImage -- An `<img>` element with built-in error handling and fallback support.\n\nRenders a native `<img>` with `display: block`. On load error, either renders\nthe `fallback` ReactNode (if provided) or a default placeholder `<div>` with a\nsurfaceVariant background and a centered image SVG icon in outline.\n\nSize values: numbers are treated as pixels, strings are passed through as-is.\nWhen no `width` is set, defaults to `100%`. When no `height` is set, defaults\nto `auto`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image source URL. Load failure triggers the fallback state. |\n| alt | `string` | - | Alt text for the image. Used as `aria-label` in the error placeholder too. |\n| width | `number \\| string` | `'100%' (applied at render time, not on the type)` | Image width. Numbers are pixels, strings are CSS values (e.g., `'100%'`, `'50vw'`). |\n| height | `number \\| string` | `'auto' (applied at render time, not on the type)` | Image height. Numbers are pixels, strings are CSS values. |\n| objectFit | `'cover' \\| 'contain' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | CSS `object-fit` value controlling how the image fills its box. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | - | Corner radius applied to both the image and the error placeholder. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through. |\n| fallback | `ReactNode` | - | Custom ReactNode rendered when the image fails to load. When provided, completely replaces the default error placeholder (no wrapper div). When omitted, a surfaceVariant background div with an image icon is shown. |\n\n**Example:**\n```tsx\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n```\n\n### Icon\n\nIcon -- a curated Lucide subset (~200 names) + emoji passthrough.\n\nThree resolution layers:\n1. **Lucide icon:** pass a name from the curated subset (e.g. `sun`, `cloud-rain`, `heart`, `shopping-cart`, `sparkles`, `arrow-up-right`).\n   Accepts kebab-case, camelCase, or PascalCase. Renders as stroke SVG. ONLY the subset renders: an\n   unknown name renders an empty box (never a placeholder glyph) \u2014 the `get_available_icons` tool lists the exact names.\n2. **Emoji:** pass emoji/unicode directly (e.g. `\u2600\uFE0F`, `\u{1F327}\uFE0F`). Rendered as text.\n3. **Custom SVG:** pass children (`<svg>` element) for full control.\n\nContainer: `<span>` with `display: inline-flex`, centered content.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| name | `string` | - | Lucide icon name from the curated subset (kebab-case, camelCase, or PascalCase all work); a name outside the subset renders an empty box. Also accepts emoji/unicode characters directly. |\n| size | `number` | `24` | Icon dimensions in pixels (applied to both width and height of the wrapper and the inner SVG element). |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (icon uses `currentColor`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Resolves to a CSS `color` on the wrapper which the inner SVG inherits via `currentColor`. Use `'inherit'` (the default behavior when unset) for icons that should pick up the parent's foreground color. |\n| children | `ReactNode` | - | Custom SVG children. When provided, `name` is ignored and children are rendered inside a sized `<span>` wrapper. |\n| 'aria-label' | `string` | - | Accessible name for a standalone, meaning-bearing icon. When set, the icon exposes `role=\"img\"` + this label. When omitted (the default) the icon is decorative and hidden from screen readers (`aria-hidden`) \u2014 the right choice for an icon next to a text label. |\n\n**Example:**\n```tsx\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n```\n\n### Link\n\nLink -- Styled anchor element with external link support.\n\nRenders a native `<a>` element. When `external` is true, sets\n`target=\"_blank\"` and `rel=\"noopener noreferrer\"`, and appends a small\n(12px) external-link SVG icon after the children.\n\nTransition: `color 0.2s`.\nUnderline behavior is controlled via mouseEnter/mouseLeave event handlers\n(for the `'hover'` mode).\n\nAlso extends native `AnchorHTMLAttributes` (except `style`/`className`),\nso props like `aria-*`, `data-*`, `title`, etc. are forwarded to the `<a>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| href | `string` | - | Destination URL. Passed directly to the `<a href>` attribute. |\n| external | `boolean` | `false` | When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`) and appends a 12px external-link icon after children. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the link text. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a primary-tinted accent (`'loud'`-ish) when unset. |\n| underline | `'always' \\| 'hover' \\| 'none'` | `'hover'` | Underline behavior: - `'always'` -- `text-decoration: underline` at all times - `'hover'` -- underline appears on mouse enter, removed on mouse leave - `'none'` -- no underline ever |\n\n**Example:**\n```tsx\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n```\n\n### Tooltip\n\nTooltip -- Hoverable information popup positioned relative to a trigger element.\n\nWraps `children` in a `<div>` trigger (display: inline-block) and renders\na fixed-position tooltip `<div role=\"tooltip\">` when visible.\n\nTooltip appearance:\n- Background: `var(--ggui-color-onContainer)`\n- Text: white, `var(--ggui-font-size-xs)`\n- Padding: `6px 10px`, border-radius: `var(--ggui-shape-radius-md)`\n- Max width: 200px, `white-space: nowrap`, `pointer-events: none`\n- Z-index: `zIndex.tooltip` (1800)\n\nShow/hide: triggered by mouseEnter/mouseLeave AND focus/blur on the\ntrigger element. Uses `position: fixed` with coordinates calculated from\n`getBoundingClientRect()` and an 8px offset from the trigger edge.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Trigger element. Wrapped in a `<div>` with mouseEnter/mouseLeave and focus/blur handlers. |\n| content | `ReactNode` | - | Tooltip content. Can be text or any ReactNode. |\n| position | `'top' \\| 'bottom' \\| 'left' \\| 'right'` | `'top'` | Tooltip placement relative to the trigger element: - `'top'` -- above, centered horizontally, transformed `translateX(-50%) translateY(-100%)` - `'bottom'` -- below, centered horizontally, transformed `translateX(-50%)` - `'left'` -- to the left, centered vertically, transformed `translateX(-100%) translateY(-50%)` - `'right'` -- to the right, centered vertically, transformed `translateY(-50%)` |\n| delay | `number` | `200` | Delay in milliseconds before the tooltip becomes visible after hover/focus. Hiding is immediate (no delay). |\n\n**Example:**\n```tsx\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n```\n\n### Table\n\nTable -- Data table with sortable columns, striped rows, and hover highlights.\n\nRenders a scrollable wrapper `<div>` containing a native `<table>` with\n`border-collapse: collapse` and `width: 100%`. The wrapper has\n`overflow-x: auto` for horizontal scrolling on narrow viewports.\n\nHeader row: 2px bottom border (`var(--ggui-color-outlineVariant)`).\nData rows: 1px bottom border (`var(--ggui-color-sunken)`).\nHover: `var(--ggui-color-container)` background with 150ms ease transition.\nStriped: alternating rows (odd index) get `var(--ggui-color-container)`.\n\nSort behavior: clicking a sortable column header calls `onSort(key, direction)`.\nIf the same column is clicked again while ascending, it toggles to descending.\nThe component does NOT sort data internally -- the parent must sort `data` and\npass updated `sortKey`/`sortDirection`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `TableColumn<T>[]` | - | Array of column definitions controlling header labels, data keys, and rendering. |\n| data | `T[]` | - | Array of row data objects. Each object's keys should match the column `key` values. |\n| sortKey | `string` | - | The `key` of the currently sorted column. Used to highlight the active sort indicator and determine toggle direction on next click. |\n| sortDirection | `SortDirection` | `'asc'` | Current sort direction for the column identified by `sortKey`. Controls which triangle indicator is highlighted in the header. |\n| onSort | `(key: string, direction: SortDirection) => void` | - | Sort change handler. Called when a sortable column header is clicked. Receives the column `key` and the new `SortDirection`. The component does NOT sort data internally -- you must sort `data` in your state and pass updated `sortKey`/`sortDirection`. |\n| striped | `boolean` | `false` | When true, alternating rows (odd index) get a `var(--ggui-color-container)` background. |\n| hoverable | `boolean` | `true` | When true, rows highlight with `var(--ggui-color-container)` on mouse enter, with a 150ms ease background-color transition. |\n| compact | `boolean` | `false` | When true, reduces cell padding: - Compact: `var(--ggui-spacing-1) var(--ggui-spacing-2)` - Normal: `var(--ggui-spacing-2) var(--ggui-spacing-4)` |\n| bordered | `boolean` | `false` | When true, adds a 1px border around the table wrapper and between cells. Wrapper border: `1px solid var(--ggui-color-outlineVariant)`. Cell borders: `1px solid var(--ggui-color-sunken)`. Wrapper border-radius: `var(--ggui-shape-radius-lg)`. |\n| caption | `string` | - | Accessible table caption. Rendered as a `<caption>` element with `caption-side: top`, `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`. |\n\n**Example:**\n```tsx\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n```\n\n### Tabs\n\nTabs -- Accessible tab navigation with panels and keyboard support.\n\nRenders a `<div role=\"tablist\">` with `<button role=\"tab\">` elements and a\n`<div role=\"tabpanel\">` for the active tab's content. Supports controlled\n(`activeKey` + `onChange`) and uncontrolled (internal state) modes.\n\nKeyboard navigation: ArrowLeft/ArrowRight (and ArrowUp/ArrowDown) cycle\nthrough enabled tabs. Home/End jump to first/last. Focus follows selection.\nDisabled tabs are skipped during keyboard navigation.\n\n**IMPORTANT:** `onChange` receives the tab's `key` string directly, NOT a\nReact event.\n\nTab panel padding: `var(--ggui-spacing-4) 0` (top/bottom only).\nTransitions: color, background-color, border-color at 200ms ease-in-out.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `TabItem[]` | - | Array of tab definitions. Must contain at least one item. |\n| activeKey | `string` | - | Controlled active tab key. When provided, the component is controlled and will not manage its own state. Must match one of `items[].key`. When omitted, defaults to the first item's key (uncontrolled mode). |\n| onChange | `(key: string) => void` | - | Tab change handler. Receives the selected tab's `key` string directly, NOT a React event. In controlled mode, you must update `activeKey` in response to this callback. |\n| variant | `'line' \\| 'pills' \\| 'enclosed'` | `'line'` | Visual style of the tab bar: - `'line'` -- underline indicator (2px solid primary-600 on active), border-bottom on tab list - `'pills'` -- filled pill buttons (primary-600 bg, white text on active), surfaceVariant container with radius-lg - `'enclosed'` -- bordered tab buttons with open bottom (card-style), border-bottom on tab list |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls tab button padding and font size: - `'sm'` -- padding `var(--ggui-spacing-1) var(--ggui-spacing-2)`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `var(--ggui-spacing-2) var(--ggui-spacing-4)`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `var(--ggui-spacing-4) var(--ggui-spacing-6)`, font `var(--ggui-font-size-base)` |\n| fullWidth | `boolean` | `false` | When true, tab buttons expand equally to fill the container width (`flex: 1`, `justify-content: center` on each button). |\n\n**Example:**\n```tsx\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n```\n\n### Toast\n\nToast -- Notification banner with auto-dismiss and slide-in animation.\n\nRenders a `<div role=\"alert\" aria-live=\"assertive\">` with a variant-specific\nicon, optional title, message body, and optional close button.\n\nAnimation: `ggui-slideInUp 200ms ease-out both` on mount (from the motion\ntoken system). The keyframes are provided by the MotionKeyframes provider.\n\nAuto-dismiss: when `onClose` is provided and `duration > 0`, a timer calls\n`onClose` after `duration` ms. Setting `duration` to `0` disables auto-dismiss.\nThe timer resets if `visible`, `duration`, or `onClose` changes.\n\nDimensions: `min-width: 280px`, `max-width: 420px`.\nShadow: `var(--ggui-shape-shadow-lg)`.\nBorder radius: `var(--ggui-shape-radius-lg)`.\n\nWhen `visible` is false, renders nothing (returns `null`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| message | `ReactNode` | - | Message body content. Can be text or any ReactNode. |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets (same palette as Alert): - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)` |\n| title | `string` | - | Optional title rendered above the message in semibold (`var(--ggui-font-weight-semibold)`, `var(--ggui-font-size-sm)`). |\n| duration | `number` | `5000` | Auto-dismiss delay in milliseconds. After this duration, `onClose` is called automatically. Set to `0` to disable auto-dismiss (toast stays until manually closed). The timer is only active when both `visible` is true and `onClose` is provided. |\n| onClose | `() => void` | - | Callback fired on auto-dismiss timeout or when the close button is clicked. When provided, a close button (X icon, 16px) is rendered in the top-right area. When omitted, no close button is shown and auto-dismiss is disabled. |\n| visible | `boolean` | `true` | Controls rendering. When false, the component returns `null`. Toggling from false to true triggers the slide-in animation. |\n| position | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-center' \\| 'bottom-center'` | - | Intended screen position. This prop is defined on the interface but is NOT implemented by the Toast component itself -- positioning must be handled by a parent container or toast manager. |\n\n**Example:**\n```tsx\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n```\n\n### Accordion\n\nAccordion -- Collapsible content sections with chevron rotation animation.\n\nRenders a vertical list of items, each with a `<button>` header (inside `<h3>`)\nand a `<div role=\"region\">` panel. Supports controlled (`expandedKeys` + `onChange`)\nand uncontrolled (internal state) modes.\n\nChevron animation: the trailing chevron icon rotates from 0deg (collapsed) to\n180deg (expanded) with `transition: transform var(--ggui-motion-duration-base) var(--ggui-motion-easing-standard)` (ggui#1106).\n\nHeader button: full-width flex layout (`justify-content: space-between`),\n`var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n`var(--ggui-color-onContainer)`.\nHeader padding: `var(--ggui-spacing-2) var(--ggui-spacing-4)`.\nBackground transition: `background-color var(--ggui-motion-duration-fast) var(--ggui-motion-easing-standard)`.\n\n**IMPORTANT:** `onChange` receives the full array of currently expanded keys,\nNOT a single key or a React event. In single mode (`multiple: false`), this\narray will have at most one element.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `AccordionItem[]` | - | Array of collapsible section definitions. |\n| expandedKeys | `string[]` | - | Controlled expanded state. Array of item `key` values that should be open. When provided, the component is controlled and will not manage its own expansion state. When omitted, defaults to `[]` (all collapsed, uncontrolled mode). |\n| onChange | `(expandedKeys: string[]) => void` | - | Expand/collapse handler. Receives the complete array of expanded keys after a toggle. In controlled mode, you must update `expandedKeys` in response to this callback. |\n| multiple | `boolean` | `false` | When true, multiple items can be open simultaneously. When false, opening one item closes any other open item (single-expand mode). |\n| variant | `'default' \\| 'bordered' \\| 'separated'` | `'default'` | Visual style controlling borders and spacing: - `'default'` -- top border on first item, bottom border on all items (`var(--ggui-color-outlineVariant)`), no gap between items - `'bordered'` -- connected card style with left/right/bottom borders on all items, top border on first, shared rounded corners (radius-lg on first/last) - `'separated'` -- each item is an independent card with full border (`1px solid var(--ggui-color-outlineVariant)`), `var(--ggui-shape-radius-lg)` radius, `var(--ggui-spacing-2)` gap between items |\n\n**Example:**\n```tsx\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n```\n\n### Support Types\n\n**ResponsiveColumns:**\n\nExplicit column count per viewport breakpoint, mobile-first. `base`\napplies from 0 up; each named key overrides at and above its\nbreakpoint width (`sm` 640px, `md` 768px, `lg` 1024px, `xl` 1280px).\nOmit `base` to default to a single column on the narrowest screens.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| base | `number` | Columns below the `sm` breakpoint. |\n| sm | `number` | Columns from 640px up. |\n| md | `number` | Columns from 768px up. |\n| lg | `number` | Columns from 1024px up. |\n| xl | `number` | Columns from 1280px up. |\n\n**SelectOption:**\n\nAn individual option within a `Select` dropdown.\n\nRendered as a native `<option>` element. When `disabled` is true, the option\nis visible but not selectable.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value submitted when this option is selected. Must be unique within the options array. |\n| label | `string` | The display text shown in the dropdown. |\n| disabled | `boolean` | When true, the option is visible but cannot be selected (grayed out by the browser). |\n\n**RadioOption:**\n\nAn individual option within a `RadioGroup`.\n\nRendered as a `<label>` containing a visually-hidden `<input type=\"radio\">`\nand a custom 18px circle indicator. Supports an optional description line\nbelow the label text.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value emitted via `RadioGroupProps.onChange` when this option is selected. Must be unique. |\n| label | `string` | Display text for this option. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| description | `string` | Optional secondary description rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| disabled | `boolean` | When true, this individual option is grayed out (`opacity: 0.5`) and cannot be selected, regardless of the group-level `disabled` prop. |\n\n**TableColumn:**\n\nColumn definition for the Table component.\n\nEach column maps a `key` in the row data object to a table column with\na header label, optional sorting, alignment, width, and custom rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key in the row data object. Used to extract cell values via `row[key]`. Must be unique across all columns in a Table. |\n| header | `string` | Column header text. Rendered in uppercase, `var(--ggui-font-size-xs)`, `var(--ggui-font-weight-semibold)`, `var(--ggui-color-onSunken)`, with `letter-spacing: 0.05em`. |\n| width | `number \\| string` | Fixed column width. Numbers are pixels, strings are CSS values (e.g., `'200px'`, `'30%'`). When omitted, the column auto-sizes based on content. |\n| align | `'left' \\| 'center' \\| 'right'` | Horizontal text alignment for both the header and data cells. |\n| sortable | `boolean` | When true, the header cell becomes clickable and shows sort direction indicators (ascending/descending triangles). Clicking toggles between `'asc'` and `'desc'`. The header gets `cursor: pointer`, `tabIndex: 0`, and keyboard support (Enter/Space to toggle). |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When provided, called instead of rendering `row[key]` directly. Receives the cell value, the full row object, and the row index. |\n\n**TabItem:**\n\nDefinition of a single tab within a Tabs component.\n\nEach item provides a unique `key` for identification, a `label` for the\ntab button, and `content` for the associated panel.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this tab. Used to match `activeKey` and as the value passed to `onChange`. |\n| label | `ReactNode` | Tab button label. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the tab bar when this tab is active. |\n| disabled | `boolean` | When true, the tab button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be selected via click or keyboard navigation. |\n| icon | `ReactNode` | Optional icon rendered before the label inside the tab button, with `var(--ggui-spacing-1)` gap between icon and label. |\n\n**AccordionItem:**\n\nDefinition of a single collapsible section within an Accordion.\n\nEach item provides a unique `key`, a clickable `title` for the header button,\nand `content` revealed when expanded.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this item. Used in `expandedKeys` and passed to `onChange`. |\n| title | `ReactNode` | Header label rendered inside the toggle button. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the header when expanded. Styled with `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`, `line-height: var(--ggui-font-lineHeight-normal)`. Padding: `0 var(--ggui-spacing-4) var(--ggui-spacing-4)`. |\n| disabled | `boolean` | When true, the header button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be toggled. |\n\n\n## Components\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### SearchField\n\nA text input with a leading search icon and optional submit button.\n\nComposes: `Input` (native `<input type=\"search\">`), `Button`, `Spinner`, `Icon`.\n\nSupports controlled and uncontrolled usage. When `value` is `undefined` the\ncomponent tracks its own state internally. Pressing **Enter** triggers\n`onSearch` with the current value. When `loading` is `true` the search icon\nis replaced by a `Spinner` and the input is disabled.\n\nTokens used: `colors.gray[300]` border, `colors.gray[50]` disabled bg,\n`colors.gray[400]` icon color, `colors.gray[900]` text color.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | - | Current search value. When provided, the component is **controlled** and the caller must update this via `onChange`. When omitted, the component manages its own internal state. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React `ChangeEvent`). |\n| onSearch | `(value: string) => void` | - | Called when the user presses **Enter** or clicks the search button (if `showButton` is `true`). Receives the current value directly. |\n| placeholder | `string` | `'Search...'` | Placeholder text shown when the input is empty. |\n| showButton | `boolean` | `false` | When `true`, renders a `Button` primitive to the right of the input. The button's label is set by `buttonText`. |\n| buttonText | `string` | `'Search'` | Label rendered inside the submit button. Only visible when `showButton` is `true`. |\n| loading | `boolean` | - | When `true`, replaces the search icon with a `Spinner`, disables the input, and disables the submit button. |\n| disabled | `boolean` | - | When `true`, the input and button are visually disabled and do not respond to interaction. The input background changes to `colors.gray[50]`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls input height and font size. - `'sm'` -- 6px vertical padding, 14px font - `'md'` -- 10px vertical padding, 14px font - `'lg'` -- 12px vertical padding, 16px font  The Button size maps `sm`->`sm`, `md`->`md`, `lg`->`md`. |\n\n**Example:**\n```tsx\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n```\n\n### FormField\n\nA wrapper that adds a label, optional description, error message,\nand helper text around any form input passed as `children`.\n\nComposes: no other primitives -- pure layout with semantic `<label>` and\n`<span>` elements.\n\nVisual hierarchy (top to bottom):\n1. **Label** (required) -- `fontSize.sm`, `fontWeight.medium`, `colors.gray[700]`\n2. **Required indicator** -- red asterisk (`colors.error[500]`) appended to label\n3. **Description** -- `fontSize.xs`, `colors.gray[500]`, 4px bottom margin\n4. **Children** -- the form control itself\n5. **Error / Helper text** -- `fontSize.xs`; error in `colors.error[500]`,\n   helper in `colors.gray[500]`. Error takes priority when both are provided.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Text rendered inside the `<label>` element above the input. |\n| children | `ReactNode` | - | The form control (typically an `Input`, `Select`, or `Textarea` primitive) rendered between the label/description and the error/helper row. |\n| error | `string` | - | Error message displayed below `children` in `colors.error[500]`. When present, it takes precedence over `helperText`. |\n| helperText | `string` | - | Neutral guidance text displayed below `children` in `colors.gray[500]`. Hidden when `error` is present. |\n| required | `boolean` | - | When `true`, appends a red asterisk (`*`) after the label text. Does **not** add any HTML validation attributes -- handle that on the child input. |\n| description | `string` | - | Secondary description rendered between the label and the child control in `fontSize.xs` / `colors.gray[500]`. Use for longer guidance that does not belong in `helperText`. |\n\n**Example:**\n```tsx\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n```\n\n### MenuItem\n\nA full-width clickable row for menus, sidebars, and action lists.\n\nComposes: none -- renders a native `<button>` element.\n\nBuilt-in transition: `background-color` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on hover (ggui#1106).\n\nColor logic:\n- **Normal**: text `colors.gray[700]`, hover bg `colors.gray[100]`\n- **Active**: bg `colors.primary[50]`, text `colors.gray[700]`, `fontWeight.medium`\n- **Danger**: text `colors.error[600]`, hover bg `colors.error[50]`, active bg `colors.error[100]`\n- **Disabled**: text `colors.gray[400]`, `cursor: not-allowed`\n\nLayout: flexbox row with `8px` gap, `8px 12px` padding, `radius.md` border-radius.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary text content of the menu item. |\n| icon | `ReactNode` | - | Icon or element rendered to the left of the label. Flex-shrink 0. |\n| rightElement | `ReactNode` | - | Element rendered to the right of the label (e.g., a keyboard shortcut badge or a count). Colored `colors.gray[400]`, flex-shrink 0. |\n| onClick | `() => void` | - | Called when the item is clicked. Suppressed when `disabled` is `true`. |\n| disabled | `boolean` | - | When `true`, the item is non-interactive: `colors.gray[400]` text, `cursor: not-allowed`, click handler suppressed. |\n| active | `boolean` | - | Marks this item as the current selection. Applies a tinted background (`colors.primary[50]`, or `colors.error[100]` when `danger` is also set) and `fontWeight.medium`. |\n| danger | `boolean` | - | Switches the item to destructive styling: `colors.error[600]` text, `colors.error[50]` hover background. |\n\n**Example:**\n```tsx\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n```\n\n### Tag\n\nAn inline label for categories, filters, statuses, or selections.\nOptionally dismissable via a close button.\n\nComposes: none -- pure `<span>` with an optional close `<button>`.\n\nEach `variant` maps to a background / text / border color triple from the\ndesign tokens:\n- `'default'`  -- `gray[100]` / `gray[700]` / `gray[200]`\n- `'primary'`  -- `primary[50]` / `primary[700]` / `primary[200]`\n- `'success'`  -- `success[50]` / `success[700]` / `success[200]`\n- `'warning'`  -- `warning[50]` / `warning[700]` / `warning[200]`\n- `'error'`    -- `error[50]` / `error[700]` / `error[200]`\n- `'info'`     -- `info[50]` / `info[700]` / `info[200]`\n\nThe close button renders an inline SVG \"x\" icon (12x12) with `opacity: 0.7`\nand an `aria-label=\"Remove\"`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Tag content -- typically a short text string. |\n| variant | `'default' \\| 'primary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Semantic color variant applied to background, text, and border. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and internal gap. - `'sm'` -- 2px/6px padding, `fontSize.xs`, 4px gap - `'md'` -- 4px/8px padding, `fontSize.xs`, 6px gap - `'lg'` -- 6px/10px padding, `fontSize.sm`, 6px gap |\n| closable | `boolean` | - | When `true`, renders a small close (\"x\") button after the content. Clicking it fires `onClose`. |\n| onClose | `() => void` | - | Called when the close button is clicked. Only relevant when `closable` is `true`. |\n| icon | `ReactNode` | - | Icon or element rendered before the text content. |\n\n**Example:**\n```tsx\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n```\n\n### Dropdown\n\nA click-triggered menu anchored to a trigger element. Manages its own\nopen/close state internally.\n\nComposes: `MenuItem` for each option.\n\nBehavior:\n- Clicking the trigger toggles the menu open/closed.\n- Selecting an option calls `onChange(option.value)` and closes the menu.\n- Clicking outside the container or pressing **Escape** closes the menu.\n- The currently selected option (matching `value`) is rendered with\n  `MenuItem`'s `active` state.\n\nMenu panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, 160px min-width, 4px padding.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| trigger | `ReactNode` | - | The element the user clicks to open the menu. Receives a wrapping `<div>` with `cursor: pointer` (or `not-allowed` when disabled). |\n| options | `DropdownOption[]` | - | Array of selectable options rendered as `MenuItem` rows. |\n| value | `string` | - | The `value` of the currently selected option. The matching `MenuItem` is rendered with `active` styling. |\n| onChange | `(value: string) => void` | - | Called with the `value` string of the selected option (not the full `DropdownOption` object). The menu closes immediately after. |\n| placement | `'bottom-start' \\| 'bottom-end' \\| 'top-start' \\| 'top-end'` | `'bottom-start'` | Where to anchor the menu panel relative to the trigger. - `'bottom-start'` -- below, aligned to left edge - `'bottom-end'`   -- below, aligned to right edge - `'top-start'`    -- above, aligned to left edge - `'top-end'`      -- above, aligned to right edge |\n| disabled | `boolean` | - | When `true`, the trigger shows `cursor: not-allowed` and clicking it does not open the menu. |\n\n**Example:**\n```tsx\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n```\n\n### Autocomplete\n\nA text input with a filterable suggestion dropdown, keyboard navigation,\nand loading/empty states.\n\nComposes: `Input` primitive (with `label`, `error`, `placeholder` forwarded),\n`Spinner` (loading state).\n\nFiltering: options are filtered client-side by case-insensitive substring\nmatch against both `option.label` and `option.value`.\n\nKeyboard support:\n- **ArrowDown / ArrowUp** -- move highlight through filtered options\n  (opens dropdown if closed)\n- **Enter** -- selects the highlighted option\n- **Escape** -- closes the dropdown\n\nOn selection, `onChange` is called with `option.label` (the display text)\nand `onSelect` is called with the full `AutocompleteOption` object.\n\nDropdown panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, max-height 240px with\noverflow scroll.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | `''` | Current text in the input field. On selection, this is set to the selected option's `label`. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React event). Also called on selection with `option.label`. |\n| onSelect | `(option: AutocompleteOption) => void` | - | Called when the user selects an option (click or Enter on highlighted item). Receives the full `AutocompleteOption` object, not just the value string. |\n| options | `AutocompleteOption[]` | - | The full list of available options. Filtering is handled internally via case-insensitive substring match on `label` and `value`. |\n| placeholder | `string` | - | Placeholder text forwarded to the inner `Input` primitive. |\n| label | `string` | - | Label text forwarded to the inner `Input` primitive. |\n| loading | `boolean` | - | When `true`, the dropdown shows a centered `Spinner` instead of the option list. The input remains interactive. |\n| disabled | `boolean` | - | When `true`, the inner `Input` is disabled and the dropdown does not open. |\n| error | `string` | - | Error message forwarded to the inner `Input` primitive. |\n| noResultsText | `string` | `'No results found'` | Text shown in the dropdown when filtering produces zero matches. Rendered centered in `colors.gray[500]` / `fontSize.sm`. |\n\n**Example:**\n```tsx\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n```\n\n### Breadcrumb\n\nA horizontal navigation trail showing the user's location within a\nhierarchy. Renders a `<nav aria-label=\"Breadcrumb\">`.\n\nComposes: `Link` primitive (for items with `href`).\n\nRendering rules per item:\n- **Last item**: static `<span>` with `colors.gray[900]`, `fontWeight: 500`,\n  and `aria-current=\"page\"`.\n- **Non-last with `href`**: `Link` in `colors.gray[500]` with\n  `underline=\"hover\"`. If `onItemClick` is provided, `e.preventDefault()`\n  is called and the handler fires instead of navigating.\n- **Non-last without `href`**: unstyled `<button>` in `colors.gray[500]`.\n\nLayout: flexbox row, `8px` gap, `fontSize.sm`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `BreadcrumbItem[]` | - | Ordered array of breadcrumb segments from root to current page. |\n| separator | `ReactNode` | `'/'` | Separator rendered between each pair of items. Can be a string (e.g., `\"/\"`, `\">\"`) or a ReactNode (e.g., an `Icon`). Rendered in `colors.gray[400]`. |\n| onItemClick | `(item: BreadcrumbItem, index: number) => void` | - | Called when a non-last item is clicked. Receives the `BreadcrumbItem` and its zero-based `index`. When provided on items that have `href`, the default navigation is prevented via `e.preventDefault()`. |\n\n**Example:**\n```tsx\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n```\n\n### Pagination\n\nPage navigation controls with previous/next arrows, numbered page buttons,\nand optional first/last jumps. Renders a `<nav aria-label=\"Pagination\">`.\n\nComposes: `Button` (ghost variant for prev/next/first/last arrows),\n`Icon` (`chevron-left`, `chevron-right`).\n\nBuilt-in transition: `all` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on page number buttons (ggui#1106).\n\nPage windowing: when `totalPages > maxVisible`, the component shows the\nfirst page, last page, a window of pages around `currentPage`, and\nellipsis (\"...\") markers for gaps. The window adjusts when near the\nstart or end of the range.\n\nActive page button: `colors.primary[600]` bg, `colors.white` text,\n`fontWeight.medium`. Inactive: transparent bg, `colors.gray[700]` text.\n\nArrow buttons are automatically disabled at boundary pages (first/last).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| currentPage | `number` | - | Current active page. **1-indexed** (first page is `1`). |\n| totalPages | `number` | - | Total number of pages. Determines when last-page / next-page buttons disable. |\n| onPageChange | `(page: number) => void` | - | Called when the user clicks a page number, arrow, or first/last button. Receives the target page number (1-indexed) directly. |\n| showFirstLast | `boolean` | `true` | When `true`, renders double-chevron buttons for jumping to the first and last page. These buttons are disabled when already on the respective boundary. |\n| maxVisible | `number` | `5` | Maximum number of page buttons visible at once (including the first and last page, but excluding ellipsis markers). When `totalPages` exceeds this value, ellipsis gaps appear. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls button dimensions and icon sizes. - `'sm'` -- 28px buttons, 14px icons, Button size `xs` - `'md'` -- 32px buttons, 16px icons, Button size `sm` - `'lg'` -- 40px buttons, 20px icons, Button size `md` |\n| disabled | `boolean` | - | When `true`, all page buttons and arrows are visually dimmed (`opacity: 0.5`) and clicks are suppressed. |\n\n**Example:**\n```tsx\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n```\n\n### EmptyState\n\nEmptyState -- placeholder for a region with no data: empty lists,\nzero search results, an error fallback. Render it instead of\nnothing whenever a data array could be empty \u2014 a list that shows\nnothing when empty looks broken.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| icon | `string \\| ReactNode` | - | A Lucide icon name (kebab-case), rendered large and subtle above the title, or a custom node. Omit for a text-only empty state. |\n| title | `string` | - | The headline, e.g. \"No results found\". |\n| description | `string` | - | Optional supporting line below the title. |\n| action | `ReactNode` | - | Optional call-to-action, typically a `<Button>`. |\n\n**Example:**\n```tsx\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n```\n\n### Stat\n\nStat -- a single KPI / metric: a label, a large value, an optional\ntrend-coloured delta and icon. Reach for it whenever the UI is\n\"show a number\" \u2014 dashboards, weather and price cards, analytics\ntiles. Drop several into a `<Grid>` for a stat grid.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | The metric name, e.g. \"Revenue\". Rendered small and uppercase above the value. |\n| value | `string \\| number` | - | The headline value \u2014 the big number. A number, or a pre-formatted string (`\"$48.2k\"`, `\"18\xB0C\"`). |\n| delta | `string` | - | Optional change indicator, pre-formatted, e.g. `\"+12.5%\"` or `\"-3\"`. |\n| trend | `'up' \\| 'down' \\| 'neutral'` | `'neutral'` | Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error, `'neutral'` muted. |\n| icon | `string \\| ReactNode` | - | Optional Lucide icon name (kebab-case) or custom node, shown next to the label. |\n\n**Example:**\n```tsx\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n```\n\n### Stepper\n\nStepper -- a display-only step indicator for multi-step flows\n(wizards, checkouts, onboarding): numbered markers joined by\nconnector lines, with completed (check), current (filled), and\nupcoming (outlined) states styled distinctly.\n\nStepper renders step state; it never owns it. Declare the step\nlabels as a top-level `const`, track the current index in\n`useState`, and advance it from your own Next/Back buttons (or\n`onStepClick`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| steps | `string[]` | - | Ordered step labels, one per step. Declare as a top-level `const` array \u2014 never as state. |\n| current | `number` | - | Zero-based index of the active step. Steps before it render as completed (check mark), steps after it as upcoming. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Flow direction. `'horizontal'` joins the markers with connector lines in a row; `'vertical'` stacks the steps with short connector columns \u2014 better for sidebars or long step labels. |\n| onStepClick | `(index: number) => void` | - | When provided, each step becomes a real button and clicks receive the step's zero-based index. Typical use: jumping back to a completed step; guard forward jumps in the handler if the flow validates per step. |\n\n**Example:**\n```tsx\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n```\n\n### Markdown\n\nMarkdown -- renders markdown-formatted text as styled content:\nheadings, paragraphs, **bold** / *italic*, `inline code`, fenced\ncode blocks, bulleted and numbered lists, pipe tables, and links.\n\nUse it whenever a prop or context slot carries prose the agent\nauthors in markdown -- article bodies, AI-generated explanations,\ndescriptions, notes, help text. Pass the raw markdown string\nstraight through; never pre-parse it, never split it into per-line\n`Text` elements, and never rebuild formatting with nested\n`<strong>`/`<em>` markup yourself.\n\nSafe by construction: raw HTML in the source displays as literal\ntext (never markup), and links render inert unless their scheme is\nhttp(s)/mailto. Streaming-tolerant: a mid-stream prefix parses\ncleanly and completed constructs never change shape, so binding a\ngrowing string re-renders correctly.\n\nFor a single line of formatted text INSIDE another element (a table\ncell, a list row, a caption), use `MarkdownInline` instead -- same\n`markdown` prop, inline-level constructs only (no headings, lists,\nor code fences), renders inside the parent's typography.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Markdown source text, passed through verbatim. Supports the conversational subset: `#`-`###` headings, paragraphs, bold, italic, inline code, fenced code blocks, `-`/`1.` lists, `\\|` pipe tables, and `[label](url)` links. Bind stateful or streamed prose directly. |\n\n**Example:**\n```tsx\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n```\n\n### MarkdownInline\n\nMarkdownInline -- renders ONE line of inline-level markdown (bold,\nitalic, inline code, links) inside the parent's typography -- a table\ncell, a list row, a caption, a summary line. Same `markdown` prop as\n`Markdown`; block constructs (headings, lists, code fences) are not\nrendered -- reach for `Markdown` for multi-paragraph bodies.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Inline markdown source -- bold, italic, inline code, and `[label](url)` links. Block-level syntax renders as plain text. |\n\n**Example:**\n```tsx\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n```\n\n### Support Types\n\n**DropdownOption:**\n\nA single option inside a `Dropdown`. Each option maps to one `MenuItem`\ninternally.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier returned to `onChange` when this option is selected. |\n| label | `string` | Human-readable text shown in the menu row. |\n| icon | `ReactNode` | Optional icon rendered to the left of the label via `MenuItem.icon`. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive. |\n| danger | `boolean` | When `true`, the option uses destructive (red) styling via `MenuItem.danger`. |\n\n**AutocompleteOption:**\n\nA single option in the `Autocomplete` suggestion list.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier for this option. Also used for case-insensitive filtering against the input value. |\n| label | `string` | Primary display text. Also used for case-insensitive filtering and is written into the input on selection. |\n| description | `string` | Secondary description rendered below the label in `fontSize.xs` / `colors.gray[500]`. |\n| icon | `ReactNode` | Icon rendered to the left of the label/description block. Flex-shrink 0. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive (`cursor: not-allowed`, `colors.gray[400]` text). |\n\n**BreadcrumbItem:**\n\nA single segment in a `Breadcrumb` trail. Items with `href` render as\n`Link` primitives; items without render as plain `<button>` elements.\nThe last item in the array is always rendered as static text with\n`aria-current=\"page\"`.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for this breadcrumb segment. |\n| href | `string` | URL for this segment. When provided (and this is not the last item), the segment renders as a `Link` primitive with `underline=\"hover\"`. When omitted, it renders as a `<button>`. |\n| icon | `ReactNode` | Icon rendered immediately before the label. Its color follows the segment's text color: `colors.gray[500]` for navigable items, `colors.gray[900]` for the current (last) item. |\n\n\n## Compositions\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Header\n\nProps for the `Header` composition.\n\nA horizontal page header that arranges a logo, navigation, and action slots\nin a flex row (`justify-content: space-between`). Internally renders a `<header>` element;\ndoes not compose other ggui primitives.\n\nWhen `sticky` is true the header gets `position: sticky; top: 0` with `zIndex.sticky`\nand a `shadow.sm` box-shadow.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| logo | `ReactNode` | - | Logo or brand element rendered at the start (flex-shrink: 0). |\n| navigation | `ReactNode` | - | Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px left margin. |\n| actions | `ReactNode` | - | Right-side action elements (buttons, avatar, etc.) rendered with a 12 px gap. |\n| sticky | `boolean` | `false` | When true, the header becomes `position: sticky` at the top of its scroll container with `zIndex.sticky` and `shadow.sm`. |\n| background | `string` | `colors.white` | Background color of the header. |\n| bordered | `boolean` | `true` | When true, renders a 1 px bottom border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n```\n\n### Sidebar\n\nProps for the `Sidebar` composition.\n\nA vertical navigation panel that composes the `Icon` primitive for chevron indicators.\nItems are rendered as `<button>` elements inside a scrollable `<nav>`. Nested items\nare indented 16 px per depth level. The sidebar animates width changes with a 200 ms\nCSS transition. Active items are highlighted with `colors.primary[50]` background\nand `colors.primary[700]` text.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `SidebarItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Matched items get a highlighted background and bold text. |\n| onItemClick | `(item: SidebarItem) => void` | - | Called when any item (including parent items with children) is clicked. |\n| collapsed | `boolean` | `false` | When true, hides labels and badges; only icons remain visible, centered in the collapsed width. Nested children are hidden entirely. |\n| header | `ReactNode` | - | Content rendered above the item list, separated by a bottom border. |\n| footer | `ReactNode` | - | Content rendered below the item list, separated by a top border. |\n| width | `number` | `256` | Width in pixels when expanded. |\n| collapsedWidth | `number` | `64` | Width in pixels when collapsed. |\n\n**Example:**\n```tsx\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n```\n\n### CardGrid\n\nProps for the `CardGrid` composition.\n\nA CSS Grid wrapper that arranges children in equal-width columns. When `columns`\nis a number, it produces `repeat(N, 1fr)`. When it is a responsive object,\nit falls back to `repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive behavior.\n\nDoes not compose any ggui primitives internally \u2014 it is a pure layout container.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Card elements to arrange in the grid. |\n| columns | `number \\| { sm?: number; md?: number; lg?: number }` | `3` | Number of columns, or a responsive breakpoint map.  - `number` \u2014 fixed column count via `repeat(N, 1fr)`. - `{ sm?, md?, lg? }` \u2014 triggers `repeat(auto-fit, minmax(280px, 1fr))` for fluid layout. |\n| gap | `number` | `16` | Gap between grid items in pixels. |\n\n**Example:**\n```tsx\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n```\n\n### CommentThread\n\nProps for the `CommentThread` composition.\n\nA threaded comment section that composes `Avatar`, `Button`, `TextArea`, and `Spinner`\nprimitives. Comments are rendered recursively with 40 px indentation per nesting level.\nEach comment shows author avatar, name, timestamp, content, reactions, and a \"Reply\" toggle.\nWhen `currentUser` is provided, a new-comment input with avatar and submit button is shown\nabove the thread.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| comments | `Comment[]` | - | Array of top-level comments to render. Replies are nested within each comment. |\n| currentUser | `{     /** Display name for the current user's avatar. */     name: string;     /** Avatar image URL for the current user. */     avatar?: string;   }` | - | Current user info. When provided, a new-comment input area is rendered above the thread. |\n| onAddComment | `(content: string, parentId?: string) => void` | - | Called when the user submits a new top-level comment. |\n| onReply | `(commentId: string, content: string) => void` | - | Called when the user submits a reply to an existing comment. |\n| onReaction | `(commentId: string, emoji: string) => void` | - | Called when the user clicks an emoji reaction on a comment. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the comment list. |\n\n**Example:**\n```tsx\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n```\n\n### DataTable\n\nProps for the `DataTable` composition.\n\nA sortable, selectable data table that composes `Checkbox`, `Spinner`, and `Icon`\nprimitives. Renders a `<table>` inside a bordered container with 8 px border-radius.\nThe header row has a `colors.gray[50]` background. Sortable columns show a chevron\nicon on click (toggles asc/desc). Selected rows are highlighted with `colors.primary[50]`.\nRow background transitions use a 150 ms ease. The \"select all\" checkbox supports an\nindeterminate state when a subset of rows is selected.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `DataTableColumn<T>[]` | - | Column definitions that control header, alignment, sorting, and rendering. |\n| data | `T[]` | - | Row data array. Each entry corresponds to one table row. |\n| rowKey | `string \\| ((row: T) => string)` | `'id'` | Property name or function used to derive a unique key for each row. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of table body rows. |\n| emptyText | `string` | `'No data'` | Text shown when `data` is empty and not loading. |\n| onSort | `(key: string, direction: 'asc' \\| 'desc') => void` | - | Called when a sortable column header is clicked. Toggles direction automatically (asc -> desc) if the same column is clicked again. |\n| sortKey | `string` | - | The column key currently being sorted. |\n| sortDirection | `'asc' \\| 'desc'` | - | The current sort direction. |\n| onRowClick | `(row: T, index: number) => void` | - | Called when a row is clicked. Rows get `cursor: pointer` when this handler is provided. |\n| selectable | `boolean` | - | When true, adds a checkbox column at the start of each row. |\n| selectedKeys | `string[]` | `[]` | Array of currently selected row keys. |\n| onSelectionChange | `(keys: string[]) => void` | - | Called when the set of selected row keys changes (via row checkbox or select-all). |\n\n**Example:**\n```tsx\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n```\n\n### ChatWindow\n\nProps for the `ChatWindow` composition.\n\nA messaging interface that composes `Avatar`, `Button`, `Spinner`, and `Icon` primitives.\nLayout is a flex column filling 100% height with a bordered `radius.lg` container.\nMessages from the current user align right with `colors.primary[600]` bubbles and white text.\nOther users' messages align left with `colors.gray[100]` bubbles. The message area\nauto-scrolls to the bottom on new messages via `scrollIntoView({ behavior: 'smooth' })`.\nThe text input sends on Enter (Shift+Enter for newline).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| messages | `ChatMessage[]` | - | Array of chat messages to display in chronological order. |\n| currentUserId | `string` | - | ID of the current user. Messages from this user render right-aligned with a primary color bubble. |\n| onSendMessage | `(content: string) => void` | - | Called when the user submits a message (Enter key or send button). |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the message list. |\n| typing | `{ name: string } \\| null` | - | When non-null, displays a typing indicator below the last message (e.g., \"Alice is typing...\"). |\n| placeholder | `string` | `'Type a message...'` | Placeholder text for the message input field. |\n| header | `ReactNode` | - | Optional header content rendered above the message area, separated by a bottom border. |\n\n**Example:**\n```tsx\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n```\n\n### NavigationBar\n\nProps for the `NavigationBar` composition.\n\nA horizontal or vertical navigation menu. Does not compose other ggui primitives\n(uses plain `<button>` and `<a>` elements). Active items are styled per variant:\n\n- `'default'` \u2014 active item gets `colors.primary[600]` text and medium font weight.\n- `'pills'` \u2014 active item gets a `radius.full` pill with `colors.primary[100]` background.\n- `'underline'` \u2014 active item gets a 2 px bottom border in `colors.primary[600]`.\n  When horizontal, the entire nav also has a 1 px bottom border.\n\nAll items have a 150 ms transition on all properties.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `NavItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Controls visual highlighting per variant style. |\n| onItemClick | `(item: NavItem) => void` | - | Called when a non-disabled item is clicked. For `<a>` elements, `preventDefault` is called first. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Layout direction. - `'horizontal'` \u2014 flex-row with 4 px gap. - `'vertical'` \u2014 flex-column with 2 px gap. |\n| variant | `'default' \\| 'pills' \\| 'underline'` | `'default'` | Visual style for active/inactive items. - `'default'` \u2014 text color change only. - `'pills'` \u2014 rounded pill background on active items. - `'underline'` \u2014 bottom border on active items. |\n\n**Example:**\n```tsx\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n```\n\n### FileUploader\n\nProps for the `FileUploader` composition.\n\nA drag-and-drop file upload area that composes `Button`, `Progress`, and `Icon` primitives.\nThe drop zone is a dashed-border container that highlights in `colors.primary[400]`/`colors.primary[50]`\non drag-over. Below the drop zone, each file in `files` is listed with its name, size,\noptional progress bar (for uploading status), and a remove button.\n\nFile validation (max size, max count) is applied client-side before calling `onFilesSelected`.\nFiles exceeding `maxSize` are silently filtered out; files exceeding `maxFiles` are truncated.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| files | `UploadedFile[]` | `[]` | Array of files currently in the upload queue, shown below the drop zone. |\n| onFilesSelected | `(files: File[]) => void` | - | Called when the user selects files via click or drag-and-drop. Receives native `File` objects after client-side filtering (maxSize, maxFiles). |\n| onFileRemove | `(fileId: string) => void` | - | Called when the user clicks the remove button on a file entry. |\n| accept | `string` | - | Accepted file types passed to the hidden `<input type=\"file\" accept=\"...\">`. E.g., `'image/*,.pdf'`. |\n| multiple | `boolean` | `true` | When true, allows selecting multiple files at once. |\n| maxSize | `number` | - | Maximum file size in bytes. Files exceeding this are silently excluded from the selection. |\n| maxFiles | `number` | - | Maximum number of files. Excess files beyond `maxFiles - files.length` are truncated. |\n| disabled | `boolean` | - | When true, the drop zone is visually dimmed (opacity 0.5) and non-interactive. |\n| dragDrop | `boolean` | `true` | When true, enables drag-and-drop on the drop zone. When false, the prompt text changes to \"Click to browse files\". |\n\n**Example:**\n```tsx\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n```\n\n### NotificationCenter\n\nProps for the `NotificationCenter` composition.\n\nA notification list with a header bar that composes `Button`, `Spinner`, and `Icon`\nprimitives. The header shows a \"Notifications\" title, an unread count badge\n(pill in `colors.primary[100]`), and \"Mark all read\" / \"Clear all\" buttons.\nEach notification item shows a colored status dot, title, message, timestamp,\n\"Mark as read\" link, and optional action. The list is scrollable (`overflowY: auto`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| notifications | `Notification[]` | - | Array of notifications to display, in the order provided. |\n| onMarkAsRead | `(id: string) => void` | - | Called when the user clicks \"Mark as read\" on an individual notification. |\n| onMarkAllAsRead | `() => void` | - | Called when the user clicks the \"Mark all read\" header button. Only shown when there are unread items. |\n| onDismiss | `(id: string) => void` | - | Called when the user clicks the dismiss (X) button on an individual notification. |\n| onClearAll | `() => void` | - | Called when the user clicks the \"Clear all\" header button. Only shown when there are any notifications. |\n| emptyText | `string` | `'No notifications'` | Text shown when `notifications` is empty and not loading. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the notification list. |\n\n**Example:**\n```tsx\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n```\n\n### Modal\n\nProps for the `Modal` composition.\n\nA dialog overlay that composes `Button`, `Icon`, and `Heading` primitives.\nThe overlay uses `animation.fadeIn` (`ggui-fadeIn`) and the dialog panel uses\n`animation.scaleIn` (`ggui-scaleIn`) \u2014 both GPU-composited (opacity + transform).\nWhen open, `document.body.style.overflow` is set to `'hidden'` to prevent background\nscrolling, and restored on close. The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`.\n\nSize widths: `sm` = 400 px, `md` = 500 px, `lg` = 640 px, `xl` = 800 px,\n`full` = 100vw (no border-radius, no padding).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls modal visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the modal (overlay click, escape key, or close button). |\n| title | `string` | - | Optional title rendered in the modal header via the `Heading` primitive (level 4). |\n| children | `ReactNode` | - | Modal body content rendered in a scrollable area (`overflowY: auto`). |\n| footer | `ReactNode` | - | Footer content rendered below the body, right-aligned with an 8 px gap, separated by a top border. |\n| size | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'` | Controls the width of the modal panel. - `'sm'` \u2014 400 px - `'md'` \u2014 500 px - `'lg'` \u2014 640 px - `'xl'` \u2014 800 px - `'full'` \u2014 100vw, no border-radius, stretches to fill viewport |\n| closeOnOverlayClick | `boolean` | `true` | When true, clicking the semi-transparent overlay behind the modal calls `onClose`. |\n| closeOnEscape | `boolean` | `true` | When true, pressing the Escape key calls `onClose`. |\n| showCloseButton | `boolean` | `true` | When true, renders a ghost close button (X icon) in the modal header. |\n\n**Example:**\n```tsx\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n```\n\n### CommandPalette\n\nProps for the `CommandPalette` composition.\n\nA searchable command menu (Cmd+K / Ctrl+K pattern) that composes `Spinner` and `Icon`\nprimitives. Appears as a centered overlay at 15vh from the top. Commands are filtered\nby label and description (case-insensitive substring match). Results are grouped under\nuppercase section headers. Keyboard navigation is fully supported:\nArrow Up/Down to navigate, Enter to select, Escape to close.\n\nWhen `recentIds` are provided and the search query is empty, matching commands appear\nin a \"Recent\" section at the top (deduplicated from their original groups).\n\nThe footer shows navigation hints: \"Up/Down Navigate\", \"Enter Select\", \"Esc Close\".\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls palette visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the palette (overlay click, Escape key, or after command selection). |\n| commands | `Command[]` | - | Full array of available commands. Filtered client-side by the search query. |\n| onSelect | `(command: Command) => void` | - | Called when a non-disabled command is selected (Enter key or click). The palette auto-closes after selection. |\n| placeholder | `string` | `'Search commands...'` | Placeholder text for the search input. |\n| recentIds | `string[]` | `[]` | IDs of recently used commands. When the query is empty, these appear in a \"Recent\" section at the top of the results. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the command list. |\n\n**Example:**\n```tsx\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n```\n\n### Footer\n\nProps for the `Footer` composition.\n\nA site footer with `role=\"contentinfo\"` that lays out a brand slot, link columns,\nsocial icons, and a bottom bar. Does not compose other ggui primitives (uses plain\nHTML elements). Content is constrained to `max-width: 1280px` with auto margins.\nLink columns use a responsive flex layout (`flex: 0 1 180px`). The bottom bar\nincludes copyright text, social links, and bottom-bar links separated by a top border.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| brand | `ReactNode` | - | Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`). |\n| columns | `FooterColumn[]` | - | Array of link columns rendered in a flex-wrap layout with 48 px gap. |\n| socialLinks | `FooterSocialLink[]` | - | Social media icon links rendered in the bottom bar. |\n| bottomText | `string` | - | Text displayed at the start of the bottom bar (e.g., copyright notice). |\n| bottomLinks | `FooterLink[]` | - | Links displayed in the bottom bar after social icons (e.g., Privacy, Terms). |\n| background | `string` | `colors.gray[50]` | Background color of the footer. |\n| bordered | `boolean` | `true` | When true, renders a 1 px top border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n```\n\n### Hero\n\nProps for the `Hero` composition.\n\nA prominent landing-page hero section that renders heading, description, CTA buttons,\nand an optional media slot. Does not compose other ggui primitives (uses plain HTML\nelements styled with design tokens). Content is constrained to `max-width: 1280px`.\n\nLayout modes:\n- `align='center'` \u2014 single-column centered layout with `max-width: 800px` text area.\n- `align='left'` \u2014 two-column side-by-side layout (50/50 split with media slot).\n\nSize controls vertical padding and font sizes:\n- `'sm'` \u2014 48 px vertical padding, 3xl heading, lg description.\n- `'md'` \u2014 80 px vertical padding, 4xl heading, xl description.\n- `'lg'` \u2014 120 px vertical padding, 5xl heading, xl description.\n\nThe primary action button uses `colors.primary[600]` fill; the secondary action uses\nan outlined style. When `overlay` is true with a `backgroundImage`, text switches to white\nand borders become semi-transparent.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| heading | `string` | - | Main heading text rendered as an `<h1>` with bold weight and tight line-height. |\n| description | `string` | - | Description paragraph rendered below the heading with relaxed line-height. |\n| primaryAction | `HeroAction` | - | Primary CTA button rendered with `colors.primary[600]` background and white text. |\n| secondaryAction | `HeroAction` | - | Secondary CTA button rendered with a transparent background and a 1 px border. |\n| media | `ReactNode` | - | Media element (image, video, illustration) rendered beside or below the text content. |\n| align | `'center' \\| 'left'` | `'center'` | Text and layout alignment. - `'center'` \u2014 centered single-column layout. - `'left'` \u2014 left-aligned text with media in a right column (50/50 split). |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls vertical padding and heading/description font sizes. - `'sm'` \u2014 compact (48 px padding, 3xl/lg fonts). - `'md'` \u2014 standard (80 px padding, 4xl/xl fonts). - `'lg'` \u2014 spacious (120 px padding, 5xl/xl fonts). |\n| background | `string` | `colors.white (when no backgroundImage is set)` | Background color of the hero section. |\n| backgroundImage | `string` | - | Background image URL applied as `background-size: cover; background-position: center`. |\n| overlay | `boolean` | `false` | When true and `backgroundImage` is set, renders a semi-transparent black overlay (`rgba(0,0,0,0.5)`) and switches text to white/semi-transparent white for contrast. |\n\n**Example:**\n```tsx\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n```\n\n### Support Types\n\n**SidebarItem:**\n\nA single navigation entry in a `Sidebar`. Supports nested children for\ncollapsible sub-menus and an optional badge slot.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the item. Hidden when the sidebar is collapsed. |\n| icon | `ReactNode` | Leading icon rendered before the label. Remains visible when collapsed. |\n| href | `string` | Optional URL associated with this item (not rendered as a link by default). |\n| badge | `ReactNode` | Trailing badge element (e.g., unread count). Hidden when collapsed. |\n| children | `SidebarItem[]` | Nested child items. When present, the item acts as a collapsible section (chevron indicator shown). |\n| disabled | `boolean` | When true, the item is visually dimmed and non-interactive (`cursor: not-allowed`). |\n\n**Comment:**\n\nA single comment entry in a `CommentThread`. Supports nested replies\nand emoji reactions with counts.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this comment. |\n| author | `{     /** Display name of the author. */     name: string;     /** URL for the author's avatar image. Passed to the `Avatar` primitive. */     avatar?: string;   }` | Comment author metadata. |\n| content | `string` | The comment body text. |\n| timestamp | `string \\| Date` | Timestamp of the comment. Rendered via `toLocaleString()` when a `Date` object. |\n| replies | `Comment[]` | Nested reply comments. Each reply is rendered indented 40 px deeper. |\n| reactions | `{ emoji: string; count: number }[]` | Emoji reactions with their aggregated counts (e.g., `{ emoji: \"\u{1F44D}\", count: 3 }`). |\n\n**DataTableColumn:**\n\nColumn definition for a `DataTable`. Controls header text, width, alignment,\nsorting, and custom cell rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key on the row object used to extract cell values. Also serves as the sort key. |\n| header | `string` | Column header text displayed in the `<thead>`. |\n| width | `number \\| string` | Column width as a CSS value (number for pixels, string for any CSS unit). |\n| sortable | `boolean` | When true, the column header is clickable and triggers `onSort`. An arrow icon indicates direction. |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When omitted, the raw value is stringified via `String()`. |\n| align | `'left' \\| 'center' \\| 'right'` | Text alignment for both header and body cells. |\n\n**ChatMessage:**\n\nA single message in a `ChatWindow`. Includes sender metadata, delivery status,\nand a timestamp.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this message. |\n| content | `string` | The message body text. |\n| sender | `{     /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */     id: string;     /** Display name of the sender. */     name: string;     /** Avatar image URL. Only shown for non-current-user messages (xs size). */     avatar?: string;   }` | Sender metadata used for avatar rendering and alignment. |\n| timestamp | `string \\| Date` | Message timestamp. Rendered as `HH:MM` via `toLocaleTimeString` when a `Date` object. |\n| status | `'sending' \\| 'sent' \\| 'delivered' \\| 'read' \\| 'error'` | Delivery status indicator shown on the current user's messages. - `'sending'` \u2014 shows a dot bullet - `'sent'` \u2014 shows a single checkmark - `'delivered'` \u2014 shows double checkmarks - `'read'` \u2014 shows double checkmarks (same visual as delivered) - `'error'` \u2014 shows an exclamation mark |\n\n**NavItem:**\n\nA single navigation entry in a `NavigationBar`. Supports nested children\nfor sub-menus (rendered by the parent via dropdown, not built-in).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the navigation link. |\n| href | `string` | URL for the item. When provided, renders an `<a>` element instead of `<button>`. |\n| icon | `ReactNode` | Optional icon rendered before the label. |\n| children | `NavItem[]` | Nested child items (for sub-menu structures; rendering is consumer-defined). |\n| disabled | `boolean` | When true, the item is visually dimmed (opacity 0.5) and non-interactive. |\n\n**UploadedFile:**\n\nA file entry in the `FileUploader` composition. Tracks upload progress,\nstatus, and optional error messages.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this file entry. Used as a key and for removal callbacks. |\n| name | `string` | Original file name. Rendered with text-overflow ellipsis when too long. |\n| size | `number` | File size in bytes. Formatted as B/KB/MB/GB for display. |\n| type | `string` | MIME type of the file (e.g., `'image/png'`). |\n| progress | `number` | Upload progress as a percentage (0-100). Shown via the `Progress` primitive when status is `'uploading'`. |\n| status | `'pending' \\| 'uploading' \\| 'success' \\| 'error'` | Current upload lifecycle status. - `'pending'` \u2014 file selected but upload not started. - `'uploading'` \u2014 upload in progress; `progress` bar is shown. - `'success'` \u2014 upload completed. - `'error'` \u2014 upload failed; `error` message is shown in `colors.error[500]`. |\n| error | `string` | Error message displayed when status is `'error'`. |\n| url | `string` | The remote URL of the uploaded file after successful upload. |\n\n**Notification:**\n\nA single notification entry in the `NotificationCenter`. Supports semantic type coloring,\nread state, and an optional inline action button.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this notification. |\n| title | `string` | Notification title rendered in medium weight. |\n| message | `string` | Optional body text rendered below the title in a smaller font. |\n| timestamp | `string \\| Date` | Timestamp of the notification. Rendered via `toLocaleString()` when a `Date` object. |\n| read | `boolean` | Read state. Unread notifications get a `colors.primary[50]` background and a colored status dot matching the notification type. |\n| type | `'info' \\| 'success' \\| 'warning' \\| 'error'` | Semantic type that controls the status dot color on unread notifications. - `'info'` \u2014 `colors.info[500]` (blue) - `'success'` \u2014 `colors.success[500]` (green) - `'warning'` \u2014 `colors.warning[500]` (amber) - `'error'` \u2014 `colors.error[500]` (red) |\n| icon | `ReactNode` | Optional icon rendered alongside the notification (not used by the default implementation). |\n| action | `{     /** Button label text. */     label: string;     /** Click handler for the action. */     onClick: () => void;   }` | Optional inline action button rendered next to the timestamp. |\n\n**Command:**\n\nA single command entry in a `CommandPalette`. Commands can be grouped,\nhave keyboard shortcuts, and support a disabled state.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this command. |\n| label | `string` | Display label for the command. Searchable by the palette's query filter. |\n| description | `string` | Optional description text shown below the label. Also searchable. |\n| icon | `ReactNode` | Icon rendered at the start of the command row. |\n| shortcut | `string` | Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element. |\n| group | `string` | Group name for visual sectioning. Commands with the same group are rendered under a shared header. Defaults to `'Commands'` if omitted. |\n| disabled | `boolean` | When true, the command is visually dimmed and cannot be selected. |\n\n**FooterLink:**\n\nA single link entry in a footer column or the bottom bar. Supports both\n`href` navigation and `onClick` handlers (onClick takes precedence via `preventDefault`).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for the link. |\n| href | `string` | URL for the link. |\n| onClick | `() => void` | Click handler. When provided, `preventDefault` is called on the anchor click. |\n\n**FooterColumn:**\n\nA named column of links in the `Footer` layout. Each column has an optional title\nand a list of links rendered as a vertical stack with 10 px gap.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| title | `string` | Column heading rendered as an `<h4>` with semibold weight. |\n| links | `FooterLink[]` | Links displayed in this column. |\n\n**FooterSocialLink:**\n\nA social media link in the `Footer` bottom bar. Rendered as an icon-only anchor\nwith `aria-label` for accessibility.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Accessible label for the social link (used as `aria-label`). |\n| href | `string` | URL for the social media profile or page. |\n| icon | `ReactNode` | Icon element rendered inside the anchor (typically an SVG or `Icon` primitive). |\n\n**HeroAction:**\n\nA call-to-action button definition for the `Hero` composition.\nUsed for both the primary (filled) and secondary (outlined) action buttons.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Button label text. |\n| onClick | `() => void` | Click handler for the button. |\n| href | `string` | Optional URL (not used by the default implementation; available for consumer routing). |\n\n\n## System Conventions\n\n### onChange Behavior (CRITICAL)\n\nAll form control onChange handlers receive the VALUE DIRECTLY, not a React event object.\n\n```tsx\n// CORRECT \u2014 onChange receives value directly\n<Input value={name} onChange={setName} />\n<Input value={email} onChange={(value) => setEmail(value)} />\n<Select value={country} onChange={setCountry} options={countries} />\n<Checkbox checked={agreed} onChange={setAgreed} />\n\n// WRONG \u2014 DO NOT use e.target.value!\n<Input value={name} onChange={(e) => setName(e.target.value)} /> // WILL BREAK\n```\n\nApplies to: Input, TextArea, Select, Checkbox, RadioGroup, Slider, Tabs, Accordion.\n\n### Available Motion & Animation\n\nRender `<MotionKeyframes />` once (anywhere in tree) to enable all keyframes.\n\n**Entrance/exit:** fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n**State feedback:** flash (background-color highlight), pulse (opacity breathing), bounce (scale overshoot)\n**Easing:** linear, easeIn, easeOut, easeInOut, spring (bouncy)\n**Durations:** instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n\n```tsx\n// Entrance animation on mount\n<div style={{ animation: 'ggui-fadeIn 200ms ease-out' }}>Content</div>\n\n// Stagger list items\n{items.map((item, i) => (\n  <div key={item.id} style={{ animation: \\`ggui-slideInUp 300ms ease-out \\${i * 50}ms both\\` }}>\n    {item.name}\n  </div>\n))}\n\n// Flash highlight when data changes (e.g., stock price update)\n// useAnimationKey returns a key that increments when dep changes \u2192 remounts element \u2192 replays animation\nconst priceKey = useAnimationKey(stock.price);\n<div key={priceKey} style={{\n  animation: animation.flash,\n  '--ggui-flash-color': stock.change > 0 ? 'var(--ggui-color-success-100)' : 'var(--ggui-color-error-100)',\n} as React.CSSProperties}>\n  {stock.price}\n</div>\n\n// Respect reduced-motion preference\nconst { motionEnabled } = useMotion();\n<div style={motionEnabled ? { animation: 'ggui-scaleIn 200ms ease-out' } : undefined}>\n  Content\n</div>\n```\n\n### Elevation System\n\n6 levels mapping shadow intensity to z-index for layering:\n- Level 0: flat (no shadow, z: auto) \u2014 inline content\n- Level 1: sm shadow (z: auto) \u2014 cards, sections\n- Level 2: md shadow (z: 1000) \u2014 dropdowns, popovers\n- Level 3: lg shadow (z: 1200) \u2014 sticky banners\n- Level 4: xl shadow (z: 1400) \u2014 modals, dialogs\n- Level 5: 2xl shadow (z: 1800) \u2014 tooltips, toasts\n\n### Import Constraints\n\nOnly these imports are allowed:\n- `react`\n- `@ggui-ai/design` \u2014 the whole design system (primitives, components, compositions, and the `Clickable` / `Hoverable` / `Pressable` traits) is one import; there are no subpaths\n- `@ggui-ai/wire` (wire hooks)\n\nNo external libraries (lodash, date-fns, etc.). No fetch(). No eval().";
+    PRIMITIVES_DOCUMENTATION = "# ggui Primitives & Design System Reference\n\n> You are a world-class UI engineer working with ggui's component library for the first time.\n> This reference documents every available component, prop, and convention.\n> Components handle theming automatically via built-in variants \u2014 pick the right variant and the theme does the rest.\n> For custom styling beyond variants, use CSS variables: var(--ggui-*, fallback).\n\n## Primitives\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Container\n\nContainer -- Width-constrained wrapper that centers content horizontally.\n\nRenders a `<div>` with `width: 100%` and a `maxWidth` constraint.\nWhen `center` is true (the default), applies `margin: 0 auto`.\nNo background, border, or shadow -- use Card for visual containment.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| maxWidth | `'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| 'full' \\| string` | `'lg'` | Maximum width constraint. Accepts a preset token or any CSS width string. - `'xs'` -- 320px - `'sm'` -- 480px - `'md'` -- 640px - `'lg'` -- 768px - `'xl'` -- 1024px - `'2xl'` -- 1280px - `'3xl'` -- 1536px - `'full'` -- 100%  Custom strings (e.g., `'900px'`, `'60ch'`) are passed through as-is. |\n| center | `boolean` | `true` | Whether to center the container horizontally via `margin: 0 auto`. |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n```\n\n### Card\n\nCard -- Container with background, shadow, and optional border.\n\nRenders a `<div>` with:\n- Background: `var(--ggui-color-container)`\n- Border (when enabled): `1px solid var(--ggui-color-outlineVariant)`\n- Shadow and radius controlled by design tokens via CSS variables.\n- No built-in transitions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'lg'` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| shadow | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'sm'` | Shadow elevation level. Maps to design tokens: - `'none'` -- no shadow - `'sm'` -- var(--ggui-shape-shadow-sm) -- subtle, default - `'md'` -- var(--ggui-shape-shadow-md) -- dialogs, emphasized sections - `'lg'` -- var(--ggui-shape-shadow-lg) -- floating panels - `'xl'` -- var(--ggui-shape-shadow-xl) -- popovers, modals |\n| border | `boolean` | `true` | Whether to render a 1px border using `var(--ggui-color-outlineVariant)`. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'lg'` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `'default'` | Semantic surface slot. Same vocabulary as ; see that prop's docs for the full slot table. Default Card surface is `'default'` (the active theme's `--ggui-color-container`); pair with `shadow=\"md\"\\|\"lg\"` for elevated cards, `'hero'` for a greeting or hero card (the theme's hero ground, right on a light or a dark host), or `'inverted'` for a dark testimonial-style card on a light theme. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n\n**Example:**\n```tsx\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n```\n\n### Stack\n\nStack -- Flexbox layout primitive for arranging children along a single axis.\n\nRenders a `<div>` with `display: flex`. Default layout is vertical (column).\nAll flex shorthand values (`align`, `justify`, `wrap`) are abstracted into\nsemantic prop names.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Main axis direction. - `'vertical'` -- `flex-direction: column` - `'horizontal'` -- `flex-direction: row` |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'sm'` | Gap between children. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| align | `'start' \\| 'center' \\| 'end' \\| 'stretch'` | `'stretch'` | Cross-axis alignment (maps to `align-items`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'stretch'` -- stretch (children fill cross-axis) |\n| justify | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'` | Main-axis content distribution (maps to `justify-content`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'between'` -- space-between - `'around'` -- space-around - `'evenly'` -- space-evenly |\n| wrap | `boolean` | `false` | Whether children wrap to the next line when they overflow. Maps to `flex-wrap: wrap` when true. |\n\n**Example:**\n```tsx\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n```\n\n### Grid\n\nGrid -- 2-D layout primitive. Arranges children into rows AND\ncolumns; reach for it when Stack/Row's single-axis flow isn't\nenough (card galleries, dashboards, stat grids).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| columns | `number \\| ResponsiveColumns` | `2` | Column count. Three forms: - a number \u2014 that many equal columns at every width (`columns={3}`); - a  map \u2014 explicit counts per breakpoint   (`columns={{ base: 1, md: 3 }}` = 1 column on mobile, 3 from `md`).   Use this when the request names exact per-breakpoint counts   (\"3 per row on desktop, 1 on mobile\"). Ignored entirely when `minColumnWidth` is set. |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'md'` | Gap between cells. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`); a number is pixels. |\n| minColumnWidth | `number \\| string` | `undefined (use `columns`)` | When set, the grid becomes responsive \u2014 it fits as many equal columns as possible, each at least this wide, and `columns` is ignored. A number is treated as pixels. |\n\n**Example:**\n```tsx\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n```\n\n### Skeleton\n\nSkeleton -- a pulsing placeholder for content that has not loaded\nyet. ggui UIs are agent-driven (props arrive late, streams start\nempty), so a loading frame is the rule \u2014 render `Skeleton` instead\nof a blank screen or a hand-rolled pulsing `<div>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| variant | `'rect' \\| 'text' \\| 'circle'` | `'rect'` | Shape preset. - `'rect'` -- a block (default); pair with `width` / `height`. - `'text'` -- a single text line (height ~1em). - `'circle'` -- equal width/height, fully rounded (avatar slot). |\n| width | `number \\| string` | - | Width. A number is pixels. Defaults to `100%` (`2.5rem` for circle). |\n| height | `number \\| string` | - | Height. A number is pixels. Defaults by variant when unset. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'sm'` | Corner radius. Prefer a radius-scale name. Ignored for `variant=\"circle\"` (always fully round). |\n\n**Example:**\n```tsx\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n```\n\n### Box\n\nBox -- Generic container with padding, margin, background, and border-radius.\n\nRenders a plain `<div>`. Unlike Card, Box has no default background, shadow,\nor border -- it is a blank canvas for custom styling. Use it for layout\nspacing, colored sections, or wrapping arbitrary content.\n\nWhen both `paddingX`/`paddingY` and `padding` are provided, the axis-specific\nprops take precedence and `padding` is ignored.\n\nCSS variables used: none (all values are passed through directly).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all four sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. Ignored when `paddingX` or `paddingY` is set. |\n| paddingX | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Horizontal (left + right) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingY`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingY`, vertical padding defaults to 0. |\n| paddingY | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Vertical (top + bottom) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingX`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingX`, horizontal padding defaults to 0. |\n| margin | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no margin)` | Margin applied to all four sides. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'hero' \\| 'transparent'` | `undefined (transparent)` | Semantic surface slot. Picks the right `var(--ggui-color-*)` background token from the active theme. The ONLY way to set a theme-tracking background fill on Box.  Available slots: - `'default'` \u2014 base container surface (most common) - `'elevated'` \u2014 same fill, intended to be paired with shadow   (use Card.shadow for actual elevation) - `'sunken'` \u2014 recessed / inset region (the `sunken` role; `surfaceVariant` was retired by ggui#987) - `'accent'` \u2014 highlighted / branded fill (`primary-50` token) - `'inverted'` \u2014 dark surface in light mode, light in dark   (testimonials, code-snippet cards, hero panels). The surface owns   ALL its inks: body text, `muted` / `subtle` labels, chips and   outlines inside it re-map to inverse-derived values by cascade \u2014   no `tone=\"inverse\"` needed, and no hand-picked greys. - `'hero'` \u2014 the hero panel's ground: brand-tinted on a light host, the   ink pair on a dark one (`heroGround` / `onHeroGround`, derived per mode)   \u2014 reach for it for a greeting or hero card instead of guessing the   host's darkness with `'inverted'`; it owns its subtree's inks likewise. - `'transparent'` \u2014 explicit \"no fill\"  For non-theme-mapped brand colors (e.g. a partner's exact brand hex like Stripe purple) use the  escape \u2014 every other hex / rgba on Box is rejected by tier-0 self-check. |\n| bleed | `boolean` | `false` | Span the expanded frame's inset edge to edge (ggui#1083). In a host's fullscreen canvas the frame gives the root a 16 px content inset; a `bleed` element (a full-width row the design means to touch the panel's edges) takes that inset back and meets the panel edge. A `surface=\"hero\"` band that opens the card already does, without it. Ignored everywhere else, so it is safe on any card. |\n| assetColor | `string` | `undefined` | Asset color escape \u2014 the typed valve for legitimate non-theme color values (a partner's exact brand hex, a fixed product surface, etc.). Renders as the Box background.  **MUST be paired with .** The semantic name is human-readable documentation of why this color bypasses the theme \u2014 e.g. `\"stripe-brand-purple\"`, `\"slack-aubergine\"`. Tier-0 self-check allows hex / rgba inside `assetColor` ONLY when `assetSemantic` is a non-empty string; one without the other fails the check.  Reach for `surface` first. This escape exists for the small set of cases where the operator's theme MUST NOT override the value (brand identity rendering). |\n| assetSemantic | `string` | `undefined` | Human-readable semantic label that documents why  bypasses the theme. Required when `assetColor` is set; tier-0 self-check rejects empty strings or a missing `assetSemantic` next to a hex `assetColor`.  Examples: `\"stripe-brand-purple\"`, `\"slack-aubergine\"`, `\"partner-logo-orange\"`. Pure documentation \u2014 no rendering effect. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `undefined (no rounding)` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n```\n\n### Divider\n\nDivider -- A 1px line to visually separate content sections.\n\nRenders an `<hr>` (horizontal) or `<div>` (vertical) with `role=\"separator\"`.\n- Horizontal: 1px tall, full width, with vertical margin.\n- Vertical: 1px wide, stretches to parent height via `align-self: stretch`,\n  with horizontal margin. Works best inside a horizontal Stack or Row.\n\nDefault color: `var(--ggui-color-outlineVariant)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Line direction. - `'horizontal'` -- renders `<hr>`, full width, 1px height, margin top/bottom - `'vertical'` -- renders `<div>`, 1px width, `align-self: stretch`, margin left/right |\n| margin | `number \\| string` | `16` | Spacing around the divider. Numbers are treated as pixels. Applied as vertical margin for horizontal dividers, horizontal margin for vertical. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-outlineVariant)`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a quiet outline-variant tint when unset (independent of the tone slots). |\n\n**Example:**\n```tsx\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n```\n\n### Spacer\n\nSpacer -- Invisible spacing element, either fixed-size or flexible.\n\nRenders an empty `<div>`.\n- Fixed mode (number): sets both `width` and `height` to the given pixel\n  value with `flex-shrink: 0`, creating rigid spacing in any direction.\n- Flex mode (`'flex'`): sets `flex: 1`, expanding to fill remaining space\n  in a flex container. Useful for pushing siblings apart.\n\nCSS variables used: none.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number \\| 'flex'` | `16` | Spacing amount. - Number: fixed square spacer (width and height in pixels, `flex-shrink: 0`). - `'flex'`: expands to fill available space (`flex: 1`). |\n\n**Example:**\n```tsx\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n```\n\n### Text\n\nText -- Versatile typography primitive for body copy, captions, and labels.\n\nRenders as `<p>` by default (configurable via `is`). Typography is\ncomposed from three orthogonal axes: `size` (font size, with a\nmatching line-height built in), `weight`, and `tone` (semantic\ncolor). `caps` adds the uppercase, letter-spaced treatment for tiny\nsection labels (the classic overline/eyebrow look) \u2014 the label's text\ncomes from a prop, never from the component: an invented eyebrow is copy\nnothing can change.\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll text renders with `margin: 0` (no default paragraph spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| size | `'xs' \\| 'sm' \\| 'base' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| '4xl'` | `'base'` | Font size. Maps to CSS variables with pixel fallbacks; each size carries a matching line-height (1.5 for `xs`--`base`, 1.625 for `lg`, then tightening on display sizes: 1.375 at `xl`, 1.25 from `2xl` up): - `'xs'` -- var(--ggui-font-size-xs) (12px) - `'sm'` -- var(--ggui-font-size-sm) (14px) - `'base'` -- var(--ggui-font-size-base) (16px) - `'lg'` -- var(--ggui-font-size-lg) (18px) - `'xl'` -- var(--ggui-font-size-xl) (20px) - `'2xl'` -- var(--ggui-font-size-2xl) (24px) - `'3xl'` -- var(--ggui-font-size-3xl) (30px) - `'4xl'` -- var(--ggui-font-size-4xl) (36px) |\n| weight | `'normal' \\| 'medium' \\| 'semibold' \\| 'bold'` | `'normal'` | Font weight. Maps to CSS variables with numeric fallbacks: - `'normal'` -- var(--ggui-font-weight-normal) - `'medium'` -- var(--ggui-font-weight-medium) - `'semibold'` -- var(--ggui-font-weight-semibold) - `'bold'` -- var(--ggui-font-weight-bold) |\n| caps | `boolean` | `false` | When true, uppercases the text and adds 0.05em letter-spacing -- the eyebrow/overline treatment for tiny section labels. Pair with `size=\"xs\" weight=\"semibold\" tone=\"muted\"`. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Picks the right `var(--ggui-color-*)` token from the active theme. The theme decides what each tone LOOKS like \u2014 `'muted'` is a quiet warm grey on Claudic, a cool slate on Indigo, dim cyan on Neon-Noir. Components that use `tone` track the operator's theme switch automatically.  Available slots: `'default'` (primary body text), `'muted'` (secondary / metadata), `'subtle'` (very-low-emphasis hint), `'emphasized'` (branded accent), `'loud'` (strongest accent \u2014 the theme's readable accent ink), `'success'` / `'warning'` / `'error'` / `'info'` (status text), `'inverse'` (text on dark surface), `'inherit'` (parent's color).  `tone` is the ONLY way to set a Text color. The legacy `color?: string` escape was retired \u2014 raw color strings bypass theming and silently override the operator's preset. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n| truncate | `boolean` | `false` | When true, clips overflowing text with an ellipsis. Applies `overflow: hidden`, `text-overflow: ellipsis`, and `white-space: nowrap`. |\n| is | `'p' \\| 'span' \\| 'div' \\| 'label'` | `'p'` | HTML element to render. Choose based on semantic context: - `'p'` -- paragraph (default, block-level) - `'span'` -- inline text within a sentence - `'div'` -- generic block container - `'label'` -- form label (pair with `htmlFor`) |\n| id | `string` | - | `id` for the rendered element \u2014 anchor an in-page link, or pair with a form control's `aria-labelledby`. |\n| htmlFor | `string` | - | Associates an `is=\"label\"` element with a form control by the control's `id`. Only meaningful when `is=\"label\"`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">{props.section}</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n```\n\n### Heading\n\nHeading -- Semantic heading element (h1-h6) with preset typography styles.\n\nRenders the corresponding `<h1>`-`<h6>` HTML element based on `level`.\nEach level has a preset font size, weight, line height, and letter spacing\nfrom the heading typography tokens:\n- Level 1: 36px / bold / 1.25 line-height / -0.025em tracking\n- Level 2: 30px / bold / 1.25 line-height / -0.025em tracking\n- Level 3: 24px / semibold / 1.375 line-height / 0em tracking\n- Level 4: 20px / semibold / 1.375 line-height / 0em tracking\n- Level 5: 18px / semibold / 1.5 line-height / 0em tracking\n- Level 6: 16px / semibold / 1.5 line-height / 0em tracking\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll headings render with `margin: 0` (no default heading spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| level | `1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6` | `2` | Semantic heading level. Determines both the HTML element (`<h1>`-`<h6>`) and the preset typography style. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Same vocabulary as ; see that prop's docs for the full slot table. `tone` is the ONLY way to set a Heading color \u2014 the legacy `color?: string` escape was retired so the operator's theme always wins. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n```\n\n### Button\n\nButton -- A clickable button primitive with multiple visual variants and sizes.\n\nRenders a native `<button>` element styled with inline CSS derived from design-token\nCSS variables. Supports a loading spinner, left/right icon slots, and a cross-platform\n`onPress` alias for `onClick`.\n\nBase styles applied to every variant:\n- `border-radius: var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- `font-weight: var(--ggui-font-weight-medium)`\n- `box-shadow: var(--ggui-shape-shadow-sm)`\n- `gap: var(--ggui-spacing-2)` between icon and text\n- Transitions: background-color, box-shadow, opacity at 200ms ease-in-out\n\nDisabled or loading: `opacity: 0.5`, `cursor: not-allowed`, click handler suppressed.\n\nAlso extends native `ButtonHTMLAttributes` (except `style`/`className`), so props\nlike `type`, `form`, `aria-*`, and `data-*` are forwarded to the `<button>` element.\nThe `type` prop defaults to `'button'` (not `'submit'`), preventing accidental form\nsubmissions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'primary' \\| 'secondary' \\| 'outline' \\| 'ghost' \\| 'danger'` | `'primary'` | Visual style. Maps to CSS variables: - `'primary'` -- `var(--ggui-color-primary-600)` background, white text, no border - `'secondary'` -- `var(--ggui-color-sunken)` background, `var(--ggui-color-onSunken)` text, no border - `'outline'` -- transparent background, `1px solid var(--ggui-color-primary-600)` border, label in the surface's   on-colour (`onContainer`) so it reads on any ground \u2014 the brand shows on the border, never as label ink on a dark theme - `'ghost'` -- transparent background, `var(--ggui-color-onSunken)` text, no border - `'danger'` -- `var(--ggui-color-error-600)` background, white text, no border |\n| size | `'xs' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and minimum height: - `'xs'` -- padding `4px 8px`, font `var(--ggui-font-size-xs)`, min-height 24px - `'sm'` -- padding `6px 12px`, font `var(--ggui-font-size-sm)`, min-height 32px - `'md'` -- padding `10px 16px`, font `var(--ggui-font-size-sm)`, min-height 40px - `'lg'` -- padding `12px 24px`, font `var(--ggui-font-size-base)`, min-height 48px |\n| fullWidth | `boolean` | `false` | When true, sets `width: 100%` so the button fills its container. |\n| loading | `boolean` | `false` | When true, replaces children with a 16px `Spinner` (color: `currentColor`) and disables interaction (same effect as `disabled`). |\n| type | `'button' \\| 'submit' \\| 'reset'` | `'button'` | The HTML button type. Defaults to `'button'`, so a Button inside a `<form>` never submits it on click: the ONE control that submits the form sets `type=\"submit\"`; secondary controls keep the default. |\n| leftIcon | `ReactNode` | - | ReactNode rendered before children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| rightIcon | `ReactNode` | - | ReactNode rendered after children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| onPress | `() => void` | - | Alias for `onClick` for cross-platform compatibility (React Native convention). If both `onClick` and `onPress` are provided, `onClick` takes precedence. |\n\n**Example:**\n```tsx\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n```\n\n### Input\n\nInput -- A single-line text input with label, validation, and helper text.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<input>`,\nand an optional message `<span>` for error or helper text.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)`\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n  `var(--ggui-color-onSunken)`\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<input>` via `htmlFor`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\nWhen `required` is true, a red asterisk is appended to the label.\n\nAlso extends native `InputHTMLAttributes` (except `style`, `className`, `onChange`,\n`size`), so props like `autoFocus`, `name`, `pattern`, `aria-*` are forwarded.\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<input>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the input. Linked to the input via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the input is empty. |\n| value | `string` | - | Controlled value of the input. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| type | `'text' \\| 'email' \\| 'password' \\| 'number' \\| 'tel' \\| 'url' \\| 'search' \\| 'date' \\| 'time' \\| 'datetime-local'` | `'text'` | HTML input type. Determines browser behavior (keyboard on mobile, validation, masking). The date/time types render the browser's native, localized, keyboard-accessible picker; their `value` stays an ISO string (`'2026-07-29'`, `'14:30'`, `'2026-07-29T14:30'`) delivered through the usual value-first `onChange`. |\n| error | `string` | - | Error message displayed below the input in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the input in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<input>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n```\n\n### TextArea\n\nTextArea -- A multiline text input with label, validation, character count, and auto-resize.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<textarea>`,\nand a footer row with error/helper text on the left and character count on the right.\n\nStyling:\n- Padding: `10px 12px`, font: `var(--ggui-font-size-sm)`, `font-family: inherit`\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Resize: `vertical` by default, `none` when `autoResize` is true\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: same label/error linking pattern as Input (auto-generated ids,\n`aria-invalid`, `role=\"alert\"` on error message).\n\nAlso extends native `TextareaHTMLAttributes` (except `style`, `className`, `onChange`).\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<textarea>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the textarea. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the textarea is empty. |\n| value | `string` | - | Controlled value of the textarea. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| rows | `number` | `4` | Number of visible text rows (native `rows` attribute on `<textarea>`). |\n| error | `string` | - | Error message displayed below the textarea in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the textarea in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<textarea>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| maxLength | `number` | - | Maximum character length (native `maxLength` attribute). Also used as the denominator in the character count display when `showCount` is true. |\n| showCount | `boolean` | `false` | When true AND `maxLength` is set, displays a `{current}/{max}` character counter in the footer row (right-aligned, `var(--ggui-font-size-xs)`). Has no effect without `maxLength`. |\n| autoResize | `boolean` | `false` | When true, sets CSS `resize: none` on the textarea. The flag disables manual resizing to signal that external logic handles sizing. The component does NOT auto-adjust height based on content in the current implementation. |\n\n**Example:**\n```tsx\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n```\n\n### Select\n\nSelect -- A native dropdown selection primitive with label and validation.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<select>`\nwith custom styling, and an optional message `<span>`.\n\nThe native `<select>` has `appearance: none` with a custom chevron SVG rendered\nas a `background-image` (right-aligned, 12px, onSurfaceVariant color). Extra right\npadding (36px) accommodates the chevron.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)` when a value is selected,\n  `var(--ggui-color-onSunken)` when showing placeholder\n- Border radius: `var(--ggui-shape-radius-control)` \u2014 the control ROLE (the host's button/field radius; falls to `var(--ggui-shape-radius-md)`)\n- Cursor: `pointer` (normal), `not-allowed` (disabled)\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<select>`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\n\nAlso extends native `SelectHTMLAttributes` (except `style`, `className`,\n`onChange`, `size`).\n\n**IMPORTANT:** `onChange` receives the selected value string directly, NOT a\nReact `ChangeEvent`. This differs from native `<select>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the select. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of the `options[].value` strings. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the selected option's value string directly, NOT a React event. |\n| options | `SelectOption[]` | - | Array of selectable options. Rendered as native `<option>` elements. Must contain at least one option (or use `placeholder` for an empty-state prompt). |\n| placeholder | `string` | - | Placeholder text rendered as a disabled `<option value=\"\">` at the top of the list. Shown when no value is selected. |\n| error | `string` | - | Error message displayed below the select in `var(--ggui-color-error-500)`. When set, the border turns red and the message has `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the select in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)` and cursor becomes `not-allowed`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n```\n\n### Checkbox\n\nCheckbox -- A custom-styled checkbox with label and description.\n\nRenders a `<label>` wrapper containing a visually-hidden native `<input type=\"checkbox\">`\noverlaid by a custom 18x18px visual box. Supports checked, unchecked, and indeterminate\nstates, each with a distinct SVG icon (checkmark or horizontal dash).\n\nStyling:\n- Box border: `2px solid var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-outline)` (unchecked)\n- Box fill: `var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-container)` (unchecked)\n- Check/dash icon: white SVG, 12x12px\n- Box radius: `var(--ggui-shape-radius-sm)`\n- Transition: all 0.2s\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`\n- Description: `var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`\n- Gap between box and text: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the boolean checked state directly, NOT a\nReact `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary label text rendered beside the checkbox box. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean checked state directly, NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5` and `cursor: not-allowed`. The native input is also disabled, preventing keyboard and click interaction. |\n| description | `string` | - | Secondary description text rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| indeterminate | `boolean` | `false` | When true, displays a horizontal dash instead of a checkmark. Used for \"select all\" states where some (but not all) children are checked. The `indeterminate` property is set via a ref on the native `<input>`. Visually identical to `checked` in terms of border and fill color. |\n\n**Example:**\n```tsx\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n```\n\n### Toggle\n\nToggle -- A switch/toggle input rendered as a pill-shaped track with a sliding knob.\n\nRenders a `<label>` wrapper with a `<div role=\"switch\">` track and an animated\ncircular knob. Does NOT use a native `<input>` -- keyboard interaction is handled\nmanually (Space and Enter keys toggle the state). The element is focusable via\n`tabIndex={0}` and shows a focus ring on focus.\n\nStyling:\n- Track (on): `var(--ggui-color-primary-600)`\n- Track (off): `var(--ggui-color-outline)`\n- Knob: white circle with `var(--ggui-shape-shadow-sm)`\n- Focus ring: `0 0 0 3px var(--ggui-color-primary-200)`\n- Transitions: background-color, box-shadow, knob position at 200ms ease-in-out\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`, `tabIndex: -1`\n- Gap between toggle and label: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the new boolean state directly (inverted from\ncurrent), NOT a React event.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label text rendered to the right of the toggle track. Also used as `aria-label` on the switch element. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked (on/off) state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean state directly (i.e., `!checked`), NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5`, `cursor: not-allowed`, and removes the element from tab order (`tabIndex: -1`). Click and keyboard handlers are suppressed. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track and knob dimensions: - `'sm'` -- track 36x20px, knob 16px diameter - `'md'` -- track 44x24px, knob 20px diameter - `'lg'` -- track 52x28px, knob 24px diameter |\n\n**Example:**\n```tsx\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n```\n\n### RadioGroup\n\nRadioGroup -- A group of mutually exclusive radio options with optional label and error.\n\nRenders a `<div role=\"radiogroup\">` containing a label span, a flex container of\nradio options, and an optional error message. Each option is a `<label>` with a\nvisually-hidden native `<input type=\"radio\">` and a custom 18px circle indicator.\n\nStyling:\n- Selected circle: `2px solid var(--ggui-color-primary-600)` border with\n  an 8px `var(--ggui-color-primary-600)` filled inner dot\n- Unselected circle: `2px solid var(--ggui-color-outline)` border,\n  `var(--ggui-color-container)` fill\n- Circle radius: `var(--ggui-shape-radius-full)`\n- Transition: all 0.2s\n- Vertical gap: `var(--ggui-spacing-2)`, horizontal gap: `var(--ggui-spacing-4)`\n- Error: `var(--ggui-font-size-xs)`, `var(--ggui-color-error-500)`,\n  `role=\"alert\"`\n- Disabled options: `opacity: 0.5`, `cursor: not-allowed`\n\nAccessibility: the group has `role=\"radiogroup\"` with `aria-labelledby` pointing\nto the label and `aria-describedby` pointing to the error message (when present).\nAll radio inputs share a common auto-generated `name` attribute.\n\n**IMPORTANT:** `onChange` receives the selected option's value string directly,\nNOT a React `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Group label rendered above the options. Used as `aria-labelledby` target on the `role=\"radiogroup\"` container. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of `options[].value`. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the newly selected option's value string directly, NOT a React event. |\n| options | `RadioOption[]` | - | Array of radio options. Must contain at least two options for meaningful selection. |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Layout direction for the options container: - `'vertical'` -- column layout, `var(--ggui-spacing-2)` gap - `'horizontal'` -- row layout with `flex-wrap: wrap`, `var(--ggui-spacing-4)` gap |\n| disabled | `boolean` | `false` | When true, disables ALL options (individual `RadioOption.disabled` is additive). Each option gets `opacity: 0.5` and `cursor: not-allowed`. |\n| error | `string` | - | Error message displayed below all options in `var(--ggui-color-error-500)` with `role=\"alert\"`. Linked to the radiogroup via `aria-describedby`. |\n\n**Example:**\n```tsx\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n```\n\n### Slider\n\nSlider -- A range input with a custom-styled track, fill, and thumb.\n\nRenders a `<div>` wrapper containing an optional label/value header, and a\ntrack area with three layers: background track, colored fill, and a circular\nthumb. A native `<input type=\"range\">` is overlaid with `opacity: 0` to\nprovide accessible keyboard and pointer interaction.\n\nStyling:\n- Track: 6px tall, `var(--ggui-color-outlineVariant)` background, `border-radius: 3px`\n- Fill: `var(--ggui-color-primary-600)` (normal),\n  `var(--ggui-color-outline)` (disabled)\n- Thumb: 20px white circle with `2px solid var(--ggui-color-primary-600)`,\n  `var(--ggui-shape-shadow-sm)`; disabled border uses outline\n- Value display (when `showValue`): `var(--ggui-color-primary-600)`,\n  `var(--ggui-font-size-sm)`, right-aligned in the header row\n- Fill and thumb transitions: 0.1s for smooth dragging\n\nAccessibility: the native `<input type=\"range\">` carries `aria-valuenow`,\n`aria-valuemin`, `aria-valuemax`, and is linked to the label via `aria-labelledby`.\nFalls back to `aria-label=\"Slider\"` when no label is provided.\n\n**IMPORTANT:** `onChange` receives the numeric value directly, NOT a React\n`ChangeEvent`. The value is coerced via `Number(e.target.value)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the slider track (left-aligned). Used as `aria-labelledby` target on the native range input. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `number` | `0` | Controlled numeric value. Must be between `min` and `max`. |\n| onChange | `(value: number) => void` | - | Change handler. Receives the new numeric value directly, NOT a React event. |\n| min | `number` | `0` | Minimum allowed value. |\n| max | `number` | `100` | Maximum allowed value. |\n| step | `number` | `1` | Step increment for the slider. Determines the granularity of selectable values. |\n| disabled | `boolean` | `false` | When true, sets `cursor: not-allowed` on the native input. The fill color changes to `var(--ggui-color-outline)` and the thumb border also uses outline. |\n| showValue | `boolean` | `false` | When true, displays the current numeric value right-aligned in the header row (beside the label) in `var(--ggui-color-primary-600)`. |\n\n**Example:**\n```tsx\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n```\n\n### Badge\n\nBadge -- Inline label for status indicators, counts, or categories.\n\nRenders a `<span>` with `display: inline-flex`, centered content, and\n`white-space: nowrap`. Semantic variant colors use background/text pairings\nfrom the 100/700 color scale. Pill shape uses `border-radius: 9999px`;\nnon-pill uses `var(--ggui-shape-radius-sm)`.\n\nFont weight: `var(--ggui-font-weight-medium)` across all variants.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'default' \\| 'primary' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info' \\| 'tertiary'` | `'default'` | Visual style. Maps to background/text color pairings: - `'default'` -- bg `var(--ggui-color-sunken)`, text `var(--ggui-color-onSunken)` - `'primary'` -- bg `var(--ggui-color-primary-100)`, text `var(--ggui-color-primary-700)` - `'secondary'` -- bg `var(--ggui-color-outlineVariant)`, text `var(--ggui-color-onContainer)` - `'success'` -- bg `var(--ggui-color-success-100)`, text `var(--ggui-color-success-700)` - `'warning'` -- bg `var(--ggui-color-warning-100)`, text `var(--ggui-color-warning-700)` - `'error'` -- bg `var(--ggui-color-error-100)`, text `var(--ggui-color-error-700)` - `'info'` -- bg `var(--ggui-color-info-100)`, text `var(--ggui-color-info-700)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `2px 6px`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `2px 8px`, font `var(--ggui-font-size-xs)` - `'lg'` -- padding `4px 10px`, font `var(--ggui-font-size-sm)` |\n| pill | `boolean` | `true` | When true, uses fully rounded corners (`border-radius: 9999px`). When false, uses `var(--ggui-shape-radius-sm)`. |\n\n**Example:**\n```tsx\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n```\n\n### Spinner\n\nSpinner -- Animated SVG loading indicator.\n\nRenders an `<svg>` with `role=\"status\"` and `aria-label=\"Loading\"`.\nThe SVG contains a full outlineVariant background circle and a quarter-arc\nforeground stroke in the spinner color.\n\nAnimation: `ggui-spin 1s linear infinite` (360-degree rotation).\nThe `@keyframes ggui-spin` definition is injected inline via a `<style>` tag.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number` | `24` | Width and height of the SVG element in pixels. The internal viewBox is always `0 0 24 24`, so this controls rendered size only. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the animated foreground arc. Same vocabulary as ; the theme decides the resolved value. The background circle always uses `var(--ggui-color-outlineVariant)`.  Use `'inherit'` when the spinner sits inside a colored container (e.g. inside a Button) \u2014 the stroke picks up `currentColor` from the parent so it tracks the container's foreground. |\n\n**Example:**\n```tsx\n<Spinner size={32} tone=\"success\" />\n```\n\n### Avatar\n\nAvatar -- User or entity representation with image or auto-generated initials.\n\nRenders a `<div role=\"img\">` with `overflow: hidden` and `flex-shrink: 0`.\nWhen `src` is provided and loads successfully, renders an `<img>` with\n`object-fit: cover`. On image error (or when no `src`), falls back to\ninitials derived from `name` (up to 2 characters, uppercase).\n\nInitials background: deterministic color from a 5-color palette based on\nname hash (primary-500, success-500, warning-500, error-500, info-500).\nFalls back to `var(--ggui-color-outline)` when no name is given.\nInitials text: white, `font-weight: var(--ggui-font-weight-semibold)`,\n`font-size: resolvedSize * 0.4`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image URL. When provided and the image loads, it is rendered with `object-fit: cover`. On load error, falls back to initials. |\n| name | `string` | - | Name used for two purposes: 1. Generating initials (splits on spaces, takes first letter of each word, max 2). 2. Deterministic background color selection via character code hash. Also used as `aria-label` on the container. Falls back to `'Avatar'` if omitted. |\n| size | `number \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Avatar dimensions. Named sizes map to pixel values: - `'xs'` -- 24px - `'sm'` -- 32px - `'md'` -- 40px - `'lg'` -- 48px - `'xl'` -- 64px  Numeric values are used directly as pixel dimensions. |\n| shape | `'circle' \\| 'square'` | `'circle'` | Container shape. - `'circle'` -- `border-radius: 50%` - `'square'` -- `border-radius: var(--ggui-shape-radius-md)` |\n\n**Example:**\n```tsx\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n```\n\n### Alert\n\nAlert -- Contextual message box for important information with icon and optional dismiss.\n\nRenders a `<div role=\"alert\">` with flex layout (12px gap), variant-specific\nbackground, border, text color, and a leading icon. Each variant provides a\ndefault SVG icon (info circle, checkmark, warning triangle, or X circle) that\ncan be overridden via the `icon` prop.\n\nLayout: icon (flex-shrink: 0) | content column (title + body) | close button.\nBorder radius: `var(--ggui-shape-radius-lg)`.\nPadding: `12px 16px`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets: - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)`, icon `var(--ggui-color-info-500)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)`, icon `var(--ggui-color-success-500)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)`, icon `var(--ggui-color-warning-500)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)`, icon `var(--ggui-color-error-500)` |\n| title | `string` | - | Optional title rendered above the body in semibold (`var(--ggui-font-weight-semibold)`), `var(--ggui-font-size-sm)`. Title and body are separated by `var(--ggui-spacing-1)` gap. |\n| closable | `boolean` | `false` | When true, renders a close button (X icon) in the top-right area. The button has `min-width: 28px`, `min-height: 28px`, and `opacity: 0.7`. Requires `onClose` to be functional. |\n| onClose | `() => void` | - | Callback fired when the close button is clicked. Only relevant when `closable` is true. |\n| icon | `ReactNode` | - | Custom icon ReactNode to replace the default variant icon. Rendered at the leading position with the variant's icon color applied via `color` CSS property. |\n\n**Example:**\n```tsx\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n```\n\n### Progress\n\nProgress -- Horizontal progress bar with determinate and indeterminate modes.\n\nRenders a track `<div role=\"progressbar\">` with a colored fill child.\nThe track background is `var(--ggui-color-outlineVariant)` with\npill-shaped corners (border-radius = height / 2).\n\nDeterminate mode: fill width transitions smoothly (`width 0.3s ease`).\nIndeterminate mode: fill is 30% width, animated with\n`ggui-progress-indeterminate 1.5s ease-in-out infinite`\n(translateX from -100% to 400%). The `@keyframes` are injected inline.\n\nAccessibility: `aria-valuenow` is set in determinate mode, omitted in\nindeterminate. `aria-valuemin` is always 0, `aria-valuemax` matches `max`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `number` | - | Current progress value. Clamped to `[0, max]` and converted to a percentage for the fill width: `Math.min(100, Math.max(0, (value / max) * 100))`. |\n| max | `number` | `100` | Maximum value representing 100% progress. |\n| variant | `'default' \\| 'success' \\| 'warning' \\| 'error'` | `'default'` | Fill bar color. Maps to CSS variables: - `'default'` -- `var(--ggui-color-primary-600)` - `'success'` -- `var(--ggui-color-success-500)` - `'warning'` -- `var(--ggui-color-warning-500)` - `'error'` -- `var(--ggui-color-error-500)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track height in pixels: - `'sm'` -- 4px - `'md'` -- 8px - `'lg'` -- 12px |\n| label | `string` | - | Accessible name describing what this bar measures, e.g. `\"Survey progress\"` or `\"Upload\"`. Becomes the progressbar's `aria-label` and \u2014 when `showLabel` is set \u2014 the visible header text in place of the generic word \"Progress\". Always pass this when the surrounding context does not already make the meaning obvious. |\n| showLabel | `boolean` | `false` | When true, displays a header row above the track with the `label` text (or \"Progress\" if `label` is unset) on the left, and the rounded percentage value on the right. |\n| indeterminate | `boolean` | `false` | When true, ignores `value` for visual width and plays a looping animation instead. The fill bar is 30% width and slides across the track. Animation: `ggui-progress-indeterminate 1.5s ease-in-out infinite`. `aria-valuenow` is omitted from the progressbar element. |\n\n**Example:**\n```tsx\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n```\n\n### Image\n\nImage -- An `<img>` element with built-in error handling and fallback support.\n\nRenders a native `<img>` with `display: block`. On load error, either renders\nthe `fallback` ReactNode (if provided) or a default placeholder `<div>` with a\nsurfaceVariant background and a centered image SVG icon in outline.\n\nSize values: numbers are treated as pixels, strings are passed through as-is.\nWhen no `width` is set, defaults to `100%`. When no `height` is set, defaults\nto `auto`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image source URL. Load failure triggers the fallback state. |\n| alt | `string` | - | Alt text for the image. Used as `aria-label` in the error placeholder too. |\n| width | `number \\| string` | `'100%' (applied at render time, not on the type)` | Image width. Numbers are pixels, strings are CSS values (e.g., `'100%'`, `'50vw'`). |\n| height | `number \\| string` | `'auto' (applied at render time, not on the type)` | Image height. Numbers are pixels, strings are CSS values. |\n| objectFit | `'cover' \\| 'contain' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | CSS `object-fit` value controlling how the image fills its box. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | - | Corner radius applied to both the image and the error placeholder. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through. |\n| fallback | `ReactNode` | - | Custom ReactNode rendered when the image fails to load. When provided, completely replaces the default error placeholder (no wrapper div). When omitted, a surfaceVariant background div with an image icon is shown. |\n\n**Example:**\n```tsx\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n```\n\n### Icon\n\nIcon -- a curated Lucide subset (~200 names) + emoji passthrough.\n\nThree resolution layers:\n1. **Lucide icon:** pass a name from the curated subset (e.g. `sun`, `cloud-rain`, `heart`, `shopping-cart`, `sparkles`, `arrow-up-right`).\n   Accepts kebab-case, camelCase, or PascalCase. Renders as stroke SVG. ONLY the subset renders: an\n   unknown name renders an empty box (never a placeholder glyph) \u2014 the `get_available_icons` tool lists the exact names.\n2. **Emoji:** pass emoji/unicode directly (e.g. `\u2600\uFE0F`, `\u{1F327}\uFE0F`). Rendered as text.\n3. **Custom SVG:** pass children (`<svg>` element) for full control.\n\nContainer: `<span>` with `display: inline-flex`, centered content.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| name | `string` | - | Lucide icon name from the curated subset (kebab-case, camelCase, or PascalCase all work); a name outside the subset renders an empty box. Also accepts emoji/unicode characters directly. |\n| size | `number` | `24` | Icon dimensions in pixels (applied to both width and height of the wrapper and the inner SVG element). |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (icon uses `currentColor`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Resolves to a CSS `color` on the wrapper which the inner SVG inherits via `currentColor`. Use `'inherit'` (the default behavior when unset) for icons that should pick up the parent's foreground color. |\n| children | `ReactNode` | - | Custom SVG children. When provided, `name` is ignored and children are rendered inside a sized `<span>` wrapper. |\n| 'aria-label' | `string` | - | Accessible name for a standalone, meaning-bearing icon. When set, the icon exposes `role=\"img\"` + this label. When omitted (the default) the icon is decorative and hidden from screen readers (`aria-hidden`) \u2014 the right choice for an icon next to a text label. |\n\n**Example:**\n```tsx\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n```\n\n### Link\n\nLink -- Styled anchor element with external link support.\n\nRenders a native `<a>` element. When `external` is true, sets\n`target=\"_blank\"` and `rel=\"noopener noreferrer\"`, and appends a small\n(12px) external-link SVG icon after the children.\n\nTransition: `color 0.2s`.\nUnderline behavior is controlled via mouseEnter/mouseLeave event handlers\n(for the `'hover'` mode).\n\nAlso extends native `AnchorHTMLAttributes` (except `style`/`className`),\nso props like `aria-*`, `data-*`, `title`, etc. are forwarded to the `<a>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| href | `string` | - | Destination URL. Passed directly to the `<a href>` attribute. |\n| external | `boolean` | `false` | When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`) and appends a 12px external-link icon after children. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the link text. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a primary-tinted accent (`'loud'`-ish) when unset. |\n| underline | `'always' \\| 'hover' \\| 'none'` | `'hover'` | Underline behavior: - `'always'` -- `text-decoration: underline` at all times - `'hover'` -- underline appears on mouse enter, removed on mouse leave - `'none'` -- no underline ever |\n\n**Example:**\n```tsx\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n```\n\n### Tooltip\n\nTooltip -- Hoverable information popup positioned relative to a trigger element.\n\nWraps `children` in a `<div>` trigger (display: inline-block) and renders\na fixed-position tooltip `<div role=\"tooltip\">` when visible.\n\nTooltip appearance:\n- Background: `var(--ggui-color-onContainer)`\n- Text: white, `var(--ggui-font-size-xs)`\n- Padding: `6px 10px`, border-radius: `var(--ggui-shape-radius-md)`\n- Max width: 200px, `white-space: nowrap`, `pointer-events: none`\n- Z-index: `zIndex.tooltip` (1800)\n\nShow/hide: triggered by mouseEnter/mouseLeave AND focus/blur on the\ntrigger element. Uses `position: fixed` with coordinates calculated from\n`getBoundingClientRect()` and an 8px offset from the trigger edge.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Trigger element. Wrapped in a `<div>` with mouseEnter/mouseLeave and focus/blur handlers. |\n| content | `ReactNode` | - | Tooltip content. Can be text or any ReactNode. |\n| position | `'top' \\| 'bottom' \\| 'left' \\| 'right'` | `'top'` | Tooltip placement relative to the trigger element: - `'top'` -- above, centered horizontally, transformed `translateX(-50%) translateY(-100%)` - `'bottom'` -- below, centered horizontally, transformed `translateX(-50%)` - `'left'` -- to the left, centered vertically, transformed `translateX(-100%) translateY(-50%)` - `'right'` -- to the right, centered vertically, transformed `translateY(-50%)` |\n| delay | `number` | `200` | Delay in milliseconds before the tooltip becomes visible after hover/focus. Hiding is immediate (no delay). |\n\n**Example:**\n```tsx\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n```\n\n### Table\n\nTable -- Data table with sortable columns, striped rows, and hover highlights.\n\nRenders a scrollable wrapper `<div>` containing a native `<table>` with\n`border-collapse: collapse` and `width: 100%`. The wrapper has\n`overflow-x: auto` for horizontal scrolling on narrow viewports.\n\nHeader row: 2px bottom border (`var(--ggui-color-outlineVariant)`).\nData rows: 1px bottom border (`var(--ggui-color-sunken)`).\nHover: `var(--ggui-color-container)` background with 150ms ease transition.\nStriped: alternating rows (odd index) get `var(--ggui-color-container)`.\n\nSort behavior: clicking a sortable column header calls `onSort(key, direction)`.\nIf the same column is clicked again while ascending, it toggles to descending.\nThe component does NOT sort data internally -- the parent must sort `data` and\npass updated `sortKey`/`sortDirection`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `TableColumn<T>[]` | - | Array of column definitions controlling header labels, data keys, and rendering. |\n| data | `T[]` | - | Array of row data objects. Each object's keys should match the column `key` values. |\n| sortKey | `string` | - | The `key` of the currently sorted column. Used to highlight the active sort indicator and determine toggle direction on next click. |\n| sortDirection | `SortDirection` | `'asc'` | Current sort direction for the column identified by `sortKey`. Controls which triangle indicator is highlighted in the header. |\n| onSort | `(key: string, direction: SortDirection) => void` | - | Sort change handler. Called when a sortable column header is clicked. Receives the column `key` and the new `SortDirection`. The component does NOT sort data internally -- you must sort `data` in your state and pass updated `sortKey`/`sortDirection`. |\n| striped | `boolean` | `false` | When true, alternating rows (odd index) get a `var(--ggui-color-container)` background. |\n| hoverable | `boolean` | `true` | When true, rows highlight with `var(--ggui-color-container)` on mouse enter, with a 150ms ease background-color transition. |\n| compact | `boolean` | `false` | When true, reduces cell padding: - Compact: `var(--ggui-spacing-1) var(--ggui-spacing-2)` - Normal: `var(--ggui-spacing-2) var(--ggui-spacing-4)` |\n| bordered | `boolean` | `false` | When true, adds a 1px border around the table wrapper and between cells. Wrapper border: `1px solid var(--ggui-color-outlineVariant)`. Cell borders: `1px solid var(--ggui-color-sunken)`. Wrapper border-radius: `var(--ggui-shape-radius-lg)`. |\n| caption | `string` | - | Accessible table caption. Rendered as a `<caption>` element with `caption-side: top`, `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`. |\n\n**Example:**\n```tsx\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n```\n\n### Tabs\n\nTabs -- Accessible tab navigation with panels and keyboard support.\n\nRenders a `<div role=\"tablist\">` with `<button role=\"tab\">` elements and a\n`<div role=\"tabpanel\">` for the active tab's content. Supports controlled\n(`activeKey` + `onChange`) and uncontrolled (internal state) modes.\n\nKeyboard navigation: ArrowLeft/ArrowRight (and ArrowUp/ArrowDown) cycle\nthrough enabled tabs. Home/End jump to first/last. Focus follows selection.\nDisabled tabs are skipped during keyboard navigation.\n\n**IMPORTANT:** `onChange` receives the tab's `key` string directly, NOT a\nReact event.\n\nTab panel padding: `var(--ggui-spacing-4) 0` (top/bottom only).\nTransitions: color, background-color, border-color at 200ms ease-in-out.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `TabItem[]` | - | Array of tab definitions. Must contain at least one item. |\n| activeKey | `string` | - | Controlled active tab key. When provided, the component is controlled and will not manage its own state. Must match one of `items[].key`. When omitted, defaults to the first item's key (uncontrolled mode). |\n| onChange | `(key: string) => void` | - | Tab change handler. Receives the selected tab's `key` string directly, NOT a React event. In controlled mode, you must update `activeKey` in response to this callback. |\n| variant | `'line' \\| 'pills' \\| 'enclosed'` | `'line'` | Visual style of the tab bar: - `'line'` -- underline indicator (2px solid primary-600 on active), border-bottom on tab list - `'pills'` -- filled pill buttons (primary-600 bg, white text on active), surfaceVariant container with radius-lg - `'enclosed'` -- bordered tab buttons with open bottom (card-style), border-bottom on tab list |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls tab button padding and font size: - `'sm'` -- padding `var(--ggui-spacing-1) var(--ggui-spacing-2)`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `var(--ggui-spacing-2) var(--ggui-spacing-4)`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `var(--ggui-spacing-4) var(--ggui-spacing-6)`, font `var(--ggui-font-size-base)` |\n| fullWidth | `boolean` | `false` | When true, tab buttons expand equally to fill the container width (`flex: 1`, `justify-content: center` on each button). |\n\n**Example:**\n```tsx\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n```\n\n### Toast\n\nToast -- Notification banner with auto-dismiss and slide-in animation.\n\nRenders a `<div role=\"alert\" aria-live=\"assertive\">` with a variant-specific\nicon, optional title, message body, and optional close button.\n\nAnimation: `ggui-slideInUp 200ms ease-out both` on mount (from the motion\ntoken system). The keyframes are provided by the MotionKeyframes provider.\n\nAuto-dismiss: when `onClose` is provided and `duration > 0`, a timer calls\n`onClose` after `duration` ms. Setting `duration` to `0` disables auto-dismiss.\nThe timer resets if `visible`, `duration`, or `onClose` changes.\n\nDimensions: `min-width: 280px`, `max-width: 420px`.\nShadow: `var(--ggui-shape-shadow-lg)`.\nBorder radius: `var(--ggui-shape-radius-lg)`.\n\nWhen `visible` is false, renders nothing (returns `null`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| message | `ReactNode` | - | Message body content. Can be text or any ReactNode. |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets (same palette as Alert): - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)` |\n| title | `string` | - | Optional title rendered above the message in semibold (`var(--ggui-font-weight-semibold)`, `var(--ggui-font-size-sm)`). |\n| duration | `number` | `5000` | Auto-dismiss delay in milliseconds. After this duration, `onClose` is called automatically. Set to `0` to disable auto-dismiss (toast stays until manually closed). The timer is only active when both `visible` is true and `onClose` is provided. |\n| onClose | `() => void` | - | Callback fired on auto-dismiss timeout or when the close button is clicked. When provided, a close button (X icon, 16px) is rendered in the top-right area. When omitted, no close button is shown and auto-dismiss is disabled. |\n| visible | `boolean` | `true` | Controls rendering. When false, the component returns `null`. Toggling from false to true triggers the slide-in animation. |\n| position | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-center' \\| 'bottom-center'` | - | Intended screen position. This prop is defined on the interface but is NOT implemented by the Toast component itself -- positioning must be handled by a parent container or toast manager. |\n\n**Example:**\n```tsx\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n```\n\n### Accordion\n\nAccordion -- Collapsible content sections with chevron rotation animation.\n\nRenders a vertical list of items, each with a `<button>` header (inside `<h3>`)\nand a `<div role=\"region\">` panel. Supports controlled (`expandedKeys` + `onChange`)\nand uncontrolled (internal state) modes.\n\nChevron animation: the trailing chevron icon rotates from 0deg (collapsed) to\n180deg (expanded) with `transition: transform var(--ggui-motion-duration-base) var(--ggui-motion-easing-standard)` (ggui#1106).\n\nHeader button: full-width flex layout (`justify-content: space-between`),\n`var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n`var(--ggui-color-onContainer)`.\nHeader padding: `var(--ggui-spacing-2) var(--ggui-spacing-4)`.\nBackground transition: `background-color var(--ggui-motion-duration-fast) var(--ggui-motion-easing-standard)`.\n\n**IMPORTANT:** `onChange` receives the full array of currently expanded keys,\nNOT a single key or a React event. In single mode (`multiple: false`), this\narray will have at most one element.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `AccordionItem[]` | - | Array of collapsible section definitions. |\n| expandedKeys | `string[]` | - | Controlled expanded state. Array of item `key` values that should be open. When provided, the component is controlled and will not manage its own expansion state. When omitted, defaults to `[]` (all collapsed, uncontrolled mode). |\n| onChange | `(expandedKeys: string[]) => void` | - | Expand/collapse handler. Receives the complete array of expanded keys after a toggle. In controlled mode, you must update `expandedKeys` in response to this callback. |\n| multiple | `boolean` | `false` | When true, multiple items can be open simultaneously. When false, opening one item closes any other open item (single-expand mode). |\n| variant | `'default' \\| 'bordered' \\| 'separated'` | `'default'` | Visual style controlling borders and spacing: - `'default'` -- top border on first item, bottom border on all items (`var(--ggui-color-outlineVariant)`), no gap between items - `'bordered'` -- connected card style with left/right/bottom borders on all items, top border on first, shared rounded corners (radius-lg on first/last) - `'separated'` -- each item is an independent card with full border (`1px solid var(--ggui-color-outlineVariant)`), `var(--ggui-shape-radius-lg)` radius, `var(--ggui-spacing-2)` gap between items |\n\n**Example:**\n```tsx\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n```\n\n### Support Types\n\n**ResponsiveColumns:**\n\nExplicit column count per viewport breakpoint, mobile-first. `base`\napplies from 0 up; each named key overrides at and above its\nbreakpoint width (`sm` 640px, `md` 768px, `lg` 1024px, `xl` 1280px).\nOmit `base` to default to a single column on the narrowest screens.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| base | `number` | Columns below the `sm` breakpoint. |\n| sm | `number` | Columns from 640px up. |\n| md | `number` | Columns from 768px up. |\n| lg | `number` | Columns from 1024px up. |\n| xl | `number` | Columns from 1280px up. |\n\n**SelectOption:**\n\nAn individual option within a `Select` dropdown.\n\nRendered as a native `<option>` element. When `disabled` is true, the option\nis visible but not selectable.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value submitted when this option is selected. Must be unique within the options array. |\n| label | `string` | The display text shown in the dropdown. |\n| disabled | `boolean` | When true, the option is visible but cannot be selected (grayed out by the browser). |\n\n**RadioOption:**\n\nAn individual option within a `RadioGroup`.\n\nRendered as a `<label>` containing a visually-hidden `<input type=\"radio\">`\nand a custom 18px circle indicator. Supports an optional description line\nbelow the label text.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value emitted via `RadioGroupProps.onChange` when this option is selected. Must be unique. |\n| label | `string` | Display text for this option. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| description | `string` | Optional secondary description rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| disabled | `boolean` | When true, this individual option is grayed out (`opacity: 0.5`) and cannot be selected, regardless of the group-level `disabled` prop. |\n\n**TableColumn:**\n\nColumn definition for the Table component.\n\nEach column maps a `key` in the row data object to a table column with\na header label, optional sorting, alignment, width, and custom rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key in the row data object. Used to extract cell values via `row[key]`. Must be unique across all columns in a Table. |\n| header | `string` | Column header text. Rendered in uppercase, `var(--ggui-font-size-xs)`, `var(--ggui-font-weight-semibold)`, `var(--ggui-color-onSunken)`, with `letter-spacing: 0.05em`. |\n| width | `number \\| string` | Fixed column width. Numbers are pixels, strings are CSS values (e.g., `'200px'`, `'30%'`). When omitted, the column auto-sizes based on content. |\n| align | `'left' \\| 'center' \\| 'right'` | Horizontal text alignment for both the header and data cells. |\n| sortable | `boolean` | When true, the header cell becomes clickable and shows sort direction indicators (ascending/descending triangles). Clicking toggles between `'asc'` and `'desc'`. The header gets `cursor: pointer`, `tabIndex: 0`, and keyboard support (Enter/Space to toggle). |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When provided, called instead of rendering `row[key]` directly. Receives the cell value, the full row object, and the row index. |\n\n**TabItem:**\n\nDefinition of a single tab within a Tabs component.\n\nEach item provides a unique `key` for identification, a `label` for the\ntab button, and `content` for the associated panel.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this tab. Used to match `activeKey` and as the value passed to `onChange`. |\n| label | `ReactNode` | Tab button label. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the tab bar when this tab is active. |\n| disabled | `boolean` | When true, the tab button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be selected via click or keyboard navigation. |\n| icon | `ReactNode` | Optional icon rendered before the label inside the tab button, with `var(--ggui-spacing-1)` gap between icon and label. |\n\n**AccordionItem:**\n\nDefinition of a single collapsible section within an Accordion.\n\nEach item provides a unique `key`, a clickable `title` for the header button,\nand `content` revealed when expanded.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this item. Used in `expandedKeys` and passed to `onChange`. |\n| title | `ReactNode` | Header label rendered inside the toggle button. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the header when expanded. Styled with `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`, `line-height: var(--ggui-font-lineHeight-normal)`. Padding: `0 var(--ggui-spacing-4) var(--ggui-spacing-4)`. |\n| disabled | `boolean` | When true, the header button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be toggled. |\n\n\n## Components\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### SearchField\n\nA text input with a leading search icon and optional submit button.\n\nComposes: `Input` (native `<input type=\"search\">`), `Button`, `Spinner`, `Icon`.\n\nSupports controlled and uncontrolled usage. When `value` is `undefined` the\ncomponent tracks its own state internally. Pressing **Enter** triggers\n`onSearch` with the current value. When `loading` is `true` the search icon\nis replaced by a `Spinner` and the input is disabled.\n\nTokens used: `colors.gray[300]` border, `colors.gray[50]` disabled bg,\n`colors.gray[400]` icon color, `colors.gray[900]` text color.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | - | Current search value. When provided, the component is **controlled** and the caller must update this via `onChange`. When omitted, the component manages its own internal state. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React `ChangeEvent`). |\n| onSearch | `(value: string) => void` | - | Called when the user presses **Enter** or clicks the search button (if `showButton` is `true`). Receives the current value directly. |\n| placeholder | `string` | `'Search...'` | Placeholder text shown when the input is empty. |\n| showButton | `boolean` | `false` | When `true`, renders a `Button` primitive to the right of the input. The button's label is set by `buttonText`. |\n| buttonText | `string` | `'Search'` | Label rendered inside the submit button. Only visible when `showButton` is `true`. |\n| loading | `boolean` | - | When `true`, replaces the search icon with a `Spinner`, disables the input, and disables the submit button. |\n| disabled | `boolean` | - | When `true`, the input and button are visually disabled and do not respond to interaction. The input background changes to `colors.gray[50]`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls input height and font size. - `'sm'` -- 6px vertical padding, 14px font - `'md'` -- 10px vertical padding, 14px font - `'lg'` -- 12px vertical padding, 16px font  The Button size maps `sm`->`sm`, `md`->`md`, `lg`->`md`. |\n\n**Example:**\n```tsx\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n```\n\n### FormField\n\nA wrapper that adds a label, optional description, error message,\nand helper text around any form input passed as `children`.\n\nComposes: no other primitives -- pure layout with semantic `<label>` and\n`<span>` elements.\n\nVisual hierarchy (top to bottom):\n1. **Label** (required) -- `fontSize.sm`, `fontWeight.medium`, `colors.gray[700]`\n2. **Required indicator** -- red asterisk (`colors.error[500]`) appended to label\n3. **Description** -- `fontSize.xs`, `colors.gray[500]`, 4px bottom margin\n4. **Children** -- the form control itself\n5. **Error / Helper text** -- `fontSize.xs`; error in `colors.error[500]`,\n   helper in `colors.gray[500]`. Error takes priority when both are provided.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Text rendered inside the `<label>` element above the input. |\n| children | `ReactNode` | - | The form control (typically an `Input`, `Select`, or `Textarea` primitive) rendered between the label/description and the error/helper row. |\n| error | `string` | - | Error message displayed below `children` in `colors.error[500]`. When present, it takes precedence over `helperText`. |\n| helperText | `string` | - | Neutral guidance text displayed below `children` in `colors.gray[500]`. Hidden when `error` is present. |\n| required | `boolean` | - | When `true`, appends a red asterisk (`*`) after the label text. Does **not** add any HTML validation attributes -- handle that on the child input. |\n| description | `string` | - | Secondary description rendered between the label and the child control in `fontSize.xs` / `colors.gray[500]`. Use for longer guidance that does not belong in `helperText`. |\n\n**Example:**\n```tsx\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n```\n\n### MenuItem\n\nA full-width clickable row for menus, sidebars, and action lists.\n\nComposes: none -- renders a native `<button>` element.\n\nBuilt-in transition: `background-color` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on hover (ggui#1106).\n\nColor logic:\n- **Normal**: text `colors.gray[700]`, hover bg `colors.gray[100]`\n- **Active**: bg `colors.primary[50]`, text `colors.gray[700]`, `fontWeight.medium`\n- **Danger**: text `colors.error[600]`, hover bg `colors.error[50]`, active bg `colors.error[100]`\n- **Disabled**: text `colors.gray[400]`, `cursor: not-allowed`\n\nLayout: flexbox row with `8px` gap, `8px 12px` padding, `radius.md` border-radius.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary text content of the menu item. |\n| icon | `ReactNode` | - | Icon or element rendered to the left of the label. Flex-shrink 0. |\n| rightElement | `ReactNode` | - | Element rendered to the right of the label (e.g., a keyboard shortcut badge or a count). Colored `colors.gray[400]`, flex-shrink 0. |\n| onClick | `() => void` | - | Called when the item is clicked. Suppressed when `disabled` is `true`. |\n| disabled | `boolean` | - | When `true`, the item is non-interactive: `colors.gray[400]` text, `cursor: not-allowed`, click handler suppressed. |\n| active | `boolean` | - | Marks this item as the current selection. Applies a tinted background (`colors.primary[50]`, or `colors.error[100]` when `danger` is also set) and `fontWeight.medium`. |\n| danger | `boolean` | - | Switches the item to destructive styling: `colors.error[600]` text, `colors.error[50]` hover background. |\n\n**Example:**\n```tsx\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n```\n\n### Tag\n\nAn inline label for categories, filters, statuses, or selections.\nOptionally dismissable via a close button.\n\nComposes: none -- pure `<span>` with an optional close `<button>`.\n\nEach `variant` maps to a background / text / border color triple from the\ndesign tokens:\n- `'default'`  -- `gray[100]` / `gray[700]` / `gray[200]`\n- `'primary'`  -- `primary[50]` / `primary[700]` / `primary[200]`\n- `'success'`  -- `success[50]` / `success[700]` / `success[200]`\n- `'warning'`  -- `warning[50]` / `warning[700]` / `warning[200]`\n- `'error'`    -- `error[50]` / `error[700]` / `error[200]`\n- `'info'`     -- `info[50]` / `info[700]` / `info[200]`\n\nThe close button renders an inline SVG \"x\" icon (12x12) with `opacity: 0.7`\nand an `aria-label=\"Remove\"`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Tag content -- typically a short text string. |\n| variant | `'default' \\| 'primary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Semantic color variant applied to background, text, and border. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and internal gap. - `'sm'` -- 2px/6px padding, `fontSize.xs`, 4px gap - `'md'` -- 4px/8px padding, `fontSize.xs`, 6px gap - `'lg'` -- 6px/10px padding, `fontSize.sm`, 6px gap |\n| closable | `boolean` | - | When `true`, renders a small close (\"x\") button after the content. Clicking it fires `onClose`. |\n| onClose | `() => void` | - | Called when the close button is clicked. Only relevant when `closable` is `true`. |\n| icon | `ReactNode` | - | Icon or element rendered before the text content. |\n\n**Example:**\n```tsx\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n```\n\n### Dropdown\n\nA click-triggered menu anchored to a trigger element. Manages its own\nopen/close state internally.\n\nComposes: `MenuItem` for each option.\n\nBehavior:\n- Clicking the trigger toggles the menu open/closed.\n- Selecting an option calls `onChange(option.value)` and closes the menu.\n- Clicking outside the container or pressing **Escape** closes the menu.\n- The currently selected option (matching `value`) is rendered with\n  `MenuItem`'s `active` state.\n\nMenu panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, 160px min-width, 4px padding.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| trigger | `ReactNode` | - | The element the user clicks to open the menu. Receives a wrapping `<div>` with `cursor: pointer` (or `not-allowed` when disabled). |\n| options | `DropdownOption[]` | - | Array of selectable options rendered as `MenuItem` rows. |\n| value | `string` | - | The `value` of the currently selected option. The matching `MenuItem` is rendered with `active` styling. |\n| onChange | `(value: string) => void` | - | Called with the `value` string of the selected option (not the full `DropdownOption` object). The menu closes immediately after. |\n| placement | `'bottom-start' \\| 'bottom-end' \\| 'top-start' \\| 'top-end'` | `'bottom-start'` | Where to anchor the menu panel relative to the trigger. - `'bottom-start'` -- below, aligned to left edge - `'bottom-end'`   -- below, aligned to right edge - `'top-start'`    -- above, aligned to left edge - `'top-end'`      -- above, aligned to right edge |\n| disabled | `boolean` | - | When `true`, the trigger shows `cursor: not-allowed` and clicking it does not open the menu. |\n\n**Example:**\n```tsx\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n```\n\n### Autocomplete\n\nA text input with a filterable suggestion dropdown, keyboard navigation,\nand loading/empty states.\n\nComposes: `Input` primitive (with `label`, `error`, `placeholder` forwarded),\n`Spinner` (loading state).\n\nFiltering: options are filtered client-side by case-insensitive substring\nmatch against both `option.label` and `option.value`.\n\nKeyboard support:\n- **ArrowDown / ArrowUp** -- move highlight through filtered options\n  (opens dropdown if closed)\n- **Enter** -- selects the highlighted option\n- **Escape** -- closes the dropdown\n\nOn selection, `onChange` is called with `option.label` (the display text)\nand `onSelect` is called with the full `AutocompleteOption` object.\n\nDropdown panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, max-height 240px with\noverflow scroll.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | `''` | Current text in the input field. On selection, this is set to the selected option's `label`. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React event). Also called on selection with `option.label`. |\n| onSelect | `(option: AutocompleteOption) => void` | - | Called when the user selects an option (click or Enter on highlighted item). Receives the full `AutocompleteOption` object, not just the value string. |\n| options | `AutocompleteOption[]` | - | The full list of available options. Filtering is handled internally via case-insensitive substring match on `label` and `value`. |\n| placeholder | `string` | - | Placeholder text forwarded to the inner `Input` primitive. |\n| label | `string` | - | Label text forwarded to the inner `Input` primitive. |\n| loading | `boolean` | - | When `true`, the dropdown shows a centered `Spinner` instead of the option list. The input remains interactive. |\n| disabled | `boolean` | - | When `true`, the inner `Input` is disabled and the dropdown does not open. |\n| error | `string` | - | Error message forwarded to the inner `Input` primitive. |\n| noResultsText | `string` | `'No results found'` | Text shown in the dropdown when filtering produces zero matches. Rendered centered in `colors.gray[500]` / `fontSize.sm`. |\n\n**Example:**\n```tsx\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n```\n\n### Breadcrumb\n\nA horizontal navigation trail showing the user's location within a\nhierarchy. Renders a `<nav aria-label=\"Breadcrumb\">`.\n\nComposes: `Link` primitive (for items with `href`).\n\nRendering rules per item:\n- **Last item**: static `<span>` with `colors.gray[900]`, `fontWeight: 500`,\n  and `aria-current=\"page\"`.\n- **Non-last with `href`**: `Link` in `colors.gray[500]` with\n  `underline=\"hover\"`. If `onItemClick` is provided, `e.preventDefault()`\n  is called and the handler fires instead of navigating.\n- **Non-last without `href`**: unstyled `<button>` in `colors.gray[500]`.\n\nLayout: flexbox row, `8px` gap, `fontSize.sm`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `BreadcrumbItem[]` | - | Ordered array of breadcrumb segments from root to current page. |\n| separator | `ReactNode` | `'/'` | Separator rendered between each pair of items. Can be a string (e.g., `\"/\"`, `\">\"`) or a ReactNode (e.g., an `Icon`). Rendered in `colors.gray[400]`. |\n| onItemClick | `(item: BreadcrumbItem, index: number) => void` | - | Called when a non-last item is clicked. Receives the `BreadcrumbItem` and its zero-based `index`. When provided on items that have `href`, the default navigation is prevented via `e.preventDefault()`. |\n\n**Example:**\n```tsx\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n```\n\n### Pagination\n\nPage navigation controls with previous/next arrows, numbered page buttons,\nand optional first/last jumps. Renders a `<nav aria-label=\"Pagination\">`.\n\nComposes: `Button` (ghost variant for prev/next/first/last arrows),\n`Icon` (`chevron-left`, `chevron-right`).\n\nBuilt-in transition: `all` over `var(--ggui-motion-duration-fast)` / `var(--ggui-motion-easing-standard)` on page number buttons (ggui#1106).\n\nPage windowing: when `totalPages > maxVisible`, the component shows the\nfirst page, last page, a window of pages around `currentPage`, and\nellipsis (\"...\") markers for gaps. The window adjusts when near the\nstart or end of the range.\n\nActive page button: `colors.primary[600]` bg, `colors.white` text,\n`fontWeight.medium`. Inactive: transparent bg, `colors.gray[700]` text.\n\nArrow buttons are automatically disabled at boundary pages (first/last).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| currentPage | `number` | - | Current active page. **1-indexed** (first page is `1`). |\n| totalPages | `number` | - | Total number of pages. Determines when last-page / next-page buttons disable. |\n| onPageChange | `(page: number) => void` | - | Called when the user clicks a page number, arrow, or first/last button. Receives the target page number (1-indexed) directly. |\n| showFirstLast | `boolean` | `true` | When `true`, renders double-chevron buttons for jumping to the first and last page. These buttons are disabled when already on the respective boundary. |\n| maxVisible | `number` | `5` | Maximum number of page buttons visible at once (including the first and last page, but excluding ellipsis markers). When `totalPages` exceeds this value, ellipsis gaps appear. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls button dimensions and icon sizes. - `'sm'` -- 28px buttons, 14px icons, Button size `xs` - `'md'` -- 32px buttons, 16px icons, Button size `sm` - `'lg'` -- 40px buttons, 20px icons, Button size `md` |\n| disabled | `boolean` | - | When `true`, all page buttons and arrows are visually dimmed (`opacity: 0.5`) and clicks are suppressed. |\n\n**Example:**\n```tsx\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n```\n\n### EmptyState\n\nEmptyState -- placeholder for a region with no data: empty lists,\nzero search results, an error fallback. Render it instead of\nnothing whenever a data array could be empty \u2014 a list that shows\nnothing when empty looks broken.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| icon | `string \\| ReactNode` | - | A Lucide icon name (kebab-case), rendered large and subtle above the title, or a custom node. Omit for a text-only empty state. |\n| title | `string` | - | The headline, e.g. \"No results found\". |\n| description | `string` | - | Optional supporting line below the title. |\n| action | `ReactNode` | - | Optional call-to-action, typically a `<Button>`. |\n\n**Example:**\n```tsx\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n```\n\n### Stat\n\nStat -- a single KPI / metric: a label, a large value, an optional\ntrend-coloured delta and icon. Reach for it whenever the UI is\n\"show a number\" \u2014 dashboards, weather and price cards, analytics\ntiles. Drop several into a `<Grid>` for a stat grid.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | The metric name, e.g. \"Revenue\". Rendered small and uppercase above the value. |\n| value | `string \\| number` | - | The headline value \u2014 the big number. A number, or a pre-formatted string (`\"$48.2k\"`, `\"18\xB0C\"`). |\n| delta | `string` | - | Optional change indicator, pre-formatted, e.g. `\"+12.5%\"` or `\"-3\"`. |\n| trend | `'up' \\| 'down' \\| 'neutral'` | `'neutral'` | Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error, `'neutral'` muted. |\n| icon | `string \\| ReactNode` | - | Optional Lucide icon name (kebab-case) or custom node, shown next to the label. |\n\n**Example:**\n```tsx\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n```\n\n### Stepper\n\nStepper -- a display-only step indicator for multi-step flows\n(wizards, checkouts, onboarding): numbered markers joined by\nconnector lines, with completed (check), current (filled), and\nupcoming (outlined) states styled distinctly.\n\nStepper renders step state; it never owns it. Declare the step\nlabels as a top-level `const`, track the current index in\n`useState`, and advance it from your own Next/Back buttons (or\n`onStepClick`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| steps | `string[]` | - | Ordered step labels, one per step. Declare as a top-level `const` array \u2014 never as state. |\n| current | `number` | - | Zero-based index of the active step. Steps before it render as completed (check mark), steps after it as upcoming. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Flow direction. `'horizontal'` joins the markers with connector lines in a row; `'vertical'` stacks the steps with short connector columns \u2014 better for sidebars or long step labels. |\n| onStepClick | `(index: number) => void` | - | When provided, each step becomes a real button and clicks receive the step's zero-based index. Typical use: jumping back to a completed step; guard forward jumps in the handler if the flow validates per step. |\n\n**Example:**\n```tsx\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n```\n\n### Markdown\n\nMarkdown -- renders markdown-formatted text as styled content:\nheadings, paragraphs, **bold** / *italic*, `inline code`, fenced\ncode blocks, bulleted and numbered lists, pipe tables, and links.\n\nUse it whenever a prop or context slot carries prose the agent\nauthors in markdown -- article bodies, AI-generated explanations,\ndescriptions, notes, help text. Pass the raw markdown string\nstraight through; never pre-parse it, never split it into per-line\n`Text` elements, and never rebuild formatting with nested\n`<strong>`/`<em>` markup yourself.\n\nSafe by construction: raw HTML in the source displays as literal\ntext (never markup), and links render inert unless their scheme is\nhttp(s)/mailto. Streaming-tolerant: a mid-stream prefix parses\ncleanly and completed constructs never change shape, so binding a\ngrowing string re-renders correctly.\n\nFor a single line of formatted text INSIDE another element (a table\ncell, a list row, a caption), use `MarkdownInline` instead -- same\n`markdown` prop, inline-level constructs only (no headings, lists,\nor code fences), renders inside the parent's typography.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Markdown source text, passed through verbatim. Supports the conversational subset: `#`-`###` headings, paragraphs, bold, italic, inline code, fenced code blocks, `-`/`1.` lists, `\\|` pipe tables, and `[label](url)` links. Bind stateful or streamed prose directly. |\n\n**Example:**\n```tsx\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n```\n\n### MarkdownInline\n\nMarkdownInline -- renders ONE line of inline-level markdown (bold,\nitalic, inline code, links) inside the parent's typography -- a table\ncell, a list row, a caption, a summary line. Same `markdown` prop as\n`Markdown`; block constructs (headings, lists, code fences) are not\nrendered -- reach for `Markdown` for multi-paragraph bodies.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Inline markdown source -- bold, italic, inline code, and `[label](url)` links. Block-level syntax renders as plain text. |\n\n**Example:**\n```tsx\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n```\n\n### Support Types\n\n**DropdownOption:**\n\nA single option inside a `Dropdown`. Each option maps to one `MenuItem`\ninternally.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier returned to `onChange` when this option is selected. |\n| label | `string` | Human-readable text shown in the menu row. |\n| icon | `ReactNode` | Optional icon rendered to the left of the label via `MenuItem.icon`. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive. |\n| danger | `boolean` | When `true`, the option uses destructive (red) styling via `MenuItem.danger`. |\n\n**AutocompleteOption:**\n\nA single option in the `Autocomplete` suggestion list.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier for this option. Also used for case-insensitive filtering against the input value. |\n| label | `string` | Primary display text. Also used for case-insensitive filtering and is written into the input on selection. |\n| description | `string` | Secondary description rendered below the label in `fontSize.xs` / `colors.gray[500]`. |\n| icon | `ReactNode` | Icon rendered to the left of the label/description block. Flex-shrink 0. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive (`cursor: not-allowed`, `colors.gray[400]` text). |\n\n**BreadcrumbItem:**\n\nA single segment in a `Breadcrumb` trail. Items with `href` render as\n`Link` primitives; items without render as plain `<button>` elements.\nThe last item in the array is always rendered as static text with\n`aria-current=\"page\"`.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for this breadcrumb segment. |\n| href | `string` | URL for this segment. When provided (and this is not the last item), the segment renders as a `Link` primitive with `underline=\"hover\"`. When omitted, it renders as a `<button>`. |\n| icon | `ReactNode` | Icon rendered immediately before the label. Its color follows the segment's text color: `colors.gray[500]` for navigable items, `colors.gray[900]` for the current (last) item. |\n\n\n## Compositions\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Header\n\nProps for the `Header` composition.\n\nA horizontal page header that arranges a logo, navigation, and action slots\nin a flex row (`justify-content: space-between`). Internally renders a `<header>` element;\ndoes not compose other ggui primitives.\n\nWhen `sticky` is true the header gets `position: sticky; top: 0` with `zIndex.sticky`\nand a `shadow.sm` box-shadow.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| logo | `ReactNode` | - | Logo or brand element rendered at the start (flex-shrink: 0). |\n| navigation | `ReactNode` | - | Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px left margin. |\n| actions | `ReactNode` | - | Right-side action elements (buttons, avatar, etc.) rendered with a 12 px gap. |\n| sticky | `boolean` | `false` | When true, the header becomes `position: sticky` at the top of its scroll container with `zIndex.sticky` and `shadow.sm`. |\n| background | `string` | `colors.white` | Background color of the header. |\n| bordered | `boolean` | `true` | When true, renders a 1 px bottom border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n```\n\n### Sidebar\n\nProps for the `Sidebar` composition.\n\nA vertical navigation panel that composes the `Icon` primitive for chevron indicators.\nItems are rendered as `<button>` elements inside a scrollable `<nav>`. Nested items\nare indented 16 px per depth level. The sidebar animates width changes with a 200 ms\nCSS transition. Active items are highlighted with `colors.primary[50]` background\nand `colors.primary[700]` text.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `SidebarItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Matched items get a highlighted background and bold text. |\n| onItemClick | `(item: SidebarItem) => void` | - | Called when any item (including parent items with children) is clicked. |\n| collapsed | `boolean` | `false` | When true, hides labels and badges; only icons remain visible, centered in the collapsed width. Nested children are hidden entirely. |\n| header | `ReactNode` | - | Content rendered above the item list, separated by a bottom border. |\n| footer | `ReactNode` | - | Content rendered below the item list, separated by a top border. |\n| width | `number` | `256` | Width in pixels when expanded. |\n| collapsedWidth | `number` | `64` | Width in pixels when collapsed. |\n\n**Example:**\n```tsx\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n```\n\n### CardGrid\n\nProps for the `CardGrid` composition.\n\nA CSS Grid wrapper that arranges children in equal-width columns. When `columns`\nis a number, it produces `repeat(N, 1fr)`. When it is a responsive object,\nit falls back to `repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive behavior.\n\nDoes not compose any ggui primitives internally \u2014 it is a pure layout container.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Card elements to arrange in the grid. |\n| columns | `number \\| { sm?: number; md?: number; lg?: number }` | `3` | Number of columns, or a responsive breakpoint map.  - `number` \u2014 fixed column count via `repeat(N, 1fr)`. - `{ sm?, md?, lg? }` \u2014 triggers `repeat(auto-fit, minmax(280px, 1fr))` for fluid layout. |\n| gap | `number` | `16` | Gap between grid items in pixels. |\n\n**Example:**\n```tsx\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n```\n\n### CommentThread\n\nProps for the `CommentThread` composition.\n\nA threaded comment section that composes `Avatar`, `Button`, `TextArea`, and `Spinner`\nprimitives. Comments are rendered recursively with 40 px indentation per nesting level.\nEach comment shows author avatar, name, timestamp, content, reactions, and a \"Reply\" toggle.\nWhen `currentUser` is provided, a new-comment input with avatar and submit button is shown\nabove the thread.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| comments | `Comment[]` | - | Array of top-level comments to render. Replies are nested within each comment. |\n| currentUser | `{     /** Display name for the current user's avatar. */     name: string;     /** Avatar image URL for the current user. */     avatar?: string;   }` | - | Current user info. When provided, a new-comment input area is rendered above the thread. |\n| onAddComment | `(content: string, parentId?: string) => void` | - | Called when the user submits a new top-level comment. |\n| onReply | `(commentId: string, content: string) => void` | - | Called when the user submits a reply to an existing comment. |\n| onReaction | `(commentId: string, emoji: string) => void` | - | Called when the user clicks an emoji reaction on a comment. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the comment list. |\n\n**Example:**\n```tsx\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n```\n\n### DataTable\n\nProps for the `DataTable` composition.\n\nA sortable, selectable data table that composes `Checkbox`, `Spinner`, and `Icon`\nprimitives. Renders a `<table>` inside a bordered container with 8 px border-radius.\nThe header row has a `colors.gray[50]` background. Sortable columns show a chevron\nicon on click (toggles asc/desc). Selected rows are highlighted with `colors.primary[50]`.\nRow background transitions use a 150 ms ease. The \"select all\" checkbox supports an\nindeterminate state when a subset of rows is selected.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `DataTableColumn<T>[]` | - | Column definitions that control header, alignment, sorting, and rendering. |\n| data | `T[]` | - | Row data array. Each entry corresponds to one table row. |\n| rowKey | `string \\| ((row: T) => string)` | `'id'` | Property name or function used to derive a unique key for each row. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of table body rows. |\n| emptyText | `string` | `'No data'` | Text shown when `data` is empty and not loading. |\n| onSort | `(key: string, direction: 'asc' \\| 'desc') => void` | - | Called when a sortable column header is clicked. Toggles direction automatically (asc -> desc) if the same column is clicked again. |\n| sortKey | `string` | - | The column key currently being sorted. |\n| sortDirection | `'asc' \\| 'desc'` | - | The current sort direction. |\n| onRowClick | `(row: T, index: number) => void` | - | Called when a row is clicked. Rows get `cursor: pointer` when this handler is provided. |\n| selectable | `boolean` | - | When true, adds a checkbox column at the start of each row. |\n| selectedKeys | `string[]` | `[]` | Array of currently selected row keys. |\n| onSelectionChange | `(keys: string[]) => void` | - | Called when the set of selected row keys changes (via row checkbox or select-all). |\n\n**Example:**\n```tsx\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n```\n\n### ChatWindow\n\nProps for the `ChatWindow` composition.\n\nA messaging interface that composes `Avatar`, `Button`, `Spinner`, and `Icon` primitives.\nLayout is a flex column filling 100% height with a bordered `radius.lg` container.\nMessages from the current user align right with `colors.primary[600]` bubbles and white text.\nOther users' messages align left with `colors.gray[100]` bubbles. The message area\nauto-scrolls to the bottom on new messages via `scrollIntoView({ behavior: 'smooth' })`.\nThe text input sends on Enter (Shift+Enter for newline).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| messages | `ChatMessage[]` | - | Array of chat messages to display in chronological order. |\n| currentUserId | `string` | - | ID of the current user. Messages from this user render right-aligned with a primary color bubble. |\n| onSendMessage | `(content: string) => void` | - | Called when the user submits a message (Enter key or send button). |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the message list. |\n| typing | `{ name: string } \\| null` | - | When non-null, displays a typing indicator below the last message (e.g., \"Alice is typing...\"). |\n| placeholder | `string` | `'Type a message...'` | Placeholder text for the message input field. |\n| header | `ReactNode` | - | Optional header content rendered above the message area, separated by a bottom border. |\n\n**Example:**\n```tsx\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n```\n\n### NavigationBar\n\nProps for the `NavigationBar` composition.\n\nA horizontal or vertical navigation menu. Does not compose other ggui primitives\n(uses plain `<button>` and `<a>` elements). Active items are styled per variant:\n\n- `'default'` \u2014 active item gets `colors.primary[600]` text and medium font weight.\n- `'pills'` \u2014 active item gets a `radius.full` pill with `colors.primary[100]` background.\n- `'underline'` \u2014 active item gets a 2 px bottom border in `colors.primary[600]`.\n  When horizontal, the entire nav also has a 1 px bottom border.\n\nAll items have a 150 ms transition on all properties.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `NavItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Controls visual highlighting per variant style. |\n| onItemClick | `(item: NavItem) => void` | - | Called when a non-disabled item is clicked. For `<a>` elements, `preventDefault` is called first. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Layout direction. - `'horizontal'` \u2014 flex-row with 4 px gap. - `'vertical'` \u2014 flex-column with 2 px gap. |\n| variant | `'default' \\| 'pills' \\| 'underline'` | `'default'` | Visual style for active/inactive items. - `'default'` \u2014 text color change only. - `'pills'` \u2014 rounded pill background on active items. - `'underline'` \u2014 bottom border on active items. |\n\n**Example:**\n```tsx\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n```\n\n### FileUploader\n\nProps for the `FileUploader` composition.\n\nA drag-and-drop file upload area that composes `Button`, `Progress`, and `Icon` primitives.\nThe drop zone is a dashed-border container that highlights in `colors.primary[400]`/`colors.primary[50]`\non drag-over. Below the drop zone, each file in `files` is listed with its name, size,\noptional progress bar (for uploading status), and a remove button.\n\nFile validation (max size, max count) is applied client-side before calling `onFilesSelected`.\nFiles exceeding `maxSize` are silently filtered out; files exceeding `maxFiles` are truncated.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| files | `UploadedFile[]` | `[]` | Array of files currently in the upload queue, shown below the drop zone. |\n| onFilesSelected | `(files: File[]) => void` | - | Called when the user selects files via click or drag-and-drop. Receives native `File` objects after client-side filtering (maxSize, maxFiles). |\n| onFileRemove | `(fileId: string) => void` | - | Called when the user clicks the remove button on a file entry. |\n| accept | `string` | - | Accepted file types passed to the hidden `<input type=\"file\" accept=\"...\">`. E.g., `'image/*,.pdf'`. |\n| multiple | `boolean` | `true` | When true, allows selecting multiple files at once. |\n| maxSize | `number` | - | Maximum file size in bytes. Files exceeding this are silently excluded from the selection. |\n| maxFiles | `number` | - | Maximum number of files. Excess files beyond `maxFiles - files.length` are truncated. |\n| disabled | `boolean` | - | When true, the drop zone is visually dimmed (opacity 0.5) and non-interactive. |\n| dragDrop | `boolean` | `true` | When true, enables drag-and-drop on the drop zone. When false, the prompt text changes to \"Click to browse files\". |\n\n**Example:**\n```tsx\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n```\n\n### NotificationCenter\n\nProps for the `NotificationCenter` composition.\n\nA notification list with a header bar that composes `Button`, `Spinner`, and `Icon`\nprimitives. The header shows a \"Notifications\" title, an unread count badge\n(pill in `colors.primary[100]`), and \"Mark all read\" / \"Clear all\" buttons.\nEach notification item shows a colored status dot, title, message, timestamp,\n\"Mark as read\" link, and optional action. The list is scrollable (`overflowY: auto`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| notifications | `Notification[]` | - | Array of notifications to display, in the order provided. |\n| onMarkAsRead | `(id: string) => void` | - | Called when the user clicks \"Mark as read\" on an individual notification. |\n| onMarkAllAsRead | `() => void` | - | Called when the user clicks the \"Mark all read\" header button. Only shown when there are unread items. |\n| onDismiss | `(id: string) => void` | - | Called when the user clicks the dismiss (X) button on an individual notification. |\n| onClearAll | `() => void` | - | Called when the user clicks the \"Clear all\" header button. Only shown when there are any notifications. |\n| emptyText | `string` | `'No notifications'` | Text shown when `notifications` is empty and not loading. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the notification list. |\n\n**Example:**\n```tsx\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n```\n\n### Modal\n\nProps for the `Modal` composition.\n\nA dialog overlay that composes `Button`, `Icon`, and `Heading` primitives.\nThe overlay uses `animation.fadeIn` (`ggui-fadeIn`) and the dialog panel uses\n`animation.scaleIn` (`ggui-scaleIn`) \u2014 both GPU-composited (opacity + transform).\nWhen open, `document.body.style.overflow` is set to `'hidden'` to prevent background\nscrolling, and restored on close. The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`.\n\nSize widths: `sm` = 400 px, `md` = 500 px, `lg` = 640 px, `xl` = 800 px,\n`full` = 100vw (no border-radius, no padding).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls modal visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the modal (overlay click, escape key, or close button). |\n| title | `string` | - | Optional title rendered in the modal header via the `Heading` primitive (level 4). |\n| children | `ReactNode` | - | Modal body content rendered in a scrollable area (`overflowY: auto`). |\n| footer | `ReactNode` | - | Footer content rendered below the body, right-aligned with an 8 px gap, separated by a top border. |\n| size | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'` | Controls the width of the modal panel. - `'sm'` \u2014 400 px - `'md'` \u2014 500 px - `'lg'` \u2014 640 px - `'xl'` \u2014 800 px - `'full'` \u2014 100vw, no border-radius, stretches to fill viewport |\n| closeOnOverlayClick | `boolean` | `true` | When true, clicking the semi-transparent overlay behind the modal calls `onClose`. |\n| closeOnEscape | `boolean` | `true` | When true, pressing the Escape key calls `onClose`. |\n| showCloseButton | `boolean` | `true` | When true, renders a ghost close button (X icon) in the modal header. |\n\n**Example:**\n```tsx\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n```\n\n### CommandPalette\n\nProps for the `CommandPalette` composition.\n\nA searchable command menu (Cmd+K / Ctrl+K pattern) that composes `Spinner` and `Icon`\nprimitives. Appears as a centered overlay at 15vh from the top. Commands are filtered\nby label and description (case-insensitive substring match). Results are grouped under\nuppercase section headers. Keyboard navigation is fully supported:\nArrow Up/Down to navigate, Enter to select, Escape to close.\n\nWhen `recentIds` are provided and the search query is empty, matching commands appear\nin a \"Recent\" section at the top (deduplicated from their original groups).\n\nThe footer shows navigation hints: \"Up/Down Navigate\", \"Enter Select\", \"Esc Close\".\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls palette visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the palette (overlay click, Escape key, or after command selection). |\n| commands | `Command[]` | - | Full array of available commands. Filtered client-side by the search query. |\n| onSelect | `(command: Command) => void` | - | Called when a non-disabled command is selected (Enter key or click). The palette auto-closes after selection. |\n| placeholder | `string` | `'Search commands...'` | Placeholder text for the search input. |\n| recentIds | `string[]` | `[]` | IDs of recently used commands. When the query is empty, these appear in a \"Recent\" section at the top of the results. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the command list. |\n\n**Example:**\n```tsx\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n```\n\n### Footer\n\nProps for the `Footer` composition.\n\nA site footer with `role=\"contentinfo\"` that lays out a brand slot, link columns,\nsocial icons, and a bottom bar. Does not compose other ggui primitives (uses plain\nHTML elements). Content is constrained to `max-width: 1280px` with auto margins.\nLink columns use a responsive flex layout (`flex: 0 1 180px`). The bottom bar\nincludes copyright text, social links, and bottom-bar links separated by a top border.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| brand | `ReactNode` | - | Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`). |\n| columns | `FooterColumn[]` | - | Array of link columns rendered in a flex-wrap layout with 48 px gap. |\n| socialLinks | `FooterSocialLink[]` | - | Social media icon links rendered in the bottom bar. |\n| bottomText | `string` | - | Text displayed at the start of the bottom bar (e.g., copyright notice). |\n| bottomLinks | `FooterLink[]` | - | Links displayed in the bottom bar after social icons (e.g., Privacy, Terms). |\n| background | `string` | `colors.gray[50]` | Background color of the footer. |\n| bordered | `boolean` | `true` | When true, renders a 1 px top border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n```\n\n### Hero\n\nProps for the `Hero` composition.\n\nA prominent landing-page hero section that renders heading, description, CTA buttons,\nand an optional media slot. Does not compose other ggui primitives (uses plain HTML\nelements styled with design tokens). Content is constrained to `max-width: 1280px`.\n\nLayout modes:\n- `align='center'` \u2014 single-column centered layout with `max-width: 800px` text area.\n- `align='left'` \u2014 two-column side-by-side layout (50/50 split with media slot).\n\nSize controls vertical padding and font sizes:\n- `'sm'` \u2014 48 px vertical padding, 3xl heading, lg description.\n- `'md'` \u2014 80 px vertical padding, 4xl heading, xl description.\n- `'lg'` \u2014 120 px vertical padding, 5xl heading, xl description.\n\nThe primary action button uses `colors.primary[600]` fill; the secondary action uses\nan outlined style. When `overlay` is true with a `backgroundImage`, text switches to white\nand borders become semi-transparent.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| heading | `string` | - | Main heading text rendered as an `<h1>` with bold weight and tight line-height. |\n| description | `string` | - | Description paragraph rendered below the heading with relaxed line-height. |\n| primaryAction | `HeroAction` | - | Primary CTA button rendered with `colors.primary[600]` background and white text. |\n| secondaryAction | `HeroAction` | - | Secondary CTA button rendered with a transparent background and a 1 px border. |\n| media | `ReactNode` | - | Media element (image, video, illustration) rendered beside or below the text content. |\n| align | `'center' \\| 'left'` | `'center'` | Text and layout alignment. - `'center'` \u2014 centered single-column layout. - `'left'` \u2014 left-aligned text with media in a right column (50/50 split). |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls vertical padding and heading/description font sizes. - `'sm'` \u2014 compact (48 px padding, 3xl/lg fonts). - `'md'` \u2014 standard (80 px padding, 4xl/xl fonts). - `'lg'` \u2014 spacious (120 px padding, 5xl/xl fonts). |\n| background | `string` | `colors.white (when no backgroundImage is set)` | Background color of the hero section. |\n| backgroundImage | `string` | - | Background image URL applied as `background-size: cover; background-position: center`. |\n| overlay | `boolean` | `false` | When true and `backgroundImage` is set, renders a semi-transparent black overlay (`rgba(0,0,0,0.5)`) and switches text to white/semi-transparent white for contrast. |\n\n**Example:**\n```tsx\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n```\n\n### Support Types\n\n**SidebarItem:**\n\nA single navigation entry in a `Sidebar`. Supports nested children for\ncollapsible sub-menus and an optional badge slot.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the item. Hidden when the sidebar is collapsed. |\n| icon | `ReactNode` | Leading icon rendered before the label. Remains visible when collapsed. |\n| href | `string` | Optional URL associated with this item (not rendered as a link by default). |\n| badge | `ReactNode` | Trailing badge element (e.g., unread count). Hidden when collapsed. |\n| children | `SidebarItem[]` | Nested child items. When present, the item acts as a collapsible section (chevron indicator shown). |\n| disabled | `boolean` | When true, the item is visually dimmed and non-interactive (`cursor: not-allowed`). |\n\n**Comment:**\n\nA single comment entry in a `CommentThread`. Supports nested replies\nand emoji reactions with counts.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this comment. |\n| author | `{     /** Display name of the author. */     name: string;     /** URL for the author's avatar image. Passed to the `Avatar` primitive. */     avatar?: string;   }` | Comment author metadata. |\n| content | `string` | The comment body text. |\n| timestamp | `string \\| Date` | Timestamp of the comment. Rendered via `toLocaleString()` when a `Date` object. |\n| replies | `Comment[]` | Nested reply comments. Each reply is rendered indented 40 px deeper. |\n| reactions | `{ emoji: string; count: number }[]` | Emoji reactions with their aggregated counts (e.g., `{ emoji: \"\u{1F44D}\", count: 3 }`). |\n\n**DataTableColumn:**\n\nColumn definition for a `DataTable`. Controls header text, width, alignment,\nsorting, and custom cell rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key on the row object used to extract cell values. Also serves as the sort key. |\n| header | `string` | Column header text displayed in the `<thead>`. |\n| width | `number \\| string` | Column width as a CSS value (number for pixels, string for any CSS unit). |\n| sortable | `boolean` | When true, the column header is clickable and triggers `onSort`. An arrow icon indicates direction. |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When omitted, the raw value is stringified via `String()`. |\n| align | `'left' \\| 'center' \\| 'right'` | Text alignment for both header and body cells. |\n\n**ChatMessage:**\n\nA single message in a `ChatWindow`. Includes sender metadata, delivery status,\nand a timestamp.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this message. |\n| content | `string` | The message body text. |\n| sender | `{     /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */     id: string;     /** Display name of the sender. */     name: string;     /** Avatar image URL. Only shown for non-current-user messages (xs size). */     avatar?: string;   }` | Sender metadata used for avatar rendering and alignment. |\n| timestamp | `string \\| Date` | Message timestamp. Rendered as `HH:MM` via `toLocaleTimeString` when a `Date` object. |\n| status | `'sending' \\| 'sent' \\| 'delivered' \\| 'read' \\| 'error'` | Delivery status indicator shown on the current user's messages. - `'sending'` \u2014 shows a dot bullet - `'sent'` \u2014 shows a single checkmark - `'delivered'` \u2014 shows double checkmarks - `'read'` \u2014 shows double checkmarks (same visual as delivered) - `'error'` \u2014 shows an exclamation mark |\n\n**NavItem:**\n\nA single navigation entry in a `NavigationBar`. Supports nested children\nfor sub-menus (rendered by the parent via dropdown, not built-in).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the navigation link. |\n| href | `string` | URL for the item. When provided, renders an `<a>` element instead of `<button>`. |\n| icon | `ReactNode` | Optional icon rendered before the label. |\n| children | `NavItem[]` | Nested child items (for sub-menu structures; rendering is consumer-defined). |\n| disabled | `boolean` | When true, the item is visually dimmed (opacity 0.5) and non-interactive. |\n\n**UploadedFile:**\n\nA file entry in the `FileUploader` composition. Tracks upload progress,\nstatus, and optional error messages.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this file entry. Used as a key and for removal callbacks. |\n| name | `string` | Original file name. Rendered with text-overflow ellipsis when too long. |\n| size | `number` | File size in bytes. Formatted as B/KB/MB/GB for display. |\n| type | `string` | MIME type of the file (e.g., `'image/png'`). |\n| progress | `number` | Upload progress as a percentage (0-100). Shown via the `Progress` primitive when status is `'uploading'`. |\n| status | `'pending' \\| 'uploading' \\| 'success' \\| 'error'` | Current upload lifecycle status. - `'pending'` \u2014 file selected but upload not started. - `'uploading'` \u2014 upload in progress; `progress` bar is shown. - `'success'` \u2014 upload completed. - `'error'` \u2014 upload failed; `error` message is shown in `colors.error[500]`. |\n| error | `string` | Error message displayed when status is `'error'`. |\n| url | `string` | The remote URL of the uploaded file after successful upload. |\n\n**Notification:**\n\nA single notification entry in the `NotificationCenter`. Supports semantic type coloring,\nread state, and an optional inline action button.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this notification. |\n| title | `string` | Notification title rendered in medium weight. |\n| message | `string` | Optional body text rendered below the title in a smaller font. |\n| timestamp | `string \\| Date` | Timestamp of the notification. Rendered via `toLocaleString()` when a `Date` object. |\n| read | `boolean` | Read state. Unread notifications get a `colors.primary[50]` background and a colored status dot matching the notification type. |\n| type | `'info' \\| 'success' \\| 'warning' \\| 'error'` | Semantic type that controls the status dot color on unread notifications. - `'info'` \u2014 `colors.info[500]` (blue) - `'success'` \u2014 `colors.success[500]` (green) - `'warning'` \u2014 `colors.warning[500]` (amber) - `'error'` \u2014 `colors.error[500]` (red) |\n| icon | `ReactNode` | Optional icon rendered alongside the notification (not used by the default implementation). |\n| action | `{     /** Button label text. */     label: string;     /** Click handler for the action. */     onClick: () => void;   }` | Optional inline action button rendered next to the timestamp. |\n\n**Command:**\n\nA single command entry in a `CommandPalette`. Commands can be grouped,\nhave keyboard shortcuts, and support a disabled state.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this command. |\n| label | `string` | Display label for the command. Searchable by the palette's query filter. |\n| description | `string` | Optional description text shown below the label. Also searchable. |\n| icon | `ReactNode` | Icon rendered at the start of the command row. |\n| shortcut | `string` | Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element. |\n| group | `string` | Group name for visual sectioning. Commands with the same group are rendered under a shared header. Defaults to `'Commands'` if omitted. |\n| disabled | `boolean` | When true, the command is visually dimmed and cannot be selected. |\n\n**FooterLink:**\n\nA single link entry in a footer column or the bottom bar. Supports both\n`href` navigation and `onClick` handlers (onClick takes precedence via `preventDefault`).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for the link. |\n| href | `string` | URL for the link. |\n| onClick | `() => void` | Click handler. When provided, `preventDefault` is called on the anchor click. |\n\n**FooterColumn:**\n\nA named column of links in the `Footer` layout. Each column has an optional title\nand a list of links rendered as a vertical stack with 10 px gap.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| title | `string` | Column heading rendered as an `<h4>` with semibold weight. |\n| links | `FooterLink[]` | Links displayed in this column. |\n\n**FooterSocialLink:**\n\nA social media link in the `Footer` bottom bar. Rendered as an icon-only anchor\nwith `aria-label` for accessibility.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Accessible label for the social link (used as `aria-label`). |\n| href | `string` | URL for the social media profile or page. |\n| icon | `ReactNode` | Icon element rendered inside the anchor (typically an SVG or `Icon` primitive). |\n\n**HeroAction:**\n\nA call-to-action button definition for the `Hero` composition.\nUsed for both the primary (filled) and secondary (outlined) action buttons.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Button label text. |\n| onClick | `() => void` | Click handler for the button. |\n| href | `string` | Optional URL (not used by the default implementation; available for consumer routing). |\n\n\n## System Conventions\n\n### onChange Behavior (CRITICAL)\n\nAll form control onChange handlers receive the VALUE DIRECTLY, not a React event object.\n\n```tsx\n// CORRECT \u2014 onChange receives value directly\n<Input value={name} onChange={setName} />\n<Input value={email} onChange={(value) => setEmail(value)} />\n<Select value={country} onChange={setCountry} options={countries} />\n<Checkbox checked={agreed} onChange={setAgreed} />\n\n// WRONG \u2014 DO NOT use e.target.value!\n<Input value={name} onChange={(e) => setName(e.target.value)} /> // WILL BREAK\n```\n\nApplies to: Input, TextArea, Select, Checkbox, RadioGroup, Slider, Tabs, Accordion.\n\n### Available Motion & Animation\n\nRender `<MotionKeyframes />` once (anywhere in tree) to enable all keyframes.\n\n**Entrance/exit:** fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n**State feedback:** flash (background-color highlight), pulse (opacity breathing), bounce (scale overshoot)\n**Easing:** linear, easeIn, easeOut, easeInOut, spring (bouncy)\n**Durations:** instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n\n```tsx\n// Entrance animation on mount\n<div style={{ animation: 'ggui-fadeIn 200ms ease-out' }}>Content</div>\n\n// Stagger list items\n{items.map((item, i) => (\n  <div key={item.id} style={{ animation: \\`ggui-slideInUp 300ms ease-out \\${i * 50}ms both\\` }}>\n    {item.name}\n  </div>\n))}\n\n// Flash highlight when data changes (e.g., stock price update)\n// useAnimationKey returns a key that increments when dep changes \u2192 remounts element \u2192 replays animation\nconst priceKey = useAnimationKey(stock.price);\n<div key={priceKey} style={{\n  animation: animation.flash,\n  '--ggui-flash-color': stock.change > 0 ? 'var(--ggui-color-success-100)' : 'var(--ggui-color-error-100)',\n} as React.CSSProperties}>\n  {stock.price}\n</div>\n\n// Respect reduced-motion preference\nconst { motionEnabled } = useMotion();\n<div style={motionEnabled ? { animation: 'ggui-scaleIn 200ms ease-out' } : undefined}>\n  Content\n</div>\n```\n\n### Elevation System\n\n6 levels mapping shadow intensity to z-index for layering:\n- Level 0: flat (no shadow, z: auto) \u2014 inline content\n- Level 1: sm shadow (z: auto) \u2014 cards, sections\n- Level 2: md shadow (z: 1000) \u2014 dropdowns, popovers\n- Level 3: lg shadow (z: 1200) \u2014 sticky banners\n- Level 4: xl shadow (z: 1400) \u2014 modals, dialogs\n- Level 5: 2xl shadow (z: 1800) \u2014 tooltips, toasts\n\n### Import Constraints\n\nOnly these imports are allowed:\n- `react`\n- `@ggui-ai/design` \u2014 the whole design system (primitives, components, compositions, and the `Clickable` / `Hoverable` / `Pressable` traits) is one import; there are no subpaths\n- `@ggui-ai/wire` (wire hooks)\n\nNo external libraries (lodash, date-fns, etc.). No fetch(). No eval().";
     VALID_PRIMITIVES = [
       "Container",
       "Card",
@@ -5268,6 +5269,56 @@ var init_run_tier0 = __esm({
   }
 });
 
+// src/check/sample-props.ts
+function generateSampleProps(spec) {
+  const props = {};
+  for (const [name, entry] of Object.entries(spec.properties)) {
+    if (entry.example !== void 0) {
+      props[name] = entry.example;
+      continue;
+    }
+    if (entry.default !== void 0) {
+      props[name] = entry.default;
+      continue;
+    }
+    props[name] = synthesizeFromSchema2(entry.schema);
+  }
+  return props;
+}
+function synthesizeFromSchema2(schema) {
+  const declared = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type;
+  switch (declared) {
+    case "string":
+      return "sample";
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return false;
+    case "null":
+      return null;
+    case "array": {
+      if (schema.items) return [synthesizeFromSchema2(schema.items) ?? null];
+      return [];
+    }
+    case "object": {
+      const obj = {};
+      if (schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+          obj[k] = synthesizeFromSchema2(v);
+        }
+      }
+      return obj;
+    }
+    default:
+      return void 0;
+  }
+}
+var init_sample_props = __esm({
+  "src/check/sample-props.ts"() {
+  }
+});
+
 // src/check/index.ts
 var check_exports = {};
 __export(check_exports, {
@@ -5277,6 +5328,7 @@ __export(check_exports, {
   extractPropsInterface: () => extractPropsInterface,
   extractWireCallSites: () => extractWireCallSites,
   extractWireImports: () => extractWireImports,
+  generateSampleProps: () => generateSampleProps,
   inferPropsSpecFromSampleData: () => inferPropsSpecFromSampleData,
   jsonSchemaTypeToTs: () => jsonSchemaTypeToTs,
   lintReactHooks: () => lintReactHooks,
@@ -5296,6 +5348,7 @@ var init_check = __esm({
     init_type_checker();
     init_react_linter();
     init_run_tier0();
+    init_sample_props();
   }
 });
 
@@ -6309,6 +6362,324 @@ var init_cost_tracker = __esm({
     };
   }
 });
+function bankRows(bank) {
+  return [...bank.criteria, ...bank.recipes ?? []];
+}
+var CRITERION_ID, criteriaScopeSchema, bankRowSchema;
+var init_bank = __esm({
+  "src/evaluation/criteria/bank.ts"() {
+    CRITERION_ID = /^[a-z][a-z0-9-]*(?:\.[a-zA-Z][a-zA-Z0-9-]*)+$/;
+    criteriaScopeSchema = z.object({
+      kind: z.string().min(1).optional(),
+      canvas: z.string().min(1).optional(),
+      preset: z.string().min(1).optional()
+    });
+    bankRowSchema = z.object({
+      id: z.string().regex(CRITERION_ID, "a criterion id is family.property[.facet], lower-case family"),
+      group: z.string().optional(),
+      scope: criteriaScopeSchema.default({}),
+      /** Importance, independent of whether anything automated checks it yet. */
+      severity: z.enum(["must", "should"]),
+      /** The method that produces the verdict. */
+      evaluation: z.enum(["instrument", "judge", "human"]),
+      /** The method's readiness — the only source of an `n/a`. */
+      status: z.enum(["live", "reference", "planned", "manual"]),
+      /** The question, answerable yes/no from the frame. */
+      text: z.string().min(1),
+      /** The evidence rule: what the one-sentence evidence must name (a region or element). */
+      evidence: z.string().min(1),
+      /** The templated fix line a feedback channel may consume later; never read in v1. */
+      fix: z.string().optional()
+    });
+    z.object({
+      version: z.string().min(1),
+      applies: z.object({
+        /** `["*"]` = every kind. */
+        kind: z.array(z.string().min(1)).optional(),
+        canvases: z.array(z.string().min(1)).optional()
+      }).optional(),
+      criteria: z.array(bankRowSchema).min(1),
+      recipes: z.array(bankRowSchema).optional()
+    }).superRefine((bank, ctx) => {
+      const seen = /* @__PURE__ */ new Set();
+      const check = (rows, key) => {
+        rows.forEach((c, i) => {
+          if (seen.has(c.id)) ctx.addIssue({ code: "custom", path: [key, i, "id"], message: `duplicate criterion id ${c.id}` });
+          seen.add(c.id);
+        });
+      };
+      check(bank.criteria, "criteria");
+      check(bank.recipes ?? [], "recipes");
+    });
+  }
+});
+function canonicalCriteriaContext(ctx) {
+  const sortKeys = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(
+    Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, sortKeys(v)])
+  ) : value;
+  return JSON.stringify(sortKeys(ctx));
+}
+function criteriaSetIdFor(bankVersion, ctx) {
+  return createHash("sha256").update(`${bankVersion}|${CRITERIA_SELECTOR_VERSION}|${canonicalCriteriaContext(ctx)}`, "utf8").digest("hex").slice(0, 16);
+}
+function matchedScope(row, ctx) {
+  const s = row.scope;
+  const matched = [];
+  if (s.kind !== void 0) {
+    if (ctx.kind !== s.kind) return null;
+    matched.push(`kind=${s.kind}`);
+  }
+  if (s.canvas !== void 0) {
+    if (ctx.canvas !== s.canvas) return null;
+    matched.push(`canvas=${s.canvas}`);
+  }
+  if (s.preset !== void 0) {
+    if (ctx.preset !== s.preset) return null;
+    matched.push(`preset=${s.preset}`);
+  }
+  return matched;
+}
+function selectCriteria(bank, ctx) {
+  const criteriaSetId = criteriaSetIdFor(bank.version, ctx);
+  const applies = bank.applies;
+  if (applies?.canvases !== void 0 && !applies.canvases.includes(ctx.canvas)) return { criteriaSetId, selection: [] };
+  if (applies?.kind !== void 0 && ctx.kind !== void 0 && !applies.kind.includes("*") && !applies.kind.includes(ctx.kind)) {
+    return { criteriaSetId, selection: [] };
+  }
+  const selection = [];
+  for (const row of bankRows(bank)) {
+    const matched = matchedScope(row, ctx);
+    if (matched === null) continue;
+    selection.push(matched.length === 0 ? { id: row.id, source: "static", reason: "static" } : { id: row.id, source: "context", reason: `context: ${matched.join(", ")}` });
+  }
+  return { criteriaSetId, selection };
+}
+var CRITERIA_SELECTOR_VERSION;
+var init_select = __esm({
+  "src/evaluation/criteria/select.ts"() {
+    init_bank();
+    CRITERIA_SELECTOR_VERSION = "selector@2";
+  }
+});
+
+// src/evaluation/criteria/resolve.ts
+function majority(id, answers) {
+  const votes = answers.flatMap((a) => a.filter((x) => x.id === id));
+  if (votes.length === 0) return { verdict: "n/a", evidence: "not answered" };
+  const counts = /* @__PURE__ */ new Map();
+  for (const v of votes) counts.set(v.verdict, (counts.get(v.verdict) ?? 0) + 1);
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  const top = ranked[0];
+  if (ranked.length > 1 && ranked[1][1] === top[1]) return { verdict: "n/a", evidence: "no majority" };
+  const evidence = votes.find((v) => v.verdict === top[0])?.evidence ?? "";
+  return { verdict: top[0], evidence };
+}
+function instrumentRead(kind, m) {
+  if (kind === "fit") {
+    if (m.contentHeight === null) return { verdict: "n/a", evidence: "content height unmeasurable" };
+    return { verdict: m.overflow ? "fail" : "pass", evidence: `content ${m.contentHeight}px against a ${m.viewportHeight}px box` };
+  }
+  if (m.inkRatio === null) return { verdict: "n/a", evidence: "capture unreadable" };
+  return { verdict: "n/a", evidence: `fill ${m.inkRatio.toFixed(3)} reported; no floor ruled` };
+}
+function readRow(row, answers, m) {
+  if (row.evaluation === "judge") return majority(row.id, answers);
+  if (row.evaluation === "human") return { verdict: "n/a", evidence: `reader's column (status ${row.status})` };
+  if (row.status !== "live") return { verdict: "n/a", evidence: `not implemented (status ${row.status})` };
+  const kind = INSTRUMENT_BY_ID[row.id];
+  return kind === void 0 ? { verdict: "n/a", evidence: "instrument not wired (status live, no binding)" } : instrumentRead(kind, m);
+}
+function resolveCriteriaBlock(args) {
+  const byId = new Map(bankRows(args.bank).map((r) => [r.id, r]));
+  const verdicts = [];
+  for (const s of args.selected.selection) {
+    const row = byId.get(s.id);
+    if (row === void 0) continue;
+    const read = readRow(row, args.answers, args.measurements);
+    verdicts.push({ id: row.id, severity: row.severity, method: row.evaluation, status: row.status, source: s.source, verdict: read.verdict, evidence: read.evidence });
+  }
+  return {
+    criteriaSetId: args.selected.criteriaSetId,
+    bankVersion: args.bank.version,
+    selectorVersion: CRITERIA_SELECTOR_VERSION,
+    context: args.context,
+    selection: args.selected.selection,
+    verdicts
+  };
+}
+function criteriaFrameLine(frame) {
+  const box = `${frame.width}\xD7${frame.height}`;
+  if (frame.canvas === "xs-chat-card") {
+    const framedBy = frame.hostLabel !== void 0 ? `inside the host's own frame (${frame.hostLabel}), on the host's ground` : "inside a generic stand-in for the host's frame \u2014 the card's surface with a thin ring and rounded corners, on the page ground";
+    return `This frame is an inline chat card captured at its natural height (at most ${box}, the host's ceiling), ${framedBy}: the host sizes the card to its content and draws that frame, so judge composition and space within the card's own extent, and read the frame and the ground round it as the host's, not the card's.`;
+  }
+  return `This frame is ${box}, a fixed full-screen box the card fills${frame.hostLabel !== void 0 ? ` (${frame.hostLabel})` : ""}: judge composition and space against the whole box, edge to edge.`;
+}
+function criteriaPropsSection(propsJson) {
+  const text = propsJson.length > CRITERIA_PROPS_MAX_CHARS ? `${propsJson.slice(0, CRITERIA_PROPS_MAX_CHARS)}\u2026 (truncated)` : propsJson;
+  return `The one input besides the frame \u2014 the props this card was rendered with. Read them ONLY for rows whose evidence names props (for example, whether a rendered string came from them); every other row is read off the frame alone:
+${text}
+`;
+}
+function buildCriteriaJudgeBlock(bank, selected, inputs = {}) {
+  const byId = new Map(bankRows(bank).map((r) => [r.id, r]));
+  const asked = selected.selection.map((s) => byId.get(s.id)).filter((r) => r !== void 0 && r.evaluation === "judge");
+  if (asked.length === 0) return "";
+  const lines = asked.map((r) => `- ${r.id} (${r.severity}): ${r.text} Evidence must name: ${r.evidence}`);
+  return "## Criteria \u2014 answer each one from the FRAME only\nRead these off the screenshot. Never infer them from the request, the styling profile or any direction text above.\n" + (inputs.frame !== void 0 ? `${criteriaFrameLine(inputs.frame)}
+` : "") + (inputs.propsJson !== void 0 ? criteriaPropsSection(inputs.propsJson) : "") + `${lines.join("\n")}
+Add to your JSON a top-level "criteria" array with exactly these ids: [{ "id": "<id>", "verdict": "pass" | "fail" | "n/a", "evidence": "<one sentence naming the region or element you read it from>" }]. Every row here was selected as applicable to this card, so "n/a" never means "does not apply": use it ONLY when this frame cannot show the criterion \u2014 it is then recorded as not evaluated.`;
+}
+var INSTRUMENT_BY_ID, CRITERIA_PROPS_MAX_CHARS;
+var init_resolve = __esm({
+  "src/evaluation/criteria/resolve.ts"() {
+    init_bank();
+    init_select();
+    INSTRUMENT_BY_ID = {
+      "comp.fit": "fit",
+      "floor.fit": "fit",
+      "finish.canvas.inhabited": "fill"
+    };
+    CRITERIA_PROPS_MAX_CHARS = 2e3;
+  }
+});
+function decodePng(png) {
+  const buf = Buffer.from(png.buffer, png.byteOffset, png.byteLength);
+  if (buf.length < 8 + 25) return { reason: `not a PNG: ${buf.length} bytes` };
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (buf[i] !== PNG_SIGNATURE[i]) return { reason: "not a PNG: signature mismatch" };
+  }
+  let width = 0;
+  let height = 0;
+  let channels = null;
+  const idat = [];
+  let offset = 8;
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString("latin1", offset + 4, offset + 8);
+    const start = offset + 8;
+    if (start + length + 4 > buf.length) return { reason: `truncated PNG: ${type} chunk runs past the end` };
+    const data = buf.subarray(start, start + length);
+    if (type === "IHDR") {
+      if (length !== 13) return { reason: `malformed IHDR: ${length} bytes` };
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      const bitDepth = data[8];
+      const colorType = data[9];
+      const interlace = data[12];
+      if (bitDepth !== 8) return { reason: `unsupported PNG: bit depth ${bitDepth}` };
+      if (interlace !== 0) return { reason: "unsupported PNG: interlaced" };
+      if (colorType === 2) channels = 3;
+      else if (colorType === 6) channels = 4;
+      else return { reason: `unsupported PNG: colour type ${colorType}` };
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+    offset = start + length + 4;
+  }
+  if (channels === null) return { reason: "malformed PNG: no IHDR" };
+  if (width === 0 || height === 0) return { reason: `empty PNG: ${width}\xD7${height}` };
+  if (idat.length === 0) return { reason: "malformed PNG: no IDAT" };
+  let raw;
+  try {
+    raw = inflateSync(Buffer.concat(idat));
+  } catch (error) {
+    return { reason: `corrupt IDAT stream: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const stride = width * channels;
+  if (raw.length !== (stride + 1) * height) {
+    return { reason: `malformed PNG: ${raw.length} raw bytes for ${width}\xD7${height}\xD7${channels}` };
+  }
+  const pixels = new Uint8Array(stride * height);
+  const bpp = channels;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const inRow = y * (stride + 1) + 1;
+    const outRow = y * stride;
+    const prevRow = outRow - stride;
+    for (let i = 0; i < stride; i++) {
+      const x = raw[inRow + i];
+      const a = i >= bpp ? pixels[outRow + i - bpp] : 0;
+      const b = y > 0 ? pixels[prevRow + i] : 0;
+      const c = y > 0 && i >= bpp ? pixels[prevRow + i - bpp] : 0;
+      let value;
+      switch (filter) {
+        case 0:
+          value = x;
+          break;
+        case 1:
+          value = x + a;
+          break;
+        case 2:
+          value = x + b;
+          break;
+        case 3:
+          value = x + (a + b >> 1);
+          break;
+        case 4: {
+          const p = a + b - c;
+          const pa = Math.abs(p - a);
+          const pb = Math.abs(p - b);
+          const pc = Math.abs(p - c);
+          value = x + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+          break;
+        }
+        default:
+          return { reason: `malformed PNG: scanline filter ${filter} at row ${y}` };
+      }
+      pixels[outRow + i] = value & 255;
+    }
+  }
+  return { width, height, channels, pixels };
+}
+function readInkExtent(png, insetPx = 0) {
+  const image = decodePng(png);
+  if ("reason" in image) return image;
+  const region = { x: insetPx, y: insetPx, width: image.width - 2 * insetPx, height: image.height - 2 * insetPx };
+  if (insetPx < 0 || region.width <= 0 || region.height <= 0) {
+    return { reason: `an inset of ${insetPx}px leaves nothing of a ${image.width}\xD7${image.height} image` };
+  }
+  const { channels, pixels, width } = image;
+  const counts = /* @__PURE__ */ new Map();
+  let ground = 0;
+  let groundCount = 0;
+  for (let y = region.y; y < region.y + region.height; y++) {
+    for (let x = region.x; x < region.x + region.width; x++) {
+      const i = (y * width + x) * channels;
+      const key = pixels[i] << 16 | pixels[i + 1] << 8 | pixels[i + 2];
+      const n = (counts.get(key) ?? 0) + 1;
+      counts.set(key, n);
+      if (n > groundCount) {
+        groundCount = n;
+        ground = key;
+      }
+    }
+  }
+  const gr = ground >> 16 & 255;
+  const gg = ground >> 8 & 255;
+  const gb = ground & 255;
+  let lastInkRow = null;
+  for (let y = region.y; y < region.y + region.height; y++) {
+    for (let x = region.x; x < region.x + region.width; x++) {
+      const i = (y * width + x) * channels;
+      if (Math.abs(pixels[i] - gr) > INK_TOLERANCE || Math.abs(pixels[i + 1] - gg) > INK_TOLERANCE || Math.abs(pixels[i + 2] - gb) > INK_TOLERANCE) {
+        lastInkRow = y - region.y;
+        break;
+      }
+    }
+  }
+  const ratio = lastInkRow === null ? 0 : Math.round((lastInkRow + 1) / region.height * 1e3) / 1e3;
+  return { ratio, lastInkRow, region, ground: [gr, gg, gb] };
+}
+var INK_TOLERANCE, PNG_SIGNATURE;
+var init_ink_extent = __esm({
+  "src/evaluation/ink-extent.ts"() {
+    INK_TOLERANCE = 8;
+    PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+  }
+});
 function isDesignRenderingInput(relativePath) {
   const rel = relativePath.split("\\").join("/");
   if (rel.startsWith("__tests__/") || rel.includes("/__tests__/")) return false;
@@ -6361,9 +6732,23 @@ var init_design_identity = __esm({
 // src/evaluation/visual-evaluator.ts
 var visual_evaluator_exports = {};
 __export(visual_evaluator_exports, {
+  CARD_HEIGHT_EXPRESSION: () => CARD_HEIGHT_EXPRESSION,
+  CARD_OVERFLOW_X_EXPRESSION: () => CARD_OVERFLOW_X_EXPRESSION,
   CONTENT_HEIGHT_EXPRESSION: () => CONTENT_HEIGHT_EXPRESSION,
   EXECUTABLE_PATH_LAUNCH_ARGS: () => EXECUTABLE_PATH_LAUNCH_ARGS,
+  HOST_COLOUR_PATTERN: () => HOST_COLOUR_PATTERN,
+  HOST_FRAME_BOUNDS: () => HOST_FRAME_BOUNDS,
+  JUDGE_GROUND_CLASS: () => JUDGE_GROUND_CLASS,
+  JUDGE_GROUND_MARGIN_PX: () => JUDGE_GROUND_MARGIN_PX,
+  JUDGE_INK_INSET_PX: () => JUDGE_INK_INSET_PX,
+  JUDGE_INLINE_FRAME_BORDER_PX: () => JUDGE_INLINE_FRAME_BORDER_PX,
+  JUDGE_INLINE_FRAME_CLASS: () => JUDGE_INLINE_FRAME_CLASS,
+  JUDGE_INLINE_FRAME_RADIUS_PX: () => JUDGE_INLINE_FRAME_RADIUS_PX,
+  JUDGE_INLINE_INK_INSET_PX: () => JUDGE_INLINE_INK_INSET_PX,
+  JUDGE_INLINE_PAD_PX: () => JUDGE_INLINE_PAD_PX,
+  JUDGE_PANEL_CLASS: () => JUDGE_PANEL_CLASS,
   JUDGE_SCOPE_CLASS: () => JUDGE_SCOPE_CLASS,
+  OVERFLOW_X_ROUNDING_PX: () => OVERFLOW_X_ROUNDING_PX,
   VISUAL_EVAL_PROMPT: () => VISUAL_EVAL_PROMPT,
   VISUAL_JUDGE_MAX_OUTPUT_TOKENS: () => VISUAL_JUDGE_MAX_OUTPUT_TOKENS,
   VISUAL_JUDGE_PROMPT_DIGEST: () => VISUAL_JUDGE_PROMPT_DIGEST,
@@ -6371,13 +6756,20 @@ __export(visual_evaluator_exports, {
   buildRenderHTML: () => buildRenderHTML,
   bundleForRendering: () => bundleForRendering,
   callMultimodalLLM: () => callMultimodalLLM,
+  canvasBlankIssue: () => canvasBlankIssue,
+  canvasChrome: () => canvasChrome,
   canvasFit: () => canvasFit,
   canvasFitPolicy: () => canvasFitPolicy,
   canvasOverflowIssue: () => canvasOverflowIssue,
+  canvasOverflowXIssue: () => canvasOverflowXIssue,
   captureScreenshot: () => captureScreenshot,
   captureScreenshotDetailed: () => captureScreenshotDetailed,
+  cardHeightExpression: () => cardHeightExpression,
   integerBox: () => integerBox,
   isDeclaredViewport: () => isDeclaredViewport,
+  judgeStoredCapture: () => judgeStoredCapture,
+  judgeWindow: () => judgeWindow,
+  naturalClip: () => naturalClip,
   resolveDesignPackageDir: () => resolveDesignPackageDir,
   resolveLaunchOptions: () => resolveLaunchOptions,
   resolveUiGenPackageDir: () => resolveUiGenPackageDir,
@@ -6392,7 +6784,7 @@ __export(visual_evaluator_exports, {
 function canvasFitPolicy(canvas) {
   switch (canvas) {
     case "xs-chat-card":
-      return { capture: "viewport", overflow: "fail" };
+      return { capture: "natural", overflow: "fail" };
     case "mobile-fullscreen-small":
       return { capture: "full-page", overflow: "warn" };
     default:
@@ -6402,6 +6794,46 @@ function canvasFitPolicy(canvas) {
 function canvasFit(canvas) {
   return displayModeForCanvas(canvas) === "fullscreen" ? "fill" : void 0;
 }
+function resolvePresentation(canvas, p) {
+  if (p === void 0) return void 0;
+  const ignored = (reason, why) => {
+    console.warn(`[visual-eval] host presentation for ${canvas} ignored (${reason}): ${why}`);
+    return { status: "ignored", reason };
+  };
+  const inline = canvasFitPolicy(canvas).capture === "natural";
+  if (typeof p.label !== "string" || p.label.length === 0) return ignored("label_missing", "no label");
+  if (p.ground !== void 0 && !HOST_COLOUR_PATTERN.test(p.ground)) return ignored("color_not_hex", "ground is not #rrggbb");
+  if (inline && p.ground !== void 0) return ignored("ground_on_inline", "the inline card's room is its frame's ground");
+  const f = p.frame;
+  if (f !== void 0) {
+    if (!inline) return ignored("frame_off_inline", "a frame on a canvas that is not the inline card");
+    if (![f.surface, f.ground, f.ring.color].every((c) => HOST_COLOUR_PATTERN.test(c))) return ignored("color_not_hex", "a frame colour is not #rrggbb");
+    const B = HOST_FRAME_BOUNDS;
+    const inRange = (n, b) => Number.isFinite(n) && n >= b.min && n <= b.max;
+    if (!inRange(f.ring.widthPx, B.ringWidthPx) || !inRange(f.ring.alpha, B.ringAlpha) || !inRange(f.radiusPx, B.radiusPx)) return ignored("frame_malformed", "a frame number out of range");
+    if (f.minHeightPx !== void 0 && !inRange(f.minHeightPx, B.minHeightPx)) return ignored("frame_malformed", "minHeightPx out of range");
+  }
+  return { status: "applied", applied: p };
+}
+function inlineGeometry(frame) {
+  if (frame === void 0) return { padPx: JUDGE_INLINE_PAD_PX, inkInsetPx: JUDGE_INLINE_INK_INSET_PX, floorPx: void 0 };
+  const padPx = JUDGE_GROUND_MARGIN_PX + frame.ring.widthPx;
+  return { padPx, inkInsetPx: padPx + frame.radiusPx, floorPx: frame.minHeightPx };
+}
+function canvasChrome(canvas) {
+  if (canvasFitPolicy(canvas).capture === "natural") return "ground";
+  return canvasFit(canvas) === "fill" && canvas !== "mobile-fullscreen-small" ? "panel" : void 0;
+}
+function judgeWindow(viewport, chrome, inlinePadPx = JUDGE_INLINE_PAD_PX) {
+  if (chrome === void 0) return viewport;
+  const gap = 2 * (chrome === "ground" ? inlinePadPx : EXPANDED_FRAME.insetPx);
+  return { width: viewport.width + gap, height: viewport.height + gap };
+}
+function cardHeight(documentHeight, chrome) {
+  if (documentHeight === null || chrome === void 0 || chrome === "ground") return documentHeight;
+  const gap = 2 * EXPANDED_FRAME.insetPx;
+  return documentHeight < gap ? null : documentHeight - gap;
+}
 function integerBox(viewport) {
   return { width: Math.round(viewport.width), height: Math.round(viewport.height) };
 }
@@ -6420,6 +6852,24 @@ function canvasOverflowIssue(canvas, viewport, contentHeight, verdict) {
     fix: "Fit the composition to the canvas: fewer and shorter sections, one compact row of chips, no hero taller than a third of the box, no fixed min-heights or tall paddings \u2014 measure against the canvas, not the page."
   };
 }
+function canvasOverflowXIssue(canvas, viewport, hiddenPx, verdict) {
+  return {
+    dimension: "canvas-overflow-x",
+    severity: verdict === "fail" ? "critical" : "major",
+    description: `Content runs ${hiddenPx}px past the ${canvas} card's ${viewport.width}px width \u2014 the card's frame clips it, so a visitor sees a cut-off row or a sideways scroll.`,
+    fix: "Keep every row within the card: wrap long text (overflow-wrap: anywhere), let a wide table or code block scroll inside its own container, and give no child a fixed width wider than the card."
+  };
+}
+function canvasBlankIssue(canvas, viewport) {
+  const classBox = CANVAS_VIEWPORTS[canvas];
+  const box = isDeclaredViewport(canvas, viewport) ? `declared ${viewport.width}\xD7${viewport.height}; class box ${classBox.width}\xD7${classBox.height}` : `${viewport.width}\xD7${viewport.height}`;
+  return {
+    dimension: "canvas-blank",
+    severity: "critical",
+    description: `Nothing painted on the ${canvas} canvas (${box}): the capture is one flat colour \u2014 the component mounted and rendered no pixels.`,
+    fix: "Return and paint the component tree: a root that renders nothing is a blank, not an empty state. Check that the default export returns its JSX, that no early return yields null on the sample props, and that the first paint shows visible content."
+  };
+}
 function resolveUiGenPackageDir() {
   const selfDir = dirname(fileURLToPath(import.meta.url));
   return resolve(selfDir, "..", "..");
@@ -6535,7 +6985,16 @@ try {
     rmSync(tmpDir, { recursive: true, force: true });
   }
 }
-function buildRenderHTML(bundledCode, cssTokens, fit) {
+function inlineFrameDecls(frame) {
+  if (frame === void 0) {
+    return `background: var(--ggui-color-container); border: ${JUDGE_INLINE_FRAME_BORDER_PX}px solid color-mix(in srgb, var(--ggui-color-onContainer) 8%, transparent); border-radius: ${JUDGE_INLINE_FRAME_RADIUS_PX}px; overflow: hidden;`;
+  }
+  const alphaPct = Math.round(frame.ring.alpha * 1e3) / 10;
+  return `background: ${frame.surface}; border: ${frame.ring.widthPx}px solid color-mix(in srgb, ${frame.ring.color} ${alphaPct}%, transparent); border-radius: ${frame.radiusPx}px; overflow: hidden;`;
+}
+function buildRenderHTML(bundledCode, cssTokens, fit, chrome, presentation) {
+  if (chrome === "panel" && fit !== "fill") throw new Error("the judge's panel frames a fill canvas only (ggui#1083 cut 3)");
+  if (chrome === "ground" && fit === "fill") throw new Error("the host ground frames an inline card only \u2014 a fill canvas has no natural height (ggui#1475)");
   const tokens = cssTokens ?? getCssTokens();
   return `<!DOCTYPE html>
 <html>
@@ -6550,15 +7009,16 @@ function buildRenderHTML(bundledCode, cssTokens, fit) {
       /* ggui#1083 \u2014 the host stand-in (neutral-50) under the theme's scrim (its tint at
          its opacity): the ground a frosted host puts under the card, so the judge scores
          the card where the visitor sees it. */
-      background: color-mix(in oklch, var(--ggui-scrim-tint, var(--ggui-color-ground, #ffffff)) calc(var(--ggui-scrim-opacity, 0.45) * 100%), var(--ggui-color-neutral-50, #ffffff));
+      ${presentation?.frame !== void 0 ? `background: ${presentation.frame.ground};` : presentation?.ground !== void 0 ? `background: ${presentation.ground};` : expandedFrameScrimDecls()}
       color: var(--ggui-color-neutral-900, #111827);
     }
     .error { color: #dc2626; padding: 16px; font-family: monospace; white-space: pre-wrap; }
-    ${fit === "fill" ? fillFitRule(JUDGE_SCOPE_CLASS) : ""}
+    ${fit === "fill" ? fillFitRule(JUDGE_SCOPE_CLASS) + (chrome === "panel" ? expandedFramePanelRule(JUDGE_PANEL_CLASS, JUDGE_SCOPE_CLASS) : "") : ""}
+    ${chrome === "ground" ? `.${JUDGE_GROUND_CLASS} { padding: ${JUDGE_GROUND_MARGIN_PX}px; } .${JUDGE_INLINE_FRAME_CLASS} { ${inlineFrameDecls(presentation?.frame)} }` : ""}
   </style>
 </head>
 <body>
-  <div id="root"${fit === "fill" ? ` class="${JUDGE_SCOPE_CLASS}"` : ""}></div>
+  ${chrome === "panel" ? `<div class="${JUDGE_PANEL_CLASS}">` : chrome === "ground" ? `<div class="${JUDGE_GROUND_CLASS}"><div class="${JUDGE_INLINE_FRAME_CLASS}">` : ""}<div id="root"${fit === "fill" ? ` class="${JUDGE_SCOPE_CLASS}"` : ""}></div>${chrome === "panel" ? "</div>" : chrome === "ground" ? "</div></div>" : ""}
   <script type="importmap">
   {
     "imports": {
@@ -6603,16 +7063,24 @@ async function launchWithPuppeteer(options) {
   const puppeteer = await import('puppeteer-core');
   return puppeteer.default.launch(options);
 }
-async function measureContentHeight(page) {
+function cardHeightExpression(padPx) {
+  return `(() => { const el = document.documentElement; const prev = el.style.height; el.style.height = 'max-content'; const h = Math.ceil(el.getBoundingClientRect().height); el.style.height = prev; return h - ${2 * padPx}; })()`;
+}
+function naturalClip(window, cardHeightPx, padPx = JUDGE_INLINE_PAD_PX) {
+  const m = padPx;
+  const box = window.height - 2 * m;
+  return { x: 0, y: 0, width: window.width, height: Math.max(1, Math.min(Math.ceil(cardHeightPx), box)) + 2 * m };
+}
+async function measureContentHeight(page, expression = CONTENT_HEIGHT_EXPRESSION) {
   try {
-    const h = await page.evaluate(CONTENT_HEIGHT_EXPRESSION);
+    const h = await page.evaluate(expression);
     return typeof h === "number" && Number.isFinite(h) ? Math.round(h) : null;
   } catch (e) {
     console.warn(`[visual-eval] content height unavailable: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   }
 }
-async function captureScreenshotDetailed(html, viewport = DEFAULT_SCREENSHOT_VIEWPORT, deps = {}, capture = "full-page") {
+async function captureScreenshotDetailed(html, viewport = DEFAULT_SCREENSHOT_VIEWPORT, deps = {}, capture = "full-page", natural = { padPx: JUDGE_INLINE_PAD_PX }) {
   try {
     const launchOptions = await resolveLaunchOptions(viewport, deps);
     const browser = await (deps.launch ?? launchWithPuppeteer)(launchOptions);
@@ -6624,6 +7092,18 @@ async function captureScreenshotDetailed(html, viewport = DEFAULT_SCREENSHOT_VIE
       await page.waitForSelector("#root > *", { timeout: 1e4 }).catch(() => {
       });
       await new Promise((r) => setTimeout(r, deps.settleMs ?? 1e3));
+      if (capture === "natural") {
+        const cardHeightPx = await measureContentHeight(page, natural.padPx === JUDGE_INLINE_PAD_PX ? CARD_HEIGHT_EXPRESSION : cardHeightExpression(natural.padPx));
+        const overflowX = await measureContentHeight(page, CARD_OVERFLOW_X_EXPRESSION);
+        const floorPx = natural.floorPx;
+        if (floorPx !== void 0 && cardHeightPx !== null && cardHeightPx < floorPx) {
+          await page.evaluate(`(() => { const f = document.querySelector('.${JUDGE_INLINE_FRAME_CLASS}'); if (f) f.style.minHeight = '${floorPx}px'; })()`);
+        }
+        const framed = cardHeightPx === null ? viewport.height - 2 * natural.padPx : floorPx !== void 0 ? Math.max(cardHeightPx, floorPx) : cardHeightPx;
+        const clip = naturalClip(viewport, framed, natural.padPx);
+        const screenshot2 = await page.screenshot({ type: "png", fullPage: false, clip });
+        return { png: Buffer.from(screenshot2), contentHeight: cardHeightPx, overflowX };
+      }
       const contentHeight = await measureContentHeight(page);
       const screenshot = await page.screenshot({ type: "png", fullPage: capture === "full-page" });
       return { png: Buffer.from(screenshot), contentHeight };
@@ -6639,12 +7119,14 @@ async function captureScreenshotDetailed(html, viewport = DEFAULT_SCREENSHOT_VIE
 async function captureScreenshot(html, viewport = DEFAULT_SCREENSHOT_VIEWPORT, deps = {}) {
   return (await captureScreenshotDetailed(html, viewport, deps)).png;
 }
-async function callMultimodalLLM(config, model, prompt, screenshot, originalPrompt, profileBlock = "") {
+async function callMultimodalLLM(config, model, prompt, screenshot, originalPrompt, profileBlock = "", criteriaBlock = "") {
   const userPrompt = `## Original Request
 ${originalPrompt}
 
 ` + (profileBlock.length > 0 ? `${profileBlock}
 
+` : "") + (criteriaBlock.length > 0 ? `${criteriaBlock}
+
 ` : "") + "Evaluate the screenshot of the generated component.";
   const agent = createVisionAgent({
     provider: config.provider === "claude" ? "anthropic" : config.provider,
@@ -6659,20 +7141,70 @@ ${originalPrompt}
     VISUAL_JUDGE_MAX_OUTPUT_TOKENS
   );
 }
-async function frameCanvas(bundledCode, context, html, canvas, canvasViewports, deps) {
+function readInk(png, chrome, canvas, inlineInkInsetPx = JUDGE_INLINE_INK_INSET_PX) {
+  if (png === null) return null;
+  const ink = readInkExtent(png, chrome === "panel" ? JUDGE_INK_INSET_PX : chrome === "ground" ? inlineInkInsetPx : 0);
+  if ("reason" in ink) {
+    console.warn(`[visual-eval] ink extent unreadable at canvas ${canvas}: ${ink.reason}`);
+    return null;
+  }
+  return ink;
+}
+function blankVerdict(canvas, frame) {
+  if (frame.chrome === "ground" && frame.attempt.contentHeight !== null && frame.attempt.contentHeight <= 0) {
+    return canvasBlankIssue(canvas, frame.viewport);
+  }
+  return frame.ink !== null && frame.ink.lastInkRow === null ? canvasBlankIssue(canvas, frame.viewport) : null;
+}
+async function frameCanvas(bundledCode, context, html, canvas, canvasViewports, deps, hostPresentations) {
   const declaredBox = canvasViewports?.[canvas];
   const viewport = declaredBox !== void 0 ? integerBox(declaredBox) : CANVAS_VIEWPORTS[canvas];
   const policy = canvasFitPolicy(canvas);
   const fit = canvasFit(canvas);
-  const canvasHtml = fit !== void 0 ? buildRenderHTML(bundledCode, context.cssTokens, fit) : html;
-  const attempt = await captureScreenshotDetailed(canvasHtml, viewport, deps, policy.capture);
-  return { viewport, policy, fit, declared: declaredBox !== void 0, attempt };
+  const chrome = canvasChrome(canvas);
+  const outcome = resolvePresentation(canvas, hostPresentations?.[canvas]);
+  const presentation = outcome?.status === "applied" ? outcome.applied : void 0;
+  const geometry = inlineGeometry(presentation?.frame);
+  const canvasHtml = fit !== void 0 || chrome !== void 0 ? buildRenderHTML(bundledCode, context.cssTokens, fit, chrome, presentation) : html;
+  const captured = await captureScreenshotDetailed(canvasHtml, judgeWindow(viewport, chrome, geometry.padPx), deps, policy.capture, {
+    padPx: geometry.padPx,
+    ...geometry.floorPx !== void 0 ? { floorPx: geometry.floorPx } : {}
+  });
+  const attempt = { ...captured, contentHeight: cardHeight(captured.contentHeight, chrome) };
+  return {
+    viewport,
+    policy,
+    fit,
+    chrome,
+    declared: declaredBox !== void 0,
+    attempt,
+    ink: readInk(captured.png, chrome, canvas, geometry.inkInsetPx),
+    ...outcome !== void 0 ? { presentation: outcome } : {}
+  };
 }
 function fitVerdict(canvas, frame) {
   const contentHeight = frame.attempt.contentHeight;
   if (contentHeight === null || contentHeight <= frame.viewport.height || frame.policy.overflow === "none") return null;
   return canvasOverflowIssue(canvas, frame.viewport, contentHeight, frame.policy.overflow);
 }
+function overflowXVerdict(canvas, frame) {
+  const px = frame.attempt.overflowX;
+  if (px === void 0 || px === null || px <= OVERFLOW_X_ROUNDING_PX || frame.policy.overflow === "none") return null;
+  return canvasOverflowXIssue(canvas, frame.viewport, px, frame.policy.overflow);
+}
+async function judgeFrame(judge, config, model, png, originalPrompt, profileBlock, canvas, k, criteriaBlock) {
+  const [scoring, criteria] = await Promise.all([
+    Promise.all(Array.from({ length: k }, () => judgeAndParse(judge, config, model, png, originalPrompt, profileBlock, canvas))),
+    criteriaBlock.length > 0 ? judgeAndParse(judge, config, model, png, originalPrompt, profileBlock, canvas, criteriaBlock) : void 0
+  ]);
+  return { scoring, criteria };
+}
+function criteriaCallTokens(criteria) {
+  return criteria?.kind === "ok" ? { inputTokens: criteria.inputTokens, outputTokens: criteria.outputTokens } : void 0;
+}
+function criteriaReads(criteria) {
+  return criteria?.kind === "ok" ? [criteria.result.criteriaAnswers ?? []] : [];
+}
 function judgeCountFor(config, canvas) {
   const k = Math.max(1, Math.floor(config.judgeK ?? 1));
   if (k === 1) return 1;
@@ -6688,10 +7220,10 @@ function populationSigma(values) {
   const variance = values.reduce((a, b) => a + (b - mean) ** 2, 0) / values.length;
   return Math.round(Math.sqrt(variance) * 10) / 10;
 }
-async function judgeAndParse(judge, config, model, screenshot, originalPrompt, profileBlock, canvas) {
+async function judgeAndParse(judge, config, model, screenshot, originalPrompt, profileBlock, canvas, criteriaBlock = "") {
   let firstReason;
   for (let attempt = 1; attempt <= 2; attempt++) {
-    const response = await judge(config, model, VISUAL_EVAL_PROMPT, screenshot, originalPrompt, profileBlock);
+    const response = await judge(config, model, VISUAL_EVAL_PROMPT, screenshot, originalPrompt, profileBlock, criteriaBlock);
     try {
       const result = parseVisualResponse(response.text, config.passThreshold);
       return { kind: "ok", result, inputTokens: response.inputTokens, outputTokens: response.outputTokens };
@@ -6740,7 +7272,7 @@ async function runVisualEvaluationDetailed(context, config, deps = {}) {
     const perCanvas = [];
     const perCanvasResults = [];
     for (const canvas of config.canvases) {
-      const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps);
+      const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps, config.hostPresentations);
       const { viewport, policy, fit, attempt: attempt2 } = frame;
       const screenshot2 = attempt2.png;
       if (!screenshot2) {
@@ -6750,8 +7282,22 @@ async function runVisualEvaluationDetailed(context, config, deps = {}) {
       }
       const k = judgeCountFor(config, canvas);
       const profileBlock = buildStylingProfileJudgeBlock(context.profile);
-      const answers = await Promise.all(
-        Array.from({ length: k }, () => judgeAndParse(judge, config, model, screenshot2, context.originalPrompt, profileBlock, canvas))
+      const criteriaContext = context.criteria !== void 0 ? { ...context.criteria.context, canvas } : void 0;
+      const criteriaSelected = context.criteria !== void 0 && criteriaContext !== void 0 ? selectCriteria(context.criteria.bank, criteriaContext) : void 0;
+      const criteriaBlock = context.criteria !== void 0 && criteriaSelected !== void 0 ? buildCriteriaJudgeBlock(context.criteria.bank, criteriaSelected, {
+        frame: { canvas, width: viewport.width, height: viewport.height, ...frame.presentation?.status === "applied" ? { hostLabel: frame.presentation.applied.label } : {} },
+        ...config.sampleProps !== void 0 ? { propsJson: JSON.stringify(config.sampleProps) } : {}
+      }) : "";
+      const { scoring: answers, criteria: criteriaAnswer } = await judgeFrame(
+        judge,
+        config,
+        model,
+        screenshot2,
+        context.originalPrompt,
+        profileBlock,
+        canvas,
+        k,
+        criteriaBlock
       );
       const parsed = answers.filter((a) => a.kind === "ok");
       if (parsed.length === 0) {
@@ -6767,6 +7313,7 @@ async function runVisualEvaluationDetailed(context, config, deps = {}) {
       result2.inputTokens = parsed.reduce((sum, a) => sum + a.inputTokens, 0);
       result2.outputTokens = parsed.reduce((sum, a) => sum + a.outputTokens, 0);
       const response2 = { inputTokens: result2.inputTokens, outputTokens: result2.outputTokens };
+      const criteriaTokens = criteriaCallTokens(criteriaAnswer);
       const judgeRecord = {
         k,
         rule: "median",
@@ -6781,6 +7328,24 @@ async function runVisualEvaluationDetailed(context, config, deps = {}) {
         result2.issues.push(fitIssue);
         if (policy.overflow === "fail") result2.passed = false;
       }
+      const overflowXIssue = overflowXVerdict(canvas, frame);
+      if (overflowXIssue !== null) {
+        result2.issues.push(overflowXIssue);
+        if (policy.overflow === "fail") result2.passed = false;
+      }
+      const blankIssue = blankVerdict(canvas, frame);
+      if (blankIssue !== null) {
+        result2.issues.push(blankIssue);
+        result2.passed = false;
+      }
+      const inkRatio = frame.ink?.ratio ?? null;
+      const criteria = context.criteria !== void 0 && criteriaContext !== void 0 && criteriaSelected !== void 0 ? resolveCriteriaBlock({
+        bank: context.criteria.bank,
+        context: criteriaContext,
+        selected: criteriaSelected,
+        answers: criteriaReads(criteriaAnswer),
+        measurements: { overflow, contentHeight, viewportHeight: viewport.height, inkRatio }
+      }) : void 0;
       perCanvasResults.push(result2);
       perCanvas.push({
         canvas,
@@ -6790,12 +7355,16 @@ async function runVisualEvaluationDetailed(context, config, deps = {}) {
         screenshotPng: screenshot2,
         contentHeight,
         overflow,
+        inkRatio,
         judge: judgeRecord,
         ...fit !== void 0 ? { fit } : {},
-        ...frame.declared ? { declared: true } : {}
+        ...frame.declared ? { declared: true } : {},
+        ...criteria !== void 0 ? { criteria } : {},
+        ...criteriaTokens !== void 0 ? { criteriaTokens } : {},
+        ...frame.presentation !== void 0 ? { presentation: frame.presentation } : {}
       });
       console.log(
-        `[visual-eval] canvas=${canvas} ${viewport.width}\xD7${viewport.height} score=${result2.finalScore}${k > 1 ? ` (median of ${judgeRecord.samples.length}/${k}: ${judgeRecord.samples.join(",")} \u03C3=${judgeRecord.sigma})` : ""} ${result2.passed ? "pass" : "FAIL"} | content=${contentHeight ?? "?"}px${overflow ? ` OVERFLOW (${policy.overflow})` : ""} | in=${response2.inputTokens} out=${response2.outputTokens}`
+        `[visual-eval] canvas=${canvas} ${viewport.width}\xD7${viewport.height} score=${result2.finalScore}${k > 1 ? ` (median of ${judgeRecord.samples.length}/${k}: ${judgeRecord.samples.join(",")} \u03C3=${judgeRecord.sigma})` : ""} ${result2.passed ? "pass" : "FAIL"} | content=${contentHeight ?? "?"}px${overflow ? ` OVERFLOW (${policy.overflow})` : ""} ink=${inkRatio ?? "?"}${blankIssue !== null ? " BLANK" : ""} | in=${response2.inputTokens} out=${response2.outputTokens}` + (criteriaTokens !== void 0 ? ` | criteria in=${criteriaTokens.inputTokens} out=${criteriaTokens.outputTokens}` : "")
       );
     }
     const aggregate = aggregateCanvasResults(perCanvas, perCanvasResults);
@@ -6856,6 +7425,7 @@ function aggregateCanvasResults(perCanvas, results) {
     inputTokens += r.inputTokens ?? 0;
     outputTokens += r.outputTokens ?? 0;
   });
+  const criteriaSpent = perCanvas.flatMap((c) => c.criteriaTokens !== void 0 ? [c.criteriaTokens] : []);
   return {
     passed: perCanvas.every((c) => c.passed),
     finalScore: mean((r) => r.finalScore),
@@ -6864,6 +7434,12 @@ function aggregateCanvasResults(perCanvas, results) {
     ...critiques.length > 0 ? { critique: critiques.join("\n") } : {},
     inputTokens,
     outputTokens,
+    ...criteriaSpent.length > 0 ? {
+      criteriaTokens: {
+        inputTokens: criteriaSpent.reduce((sum, t) => sum + t.inputTokens, 0),
+        outputTokens: criteriaSpent.reduce((sum, t) => sum + t.outputTokens, 0)
+      }
+    } : {},
     canvases: [...perCanvas]
   };
 }
@@ -6876,9 +7452,17 @@ function summarizeVisualResult(result) {
     passed: c.passed,
     contentHeight: c.contentHeight,
     overflow: c.overflow,
+    inkRatio: c.inkRatio,
     judge: c.judge,
-    ...c.fit !== void 0 ? { fit: c.fit } : {}
+    ...c.fit !== void 0 ? { fit: c.fit } : {},
+    ...c.criteria !== void 0 ? { criteria: c.criteria } : {},
+    ...c.presentation !== void 0 ? { presentation: c.presentation } : {}
   }));
+  const blocks = result.canvases.map((c) => c.criteria).filter((b) => b !== void 0);
+  const idsWhere = (severity, verdict) => [
+    ...new Set(blocks.flatMap((b) => b.verdicts.filter((v) => v.severity === severity && v.verdict === verdict).map((v) => v.id)))
+  ];
+  const rollup = blocks.length > 0 ? { mustFailed: idsWhere("must", "fail"), shouldFailed: idsWhere("should", "fail"), mustNa: idsWhere("must", "n/a") } : void 0;
   const fitCanvas = result.canvases.find((c) => canvasFitPolicy(c.canvas).overflow === "fail" && c.contentHeight !== null);
   const fit = fitCanvas !== void 0 && fitCanvas.contentHeight !== null ? {
     canvas: fitCanvas.canvas,
@@ -6893,7 +7477,72 @@ function summarizeVisualResult(result) {
     canvases,
     ...fit !== void 0 ? { fit } : {},
     ...result.design !== void 0 ? { design: result.design } : {},
-    ...result.themeMode !== void 0 ? { themeMode: result.themeMode } : {}
+    ...result.themeMode !== void 0 ? { themeMode: result.themeMode } : {},
+    ...rollup !== void 0 ? { criteria: rollup } : {}
+  };
+}
+async function judgeStoredCapture(input, config, deps = {}) {
+  const judge = deps.judge ?? callMultimodalLLM;
+  const model = config.model ?? getDefaultVisualModel(config.provider);
+  const { canvas, viewport, png } = input;
+  const chrome = canvasChrome(canvas);
+  const ink = readInk(png, chrome, canvas);
+  const inkRatio = ink?.ratio ?? null;
+  const k = judgeCountFor(config, canvas);
+  const profileBlock = buildStylingProfileJudgeBlock(input.profile);
+  const criteriaContext = input.criteria !== void 0 ? { ...input.criteria.context, canvas } : void 0;
+  const criteriaSelected = input.criteria !== void 0 && criteriaContext !== void 0 ? selectCriteria(input.criteria.bank, criteriaContext) : void 0;
+  const criteriaBlock = input.criteria !== void 0 && criteriaSelected !== void 0 ? buildCriteriaJudgeBlock(input.criteria.bank, criteriaSelected, {
+    frame: { canvas, width: viewport.width, height: viewport.height },
+    ...input.sampleProps !== void 0 ? { propsJson: JSON.stringify(input.sampleProps) } : {}
+  }) : "";
+  const { scoring: answers, criteria: criteriaAnswer } = await judgeFrame(judge, config, model, png, input.originalPrompt, profileBlock, canvas, k, criteriaBlock);
+  const parsed = answers.filter((a) => a.kind === "ok");
+  if (parsed.length === 0) {
+    const first = answers.find((a) => a.kind === "unparsable");
+    return { kind: "unavailable", reason: first?.reason ?? "judge answer unparsable" };
+  }
+  const samples = parsed.map((a) => a.result.finalScore);
+  const median = medianOf(samples);
+  const result = parsed[samples.indexOf(median)].result;
+  const issues = [...result.issues];
+  let passed = median >= config.passThreshold;
+  const contentHeight = input.contentHeight;
+  const overflow = contentHeight !== null && contentHeight > viewport.height;
+  const policy = canvasFitPolicy(canvas);
+  if (overflow && contentHeight !== null && policy.overflow !== "none") {
+    issues.push(canvasOverflowIssue(canvas, viewport, contentHeight, policy.overflow));
+    if (policy.overflow === "fail") passed = false;
+  }
+  if (ink !== null && ink.lastInkRow === null) {
+    issues.push(canvasBlankIssue(canvas, viewport));
+    passed = false;
+  }
+  const criteria = input.criteria !== void 0 && criteriaContext !== void 0 && criteriaSelected !== void 0 ? resolveCriteriaBlock({
+    bank: input.criteria.bank,
+    context: criteriaContext,
+    selected: criteriaSelected,
+    answers: criteriaReads(criteriaAnswer),
+    measurements: { overflow, contentHeight, viewportHeight: viewport.height, inkRatio }
+  }) : void 0;
+  const criteriaTokens = criteriaCallTokens(criteriaAnswer);
+  return {
+    kind: "ok",
+    verdict: {
+      canvas,
+      viewport,
+      score: median,
+      passed,
+      issues,
+      judge: { k, rule: "median", samples, sigma: populationSigma(samples), notes: parsed.map((a) => a.result.critique ?? "") },
+      contentHeight,
+      overflow,
+      inkRatio,
+      ...criteria !== void 0 ? { criteria } : {},
+      inputTokens: parsed.reduce((sum, a) => sum + a.inputTokens, 0),
+      outputTokens: parsed.reduce((sum, a) => sum + a.outputTokens, 0),
+      ...criteriaTokens !== void 0 ? { criteriaTokens } : {}
+    }
   };
 }
 function salvageTruncatedVisualAnswer(text, passThreshold) {
@@ -6963,14 +7612,28 @@ function parseVisualResponse(text, passThreshold) {
     description: i.description || "",
     fix: i.fix || ""
   }));
+  const criteriaAnswers = parseCriteriaAnswers(raw.criteria);
   return {
     passed: finalScore >= passThreshold,
     finalScore,
     dimensions,
     issues,
-    critique: raw.critique
+    critique: raw.critique,
+    ...criteriaAnswers !== void 0 ? { criteriaAnswers } : {}
   };
 }
+function parseCriteriaAnswers(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const out = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const o = entry;
+    if (typeof o.id !== "string") continue;
+    if (o.verdict !== "pass" && o.verdict !== "fail" && o.verdict !== "n/a") continue;
+    out.push({ id: o.id, verdict: o.verdict, evidence: typeof o.evidence === "string" ? o.evidence : "" });
+  }
+  return out;
+}
 function getDefaultVisualModel(provider) {
   switch (provider) {
     case "claude":
@@ -7017,7 +7680,7 @@ async function runVisualFit(context, config, deps = {}) {
   const issues = [];
   const readings = [];
   for (const canvas of config.canvases) {
-    const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps);
+    const frame = await frameCanvas(bundledCode, context, html, canvas, config.canvasViewports, deps, config.hostPresentations);
     if (!frame.attempt.png) {
       return { status: "unavailable", reason: `${frame.attempt.reason ?? "no browser available"} at canvas ${canvas}` };
     }
@@ -7025,30 +7688,59 @@ async function runVisualFit(context, config, deps = {}) {
     const overflow = contentHeight !== null && contentHeight > frame.viewport.height;
     const verdict = fitVerdict(canvas, frame);
     if (verdict !== null) issues.push(toEvalIssue2(canvasScopedIssue(canvas, verdict)));
+    const overflowXIssue = overflowXVerdict(canvas, frame);
+    if (overflowXIssue !== null) issues.push(toEvalIssue2(canvasScopedIssue(canvas, overflowXIssue)));
+    const blank = blankVerdict(canvas, frame);
+    if (blank !== null) issues.push(toEvalIssue2(canvasScopedIssue(canvas, blank)));
+    const inkRatio = frame.ink?.ratio ?? null;
     readings.push({
       canvas,
       viewport: frame.viewport,
       contentHeight,
       overflow,
-      ...frame.declared ? { declared: true } : {}
+      inkRatio,
+      ...frame.declared ? { declared: true } : {},
+      ...frame.presentation !== void 0 ? { presentation: frame.presentation } : {}
     });
     console.log(
-      `[visual-fit] canvas=${canvas} ${frame.viewport.width}\xD7${frame.viewport.height} content=${contentHeight ?? "?"}px${overflow ? ` OVERFLOW (${frame.policy.overflow})` : ""} | no judge`
+      `[visual-fit] canvas=${canvas} ${frame.viewport.width}\xD7${frame.viewport.height} content=${contentHeight ?? "?"}px${overflow ? ` OVERFLOW (${frame.policy.overflow})` : ""} ink=${inkRatio ?? "?"}${blank !== null ? " BLANK" : ""} | no judge`
     );
   }
   return { status: "measured", issues, readings };
 }
-var JUDGE_SCOPE_CLASS, EXECUTABLE_PATH_LAUNCH_ARGS, DEFAULT_SCREENSHOT_VIEWPORT, CONTENT_HEIGHT_EXPRESSION, VISUAL_EVAL_PROMPT, VISUAL_JUDGE_MAX_OUTPUT_TOKENS, VISUAL_JUDGE_PROMPT_VERSION, VISUAL_JUDGE_PROMPT_DIGEST;
+var JUDGE_SCOPE_CLASS, JUDGE_PANEL_CLASS, JUDGE_INK_INSET_PX, JUDGE_GROUND_MARGIN_PX, JUDGE_GROUND_CLASS, JUDGE_INLINE_FRAME_CLASS, JUDGE_INLINE_FRAME_BORDER_PX, JUDGE_INLINE_FRAME_RADIUS_PX, JUDGE_INLINE_PAD_PX, JUDGE_INLINE_INK_INSET_PX, HOST_COLOUR_PATTERN, HOST_FRAME_BOUNDS, EXECUTABLE_PATH_LAUNCH_ARGS, DEFAULT_SCREENSHOT_VIEWPORT, CONTENT_HEIGHT_EXPRESSION, CARD_HEIGHT_EXPRESSION, OVERFLOW_X_ROUNDING_PX, CARD_OVERFLOW_X_EXPRESSION, VISUAL_EVAL_PROMPT, VISUAL_JUDGE_MAX_OUTPUT_TOKENS, VISUAL_JUDGE_PROMPT_VERSION, VISUAL_JUDGE_PROMPT_DIGEST;
 var init_visual_evaluator = __esm({
   "src/evaluation/visual-evaluator.ts"() {
     init_styling_profile();
+    init_select();
+    init_resolve();
+    init_ink_extent();
     init_design_identity();
     init_llm_router();
     init_design_mode();
     JUDGE_SCOPE_CLASS = "ggui-judge-scope";
+    JUDGE_PANEL_CLASS = "ggui-judge-panel";
+    JUDGE_INK_INSET_PX = EXPANDED_FRAME.insetPx + 24 + 1;
+    JUDGE_GROUND_MARGIN_PX = EXPANDED_FRAME.insetPx;
+    JUDGE_GROUND_CLASS = "ggui-judge-ground";
+    JUDGE_INLINE_FRAME_CLASS = "ggui-judge-inline-frame";
+    JUDGE_INLINE_FRAME_BORDER_PX = 1;
+    JUDGE_INLINE_FRAME_RADIUS_PX = 16;
+    JUDGE_INLINE_PAD_PX = JUDGE_GROUND_MARGIN_PX + JUDGE_INLINE_FRAME_BORDER_PX;
+    JUDGE_INLINE_INK_INSET_PX = JUDGE_INLINE_PAD_PX + JUDGE_INLINE_FRAME_RADIUS_PX;
+    HOST_COLOUR_PATTERN = /^#[0-9a-f]{6}$/;
+    HOST_FRAME_BOUNDS = {
+      ringWidthPx: { min: 0, max: 8 },
+      ringAlpha: { min: 0, max: 1 },
+      radiusPx: { min: 0, max: 64 },
+      minHeightPx: { min: 0, max: 2560 }
+    };
     EXECUTABLE_PATH_LAUNCH_ARGS = ["--no-sandbox", "--disable-dev-shm-usage"];
     DEFAULT_SCREENSHOT_VIEWPORT = { width: 1280, height: 800 };
     CONTENT_HEIGHT_EXPRESSION = "Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0)";
+    CARD_HEIGHT_EXPRESSION = cardHeightExpression(JUDGE_INLINE_PAD_PX);
+    OVERFLOW_X_ROUNDING_PX = 1;
+    CARD_OVERFLOW_X_EXPRESSION = "(() => { const r = document.getElementById('root'); return r ? Math.max(0, Math.ceil(r.scrollWidth - r.clientWidth)) : null; })()";
     VISUAL_EVAL_PROMPT = `You are a visual quality evaluator for ggui \u2014 a platform where AI agents generate React UI components on demand.
 
 ## Context
@@ -7103,7 +7795,7 @@ __export(get_primitives_ts_exports, {
 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";
+    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  type?: 'button' | 'submit' | 'reset';  // default 'button'; The HTML button type\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";
   }
 });
 
@@ -8628,6 +9320,81 @@ function runActionLabelDropped(input) {
     )
   );
 }
+var MIN_ECHO_CHARS = 12;
+function collectStrings(value, out) {
+  if (typeof value === "string") {
+    out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) collectStrings(v, out);
+  } else if (value !== null && typeof value === "object") {
+    for (const v of Object.values(value)) collectStrings(v, out);
+  }
+}
+function fixtureOnlyStrings(input) {
+  if (input.fixtureProps === void 0) return [];
+  const values = [];
+  collectStrings(input.fixtureProps, values);
+  const stated = `${input.originalPrompt}
+${input.contract === void 0 ? "" : JSON.stringify(input.contract)}`;
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const v of values) {
+    const t = v.trim();
+    if (t.length < MIN_ECHO_CHARS || !t.includes(" ") || seen.has(t)) continue;
+    seen.add(t);
+    if (stated.includes(t)) continue;
+    out.push(t);
+  }
+  return out;
+}
+function runFixtureDefaultEcho(input) {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const issues = [];
+  for (const value of fixtureOnlyStrings(input)) {
+    if (!src.includes(value)) continue;
+    issues.push(
+      mkIssue(
+        "universal.fixture_default_echo",
+        `A literal in the source equals a fixture value the request never stated: "${value.length > 60 ? `${value.slice(0, 57)}\u2026` : value}". The fixture is judging data; a visitor sees this copy whenever the agent leaves the prop out.`,
+        "Take that copy from the prop it renders and drop the literal \u2014 no default, fallback or placeholder that repeats a fixture value. A default may only carry text the request itself states.",
+        "warn"
+      )
+    );
+  }
+  return issues;
+}
+var FORM_OPEN_RX = /<form\b[^<>]*\bonSubmit\s*=[^<>]*>/g;
+var CONTROL_TAG_RX = /<(?:Button|button|input)\b[^<>]*>/g;
+var SUBMIT_TYPE_RX = /\btype\s*=\s*(?:["']submit["']|\{\s*["']submit["']\s*\})/;
+function submitForms(sourceCode) {
+  const out = [];
+  for (const m of sourceCode.matchAll(FORM_OPEN_RX)) {
+    const start = m.index ?? 0;
+    const end = sourceCode.indexOf("</form>", start + m[0].length);
+    out.push(end === -1 ? sourceCode.slice(start) : sourceCode.slice(start, end + "</form>".length));
+  }
+  return out;
+}
+function runFormSubmitControl(input) {
+  if (input.compiledCode === null) return [];
+  const issues = [];
+  for (const form of submitForms(input.sourceCode)) {
+    const controls = [...form.matchAll(CONTROL_TAG_RX)].map((m) => m[0]);
+    if (controls.length === 0) continue;
+    if (controls.some((tag) => SUBMIT_TYPE_RX.test(tag))) continue;
+    const named = controls.find((tag) => /<Button\b/.test(tag)) ?? controls[0];
+    issues.push(
+      mkIssue(
+        "universal.form_submit_control",
+        `A <form onSubmit> renders ${controls.length} control(s) and none submits it: the design Button defaults to type="button", so clicking ${named.length > 60 ? `${named.slice(0, 57)}\u2026` : named} does nothing \u2014 only Enter in a field submits.`,
+        'Give the control that submits this form type="submit" \u2014 a Button inside a form defaults to type="button" and never submits on click; keep type="button" on the others.',
+        "fail"
+      )
+    );
+  }
+  return issues;
+}
 var UNIVERSAL_CHECKS = [
   {
     id: "universal.icon_name_known",
@@ -8665,6 +9432,18 @@ var UNIVERSAL_CHECKS = [
     values: ALL_RENDER_VALUES,
     run: runTerminalActionUnguarded
   },
+  {
+    id: "universal.form_submit_control",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runFormSubmitControl
+  },
+  {
+    id: "universal.fixture_default_echo",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runFixtureDefaultEcho
+  },
   {
     id: "universal.accent_text_ink",
     axis: "render",
@@ -8788,7 +9567,7 @@ function runMapKeyIsId(input) {
       mkIssue(
         "render.map_key_is_id",
         `Array key uses index variable "${key}" \u2014 reorders and stream merges will break React reconciliation.`,
-        `Replace key={${key}} with key={item.id} (or item.symbol / whatever the entity id field is).`
+        `Replace key={${key}} with key={item.id} \u2014 or, when the items carry no id, with the field that names each one (item.label / item.symbol / item.name).`
       )
     );
   }
@@ -9795,7 +10574,9 @@ async function runCheck(input) {
     classification: harness.classification,
     designMode: harness.designMode,
     // ggui#1117: the canvas the harness was built for, when it has one — never a default.
-    ...harness.canvas !== void 0 ? { canvas: harness.canvas } : {}
+    ...harness.canvas !== void 0 ? { canvas: harness.canvas } : {},
+    // ggui#1285: the props the probe and judge rendered with — the fixture-echo check reads them.
+    ...input.fixtureProps !== void 0 ? { fixtureProps: input.fixtureProps } : {}
   };
   const axisRun = runGatedAxisChecks(check.axisChecks, axisInput);
   issues.push(...axisRun.issues);
@@ -10530,6 +11311,7 @@ function generateBoilerplate(_userPrompt, contract, shellType, screen, composedS
   }
   const actionTypeAliases = [];
   const actionHookCalls = [];
+  let hasOneShotAction = false;
   const actionsMap = contract?.actionSpec ?? {};
   for (const [key, entry] of Object.entries(actionsMap)) {
     const label = entry.label ?? key;
@@ -10550,7 +11332,20 @@ type ${typeName} = ${tsType};`
     const callSig = tsType === "void" ? "() => void \u2014 fire and forget" : `(data: ${tsType}) => void`;
     const toolHint = tool ? ` \u2192 nextStep: ${tool}` : "";
     const onceHint = " \u2014 if this is meant ONCE, disable its control after it fires";
-    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
+    if (entry.oneShot === true) {
+      hasOneShotAction = true;
+      actionHookCalls.push(
+        `  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint} \u2014 declared oneShot: the runtime drops a second dispatch`
+      );
+      actionHookCalls.push(
+        `  const ${key}Spent = useActionSpent('${key}'); // true once fired, also after a reload \u2014 render the control from THIS: disabled={${key}Spent} and a spent label`
+      );
+    } else {
+      actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
+    }
+    actionHookCalls.push(
+      `  const ${key}Pending = useActionPending('${key}'); // true from the tap until the agent's answer repaints the card \u2014 render EVERY control that dispatches '${key}' (a Button, a Select's onChange, an Input's Enter) from THIS: disabled={${key}Pending} aria-busy={${key}Pending}, and a working label on a button; no other control carries its aria-busy`
+    );
   }
   const streamChannels = contract?.streamSpec ?? {};
   const streamChannelEntries = Object.entries(streamChannels);
@@ -10648,6 +11443,8 @@ ${hookLines.join("\n")}
   const hasAnyWireFromWire = hasActions || hasStream || hasContext;
   const wireHooks = [];
   if (hasActions) wireHooks.push("useAction");
+  if (hasOneShotAction) wireHooks.push("useActionSpent");
+  if (hasActions) wireHooks.push("useActionPending");
   if (hasStream) wireHooks.push("useStream");
   if (hasContext) wireHooks.push("useGguiContext");
   const wireImport = hasAnyWireFromWire ? `import { ${wireHooks.join(", ")} } from '@ggui-ai/wire';
@@ -10895,21 +11692,17 @@ Rules:
 2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
 3. Default values come from the current request \u2014 so the component renders correctly standalone.
 4. Copy comes from the props. NEVER invent display text the contract does not carry \u2014 no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** \u2014 not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` \u2014 UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it. An action's control shows the contract's \`label\` VERBATIM \u2014 every character, including \`&\`, \`/\`, \`\u2013\` and quotes \u2014 never paraphrased, shortened or re-cased (\`"Confirm & Schedule"\` is not \`"Confirm Schedule"\`).
-5. Props interface must be typed and exported.`;
+5. Props interface must be typed and exported.
+6. Keys on a mapped list come from the item's own identity: \`key={item.id}\` when the contract gives an id; when the items carry none (KPI tiles \`{label, value}\`, forecast days \`{day, high}\`), key by the field that names each one \u2014 \`key={item.label}\`, \`key={day.day}\` \u2014 never by the map index: a reorder or a stream merge re-keys by index and re-mounts the wrong rows, and the self-check refuses an index key.`;
 var TERMINAL_ACTIONS = `## Actions the user means once
 
 A second press is a mistake only when it would make a SECOND THING HAPPEN IN THE WORLD \u2014 a second booking, a second charge, a second order, a second application sent. If pressing again would only write the SAME STATE AGAIN \u2014 saving, updating, renaming, setting a preference, toggling \u2014 nothing is duplicated and the control stays armed.
 
-Guard a control only where you have evidence, not a feeling about the verb: the request itself names a one-time commitment \u2014 "submit the application", "place the order", "confirm the booking".
+**The contract says which actions are once.** An action the contract declares \`oneShot: true\` (in the Contract block above) is guarded by the runtime \u2014 a second dispatch is dropped \u2014 and its spent state is DATA you read, never state you hold: render its control from \`const spent = useActionSpent('<name>')\`, \`disabled={spent}\`, and say so in the label or beside it ("Submitted", "Request sent") \u2014 a control that is disabled without explanation reads as broken. The hook's answer survives a reload and a second tab; \`useState(false)\` does not, so a reloaded card built on local state re-arms a control that already fired.
 
-**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked \u2014 save, edit, save again is ordinary. A control left armed is only what every interface does by default.
+**An action the contract does not declare \`oneShot\` stays armed.** Never guard one from a feeling about the verb \u2014 "confirm", "submit", "place" alone are not evidence. Guard it only where the request itself names a one-time commitment the contract failed to declare ("submit the application", "place the order"), and then with local state as the fallback: \`const [submitted, setSubmitted] = useState(false)\` set in the handler, \`disabled={submitted}\` with a label \u2014 knowing that this state lives with the component, not with the request, and starts fresh on a re-render with new props.
 
-When you do guard one:
-- Hold a small piece of state for it and set it in the handler: \`const [submitted, setSubmitted] = useState(false)\`.
-- \`disabled={submitted}\` on the control that fires it, and say so in the label or beside it ("Submitted", "Request sent") \u2014 a control that is disabled without explanation reads as broken.
-- A card re-rendered with new props starts fresh; the state above lives with the component, not with the request.
-
-Nothing in the wire DECLARES one-shot-ness yet, which is why the test is what a second press would DO \u2014 not how final the word sounds.`;
+**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked \u2014 save, edit, save again is ordinary. A control left armed is only what every interface does by default.`;
 var FRAME_SIZING = `## Sizing \u2014 the frame owns the height and the width
 
 The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
@@ -11065,7 +11858,7 @@ With raw elements YOU own the semantics \u2014 nothing is accessible by construc
 3. **Images have \`alt\`** (\`alt=""\` for decorative). Icon-only buttons need \`aria-label\`; decorative icons and emoji are \`aria-hidden="true"\`.
 4. **Live & streaming data** (a \`useStream\` \`.latest\` value, counters, clocks, flashing prices) sits in an \`aria-live="polite"\` (or \`role="status"\`) region so screen readers announce the change.
 5. **Headings nest**: one \`<h1>\` per screen, \`<h2>\` for sections, \`<h3>\` below \u2014 never skipped or inverted.
-6. **Busy state is announced**: \`<button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting\u2026' : 'Submit'}</button>\`.
+6. **Busy state is announced**: every control that dispatches an action (a button, a select whose change dispatches, an input that sends on Enter) stays pending from \`useActionPending('<action>')\` until the agent's answer repaints the card \u2014 \`<button disabled={sendPending} aria-busy={sendPending}>{sendPending ? 'Sending\u2026' : 'Send'}</button>\`. Only a control that dispatches the action carries its busy look; while it is pending, other controls of the same record may be disabled \u2014 nothing more (controls of other records, creation controls and the action's own cancel stay enabled); busy state the card owns (\`isLoading\`) the same way.
 7. **Stateful controls announce state**: \`role="checkbox"\` + \`aria-checked\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check mark) is never the only carrier of state.
 8. **Focus is visible** \u2014 style \`:focus-visible\` with a token color; never \`outline: none\` without a replacement.`;
 var FREE_QUALITY_CHECKLIST = `## Quality Checklist (verify before returning)
@@ -11609,7 +12402,7 @@ The design-system primitives are accessible by construction \u2014 they emit the
 3. **Icons are decorative by default** \u2014 \`<Icon name="check" />\` is hidden from screen readers, which is correct for an icon sitting next to text. Add \`aria-label\` ONLY for a standalone, meaning-bearing icon with no adjacent text. Icon-only \`Button\`s still need \`aria-label\` on the **Button** itself.
 4. **Live & streaming data** \u2014 wrap any region whose content updates on its own (a \`useStream\` \`.latest\` value, a live clock, an "N new" counter, a flashing price) in an element with \`aria-live="polite"\` so screen readers announce the change.
 5. **Headings nest** \u2014 one \`<Heading level={1}>\` per screen, \`level={2}\` for sections, \`level={3}\` for subsections. Never skip or invert levels.
-6. **Buttons** \u2014 descriptive text content; icon-only buttons need \`aria-label\`. Announce busy state: \`<Button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting\u2026' : 'Submit'}</Button>\`.
+6. **Buttons** \u2014 descriptive text content; icon-only buttons need \`aria-label\`. Announce busy state. EVERY control that dispatches an action \u2014 a Button, a Select whose change dispatches, an Input that sends on Enter \u2014 stays pending from that action's \`useActionPending\` until the agent's answer repaints the card: with \`const sendPending = useActionPending('send');\`, write \`<Button disabled={sendPending} aria-busy={sendPending} onClick={() => send({ text })}>{sendPending ? 'Sending\u2026' : 'Send'}</Button>\`, and give a dispatching Select or Input the same \`disabled={sendPending} aria-busy={sendPending}\`. Only a control that dispatches the action carries its \`aria-busy\` and a working label. While it is pending, other controls of the SAME record may be \`disabled\` \u2014 nothing more; controls of other records, creation controls and the action's own cancel stay enabled. Busy state the card owns (a local \`isLoading\`) is announced the same way.
 7. **Stateful controls announce their state.** Toggleable / selectable / expandable things use the primitive that carries the semantics (\`Checkbox\`, \`Toggle\`, \`Tabs\`, \`Accordion\`) \u2014 never a styled \`Box\`/\`Icon\` that only *looks* checked. When you hand-roll one with \`as={Clickable}\`, \`Clickable\` adds button + keyboard semantics but NOT state \u2014 add it yourself: \`role="checkbox"\` + \`aria-checked={done}\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check icon) must never be the only carrier of state.
 
 ## Design System Usage (CRITICAL)
@@ -11959,9 +12752,10 @@ var APPLY_CHANGES_HASHLINE_TOOL_FLAT = {
     required: ["changes", "commit_message"]
   }
 };
+var ICON_LIST_NO_MATCH_GUIDANCE = "This list is complete and constant \u2014 calling again returns exactly it. If the name you wanted is not here, pick the nearest listed name (or a neutral one such as `circle`) and continue with apply_changes; never call this tool twice.";
 var GET_ICONS_TOOL = {
   name: "get_available_icons",
-  description: 'List every Lucide icon name the <Icon name="..."> component renders (kebab-case). A name outside this list renders nothing \u2014 check before choosing.',
+  description: 'List every Lucide icon name the <Icon name="..."> component renders (kebab-case). A name outside this list renders nothing \u2014 check before choosing. ' + ICON_LIST_NO_MATCH_GUIDANCE,
   parameters: { type: "object", properties: {} }
 };
 var GET_COMPONENTS_INFO_TOOL = {
@@ -12021,6 +12815,10 @@ var REWRITE_TOOL = {
   }
 };
 
+// src/harness-tool-names.ts
+var HARNESS_CODING_TOOLS = [APPLY_CHANGES_TOOL];
+var HARNESS_SCOPED_TOOLS = [APPLY_CHANGES_TOOL_SCOPED];
+
 // src/create-harness.ts
 init_patch();
 function stableStringify(value) {
@@ -12147,8 +12945,8 @@ function createHarness(input) {
   const baseWhat = {
     boilerplate,
     fragments: whatFragments,
-    codingTools: [APPLY_CHANGES_TOOL],
-    scopedTools: [APPLY_CHANGES_TOOL_SCOPED],
+    codingTools: [...HARNESS_CODING_TOOLS],
+    scopedTools: [...HARNESS_SCOPED_TOOLS],
     applyPatch: defaultPatchFn,
     // Registered gadget catalog — drives the system prompt's gadget
     // table + the boilerplate's direct-import emission. Omitted when no
@@ -12610,7 +13408,7 @@ tighter on display sizes).
 init_validation();
 
 // src/tools/get-wire.ts
-var WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate \u2014 use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 \u2014 agentCapabilities.tools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget \u2014 no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse \u2014 advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced \u2014 the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** \u2014 wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit \u2014 it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` \u2014 this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload \u2014 matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded \u2014 auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly \u2014 it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider \u2014 the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` \u2014 `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` \u2014 same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases \u2014 no call-site break.\n\nThe contract's `agentCapabilities.tools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe \u2014 `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for the runtime's two dispatch- suppression invariants \u2014 the task-scoped duplicate backstop (`reason: 'duplicate-dispatch'`, fired by `useAction`) and the render-lifetime one-shot guard (`reason: 'one-shot-spent'`, fired by the config's own `dispatch` when a declared `oneShot` action is gestured a second time, ggui#1108). Both fire ALONGSIDE the always-on `console.warn`; neither reaches the agent.  Reachability constraint: the first-party renderers do NOT set this field \u2014 `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` (or passes `onDispatchSuppressed` to `buildWireConfig`). On every first-party render path the `console.warn` is the sole suppression signal \u2014 which is what the `oneShot` contract requires as its minimum trace. |\n";
+var WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate \u2014 use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 \u2014 agentCapabilities.tools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget \u2014 no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse \u2014 advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced \u2014 the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** \u2014 wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit \u2014 it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useActionSpent\n\nWhether the card's `oneShot` action `actionName` is already spent, so a\ncomponent can paint its control as submitted on the first paint, with no\npress needed to find out.\n\n`true` iff the contract declares `actionName` `oneShot` and the card already\nfired it, either in this render or before a reload (the record the host\nre-serves). It is reactive, flipping to `true` when this card's own dispatch\ncommits. It returns data only: how a spent control looks (disabled,\n\"Submitted\", hidden) is the component's choice. Outside a runtime that\nprovides spent state, it is `false` and the dispatch guard still holds.\n\n**Signature:** `useActionSpent(actionName: string): boolean`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | actionName |\n\n**Returns:** `boolean`\n\n**Example:**\n```tsx\nconst confirm = useAction<ActionConfirmPayload>('confirm');\nconst spent = useActionSpent('confirm');\n\n// In JSX \u2014 the control paints spent on the first paint after a reload, with no press:\n<Button variant=\"primary\" disabled={spent} onClick={() => confirm({ bookingId })}>\n  {spent ? 'Confirmed' : 'Confirm booking'}\n</Button>\n```\n\n\n### useActionPending\n\nWhether this card's action `actionName` was dispatched and is still waiting\nfor the agent's answer, so the control can show it is working (disabled,\n`aria-busy`, \"Sending\u2026\") instead of looking untouched while the agent\nreacts.\n\n`true` from the committed dispatch until the session's next frame lands, or\nthe bound elapses. It is reactive. It returns data only: how a pending\ncontrol looks is the component's choice. Outside a runtime that provides\npending state, it is `false`.\n\n**Signature:** `useActionPending(actionName: string): boolean`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | actionName |\n\n**Returns:** `boolean`\n\n**Example:**\n```tsx\nconst send = useAction<ActionSendPayload>('send');\nconst sending = useActionPending('send');\n\n// In JSX \u2014 the control shows it is working until the agent's answer repaints the card:\n<Button variant=\"primary\" disabled={sending} aria-busy={sending} onClick={() => send({ text })}>\n  {sending ? 'Sending\u2026' : 'Send'}\n</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` \u2014 this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload \u2014 matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded \u2014 auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly \u2014 it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider \u2014 the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` \u2014 `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` \u2014 same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases \u2014 no call-site break.\n\nThe contract's `agentCapabilities.tools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe \u2014 `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for the runtime's two dispatch- suppression invariants \u2014 the task-scoped duplicate backstop (`reason: 'duplicate-dispatch'`, fired by `useAction`) and the render-lifetime one-shot guard (`reason: 'one-shot-spent'`, fired by the config's own `dispatch` when a declared `oneShot` action is gestured a second time, ggui#1108). Both fire ALONGSIDE the always-on `console.warn`; neither reaches the agent.  Reachability constraint: the first-party renderers do NOT set this field \u2014 `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` (or passes `onDispatchSuppressed` to `buildWireConfig`). On every first-party render path the `console.warn` is the sole suppression signal \u2014 which is what the `oneShot` contract requires as its minimum trace. |\n";
 
 // src/harness/pitfalls.ts
 var PITFALLS = [
@@ -14664,6 +15462,9 @@ init_check();
 init_check();
 init_check();
 
+// src/adapters/tools.ts
+init_sample_props();
+
 // src/coding-agent/self-check.ts
 init_check();
 init_check();
@@ -14742,7 +15543,8 @@ async function autoCommit(workspace, commitMeta, message, contract, contextPolic
     originalPrompt: axis.originalPrompt,
     classification: axis.classification,
     designMode,
-    ...axis.canvas !== void 0 ? { canvas: axis.canvas } : {}
+    ...axis.canvas !== void 0 ? { canvas: axis.canvas } : {},
+    ...axis.fixtureProps !== void 0 ? { fixtureProps: axis.fixtureProps } : {}
   } : void 0;
   if (axisFacts !== void 0 && !buildSuccess) traceAxisChecksSkipped(axisFacts, "build failed \u2014 no check ran");
   const axisRun = axis !== void 0 && axisFacts !== void 0 && buildSuccess ? runGatedAxisChecks(axis.checks, { ...axisFacts, compiledCode }) : void 0;
@@ -15374,7 +16176,9 @@ ${closingInstruction}`;
     }
     console.log(`[simple] turn ${turnsUsed}: get_available_icons`);
     let iconResult = `Available Lucide icon names (use with <Icon name="...">):
-${iconNamesCache}`;
+${iconNamesCache}
+
+${ICON_LIST_NO_MATCH_GUIDANCE}`;
     let iconRepeats = 0;
     if (ctx.dupeBreak) {
       iconRepeats = recordToolExchange(ctx.dupeBreak, call.name, call.input, iconResult);
@@ -15444,7 +16248,8 @@ ${iconNamesCache}`;
       checks: harness.check.axisChecks,
       classification: harness.classification,
       originalPrompt: ctx.originalPrompt,
-      ...harness.canvas !== void 0 ? { canvas: harness.canvas } : {}
+      ...harness.canvas !== void 0 ? { canvas: harness.canvas } : {},
+      ...ctx.fixtureProps !== void 0 ? { fixtureProps: ctx.fixtureProps } : {}
     }
   );
   const toolMs = Date.now() - toolStart;
@@ -15668,6 +16473,33 @@ Repeated error: ${errText}
   };
 }
 
+// src/evaluation/criteria/context.ts
+var PRIMARY_500 = /--ggui-color-primary-500:\s*(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6})\s*;/;
+var ACHROMATIC_SPREAD = 0.08;
+function chromaOfCssTokens(cssTokens) {
+  const m = cssTokens?.match(PRIMARY_500);
+  if (!m) return "unknown";
+  const hex = m[1].slice(1);
+  const full = hex.length === 3 ? hex.split("").map((c) => c + c).join("") : hex;
+  const channels = [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16));
+  const spread = (Math.max(...channels) - Math.min(...channels)) / 255;
+  return spread < ACHROMATIC_SPREAD ? "achromatic" : "chromatic";
+}
+function criteriaContextFor(src) {
+  const v = src.classification.vector;
+  const preset = src.profile?.aesthetic?.id;
+  return {
+    hasActions: Object.keys(src.contract?.actionSpec ?? {}).length > 0,
+    riskTier: src.classification.riskTier,
+    axes: { render: v.render, state: v.state, writes: v.writes, fetch: v.fetch, layout: v.layout },
+    chroma: chromaOfCssTokens(src.cssTokens),
+    profilePresent: src.profile !== void 0,
+    shell: src.shell,
+    ...src.kind !== void 0 ? { kind: src.kind } : {},
+    ...preset !== void 0 ? { preset } : {}
+  };
+}
+
 // src/harness/coding/run-eval-round.ts
 init_types_public();
 
@@ -16037,7 +16869,21 @@ async function runEvalRound(ctx, input) {
       originalPrompt: userPrompt,
       profile: harness.profile,
       // The caller's theme, when named — the round paints what the app paints.
-      ...visualEvaluation?.cssTokens !== void 0 ? { cssTokens: visualEvaluation.cssTokens } : {}
+      ...visualEvaluation?.cssTokens !== void 0 ? { cssTokens: visualEvaluation.cssTokens } : {},
+      // ggui#1436 — the criteria bank and the card's context; the judge selects per canvas, report-only.
+      ...visualEvaluation?.criteriaBank !== void 0 ? {
+        criteria: {
+          bank: visualEvaluation.criteriaBank,
+          context: criteriaContextFor({
+            classification,
+            contract,
+            cssTokens: visualEvaluation.cssTokens,
+            profile: harness.profile,
+            shell: ctx.shellType ?? "unknown",
+            ...visualEvaluation.criteriaKind !== void 0 ? { kind: visualEvaluation.criteriaKind } : {}
+          })
+        }
+      } : {}
     };
     const visualFrame = {
       // The in-loop visual round renders the same sample the runtime probe
@@ -16589,6 +17435,8 @@ function createGenerateTaskRunner(input) {
           originalPrompt: params.userPrompt,
           commitMeta: session.commitMeta,
           originalProps: session.originalProps,
+          // ggui#1285: the fixture the probe and judge render with, for the echo check at auto-commit.
+          ...params.fixtureProps !== void 0 ? { fixtureProps: params.fixtureProps } : {},
           costTracker: session.costTracker,
           // Thread the dispatch-resolved policy so experimental
           // profiles take effect on both preflight and tier-0 retry
@@ -16673,6 +17521,7 @@ function createGenerateTaskRunner(input) {
             evaluationAgent: session.agents.evaluation,
             visualEvalAgent: session.agents.visualEval,
             visualEvaluation: params.visualEvaluation,
+            shellType: params.shellType,
             visualThreshold: session.visualThreshold,
             qualityMode: session.qualityMode,
             maxEvalRounds: session.maxEvalRounds,
@@ -17014,6 +17863,12 @@ async function dispatchGeneration(params) {
     routeOverride: params.routeOverride,
     onRetry: params.onRetry
   } : void 0;
+  const visualEvalAgent = params.visualEvalAgent ? {
+    provider: params.visualEvalAgent.provider,
+    model: params.visualEvalAgent.model,
+    ...params.visualEvalAgent.apiKey !== void 0 ? { routeOverride: { apiKey: params.visualEvalAgent.apiKey } } : {},
+    onRetry: params.onRetry
+  } : void 0;
   const effectiveContract = params.contract;
   const sessionParams = {
     userPrompt: params.originalPrompt ?? params.userPrompt,
@@ -17126,7 +17981,8 @@ async function dispatchGeneration(params) {
   }
   const agents = resolveSessionAgents({
     codingAgent,
-    evaluationAgent
+    evaluationAgent,
+    ...visualEvalAgent !== void 0 ? { visualEvalAgent } : {}
   });
   const { resolveRunPolicyForProfile: resolveRunPolicyForProfile2 } = await Promise.resolve().then(() => (init_policy2(), policy_exports));
   const resolvedPolicy = resolveRunPolicyForProfile2(process.env.GGUI_POLICY_PROFILE, harness, {