@gradeui/ui 2.0.0 → 2.1.0

package/dist/index.d.mts

@@ -25,6 +25,11 @@ import * as SeparatorPrimitive from '@radix-ui/react-separator';
 import * as SliderPrimitive from '@radix-ui/react-slider';
 import { UniqueIdentifier } from '@dnd-kit/core';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
+import * as recharts_types_util_payload_getUniqPayload from 'recharts/types/util/payload/getUniqPayload';
+import * as recharts_types_component_Tooltip from 'recharts/types/component/Tooltip';
+import * as recharts_types_util_types from 'recharts/types/util/types';
+import * as recharts_types_component_DefaultTooltipContent from 'recharts/types/component/DefaultTooltipContent';
+import * as RechartsPrimitive from 'recharts';
 import * as TogglePrimitive from '@radix-ui/react-toggle';
 import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -384,10 +389,10 @@ declare const AccordionContent: React$1.ForwardRefExoticComponent<Omit<Accordion
  * `variant="warning"` or `variant="info"` depending on temperature.
  */
 declare const calloutVariants: (props?: ({
-    variant?: "default" | "info" | "success" | "warning" | "destructive" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | "info" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const Callout: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    variant?: "default" | "info" | "success" | "warning" | "destructive" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | "info" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLDivElement>>;
 declare const CalloutTitle: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLHeadingElement> & React$1.RefAttributes<HTMLParagraphElement>>;
 declare const CalloutDescription: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLParagraphElement> & React$1.RefAttributes<HTMLParagraphElement>>;
@@ -489,7 +494,7 @@ declare const AppShellFooter: React$1.ForwardRefExoticComponent<AppShellFooterPr
  * directly still works and overrides the variant defaults.
  */
 declare const avatarSizes: (props?: ({
-    size?: "sm" | "md" | "lg" | "xl" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface AvatarProps extends React$1.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>, VariantProps<typeof avatarSizes> {
 }
@@ -504,7 +509,7 @@ interface AvatarFallbackProps extends React$1.ComponentPropsWithoutRef<typeof Av
 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;
+    variant?: "default" | "secondary" | "destructive" | "outline" | "highlight" | "success" | "warning" | "info" | "success-soft" | "warning-soft" | "destructive-soft" | "info-soft" | "highlight-soft" | "success-outline" | "warning-outline" | "destructive-outline" | "info-outline" | null | undefined;
     rounded?: "default" | "full" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BadgeProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
@@ -570,7 +575,7 @@ type Surface = "solid" | "translucent" | "glass" | "glass-strong";
  * cannot get the token names wrong.
  */
 declare const bannerVariants: (props?: ({
-    variant?: "default" | "info" | "success" | "warning" | "destructive" | "announcement" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | "info" | "announcement" | null | undefined;
     align?: "between" | "start" | "center" | null | undefined;
     sticky?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -627,8 +632,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?: "sm" | "md" | "lg" | "default" | "icon" | "xs" | "2xs" | null | undefined;
+    variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "raised" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "md" | "lg" | "default" | "icon" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;
@@ -1907,7 +1912,7 @@ declare const DropdownMenuShortcut: {
  * rationale.
  */
 declare const inputVariants: (props?: ({
-    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type InputSize = NonNullable<VariantProps<typeof inputVariants>["size"]>;
 type InputProps = Omit<React$1.ComponentProps<"input">, "size"> & {
@@ -1925,7 +1930,7 @@ type InputProps = Omit<React$1.ComponentProps<"input">, "size"> & {
 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?: ({
-    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLLabelElement>>;
 
 declare const Popover: React$1.FC<PopoverPrimitive.PopoverProps>;
@@ -2108,7 +2113,7 @@ declare const ResizableHandle: ({ withHandle, className, ...props }: React$1.Com
  * etc.) and is a separate primitive.
  */
 declare const rowVariants: (props?: ({
-    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
     align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
     justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
     wrap?: boolean | null | undefined;
@@ -2144,7 +2149,7 @@ 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" | "xl" | "xs" | "2xl" | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
     align?: "start" | "center" | "end" | "stretch" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface GridProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProps<typeof gridVariants> {
@@ -2178,7 +2183,7 @@ declare const Grid: React$1.ForwardRefExoticComponent<GridProps & React$1.RefAtt
  */
 declare const flexVariants: (props?: ({
     direction?: "row" | "col" | "row-reverse" | "col-reverse" | null | undefined;
-    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
     align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
     justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
     wrap?: "wrap" | "nowrap" | "wrap-reverse" | null | undefined;
@@ -2214,7 +2219,7 @@ type SelectMenuSize = "default" | "sm" | "xs" | "2xs";
  * existing call site.
  */
 declare const selectTriggerVariants: (props?: ({
-    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "default" | 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"> & {
@@ -2389,7 +2394,7 @@ declare const Sortable: SortableRootComponent;
  * for a centred narrow column (auth cards, marketing copy).
  */
 declare const stackVariants: (props?: ({
-    gap?: "none" | "sm" | "md" | "lg" | "xl" | "xs" | "2xl" | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | null | undefined;
     align?: "start" | "center" | "end" | "stretch" | null | undefined;
     justify?: "between" | "start" | "center" | "end" | "around" | "evenly" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -2409,7 +2414,7 @@ declare const Stack: React$1.ForwardRefExoticComponent<StackProps & React$1.RefA
  * dense tool-panel sizes (the Studio inspector).
  */
 declare const switchTrackVariants: (props?: ({
-    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type SwitchSize = NonNullable<VariantProps<typeof switchTrackVariants>["size"]>;
 declare const Switch: React$1.ForwardRefExoticComponent<Omit<Omit<SwitchPrimitives.SwitchProps & React$1.RefAttributes<HTMLButtonElement>, "ref">, "size"> & {
@@ -2531,13 +2536,73 @@ 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 THEMES: {
+    readonly light: "";
+    readonly dark: ".dark";
+};
+type ChartConfig = {
+    [k in string]: {
+        label?: React$1.ReactNode;
+        icon?: React$1.ComponentType;
+    } & ({
+        color?: string;
+        theme?: never;
+    } | {
+        color?: never;
+        theme: Record<keyof typeof THEMES, string>;
+    });
+};
+declare const ChartContainer: React$1.ForwardRefExoticComponent<Omit<React$1.ClassAttributes<HTMLDivElement> & React$1.HTMLAttributes<HTMLDivElement> & {
+    config: ChartConfig;
+    children: React$1.ComponentProps<typeof RechartsPrimitive.ResponsiveContainer>["children"];
+}, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const ChartStyle: ({ id, config }: {
+    id: string;
+    config: ChartConfig;
+}) => React$1.JSX.Element | null;
+declare const ChartTooltip: typeof RechartsPrimitive.Tooltip;
+declare const ChartTooltipContent: React$1.ForwardRefExoticComponent<Omit<RechartsPrimitive.DefaultTooltipContentProps<recharts_types_component_DefaultTooltipContent.ValueType, recharts_types_component_DefaultTooltipContent.NameType> & {
+    accessibilityLayer?: boolean;
+    active?: boolean | undefined;
+    includeHidden?: boolean | undefined;
+    allowEscapeViewBox?: recharts_types_util_types.AllowInDimension;
+    animationDuration?: recharts_types_util_types.AnimationDuration;
+    animationEasing?: recharts_types_util_types.AnimationTiming;
+    content?: recharts_types_component_Tooltip.ContentType<recharts_types_component_DefaultTooltipContent.ValueType, recharts_types_component_DefaultTooltipContent.NameType> | undefined;
+    coordinate?: Partial<recharts_types_util_types.Coordinate>;
+    cursor?: boolean | React$1.ReactElement | React$1.SVGProps<SVGElement>;
+    filterNull?: boolean;
+    defaultIndex?: number;
+    isAnimationActive?: boolean;
+    offset?: number;
+    payloadUniqBy?: recharts_types_util_payload_getUniqPayload.UniqueOption<recharts_types_component_DefaultTooltipContent.Payload<recharts_types_component_DefaultTooltipContent.ValueType, recharts_types_component_DefaultTooltipContent.NameType>> | undefined;
+    position?: Partial<recharts_types_util_types.Coordinate>;
+    reverseDirection?: recharts_types_util_types.AllowInDimension;
+    shared?: boolean;
+    trigger?: "hover" | "click";
+    useTranslate3d?: boolean;
+    viewBox?: recharts_types_util_types.CartesianViewBox;
+    wrapperStyle?: React$1.CSSProperties;
+} & React$1.ClassAttributes<HTMLDivElement> & React$1.HTMLAttributes<HTMLDivElement> & {
+    hideLabel?: boolean;
+    hideIndicator?: boolean;
+    indicator?: "line" | "dot" | "dashed";
+    nameKey?: string;
+    labelKey?: string;
+}, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+declare const ChartLegend: typeof RechartsPrimitive.Legend;
+declare const ChartLegendContent: React$1.ForwardRefExoticComponent<Omit<React$1.ClassAttributes<HTMLDivElement> & React$1.HTMLAttributes<HTMLDivElement> & Pick<RechartsPrimitive.LegendProps, "verticalAlign" | "payload"> & {
+    hideIcon?: boolean;
+    nameKey?: string;
+}, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
+
 /**
  * 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?: "sm" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "default" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type TextareaSize = NonNullable<VariantProps<typeof textareaVariants>["size"]>;
 type TextareaProps = Omit<React$1.ComponentProps<"textarea">, "size"> & {
@@ -2547,11 +2612,11 @@ declare const Textarea: React$1.ForwardRefExoticComponent<Omit<TextareaProps, "r
 
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "sm" | "lg" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "lg" | "default" | 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?: "sm" | "lg" | "default" | "xs" | "2xs" | null | undefined;
+    size?: "2xs" | "xs" | "sm" | "lg" | "default" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLButtonElement>>;
 
 declare const TooltipProvider: React$1.FC<TooltipPrimitive.TooltipProviderProps>;
@@ -3362,6 +3427,18 @@ interface LogoProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "children"
 }
 declare const Logo: React$1.ForwardRefExoticComponent<LogoProps & React$1.RefAttributes<HTMLElement>>;
 
+type GradeLoaderSize = "sm" | "md" | "lg" | "xl";
+interface GradeLoaderProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Mark size — token or exact pixels. Default `"md"` (24px). */
+    size?: GradeLoaderSize | number;
+    /** Accessible status text (and the optional visible caption).
+     *  Default "Loading…"; pass "" to silence. */
+    label?: string;
+    /** Show the label visually under the mark (it's always announced). */
+    showLabel?: boolean;
+}
+declare const GradeLoader: React$1.ForwardRefExoticComponent<GradeLoaderProps & React$1.RefAttributes<HTMLDivElement>>;
+
 /**
  * ScreenAnimator — wrap any content in a directed camera.
  *
@@ -3402,6 +3479,12 @@ interface ScreenAnimatorProps {
     maxLoops?: number;
     /** Show the play / pause / restart transport. Default true. */
     controls?: boolean;
+    /** Controlled pause override — a sequencer (e.g. `<Motion>`) holds the
+     *  transport. Leave undefined for self-managed playback. */
+    paused?: boolean;
+    /** Fires once when the tour runs to its end and stops (loop cap reached,
+     *  or `loop=false`). The hook a sequencer advances on. */
+    onEnded?: () => void;
     /** Dim the edges when pushed in (focus vignette). Default false — opt in. */
     spotlight?: boolean;
     /** Render the synthetic cursor pulse on detail shots. Default true. */
@@ -3421,7 +3504,185 @@ interface ScreenAnimatorProps {
     style?: React$1.CSSProperties;
     children: React$1.ReactNode;
 }
-declare function ScreenAnimator({ shots, autoplay, loop, maxLoops, controls, spotlight, cursor, enter, captionPosition, stage, backdrop, className, style, children, }: ScreenAnimatorProps): React$1.JSX.Element;
+declare function ScreenAnimator({ shots, autoplay, loop, maxLoops, controls, paused, onEnded, spotlight, cursor, enter, captionPosition, stage, backdrop, className, style, children, }: ScreenAnimatorProps): React$1.JSX.Element;
+
+/**
+ * Motion — a directed sequence of scenes on one persistent stage.
+ *
+ * The grammar of a modern product demo: text → demo → video → text, any
+ * order, any mix. A `<Motion>` owns the stage (one continuous backdrop) and
+ * plays its `<MotionScene>`s in order. A scene is a *stage moment* holding
+ * arbitrary content:
+ *
+ *   - `<MotionScreen>` — a framed screen with its OWN camera (`shots`,
+ *     ScreenAnimator applied per-screen). Several can share a scene
+ *     (mobile + desktop side by side).
+ *   - `<MotionText>` — templated text animations (Motion Templates:
+ *     title / lower-third / section-break).
+ *   - anything else — a <video>, an image, plain JSX. Untimed content
+ *     rides the scene's `durationMs`.
+ *
+ * THE COMPLETION CONTRACT: a scene advances when all its *timed* children
+ * have finished (a camera tour ending, a text template completing), or
+ * after `durationMs` when nothing in it keeps time. Timed children register
+ * with the scene; static content doesn't. New content types plug in by
+ * registering — nothing else changes.
+ *
+ * Two views of the same children: `view="play"` (the film) and
+ * `view="strip"` (the arrangement — scenes left-to-right as labelled
+ * cards, the Studio edit view). Under `prefers-reduced-motion` the play
+ * view falls back to the strip: see everything, move nothing.
+ *
+ * See STUDIO-DIRECTOR.md ("Grade Motion") for the design doc.
+ */
+interface MotionSceneRegistration {
+    /** Signal this timed child has finished its run. Idempotent. */
+    done: () => void;
+    /** Unregister (unmount) without deadlocking the scene. */
+    cancel: () => void;
+}
+interface SceneCtxValue {
+    mode: "play" | "strip";
+    active: boolean;
+    paused: boolean;
+    /** Register as a timed child. Call in a mount effect; cancel on cleanup. */
+    register: () => MotionSceneRegistration;
+}
+/** Read the enclosing scene (or a permissive standalone default). */
+declare function useMotionScene(): SceneCtxValue;
+interface MotionScreenProps {
+    /** Frame preset. Desktop is a 16:10 browser-ish frame; mobile a tall
+     *  device frame. Default "desktop". */
+    device?: "desktop" | "mobile";
+    /** Camera shots for THIS screen (ScreenAnimator, per-screen). Omit for
+     *  fly-in + a single dwell. */
+    shots?: ScreenAnimatorShot[];
+    /** Virtual CSS width the content is laid out at before scaling into the
+     *  frame. Defaults: desktop 1100, mobile 390. */
+    virtualWidth?: number;
+    /** Dim edges when the camera pushes in. Default false. */
+    spotlight?: boolean;
+    /** Synthetic cursor on detail shots. Default true. */
+    cursor?: boolean;
+    /** Fly the CONTENT in from offscreen when the scene starts. Default
+     *  FALSE for framed screens — the full-screen fly-in choreography
+     *  reads badly inside a small clipped frame (content sliding around
+     *  in a box). Scene `transition` and frame `animate` are the
+     *  entrances here; opt back in for full-bleed hero screens. */
+    enter?: boolean;
+    /** Animate the FRAME in place within the scene — independent of (and
+     *  composable with) the camera inside it. "rise" / "tilt-settle" are
+     *  entrances; "float" / "drift" are ambient loops. Default "none".
+     *  Pair with enter={false} when using an entrance here. */
+    animate?: MotionScreenAnimate;
+    /** Provenance — the Studio screen this was copied from. Ignored at
+     *  render; read by tooling (the dock, future live-reference scenes). */
+    screenId?: string;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children: React$1.ReactNode;
+}
+declare function MotionScreen({ device, shots, virtualWidth, spotlight, cursor, enter, animate, screenId: _screenId, className, style, children, }: MotionScreenProps): React$1.JSX.Element;
+type MotionTextTemplate = "title" | "lower-third" | "section-break" | "broadcast" | "ticker" | "stat" | "quote";
+interface MotionTextProps {
+    /** Which Motion Template. Default "title". */
+    template?: MotionTextTemplate;
+    heading: string;
+    /** Supporting line (title / lower-third). */
+    text?: string;
+    /** Override the template's run length (ms). */
+    durationMs?: number;
+    /** Text colour against the stage. Default "light" (for the dark stage). */
+    tone?: "light" | "dark";
+    /**
+     * Lift the type off a busy or low-contrast backdrop (pale shader washes,
+     * photos, video). `"shadow"` adds a soft contrast shadow to the glyphs;
+     * `"scrim"` additionally drops a quiet radial darkening behind the text
+     * block. Default "none" — flat fills don't need it.
+     */
+    lift?: "none" | "shadow" | "scrim";
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+declare function MotionText({ template, heading, text, durationMs, tone, lift, className, style, }: MotionTextProps): React$1.JSX.Element;
+type MotionOverlayZone = "top-left" | "top" | "top-right" | "center" | "bottom-left" | "bottom" | "bottom-right" | "lower-third";
+interface MotionOverlayProps {
+    /** Anchor zone. Default "top-right" (the classic network-bug corner). */
+    zone?: MotionOverlayZone;
+    /** Visible from this scene index (inclusive). Default 0 — overlays are
+     *  a second TIMELINE: always-on is just the full-range case. */
+    fromScene?: number;
+    /** Visible through this scene index (inclusive). Default: the end. */
+    toScene?: number;
+    /** Re-enable pointer events for interactive overlays. Default false. */
+    interactive?: boolean;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children: React$1.ReactNode;
+}
+declare function MotionOverlay({ zone, fromScene: _fromScene, toScene: _toScene, interactive, className, style, children, }: MotionOverlayProps): React$1.JSX.Element;
+/** How a scene ARRIVES on the stage. Entrance-only by design — the
+ *  outgoing scene cuts; the incoming one performs. (True cross-fades
+ *  need both scenes mounted; that rides the seekable-clock work.) */
+type MotionSceneTransition = "fade" | "slide-up" | "slide-down" | "slide-left" | "slide-right" | "pop" | "zoom" | "wipe-circle" | "none";
+/** In-place frame animation for MotionScreen — the screen performs
+ *  WITHIN the scene (independent of the camera inside it, composable
+ *  with it). "rise" and "tilt-settle" are entrances; "float" and
+ *  "drift" are ambient loops. */
+type MotionScreenAnimate = "rise" | "float" | "tilt-settle" | "drift" | "none";
+interface MotionSceneProps {
+    /** Shown in the strip view + read by the timeline dock. */
+    label?: string;
+    /** Minimum runtime (ms); the whole clock when nothing inside keeps
+     *  time. Default 4000 for untimed scenes. */
+    durationMs?: number;
+    /** Scene background painted over the shared stage for this moment only
+     *  (a CSS background — the white title card, a brand fill). */
+    fill?: string;
+    /** How the scene arrives: fade · slide-up/down/left/right · pop ·
+     *  zoom · wipe-circle (a mask wipe) · none. Default "fade". The
+     *  OUTGOING scene stays visible underneath for the transition window,
+     *  so slides/wipes reveal it rather than the stage. */
+    transition?: MotionSceneTransition;
+    /** Transition timing override (ms). Defaults per transition — see
+     *  SCENE_TRANSITION_DEFAULT_MS. */
+    transitionMs?: number;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children: React$1.ReactNode;
+}
+/**
+ * One stage moment in a `<Motion>`. Holds arbitrary content; advances by
+ * the completion contract (see the file header). Renders standalone too
+ * (active, looping nothing) so a scene can be previewed in isolation —
+ * each scene is independently editable.
+ */
+declare function MotionScene(props: MotionSceneProps): React$1.JSX.Element;
+interface MotionProps {
+    /** "play" runs the film; "strip" lays the scenes out left-to-right as
+     *  labelled cards (the arrangement / edit view). Default "play". */
+    view?: "play" | "strip";
+    /** Fixed artboard aspect for the film, letterboxed into the container —
+     *  "16/9" (landscape demo), "9/16" (TikTok / Reels / Shorts), "1/1".
+     *  Default "auto": the stage fills the container responsively. Strip
+     *  cards adopt the same ratio. */
+    aspect?: "auto" | "16/9" | "9/16" | "1/1" | (string & {});
+    /** The persistent stage behind every scene (CSS background). */
+    stage?: string;
+    /** A live layer behind all scenes (image, gradient, <ThreeScene>). */
+    backdrop?: React$1.ReactNode;
+    /** Start playing on mount. Default true. */
+    autoplay?: boolean;
+    /** Return to scene 1 and keep going at the end. Default false — a
+     *  motion is a movie; it ends. */
+    loop?: boolean;
+    /** Show the transport (play/pause, restart, scene dots). Default true. */
+    controls?: boolean;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children: React$1.ReactNode;
+}
+declare function Motion({ view, aspect, stage, backdrop, autoplay, loop, controls, className, style, children, }: MotionProps): React$1.JSX.Element;
 
 /**
  * Control schema — the canonical, UI-agnostic descriptor for a shader's
@@ -3651,6 +3912,17 @@ declare function buildFragmentShaderScene(userFragment: string): SceneFactory;
  * play/pause overlay. Scene pauses when offscreen (pauseOffscreen default `true`).
  */
 
+/**
+ * Tone — pin the shader's canvas independently of the page theme.
+ *
+ * `"auto"` (default) follows `--background`, so a shader on a page
+ * re-tints with light/dark mode. But a film frame or a hero with white
+ * type wants a STABLE ground: in light mode `--background` is near-white
+ * and every wash goes pastel under it. `tone="dark"` / `tone="light"`
+ * pins just the background uniform (brand pops still flow through), and
+ * an explicit `palette.background` always wins over both.
+ */
+type SceneTone = "auto" | "dark" | "light";
 interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster">, Omit<React$1.HTMLAttributes<HTMLDivElement>, keyof BaseMediaProps> {
     /** Preset id from the shader preset registry. */
     preset?: string;
@@ -3675,6 +3947,9 @@ interface ThreeSceneProps extends Omit<BaseMediaProps, "src" | "poster">, Omit<R
     postPreset?: string | PostPreset;
     /** Palette overrides. Unset slots fall back to `DEFAULT_PALETTE`. */
     palette?: Partial<Palette>;
+    /** Pin the canvas tone regardless of page theme (see `SceneTone`).
+     *  An explicit `palette.background` wins over this. */
+    tone?: SceneTone;
     /**
      * Custom scene factory. Takes precedence over `preset` and `fragmentShader`.
      * Use for bespoke three.js scenes that don't fit a preset or fullscreen quad.
@@ -3787,6 +4062,11 @@ interface BackgroundFillProps {
     fragmentShader?: string;
     /** Palette overrides for the shader. */
     palette?: Partial<Palette>;
+    /** Pin the shader's canvas tone — "dark" | "light" | "auto" (default).
+     *  Film frames and heroes with fixed-colour type should pin their tone
+     *  rather than inherit the page's light/dark mode (in light mode the
+     *  theme background washes every shader pastel). See ThreeScene. */
+    tone?: SceneTone;
     /** Post-FX preset id or live PostPreset object. */
     postPreset?: string | PostPreset;
     /** Layer opacity (0–1). */
@@ -3995,6 +4275,7 @@ declare const FONTS: {
     readonly outfit: "var(--font-outfit), system-ui, sans-serif";
     readonly plusJakarta: "var(--font-plus-jakarta), system-ui, sans-serif";
     readonly spaceGrotesk: "var(--font-space-grotesk), system-ui, sans-serif";
+    readonly poppins: "var(--font-poppins), system-ui, sans-serif";
     readonly fraunces: "var(--font-fraunces), Georgia, serif";
     readonly instrumentSerif: "var(--font-instrument-serif), Georgia, serif";
     readonly sourceSerif: "var(--font-source-serif), Georgia, serif";
@@ -4008,6 +4289,13 @@ declare const FONTS: {
 type FontKey = keyof typeof FONTS;
 /** Type scale preset — controls how generous the size ladder is. */
 type TypeScalePreset = "compact" | "default" | "spacious";
+/** Modular (musical-interval) scale ids — mirror GDS_MODULAR_SCALES in
+ *  @gradeui/core. Selecting one generates the type ladder middle-out from
+ *  the body size (Utopia model): up by the ratio, down by the reciprocal,
+ *  floored. */
+type ModularScaleId = "minor-second" | "major-second" | "minor-third" | "major-third" | "perfect-fourth" | "augmented-fourth" | "perfect-fifth" | "golden-ratio";
+/** What `typography.scale` accepts: a legacy flat preset or a modular ratio. */
+type TypeScale = TypeScalePreset | ModularScaleId;
 /** Density preset — controls spacing tightness. */
 type SpacingDensity = "tight" | "default" | "roomy";
 /** Radius preset — controls how rounded corners are across the system. */
@@ -4071,7 +4359,7 @@ interface ThemeInput {
         display: FontKey;
         body: FontKey;
         mono: FontKey;
-        scale: TypeScalePreset;
+        scale: TypeScale;
         /** Override heading weight. Defaults to 600 for sans, 500 for serif. */
         headingWeight?: number;
         /** Override body weight. Defaults to 400. */
@@ -4417,4 +4705,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, 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, ScreenAnimator, type ScreenAnimatorProps, type ScreenAnimatorShot, 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, usePageActive, usePrefersReducedMotion, useReducedMotion, useScriptedDemo };
+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 ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, type ChartPalette, ChartStyle, ChartTooltip, ChartTooltipContent, 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, GradeLoader, type GradeLoaderProps, type GradeLoaderSize, 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, Motion, MotionOverlay, type MotionOverlayProps, type MotionOverlayZone, type MotionProps, MotionScene, type MotionSceneProps, type MotionSceneRegistration, type MotionSceneTransition, MotionScreen, type MotionScreenAnimate, type MotionScreenProps, MotionText, type MotionTextProps, type MotionTextTemplate, 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, ScreenAnimator, type ScreenAnimatorProps, type ScreenAnimatorShot, 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, useMotionScene, usePageActive, usePrefersReducedMotion, useReducedMotion, useScriptedDemo };