Production-ready animations, transitions, backgrounds, and scenes for Remotion
TypeScript ai-agentsclaude-codedemo-videomcpmcp-servermodel-context-protocolmotion-designproduct-demoreactremotionshadcnvideo
feat: rewrite
dev_wandry883fedd2d8d5
diff --git a/content/docs/ui/button.mdx b/content/docs/ui/components/button.mdxsimilarity index 98%rename from content/docs/ui/button.mdxrename to content/docs/ui/components/button.mdxindex 26a1b2d4..cd6e1cf1 100644--- a/content/docs/ui/button.mdx+++ b/content/docs/ui/components/button.mdx@@ -61,7 +61,7 @@ export const Scene = () => {};```-Each `at` is a **Sequence-local authored frame**. State persists between steps: `hover` at frame 8 keeps the button lifted until `press` fires at frame 20. See the [ui tier intro](/docs/ui) for the full `useCurrentState` API.+Each `at` is a **Sequence-local authored frame**. State persists between steps: `hover` at frame 8 keeps the button lifted until `press` fires at frame 20. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.## Smooth transitions (opt-in)diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.jsonnew file mode 100644index 00000000..e1a41f65--- /dev/null+++ b/content/docs/ui/components/meta.json@@ -0,0 +1,5 @@+{+ "title": "Components",+ "collapsible": false,+ "pages": ["button", "spinner"]+}diff --git a/content/docs/ui/spinner.mdx b/content/docs/ui/components/spinner.mdxsimilarity index 100%rename from content/docs/ui/spinner.mdxrename to content/docs/ui/components/spinner.mdxdiff --git a/content/docs/ui/concepts.mdx b/content/docs/ui/concepts.mdxnew file mode 100644index 00000000..6febd735--- /dev/null+++ b/content/docs/ui/concepts.mdx@@ -0,0 +1,161 @@+---+title: Concepts+description: The mental model behind remocn-ui primitives — atoms, timeline hooks, theming, and core exports+---++## Two kinds of atom++### State atoms++**State atoms** (Button, Input, Checkbox, Switch) are pure visual functions of `(state | style, theme)`. They read no frame, hold no internal clock, and snap instantly between named states. The component accepts either a `state` (named preset, snap path) or a `style` (resolved, interpolated visual, smooth path) — but never reads the frame itself. The state or style value comes from outside: a direct prop, `useCurrentState`, or a transition hook (see below).++**Purity boundary:** `useCurrentFrame()` is never called inside a state atom. Frame resolution happens in the caller — either in `useCurrentState`, `useStateTransition`, or a component's transition hook like `useButtonTransition`. This keeps every state atom safe as a pure renderer.++### Motion atoms++**Motion atoms** (Spinner) loop on `useCurrentFrame()` with no discrete states. They are pure functions of the frame and safe in Remotion's headless renderer — no `Date`, no `Math.random`, no `requestAnimationFrame`. Spinner is the first motion atom in this tier.++## Timeline hooks++### `useCurrentState` — snap resolution++`useCurrentState` resolves the current state as a **latest-step-wins fold**: it scans the steps array and returns the `state` of the last step whose `at` is at or before the current effective frame.++```ts+function useCurrentState<S extends string>(+ steps: Step<S>[],+ defaultState: S,+ speed?: number,+): S+```++- `defaultState` is returned before the first step fires.+- `speed` scales the playhead: `effectiveFrame = currentFrame * speed`. A step at `{ at: 30 }` with `speed: 2` activates at render frame 15.+- `at` values are always **Sequence-local authored frames** — if the component sits inside `<Sequence from={30}>`, Remotion shifts the playhead automatically.++### `useStateTransition` — smooth resolution++`useStateTransition` is the lower-level resolver used by transition hooks. It returns the `from` state, the `to` state, and a `progress` value (0 → 1) over the transition window. Transition hooks call this and blend the visuals; you generally do not call it directly.++```ts+function useStateTransition<S extends string>(+ steps: Step<S>[],+ defaultState: S,+ speed?: number,+ defaultDuration?: number,+): { from: S; to: S; progress: number }+```++- `defaultDuration` — frames to animate into a step that omits `duration`. Defaults to `8`.+- `progress` ramps from 0 to 1 over `[step.at, step.at + duration)`, then holds at 1.+- Ties on `at` resolve later-array-wins (same as `useCurrentState`).++### `Step`++```ts+interface Step<S extends string = string> {+ /** Sequence-local frame at which this state becomes active. */+ at: number;+ /** The state value to enter at this frame. */+ state: S;+ /** Frames to animate the transition INTO this state. Omitted → caller's defaultDuration. */+ duration?: number;+}+```++`duration` is consumed by `useStateTransition` (and transition hooks). `useCurrentState` ignores it — snap resolution has no concept of transition length.++## States snap by default++State atoms snap instantly between named states — no automatic cross-fade or enter-tween. Snap is the default and cheapest path: author `{ at: N, state: "hover" }` and the atom jumps straight to that visual at frame N.++## Smooth transitions — opt-in via transition hooks++Each state atom ships a **transition file** (e.g. `use-button-transition.ts`) that is copied into your project alongside the component. That file:++- owns `DEFAULT_DURATION` and easing+- exports a `use<Name>Transition(steps, opts?) → <Name>Style` hook+- calls `useStateTransition` internally and interpolates between state presets++To get smooth motion, call the hook in your composition and feed the result to the component's `style` prop:++```tsx+import { Button } from "@/components/remocn/button";+import { useButtonTransition } from "@/components/remocn/use-button-transition";++export const Scene = () => {+ const style = useButtonTransition([+ { at: 12, state: "hover" },+ { at: 30, state: "press" },+ { at: 48, state: "loading", duration: 6 },+ ]);+ return <Button label="Continue" style={style} />;+};+```++To tune timing globally, edit `DEFAULT_DURATION` in your copied `use-button-transition.ts`. To tune a single transition, add `duration` to that step — it overrides the file default for that transition only. To tune easing, edit the `easings.out(progress)` call in the same file.++## Theming++The `ui` tier uses a JS theme object with stock shadcn token names. Values are concrete oklch strings — not CSS custom properties.++```ts+import type { RemocnTheme } from "@/lib/remocn-ui";++// All tokens match shadcn's default neutral palette out of the box+const myTheme: Partial<RemocnTheme> = {+ primary: "oklch(0.55 0.2 250)", // override just what you need+ radius: 6,+};+```++### `RemocnUIProvider`++Wrap your composition (or a subtree) in `RemocnUIProvider` to set a theme and/or mode for all nested `ui` primitives:++```tsx+import { RemocnUIProvider } from "@/lib/remocn-ui";++export const Scene = () => (+ <RemocnUIProvider mode="dark" theme={{ primary: "oklch(0.6 0.22 260)" }}>+ <Button state={buttonState} label="Continue" />+ <UICheckbox label="Remember me" state={checkState} />+ </RemocnUIProvider>+);+```++Token resolution order (highest wins): per-component `theme` prop > `RemocnUIProvider` theme > `defaultLightTheme` / `defaultDarkTheme` per `mode`. The `mode` prop on a component wins over `RemocnUIProvider`'s `mode`.++Available exports from `lib/remocn-ui`:++| Export | Type | Description |+|---|---|---|+| `RemocnUIProvider` | Component | Context provider for theme and mode |+| `useRemocnTheme` | Hook | Resolves the active theme inside a component |+| `defaultLightTheme` | `RemocnTheme` | Stock shadcn neutral light palette |+| `defaultDarkTheme` | `RemocnTheme` | Stock shadcn neutral dark palette |+| `RemocnTheme` | Interface | Full token shape with `radius: number` |++### Animated colors require concrete JS values++<Warning>+CSS custom properties (`var(--primary)`) work for **static** styling only. Remotion's headless per-frame renderer cannot resolve `var(...)` for JS interpolation. If you pass `var(--primary)` as an animated token, `parseColor` will warn in dev mode and fall back to the JS default theme value — not your CSS override.++To override an animated color, pass a concrete oklch, hex, or rgb value via the `theme` prop or `RemocnUIProvider`. Static colors (borders, backgrounds that never animate) can safely use `var()` in `style` props.+</Warning>++A project whose `:root` overrides `--primary` will see static elements pick up the CSS variable correctly, but state-dependent visuals (hover background, press darkening) will use the JS theme default. The defaults match stock shadcn, so unless you have custom colors, you will not notice the difference — but if you do have custom colors, supply them through the JS theme.++## Core library exports++Installing any component in this tier also installs `lib/remocn-ui/` with these modules:++| Module | Key exports |+|---|---|+| `timeline.ts` | `useCurrentState`, `useStateTransition`, `framesFor`, `revealCount` |+| `theme.ts` | `RemocnUIProvider`, `useRemocnTheme`, `defaultLightTheme`, `defaultDarkTheme` |+| `color.ts` | `mixOklch`, `parseColor`, `oklchToRgb`, `rgbToOklch`, `toCss` |+| `motion.ts` | `easings`, `springs` |+| `types.ts` | `Step` (with optional `duration`) |++You can import from `@/lib/remocn-ui` (the barrel) or from the individual module paths.diff --git a/content/docs/ui/index.mdx b/content/docs/ui/index.mdxindex bb33da3a..300d91f7 100644--- a/content/docs/ui/index.mdx+++ b/content/docs/ui/index.mdx@@ -1,9 +1,9 @@----title: UI+title: Introductiondescription: shadcn-style primitives scripted on the Remotion timeline----The `ui` tier brings familiar shadcn components — Button, Input, Checkbox, Switch — into Remotion video. Instead of responding to mouse events, their interactions are **scripted on the timeline**: you declare what state a component is in and when, and it renders that state as a deterministic pure function of `useCurrentFrame()`.+The `ui` tier brings familiar shadcn components — Button, Input, Checkbox, Switch, Spinner — into Remotion video. Instead of responding to mouse events, their interactions are **scripted on the timeline**: you declare what state a component is in and when, and it renders that state as a deterministic pure function of `useCurrentFrame()`.No `useState`. No event handlers. No CSS transitions. Every pixel is a function of the current frame — which is exactly what Remotion's headless per-frame renderer requires.@@ -13,207 +13,7 @@ In a browser, a button enters its loading state because the user clicked. In a vThis also means you get things that are impossible in a real UI: scrub backward through a form fill, play a button click at half speed, or loop a checkbox toggle indefinitely — all without any special setup.-## Installation+## Where to go next-Each component installs via the standard shadcn CLI. The shared `remocn-ui` core installs automatically as a `registryDependencies` entry — you do not need to install it separately.--```bash-npx shadcn add @remocn/button-```--This writes `components/remocn/button.tsx` and `lib/remocn-ui/` to your project. Every component depends on the same `lib/remocn-ui/` core.--## Two kinds of atom--### State atoms--**State atoms** (Button, Input, Checkbox, Switch) are pure visual functions of `(state | style, theme)`. They read no frame, hold no internal clock, and snap instantly between named states. The component accepts either a `state` (named preset, snap path) or a `style` (resolved, interpolated visual, smooth path) — but never reads the frame itself. The state or style value comes from outside: a direct prop, `useCurrentState`, or a transition hook (see below).--**Purity boundary:** `useCurrentFrame()` is never called inside a state atom. Frame resolution happens in the caller — either in `useCurrentState`, `useStateTransition`, or a component's transition hook like `useButtonTransition`. This keeps every state atom safe as a pure renderer.--### Motion atoms--**Motion atoms** (Spinner) loop on `useCurrentFrame()` with no discrete states. They are pure functions of the frame and safe in Remotion's headless renderer — no `Date`, no `Math.random`, no `requestAnimationFrame`. Spinner is the first motion atom in this tier.--## Timeline hooks--### `useCurrentState` — snap resolution--`useCurrentState` resolves the current state as a **latest-step-wins fold**: it scans the steps array and returns the `state` of the last step whose `at` is at or before the current effective frame.--```ts-function useCurrentState<S extends string>(- steps: Step<S>[],- defaultState: S,- speed?: number,-): S-```--- `defaultState` is returned before the first step fires.-- `speed` scales the playhead: `effectiveFrame = currentFrame * speed`. A step at `{ at: 30 }` with `speed: 2` activates at render frame 15.-- `at` values are always **Sequence-local authored frames** — if the component sits inside `<Sequence from={30}>`, Remotion shifts the playhead automatically.--### `useStateTransition` — smooth resolution--`useStateTransition` is the lower-level resolver used by transition hooks. It returns the `from` state, the `to` state, and a `progress` value (0 → 1) over the transition window. Transition hooks call this and blend the visuals; you generally do not call it directly.--```ts-function useStateTransition<S extends string>(- steps: Step<S>[],- defaultState: S,- speed?: number,- defaultDuration?: number,-): { from: S; to: S; progress: number }-```--- `defaultDuration` — frames to animate into a step that omits `duration`. Defaults to `8`.-- `progress` ramps from 0 to 1 over `[step.at, step.at + duration)`, then holds at 1.-- Ties on `at` resolve later-array-wins (same as `useCurrentState`).--### `Step`--```ts-interface Step<S extends string = string> {- /** Sequence-local frame at which this state becomes active. */- at: number;- /** The state value to enter at this frame. */- state: S;- /** Frames to animate the transition INTO this state. Omitted → caller's defaultDuration. */- duration?: number;-}-```--`duration` is consumed by `useStateTransition` (and transition hooks). `useCurrentState` ignores it — snap resolution has no concept of transition length.--## Usage patterns--### Controlled (canonical)--Pass a state value directly — useful when you want to drive the component from your own logic:--```tsx-import { Button } from "@/components/remocn/button";--// Always shows the loading state-export const Scene = () => <Button state="loading" />;-```--### Timeline-driven--Drive state from the Remotion timeline via `useCurrentState`:--```tsx-import { useCurrentState } from "@/lib/remocn-ui";-import { Button } from "@/components/remocn/button";--export const Scene = () => {- const state = useCurrentState(- [- { at: 8, state: "hover" },- { at: 20, state: "press" },- { at: 35, state: "loading" },- { at: 70, state: "success" },- ],- "idle",- );-- return <Button state={state} />;-};-```--The `at` value is a **Sequence-local authored frame** throughout. State persists between steps: `hover` at frame 8 keeps the button lifted all the way until `press` at frame 20, with no extra bookkeeping.--## States snap by default--State atoms snap instantly between named states — no automatic cross-fade or enter-tween. Snap is the default and cheapest path: author `{ at: N, state: "hover" }` and the atom jumps straight to that visual at frame N.--## Smooth transitions — opt-in via transition hooks--Each state atom ships a **transition file** (e.g. `use-button-transition.ts`) that is copied into your project alongside the component. That file:--- owns `DEFAULT_DURATION` and easing-- exports a `use<Name>Transition(steps, opts?) → <Name>Style` hook-- calls `useStateTransition` internally and interpolates between state presets--To get smooth motion, call the hook in your composition and feed the result to the component's `style` prop:--```tsx-import { Button } from "@/components/remocn/button";-import { useButtonTransition } from "@/components/remocn/use-button-transition";--export const Scene = () => {- const style = useButtonTransition([- { at: 12, state: "hover" },- { at: 30, state: "press" },- { at: 48, state: "loading", duration: 6 },- ]);- return <Button label="Continue" style={style} />;-};-```--To tune timing globally, edit `DEFAULT_DURATION` in your copied `use-button-transition.ts`. To tune a single transition, add `duration` to that step — it overrides the file default for that transition only. To tune easing, edit the `easings.out(progress)` call in the same file.--## Theming--The `ui` tier uses a JS theme object with stock shadcn token names. Values are concrete oklch strings — not CSS custom properties.--```ts-import type { RemocnTheme } from "@/lib/remocn-ui";--// All tokens match shadcn's default neutral palette out of the box-const myTheme: Partial<RemocnTheme> = {- primary: "oklch(0.55 0.2 250)", // override just what you need- radius: 6,-};-```--### `RemocnUIProvider`--Wrap your composition (or a subtree) in `RemocnUIProvider` to set a theme and/or mode for all nested `ui` primitives:--```tsx-import { RemocnUIProvider } from "@/lib/remocn-ui";--export const Scene = () => (- <RemocnUIProvider mode="dark" theme={{ primary: "oklch(0.6 0.22 260)" }}>- <Button state={buttonState} label="Continue" />- <UICheckbox label="Remember me" state={checkState} />- </RemocnUIProvider>-);-```--Token resolution order (highest wins): per-component `theme` prop > `RemocnUIProvider` theme > `defaultLightTheme` / `defaultDarkTheme` per `mode`. The `mode` prop on a component wins over `RemocnUIProvider`'s `mode`.--Available exports from `lib/remocn-ui`:--| Export | Type | Description |-|---|---|---|-| `RemocnUIProvider` | Component | Context provider for theme and mode |-| `useRemocnTheme` | Hook | Resolves the active theme inside a component |-| `defaultLightTheme` | `RemocnTheme` | Stock shadcn neutral light palette |-| `defaultDarkTheme` | `RemocnTheme` | Stock shadcn neutral dark palette |-| `RemocnTheme` | Interface | Full token shape with `radius: number` |--### Animated colors require concrete JS values--<Warning>-CSS custom properties (`var(--primary)`) work for **static** styling only. Remotion's headless per-frame renderer cannot resolve `var(...)` for JS interpolation. If you pass `var(--primary)` as an animated token, `parseColor` will warn in dev mode and fall back to the JS default theme value — not your CSS override.--To override an animated color, pass a concrete oklch, hex, or rgb value via the `theme` prop or `RemocnUIProvider`. Static colors (borders, backgrounds that never animate) can safely use `var()` in `style` props.-</Warning>--A project whose `:root` overrides `--primary` will see static elements pick up the CSS variable correctly, but state-dependent visuals (hover background, press darkening) will use the JS theme default. The defaults match stock shadcn, so unless you have custom colors, you will not notice the difference — but if you do have custom colors, supply them through the JS theme.--## Core library exports--Installing any component in this tier also installs `lib/remocn-ui/` with these modules:--| Module | Key exports |-|---|---|-| `timeline.ts` | `useCurrentState`, `useStateTransition`, `framesFor`, `revealCount` |-| `theme.ts` | `RemocnUIProvider`, `useRemocnTheme`, `defaultLightTheme`, `defaultDarkTheme` |-| `color.ts` | `mixOklch`, `parseColor`, `oklchToRgb`, `rgbToOklch`, `toCss` |-| `motion.ts` | `easings`, `springs` |-| `types.ts` | `Step` (with optional `duration`) |--You can import from `@/lib/remocn-ui` (the barrel) or from the individual module paths.+- [Concepts](/docs/ui/concepts) — the mental model: two kinds of atom, timeline hooks, states, theming, and core exports.+- [Installation](/docs/ui/installation) — add your first component to a Remotion project.diff --git a/content/docs/ui/installation.mdx b/content/docs/ui/installation.mdxnew file mode 100644index 00000000..d174d809--- /dev/null+++ b/content/docs/ui/installation.mdx@@ -0,0 +1,35 @@+---+title: Installation+description: Add remocn-ui primitives to an existing Remotion project via the shadcn CLI+---++## Prerequisites++Remotion must already be set up in your project. remocn-ui does not bootstrap Remotion — it only adds components on top of an existing Remotion setup.++## Install a component++Use the standard shadcn CLI. The shared `remocn-ui` core installs automatically as a `registryDependencies` entry — you do not need to install it separately.++```bash+npx shadcn add @remocn/button+```++This writes two things into your project:++- `components/remocn/button.tsx` — the component and its transition hook+- `lib/remocn-ui/` — the shared core library used by every component in this tier++## Registry dependencies++Some components declare additional `registryDependencies`. For example, a composition that includes a loading indicator will pull in `@remocn/spinner` automatically when you install it. The shadcn CLI resolves and installs the full dependency graph in one command — you only need to name the top-level component you want.++## What gets written++| Path | Contents |+|---|---|+| `components/remocn/<name>.tsx` | The state atom component |+| `components/remocn/use-<name>-transition.ts` | The transition hook for smooth motion (edit `DEFAULT_DURATION` and easing here) |+| `lib/remocn-ui/` | Shared core — timeline hooks, theme, color utilities, motion helpers, types |++All files are copied into your project. You own the code — edit any file freely to suit your video.diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.jsonindex 158e5caa..08a8b990 100644--- a/content/docs/ui/meta.json+++ b/content/docs/ui/meta.json@@ -1,5 +1,5 @@{"title": "UI","collapsible": false,- "pages": ["index", "button", "spinner"]+ "pages": ["index", "concepts", "installation", "components"]}diff --git a/lib/docs-tabs.ts b/lib/docs-tabs.tsindex b8fe0d89..719636e6 100644--- a/lib/docs-tabs.ts+++ b/lib/docs-tabs.ts@@ -51,6 +51,20 @@ function isPrimitivesNode(node: Node): boolean {);}+/**+ * Hoists a matched folder's own index page and children up to the tab root, so+ * the Primitives sidebar reads its pages directly (Introduction / Concepts /+ * Installation / Components) instead of nesting them under a single "UI" group.+ * Non-folder nodes pass through untouched.+ */+function hoistPrimitives(nodes: Node[]): Node[] {+ return nodes.flatMap((node) =>+ node.type === "folder"+ ? [node.index, ...node.children].filter((n): n is Node => Boolean(n))+ : [node],+ );+}+/*** Splits the Fumadocs page tree into the two tab trees. Immutable — the source* `Root` (shared across requests) is never mutated; each branch is a shallow@@ -64,6 +78,9 @@ function isPrimitivesNode(node: Node): boolean {* would never change when `DocsShell` swaps trees on a tab switch, freezing the* sidebar on the first tab until a full page reload. Distinct ids make the dep* differ per tab so the sidebar updates client-side.+ *+ * The Primitives branch is additionally hoisted (see {@link hoistPrimitives}) so+ * the remocn-ui pages render at the sidebar root without a wrapping "UI" label.*/export function splitDocsTree(tree: Root): {components: Root;@@ -78,7 +95,7 @@ export function splitDocsTree(tree: Root): {primitives: {...tree,$id: "docs-tab-primitives",- children: tree.children.filter(isPrimitivesNode),+ children: hoistPrimitives(tree.children.filter(isPrimitivesNode)),},};}