@gradeui/ui 0.9.0 → 1.0.0

package/components/ui/three-scene.md

@@ -0,0 +1,226 @@
+---
+name: ThreeScene
+import: "@gradeui/ui"
+props:
+  - preset?: "space" | "plasma" | "voronoi" | "synthwave" — shader preset id from the registry
+  - fragmentShader?: string — user-authored GLSL body; takes precedence over preset
+  - onShaderError?: (error: ShaderCompileError) => void — fires on compile failure; scene falls back to `preset="space"`
+  - postPreset?: "none" | "vhs" | "cinematic" | "synthwave" | "crt" (default "vhs") — post-processing pass
+  - palette?: Partial<{ primary; secondary; accent; background }> — any CSS-legal colour string per slot. Re-tints automatically when the theme changes. Unset slots fall back to defaults.
+  - createScene?: (ctx) => SceneHandle — custom full scene factory; takes precedence over preset AND fragmentShader
+  - controls?: boolean (default false) — play/pause overlay
+  - autoPlay?: boolean (default true) — respects reduced-motion
+  - pauseOffscreen?: boolean (default true) — big win for WebGL battery life
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
+  - maxDpr?: number (default min(devicePixelRatio, 2)) — lower for thumbnails / low-end devices
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg")
+when_to_use: WebGL primitive for shader backgrounds, generative visuals, and bespoke three.js scenes. Three authoring paths, in order of preference — (1) pick a `preset` id; (2) if nothing in the registry fits, write a `fragmentShader` against the fixed uniform contract; (3) only as a last resort, pass a full `createScene` factory. For looping video, use VideoPlayer; for interactive animations, use RivePlayer.
+composes_with: [MediaSurface (internal), foreground content stacked above with `position: absolute/relative z-10`]
+aliases: [three, threejs, webgl, shader, scene, 3d, generative, hero background, fragment shader, glsl]
+notes: |
+  Depends on `three` and `postprocessing` (bundled into @gradeui/ui). Safari caps concurrent WebGL contexts at ~8 — for preset galleries, prefer ShaderPresetPreview with `live="hover"`.
+
+  ## Path 1 — `preset` (pick one, fastest, highest quality)
+
+  Valid `preset` ids (complete list — do NOT invent any others):
+    - "space"     — Hyperspace starfield, streaking stars. Default post: "vhs".
+    - "plasma"    — soft rolling colour clouds, ambient/abstract. Default post: "synthwave".
+    - "voronoi"   — jittered cellular grid with glowing edges. Default post: "crt".
+    - "synthwave" — retro perspective grid + banded sun. Default post: "synthwave".
+
+  Any other preset id renders an empty surface. If these don't cover the ask, DO NOT invent a name — jump to Path 2 (`fragmentShader`) and write the shader directly.
+
+  Valid `postPreset` ids (complete list): "none" | "vhs" | "cinematic" | "synthwave" | "crt".
+
+  Re-skin any preset with `palette={{ primary, secondary, accent, background }}` to shift its mood. Preset + palette + postPreset is usually enough to hit ocean / lava / neon / forest vibes.
+
+  ### Palette values — what counts as a valid colour
+
+  Each slot accepts ANY CSS-legal colour expression. Values are normalised via a browser probe before being handed to three.js, so all of these work:
+
+    - CSS custom properties wrapped in a colour function — `"oklch(var(--primary))"`, `"oklch(var(--foreground))"`. **This is the recommended pattern for gradeui consumers.** gradeui tokens (like shadcn) are bare channel triplets (`--primary: 0.610 0.128 20`), so `var(--primary)` alone is NOT a valid CSS colour and will render black. ALWAYS wrap as `oklch(var(--token))`. The shader re-tints automatically on theme change.
+    - Hex — `"#ff5fb9"`, `"#f5b"`.
+    - `rgb()` / `rgba()` — `"rgb(255 95 185)"`, `"rgb(255, 95, 185)"`.
+    - `hsl()` / `hsla()` — `"hsl(330 100% 69%)"`.
+    - `oklch()` / `lab()` / `lch()` / `oklab()` — `"oklch(0.74 0.18 350)"`. Full CSS Color 4.
+    - Named colours — `"tomato"`, `"dodgerblue"`, `"black"`.
+
+  INVALID — these DO NOT work and will silently fall back to the default palette slot:
+
+    - Literal bare triplets passed as a palette string — `"0.4 0.1 0.9"` is NOT a colour; wrap it as `"oklch(0.4 0.1 0.9)"`. (The var()-based auto-wrap above only kicks in when the palette value is `var(--token)` and the token itself is a triplet — it can't rescue a raw triplet passed directly.)
+    - three.js hex numbers — `0xff5fb9` (number). Use the string `"#ff5fb9"`.
+    - Colour arrays — `[0.4, 0.1, 0.9]`. Not accepted.
+
+  Theme reactivity: when the host document's root class or `data-theme` attribute changes, the scene re-reads the palette and pushes new uniforms into the running shader WITHOUT tearing down the WebGL context. Dark/light swaps are essentially free.
+
+  ### gradeui token semantics — pick the RIGHT tokens, and ALWAYS wrap in `oklch()`
+
+  gradeui tokens are bare OKLCH channel triplets (`--primary: 0.610 0.128 20`, no `oklch()` wrapper) — same convention as shadcn. That means **every `var(--token)` passed to the palette MUST be wrapped in `oklch(...)` at the call site**: `"oklch(var(--primary))"`, not `"var(--primary)"`. Unwrapped values resolve to invalid CSS and render black.
+
+  Token role cheat-sheet when picking which slot maps to what:
+
+    - `--primary` — brand hue 1. USE for `palette.primary` (and often `palette.accent` too).
+    - `--accent` — brand hue 2. USE for `palette.secondary` — gradeui's `--secondary` is a NEUTRAL surface (identical to `--muted`) and will render as a flat near-white wash in the shader.
+    - `--foreground` — inverted neutral (dark in light mode, light in dark mode). USE for `palette.background` — the raw `--background` token is the page background (near-white in light mode) and will wash the shader out.
+
+  Idiomatic theme-reactive palette for gradeui consumers (copy verbatim):
+
+    ```jsx
+    palette={{
+      primary: "oklch(var(--primary))",
+      secondary: "oklch(var(--accent))",   // NOT var(--secondary) — that's a neutral
+      accent: "oklch(var(--primary))",
+      background: "oklch(var(--foreground))", // NOT var(--background) — that's the page bg
+    }}
+    ```
+
+  ## Path 2 — `fragmentShader` (custom GLSL)
+
+  Pass a GLSL fragment shader body as a string. Runs on a fullscreen quad. Header is AUTO-INJECTED — write `void main()` only and use the uniforms below as given. Do NOT redeclare them, do NOT add `#version` directives, do NOT `import * as THREE` — you are writing shader text, not JavaScript.
+
+  Auto-injected header (available to every fragmentShader):
+
+    ```glsl
+    precision highp float;
+    varying vec2 vUv;               // [0,1] across the quad
+    uniform float uTime;            // elapsed seconds
+    uniform vec2  uResolution;      // pixel size of the canvas
+    uniform vec2  uMouse;           // [0,1], y-up (GLSL convention); defaults to (0.5, 0.5)
+    uniform vec3  uPrimary;         // palette.primary  (theme-driven)
+    uniform vec3  uSecondary;       // palette.secondary
+    uniform vec3  uAccent;          // palette.accent
+    uniform vec3  uBackground;      // palette.background
+    ```
+
+  Minimal working skeleton:
+
+    ```glsl
+    void main() {
+      vec2 uv = vUv - 0.5;
+      float t = uTime;
+      vec3 col = mix(uBackground, uPrimary, 0.5 + 0.5 * sin(length(uv) * 10.0 - t));
+      gl_FragColor = vec4(col, 1.0);
+    }
+    ```
+
+  GLSL syntax rules:
+    - Use `gl_FragColor` for output (NOT `out vec4`).
+    - Use `varying` for inputs (NOT `in`).
+    - Use `texture2D` if sampling textures (not `texture`). In practice you won't need textures — stick to procedural colour.
+    - Hard cap: keep shaders under ~200 lines. Long raymarchers are usually both slow and wrong.
+
+  Error handling: if the GLSL fails to compile, the component fires `onShaderError` with the GL info log and renders `preset="space"` as a fallback. Never returns a blank surface.
+
+  ## Path 3 — `createScene` (escape hatch)
+
+  A full `SceneFactory` that returns `{ scene, camera, update, resize, setPalette, dispose }`. Only reach for this if you need real geometry, multiple passes, or a custom camera. 95% of "make me a shader" asks are better served by Path 2.
+
+  ## Fullscreen backgrounds
+
+  Surface defaults to `aspect="video"` (16:9). For a full-bleed hero background using `className="absolute inset-0"`, ALWAYS also pass `aspect="auto"` — otherwise the aspect-ratio constraint fights the absolute positioning and you get letterboxing.
+---
+
+```jsx
+// Path 1 — named preset (fastest path)
+<ThreeScene preset="plasma" postPreset="synthwave" aspect="wide" />
+```
+
+```jsx
+// Path 1 — preset + palette re-skin to hit a custom mood
+<ThreeScene
+  preset="space"
+  postPreset="cinematic"
+  palette={{
+    primary: "#00e0ff",
+    secondary: "#1a7eff",
+    accent: "#ffffff",
+    background: "#000512",
+  }}
+/>
+```
+
+```jsx
+// Path 1 — palette from the active theme via CSS variables.
+// Recolors automatically when the theme switches.
+//
+// gradeui tokens are bare OKLCH triplets (shadcn-style), so EVERY var() MUST
+// be wrapped in oklch(...) at the call site — unwrapped `var(--primary)` is
+// invalid CSS and will render black.
+//
+// Slot mapping: `--secondary` is a neutral surface in gradeui (not a brand hue)
+// and `--background` is the page bg (near-white in light mode). Map secondary
+// to `--accent` and background to `--foreground` for a punchy, theme-reactive
+// palette that inverts cleanly on dark-mode toggle.
+<ThreeScene
+  preset="plasma"
+  palette={{
+    primary: "oklch(var(--primary))",
+    secondary: "oklch(var(--accent))",
+    accent: "oklch(var(--primary))",
+    background: "oklch(var(--foreground))",
+  }}
+/>
+```
+
+```jsx
+// Path 1 — CSS Color 4 (oklch) works too.
+<ThreeScene
+  preset="voronoi"
+  palette={{
+    primary: "oklch(0.74 0.18 350)",
+    secondary: "oklch(0.62 0.22 260)",
+    accent: "oklch(0.92 0.11 95)",
+    background: "oklch(0.1 0.04 280)",
+  }}
+/>
+```
+
+```jsx
+// Path 2 — custom fragment shader. Header is auto-injected; just write main().
+// This one: concentric rings in the theme's primary colour, breathing on uTime.
+<ThreeScene
+  fragmentShader={`
+    void main() {
+      vec2 uv = vUv - 0.5;
+      uv.x *= uResolution.x / uResolution.y;
+      float d = length(uv);
+      float rings = 0.5 + 0.5 * sin(d * 30.0 - uTime * 2.0);
+      vec3 col = mix(uBackground, uPrimary, rings);
+      col = mix(col, uAccent, smoothstep(0.45, 0.5, d) * 0.4);
+      gl_FragColor = vec4(col, 1.0);
+    }
+  `}
+  postPreset="vhs"
+  aspect="square"
+/>
+```
+
+```jsx
+// Path 2 — interactive: follow the pointer with uMouse.
+<ThreeScene
+  fragmentShader={`
+    void main() {
+      vec2 uv = vUv;
+      float d = distance(uv, uMouse);
+      float glow = smoothstep(0.3, 0.0, d);
+      vec3 col = mix(uBackground, uPrimary, glow);
+      gl_FragColor = vec4(col, 1.0);
+    }
+  `}
+/>
+```
+
+```jsx
+// Fullscreen hero — shader behind, content on top.
+// `aspect="auto"` is required for inset-0 to fill the parent.
+<div className="relative h-screen w-full overflow-hidden">
+  <ThreeScene
+    preset="synthwave"
+    aspect="auto"
+    className="absolute inset-0"
+  />
+  <div className="relative z-10 py-16 px-6 text-center text-white">
+    <h1 className="text-5xl font-bold">Build at the speed of thought</h1>
+  </div>
+</div>
+```

package/components/ui/toast.md

@@ -0,0 +1,38 @@
+---
+name: Toaster
+import: "@gradeui/ui"
+aliases: [toast, toaster, sonner, notification, snackbar, alert toast, transient alert, transient banner, banner notification, toastandroid]
+props:
+  - Toaster: position? "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" (default "bottom-right")
+  - Toaster: theme? "light" | "dark" | "system"
+  - Toaster: richColors?: boolean — colored variants for success/error/warning/info
+  - Toaster: expand?: boolean — keep multiple toasts visually separated rather than stacked
+  - Toaster: visibleToasts?: number — max concurrent toasts on screen (default 3)
+  - Toaster: duration?: number — default ms before auto-dismiss
+when_to_use: Transient, non-blocking feedback that confirms or warns about an action — "Saved", "Failed to upload", "Copied to clipboard", "Invitation sent". For permanent inline messages reach for Callout. For confirmations that block until acknowledged use Dialog. Mount <Toaster /> ONCE at the root of the app; everywhere else, call the `toast` helper.
+composes_with: [App root layout (single <Toaster /> mount), Form submit handlers (success/error toasts), Async actions]
+notes: Backed by Sonner under the hood — `import { toast } from "sonner"` to fire toasts from anywhere.
+---
+
+```jsx
+// At the app root, mount once.
+<Toaster richColors position="bottom-right" />
+```
+
+```jsx
+// Anywhere else, fire via the helper.
+import { toast } from "sonner";
+
+<Button
+  onClick={async () => {
+    try {
+      await saveProfile();
+      toast.success("Saved");
+    } catch (err) {
+      toast.error("Couldn't save", { description: err.message });
+    }
+  }}
+>
+  Save changes
+</Button>
+```

package/components/ui/toggle-group.md

@@ -0,0 +1,43 @@
+---
+name: ToggleGroup
+import: "@gradeui/ui"
+subcomponents: [ToggleGroupItem]
+variants: [default, outline]
+sizes: [sm, md, lg]
+props:
+  - ToggleGroup: type: "single" | "multiple" — single picks one, multiple picks any number
+  - ToggleGroup: value?: string | string[] — controlled; matches `type` (string for single, string[] for multiple)
+  - ToggleGroup: defaultValue?: string | string[] — uncontrolled initial
+  - ToggleGroup: onValueChange?: (value: string | string[]) => void
+  - ToggleGroup: size? (sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights
+  - ToggleGroup: variant? (default | outline)
+  - ToggleGroupItem: value: string — what the group reports when this item is pressed
+  - ToggleGroupItem: tooltip?: ReactNode — when set, wraps the item in a Tooltip; required for icon-only items where the visible chrome doesn't carry a label
+  - ToggleGroupItem: tooltipSide? ("top" | "right" | "bottom" | "left", default "top") — side the tooltip renders on
+  - ToggleGroupItem: tooltipDelay?: number — per-item delay override; falls back to the upstream TooltipProvider's delayDuration
+when_to_use: A small set of mutually-exclusive (`type="single"`) or independent (`type="multiple"`) binary options that live side-by-side as a segmented control — viewport size picker (Mobile/Tablet/Desktop), text alignment, view density. Reads identically to a TabsList of the same size; reach for ToggleGroup when each option emits a value (like a form input) rather than swapping panels. Use Tabs for panel switching, Toggle for a single on/off.
+composes_with: [Card (header controls), Row, AppShellHeader chrome, settings panels]
+aliases: [toggle group, segmented control, segmented buttons, button group, pill group, view selector, segmented picker, segmentedcontrolios, segmented buttons group, rn segmented control]
+---
+
+```jsx
+// Single-select segmented control — viewport size picker with
+// icon-only items + tooltips. The `tooltip` prop also fills in
+// `aria-label` for screen readers, so consumers don't have to
+// duplicate the label.
+<ToggleGroup type="single" defaultValue="desktop" size="sm">
+  <ToggleGroupItem value="mobile" tooltip="Mobile — 390px"><Smartphone /></ToggleGroupItem>
+  <ToggleGroupItem value="tablet" tooltip="Tablet — 768px"><Tablet /></ToggleGroupItem>
+  <ToggleGroupItem value="desktop" tooltip="Desktop — 1024px"><Monitor /></ToggleGroupItem>
+  <ToggleGroupItem value="responsive" tooltip="Responsive — fills the column"><MoveHorizontal /></ToggleGroupItem>
+</ToggleGroup>
+```
+
+```jsx
+// Multi-select — text formatting toolbar.
+<ToggleGroup type="multiple">
+  <ToggleGroupItem value="bold" aria-label="Bold"><Bold /></ToggleGroupItem>
+  <ToggleGroupItem value="italic" aria-label="Italic"><Italic /></ToggleGroupItem>
+  <ToggleGroupItem value="underline" aria-label="Underline"><Underline /></ToggleGroupItem>
+</ToggleGroup>
+```

package/components/ui/toggle.md

@@ -0,0 +1,36 @@
+---
+name: Toggle
+import: "@gradeui/ui"
+variants: [default, outline]
+sizes: [default, sm, lg]
+props:
+  - variant? (default | outline) — outline adds a border, default is borderless and ghost-like
+  - size? (default | sm | lg)
+  - pressed?: boolean — controlled pressed state
+  - defaultPressed?: boolean — uncontrolled initial state
+  - onPressedChange?: (pressed: boolean) => void
+  - disabled?: boolean
+  - children: React.ReactNode — usually an icon or short label
+when_to_use: A standalone on/off button — Bold/Italic in a toolbar, "Show grid" in a header, single binary toggle that doesn't belong inside a Switch row. For two-or-more mutually-exclusive options use ToggleGroup. For a labeled settings switch ("Active: on/off") use Switch.
+composes_with: [Tooltip (wrap an icon-only Toggle), Row, TabsList (sibling)]
+aliases: [toggle, toggle button, press button, bold button, italic button]
+---
+
+```jsx
+// Single toolbar toggle — icon + tooltip for screen readers.
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Toggle aria-label="Toggle bold">
+        <Bold />
+      </Toggle>
+    </TooltipTrigger>
+    <TooltipContent>Bold</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+```jsx
+// Borderless variant — fits inline among other controls.
+<Toggle defaultPressed>Show grid</Toggle>
+```

package/components/ui/toolbar.md

@@ -0,0 +1,167 @@
+---
+name: Toolbar
+import: "@gradeui/ui"
+role: layout
+subcomponents: [ToolbarSlot]
+props:
+  - leading?: React.ReactNode — left-aligned region (logo + primary nav)
+  - center?: React.ReactNode — center region (search, page title, segmented control)
+  - trailing?: React.ReactNode — right-aligned region (action icons, avatar, primary CTA)
+  - children?: React.ReactNode — escape hatch; bypasses slot layout
+  - position?: "top" | "bottom" | "inline" (default "top") — border placement
+  - variant?: "default" | "subtle" | "transparent" (default "default")
+  - size?: "sm" | "md" | "lg" (default "md") — height + padding
+  - sticky?: boolean (default false) — pin to top/bottom of scroll container
+  - aria-label?: string (default "Toolbar") — required by WAI-ARIA toolbar pattern
+  - className?: string
+when_to_use: |
+  ANY three-region chrome bar — the leading/center/trailing pattern Apple HIG
+  describes as a "Toolbar." App window chrome (Reddit, Twitter, GitHub, Linear,
+  most desktop apps), section toolbars inside Cards or panels, bottom action
+  bars on mobile layouts, persistent footer toolbars.
+
+  Don't hand-roll `<Row justify="between">` with a flex-1 on a middle child and
+  manual min-width juggling — Toolbar gives you the canonical `auto 1fr auto`
+  grid for free, with `role="toolbar"`, `data-gds-part` markers, position
+  variants for top/bottom borders, and sticky sizing.
+
+  Slot semantics:
+    leading   — Logo + nav rail (e.g. a `<Row>` of Buttons or Link components)
+    center    — Search input, page title chip, segmented Tab strip
+    trailing  — Icon buttons, notification bell, avatar, primary CTA
+
+  When a slot is omitted, its column collapses cleanly. Center stays visually
+  centered in the bar regardless of leading/trailing widths because the grid
+  template is `auto 1fr auto` (the center column absorbs available width).
+
+  Use as the top child of `<AppShellHeader>` for window-level chrome:
+    <AppShellHeader>
+      <Toolbar leading={<Logo/>} center={<Search/>} trailing={<Avatar/>} />
+    </AppShellHeader>
+
+  Use directly inside a Card or page section for section-scoped toolbars:
+    <Card>
+      <Toolbar size="sm" variant="subtle" leading={...} trailing={...} />
+      {content}
+    </Card>
+composes_with: [Button, Avatar, Input, Logo, Badge, AppShellHeader, Card, Row, Stack]
+aliases: [
+  toolbar, tool bar, top bar, topbar, app bar, appbar, header bar, header,
+  navigation bar, nav bar, navbar, window chrome, window toolbar, title bar,
+  titlebar, action bar, actionbar, command bar, ribbon,
+  three-region nav, leading center trailing, leading-center-trailing,
+  apple hig toolbar, hig toolbar, native toolbar, segmented toolbar,
+  bottom toolbar, footer toolbar, fixed toolbar, sticky header
+]
+notes: |
+  Apple HIG reference: https://developer.apple.com/design/human-interface-guidelines/toolbars
+  WAI-ARIA toolbar pattern: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+
+  Roving tabindex for arrow-key navigation between toolbar items is NOT
+  implemented in v1. For a tight cluster of related controls (an editor
+  toolbar — B / I / S / link), compose with @radix-ui/react-toolbar inside
+  the slots if you need arrow-key navigation. For an app chrome bar (logo
+  + nav + actions), standard tab order is the expected pattern and a
+  single aria-label is sufficient.
+
+  Center vs. leading for the page title:
+    - Use `center` for a CENTERED page title (Apple-style window chrome).
+    - Use `leading` after the logo for a LEFT-ALIGNED page title (web-app
+      style — GitHub, Linear). Mixing is fine.
+---
+
+```jsx
+// App window chrome — Reddit / Twitter / GitHub shape.
+<Toolbar
+  leading={
+    <Row gap="sm" align="center">
+      <Logo />
+      <Button variant="ghost" size="sm">Home</Button>
+      <Button variant="ghost" size="sm">Explore</Button>
+    </Row>
+  }
+  center={
+    <Input placeholder="Search" className="max-w-md" />
+  }
+  trailing={
+    <Row gap="xs" align="center">
+      <Button variant="ghost" size="icon"><Bell /></Button>
+      <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+    </Row>
+  }
+/>
+```
+
+```jsx
+// Section toolbar inside a Card — small, subtle, no border.
+<Card>
+  <Toolbar
+    size="sm"
+    variant="subtle"
+    position="inline"
+    leading={<span className="text-sm font-medium">Recent activity</span>}
+    trailing={
+      <Button variant="ghost" size="sm">View all</Button>
+    }
+  />
+  <CardContent>…</CardContent>
+</Card>
+```
+
+```jsx
+// Bottom action toolbar — common on mobile-style detail pages.
+<Toolbar
+  position="bottom"
+  sticky
+  leading={<Button variant="outline" size="sm">Cancel</Button>}
+  trailing={<Button size="sm">Save changes</Button>}
+/>
+```
+
+```jsx
+// Inside AppShellHeader — the canonical "app chrome" composition.
+<AppShell nav="side">
+  <AppShellHeader>
+    <Toolbar
+      leading={<Logo />}
+      trailing={
+        <Row gap="xs">
+          <Button variant="ghost" size="icon"><Bell /></Button>
+          <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+        </Row>
+      }
+    />
+  </AppShellHeader>
+  <AppShellNav placement="side">{/* sidebar */}</AppShellNav>
+  <AppShellMain>{/* content */}</AppShellMain>
+</AppShell>
+```
+
+## Anti-patterns
+
+```jsx
+// ❌ Hand-rolling the three-region grid every time.
+<Row justify="between" align="center" className="px-4 py-3 border-b border-border">
+  <Row gap="sm" align="center"><Logo /></Row>
+  <div className="flex-1 flex justify-center"><Input className="max-w-md" /></div>
+  <Row gap="xs" align="center"><Bell /><Avatar /></Row>
+</Row>
+
+// ✅ Toolbar collapses this to slot props + the right ARIA role.
+<Toolbar
+  leading={<Logo />}
+  center={<Input className="max-w-md" />}
+  trailing={<Row gap="xs"><Bell /><Avatar /></Row>}
+/>
+```
+
+```jsx
+// ❌ Cramming an editor-style toolbar (B / I / S / link) into the leading
+//    slot. Toolbar's slot layout is for chrome bars; for a tight cluster
+//    of related controls with arrow-key navigation, compose with Radix
+//    Toolbar primitives inside the leading slot OR use a plain <Row>.
+
+// ✅ Editor toolbar lives inside the section it's editing, not in the
+//    window chrome. Use a Row of Buttons or @radix-ui/react-toolbar
+//    inside the section.
+```

package/components/ui/tooltip.md

@@ -0,0 +1,28 @@
+---
+name: Tooltip
+import: "@gradeui/ui"
+subcomponents: [TooltipTrigger, TooltipContent, TooltipProvider]
+props:
+  - TooltipProvider: delayDuration? number (default 700) — ms hover before show; mount ONCE near the app root
+  - TooltipProvider: skipDelayDuration? number (default 300) — ms gap that still feels like "same hover"
+  - Tooltip: open?, defaultOpen?, onOpenChange?
+  - TooltipTrigger: asChild?: boolean — usually wraps a Button or icon
+  - TooltipContent: side? "top" | "right" | "bottom" | "left" (default "top"); align? "start" | "center" | "end"; sideOffset?: number
+when_to_use: A short, non-essential label that explains a control on hover/focus — icon-only buttons in toolbars, abbreviated column headers, status dots. NEVER hide critical info inside a tooltip — they're invisible on touch and can be skipped by screen readers if implemented carelessly. For richer hover content use HoverCard. For inline help text that's always visible, use a description paragraph.
+composes_with: [Button (icon-only), Toggle, TabsTrigger (the canonical tabs already have a `tooltip` prop that wraps this), Avatar (status badge meaning)]
+aliases: [tooltip, tip, hover tip, hint, label on hover, help tag, hint, helper text bubble, info tip]
+---
+
+```jsx
+// Icon-only Button with a tooltip — accessible name still set via aria-label.
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="ghost" size="icon" aria-label="Open settings">
+        <Settings />
+      </Button>
+    </TooltipTrigger>
+    <TooltipContent>Settings</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```

package/components/ui/video-player.md

@@ -0,0 +1,27 @@
+---
+name: VideoPlayer
+import: "@gradeui/ui"
+props:
+  - src: string — video URL
+  - controls?: boolean (default true) — show native controls; false for chromeless hero/background video
+  - autoPlay?: boolean (default false) — forces muted=true (browser restriction)
+  - loop?: boolean (default false)
+  - muted?: boolean (default = autoPlay)
+  - pauseOffscreen?: boolean (default true) — pause when scrolled out of viewport
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--gds-media-radius`
+  - objectFit?: "cover" | "contain" | "fill" (default "cover")
+  - poster?: string — image shown before playback. Always rendered as a `loading="lazy"` `<img>` overlay (not the native `poster` attribute, which fetches eagerly).
+  - playbackRate?: number (default 1)
+when_to_use: HTML5 video wrapped in the shared media surface. Controls-on for a standard player, controls-off (+ autoplay/muted/loop) for hero / background video. Prefer Rive for anything interactive, Three Scene for shader backgrounds.
+composes_with: [MediaSurface (internal), Card (wrap for thumbnail grids)]
+aliases: [video, mp4, movie, webm, clip, video view, av player, react native video, video element]
+notes: Poster images are always lazy-loaded. We don't use the native `<video poster>` attribute because browsers fetch it eagerly even when the surface is off-screen, which wastes the offscreen-pause savings. Instead we render `<img loading="lazy" decoding="async">` layered over the video, then fade it out on `onPlaying`. When no `src` is given nothing renders — always pass a URL.
+---
+
+```jsx
+<VideoPlayer src="/sample.mp4" poster="/movie-poster.jpg" controls />
+
+// Chromeless hero video
+<VideoPlayer src="/sample.mp4" controls={false} autoPlay loop muted aspect="wide" />
+```

package/dist/contracts.d.mts

@@ -0,0 +1,14 @@
+import { ComponentContract } from '@gradeui/contracts';
+
+/**
+ * Component contract registry — auto-managed by
+ * scripts/generate-contracts.mjs. Hand-authored contracts (MediaSurface,
+ * etc.) are also wired in here; the generator preserves them on each
+ * run.
+ */
+
+declare const COMPONENT_CONTRACTS: Readonly<Record<string, ComponentContract>>;
+declare function getComponentContract(componentName: string | null | undefined): ComponentContract | null;
+declare function listContractedComponents(): string[];
+
+export { COMPONENT_CONTRACTS, getComponentContract, listContractedComponents };

package/dist/contracts.d.ts

@@ -0,0 +1,14 @@
+import { ComponentContract } from '@gradeui/contracts';
+
+/**
+ * Component contract registry — auto-managed by
+ * scripts/generate-contracts.mjs. Hand-authored contracts (MediaSurface,
+ * etc.) are also wired in here; the generator preserves them on each
+ * run.
+ */
+
+declare const COMPONENT_CONTRACTS: Readonly<Record<string, ComponentContract>>;
+declare function getComponentContract(componentName: string | null | undefined): ComponentContract | null;
+declare function listContractedComponents(): string[];
+
+export { COMPONENT_CONTRACTS, getComponentContract, listContractedComponents };