@gradeui/ui 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -17,6 +17,7 @@ import * as SliderPrimitive from '@radix-ui/react-slider';
 import * as SwitchPrimitives from '@radix-ui/react-switch';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as THREE from 'three';
 import { ClassValue } from 'clsx';
 
 declare const Accordion: React$1.ForwardRefExoticComponent<(AccordionPrimitive.AccordionSingleProps | AccordionPrimitive.AccordionMultipleProps) & React$1.RefAttributes<HTMLDivElement>>;
@@ -426,6 +427,314 @@ declare const Tooltip: React$1.FC<TooltipPrimitive.TooltipProps>;
 declare const TooltipTrigger: React$1.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
 declare const TooltipContent: React$1.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * MediaSurface — the shared shell used by VideoPlayer, RivePlayer,
+ * and ThreeScene. Not exported publicly.
+ *
+ * Handles the surface area that's identical across all media types:
+ *   - aspect ratio / radius / border (driven by CSS variables for theming)
+ *   - loading skeleton
+ *   - intersection-observer (for pause-when-offscreen)
+ *   - reduced-motion query
+ *
+ * Design-system note: all visual dimensions are backed by CSS vars so
+ * consumers can retheme via `--rds-media-radius`, `--rds-media-border`, etc.
+ * (These will rename to `--gds-*` when the broader codebase rename lands.)
+ */
+
+type MediaAspect = "video" | "square" | "portrait" | "wide" | "auto";
+type MediaRadius = "none" | "sm" | "md" | "lg" | "xl";
+interface MediaSurfaceProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "children"> {
+    aspect?: MediaAspect;
+    radius?: MediaRadius;
+    border?: boolean;
+    loading?: boolean;
+    /** Callback fires when the surface enters / leaves the viewport. */
+    onVisibilityChange?: (visible: boolean) => void;
+    /** Fallback shown before `onReady` is signalled by the child. */
+    fallback?: React$1.ReactNode;
+    children?: React$1.ReactNode;
+}
+declare const MediaSurface: React$1.ForwardRefExoticComponent<MediaSurfaceProps & React$1.RefAttributes<HTMLDivElement>>;
+/** Shared prop interface extended by each media primitive. */
+interface BaseMediaProps {
+    /** src for the media — url or path. */
+    src?: string;
+    /** Show native-ish play/pause/scrubber controls. Default: `true` for video, `false` for Rive/three. */
+    controls?: boolean;
+    /** Autoplay when mounted (respects reduced-motion). */
+    autoPlay?: boolean;
+    /** Loop on end. */
+    loop?: boolean;
+    /** Pause rendering / playback when offscreen. Default `true` (big perf win for WebGL). */
+    pauseOffscreen?: boolean;
+    /** Aspect ratio of the surface. */
+    aspect?: MediaAspect;
+    /** Corner radius. */
+    radius?: MediaRadius;
+    /** Draw a subtle border around the surface. */
+    border?: boolean;
+    /** Poster / fallback image while loading. */
+    poster?: string;
+    /** Accessible label — used as `aria-label` on the surface. */
+    label?: string;
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+/** Hook — returns `true` when the OS reports reduced-motion preference. */
+declare function usePrefersReducedMotion(): boolean;
+
+/**
+ * VideoPlayer — native HTML5 video wrapped in a MediaSurface.
+ *
+ * Modes:
+ *   controls={true}  (default) — shows native video controls
+ *   controls={false}           — bare viewer: hides chrome, muted autoplay/loop
+ */
+
+interface VideoPlayerProps extends BaseMediaProps {
+    /** Mute audio. Required `true` if `autoPlay` (browser restriction). */
+    muted?: boolean;
+    /** Playback rate. Defaults to 1. */
+    playbackRate?: number;
+    /** Object-fit. Defaults to "cover" — matches typical hero/background use. */
+    objectFit?: "cover" | "contain" | "fill";
+}
+declare const VideoPlayer: React$1.ForwardRefExoticComponent<VideoPlayerProps & React$1.RefAttributes<HTMLVideoElement>>;
+
+/**
+ * RivePlayer — Rive runtime wrapped in a MediaSurface.
+ *
+ * The @rive-app/react-canvas dep is marked `optional` in package.json — this
+ * component lazy-imports it so consumers who don't use Rive don't fail at
+ * install time and don't pay the bundle cost unless they render one.
+ *
+ * Modes:
+ *   controls={true}             — shows a small play/pause overlay
+ *   controls={false} (default)  — bare viewer: zero chrome
+ */
+
+interface RivePlayerProps extends BaseMediaProps {
+    /** State machine to run. */
+    stateMachines?: string | string[];
+    /** Artboard name — omit to use the default. */
+    artboard?: string;
+    /** Object-fit equivalent — how the art sits inside the surface. */
+    fit?: "contain" | "cover" | "fill" | "fitWidth" | "fitHeight" | "none";
+    /** Inputs to pass to the state machine. */
+    stateMachineInputs?: Record<string, number | boolean | string>;
+}
+declare const RivePlayer: React$1.ForwardRefExoticComponent<RivePlayerProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared types for the three.js layer of the design system.
+ *
+ * Presets are structured data so the same registry can drive both the
+ * runtime `<ThreeScene preset="..." />` and the `<ShaderPresetPicker />`
+ * preview gallery without duplicating shaders.
+ */
+
+/** Minimal context passed to a scene factory. */
+interface SceneContext {
+    renderer: THREE.WebGLRenderer;
+    width: number;
+    height: number;
+    /** Palette to drive the scene — all presets map their colors onto these slots. */
+    palette: Palette;
+}
+/** The four palette slots every preset opts into. */
+interface Palette {
+    primary: string;
+    secondary: string;
+    accent: string;
+    background: string;
+}
+/** A scene factory returns everything needed to run and tear down a scene. */
+interface SceneHandle {
+    scene: THREE.Scene;
+    camera: THREE.Camera;
+    /** Called every frame with elapsed seconds + delta seconds. */
+    update?: (elapsed: number, delta: number) => void;
+    /** Called on container resize. */
+    resize?: (width: number, height: number) => void;
+    /** Called when palette changes at runtime. */
+    setPalette?: (palette: Palette) => void;
+    /** Release GPU + CPU resources. */
+    dispose?: () => void;
+}
+type SceneFactory = (ctx: SceneContext) => SceneHandle;
+/** Declarative description of a post-FX stack. Specific pass types are strings
+ *  so consumers can author presets without importing postprocessing types. */
+interface PostPreset {
+    id: string;
+    label: string;
+    /** Per-pass options keyed by effect name (bloom, noise, scanlines, vignette, chromatic, glitch). */
+    effects: {
+        bloom?: {
+            intensity?: number;
+            luminanceThreshold?: number;
+            radius?: number;
+        };
+        noise?: {
+            intensity?: number;
+        };
+        scanlines?: {
+            density?: number;
+            opacity?: number;
+        };
+        vignette?: {
+            darkness?: number;
+            offset?: number;
+        };
+        chromatic?: {
+            offset?: number;
+        };
+        glitch?: {
+            chromatic?: boolean;
+            strength?: [number, number];
+        };
+    };
+}
+/** A shader preset is the data needed to instantiate one of the canned scenes. */
+interface ShaderPreset {
+    id: string;
+    /** Short human label for picker cards. */
+    label: string;
+    /** One-line description an LLM can use to pick this preset. */
+    description: string;
+    /** Semantic tags — consumer filters ("space", "retro", "abstract") and LLM hints. */
+    tags: string[];
+    /** Name of the scene factory in the scene registry. */
+    scene: string;
+    /** Default post-FX preset id for this preset. */
+    defaultPostPreset?: string;
+    /** Optional palette overrides — otherwise uses the theme palette. */
+    defaultPalette?: Partial<Palette>;
+    /** Static poster image path for non-hover previews. Served from /public. */
+    poster?: string;
+}
+
+/**
+ * ThreeScene — the WebGL media primitive.
+ *
+ * Supports two modes:
+ *   1. Preset mode:  <ThreeScene preset="space" postPreset="vhs" />
+ *   2. Custom mode:  <ThreeScene createScene={({ renderer, width, height, palette }) => ({ scene, camera, update, dispose })} />
+ *
+ * Post-FX composer is always applied; use postPreset="none" for a clean render.
+ *
+ * Zero-chrome viewer mode: the default. Pass `controls` to show a minimal
+ * play/pause overlay. Scene pauses when offscreen (pauseOffscreen default `true`).
+ */
+
+interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster"> {
+    /** Preset id from the shader preset registry. */
+    preset?: string;
+    /** Post-FX preset id. Defaults to the preset's `defaultPostPreset` or "vhs". */
+    postPreset?: string;
+    /** Palette overrides. Unset slots fall back to `DEFAULT_PALETTE`. */
+    palette?: Partial<Palette>;
+    /**
+     * Custom scene factory. Takes precedence over `preset`.
+     * Use for bespoke three.js scenes that don't fit a preset.
+     */
+    createScene?: SceneFactory;
+    /** Static poster to show while the GL context warms up. */
+    poster?: string;
+    /** Pixel-ratio cap. Defaults to `Math.min(window.devicePixelRatio, 2)`. */
+    maxDpr?: number;
+}
+declare const ThreeScene: React$1.ForwardRefExoticComponent<ThreeSceneProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ShaderPresetPreview — a thumbnail-sized preview of a shader preset.
+ *
+ * Default behaviour: static poster until hovered, then kick in a live
+ * `<ThreeScene>` render. Keeps gallery pages cheap (ten live shaders on
+ * one page eats FPS fast, Safari caps WebGL contexts ~8).
+ *
+ * Props:
+ *   live: "never"  → always show poster, no canvas
+ *   live: "hover"  → (default) canvas spins up on hover, tears down on leave
+ *   live: "always" → canvas always rendering
+ */
+
+interface ShaderPresetPreviewProps {
+    preset: string;
+    live?: "never" | "hover" | "always";
+    postPreset?: string;
+    palette?: Partial<Palette>;
+    className?: string;
+    aspect?: "video" | "square" | "portrait" | "wide";
+    radius?: "none" | "sm" | "md" | "lg" | "xl";
+    /** Text label shown on the card. Defaults to preset label. */
+    label?: string;
+    /** Hide the label strip. */
+    hideLabel?: boolean;
+    onClick?: () => void;
+}
+declare const ShaderPresetPreview: React$1.ForwardRefExoticComponent<ShaderPresetPreviewProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ShaderPresetPicker — runtime preset gallery + selection.
+ *
+ * A grid of `<ShaderPresetPreview>` cards. Click to select. Used for
+ * things like "pick a vibe for your course background".
+ *
+ * For a browsing-only catalogue with no selection, just lay out
+ * `<ShaderPresetPreview>` directly.
+ *
+ * TODO(phase 2): static catalogue page for the docs site mirroring this.
+ */
+
+interface ShaderPresetPickerProps {
+    /** Currently selected preset id (controlled). */
+    value?: string;
+    /** Called when the user clicks a preset. */
+    onChange?: (presetId: string) => void;
+    /** Filter by tag — e.g. only show `"space"` or `"retro"` presets. */
+    filterTags?: string[];
+    /** Live-render mode for thumbnails. Default "hover". */
+    live?: "never" | "hover" | "always";
+    /** Shared post-FX preset applied to all thumbnails. Default: each preset's own. */
+    postPreset?: string;
+    /** Shared palette for all thumbnails. */
+    palette?: Partial<Palette>;
+    /** Columns at md+ breakpoint. Default 3. */
+    columns?: 2 | 3 | 4;
+    className?: string;
+}
+declare function ShaderPresetPicker({ value, onChange, filterTags, live, postPreset, palette, columns, className, }: ShaderPresetPickerProps): React$1.JSX.Element;
+
+/**
+ * Shader preset registry — maps semantic preset ids to scene factories
+ * plus metadata for the picker UI.
+ *
+ * Adding a new preset:
+ *   1. Write a SceneFactory in `./scenes/<name>.ts`
+ *   2. Register it in `sceneRegistry` below
+ *   3. Add a `ShaderPreset` entry in `shaderPresets`
+ *
+ * Both `<ThreeScene preset="space" />` and `<ShaderPresetPicker />` read
+ * from this registry so they stay in lockstep.
+ */
+
+declare const sceneRegistry: Record<string, SceneFactory>;
+declare const shaderPresets: ShaderPreset[];
+declare const shaderPresetById: Record<string, ShaderPreset>;
+
+/**
+ * Post-FX preset registry.
+ *
+ * Each preset is a tunable description of the post-FX stack. Lives as data
+ * so the same registry drives `<ThreeScene postPreset="vhs" />` and the
+ * preset picker's preview thumbnails.
+ */
+
+declare const postPresets: Record<string, PostPreset>;
+type PostPresetId = keyof typeof postPresets;
+declare const defaultPostPreset: PostPresetId;
+
 declare function cn(...inputs: ClassValue[]): string;
 
 interface LenisProviderProps {
@@ -908,4 +1217,4 @@ declare function GradeModeSwitcher({ className, variant }: GradeModeSwitcherProp
  */
 declare function ThemeToggle(): React$1.JSX.Element;
 
-export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertTitle, BUILT_IN_INPUTS, Badge, type BreadcrumbItem, Button, type ButtonShape, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, type ChartPalette, Checkbox, type ColorIntensity, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Input, type InputStyle, Label, LenisProvider, type ModeName, type OKLCHTriplet, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SideMenu, type SideMenuItem, type SideMenuProps, type SideMenuSection, type SimpleTab, SimpleTabs, SimpleTabsContent, SimpleTabsList, type SimpleTabsListProps, SimpleTabsPanel, type SimpleTabsPanelProps, type SimpleTabsProps, SimpleTabsRoot, type SimpleTabsRootProps, SimpleTabsTrigger, type SimpleTabsTriggerProps, Skeleton, Slider, type SpacingDensity, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopMenu, type TopMenuProps, TopMenuUser, TopMenuUserItem, type TopMenuUserItemProps, type TopMenuUserProps, TopMenuUserSection, type TypeScalePreset, applyThemeToRoot, badgeVariants, builtInThemes, buttonVariants, calmInput, cn, defaultThemeId, deleteUserTheme, duplicateTheme, energyInput, generateTheme, getTheme, listThemes, listUserThemes, loadUserThemeInput, saveUserTheme, themeToCSSVars, useGradeTheme, useMaybeGradeTheme };
+export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertTitle, BUILT_IN_INPUTS, Badge, type BaseMediaProps, type BreadcrumbItem, Button, type ButtonShape, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, type ChartPalette, Checkbox, type ColorIntensity, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Input, type InputStyle, Label, LenisProvider, type MediaAspect, type MediaRadius, MediaSurface, type MediaSurfaceProps, type ModeName, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, RivePlayer, type RivePlayerProps, type SceneContext, type SceneFactory, type SceneHandle, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SideMenu, type SideMenuItem, type SideMenuProps, type SideMenuSection, type SimpleTab, SimpleTabs, SimpleTabsContent, SimpleTabsList, type SimpleTabsListProps, SimpleTabsPanel, type SimpleTabsPanelProps, type SimpleTabsProps, SimpleTabsRoot, type SimpleTabsRootProps, SimpleTabsTrigger, type SimpleTabsTriggerProps, Skeleton, Slider, type SpacingDensity, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopMenu, type TopMenuProps, TopMenuUser, TopMenuUserItem, type TopMenuUserItemProps, type TopMenuUserProps, TopMenuUserSection, type TypeScalePreset, VideoPlayer, type VideoPlayerProps, applyThemeToRoot, badgeVariants, builtInThemes, buttonVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, duplicateTheme, energyInput, generateTheme, getTheme, listThemes, listUserThemes, loadUserThemeInput, postPresets, saveUserTheme, sceneRegistry, shaderPresetById, shaderPresets, themeToCSSVars, useGradeTheme, useMaybeGradeTheme, usePrefersReducedMotion };

package/dist/index.d.ts

@@ -17,6 +17,7 @@ import * as SliderPrimitive from '@radix-ui/react-slider';
 import * as SwitchPrimitives from '@radix-ui/react-switch';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as THREE from 'three';
 import { ClassValue } from 'clsx';
 
 declare const Accordion: React$1.ForwardRefExoticComponent<(AccordionPrimitive.AccordionSingleProps | AccordionPrimitive.AccordionMultipleProps) & React$1.RefAttributes<HTMLDivElement>>;
@@ -426,6 +427,314 @@ declare const Tooltip: React$1.FC<TooltipPrimitive.TooltipProps>;
 declare const TooltipTrigger: React$1.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
 declare const TooltipContent: React$1.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * MediaSurface — the shared shell used by VideoPlayer, RivePlayer,
+ * and ThreeScene. Not exported publicly.
+ *
+ * Handles the surface area that's identical across all media types:
+ *   - aspect ratio / radius / border (driven by CSS variables for theming)
+ *   - loading skeleton
+ *   - intersection-observer (for pause-when-offscreen)
+ *   - reduced-motion query
+ *
+ * Design-system note: all visual dimensions are backed by CSS vars so
+ * consumers can retheme via `--rds-media-radius`, `--rds-media-border`, etc.
+ * (These will rename to `--gds-*` when the broader codebase rename lands.)
+ */
+
+type MediaAspect = "video" | "square" | "portrait" | "wide" | "auto";
+type MediaRadius = "none" | "sm" | "md" | "lg" | "xl";
+interface MediaSurfaceProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "children"> {
+    aspect?: MediaAspect;
+    radius?: MediaRadius;
+    border?: boolean;
+    loading?: boolean;
+    /** Callback fires when the surface enters / leaves the viewport. */
+    onVisibilityChange?: (visible: boolean) => void;
+    /** Fallback shown before `onReady` is signalled by the child. */
+    fallback?: React$1.ReactNode;
+    children?: React$1.ReactNode;
+}
+declare const MediaSurface: React$1.ForwardRefExoticComponent<MediaSurfaceProps & React$1.RefAttributes<HTMLDivElement>>;
+/** Shared prop interface extended by each media primitive. */
+interface BaseMediaProps {
+    /** src for the media — url or path. */
+    src?: string;
+    /** Show native-ish play/pause/scrubber controls. Default: `true` for video, `false` for Rive/three. */
+    controls?: boolean;
+    /** Autoplay when mounted (respects reduced-motion). */
+    autoPlay?: boolean;
+    /** Loop on end. */
+    loop?: boolean;
+    /** Pause rendering / playback when offscreen. Default `true` (big perf win for WebGL). */
+    pauseOffscreen?: boolean;
+    /** Aspect ratio of the surface. */
+    aspect?: MediaAspect;
+    /** Corner radius. */
+    radius?: MediaRadius;
+    /** Draw a subtle border around the surface. */
+    border?: boolean;
+    /** Poster / fallback image while loading. */
+    poster?: string;
+    /** Accessible label — used as `aria-label` on the surface. */
+    label?: string;
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+/** Hook — returns `true` when the OS reports reduced-motion preference. */
+declare function usePrefersReducedMotion(): boolean;
+
+/**
+ * VideoPlayer — native HTML5 video wrapped in a MediaSurface.
+ *
+ * Modes:
+ *   controls={true}  (default) — shows native video controls
+ *   controls={false}           — bare viewer: hides chrome, muted autoplay/loop
+ */
+
+interface VideoPlayerProps extends BaseMediaProps {
+    /** Mute audio. Required `true` if `autoPlay` (browser restriction). */
+    muted?: boolean;
+    /** Playback rate. Defaults to 1. */
+    playbackRate?: number;
+    /** Object-fit. Defaults to "cover" — matches typical hero/background use. */
+    objectFit?: "cover" | "contain" | "fill";
+}
+declare const VideoPlayer: React$1.ForwardRefExoticComponent<VideoPlayerProps & React$1.RefAttributes<HTMLVideoElement>>;
+
+/**
+ * RivePlayer — Rive runtime wrapped in a MediaSurface.
+ *
+ * The @rive-app/react-canvas dep is marked `optional` in package.json — this
+ * component lazy-imports it so consumers who don't use Rive don't fail at
+ * install time and don't pay the bundle cost unless they render one.
+ *
+ * Modes:
+ *   controls={true}             — shows a small play/pause overlay
+ *   controls={false} (default)  — bare viewer: zero chrome
+ */
+
+interface RivePlayerProps extends BaseMediaProps {
+    /** State machine to run. */
+    stateMachines?: string | string[];
+    /** Artboard name — omit to use the default. */
+    artboard?: string;
+    /** Object-fit equivalent — how the art sits inside the surface. */
+    fit?: "contain" | "cover" | "fill" | "fitWidth" | "fitHeight" | "none";
+    /** Inputs to pass to the state machine. */
+    stateMachineInputs?: Record<string, number | boolean | string>;
+}
+declare const RivePlayer: React$1.ForwardRefExoticComponent<RivePlayerProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared types for the three.js layer of the design system.
+ *
+ * Presets are structured data so the same registry can drive both the
+ * runtime `<ThreeScene preset="..." />` and the `<ShaderPresetPicker />`
+ * preview gallery without duplicating shaders.
+ */
+
+/** Minimal context passed to a scene factory. */
+interface SceneContext {
+    renderer: THREE.WebGLRenderer;
+    width: number;
+    height: number;
+    /** Palette to drive the scene — all presets map their colors onto these slots. */
+    palette: Palette;
+}
+/** The four palette slots every preset opts into. */
+interface Palette {
+    primary: string;
+    secondary: string;
+    accent: string;
+    background: string;
+}
+/** A scene factory returns everything needed to run and tear down a scene. */
+interface SceneHandle {
+    scene: THREE.Scene;
+    camera: THREE.Camera;
+    /** Called every frame with elapsed seconds + delta seconds. */
+    update?: (elapsed: number, delta: number) => void;
+    /** Called on container resize. */
+    resize?: (width: number, height: number) => void;
+    /** Called when palette changes at runtime. */
+    setPalette?: (palette: Palette) => void;
+    /** Release GPU + CPU resources. */
+    dispose?: () => void;
+}
+type SceneFactory = (ctx: SceneContext) => SceneHandle;
+/** Declarative description of a post-FX stack. Specific pass types are strings
+ *  so consumers can author presets without importing postprocessing types. */
+interface PostPreset {
+    id: string;
+    label: string;
+    /** Per-pass options keyed by effect name (bloom, noise, scanlines, vignette, chromatic, glitch). */
+    effects: {
+        bloom?: {
+            intensity?: number;
+            luminanceThreshold?: number;
+            radius?: number;
+        };
+        noise?: {
+            intensity?: number;
+        };
+        scanlines?: {
+            density?: number;
+            opacity?: number;
+        };
+        vignette?: {
+            darkness?: number;
+            offset?: number;
+        };
+        chromatic?: {
+            offset?: number;
+        };
+        glitch?: {
+            chromatic?: boolean;
+            strength?: [number, number];
+        };
+    };
+}
+/** A shader preset is the data needed to instantiate one of the canned scenes. */
+interface ShaderPreset {
+    id: string;
+    /** Short human label for picker cards. */
+    label: string;
+    /** One-line description an LLM can use to pick this preset. */
+    description: string;
+    /** Semantic tags — consumer filters ("space", "retro", "abstract") and LLM hints. */
+    tags: string[];
+    /** Name of the scene factory in the scene registry. */
+    scene: string;
+    /** Default post-FX preset id for this preset. */
+    defaultPostPreset?: string;
+    /** Optional palette overrides — otherwise uses the theme palette. */
+    defaultPalette?: Partial<Palette>;
+    /** Static poster image path for non-hover previews. Served from /public. */
+    poster?: string;
+}
+
+/**
+ * ThreeScene — the WebGL media primitive.
+ *
+ * Supports two modes:
+ *   1. Preset mode:  <ThreeScene preset="space" postPreset="vhs" />
+ *   2. Custom mode:  <ThreeScene createScene={({ renderer, width, height, palette }) => ({ scene, camera, update, dispose })} />
+ *
+ * Post-FX composer is always applied; use postPreset="none" for a clean render.
+ *
+ * Zero-chrome viewer mode: the default. Pass `controls` to show a minimal
+ * play/pause overlay. Scene pauses when offscreen (pauseOffscreen default `true`).
+ */
+
+interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster"> {
+    /** Preset id from the shader preset registry. */
+    preset?: string;
+    /** Post-FX preset id. Defaults to the preset's `defaultPostPreset` or "vhs". */
+    postPreset?: string;
+    /** Palette overrides. Unset slots fall back to `DEFAULT_PALETTE`. */
+    palette?: Partial<Palette>;
+    /**
+     * Custom scene factory. Takes precedence over `preset`.
+     * Use for bespoke three.js scenes that don't fit a preset.
+     */
+    createScene?: SceneFactory;
+    /** Static poster to show while the GL context warms up. */
+    poster?: string;
+    /** Pixel-ratio cap. Defaults to `Math.min(window.devicePixelRatio, 2)`. */
+    maxDpr?: number;
+}
+declare const ThreeScene: React$1.ForwardRefExoticComponent<ThreeSceneProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ShaderPresetPreview — a thumbnail-sized preview of a shader preset.
+ *
+ * Default behaviour: static poster until hovered, then kick in a live
+ * `<ThreeScene>` render. Keeps gallery pages cheap (ten live shaders on
+ * one page eats FPS fast, Safari caps WebGL contexts ~8).
+ *
+ * Props:
+ *   live: "never"  → always show poster, no canvas
+ *   live: "hover"  → (default) canvas spins up on hover, tears down on leave
+ *   live: "always" → canvas always rendering
+ */
+
+interface ShaderPresetPreviewProps {
+    preset: string;
+    live?: "never" | "hover" | "always";
+    postPreset?: string;
+    palette?: Partial<Palette>;
+    className?: string;
+    aspect?: "video" | "square" | "portrait" | "wide";
+    radius?: "none" | "sm" | "md" | "lg" | "xl";
+    /** Text label shown on the card. Defaults to preset label. */
+    label?: string;
+    /** Hide the label strip. */
+    hideLabel?: boolean;
+    onClick?: () => void;
+}
+declare const ShaderPresetPreview: React$1.ForwardRefExoticComponent<ShaderPresetPreviewProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ShaderPresetPicker — runtime preset gallery + selection.
+ *
+ * A grid of `<ShaderPresetPreview>` cards. Click to select. Used for
+ * things like "pick a vibe for your course background".
+ *
+ * For a browsing-only catalogue with no selection, just lay out
+ * `<ShaderPresetPreview>` directly.
+ *
+ * TODO(phase 2): static catalogue page for the docs site mirroring this.
+ */
+
+interface ShaderPresetPickerProps {
+    /** Currently selected preset id (controlled). */
+    value?: string;
+    /** Called when the user clicks a preset. */
+    onChange?: (presetId: string) => void;
+    /** Filter by tag — e.g. only show `"space"` or `"retro"` presets. */
+    filterTags?: string[];
+    /** Live-render mode for thumbnails. Default "hover". */
+    live?: "never" | "hover" | "always";
+    /** Shared post-FX preset applied to all thumbnails. Default: each preset's own. */
+    postPreset?: string;
+    /** Shared palette for all thumbnails. */
+    palette?: Partial<Palette>;
+    /** Columns at md+ breakpoint. Default 3. */
+    columns?: 2 | 3 | 4;
+    className?: string;
+}
+declare function ShaderPresetPicker({ value, onChange, filterTags, live, postPreset, palette, columns, className, }: ShaderPresetPickerProps): React$1.JSX.Element;
+
+/**
+ * Shader preset registry — maps semantic preset ids to scene factories
+ * plus metadata for the picker UI.
+ *
+ * Adding a new preset:
+ *   1. Write a SceneFactory in `./scenes/<name>.ts`
+ *   2. Register it in `sceneRegistry` below
+ *   3. Add a `ShaderPreset` entry in `shaderPresets`
+ *
+ * Both `<ThreeScene preset="space" />` and `<ShaderPresetPicker />` read
+ * from this registry so they stay in lockstep.
+ */
+
+declare const sceneRegistry: Record<string, SceneFactory>;
+declare const shaderPresets: ShaderPreset[];
+declare const shaderPresetById: Record<string, ShaderPreset>;
+
+/**
+ * Post-FX preset registry.
+ *
+ * Each preset is a tunable description of the post-FX stack. Lives as data
+ * so the same registry drives `<ThreeScene postPreset="vhs" />` and the
+ * preset picker's preview thumbnails.
+ */
+
+declare const postPresets: Record<string, PostPreset>;
+type PostPresetId = keyof typeof postPresets;
+declare const defaultPostPreset: PostPresetId;
+
 declare function cn(...inputs: ClassValue[]): string;
 
 interface LenisProviderProps {
@@ -908,4 +1217,4 @@ declare function GradeModeSwitcher({ className, variant }: GradeModeSwitcherProp
  */
 declare function ThemeToggle(): React$1.JSX.Element;
 
-export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertTitle, BUILT_IN_INPUTS, Badge, type BreadcrumbItem, Button, type ButtonShape, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, type ChartPalette, Checkbox, type ColorIntensity, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Input, type InputStyle, Label, LenisProvider, type ModeName, type OKLCHTriplet, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SideMenu, type SideMenuItem, type SideMenuProps, type SideMenuSection, type SimpleTab, SimpleTabs, SimpleTabsContent, SimpleTabsList, type SimpleTabsListProps, SimpleTabsPanel, type SimpleTabsPanelProps, type SimpleTabsProps, SimpleTabsRoot, type SimpleTabsRootProps, SimpleTabsTrigger, type SimpleTabsTriggerProps, Skeleton, Slider, type SpacingDensity, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopMenu, type TopMenuProps, TopMenuUser, TopMenuUserItem, type TopMenuUserItemProps, type TopMenuUserProps, TopMenuUserSection, type TypeScalePreset, applyThemeToRoot, badgeVariants, builtInThemes, buttonVariants, calmInput, cn, defaultThemeId, deleteUserTheme, duplicateTheme, energyInput, generateTheme, getTheme, listThemes, listUserThemes, loadUserThemeInput, saveUserTheme, themeToCSSVars, useGradeTheme, useMaybeGradeTheme };
+export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertTitle, BUILT_IN_INPUTS, Badge, type BaseMediaProps, type BreadcrumbItem, Button, type ButtonShape, Calendar, CalendarDayButton, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, type ChartPalette, Checkbox, type ColorIntensity, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Input, type InputStyle, Label, LenisProvider, type MediaAspect, type MediaRadius, MediaSurface, type MediaSurfaceProps, type ModeName, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, RivePlayer, type RivePlayerProps, type SceneContext, type SceneFactory, type SceneHandle, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SideMenu, type SideMenuItem, type SideMenuProps, type SideMenuSection, type SimpleTab, SimpleTabs, SimpleTabsContent, SimpleTabsList, type SimpleTabsListProps, SimpleTabsPanel, type SimpleTabsPanelProps, type SimpleTabsProps, SimpleTabsRoot, type SimpleTabsRootProps, SimpleTabsTrigger, type SimpleTabsTriggerProps, Skeleton, Slider, type SpacingDensity, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, TopMenu, type TopMenuProps, TopMenuUser, TopMenuUserItem, type TopMenuUserItemProps, type TopMenuUserProps, TopMenuUserSection, type TypeScalePreset, VideoPlayer, type VideoPlayerProps, applyThemeToRoot, badgeVariants, builtInThemes, buttonVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, duplicateTheme, energyInput, generateTheme, getTheme, listThemes, listUserThemes, loadUserThemeInput, postPresets, saveUserTheme, sceneRegistry, shaderPresetById, shaderPresets, themeToCSSVars, useGradeTheme, useMaybeGradeTheme, usePrefersReducedMotion };