@gradeui/ui 1.3.0 → 2.1.0

package/components/ui/avatar.md

@@ -2,16 +2,23 @@
 name: Avatar
 import: "@gradeui/ui"
 subcomponents: [AvatarImage, AvatarFallback]
+sizes: [2xs, xs, sm, md, lg, xl]
 props:
-  - Avatar: className? — set size via utilities (default h-10 w-10)
+  - size? (2xs | xs | sm | md | lg | xl) — t-shirt scale, 20px → 80px; default md (40px). xs for chat message rows, sm for comments/dense threads, lg/xl for profile headers. Prefer this over h-*/w-* className utilities.
   - AvatarImage: src, alt
-  - AvatarFallback: initials/icon rendered when image fails or loads
+  - AvatarFallback: tone? (muted | primary | violet | amber | emerald | sky | rose | plum | lime) — tinted bg/text pair. Reach for explicit tones when each author needs a stable colour mapping (chat avatars, comment threads, member lists); default muted.
+  - AvatarFallback: children — initials (or a small icon), rendered while the image loads or when it fails
 when_to_use: User/entity identity for PEOPLE — profile pictures, author rows, member lists, account headers. Circular by default; the AvatarFallback initials read as a person's name. Always include AvatarFallback so load failure doesn't leave a gap.
-composes_with: [Card (in CardHeader), Table cells, Badge (placed next to for status), Skeleton (loading state)]
+composes_with: [Card (in CardHeader), Table cells, Badge (placed next to for status), Skeleton (loading state), Message (in the avatar slot)]
 aliases: [profile picture, user image, account image, avatar, person glyph, user avatar, profile image, react native avatar]
 notes: |
   Anti-patterns to avoid:
 
+  - DO NOT pass `initials` as a prop on <Avatar> — that prop does not
+    exist. Initials are the CHILDREN of <AvatarFallback>:
+    `<Avatar><AvatarFallback>AL</AvatarFallback></Avatar>`.
+  - DO NOT size with className utilities (h-7 w-7) — use the `size`
+    prop so the scale stays on the t-shirt tokens.
   - DO NOT use Avatar for album art, posters, product photos, landscape
     images, or anything that isn't a person. Use <MediaSurface> with the
     appropriate `hint` ("album", "poster", "product", "landscape", etc.) —
@@ -27,3 +34,21 @@ notes: |
   <AvatarFallback>AL</AvatarFallback>
 </Avatar>
 ```
+
+```jsx
+// Chat / comment rows — small size + stable per-author tone.
+<Avatar size="xs">
+  <AvatarFallback tone="violet">A</AvatarFallback>
+</Avatar>
+<Avatar size="sm">
+  <AvatarFallback tone="amber">B</AvatarFallback>
+</Avatar>
+```
+
+```jsx
+// Profile header — large, with image + initials fallback.
+<Avatar size="lg">
+  <AvatarImage src="/ali.jpg" alt="Ali Driver" />
+  <AvatarFallback tone="primary">AD</AvatarFallback>
+</Avatar>
+```

package/components/ui/background-fill.md

@@ -4,7 +4,7 @@ import: "@gradeui/ui"
 props:
   - type: "none" | "solid" | "gradient" | "image" | "video" | "shader" — which paint to render (required)
   - color?: string — solid fill; a token name (`primary`, `card`, `muted`, `accent`, `secondary`, `destructive`, `background`, `transparent`) or any CSS colour
-  - gradient?: { from?; via?; to?; angle? } — gradient stops (token names or CSS colours) + angle in degrees (default 135)
+  - gradient?: { from?; via?; to?; angle?; shape?; at?; size? } — stops are token names or CSS colours. shape: "linear" (default, uses `angle`, default 135°) | "radial" (uses `at` — CSS position like "top" / "30% 20%", default "center" — and optional `size` like "45rem 50rem", default farthest-corner)
   - src?: string — image or video URL
   - fit?: "cover" | "contain" | "fill" | "none" — object-fit for image/video (default "cover")
   - position?: string — CSS object/background position (default "center")
@@ -54,11 +54,24 @@ notes: |
   ### Type cheat-sheet
 
     - solid    — `color` (token or CSS colour). Cheapest.
-    - gradient — `gradient={{ from, via?, to, angle }}`. Tokens get wrapped in oklch() automatically.
+    - gradient — `gradient={{ from, via?, to, angle }}` for linear;
+                 `gradient={{ shape: "radial", at: "top", from, to }}` for a radial
+                 glow/wash. Tokens get wrapped in oklch() automatically.
     - image    — `src` + `fit` / `position`; set `repeat` (+ `tileSize`) for a tiled texture.
     - video    — `src` (autoplays muted + looped + inline).
     - shader   — `preset` OR `fragmentShader`, + `palette` / `postPreset`. Delegates to ThreeScene.
 
+  Anti-patterns to avoid:
+
+  - DO NOT build gradients with arbitrary-value Tailwind classes —
+    `bg-[radial-gradient(45rem_50rem_at_top,theme(colors.indigo.50),white)]`
+    renders NOTHING in the Studio preview (no runtime Tailwind compiler) and
+    `theme(colors.*)` colours ignore the active Grade theme. Use
+    `type="gradient"` with token stops instead — themeable, and it always renders.
+  - DO NOT hand-roll `style={{ backgroundImage: "linear-gradient(…)" }}` on the
+    frame itself when a BackgroundFill child does the same job — the fill layer
+    keeps the paint selectable/editable as a Fill in Studio's inspector.
+
   `opacity` + `blendMode` apply to every type — the same two controls as
   the inspector's Blending section, so a loud shader/image can be dialled
   back to a subtle wash behind text.
@@ -92,6 +105,19 @@ notes: |
 </Card>
 ```
 
+```jsx
+// Radial glow from the top of a hero — the token-true version of the
+// classic `radial-gradient(45rem 50rem at top, indigo-50, white)` wash.
+<section className="relative overflow-hidden">
+  <BackgroundFill
+    type="gradient"
+    gradient={{ shape: "radial", at: "top", size: "45rem 50rem", from: "primary", to: "background" }}
+    opacity={0.2}
+  />
+  <div className="relative z-10 py-24 text-center">…hero content…</div>
+</section>
+```
+
 ```jsx
 // Image background, cover-fit, with a blend mode.
 <div className="relative h-64 overflow-hidden rounded-lg">

package/components/ui/grade-loader.md

@@ -0,0 +1,31 @@
+# GradeLoader
+
+The branded indeterminate loader — the Grade G-arrow mark with a diagonal
+shimmer sweeping through it. Use it for EVERY "working, unknown duration"
+moment instead of a generic spinner: fetching, compiling, warming a shader,
+waiting on AI.
+
+props:
+  - size?: "sm" | "md" | "lg" | "xl" | number — mark size (16/24/32/48px). Default "md".
+  - label?: string — accessible status text; shown visually with showLabel. Default "Loading…"; pass "" to silence.
+  - showLabel?: boolean — render the label as a caption under the mark. Default false.
+
+when_to_use:
+  - Indeterminate waits: data fetching, AI generation in flight, preview compiling, media/shader warm-up, route transitions.
+  - Centered in an empty panel/card region while its content loads (pair with size="lg" + showLabel).
+  - NOT for determinate progress — use Progress when you can show a fraction.
+  - NOT a skeleton — use Skeleton when the layout shape is known and content is imminent.
+
+composes_with:
+  - Card / panel bodies (centered placeholder state)
+  - Button (size="sm" inline while an action is pending)
+  - Motion scene boundaries / media surfaces while heavy content warms
+  - EmptyState (loading precursor before empty/error variants)
+
+aliases: loader, spinner, loading indicator, busy, indeterminate, grade mark loader, branded spinner
+
+notes:
+  - Paints with currentColor — set text colour on a parent (`text-muted-foreground`, `text-white` over footage).
+  - The shimmer highlights with oklch(var(--brand-1)) when brand pops are present; degrades to currentColor.
+  - prefers-reduced-motion swaps the sweep for a gentle opacity pulse.
+  - Announces via role="status"; the label is always available to screen readers.

package/components/ui/input.md

@@ -3,7 +3,8 @@ name: Input
 import: "@gradeui/ui"
 props:
   - type?: string (text | email | password | number | search | url | tel | date)
-  - size?: "default" | "sm" | "xs" — control density. `default` (h-9) for forms; `sm` (h-8) and `xs` (h-7) for dense tool panels like the inspector.
+  - placeholder?: string — hint text shown while the input is empty. Model it explicitly (not just a native passthrough) so generated screens carry placeholders and the validator accepts them.
+  - size?: "default" | "sm" | "xs" — control density. `default` (h-9) for forms; `sm` (h-8) and `xs` (h-7) for dense tool panels like the inspector. NOTE: pre-unification scale — see Figma parity audit; due to migrate to the t-shirt scale (xs 24 | sm 28 | md 32 | lg 40, default→md).
   - startSlot?: ReactNode — adornment rendered inside the leading edge (icon, prefix, currency symbol). Non-interactive by default so clicks focus the input.
   - endSlot?: ReactNode — adornment rendered inside the trailing edge (unit like "px", a clear button, a stepper). Same pointer rules as startSlot.
   - All native input HTML attrs (value, onChange, placeholder, disabled, required)

package/components/ui/logo.md

@@ -3,9 +3,12 @@ name: Logo
 import: "@gradeui/ui"
 subcomponents: []
 props:
-  - sources: LogoSources (required) — artwork keyed by lockup then appearance:
+  - sources?: LogoSources — artwork keyed by lockup then appearance:
       { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
-      Each slot is any node (inline <svg>, <img>, component).
+      Each slot is any node (inline <svg>, <img>, component). OMIT ENTIRELY
+      and the GRADE MARK renders (the square G-arrow, painted with
+      currentColor so it sits correctly on any surface). A bare <Logo /> is
+      always correct branding.
   - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
   - mode?: "light" | "dark" (default "light") — the background the logo sits on
   - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)
@@ -14,19 +17,31 @@ props:
   - decorative?: boolean — aria-hidden when the name is already nearby
   - href?: string — renders the logo as a link (logo-links-home)
   - className?: string
-when_to_use: A brand mark with built-in variations — a square mark for tight
-  spaces, a horizontal lockup for headers, monochrome for busy/inverted
-  surfaces. Reach for Logo in toolbars, sidenav headers, and footers instead
-  of dropping a bare <img>, so the lockup and on-dark/on-light treatment are
-  switchable by prop. The artwork is supplied by the consumer; Logo just picks
-  the right slot for the context.
-composes_with: [AppShell, AppShellHeader, Sidebar, SidebarHeader, Row, Stack]
-aliases: [logo, brand, brandmark, wordmark, lockup, brand logo, app logo, logotype]
+when_to_use: ALWAYS use <Logo> wherever a screen carries a brand mark —
+  app-shell headers, sidenav headers, toolbars, footers, sign-in pages, hero
+  navs, splash states, Motion network-bug overlays. NEVER fake a brand with
+  placeholder text, initials in a circle, a generic lucide icon, or a bare
+  <img>. When the user hasn't named a brand or supplied artwork, render a
+  bare <Logo /> — it defaults to the GRADE mark (the square G-arrow), which
+  is the intended branding for unbranded screens. When the user names their
+  own brand, pass their artwork via `sources` (with a `label`). Built-in
+  variations — square for tight spaces, horizontal lockup for headers,
+  monochrome for busy/inverted surfaces — all switchable by prop.
+composes_with: [AppShell, AppShellHeader, Sidebar, SidebarHeader, Toolbar, MotionOverlay, Row, Stack]
+aliases: [logo, brand, brandmark, wordmark, lockup, brand logo, app logo, logotype, grade mark, g arrow]
 ---
 
 ```jsx
-// Sidenav header: square mark when collapsed, horizontal when expanded.
-// Supply your own artwork per slot; here inline SVGs stand in.
+// THE DEFAULT — no brand named, no artwork supplied: the Grade mark.
+// Size it and set the surrounding text colour; nothing else needed.
+<Row gap="sm" align="center" className="text-foreground">
+  <Logo lockup="square" size="sm" decorative />
+  <span className="text-sm font-semibold">Grade</span>
+</Row>
+```
+
+```jsx
+// A branded screen: supply the brand's own artwork per slot.
 <Logo
   lockup="horizontal"
   mode="dark"
@@ -40,8 +55,21 @@ aliases: [logo, brand, brandmark, wordmark, lockup, brand logo, app logo, logoty
 />
 ```
 
+```jsx
+// In a Motion's broadcast layer — the network bug is a Logo, not a div.
+<MotionOverlay zone="top-right">
+  <span className="text-white">
+    <Logo lockup="square" size="sm" label="Grade" />
+  </span>
+</MotionOverlay>
+```
+
 ### Anti-patterns
 
+DO NOT fake a brand mark with initials in a circle, placeholder text like
+"LOGO", or a generic lucide icon — `<Logo />` with no props IS the correct
+unbranded default (it renders the Grade mark).
+
 DO NOT drop a bare `<img src="logo.png">` in a toolbar/sidenav/footer when you
 want light/dark or square/horizontal switching — use `<Logo>` so the variant
 is a prop.

package/components/ui/map.md

@@ -4,16 +4,22 @@ import: "@gradeui/ui"
 subcomponents: [MapMarker]
 aliases: [map, maps, mapbox, maplibre, google maps, geo, location, latlng, coordinates, marker, pin, airbnb, listings, fleet, real estate, logistics, map view, mapkit, mapview, react native maps, rn maps]
 props:
-  - provider — "maplibre" (default, free, no key) | "mapbox" (needs accessToken) | "google" (needs apiKey). Switching is one prop change.
-  - center — `[lng, lat]` tuple. ALWAYS lng first. Required.
-  - zoom — number, 0–22. Required.
-  - bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
-  - appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
-  - hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
-  - interactive — false freezes pan/zoom, useful for static cards.
-  - onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
-  - tilerKey (maplibre) — only needed off `gradeui.com`/`localhost`. Default key is referrer-locked.
-  - accessToken (mapbox), apiKey (google) — required for those providers.
+  - Map: provider — "maplibre" (default, free, no key) | "mapbox" (needs accessToken) | "google" (needs apiKey). Switching is one prop change.
+  - Map: center — `[lng, lat]` tuple. ALWAYS lng first. Required.
+  - Map: zoom — number, 0–22. Required.
+  - Map: bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
+  - Map: appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
+  - Map: hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
+  - Map: interactive — false freezes pan/zoom, useful for static cards.
+  - Map: onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
+  - Map: tilerKey? — MapLibre only (provider="maplibre"). Optional everywhere: omit on `gradeui.com`/`localhost` and the referrer-locked demo key is used; set it only when embedding off-domain. The contract never requires it.
+  - Map: accessToken? — Mapbox only. Pass it whenever provider="mapbox" — the component itself enforces this at runtime (throws a clear `provider="mapbox" requires an accessToken prop` error via onError if missing). It is OPTIONAL in the contract on purpose, so the validator never demands it from maplibre/google maps.
+  - Map: apiKey? — Google only. Pass it whenever provider="google" — the component enforces it at runtime (throws `provider="google" requires an apiKey prop` via onError if missing). OPTIONAL in the contract on purpose, so it's never demanded from maplibre/mapbox.
+  - MapMarker: id — string. Required. Stable marker id; pair with Map's `hoveredId` for list↔map hover sync.
+  - MapMarker: at — `[lng, lat]` tuple. Required. THE coordinate prop. ALWAYS lng first. The prop is literally named `at` — it is NOT `lngLat`, `coordinates`, `position`, `latLng`, `center`, or separate `lng`/`lat` props. Passing any other name leaves the marker coord `undefined`, and MapLibre throws on mount, crashing the WHOLE screen in every renderer. When in doubt, copy the `airbnb-listings` scaffold: `<MapMarker id={l.id} at={l.coords}>`.
+  - MapMarker: anchor — "center" | "bottom" (default "bottom", pin tip sits on the coord). Only these two values.
+  - MapMarker: onClick — handler called with `({ id, coords, native })` on marker click.
+  - MapMarker: children — DOM rendered as the marker (Badge, Card, Avatar, or any element). Inherits `--gds-*` tokens.
 when_to_use: Any layout that needs a real map — listings (real estate, Airbnb-style), fleet/logistics dashboards, store locators, anywhere a user picks a location from a viewport. Reach for the controlled `hoveredId` prop when a sibling list and the map need to highlight each other.
 composes_with: [Card (as marker content), Badge, Avatar, Button, Row, Stack, Skeleton]
 ---
@@ -69,8 +75,11 @@ Provider swap — one line:
 <Map provider="google" apiKey={env.GOOGLE_MAPS_KEY} center={[-0.1, 51.5]} zoom={11} />
 ```
 
+The contract is deliberately provider-AGNOSTIC. `tilerKey`, `accessToken`, and `apiKey` are all OPTIONAL in the contract so any valid provider config validates — a maplibre map needs no key on-domain, a mapbox map carries `accessToken`, a google map carries `apiKey`, and none of them trip a `missing-required` error for a key another provider uses. The knowledge of which key a provider needs lives in the component/adapter at runtime, not the static contract: maplibre falls back to the referrer-locked demo key; mapbox throws `provider="mapbox" requires an accessToken prop`; google throws `provider="google" requires an apiKey prop` — each surfaced via `onError({ code: "api-key-missing" })`. Maintainers: do NOT re-mark these credentials required in the contract — that's the bug that blanket-required all three and broke on-domain maplibre maps.
+
 ANTI-PATTERNS — don't do these:
 
+- DO NOT name the marker coordinate prop anything other than `at`. It is `<MapMarker id="…" at={[lng, lat]} />` — NOT `lngLat`, `coordinates`, `position`, `latLng`, or `center`. A wrong name passes JSX validation (the validator only checks `<Map>`'s contract, not subcomponent prop names) but registers an `undefined` coord, so MapLibre throws on mount and the whole screen fails to render.
 - DO NOT pass `{ lat, lng }` objects. Coordinates are ALWAYS `[lng, lat]` tuples. Google's adapter handles the object conversion internally.
 - DO NOT hand-roll an iframe with a Google Maps embed URL. Use `<Map provider="google" apiKey={...}>`.
 - DO NOT use `useRef` + `mapRef.current.flyTo(id)` on list-hover when `hoveredId` already does it controlled.

package/components/ui/motion.md

@@ -0,0 +1,109 @@
+---
+name: Motion
+import: "@gradeui/ui"
+subcomponents: [MotionScene, MotionScreen, MotionText]
+props:
+  - view?: "play" | "strip" (default "play") — play runs the film; strip lays
+      scenes out left-to-right as labelled cards (the arrangement view).
+  - aspect?: "auto" | "16/9" | "9/16" | "1/1" (default "auto") — fixed artboard
+      aspect, letterboxed into the container. "9/16" is the TikTok / Reels /
+      Shorts format; "auto" fills responsively. Strip cards adopt the ratio.
+  - stage?: string — CSS background of the persistent stage behind every scene.
+  - backdrop?: React.ReactNode — live layer behind all scenes (image, gradient, <ThreeScene>).
+  - autoplay?: boolean (default true)
+  - loop?: boolean (default false — a motion is a movie, it ends)
+  - controls?: boolean (default true) — play/pause, restart, scene dots (random access)
+  - children: <MotionScene> elements, in order.
+  - "MotionScene: label?, durationMs? (MINIMUM runtime; the whole clock when
+      nothing inside keeps time, default 4000), fill? (scene background over
+      the stage — e.g. a white title card), transition? ('fade' | 'slide-up' |
+      'slide-down' | 'slide-left' | 'slide-right' | 'pop' | 'zoom' |
+      'wipe-circle' (a circular mask wipe) | 'none' — how the scene ARRIVES.
+      The OUTGOING scene stays visible as a frozen layer UNDERNEATH for the
+      transition window, so slides reveal it and wipes cut through it),
+      transitionMs? (timing override; each transition has a sensible
+      default), children (ANY JSX)."
+  - "MotionScreen: device? ('desktop' | 'mobile'), shots? (its OWN ScreenAnimator
+      camera), virtualWidth?, spotlight?, cursor?, enter? (default FALSE —
+      the offscreen fly-in reads badly inside a small frame; use scene
+      transition / animate for entrances), animate? ('rise' |
+      'tilt-settle' — entrances; 'float' | 'drift' — ambient loops; 'none'
+      default — animates the FRAME in place within the scene, composable with
+      the camera inside; pair entrances with enter={false}), screenId?
+      (provenance, ignored at render), children (the screen content, copied in)."
+  - "MotionText: template? ('title' | 'lower-third' | 'section-break' |
+      'broadcast' — the TV-style full-width brand-blue band that sits over
+      the screen | 'ticker' — a news-style marquee bar pinned to the very
+      bottom: heading is the uppercase label chip, text scrolls in an
+      infinite loop | 'stat' — an oversized statistic slate: heading is the
+      number slamming in at up to 180px, text is the label fading up below |
+      'quote' — an editorial pull-quote with a decorative oversized opening
+      mark: heading is the quote, text the em-dash attribution), heading,
+      text?, durationMs?, tone? ('light' | 'dark'). 'ticker' pairs well
+      inside MotionOverlay zone='bottom' for a film-level ticker that runs
+      across every scene."
+  - "MotionOverlay: the BROADCAST layer — a peer of MotionScene inside
+      <Motion> that renders above every scene for the film's runtime:
+      network-bug logo, live wall clock (which keeps ticking when playback
+      pauses — better-than-video proof it's live), ticker, persistent
+      video. zone? ('top-left' | 'top' | 'top-right' | 'center' |
+      'bottom-left' | 'bottom' | 'bottom-right' | 'lower-third'),
+      fromScene?/toScene? (scene-range visibility — overlays are a second
+      timeline; defaults = always on), interactive? (re-enable pointer
+      events), children (any JSX)."
+when_to_use: A directed sequence of scenes on one persistent stage — the
+  text → demo → video → text grammar of a modern product demo. A scene is a
+  stage MOMENT holding arbitrary JSX; screens go inside scenes via
+  <MotionScreen> (each with its own camera — two side by side shows
+  mobile + desktop), templated text via <MotionText>, video/images as plain
+  children. A scene advances when all its timed children finish (camera tours,
+  text templates), or after durationMs when nothing keeps time. Use
+  <ScreenAnimator> alone for a single directed screen; use <Motion> the moment
+  there's a sequence.
+composes_with: [ScreenAnimator, ThreeScene, VideoPlayer, AppShell, the whole component set (scenes hold screens)]
+aliases: [motion, grade motion, scenes, sequence, demo reel, product video, launch video, title card, lower third, section break, multi-scene, storyboard]
+---
+
+```jsx
+// Title card → dashboard at two viewports → video clip. One stage throughout.
+<Motion>
+  <MotionScene label="Hook">
+    <MotionText template="title" heading="Meet the new pipeline" text="From prompt to product" />
+  </MotionScene>
+  <MotionScene label="Dashboard">
+    <MotionScreen device="mobile" shots={[{ zoom: 1, hold: 2000 }, { zoom: 2, cx: 0.5, cy: 0.25, hold: 2400, label: "Live on mobile" }]}>
+      <DashboardMobile />
+    </MotionScreen>
+    <MotionScreen shots={[{ zoom: 1, hold: 2400 }, { zoom: 2.2, cx: 0.22, cy: 0.3, hold: 2600, label: "Revenue up 24%" }]}>
+      <Dashboard />
+    </MotionScreen>
+  </MotionScene>
+  <MotionScene label="Proof">
+    <MotionText template="stat" heading="4.2x" text="Faster from prompt to product" />
+  </MotionScene>
+  <MotionScene label="Word">
+    <MotionText template="quote" heading="It feels like the demo directs itself." text="Head of Design, Acme" />
+  </MotionScene>
+  <MotionScene label="Clip" durationMs={6000}>
+    <video src="/clip.mp4" autoPlay muted style={{ borderRadius: 12, maxWidth: "70%" }} />
+    <MotionText template="ticker" heading="Live" text="Grade Motion ships scene transitions, broadcast overlays and a directed camera" />
+  </MotionScene>
+</Motion>
+```
+
+### Anti-patterns
+
+DO NOT wrap a whole scene in <ScreenAnimator> — the camera belongs to each
+<MotionScreen> inside the scene, not to the scene. A scene with two screens
+has two cameras.
+
+durationMs is a MINIMUM runtime, not just a fallback: a scene with a 3s
+lower-third and `durationMs={16000}` runs the full 16s (the caption ending
+early never cuts a long visual mid-flight). Timed children can extend a
+scene PAST the floor; with no timed children, durationMs is the whole clock.
+
+DO NOT use it as a layout wrapper — like ScreenAnimator it positions
+`absolute inset-0` and takes over the frame.
+
+DO NOT worry about reduced motion — the play view falls back to the strip
+(see everything, move nothing).

package/components/ui/screen-animator.md

@@ -0,0 +1,54 @@
+---
+name: ScreenAnimator
+import: "@gradeui/ui"
+subcomponents: []
+props:
+  - shots?: Array<{ zoom?, cx?, cy?, hold?, trans?, label? }> — the tour. Each
+      shot is a zoom (1 = fit, >1 push in), focal point cx/cy (0..1 fractions of
+      the content), hold (ms dwell), trans (ms glide-in), and a caption label.
+      Omit for a static framed view.
+  - autoplay?: boolean (default true)
+  - loop?: boolean (default true) — fly in → shots → back to start → exit → repeat
+  - controls?: boolean (default true) — play / pause / restart transport
+  - spotlight?: boolean (default false) — opt in to dim the edges (vignette) when pushed in
+  - cursor?: boolean (default true) — synthetic cursor pulse on detail shots
+  - enter?: boolean (default true) — fly in from offscreen on start
+  - stage?: string — CSS background of the stage behind the screen (default dark)
+  - backdrop?: React.ReactNode — a live layer behind the content (image, gradient, or a <ThreeScene> shader)
+  - className?: string
+  - children: React.ReactNode (the screen to animate)
+when_to_use: Wrap ANY screen or section in a directed camera — a "live demo
+  director". Give it a list of shots and it tours them (zoom + pan) over the
+  live, still-interactive content, with a focus spotlight, captions, a synthetic
+  cursor, and play/pause. Use it to turn a built screen into an auto-playing
+  product demo (embed it, or drop it on a marketing page). It's the live,
+  editable, re-renderable answer to a screen-recording video.
+composes_with: [AppShell, ThreeScene, Card, Grid, the whole component set (it wraps a screen)]
+aliases: [screen animator, camera, camera tour, director, demo, product demo, zoom pan, spotlight, ken burns, presenter]
+---
+
+```jsx
+// Wrap a live screen; the camera tours the shots and loops.
+<ScreenAnimator
+  shots={[
+    { zoom: 1, cx: 0.5, cy: 0.5, hold: 2400, label: "Overview" },
+    { zoom: 2.4, cx: 0.2, cy: 0.34, hold: 2600, label: "Revenue up 24%" },
+    { zoom: 1.8, cx: 0.5, cy: 0.6, hold: 2800, label: "Pipeline" },
+  ]}
+  backdrop={<ThreeScene preset="aurora" />}
+>
+  <Dashboard />
+</ScreenAnimator>
+```
+
+### Anti-patterns
+
+DO NOT use it as a layout wrapper — it positions `absolute inset-0` and takes
+over the frame. It's for a whole screen/section you want to direct, not a div.
+
+DO NOT hand-tune `trans`/`hold` per shot unless you need to — the defaults
+(soft settle on overview, snappier push on detail) read well. `cx`/`cy` are the
+knobs that matter; they're fractions of the screen (0 = left/top, 0.5 = centre).
+
+DO NOT worry about reduced motion — it settles on the starter frame and stops
+moving automatically under `prefers-reduced-motion`.