@gradeui/ui 1.3.0 → 2.0.0

package/dist/index.d.ts

@@ -177,14 +177,14 @@ declare const MediaSurfaceContract: _gradeui_contracts.ComponentContract<{
             description: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             kind: "book";
-            title?: string | undefined;
             description?: string | undefined;
+            title?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }, {
             kind: "book";
-            title?: string | undefined;
             description?: string | undefined;
+            title?: string | undefined;
             author?: string | undefined;
             isbn?: string | undefined;
         }>, z.ZodObject<{
@@ -489,7 +489,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" | null | undefined;
+    size?: "sm" | "md" | "lg" | "xl" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface AvatarProps extends React$1.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>, VariantProps<typeof avatarSizes> {
 }
@@ -571,7 +571,7 @@ type Surface = "solid" | "translucent" | "glass" | "glass-strong";
  */
 declare const bannerVariants: (props?: ({
     variant?: "default" | "info" | "success" | "warning" | "destructive" | "announcement" | null | undefined;
-    align?: "center" | "start" | "between" | null | undefined;
+    align?: "between" | "start" | "center" | 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> {
@@ -627,8 +627,8 @@ declare const Banner: React$1.ForwardRefExoticComponent<BannerProps & React$1.Re
  * consistent across primitives.
  */
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | "raised" | null | undefined;
-    size?: "default" | "sm" | "md" | "lg" | "icon" | "xs" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "raised" | null | undefined;
+    size?: "sm" | "md" | "lg" | "default" | "icon" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;
@@ -1326,6 +1326,10 @@ interface UseScriptedDemoOptions<TStep> {
     play?: boolean;
     /** Loop the sequence forever after completion. Pause length controlled by `loopDelay`. */
     loop?: boolean;
+    /** Cap the number of loop cycles, then settle and stop. A demo is a movie —
+     *  it shouldn't spin forever. Default Infinity. Grid/embed surfaces set a
+     *  small number so the loop ends instead of running unattended. */
+    maxLoops?: number;
     /**
      * Milliseconds to pause between loop cycles. Only applies when
      * `loop` is true. Defaults to 2000. Marketing surfaces that want
@@ -1903,7 +1907,7 @@ declare const DropdownMenuShortcut: {
  * rationale.
  */
 declare const inputVariants: (props?: ({
-    size?: "default" | "sm" | "xs" | null | undefined;
+    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type InputSize = NonNullable<VariantProps<typeof inputVariants>["size"]>;
 type InputProps = Omit<React$1.ComponentProps<"input">, "size"> & {
@@ -1921,7 +1925,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?: "default" | "sm" | "xs" | null | undefined;
+    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLLabelElement>>;
 
 declare const Popover: React$1.FC<PopoverPrimitive.PopoverProps>;
@@ -2065,7 +2069,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<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"> & {
+declare const ResizablePanel: React$1.ForwardRefExoticComponent<Omit<React$1.HTMLAttributes<HTMLDivElement | HTMLElement | HTMLObjectElement | HTMLSelectElement | HTMLTextAreaElement | HTMLMapElement | HTMLTitleElement | HTMLVideoElement | HTMLButtonElement | HTMLLinkElement | HTMLLabelElement | HTMLStyleElement | HTMLSourceElement | HTMLHtmlElement | HTMLOptionElement | HTMLTableColElement | 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 | HTMLOutputElement | HTMLPreElement | HTMLSlotElement | HTMLScriptElement | HTMLTemplateElement | HTMLTableSectionElement | HTMLTableCellElement | HTMLTimeElement | HTMLTableRowElement | HTMLTrackElement | HTMLTableCaptionElement | HTMLMenuElement | HTMLPictureElement>, "id" | "onResize"> & {
     className?: string | undefined;
     collapsedSize?: number | undefined;
     collapsible?: boolean | undefined;
@@ -2105,8 +2109,8 @@ declare const ResizableHandle: ({ withHandle, className, ...props }: React$1.Com
  */
 declare const rowVariants: (props?: ({
     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;
+    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "between" | "start" | "center" | "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> {
@@ -2141,7 +2145,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;
-    align?: "center" | "start" | "end" | "stretch" | 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> {
     /** When true, render as the single child element via Radix Slot — lets
@@ -2173,10 +2177,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?: "col" | "row" | "row-reverse" | "col-reverse" | null | undefined;
+    direction?: "row" | "col" | "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;
+    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "between" | "start" | "center" | "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> {
@@ -2201,7 +2205,7 @@ declare const SelectValue: React$1.ForwardRefExoticComponent<SelectPrimitive.Sel
  * 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";
+type SelectMenuSize = "default" | "sm" | "xs" | "2xs";
 /**
  * Select trigger variants — `size` lets dense surfaces (the
  * Studio inspector, settings sheets) reach for a compact `sm`
@@ -2210,11 +2214,20 @@ type SelectMenuSize = "default" | "sm" | "xs";
  * existing call site.
  */
 declare const selectTriggerVariants: (props?: ({
-    size?: "default" | "sm" | "xs" | null | undefined;
+    size?: "sm" | "default" | "xs" | "2xs" | 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"> & {
     size?: SelectTriggerSize;
+    /** Adornment rendered inside the trigger on the leading edge — a
+     *  property glyph, a unit. Mirrors Input's startSlot. Grouped with
+     *  the value in a div (NOT a bare span: the trigger's
+     *  `[&>span]:line-clamp-1` would stack a span's children
+     *  vertically). */
+    startSlot?: React$1.ReactNode;
+    /** Hide the dropdown chevron — Figma-style token fields keep the
+     *  right edge for their own affordances (detach/attach). */
+    chevron?: boolean;
 } & 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>>;
@@ -2222,7 +2235,12 @@ declare const SelectContent: React$1.ForwardRefExoticComponent<Omit<SelectPrimit
     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 SelectItem: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & {
+    /** Optional right-aligned secondary text (e.g. a token's resolved
+     *  value). Rendered in the menu row only — NOT inside ItemText, so
+     *  it never mirrors into the trigger via SelectValue. */
+    hint?: React$1.ReactNode;
+} & React$1.RefAttributes<HTMLDivElement>>;
 declare const SelectSeparator: React$1.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectSeparatorProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 
 declare const Separator: React$1.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
@@ -2233,7 +2251,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?: "bottom" | "top" | "right" | "left" | null | undefined;
+    side?: "top" | "right" | "bottom" | "left" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface SheetContentProps extends React$1.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants> {
     /**
@@ -2372,8 +2390,8 @@ declare const Sortable: SortableRootComponent;
  */
 declare const stackVariants: (props?: ({
     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;
+    align?: "start" | "center" | "end" | "stretch" | null | undefined;
+    justify?: "between" | "start" | "center" | "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
@@ -2383,7 +2401,20 @@ interface StackProps extends React$1.HTMLAttributes<HTMLDivElement>, VariantProp
 }
 declare const Stack: React$1.ForwardRefExoticComponent<StackProps & React$1.RefAttributes<HTMLDivElement>>;
 
-declare const Switch: React$1.ForwardRefExoticComponent<Omit<SwitchPrimitives.SwitchProps & React$1.RefAttributes<HTMLButtonElement>, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Switch — track + thumb scale together via the shared control size
+ * scale. Dimensions stay on Tailwind's spacing scale (no arbitrary
+ * values): thumb travel = trackWidth − thumbWidth − 2×border, which
+ * lands on a clean `translate-x-*` step at each size. `xs`/`sm` are the
+ * dense tool-panel sizes (the Studio inspector).
+ */
+declare const switchTrackVariants: (props?: ({
+    size?: "sm" | "default" | "xs" | "2xs" | 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"> & {
+    size?: SwitchSize;
+} & React$1.RefAttributes<HTMLButtonElement>>;
 
 declare const Table: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTableElement> & React$1.RefAttributes<HTMLTableElement>>;
 declare const TableHeader: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTableSectionElement> & React$1.RefAttributes<HTMLTableSectionElement>>;
@@ -2506,7 +2537,7 @@ declare const TabsContent: React$1.ForwardRefExoticComponent<Omit<TabsPrimitive.
  * px-3 / text-sm; `sm` and `xs` are for dense tool panels.
  */
 declare const textareaVariants: (props?: ({
-    size?: "default" | "sm" | "xs" | null | undefined;
+    size?: "sm" | "default" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type TextareaSize = NonNullable<VariantProps<typeof textareaVariants>["size"]>;
 type TextareaProps = Omit<React$1.ComponentProps<"textarea">, "size"> & {
@@ -2516,11 +2547,11 @@ declare const Textarea: React$1.ForwardRefExoticComponent<Omit<TextareaProps, "r
 
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "default" | "sm" | "lg" | "xs" | null | undefined;
+    size?: "sm" | "lg" | "default" | "xs" | "2xs" | 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" | "xs" | null | undefined;
+    size?: "sm" | "lg" | "default" | "xs" | "2xs" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & React$1.RefAttributes<HTMLButtonElement>>;
 
 declare const TooltipProvider: React$1.FC<TooltipPrimitive.TooltipProviderProps>;
@@ -2605,7 +2636,7 @@ declare const ToggleGroupItem: React$1.ForwardRefExoticComponent<Omit<ToggleGrou
  * persistent footer toolbars on mobile-style layouts.
  */
 declare const toolbarVariants: (props?: ({
-    position?: "bottom" | "top" | "inline" | null | undefined;
+    position?: "top" | "bottom" | "inline" | null | undefined;
     variant?: "default" | "transparent" | "subtle" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
     sticky?: boolean | null | undefined;
@@ -2891,6 +2922,24 @@ declare function useReducedMotion(): boolean;
  * global `data-motion="off"` toggle, not just the OS query.
  */
 declare const usePrefersReducedMotion: typeof useReducedMotion;
+/**
+ * Returns `true` when the page is actually being watched — the tab is visible
+ * AND (for a top-level document) the window is focused. Inside an iframe the
+ * focus check is skipped, because an iframe rarely "has focus" even when its
+ * tab is frontmost; it falls back to visibility, which correctly tracks the
+ * top tab. Use it to PAUSE autoplay loops when nobody's looking: a movie stops
+ * when you tab away.
+ *
+ * SSR-safe — defaults to `true` and rehydrates in an effect.
+ *
+ * Scope, deliberately: this knows about tab visibility + window focus, NOT
+ * whether the element is scrolled into view (pair it with an
+ * IntersectionObserver — e.g. motion's `useInView` — for that), and NOT
+ * whether a cross-document iframe has scrolled off its PARENT's viewport. An
+ * iframe can't see the parent's scroll; the parent must observe the host and
+ * pause it. See the grid poster/promote policy in STUDIO-CAPTURE.md.
+ */
+declare function usePageActive(): boolean;
 /**
  * Imperatively set the global motion toggle on `<html>`.
  *
@@ -3084,6 +3133,11 @@ declare global {
     interface Window {
         __gradeMediaUrls?: MediaUrlMap;
         __gradeMediaOverrides?: MediaOverrideMap;
+        /** Source-keys with a Fill request currently in flight. Stamped by
+         *  the sandbox agent on `grade:set-media-pending`; drives the
+         *  placeholder's Presence shimmer (gds-aura-shimmer) so slots read
+         *  as "being generated" rather than inert while the resolver works. */
+        __gradeMediaPending?: Record<string, true>;
     }
 }
 interface MediaSurfaceProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "children"> {
@@ -3279,8 +3333,11 @@ interface LogoSources {
     icon?: LogoVariant;
 }
 interface LogoProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "children"> {
-    /** The brand artwork. Supply only the slots you have. */
-    sources: LogoSources;
+    /** The brand artwork. Supply only the slots you have. Optional — with
+     *  no artwork at all the neutral placeholder renders, which keeps
+     *  layout intact (and keeps a model-emitted bare `<Logo />` from
+     *  crashing a Studio preview). */
+    sources?: LogoSources;
     /** Which lockup to show. Falls back to another lockup if this one is
      *  empty. Default `"horizontal"`. */
     lockup?: LogoLockup;
@@ -3305,6 +3362,67 @@ interface LogoProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "children"
 }
 declare const Logo: React$1.ForwardRefExoticComponent<LogoProps & React$1.RefAttributes<HTMLElement>>;
 
+/**
+ * ScreenAnimator — wrap any content in a directed camera.
+ *
+ * Give it a list of `shots` (a zoom + focal point + dwell) and it tours them:
+ * flies in from offscreen, eases between shots, settles back to the start,
+ * exits, and loops, with a focus spotlight, a synthetic cursor, captions, and
+ * a play/pause/restart transport. The content stays live and interactive
+ * underneath; the camera just directs the eye. It works around ANY children,
+ * a dashboard, an app shell, a single card.
+ *
+ * It's the reusable form of the camera in the embed (`useCameraTimeline` /
+ * `ZoomPan`) and the `camera-tour` scaffold — see STUDIO-DIRECTOR.md. Honours
+ * reduced motion (settles on the starter frame, no movement).
+ */
+interface ScreenAnimatorShot {
+    /** Magnification (1 = fit). >1 pushes in. */
+    zoom?: number;
+    /** Focal point as fractions of the content (0..1). Defaults to centre. */
+    cx?: number;
+    cy?: number;
+    /** Milliseconds to dwell on this shot. */
+    hold?: number;
+    /** Milliseconds to glide INTO this shot from the previous one. */
+    trans?: number;
+    /** Caption shown while on this shot. */
+    label?: string;
+}
+interface ScreenAnimatorProps {
+    /** The shot list. Omit (or one shot) for a static framed view. */
+    shots?: ScreenAnimatorShot[];
+    /** Start playing on mount. Default true. */
+    autoplay?: boolean;
+    /** Loop the tour (fly in → shots → back to start → exit → repeat). Default true. */
+    loop?: boolean;
+    /** Cap the number of loop cycles, then settle and stop — a demo is a movie,
+     *  it shouldn't spin forever. Default Infinity (loops while watched). Set a
+     *  small number for grid/embed contexts so it ends. */
+    maxLoops?: number;
+    /** Show the play / pause / restart transport. Default true. */
+    controls?: boolean;
+    /** Dim the edges when pushed in (focus vignette). Default false — opt in. */
+    spotlight?: boolean;
+    /** Render the synthetic cursor pulse on detail shots. Default true. */
+    cursor?: boolean;
+    /** Fly in from offscreen on start (and exit on loop). Default true. */
+    enter?: boolean;
+    /** Where the caption sits over the frame. Default "bottom". */
+    captionPosition?: "top" | "bottom";
+    /** Background of the stage the content sits on while it's small (fly in/out).
+     *  A CSS background string. Default a dark cinematic stage. */
+    stage?: string;
+    /** A live backdrop rendered BEHIND the content, filling the stage — an
+     *  image, a gradient, or a `<ThreeScene>` shader. Shows around the screen
+     *  while it's small (fly in/out) and behind any padding. */
+    backdrop?: React$1.ReactNode;
+    className?: string;
+    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;
+
 /**
  * Control schema — the canonical, UI-agnostic descriptor for a shader's
  * (or effect layer's) tweakable parameters. Shared by base demos AND the
@@ -3639,12 +3757,19 @@ interface BackgroundFillProps {
     type: BackgroundFillType;
     /** Token name (`primary`, `card`, …) or any CSS colour. */
     color?: string;
-    /** Gradient stops — token names or CSS colours. */
+    /** Gradient stops — token names or CSS colours. `shape: "radial"`
+     *  swaps the linear paint for a radial wash (the classic "soft glow
+     *  behind the hero"); `at` positions its centre, `size` fixes the
+     *  ellipse (e.g. "45rem 50rem" — defaults to farthest-corner).
+     *  `angle` is linear-only; `at`/`size` are radial-only. */
     gradient?: {
         from?: string;
         via?: string;
         to?: string;
         angle?: number;
+        shape?: "linear" | "radial";
+        at?: string;
+        size?: string;
     };
     /** Image or video URL. */
     src?: string;
@@ -4292,4 +4417,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, 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 };
+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 };