@gradeui/ui 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -9,20 +9,21 @@ import * as AvatarPrimitive from '@radix-ui/react-avatar';
 import { DayPicker, DayButton, DateRange } from 'react-day-picker';
 import { UseEmblaCarouselType } from 'embla-carousel-react';
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import * as SwitchPrimitives from '@radix-ui/react-switch';
 import { Language } from 'prism-react-renderer';
+import { LexicalEditor } from 'lexical';
 import * as DialogPrimitive from '@radix-ui/react-dialog';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
 import * as LabelPrimitive from '@radix-ui/react-label';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import * as ProgressPrimitive from '@radix-ui/react-progress';
-import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import * as ResizablePrimitive from 'react-resizable-panels';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
 import * as SelectPrimitive from '@radix-ui/react-select';
 import * as SeparatorPrimitive from '@radix-ui/react-separator';
 import * as SliderPrimitive from '@radix-ui/react-slider';
 import { UniqueIdentifier } from '@dnd-kit/core';
-import * as SwitchPrimitives from '@radix-ui/react-switch';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 import * as TogglePrimitive from '@radix-ui/react-toggle';
 import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
@@ -47,6 +48,7 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
     hint: {
         schema: z.ZodOptional<z.ZodEnum<["album", "tv-show", "movie", "game", "book", "portrait", "landscape", "poster", "product", "food", "video", "audio", "embed", "3d", "generic"]>>;
         design: "knob";
+        group: string;
         control: "glyph-picker";
         label: string;
         description: string;
@@ -92,6 +94,7 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
     alt: {
         schema: z.ZodOptional<z.ZodString>;
         design: "content";
+        group: string;
         control: "text";
         label: string;
         description: string;
@@ -100,6 +103,7 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
     src: {
         schema: z.ZodOptional<z.ZodString>;
         design: "content";
+        group: string;
         control: "url";
         label: string;
         description: string;
@@ -173,14 +177,14 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
             description: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             kind: "book";
-            description?: string | undefined;
             title?: string | undefined;
+            description?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }, {
             kind: "book";
-            description?: string | undefined;
             title?: string | undefined;
+            description?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }>, z.ZodObject<{
@@ -466,9 +470,38 @@ interface AppShellFooterProps extends React$1.HTMLAttributes<HTMLElement>, Varia
 }
 declare const AppShellFooter: React$1.ForwardRefExoticComponent<AppShellFooterProps & React$1.RefAttributes<HTMLElement>>;
 
-declare const Avatar: React$1.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React$1.RefAttributes<HTMLSpanElement>, "ref"> & React$1.RefAttributes<HTMLSpanElement>>;
+/**
+ * Avatar — circular user/entity glyph. Wraps Radix's avatar primitive
+ * with two ergonomic additions over the base shadcn shape:
+ *
+ *   size — t-shirt scale (xs / sm / md / lg / xl) so consumers pick a
+ *          token instead of writing `h-7 w-7` every time. Defaults
+ *          to md (40px) to preserve previous behaviour.
+ *
+ *   tone — on AvatarFallback only. Picks a tinted bg/text colour
+ *          pair (violet / amber / emerald / sky / rose / plum / lime /
+ *          primary / muted). Default `muted` matches the previous
+ *          `bg-muted` behaviour. Reach for explicit tones when each
+ *          author needs a stable colour mapping (chat avatars, comment
+ *          threads, member lists).
+ *
+ * Both additions are backwards compatible — code that passed className
+ * directly still works and overrides the variant defaults.
+ */
+declare const avatarSizes: (props?: ({
+    size?: "sm" | "md" | "lg" | "xl" | "xs" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface AvatarProps extends React$1.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>, VariantProps<typeof avatarSizes> {
+}
+declare const Avatar: React$1.ForwardRefExoticComponent<AvatarProps & React$1.RefAttributes<HTMLSpanElement>>;
 declare const AvatarImage: React$1.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React$1.RefAttributes<HTMLImageElement>, "ref"> & React$1.RefAttributes<HTMLImageElement>>;
-declare const AvatarFallback: React$1.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarFallbackProps & React$1.RefAttributes<HTMLSpanElement>, "ref"> & React$1.RefAttributes<HTMLSpanElement>>;
+declare const avatarFallbackTones: (props?: ({
+    tone?: "muted" | "primary" | "violet" | "amber" | "emerald" | "sky" | "rose" | "plum" | "lime" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type AvatarTone = NonNullable<VariantProps<typeof avatarFallbackTones>["tone"]>;
+interface AvatarFallbackProps extends React$1.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback>, VariantProps<typeof avatarFallbackTones> {
+}
+declare const AvatarFallback: React$1.ForwardRefExoticComponent<AvatarFallbackProps & React$1.RefAttributes<HTMLSpanElement>>;
 
 declare const badgeVariants: (props?: ({
     variant?: "default" | "info" | "success" | "warning" | "destructive" | "outline" | "secondary" | "highlight" | "success-soft" | "warning-soft" | "destructive-soft" | "info-soft" | "highlight-soft" | "success-outline" | "warning-outline" | "destructive-outline" | "info-outline" | null | undefined;
@@ -538,7 +571,7 @@ type Surface = "solid" | "translucent" | "glass" | "glass-strong";
  */
 declare const bannerVariants: (props?: ({
     variant?: "default" | "info" | "success" | "warning" | "destructive" | "announcement" | null | undefined;
-    align?: "start" | "center" | "between" | null | undefined;
+    align?: "center" | "start" | "between" | null | undefined;
     sticky?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BannerProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title">, VariantProps<typeof bannerVariants> {
@@ -594,8 +627,8 @@ declare const Banner: React$1.ForwardRefExoticComponent<BannerProps & React$1.Re
  * consistent across primitives.
  */
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "raised" | null | undefined;
-    size?: "default" | "icon" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | "raised" | null | undefined;
+    size?: "default" | "sm" | "md" | "lg" | "icon" | "xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;
@@ -770,6 +803,107 @@ declare const CardFooter: React$1.ForwardRefExoticComponent<React$1.HTMLAttribut
 
 declare const Checkbox: React$1.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Field — the inline composition primitive for a control + its caption.
+ *
+ * Pairs a bare control (Checkbox / RadioGroupItem / Switch) with a label,
+ * an optional description, and an optional trailing slot — and wires the
+ * accessibility plumbing for you:
+ *
+ *   - generates one id, hands it to the control, and points the label's
+ *     `htmlFor` at it (click-the-label-to-toggle for free)
+ *   - if a <Field.Description> is present, links it via `aria-describedby`
+ *
+ * The control stays a bare primitive — Field clones it to inject the id +
+ * aria wiring, so Checkbox/Radio/Switch never grow a `description` prop.
+ *
+ *   <Field>
+ *     <Checkbox value="terms" />
+ *     <Field.Label>Accept terms</Field.Label>
+ *     <Field.Description>You agree to the privacy policy.</Field.Description>
+ *     <Field.Trailing><Badge>New</Badge></Field.Trailing>
+ *   </Field>
+ *
+ * Two layouts:
+ *   - `option`  (default) — control leads, text stacks beside it. The
+ *                checkbox/radio-with-label case. Top-aligned for two lines.
+ *   - `setting` — text leads, control pinned trailing. The classic
+ *                settings row (label + description on the left, Switch right).
+ *
+ * For a selectable *card* (the whole surface is the control), reach for
+ * RadioCard / CheckboxCard / SwitchCard instead — see `selection-card.tsx`.
+ */
+type FieldLayout = "option" | "setting";
+declare const FieldLabel: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>, "ref"> & React$1.RefAttributes<HTMLLabelElement>>;
+declare const FieldDescription: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, "ref"> & React$1.RefAttributes<HTMLParagraphElement>>;
+declare const FieldTrailing: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLDivElement> & React$1.RefAttributes<HTMLDivElement>>;
+interface FieldProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /** `option` (control leads) or `setting` (text leads, control trailing). */
+    layout?: FieldLayout;
+}
+declare const Field: React$1.ForwardRefExoticComponent<FieldProps & React$1.RefAttributes<HTMLDivElement>> & {
+    Label: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>, "ref"> & React$1.RefAttributes<HTMLLabelElement>>;
+    Description: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, "ref"> & React$1.RefAttributes<HTMLParagraphElement>>;
+    Trailing: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLDivElement> & React$1.RefAttributes<HTMLDivElement>>;
+};
+
+/**
+ * Selection cards — RadioCard / CheckboxCard / SwitchCard.
+ *
+ * The whole card IS the control. RadioCard renders as a
+ * `RadioGroupPrimitive.Item`, CheckboxCard as a `CheckboxPrimitive.Root`,
+ * SwitchCard as a `SwitchPrimitives.Root` — so focus, hover, and the
+ * checked state all live on the parent surface, and the entire card is the
+ * hit target. The small glyph (dot / check / switch) is just a visual
+ * indicator; it differs by type on purpose, because that's how someone
+ * reads single-select vs multi-select vs toggle at a glance.
+ *
+ * All three share ONE surface (`.gds-selection-card`) so they look identical
+ * sitting together. Every visual is token-driven (`--gds-selection-card-*`
+ * with semantic fallbacks), so a project can re-skin the cards through the
+ * per-project override layer without forking the component.
+ *
+ *   <RadioGroup defaultValue="standard" className="grid gap-3">
+ *     <RadioCard value="standard" label="Standard" description="4–10 business days" />
+ *     <RadioCard value="fast"     label="Fast"     description="2–5 business days" />
+ *     <RadioCard value="next-day" label="Next day" description="1 business day" />
+ *   </RadioGroup>
+ *
+ * IMPORTANT — interactive content. Because the card is itself a control
+ * (a `role=radio`/`checkbox`/`switch` button), you must NOT nest other
+ * interactive elements (Slider, Input, Button, links) inside it. Put only
+ * static content here (text, images, badges). If a card needs its own
+ * controls, use a plain `Card` containing a `Field` row + the control as
+ * siblings instead.
+ */
+type IndicatorPosition = "leading" | "trailing";
+interface SelectionCardOwnProps {
+    /** Title line. Omit and pass `children` for fully custom content. */
+    label?: React$1.ReactNode;
+    /** Secondary line under the label. */
+    description?: React$1.ReactNode;
+    /** Optional slot rendered between the content and the indicator
+     *  (a Badge, price, kbd hint, …). */
+    aside?: React$1.ReactNode;
+    /** Hide the dot/check/switch glyph — selection is then conveyed purely by
+     *  the card's selected border + background. Semantics stay intact. */
+    hideIndicator?: boolean;
+    /** Which side the indicator sits on. Default `trailing`. */
+    indicatorPosition?: IndicatorPosition;
+}
+interface RadioCardProps extends Omit<React$1.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>, "children">, SelectionCardOwnProps {
+    children?: React$1.ReactNode;
+}
+declare const RadioCard: React$1.ForwardRefExoticComponent<RadioCardProps & React$1.RefAttributes<HTMLButtonElement>>;
+interface CheckboxCardProps extends Omit<React$1.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, "children">, SelectionCardOwnProps {
+    children?: React$1.ReactNode;
+}
+declare const CheckboxCard: React$1.ForwardRefExoticComponent<CheckboxCardProps & React$1.RefAttributes<HTMLButtonElement>>;
+interface SwitchCardProps extends Omit<React$1.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>, "children">, SelectionCardOwnProps {
+    children?: React$1.ReactNode;
+}
+declare const SwitchCard: React$1.ForwardRefExoticComponent<SwitchCardProps & React$1.RefAttributes<HTMLButtonElement>>;
+
 /**
  * Code — syntax-highlighted code surface with diff, line-emphasis, and
  * reveal animation modes. Designed for marketing heroes ("diff hero"),
@@ -797,6 +931,7 @@ type CodeLanguage = Language;
 type CodeReveal = "none" | "lines" | "typewriter" | "diff";
 type CodeTrigger = "mount" | "inView" | "manual";
 type CodeSpeed = "slow" | "normal" | "fast";
+type CodeSize = "xs" | "sm" | "md";
 /**
  * Step shape for scripted terminal / CLI sessions. Lives on `<Code>`
  * itself rather than a sibling `CodeSequence` so the theme bridge,
@@ -921,6 +1056,17 @@ interface CodeProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "childr
      * Overflowing content scrolls. Pair with `wrap` to break long lines
      * instead of horizontal scroll.
      */
+    /**
+     * Type-scale preset. `xs` (12px) for dense changelog cards and inline
+     * code in tables; `sm` (14px, default) for marketing heroes and most
+     * docs blocks; `md` (16px) for "this is the focal point" displays
+     * like AI-output demos and large screen-capture replacements.
+     *
+     * Composes with `maxLines` correctly because the container height
+     * uses `1lh` which inherits whatever line-height the size class
+     * produces — switching size resizes the container automatically.
+     */
+    size?: CodeSize;
     height?: number | string | "auto";
     /**
      * Cap the visible line count — the container is fixed at exactly
@@ -935,6 +1081,669 @@ interface CodeProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "childr
 }
 declare const Code: React$1.ForwardRefExoticComponent<CodeProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Message — the canonical "avatar + author + timestamp + body" row.
+ *
+ * THE primitive for any chat message, comment, post-reply, activity-log
+ * entry, or notification row that follows the people-and-text shape.
+ * Surfaced after three scaffolds (chat, comments, hero preview) all
+ * re-rolled the same flex layout inline — that was the signal.
+ *
+ * Slot-based composition for the avatar so consumers pass whatever
+ * Avatar variant fits their surface (sized, toned, image, fallback).
+ * Message doesn't pick an Avatar shape for you — it just hosts.
+ *
+ *   <Message
+ *     author="alice"
+ *     timestamp="11:24"
+ *     avatar={
+ *       <Avatar size="sm">
+ *         <AvatarFallback tone="violet">A</AvatarFallback>
+ *       </Avatar>
+ *     }
+ *   >
+ *     Post copy is in the doc.
+ *   </Message>
+ *
+ * For "your messages right-aligned" chat surfaces (iMessage / WhatsApp
+ * / your own DM threads), pass `align="end"` and the row + content
+ * mirror.
+ *
+ * Anti-patterns to avoid (caught from real scaffold use):
+ *
+ *   - Don't roll a custom "AuthorDot" inline — Avatar with
+ *     <AvatarFallback tone="..."> covers the colored-initials case
+ *     cleanly and stays themable.
+ *   - Don't use Message for non-people activity (system events,
+ *     log lines). Reach for Callout or a plain Row.
+ */
+interface MessageProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Display name of the message author. */
+    author: string;
+    /**
+     * Timestamp string ("11:24", "2 hours ago") OR any node for custom
+     * formatting (tooltip-wrapped time, link to permalink, etc).
+     */
+    timestamp?: React$1.ReactNode;
+    /**
+     * Avatar slot. Pass any `<Avatar>` composition. When omitted, the
+     * row renders without an avatar column — handy for grouped messages
+     * from the same author where only the first row shows the avatar.
+     */
+    avatar?: React$1.ReactNode;
+    /**
+     * Small chip(s) next to the author name. Use for "OP", "Bot",
+     * "Admin", or any role/state badge that belongs in the header
+     * rhythm rather than the body.
+     */
+    badge?: React$1.ReactNode;
+    /**
+     * Editing state — renders an "(edited)" hint next to the timestamp.
+     * Pass a string to customise the label (e.g. "(edited 2 minutes ago)").
+     */
+    edited?: boolean | string;
+    /**
+     * Pinned state — renders a small pin glyph at the top of the row.
+     * Surfaces "this is a sticky / pinned message" in Slack-style feeds.
+     */
+    pinned?: boolean;
+    /**
+     * End-of-header slot. Common use: a hover-revealed Row of small
+     * icon buttons (reply / react / pin / more). Pushed to the right
+     * with `ml-auto`.
+     */
+    actions?: React$1.ReactNode;
+    /**
+     * Reactions slot — renders below the body. Typically a Row of
+     * reaction chips (emoji + count). Hidden when no node is passed.
+     */
+    reactions?: React$1.ReactNode;
+    /**
+     * Thread / reply count — renders a "N replies" link affordance
+     * below the body. Click handler is the consumer's responsibility.
+     * Wire `onThreadClick` if you want the built-in button to fire.
+     */
+    threadCount?: number;
+    /** Fires when the built-in "N replies" affordance is clicked. */
+    onThreadClick?: () => void;
+    /**
+     * Visual alignment. `start` (default) puts the avatar on the left
+     * — the standard chat / comment shape. `end` mirrors the row so the
+     * avatar sits on the right and the content right-aligns — use for
+     * "your messages" in DM threads.
+     */
+    align?: "start" | "end";
+    /**
+     * Row rhythm. `default` is the canonical chat / channel-feed shape.
+     * `compact` tightens text sizes + gaps for dense side-panel use
+     * (Studio comments tab, activity feeds, notification rows where many
+     * rows stack vertically and the surface is narrow). Avatar size is
+     * still consumer-controlled — pair `density="compact"` with
+     * `Avatar size="xs"` for the tightest rhythm.
+     */
+    density?: "default" | "compact";
+    /**
+     * Body content (the message text). Accepts any node so consumers
+     * can embed rich content — Markdown-rendered prose, images,
+     * embedded cards, etc. Plain text is the common case.
+     */
+    children: React$1.ReactNode;
+}
+declare const Message: React$1.ForwardRefExoticComponent<MessageProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Shared types + presets for scripted component demos.
+ *
+ * Lives at the bottom of the demo primitive stack so the hook, the
+ * cursor, and any component that opts in (`<Code>`, `<Composer>`,
+ * `<DemoStage>`) all read from one definition of "what slow / normal /
+ * fast feels like" and one definition of "when do we start playing".
+ *
+ * If you ever want to retune the cadence of every demo on the marketing
+ * site at once, this is the file to edit.
+ */
+/**
+ * Animation feel. Maps onto a triple of timing values so authors can
+ * pick a vibe (slow / normal / fast) instead of hand-tuning ms.
+ * Components that need finer control can still override the resolved
+ * values per-instance.
+ */
+type DemoSpeed = "slow" | "normal" | "fast";
+/**
+ * What kicks the demo off:
+ *   - `mount`   plays immediately on first paint
+ *   - `inView`  waits for the container to cross the viewport threshold
+ *   - `manual`  driven by the `play` prop or imperative ref
+ */
+type DemoTrigger = "mount" | "inView" | "manual";
+/**
+ * Speed presets shared across every scripted-demo surface. Three
+ * unambiguously distinct feels: `slow` is "I am being shown", `normal`
+ * is "I am being told", `fast` is "I am being briefed".
+ *
+ *   - `tokenStagger`  per-character cadence for typing-style steps
+ *   - `lineStagger`   per-line cadence for reveal-style demos
+ *   - `preDelay`      pause after the trigger fires before the first tick
+ *   - `fadeMs`        default enter-transition duration for revealed parts
+ */
+declare const DEMO_SPEED_PRESETS: Record<DemoSpeed, {
+    tokenStagger: number;
+    lineStagger: number;
+    preDelay: number;
+    fadeMs: number;
+}>;
+
+/**
+ * Cancellable sleep + type helpers for scripted demos.
+ *
+ * The runner threads an `AbortSignal` through every step so a `stop()`
+ * call (or an unmount) can short-circuit long waits and typing loops
+ * cleanly. Consumers write `await sleep(ms, signal)` inside their
+ * interpret callback and the cancellation is automatic.
+ *
+ * Note: this throws DOMException("Aborted", "AbortError") on cancel.
+ * The runner's outer try/catch swallows that specific error and exits;
+ * any other rejection bubbles up so authoring bugs aren't silenced.
+ */
+/**
+ * Promisified setTimeout that resolves after `ms` milliseconds, or
+ * rejects with an AbortError if the signal fires first. Resolves
+ * immediately if `ms <= 0`.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Type `text` one character at a time, calling `onTick(partial)` for
+ * each prefix. Stagger between ticks defaults to 22ms (the `normal`
+ * speed preset's `tokenStagger`).
+ *
+ * `onTick` receives the cumulative typed text (not the new char), so
+ * consumers can do `setBuffer(prefix + partial)` without tracking state
+ * themselves. The final call fires with the complete text — there's no
+ * separate "done" callback.
+ */
+declare function typeText(text: string, onTick: (partial: string) => void, stagger?: number, signal?: AbortSignal): Promise<void>;
+
+/**
+ * useScriptedDemo — the shared step-machine hook behind every
+ * scripted-demo surface in gradeui (`<Code>`, `<Composer>`,
+ * `<DemoStage>`, anything else that wants the same play / stop / speed
+ * semantics).
+ *
+ * Generic over the Step type. Each consumer defines its own verbs
+ * (Code has `output`, Composer has `mention`, DemoStage has `reveal`)
+ * and passes an `interpret(step, ctx)` callback that executes one
+ * step. The hook owns: sequencing, cancellation, trigger detection
+ * (mount / inView / manual), loop, pre-delay, completion signal, and
+ * the imperative play() / stop() API.
+ *
+ * Reduced motion: this hook is the declarative-motion layer's accessibility
+ * boundary. When the OS reports `prefers-reduced-motion: reduce` OR the
+ * global `data-motion="off"` toggle is set (both via `useReducedMotion`),
+ * the runner settles on the FINAL frame instead of animating — zeroed
+ * timings run every step instantly and the sequence never loops, so the
+ * end state shows and holds. That keeps lib/demo honouring the same motion
+ * control as ThreeScene and the CSS reset; without it, a screen built with
+ * <Code> would keep typing under reduced motion and would not be accessible.
+ *
+ * Authoring guide for `interpret`:
+ *   - `await sleep(ms, ctx.signal)` for any pause so stop() can short
+ *     a long wait cleanly.
+ *   - `await typeText(text, onTick, stagger, ctx.signal)` for typing
+ *     loops, again so stop() interrupts mid-character. A non-positive
+ *     stagger (what the reduced-motion preset supplies) emits the whole
+ *     string in one tick, so the final state shows with no animation.
+ *   - Read `ctx.speed` to grab the resolved DEMO_SPEED_PRESETS entry
+ *     when a step doesn't pin its own cadence.
+ *   - Throw nothing on cancel — the helpers do it for you. Anything
+ *     else thrown is treated as a real bug and bubbles to the console.
+ */
+interface ScriptedDemoContext {
+    /** Resolved speed preset for the current run. Zeroed under reduced motion. */
+    speed: (typeof DEMO_SPEED_PRESETS)[DemoSpeed];
+    /** AbortSignal that fires on stop() / unmount / steps change. */
+    signal: AbortSignal;
+    /** Live cancellation check for code paths that can't take a signal. */
+    cancelled: () => boolean;
+    /** True when the run is in reduced-motion mode (settling, not animating).
+     *  Most interpreters don't need this — zeroed timings handle it — but a
+     *  step that does something non-timing-based (confetti, sound) can skip it. */
+    reduced: boolean;
+}
+interface UseScriptedDemoOptions<TStep> {
+    /** The steps to run. Undefined or empty means "no script". */
+    steps?: TStep[];
+    /**
+     * Per-step interpreter. Receives one step + a context with timing
+     * helpers, runs whatever the step means, and returns when done.
+     * Synchronous or async — the runner awaits either.
+     */
+    interpret: (step: TStep, ctx: ScriptedDemoContext) => Promise<void> | void;
+    /** Animation feel. Defaults to `normal`. */
+    speed?: DemoSpeed;
+    /** What kicks the script off. Defaults to `mount`. */
+    trigger?: DemoTrigger;
+    /** For `trigger="manual"` — flip true to play. */
+    play?: boolean;
+    /** Loop the sequence forever after completion. Pause length controlled by `loopDelay`. */
+    loop?: boolean;
+    /**
+     * Milliseconds to pause between loop cycles. Only applies when
+     * `loop` is true. Defaults to 2000. Marketing surfaces that want
+     * the demo to breathe between repeats bump this to 4000-6000; tight
+     * inline demos drop it to 800.
+     */
+    loopDelay?: number;
+    /** Container ref for inView detection. Required when `trigger="inView"`. */
+    containerRef?: React$1.RefObject<HTMLElement | null>;
+    /**
+     * Fires when one loop iteration completes (or the whole run, when
+     * `loop` is false). Consumers can use this to reset their buffer or
+     * fire a parent callback.
+     */
+    onComplete?: () => void;
+    /**
+     * Fires before each loop iteration starts (after the 2s pause).
+     * Use to reset per-iteration state in the consumer.
+     */
+    onLoopReset?: () => void;
+}
+interface ScriptedDemoState {
+    /** True while the runner is actively walking steps. */
+    isPlaying: boolean;
+    /** True after the last step has run (and stays true until reset). */
+    isComplete: boolean;
+    /** 0-indexed pointer to the currently executing step, or -1 idle. */
+    currentIndex: number;
+    /** Imperative trigger. Mostly for `trigger="manual"` ref handles. */
+    play: () => void;
+    /** Cancel the in-flight script. Idempotent. */
+    stop: () => void;
+    /**
+     * One-shot replay. Cancels any in-flight run, then re-plays from
+     * step 0. Pass a delay in ms to schedule the replay (useful for
+     * "play, finish, breathe, play once more" cadences without the
+     * commitment of `loop`).
+     */
+    restart: (delayMs?: number) => void;
+}
+declare function useScriptedDemo<TStep>(opts: UseScriptedDemoOptions<TStep>): ScriptedDemoState;
+
+/**
+ * BlinkingCursor — the shared caret used by every scripted-demo
+ * surface in gradeui. Styled via CSS variables so each host (Code's
+ * terminal, Composer's inline caret, future surfaces) can tweak
+ * dimensions and colour without forking the component.
+ *
+ * Tokens read from the cascade:
+ *   --gds-demo-cursor-color   defaults to currentColor
+ *   --gds-demo-cursor-width   defaults to 0.55ch (a hair narrower than
+ *                             a monospace char so it reads as a caret
+ *                             rather than a block)
+ *   --gds-demo-cursor-height  defaults to 1.1em
+ *
+ * The animation lives in `styles/globals.css` as `.gds-demo-cursor`
+ * (alongside the other demo primitives). Keeping it in CSS rather
+ * than motion / framer keeps the cursor available in environments
+ * that disable JS animation but still render the page.
+ */
+interface BlinkingCursorProps extends Omit<React$1.HTMLAttributes<HTMLSpanElement>, "children"> {
+    /**
+     * Visual variant. `inline` (default) is for caret-in-text demos
+     * (Code, Composer). `block` is for terminal-style square cursors
+     * that fill a character cell.
+     */
+    variant?: "inline" | "block";
+}
+declare const BlinkingCursor: React$1.ForwardRefExoticComponent<BlinkingCursorProps & React$1.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * DemoStage + Reveal — staged appearance for whole-interface demos.
+ *
+ * Drop `<Reveal id="hero">…</Reveal>` around any subtree that should
+ * appear on cue. Wrap a region in `<DemoStage steps={…}>` and the
+ * script drives which targets become visible, in what order, with
+ * what cadence. Same speed / trigger / loop / play semantics as
+ * `<Code>` and `<Composer>`.
+ *
+ * Why a context-based pattern instead of one-component-per-region:
+ *   - Authoring stays declarative — the script reads as a storyboard,
+ *     not as a stack of imperative ref calls.
+ *   - Reveals can live deep in a subtree without prop-drilling.
+ *   - The same `<Reveal>` works whether or not a parent stage exists
+ *     (it just renders visible if there's no context, so the same
+ *     markup ships to production without the demo wrapper).
+ *
+ * Reduced motion: if the user has `prefers-reduced-motion`, every
+ * Reveal renders immediately at its destination state — the stage's
+ * script still walks, but the visual transitions are no-ops.
+ */
+type RevealStep = {
+    type: "reveal";
+    target: string;
+} | {
+    type: "reveal-all";
+} | {
+    type: "hide";
+    target: string;
+} | {
+    type: "wait";
+    ms: number;
+} | {
+    type: "reset";
+};
+type RevealAnimation = "fade" | "fade-up" | "fade-down" | "fade-left" | "fade-right" | "scale" | "none";
+interface DemoStageProps {
+    /** Steps that drive which Reveals are visible at what time. */
+    steps?: RevealStep[];
+    /** Speed preset. Same vocabulary as Code / Composer. */
+    speed?: DemoSpeed;
+    /** When the stage starts running. Defaults to `mount`. */
+    trigger?: DemoTrigger;
+    /** For trigger="manual" — flip true to play. */
+    play?: boolean;
+    /** Loop the script forever. */
+    loop?: boolean;
+    /** Default enter animation for child Reveals that don't override. */
+    defaultAnimation?: RevealAnimation;
+    /**
+     * Render content visible by default (every target shown) when the
+     * stage has no steps. Useful for sharing the same JSX between live
+     * production use and demo playback.
+     */
+    visibleWhenIdle?: boolean;
+    className?: string;
+    children: React$1.ReactNode;
+}
+declare function DemoStage({ steps, speed, trigger, play, loop, defaultAnimation, visibleWhenIdle, className, children, }: DemoStageProps): React$1.JSX.Element;
+interface RevealProps {
+    /** Stage target id. The matching `{ type: "reveal", target: id }` step shows this. */
+    id: string;
+    /** Enter animation. Falls back to the parent stage's `defaultAnimation`. */
+    animation?: RevealAnimation;
+    /** Override transition duration (ms). Defaults to the stage speed's fadeMs. */
+    durationMs?: number;
+    /**
+     * When true and there's no parent DemoStage, render hidden anyway.
+     * Default false — naked usage renders visible so production markup
+     * matches demo markup.
+     */
+    hideOutsideStage?: boolean;
+    /**
+     * Fires when this Reveal transitions from hidden to visible. Use to
+     * kick off a nested scripted demo (Composer.restart(), Code.play(),
+     * etc) at the moment the user actually sees the surface. Without
+     * this hook, nested demos with `trigger="mount"` would run while
+     * still hidden and the user would miss the animation entirely.
+     */
+    onReveal?: () => void;
+    /**
+     * Fires when this Reveal transitions from visible to hidden (e.g.
+     * because the stage script ran a `hide` step or looped via `reset`).
+     * Use to pause/reset nested state.
+     */
+    onHide?: () => void;
+    className?: string;
+    children: React$1.ReactNode;
+}
+declare function Reveal({ id, animation, durationMs, hideOutsideStage, onReveal, onHide, className, children, }: RevealProps): React$1.JSX.Element;
+
+/**
+ * Composer — the generic text composition surface for the design system.
+ *
+ * The answer wherever a user is composing a message: AI chat input,
+ * comment thread reply, post-body editor, future copilot panels.
+ * Replaces the textarea-with-buttons pattern that hosts kept rolling
+ * by hand.
+ *
+ * Built on Lexical (Meta's React-first editor framework) so it can do:
+ *   - rich text formatting (B / I / U / S / code, headings, blockquote,
+ *     pullquote, lists)
+ *   - mentions and slash commands via lexical-beautiful-mentions, with
+ *     a typeahead popover and theme-able tokens
+ *   - image attachments (paperclip + clipboard paste) when opted in
+ *   - scripted demo playback for marketing surfaces (types text, opens
+ *     mention popovers, applies formatting, all via the same step
+ *     vocabulary as <Code>)
+ *
+ * Slot-based composition for the action row: hosts that need custom
+ * affordances (template picker, voice button, attach-document) pass
+ * `leftActions` / `rightActions`. Default Send / Stop / paperclip
+ * render only when the host hasn't replaced the slot.
+ *
+ * Hosts that want the canned "chat composer with paperclip + send"
+ * preset should reach for `<AIChatComposer>` instead, which configures
+ * this Composer with the right slots wired up.
+ *
+ * Scripted demos: same `speed` / `trigger` / `play` / `loop` vocabulary
+ * as `<Code>`, sharing the underlying `useScriptedDemo` hook from
+ * `lib/demo/`. The Composer adds its own verbs (`mention`, `format`,
+ * `select`, `submit`) on top of the universal `type` / `wait` / `clear`.
+ */
+type ComposerFormat = "bold" | "italic" | "underline" | "strikethrough" | "code" | "h1" | "h2" | "h3" | "blockquote" | "pullquote" | "ul" | "ol";
+interface ComposerMentionItem {
+    id: string;
+    /** Display value (without the trigger char). */
+    value: string;
+    /** Optional secondary label shown in the suggester. */
+    label?: string;
+    /** Avatar URL or initials for the suggester row. */
+    avatar?: string;
+    /** Arbitrary payload the host can attach to the mention. */
+    data?: Record<string, unknown>;
+}
+interface ComposerTriggerConfig {
+    /** The trigger character, eg. "@" or "/". */
+    char: string;
+    /**
+     * Items to populate the suggester. Either a static array or a
+     * resolver function (sync or async) that receives the typed query.
+     * The plugin filters automatically when items is an array.
+     */
+    items: ComposerMentionItem[] | ((query: string) => ComposerMentionItem[] | Promise<ComposerMentionItem[]>);
+    /**
+     * Whether to strip the trigger char on insert. Defaults: keep for
+     * "@" (mentions read as "@alice"), strip for "/" (commands read as
+     * "Insert image" not "/insert-image").
+     */
+    stripTrigger?: boolean;
+}
+interface ComposerAttachmentConfig {
+    /** Master enable. Set true on the prop to use defaults, or pass a config object. */
+    enabled?: boolean;
+    /** HTML accept attribute on the file input. Default "image/*". */
+    accept?: string;
+    /** Max number of attachments. Default 10. */
+    maxItems?: number;
+    /** Allow multiple selection in the file picker. Default true. */
+    multiple?: boolean;
+}
+interface ComposerAttachment {
+    id: string;
+    file: File;
+    /** Object URL owned by the composer. Hosts must NOT revoke it. */
+    previewUrl: string;
+    name: string;
+}
+interface ComposerContent {
+    /** Plain text representation of the editor contents (whitespace preserved). */
+    text: string;
+    /** Lexical editor state serialised to JSON (for round-trip persistence). */
+    json: string;
+    /** Resolved mention tokens in document order. */
+    mentions: Array<{
+        trigger: string;
+        value: string;
+        data?: Record<string, unknown>;
+    }>;
+}
+interface ComposerHandle {
+    /** Run a demo script imperatively (vs. via `steps` + `trigger="manual"`). */
+    play: (steps: ComposerStep[]) => void;
+    /** Cancel an in-flight demo. Idempotent. */
+    stop: () => void;
+    /**
+     * One-shot replay of the configured `steps`. Cancels any in-flight
+     * run, clears the editor, replays from step 0. Pass a delay (ms) to
+     * schedule the replay (useful for chaining demos). Requires `steps`
+     * to be configured.
+     */
+    restart: (delayMs?: number) => void;
+    /** Move focus into the editor. */
+    focus: () => void;
+    /** Wipe the editor. */
+    clear: () => void;
+    /** Insert plain text at the current selection. */
+    insert: (text: string) => void;
+    /** Snapshot the current content + mentions. */
+    getContent: () => ComposerContent;
+    /** Direct access to the underlying Lexical editor (escape hatch). */
+    getEditor: () => LexicalEditor | null;
+}
+/**
+ * Demo step vocabulary for Composer scripts. Shares `type` / `wait` /
+ * `clear` with the universal `lib/demo` verbs; adds composer-specific
+ * `mention`, `format`, `select`, `newline`, `submit` on top.
+ */
+type ComposerStep = {
+    type: "type";
+    text: string;
+    speed?: DemoSpeed;
+} | {
+    type: "wait";
+    ms: number;
+} | {
+    type: "clear";
+} | {
+    type: "newline";
+} | {
+    type: "submit";
+} | {
+    type: "mention";
+    /** Trigger char (must match a registered ComposerTriggerConfig.char). */
+    trigger: string;
+    /** Value to insert (without the trigger). Looks up the matching item by `value`. */
+    value: string;
+    /** Optional pre-typed query — the demo types this after the trigger char before "selecting" the value, to show the typeahead in action. */
+    query?: string;
+} | {
+    type: "format";
+    format: ComposerFormat;
+} | {
+    type: "select";
+    /** Substring to find and select. First match wins. */
+    text: string;
+};
+interface ComposerProps {
+    /** Placeholder copy shown when empty. */
+    placeholder?: string;
+    /** Initial plain text content. For richer initial state, use `initialJson`. */
+    initialText?: string;
+    /** Initial Lexical state JSON (from a previous `onSubmit` round-trip). */
+    initialJson?: string;
+    /**
+     * Available formats. Pass false to disable rich text entirely
+     * (plain text mode, half the bundle weight, no toolbar). Default
+     * enables a sensible set for most chat / comment surfaces.
+     */
+    formats?: ComposerFormat[] | false;
+    /**
+     * Render the formatting toolbar. Default false because most uses
+     * are short-form. Set true (or "top") to show the toolbar above the
+     * editor. "floating" is planned; not yet implemented.
+     */
+    toolbar?: boolean | "top";
+    /**
+     * Mention / slash command configs. Each entry registers one trigger
+     * char and its items. Pass `[{ char: "@", items: people }, { char: "/", items: commands }]`
+     * for the common chat-app setup.
+     */
+    triggers?: ComposerTriggerConfig[];
+    /**
+     * Image attachments (paperclip + clipboard paste). Pass true for
+     * defaults, an object to customise, or omit/false to skip the
+     * attachment plumbing entirely.
+     */
+    attachments?: boolean | ComposerAttachmentConfig;
+    /** Fires when the user submits (Enter, click Send, or scripted `submit` step). */
+    onSubmit?: (content: ComposerContent, attachments?: ComposerAttachment[]) => void;
+    /**
+     * Fires on every editor change with the current plain text. Use for
+     * length validation, controlled-value bridges (eg. AIChatComposer
+     * forwarding to a host's `value`/`onChange` pair), or live preview
+     * surfaces. Cheap, called frequently; debounce if you need the
+     * Lexical state JSON (use `getContent()` via ref instead).
+     */
+    onChange?: (text: string) => void;
+    /**
+     * Loading state — disables the editor + paperclip and swaps the
+     * default Send button for Stop. Has no effect when `rightActions`
+     * overrides the default Send.
+     */
+    isLoading?: boolean;
+    /** Stop handler — required for Stop to be active when loading. */
+    onStop?: () => void;
+    /** Hard character cap. */
+    maxLength?: number;
+    /** Auto-focus the editor on mount. Default false. */
+    autoFocus?: boolean;
+    /** Whether Enter submits. Default true (Shift-Enter still inserts a newline). */
+    submitOnEnter?: boolean;
+    /**
+     * Custom content for the left action slot. Replaces the default
+     * paperclip button when `attachments` is enabled.
+     */
+    leftActions?: React$1.ReactNode;
+    /**
+     * Custom content for the right action slot. Replaces the default
+     * Send / Stop button. Use the `useComposer()` hook inside to access
+     * imperative methods.
+     */
+    rightActions?: React$1.ReactNode;
+    /** Hide the default Send button without replacing it. */
+    hideSend?: boolean;
+    /** Scripted demo steps. */
+    steps?: ComposerStep[];
+    /** What kicks the script off. Defaults to "mount". */
+    trigger?: DemoTrigger;
+    /** For trigger="manual" — flip true to play. */
+    play?: boolean;
+    /** Animation feel. */
+    speed?: DemoSpeed;
+    /** Loop the script forever. */
+    loop?: boolean;
+    /**
+     * Pause between loop iterations (ms). Defaults to 2000. Marketing
+     * heroes that want the demo to breathe between repeats bump this
+     * higher; tight inline demos drop it.
+     */
+    loopDelay?: number;
+    /**
+     * Fires once per loop cycle, AFTER the loopDelay pause and BEFORE
+     * the script replays. Use to reset parent state that the script
+     * mutated via onSubmit (e.g., wipe a messages list back to its
+     * seed before the demo types into it again). The editor is cleared
+     * automatically — you only need this hook if state outside the
+     * Composer needs to reset too.
+     */
+    onLoopReset?: () => void;
+    /**
+     * Bare mode — strip the card chrome (border / bg / rounding). Use
+     * when embedding inside an existing card or column layout.
+     */
+    bare?: boolean;
+    /**
+     * Read-only mode — disables editing AND focusability. Programmatic
+     * updates (including scripted demo playback) still work. Use for
+     * marketing surfaces that render a Composer purely for show, so the
+     * scripted typing doesn't steal focus from other inputs on the page.
+     * Hides the default Send / paperclip action row.
+     */
+    readOnly?: boolean;
+    className?: string;
+}
+declare const Composer: React$1.ForwardRefExoticComponent<ComposerProps & React$1.RefAttributes<ComposerHandle>>;
+declare const ComposerReply: React$1.ForwardRefExoticComponent<ComposerProps & React$1.RefAttributes<ComposerHandle>>;
+
 /**
  * DatePicker + DateRangePicker
  *
@@ -1033,6 +1842,15 @@ declare const DialogDescription: React$1.ForwardRefExoticComponent<Omit<DialogPr
 
 declare const DropdownMenu: React$1.FC<DropdownMenuPrimitive.DropdownMenuProps>;
 declare const DropdownMenuTrigger: React$1.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Menu density. Set `size` on `<DropdownMenuContent>` (or
+ * `<DropdownMenuSubContent>`) and every item inside — Item, Checkbox,
+ * Radio, SubTrigger, Label — picks up matching padding / text-size via
+ * context (which flows through the Radix portal). Mirrors Select so a
+ * compact trigger can have an equally compact menu. `xs` is the
+ * tool-panel density (the Studio inspector).
+ */
+type DropdownMenuSize = "default" | "sm" | "xs";
 declare const DropdownMenuGroup: React$1.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuGroupProps & React$1.RefAttributes<HTMLDivElement>>;
 declare const DropdownMenuPortal: React$1.FC<DropdownMenuPrimitive.DropdownMenuPortalProps>;
 declare const DropdownMenuSub: React$1.FC<DropdownMenuPrimitive.DropdownMenuSubProps>;
@@ -1043,6 +1861,8 @@ declare const DropdownMenuSubTrigger: React$1.ForwardRefExoticComponent<Omit<Dro
 interface DropdownMenuSubContentProps extends React$1.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent> {
     /** What the submenu surface is *made of*. See dropdown-menu.md. */
     surface?: Surface;
+    /** Menu density — cascades to items via context. */
+    size?: DropdownMenuSize;
 }
 declare const DropdownMenuSubContent: React$1.ForwardRefExoticComponent<DropdownMenuSubContentProps & React$1.RefAttributes<HTMLDivElement>>;
 interface DropdownMenuContentProps extends React$1.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content> {
@@ -1052,6 +1872,8 @@ interface DropdownMenuContentProps extends React$1.ComponentPropsWithoutRef<type
      * floating over rich canvases. See dropdown-menu.md.
      */
     surface?: Surface;
+    /** Menu density — cascades to items via context. */
+    size?: DropdownMenuSize;
 }
 declare const DropdownMenuContent: React$1.ForwardRefExoticComponent<DropdownMenuContentProps & React$1.RefAttributes<HTMLDivElement>>;
 declare const DropdownMenuItem: React$1.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & {
@@ -1081,15 +1903,26 @@ declare const DropdownMenuShortcut: {
  * rationale.
  */
 declare const inputVariants: (props?: ({
-    size?: "default" | "sm" | null | undefined;
+    size?: "default" | "sm" | "xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type InputSize = NonNullable<VariantProps<typeof inputVariants>["size"]>;
 type InputProps = Omit<React$1.ComponentProps<"input">, "size"> & {
     size?: InputSize;
+    /** Adornment rendered inside the field on the leading edge — an icon,
+     *  a unit, a prefix. Non-interactive by default (clicks pass through
+     *  to focus the input); pass an element with its own pointer-events
+     *  if you need it clickable. */
+    startSlot?: React$1.ReactNode;
+    /** Adornment rendered inside the field on the trailing edge — a unit
+     *  ("px"), a clear button, a stepper. Same pointer rules as
+     *  `startSlot`. */
+    endSlot?: React$1.ReactNode;
 };
 declare const Input: React$1.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React$1.RefAttributes<HTMLInputElement>>;
 
-declare const Label: React$1.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React$1.RefAttributes<HTMLLabelElement>, "ref"> & VariantProps<(props?: class_variance_authority_types.ClassProp | undefined) => string> & React$1.RefAttributes<HTMLLabelElement>>;
+declare const Label: React$1.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React$1.RefAttributes<HTMLLabelElement>, "ref"> & VariantProps<(props?: ({
+    size?: "default" | "sm" | "xs" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLLabelElement>>;
 
 declare const Popover: React$1.FC<PopoverPrimitive.PopoverProps>;
 declare const PopoverTrigger: React$1.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
@@ -1232,7 +2065,7 @@ declare const RadioGroupItem: React$1.ForwardRefExoticComponent<Omit<RadioGroupP
  *   </ResizablePanelGroup>
  */
 declare const ResizablePanelGroup: ({ className, ...props }: React$1.ComponentProps<typeof ResizablePrimitive.PanelGroup>) => React$1.JSX.Element;
-declare const ResizablePanel: React$1.ForwardRefExoticComponent<Omit<React$1.HTMLAttributes<HTMLDivElement | HTMLElement | HTMLObjectElement | HTMLSelectElement | HTMLTextAreaElement | HTMLMapElement | HTMLTitleElement | HTMLButtonElement | HTMLLinkElement | HTMLLabelElement | HTMLStyleElement | HTMLSourceElement | HTMLHtmlElement | HTMLTableColElement | HTMLVideoElement | HTMLAudioElement | HTMLEmbedElement | HTMLProgressElement | HTMLHRElement | HTMLTableElement | HTMLAnchorElement | HTMLFormElement | HTMLHeadingElement | HTMLImageElement | HTMLInputElement | HTMLLIElement | HTMLOListElement | HTMLParagraphElement | HTMLSpanElement | HTMLUListElement | HTMLAreaElement | HTMLBaseElement | HTMLQuoteElement | HTMLBodyElement | HTMLBRElement | HTMLCanvasElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLFieldSetElement | HTMLHeadElement | HTMLIFrameElement | HTMLLegendElement | HTMLMetaElement | HTMLMeterElement | HTMLOptGroupElement | HTMLOptionElement | HTMLOutputElement | HTMLPreElement | HTMLSlotElement | HTMLScriptElement | HTMLTemplateElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTimeElement | HTMLTableRowElement | HTMLTrackElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
+declare const ResizablePanel: React$1.ForwardRefExoticComponent<Omit<React$1.HTMLAttributes<HTMLHeadElement | HTMLElement | HTMLLinkElement | HTMLDivElement | HTMLObjectElement | HTMLAnchorElement | HTMLAreaElement | HTMLAudioElement | HTMLBaseElement | HTMLQuoteElement | HTMLBodyElement | HTMLBRElement | HTMLButtonElement | HTMLCanvasElement | HTMLTableColElement | HTMLDataElement | HTMLDataListElement | HTMLModElement | HTMLDetailsElement | HTMLDialogElement | HTMLDListElement | HTMLEmbedElement | HTMLFieldSetElement | HTMLFormElement | HTMLHeadingElement | HTMLHRElement | HTMLHtmlElement | HTMLIFrameElement | HTMLImageElement | HTMLInputElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement | HTMLMapElement | HTMLMetaElement | HTMLMeterElement | HTMLOListElement | HTMLOptGroupElement | HTMLOptionElement | HTMLOutputElement | HTMLParagraphElement | HTMLPreElement | HTMLProgressElement | HTMLScriptElement | HTMLSelectElement | HTMLSlotElement | HTMLSourceElement | HTMLSpanElement | HTMLStyleElement | HTMLTableElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTemplateElement | HTMLTextAreaElement | HTMLTimeElement | HTMLTitleElement | HTMLTableRowElement | HTMLTrackElement | HTMLUListElement | HTMLVideoElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
     className?: string | undefined;
     collapsedSize?: number | undefined;
     collapsible?: boolean | undefined;
@@ -1271,9 +2104,9 @@ declare const ResizableHandle: ({ withHandle, className, ...props }: React$1.Com
  * etc.) and is a separate primitive.
  */
 declare const rowVariants: (props?: ({
-    gap?: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
-    justify?: "start" | "center" | "between" | "end" | "around" | "evenly" | null | undefined;
+    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "center" | "start" | "between" | "end" | "around" | "evenly" | null | undefined;
     wrap?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface RowProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof rowVariants> {
@@ -1307,8 +2140,8 @@ declare const Row: React$1.ForwardRefExoticComponent<RowProps & React$1.RefAttri
  */
 declare const gridVariants: (props?: ({
     cols?: "1" | "2" | "3" | "4" | "5" | "6" | "12" | null | undefined;
-    gap?: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | null | undefined;
+    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface GridProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof gridVariants> {
     /** When true, render as the single child element via Radix Slot — lets
@@ -1340,10 +2173,10 @@ declare const Grid: React$1.ForwardRefExoticComponent<GridProps & React$1.RefAtt
  * case. Flex is the escape hatch, not the default.
  */
 declare const flexVariants: (props?: ({
-    direction?: "row" | "col" | "row-reverse" | "col-reverse" | null | undefined;
-    gap?: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
-    justify?: "start" | "center" | "between" | "end" | "around" | "evenly" | null | undefined;
+    direction?: "col" | "row" | "row-reverse" | "col-reverse" | null | undefined;
+    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "center" | "start" | "between" | "end" | "around" | "evenly" | null | undefined;
     wrap?: "wrap" | "nowrap" | "wrap-reverse" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface FlexProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof flexVariants> {
@@ -1360,6 +2193,15 @@ declare const ScrollBar: React$1.ForwardRefExoticComponent<Omit<ScrollAreaPrimit
 declare const Select: React$1.FC<SelectPrimitive.SelectProps>;
 declare const SelectGroup: React$1.ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectValue: React$1.ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & React$1.RefAttributes<HTMLSpanElement>>;
+/**
+ * Menu density. Set `size` on `<SelectContent>` and every `<SelectItem>`
+ * inside it picks up matching padding / text-size / check-indicator
+ * sizing via context — so a compact trigger (`size="xs"`) can have an
+ * equally compact dropdown without per-item overrides. React context
+ * flows through the Radix portal (it follows the React tree, not the
+ * DOM), so items styled this way work even though the menu is portaled.
+ */
+type SelectMenuSize = "default" | "sm" | "xs";
 /**
  * Select trigger variants — `size` lets dense surfaces (the
  * Studio inspector, settings sheets) reach for a compact `sm`
@@ -1368,7 +2210,7 @@ declare const SelectValue: React$1.ForwardRefExoticComponent<SelectPrimitive.Sel
  * existing call site.
  */
 declare const selectTriggerVariants: (props?: ({
-    size?: "default" | "sm" | null | undefined;
+    size?: "default" | "sm" | "xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type SelectTriggerSize = NonNullable<VariantProps<typeof selectTriggerVariants>["size"]>;
 declare const SelectTrigger: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectTriggerProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & {
@@ -1376,7 +2218,9 @@ declare const SelectTrigger: React$1.ForwardRefExoticComponent<Omit<SelectPrimit
 } & React$1.RefAttributes<HTMLButtonElement>>;
 declare const SelectScrollUpButton: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollUpButtonProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectScrollDownButton: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectScrollDownButtonProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
-declare const SelectContent: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const SelectContent: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & {
+    size?: SelectMenuSize;
+} & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectLabel: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectLabelProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectItem: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectSeparator: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectSeparatorProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
@@ -1389,7 +2233,7 @@ declare const SheetClose: React$1.ForwardRefExoticComponent<DialogPrimitive.Dial
 declare const SheetPortal: React$1.FC<DialogPrimitive.DialogPortalProps>;
 declare const SheetOverlay: React$1.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogOverlayProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 declare const sheetVariants: (props?: ({
-    side?: "top" | "right" | "bottom" | "left" | null | undefined;
+    side?: "bottom" | "top" | "right" | "left" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface SheetContentProps extends React$1.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants> {
     /**
@@ -1527,9 +2371,9 @@ declare const Sortable: SortableRootComponent;
  * for a centred narrow column (auth cards, marketing copy).
  */
 declare const stackVariants: (props?: ({
-    gap?: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl" | null | undefined;
-    align?: "start" | "center" | "end" | "stretch" | null | undefined;
-    justify?: "start" | "center" | "between" | "end" | "around" | "evenly" | null | undefined;
+    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    align?: "center" | "start" | "end" | "stretch" | null | undefined;
+    justify?: "center" | "start" | "between" | "end" | "around" | "evenly" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface StackProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof stackVariants> {
     /** When true, render as the single child element via Radix Slot — lets
@@ -1656,15 +2500,27 @@ interface TabsTriggerProps extends React$1.ComponentPropsWithoutRef<typeof TabsP
 declare const TabsTrigger: React$1.ForwardRefExoticComponent<TabsTriggerProps & React$1.RefAttributes<HTMLButtonElement>>;
 declare const TabsContent: React$1.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 
-declare const Textarea: React$1.ForwardRefExoticComponent<Omit<React$1.DetailedHTMLProps<React$1.TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, "ref"> & React$1.RefAttributes<HTMLTextAreaElement>>;
+/**
+ * Textarea variants — `size` mirrors Input so the whole form-control
+ * family scales together. Default keeps the existing min-h-[80px] /
+ * px-3 / text-sm; `sm` and `xs` are for dense tool panels.
+ */
+declare const textareaVariants: (props?: ({
+    size?: "default" | "sm" | "xs" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type TextareaSize = NonNullable<VariantProps<typeof textareaVariants>["size"]>;
+type TextareaProps = Omit<React$1.ComponentProps<"textarea">, "size"> & {
+    size?: TextareaSize;
+};
+declare const Textarea: React$1.ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & React$1.RefAttributes<HTMLTextAreaElement>>;
 
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | null | undefined;
+    size?: "default" | "sm" | "lg" | "xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const Toggle: React$1.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | null | undefined;
+    size?: "default" | "sm" | "lg" | "xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLButtonElement>>;
 
 declare const TooltipProvider: React$1.FC<TooltipPrimitive.TooltipProviderProps>;
@@ -1749,7 +2605,7 @@ declare const ToggleGroupItem: React$1.ForwardRefExoticComponent<Omit<ToggleGrou
  * persistent footer toolbars on mobile-style layouts.
  */
 declare const toolbarVariants: (props?: ({
-    position?: "top" | "bottom" | "inline" | null | undefined;
+    position?: "bottom" | "top" | "inline" | null | undefined;
     variant?: "default" | "transparent" | "subtle" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
     sticky?: boolean | null | undefined;
@@ -1993,6 +2849,60 @@ declare const Map: React$1.ForwardRefExoticComponent<MapProps & React$1.RefAttri
 
 declare const MapMarker: React$1.NamedExoticComponent<MapMarkerProps>;
 
+/**
+ * lib/motion — the global motion control for gradeui.
+ *
+ * One choke point for "should this animate?". Every animated component
+ * (ThreeScene, RivePlayer, VideoPlayer, aura surfaces) asks
+ * `useReducedMotion()`, so flipping motion off in one place stills them all.
+ *
+ * Two independent inputs, ORed together (reduce-only by design — the toggle
+ * can ADD restriction but never override a user's OS preference to force
+ * motion ON):
+ *
+ *   1. the OS `prefers-reduced-motion: reduce` media query, and
+ *   2. a `data-motion="off"` attribute on the document root (`<html>`),
+ *      the manual toggle.
+ *
+ * The attribute is the same mechanism the renderer's `data-fidelity` flag
+ * uses: stamp it on `<html>` and CSS + components react. Inside Studio's
+ * Fast Frame / embed / share iframes it is driven over postMessage
+ * (`grade:set-motion`), so the toggle reaches into the sandbox where the
+ * ThreeScene surfaces actually run. A matching `[data-motion="off"]` CSS
+ * reset in `styles/globals.css` covers pure-CSS animation/transition.
+ *
+ * Sibling to lib/demo (the scripted-reveal spine).
+ */
+/** The attribute stamped on `<html>` to force motion off. */
+declare const MOTION_ATTR = "data-motion";
+/**
+ * Returns `true` when motion should be suppressed — either the OS reports
+ * `prefers-reduced-motion: reduce`, or the global `data-motion="off"` toggle
+ * is set on `<html>`. Stays live: re-reads on media-query change and on the
+ * attribute mutating.
+ *
+ * SSR-safe — defaults to `false` (motion allowed) on the server and
+ * rehydrates in an effect, so it never causes a hydration mismatch.
+ */
+declare function useReducedMotion(): boolean;
+/**
+ * @deprecated Prefer {@link useReducedMotion}. Kept for back-compat with the
+ * components that import it from `media-surface`; it now also folds in the
+ * global `data-motion="off"` toggle, not just the OS query.
+ */
+declare const usePrefersReducedMotion: typeof useReducedMotion;
+/**
+ * Imperatively set the global motion toggle on `<html>`.
+ *
+ *   setMotion(false) → stamps `data-motion="off"` (animation suppressed)
+ *   setMotion(true)  → removes the attribute (default: respect the OS only)
+ *
+ * Reduce-only: turning motion "on" never forces animation for a viewer whose
+ * OS asks for reduced motion — `useReducedMotion()` still honours the query.
+ * No-op on the server.
+ */
+declare function setMotion(enabled: boolean): void;
+
 /**
  * MediaSurface — the shared shell used by VideoPlayer, RivePlayer, ThreeScene
  * AND the canonical "media slot" primitive for still images, posters, album
@@ -2030,7 +2940,7 @@ declare const MapMarker: React$1.NamedExoticComponent<MapMarkerProps>;
  * the right semantics.
  */
 
-type MediaAspect = "video" | "square" | "portrait" | "wide" | "auto";
+type MediaAspect = "video" | "standard" | "square" | "portrait" | "wide" | "auto";
 type MediaRadius = "none" | "sm" | "md" | "lg" | "xl";
 /**
  * What kind of media is this slot intended for? Drives three things:
@@ -2288,8 +3198,6 @@ interface BaseMediaProps {
     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.
@@ -2333,6 +3241,153 @@ interface RivePlayerProps extends BaseMediaProps {
 }
 declare const RivePlayer: React$1.ForwardRefExoticComponent<RivePlayerProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Logo — a brand mark with lockup, background-mode, and monochrome
+ * variations, fed bespoke artwork per slot.
+ *
+ * A brand rarely has one logo: there's a square mark for tight spaces, a
+ * horizontal lockup for headers, and single-colour versions for busy or
+ * inverted backgrounds. This component holds that set and renders the right
+ * one for the context, so a sidenav, toolbar, and footer can all reach for
+ * `<Logo>` and ask for the lockup/mode they need.
+ *
+ * Artwork is yours: each slot is any React node — an inline `<svg>`, an
+ * `<img>`, or a component. Supply only what you have; the component falls
+ * back across appearances and lockups so a partial set still renders
+ * something. Monochrome artwork should paint with `currentColor` so it
+ * inherits the surrounding text colour.
+ *
+ * Selection is explicit, not theme-coupled: set `mode="dark"` when the logo
+ * sits on a dark surface. (Wrap it in your own theme hook if you want it
+ * automatic.)
+ */
+type LogoLockup = "square" | "horizontal" | "icon";
+type LogoMode = "light" | "dark";
+type LogoSize = "sm" | "md" | "lg" | "xl";
+/** Artwork for one lockup. `light`/`dark` are the full-colour versions for a
+ *  light or dark background; `mono` is a single-colour treatment that
+ *  inherits `currentColor` and works on any background. */
+interface LogoVariant {
+    light?: React$1.ReactNode;
+    dark?: React$1.ReactNode;
+    mono?: React$1.ReactNode;
+}
+/** The brand artwork set, keyed by lockup then appearance. */
+interface LogoSources {
+    square?: LogoVariant;
+    horizontal?: LogoVariant;
+    icon?: LogoVariant;
+}
+interface LogoProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "children"> {
+    /** The brand artwork. Supply only the slots you have. */
+    sources: LogoSources;
+    /** Which lockup to show. Falls back to another lockup if this one is
+     *  empty. Default `"horizontal"`. */
+    lockup?: LogoLockup;
+    /** The background the logo sits on — selects the light/dark artwork.
+     *  Explicit (not theme-coupled). Default `"light"`. */
+    mode?: LogoMode;
+    /** Render the monochrome artwork instead of full colour. Mono inherits
+     *  `currentColor`, so set the text colour on a parent. Default `false`. */
+    mono?: boolean;
+    /** Height of the logo — a t-shirt token or a raw pixel number. Width is
+     *  intrinsic (square/icon are 1:1, horizontal keeps its ratio).
+     *  Default `"md"`. */
+    size?: LogoSize | number;
+    /** Accessible name (e.g. the brand name) → `aria-label` + `role="img"`.
+     *  Omit and set `decorative` when something nearby already names it. */
+    label?: string;
+    /** Mark the logo decorative (`aria-hidden`, no role). Use when the brand
+     *  name is already in the DOM beside it. */
+    decorative?: boolean;
+    /** Optional link target — renders the logo as an `<a>` (logo-links-home). */
+    href?: string;
+}
+declare const Logo: React$1.ForwardRefExoticComponent<LogoProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Control schema — the canonical, UI-agnostic descriptor for a shader's
+ * (or effect layer's) tweakable parameters. Shared by base demos AND the
+ * universal post stack, so a single `<ShaderControls schema={...} />`
+ * renders any of them.
+ *
+ * Ported from the three-lab experiments (the proven shape) and extended
+ * with two controls from the Paper reference — `segmented` and
+ * `colorList` (Paper's colorCount) — plus an optional palette-slot
+ * binding on `color` (the "Line colour → accent" affordance).
+ *
+ * Kept free of three.js / React imports so post-stack.ts and any other
+ * renderer can depend on it without a circular import.
+ */
+/** Global palette slots a colour control can bind to. */
+type PaletteSlot = "primary" | "secondary" | "accent" | "background";
+type NumberControl = {
+    type: "slider";
+    key: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    /** Display unit appended in the readout (e.g. "px", "°", "%"). */
+    unit?: string;
+};
+type ColorControl = {
+    type: "color";
+    key: string;
+    label: string;
+    default: string;
+    /** When set, the control FOLLOWS this palette slot (re-tints with the
+     *  theme, shows a "→ accent" affordance) until the user overrides it. */
+    slot?: PaletteSlot;
+};
+/** A variable-length list of colours — Paper's colorCount + swatches. */
+type ColorListControl = {
+    type: "colorList";
+    key: string;
+    label: string;
+    default: string[];
+    /** Min / max swatches the user can add. */
+    min?: number;
+    max?: number;
+};
+type ToggleControl = {
+    type: "toggle";
+    key: string;
+    label: string;
+    default: boolean;
+};
+type SelectControl = {
+    type: "select";
+    key: string;
+    label: string;
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    default: string;
+};
+/** Same data as a select, rendered as a segmented toggle (≤4 options). */
+type SegmentedControl = {
+    type: "segmented";
+    key: string;
+    label: string;
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    default: string;
+};
+type DividerControl = {
+    type: "divider";
+    key: string;
+    /** Optional section heading above the divider line. */
+    label?: string;
+};
+type ControlSpec = NumberControl | ColorControl | ColorListControl | ToggleControl | SelectControl | SegmentedControl | DividerControl;
+/** A flat bag of current values, keyed by ControlSpec.key. */
+type DemoState = Record<string, number | string | boolean | string[]>;
+
 /**
  * Shared types for the three.js layer of the design system.
  *
@@ -2402,6 +3457,7 @@ interface PostPreset {
         };
     };
 }
+
 /** A shader preset is the data needed to instantiate one of the canned scenes. */
 interface ShaderPreset {
     id: string;
@@ -2419,6 +3475,10 @@ interface ShaderPreset {
     defaultPalette?: Partial<Palette>;
     /** Static poster image path for non-hover previews. Served from /public. */
     poster?: string;
+    /** Tweakable controls for this base shader (drives the controls panel
+     *  + maps to uniforms). Effect layers (grain etc.) carry their own
+     *  controls separately via EffectLayerSpec. */
+    controls?: ControlSpec[];
 }
 
 /**
@@ -2473,7 +3533,7 @@ declare function buildFragmentShaderScene(userFragment: string): SceneFactory;
  * play/pause overlay. Scene pauses when offscreen (pauseOffscreen default `true`).
  */
 
-interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster"> {
+interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster">, Omit<React$1.HTMLAttributes<HTMLDivElement>, keyof BaseMediaProps> {
     /** Preset id from the shader preset registry. */
     preset?: string;
     /**
@@ -2489,8 +3549,12 @@ interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster"> {
     fragmentShader?: string;
     /** Called when a supplied `fragmentShader` fails to compile. */
     onShaderError?: (error: ShaderCompileError) => void;
-    /** Post-FX preset id. Defaults to the preset's `defaultPostPreset` or "vhs". */
-    postPreset?: string;
+    /** Post-FX preset. Either a registry id (`"vhs"`) OR a full `PostPreset`
+     *  object — pass an object (e.g. from `postStateToPreset`) to drive the
+     *  stack live from a controls panel; changes are applied via the
+     *  composer's `setPreset` WITHOUT remounting WebGL. Defaults to the
+     *  base preset's `defaultPostPreset` or "vhs". */
+    postPreset?: string | PostPreset;
     /** Palette overrides. Unset slots fall back to `DEFAULT_PALETTE`. */
     palette?: Partial<Palette>;
     /**
@@ -2502,9 +3566,161 @@ interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster"> {
     poster?: string;
     /** Pixel-ratio cap. Defaults to `Math.min(window.devicePixelRatio, 2)`. */
     maxDpr?: number;
+    /**
+     * Controlled play/pause. When provided, pauses/resumes the render loop
+     * WITHOUT remounting the WebGL context (unlike `autoPlay`, which only
+     * sets the initial state and remounts on change). Use for "animate on
+     * hover" thumbnails. Reduced-motion still forces paused.
+     */
+    play?: boolean;
 }
 declare const ThreeScene: React$1.ForwardRefExoticComponent<ThreeSceneProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * ShaderControls — renders a `ControlSpec[]` schema into a live controls
+ * panel using the DS control primitives. One component drives every
+ * shader's params, the universal post stack (POST_CONTROLS), and any
+ * effect layer — because they all describe themselves as ControlSpec[].
+ *
+ * Controlled: parent owns the `DemoState` and gets `onChange(key, value)`
+ * on every edit. UI-only; it knows nothing about WebGL.
+ *
+ * Mapping:
+ *   slider     → Slider + editable number (with optional unit)
+ *   segmented  → ToggleGroup (single)
+ *   select     → Select (compact)
+ *   toggle     → Switch
+ *   color      → swatch + hex field (with optional "→ slot" binding hint)
+ *   colorList  → N swatches + add/remove (Paper's colorCount)
+ *   divider    → section heading + rule
+ */
+
+interface ShaderControlsProps {
+    controls: readonly ControlSpec[];
+    state: DemoState;
+    onChange: (key: string, value: number | string | boolean | string[]) => void;
+    disabled?: boolean;
+    className?: string;
+}
+declare function ShaderControls({ controls, state, onChange, disabled, className, }: ShaderControlsProps): React$1.JSX.Element;
+
+/**
+ * BackgroundFill — a frame's background *paint*, as a layer.
+ *
+ * This is the render boundary for the "fill" model: a generative
+ * background (shader), an image, a video, a gradient, a repeating
+ * texture, or a solid token is NEVER a free-standing selectable node.
+ * It is a paint that belongs to a frame, exactly like a fill in Figma /
+ * Paper. The frame is the thing you select; this layer is plumbing.
+ *
+ * Drop it as the FIRST child of a `relative` frame. It paints an
+ * `absolute inset-0`, `z-0`, `pointer-events-none` layer behind the
+ * frame's content — so siblings that carry `relative z-10` (or any
+ * positioned/z-indexed content) sit on top automatically. It is marked
+ * `data-gds-part="frame-fill"` + `aria-hidden` so Studio treats it as
+ * chrome (not separately selectable) and a11y trees skip it.
+ *
+ * The `type` switch picks what gets painted:
+ *   none     → renders nothing
+ *   solid    → a theme token (or any CSS colour)
+ *   gradient → a linear-gradient from from/via/to stops
+ *   image    → an <img> (object-fit) or a tiled background (repeat)
+ *   video    → a muted, looping, autoplaying <video>
+ *   shader   → a <ThreeScene> generative shader (preset or GLSL)
+ *
+ * Common controls — `opacity` and `blendMode` — apply to every type,
+ * mirroring the inspector's Blending section.
+ */
+
+type BackgroundFillType = "none" | "solid" | "gradient" | "image" | "video" | "shader";
+type BackgroundFillFit = "cover" | "contain" | "fill" | "none";
+interface BackgroundFillProps {
+    /** Which paint to render. */
+    type: BackgroundFillType;
+    /** Token name (`primary`, `card`, …) or any CSS colour. */
+    color?: string;
+    /** Gradient stops — token names or CSS colours. */
+    gradient?: {
+        from?: string;
+        via?: string;
+        to?: string;
+        angle?: number;
+    };
+    /** Image or video URL. */
+    src?: string;
+    /** object-fit for image / video. Default `cover`. */
+    fit?: BackgroundFillFit;
+    /** CSS object-position / background-position. Default `center`. */
+    position?: string;
+    /** Tile the image (uses background-image + repeat instead of <img>). */
+    repeat?: boolean;
+    /** Tile size when `repeat` (CSS background-size, e.g. "120px"). */
+    tileSize?: string;
+    /** Shader preset id (see ThreeScene). */
+    preset?: string;
+    /** Custom GLSL fragment shader (takes precedence over preset). */
+    fragmentShader?: string;
+    /** Palette overrides for the shader. */
+    palette?: Partial<Palette>;
+    /** Post-FX preset id or live PostPreset object. */
+    postPreset?: string | PostPreset;
+    /** Layer opacity (0–1). */
+    opacity?: number;
+    /** CSS mix-blend-mode against the frame behind it. */
+    blendMode?: React$1.CSSProperties["mixBlendMode"];
+    /** Corner radius — match the frame's so the paint clips cleanly. */
+    radius?: MediaRadius;
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+declare const BackgroundFill: React$1.ForwardRefExoticComponent<BackgroundFillProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * FillPicker — Grade's paint picker, modelled on Figma's fill popover.
+ *
+ * A type-icon row across the top (solid · gradient · image · pattern ·
+ * video · shader) switches the panel below to that paint's controls,
+ * with a global opacity at the foot. It emits a `FillValue` that maps
+ * 1:1 onto `<BackgroundFill>` props, so the inspector's Fill section and
+ * any frame background share one control + one data shape.
+ *
+ * Grade is token-led, so the SOLID tab leads with theme-token swatches
+ * (the "Libraries" half of Figma's picker) rather than a freeform HSV
+ * square. A custom-colour square is a deliberate later pass.
+ */
+
+/** A paint value — the serialisable shape both the picker and
+ *  `<BackgroundFill>` speak. */
+interface FillValue {
+    type: BackgroundFillType;
+    color?: string;
+    gradient?: {
+        from?: string;
+        via?: string;
+        to?: string;
+        angle?: number;
+    };
+    src?: string;
+    fit?: BackgroundFillFit;
+    repeat?: boolean;
+    tileSize?: string;
+    preset?: string;
+    palette?: Partial<Palette>;
+    postPreset?: string | PostPreset;
+    opacity?: number;
+}
+/** Theme tokens offered as solid / gradient swatches. */
+declare const FILL_TOKENS: readonly ["primary", "accent", "secondary", "muted", "card", "background", "destructive", "transparent"];
+interface FillPickerProps {
+    value: FillValue;
+    onChange: (value: FillValue) => void;
+    className?: string;
+}
+declare function FillPicker({ value, onChange, className }: FillPickerProps): React$1.JSX.Element;
+declare namespace FillPicker {
+    var displayName: string;
+}
+
 /**
  * ShaderPresetPreview — a thumbnail-sized preview of a shader preset.
  *
@@ -2524,7 +3740,7 @@ interface ShaderPresetPreviewProps {
     postPreset?: string;
     palette?: Partial<Palette>;
     className?: string;
-    aspect?: "video" | "square" | "portrait" | "wide";
+    aspect?: "video" | "standard" | "square" | "portrait" | "wide";
     radius?: "none" | "sm" | "md" | "lg" | "xl";
     /** Text label shown on the card. Defaults to preset label. */
     label?: string;
@@ -3076,4 +4292,4 @@ declare function GradeModeSwitcher({ className, variant }: GradeModeSwitcherProp
  */
 declare function ThemeToggle(): React$1.JSX.Element;
 
-export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AppShell, AppShellAside, type AppShellAsideProps, AppShellFooter, type AppShellFooterProps, AppShellHeader, type AppShellHeaderProps, AppShellMain, type AppShellMainProps, AppShellNav, type AppShellNavProps, type AppShellProps, Avatar, AvatarFallback, AvatarImage, BUILT_IN_INPUTS, Badge, Banner, type BannerProps, type BaseMediaProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, type BreadcrumbMenuItem, BreadcrumbMenuTrigger, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonShape, COMPONENT_CONTRACTS, Calendar, CalendarDayButton, Callout, CalloutDescription, CalloutTitle, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, Carousel, CarouselArrows, type CarouselArrowsProps, type AutoplayConfig as CarouselAutoplayConfig, CarouselDots, type CarouselDotsProps, type CarouselNavButtonProps, CarouselNext, CarouselPrev, type CarouselProps, CarouselSlide, type CarouselSlideProps, CarouselVideoSlide, type CarouselVideoSlideProps, type ChartPalette, Checkbox, Code, type CodeDiff, type CodeLanguage, type CodeProps, type CodeReveal, type CodeTrigger, 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, FRAGMENT_HEADER, Flex, type FlexProps, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Grid, type GridProps, Input, type InputStyle, Label, LenisProvider, Map, MapHandle, MapMarker, MapMarkerProps, MapProps, type MediaAspect, type MediaRadius, MediaSurface, MediaSurfaceContract, type MediaSurfaceProps, type ModeName, MultiSelect, type MultiSelectOption, type MultiSelectProps, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ResizableHandle, ResizablePanel, ResizablePanelGroup, RivePlayer, type RivePlayerProps, Row, type RowProps, type SceneContext, type SceneFactory, type SceneHandle, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, ShaderCompileError, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, type SidebarContentProps, SidebarFooter, type SidebarFooterProps, SidebarHeader, type SidebarHeaderProps, SidebarItem, type SidebarItemProps, type SidebarProps, SidebarSection, type SidebarSectionProps, SidebarTreeItem, type SidebarTreeItemProps, Skeleton, Slider, Sortable, SortableGroup, type SortableGroupProps, SortableHandle, type SortableHandleProps, SortableItem, type SortableItemProps, type SortableProps, type SpacingDensity, Stack, type StackProps, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, type ToolbarProps, ToolbarSlot, type ToolbarSlotProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TypeScalePreset, VideoPlayer, type VideoPlayerProps, asideVariants as appShellAsideVariants, footerVariants as appShellFooterVariants, headerVariants as appShellHeaderVariants, mainVariants as appShellMainVariants, navVariants as appShellNavVariants, applyThemeToRoot, badgeVariants, bannerVariants, buildFragmentShaderScene, builtInThemes, buttonVariants, calloutVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, duplicateTheme, energyInput, flexVariants, generateTheme, getComponentContract, getTheme, gridVariants, listContractedComponents, listThemes, listUserThemes, loadUserThemeInput, postPresets, rowVariants, saveUserTheme, sceneRegistry, shaderPresetById, shaderPresets, shellVariants, stackVariants, themeToCSSVars, toggleVariants, useCarouselApi, useGradeTheme, useMaybeGradeTheme, usePrefersReducedMotion };
+export { ALL_MODES, Accordion, AccordionContent, AccordionItem, AccordionTrigger, AppShell, AppShellAside, type AppShellAsideProps, AppShellFooter, type AppShellFooterProps, AppShellHeader, type AppShellHeaderProps, AppShellMain, type AppShellMainProps, AppShellNav, type AppShellNavProps, type AppShellProps, Avatar, AvatarFallback, AvatarImage, type AvatarTone, BUILT_IN_INPUTS, BackgroundFill, type BackgroundFillFit, type BackgroundFillProps, type BackgroundFillType, Badge, Banner, type BannerProps, type BaseMediaProps, BlinkingCursor, type BlinkingCursorProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, type BreadcrumbMenuItem, BreadcrumbMenuTrigger, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonShape, COMPONENT_CONTRACTS, Calendar, CalendarDayButton, Callout, CalloutDescription, CalloutTitle, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardStyle, CardTitle, Carousel, CarouselArrows, type CarouselArrowsProps, type AutoplayConfig as CarouselAutoplayConfig, CarouselDots, type CarouselDotsProps, type CarouselNavButtonProps, CarouselNext, CarouselPrev, type CarouselProps, CarouselSlide, type CarouselSlideProps, CarouselVideoSlide, type CarouselVideoSlideProps, type ChartPalette, Checkbox, CheckboxCard, type CheckboxCardProps, Code, type CodeDiff, type CodeLanguage, type CodeProps, type CodeReveal, type CodeTrigger, type ColorIntensity, Composer, type ComposerAttachment, type ComposerAttachmentConfig, type ComposerContent, type ComposerFormat, type ComposerHandle, type ComposerMentionItem, type ComposerProps, ComposerReply, type ComposerStep, type ComposerTriggerConfig, DEMO_SPEED_PRESETS, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, type DemoSpeed, DemoStage, type DemoStageProps, type DemoTrigger, 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, FILL_TOKENS, FRAGMENT_HEADER, Field, FieldDescription, FieldLabel, type FieldProps, FieldTrailing, FillPicker, type FillPickerProps, type FillValue, Flex, type FlexProps, type FontKey, GRADE_PRE_HYDRATION_SCRIPT, type GeneratedTheme, GradeModeSwitcher, GradeThemeProvider, type GradeThemeProviderProps, GradeThemeSwitcher, Grid, type GridProps, Input, type InputStyle, Label, LenisProvider, Logo, type LogoLockup, type LogoMode, type LogoProps, type LogoSize, type LogoSources, type LogoVariant, MOTION_ATTR, Map, MapHandle, MapMarker, MapMarkerProps, MapProps, type MediaAspect, type MediaRadius, MediaSurface, MediaSurfaceContract, type MediaSurfaceProps, Message, type MessageProps, type ModeName, MultiSelect, type MultiSelectOption, type MultiSelectProps, type OKLCHTriplet, type Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PostPreset, Progress, RadioCard, type RadioCardProps, RadioGroup, RadioGroupItem, type RadiusStyle, type Ramp, ResizableHandle, ResizablePanel, ResizablePanelGroup, Reveal, type RevealAnimation, type RevealProps, type RevealStep, RivePlayer, type RivePlayerProps, Row, type RowProps, type SceneContext, type SceneFactory, type SceneHandle, type ScriptedDemoContext, type ScriptedDemoState, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, ShaderCompileError, ShaderControls, type ShaderControlsProps, type ShaderPreset, ShaderPresetPicker, type ShaderPresetPickerProps, ShaderPresetPreview, type ShaderPresetPreviewProps, type ShadowIntensity, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, type SidebarContentProps, SidebarFooter, type SidebarFooterProps, SidebarHeader, type SidebarHeaderProps, SidebarItem, type SidebarItemProps, type SidebarProps, SidebarSection, type SidebarSectionProps, SidebarTreeItem, type SidebarTreeItemProps, Skeleton, Slider, Sortable, SortableGroup, type SortableGroupProps, SortableHandle, type SortableHandleProps, SortableItem, type SortableItemProps, type SortableProps, type SpacingDensity, Stack, type StackProps, Switch, SwitchCard, type SwitchCardProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type ThemeInput, ThemeToggle, ThreeScene, type ThreeSceneProps, Toggle, ToggleGroup, ToggleGroupItem, Toolbar, type ToolbarProps, ToolbarSlot, type ToolbarSlotProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TypeScalePreset, type UseScriptedDemoOptions, VideoPlayer, type VideoPlayerProps, asideVariants as appShellAsideVariants, footerVariants as appShellFooterVariants, headerVariants as appShellHeaderVariants, mainVariants as appShellMainVariants, navVariants as appShellNavVariants, applyThemeToRoot, badgeVariants, bannerVariants, buildFragmentShaderScene, builtInThemes, buttonVariants, calloutVariants, calmInput, cn, defaultPostPreset, defaultThemeId, deleteUserTheme, sleep as demoSleep, typeText as demoTypeText, duplicateTheme, energyInput, flexVariants, generateTheme, getComponentContract, getTheme, gridVariants, listContractedComponents, listThemes, listUserThemes, loadUserThemeInput, postPresets, rowVariants, saveUserTheme, sceneRegistry, setMotion, shaderPresetById, shaderPresets, shellVariants, stackVariants, themeToCSSVars, toggleVariants, useCarouselApi, useGradeTheme, useMaybeGradeTheme, usePrefersReducedMotion, useReducedMotion, useScriptedDemo };