@omerdlw/base-framework 1.0.5 → 2.0.0

package/docs/theming.md

@@ -1,6 +1,6 @@
 # Theming System Guide — `@omerdlw/base-framework/theme`
 
-> **Read this first if you need to:** customize the visual design of any first-party module (`dock`, `modal`, `notification`, etc.), supply custom Tailwind styles, or understand the theme slot contract.
+> **Read this first if you need to:** customize the visual design or the animation of any first-party module (`dock`, `modal`, `notification`, etc.), supply custom Tailwind styles, set your app's motion tempo, or understand the theme slot and motion contracts.
 
 ---
 
@@ -10,6 +10,8 @@
 
 Modules ship with **zero hardcoded visual Tailwind colors or aesthetic choices**. Instead, each module declares a typed **Theme Spec** defining required "slots" (e.g. `card`, `backdrop`, `header`, `item`).
 
+The same holds for **animation**. Modules that animate (`dock`, `modal`, `notification`, `context-menu`, `background`) ship no durations, curves, springs or travel distances. Their spec also declares a typed **motion contract**, and your theme file supplies it next to `slots` (§5). The module keeps only the mechanics: which phase plays when, what comes from layout, and accessibility.
+
 If a required theme is not provided to `<ThemeProvider>`, `useTheme()` throws an informative error at mount time:
 ```
 Theme "dock" is missing. Add its theme configuration to your ThemeProvider.
@@ -33,15 +35,16 @@ import {
 } from "@omerdlw/base-framework/theme";
 ```
 
-### 2.1 `defineThemeSpec<Slots>(id)`
+### 2.1 `defineThemeSpec<Slots, Motion?>(id)`
 Used by module authors to define the contract:
 ```ts
 export type DockThemeSlot = "card" | "header" | "title" | "description" | "icon" | "surface";
-export const dockTheme = defineThemeSpec<DockThemeSlot>("dock");
+export const dockTheme = defineThemeSpec<DockThemeSlot, DockMotion>("dock");
 ```
+The second type parameter is the module's motion contract. Leave it out for a module that doesn't animate (`ambient`, `controls`, `loading`, `error`).
 
-### 2.2 `defineTheme(spec, { slots, styles? })`
-Used by application developers to implement the styling contract. TypeScript enforces that **every required slot** is provided:
+### 2.2 `defineTheme(spec, { slots, styles?, motion })`
+Used by application developers to implement the styling contract. TypeScript enforces that **every required slot** is provided, and that `motion` is given exactly when the spec declares a motion contract (§5):
 ```ts
 export const dockThemeConfig = defineTheme(dockTheme, {
   slots: {
@@ -59,10 +62,10 @@ export const dockThemeConfig = defineTheme(dockTheme, {
 });
 ```
 
-### 2.3 `ThemeProvider({ themes, children })`
-Wraps your application or `CoreProvider` to supply the theme map:
+### 2.3 `ThemeProvider({ themes, motion?, children })`
+Wraps your application or `CoreProvider` to supply the theme map and your motion tokens (§5.1):
 ```tsx
-<ThemeProvider themes={[dockThemeConfig, modalThemeConfig, notificationThemeConfig]}>
+<ThemeProvider themes={[dockThemeConfig, modalThemeConfig, notificationThemeConfig]} motion={appMotion}>
   <CoreProvider modules={modules}>
     {children}
   </CoreProvider>
@@ -165,6 +168,8 @@ export const appThemes = [
 ];
 ```
 
+Modules that animate also need their `motion` (§5): start from the framework's `templates/motion/` and add `motion: dockMotion` and so on next to each `slots`.
+
 Then in `src/app/providers.tsx`:
 
 ```tsx
@@ -173,13 +178,80 @@ Then in `src/app/providers.tsx`:
 import { ThemeProvider } from "@omerdlw/base-framework/theme";
 import { CoreProvider } from "@omerdlw/base-framework/provider";
 import { appThemes } from "@/config/themes";
+import { motion } from "@/config/theme/motion/tokens";
 import { modules } from "@/config/modules";
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <ThemeProvider themes={appThemes}>
+    <ThemeProvider themes={appThemes} motion={motion}>
       <CoreProvider modules={modules}>{children}</CoreProvider>
     </ThemeProvider>
   );
 }
 ```
+
+---
+
+## 5. Motion: Your App Owns Every Animation
+
+Animation is part of your design, so it lives in your theme files like your slots do. The framework applies two things to whatever you write: your **tempo** and your **reduced-motion policy**.
+
+### 5.1 `defineMotion({ tempo?, reducedMotion?, durations?, easings?, springs? })`
+
+```ts
+// src/config/theme/motion/tokens.ts
+import { defineMotion } from "@omerdlw/base-framework/tokens";
+
+export const motion = defineMotion({
+  tempo: 1, // stretches everything a module animates
+  reducedMotion: "user", // "user" (OS setting) | "always" | "never"
+  durations: { fast: 0.28, base: 0.36, slow: 0.58 },
+  easings: { enter: [0.25, 1, 0.5, 1], exit: [0.5, 0, 1, 1] },
+  springs: { press: { type: "spring", stiffness: 420, damping: 34, mass: 0.35 } },
+});
+```
+
+- `durations`, `easings` and `springs` are **your vocabulary**: name them as you like. The framework never reads them. Your module motion files use them, so changing one easing re-times every module that refers to it.
+- `tempo` stretches every duration, delay, stagger and choreography timer the modules play, including the ones you wrote. Springs are retuned to take tempo× as long at the same damping ratio. Write values at tempo 1.
+- Pass the result to `<ThemeProvider motion={motion}>`. App code can read it back with `useMotionTokens()`, which also returns `reduced`: whether reduced motion is in effect. A nested `ThemeProvider` without `motion` keeps the one above it.
+
+### 5.2 Module motion: `defineTheme(spec, { slots, motion })`
+
+Each animating module exports its contract type. Give it a full value, the same way you give `slots`:
+
+| Module | Spec | Contract type | What it holds |
+| :--- | :--- | :--- | :--- |
+| Dock | `dockTheme` | `DockMotion` | `transitions` (stack, expand, surface enter/step/exit/resize, cards, text, header swap, press, …), `variants` (fade, text crossfade, header swap/restore, controls, command bar, badge, hud, …), `deck` (elevation, compress, `peek(position)`, `exit(card)`, `tapScale`), `drag`, `skeleton`, `timings` (surface phase lengths and card staggers, in seconds) |
+| Modal | `modalTheme` | `ModalMotion` | `backdrop`, `content`, `header`, `footer` variants, and `positions` (`center`, `top`, `right`, `bottom`, `left`: variants plus an optional own `transition`) |
+| Notification | `notificationTheme` | `NotificationMotion` | `toast` variants and the toast's `transition` |
+| Context menu | `contextMenuTheme` | `ContextMenuMotion` | `pop`, `content`, `item` variants (`item.visible` may take the row index), `itemTap`, `itemTransition` |
+| Background | `backgroundTheme` | `BackgroundMotion` | `initial`, `animate`, `exit`, `transition`, `exitDurationFactor`. A page's own `background.animation` still wins field by field and follows your tempo too. |
+
+```ts
+// src/config/theme/dock.ts
+import { defineTheme } from "@omerdlw/base-framework/theme";
+import { dockTheme } from "@omerdlw/base-framework/modules/dock";
+import { dockMotion } from "./motion/dock";
+
+export const dockThemeConfig = defineTheme(dockTheme, { slots: { … }, motion: dockMotion });
+```
+
+Variant functions keep their `custom` signature (e.g. `commandBar.visible(index)`, `controlsContainer.hidden(targetY)`), and `deck.peek` / `deck.exit` receive what the dock knows from layout. Everything else about those values is yours.
+
+If an animating module's theme has no `motion`, mounting it throws:
+```
+Motion for theme "dock" is missing. Add `motion` to its defineTheme(...) next to `slots` (start from the framework's templates/motion/).
+```
+`DockProvider` alone (without the dock theme) still runs: its surface phases advance immediately, since nothing is drawn.
+
+### 5.3 The starter: `templates/motion/`
+
+The package ships `templates/motion/` with `tokens.ts`, `dock.ts`, `modal.ts`, `notification.ts`, `context-menu.ts` and `background.ts`. It is a complete starting point (the motion the modules carried before motion moved into apps), type-checked against the module contracts. Copy the folder into your app (e.g. `src/config/theme/motion/`) and make it yours; the framework never reads it.
+
+### 5.4 Reduced motion
+
+Reduced motion is an accessibility mechanic, so the framework handles it once for every module:
+
+- When it is in effect (`reducedMotion: "always"`, or `"user"` with the OS setting on), every module transition, including your own, collapses to `REDUCED_MOTION_TRANSITION` (0.08 s, linear, no delay). Every `timings` entry is capped at 0.08 s, so choreography doesn't hold the dock still on animations that aren't playing.
+- `CoreProvider` wraps every module backdrop and overlay in `ModuleMotionConfig` (Motion's `MotionConfig` with your policy), so positional values (`width`, `height`, `x`, `scale`, …) jump instead of animating. App content outside the modules is untouched and keeps its own `MotionConfig`.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omerdlw/base-framework",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "Microkernel engine and first-party declarative UI modules for app-like Next.js products.",
   "type": "module",
   "sideEffects": false,
@@ -82,6 +82,16 @@
       "import": "./dist/modules/ambient/index.js",
       "default": "./dist/modules/ambient/index.js"
     },
+    "./ambient/server": {
+      "types": "./dist/modules/ambient/server/index.d.ts",
+      "import": "./dist/modules/ambient/server/index.js",
+      "default": "./dist/modules/ambient/server/index.js"
+    },
+    "./ambient/worker": {
+      "types": "./dist/modules/ambient/worker/index.d.ts",
+      "import": "./dist/modules/ambient/worker/index.js",
+      "default": "./dist/modules/ambient/worker/index.js"
+    },
     "./background": {
       "types": "./dist/modules/background/index.d.ts",
       "import": "./dist/modules/background/index.js",
@@ -126,12 +136,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && ./node_modules/.bin/tsup && ./node_modules/.bin/tsc --emitDeclarationOnly --outDir dist",
-    "prepublishOnly": "npm run build",
+    "build": "rm -rf dist && ./node_modules/.bin/tsup && ./node_modules/.bin/tsc --emitDeclarationOnly --outDir dist && node scripts/rewrite-dts-aliases.mjs",
+    "prepublishOnly": "npm run build && npm run test:dist",
     "dev": "./node_modules/.bin/tsup --watch",
-    "type-check": "./node_modules/.bin/tsc --noEmit",
+    "type-check": "./node_modules/.bin/tsc --noEmit && ./node_modules/.bin/tsc -p templates",
     "check:architecture": "node scripts/check-architecture.mjs",
     "test": "node --import ./tests/support/register.mjs --test 'tests/**/*.test.ts'",
+    "test:dist": "node --import ./tests/support/register.mjs --test 'tests/bundle/*.smoke.ts'",
     "pack": "npm run build && npm pack",
     "clean": "rm -rf dist *.tgz"
   },
@@ -139,7 +150,13 @@
     "motion": "^12.0.0 || ^13.0.0",
     "next": ">=15.0.0",
     "react": ">=19.0.0",
-    "react-dom": ">=19.0.0"
+    "react-dom": ">=19.0.0",
+    "sharp": "^0.35.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@iconify-icon/react": "3.0.3",

package/templates/AGENTS.md

@@ -10,7 +10,7 @@
 - **Engine:** Next.js 16 (App Router), React 19
 - **Core Framework:** `@omerdlw/base-framework` (Microkernel & Declarative UI Modules)
 - **Styling:** Tailwind CSS v4 (`@theme`, OKLCH semantic color tokens, `.center`, `.skeleton-block`)
-- **Motion:** Motion (v13) with hardware GPU acceleration (`translate3d`, `scale`)
+- **Motion:** Motion (v13) with hardware GPU acceleration (`translate3d`, `scale`). Framework modules ship no animation of their own: the dock, modal, toast, context-menu and background motion lives in this app's theme files (`motion` next to `slots`), with tempo and vocabulary from `defineMotion`. Change module animation there, never in the framework.
 - **Icons:** `@iconify-icon/react` via `<Icon icon="solar:..." />`
 
 ---

package/templates/motion/background.ts

@@ -0,0 +1,17 @@
+import type { BackgroundMotion } from "@omerdlw/base-framework/modules/background";
+import { motion } from "./tokens";
+
+const { durations, easings } = motion;
+
+// defineTheme(backgroundTheme, { slots, motion: backgroundMotion })
+// A page can still pass its own `background.animation`; it wins field by field.
+export const backgroundMotion: BackgroundMotion = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1 },
+  exit: {
+    opacity: 0,
+    transition: { duration: durations.slow, ease: easings.exit },
+  },
+  transition: { delay: 0, duration: durations.slow, ease: easings.enter },
+  exitDurationFactor: 0.6,
+};

package/templates/motion/context-menu.ts

@@ -0,0 +1,63 @@
+import type { ContextMenuMotion } from "@omerdlw/base-framework/modules/context-menu";
+import { motion } from "./tokens";
+
+const { durations, easings, springs } = motion;
+
+// Rows come in one after another, a short step apart, after the menu opens.
+const rowDelay = (index: unknown) =>
+  0.04 + Math.min(Math.max(Number(index) || 0, 0) * 0.042, 0.21);
+
+const leave = { duration: durations.micro, ease: easings.exit };
+
+// defineTheme(contextMenuTheme, { slots, motion: contextMenuMotion })
+export const contextMenuMotion: ContextMenuMotion = {
+  pop: {
+    hidden: {
+      opacity: 0,
+      transform: "translate3d(0px, 0px, 0) scale(0.96)",
+      transformOrigin: "top left",
+    },
+    visible: {
+      opacity: 1,
+      transform: "translate3d(0px, 0px, 0) scale(1)",
+      transformOrigin: "top left",
+      transition: { duration: durations.fast, ease: easings.emphasized },
+    },
+    exit: {
+      opacity: 0,
+      transform: "translate3d(0px, 0px, 0) scale(0.98)",
+      transformOrigin: "top left",
+      transition: leave,
+    },
+  },
+  content: {
+    hidden: { opacity: 0 },
+    visible: {
+      opacity: 1,
+      transition: { duration: durations.fast, ease: easings.weighted, delay: 0.04 },
+    },
+    exit: { opacity: 0, transition: leave },
+  },
+  item: {
+    hidden: {
+      opacity: 0,
+      transform: "translate3d(0px, 4px, 0) scale(0.992)",
+    },
+    visible: (index: unknown = 0) => ({
+      opacity: 1,
+      transform: "translate3d(0px, 0px, 0) scale(1)",
+      transition: {
+        duration: durations.fast,
+        ease: easings.emphasized,
+        delay: rowDelay(index),
+      },
+    }),
+    exit: {
+      opacity: 0,
+      transform: "translate3d(0px, -3px, 0) scale(0.994)",
+      transition: leave,
+    },
+  },
+  itemTap: { transform: "translate3d(0px, 0px, 0) scale(0.97)" },
+  itemTransition: springs.tap,
+};

package/templates/motion/dock.ts

@@ -0,0 +1,327 @@
+import type { DockMotion } from "@omerdlw/base-framework/modules/dock";
+import {
+  chip,
+  contentSwap,
+  contentSwapTransitions,
+  gpuTransform,
+  overlaySurface,
+  press,
+  staggerDelay,
+  surfaceResizeTransition,
+} from "@omerdlw/base-framework/tokens";
+import { motion, tween } from "./tokens";
+
+const { durations, easings, springs } = motion;
+
+// Dock-only lengths, next to the shared scale.
+const HEADER = 0.32;
+const ACTION_DISMISS = 0.32;
+const COLLAPSE = 0.52;
+
+// A surface opening: the inline action leaves (overlapping the growth a
+// little), the deck compresses for a beat, then the body grows in. Closing
+// runs the other way and the card header comes back last.
+const SURFACE = {
+  anticipation: 0.24,
+  bodyEnter: 0.86,
+  bodyEnterDelay: 0.1,
+  // The header's return: 0.36s in all, of which 0.08s is waiting.
+  headerRestore: 0.36,
+  headerRevealDelay: 0.08,
+  headerReveal: 0.28,
+};
+
+const swap = (duration: number, enterEase: typeof easings.enter) =>
+  contentSwapTransitions({
+    duration,
+    exitDuration: durations.fast,
+    enterEase,
+    exitEase: easings.exit,
+  });
+
+const headerSwap = swap(HEADER, easings.enter);
+const controlSwap = swap(durations.base, easings.enter);
+const textSwap = swap(durations.base, easings.emphasized);
+
+const expand = tween(durations.cinematic, easings.weighted);
+const card = tween(COLLAPSE, easings.enter);
+const cardCollapse = tween(durations.base, easings.exit);
+
+const surfaceBody = overlaySurface({
+  travel: 14,
+  exitTravel: 14,
+  enterScale: 0.985,
+  exitScale: 0.985,
+  duration: SURFACE.bodyEnter - SURFACE.bodyEnterDelay,
+  exitDuration: SURFACE.anticipation,
+  enterEase: easings.weighted,
+  exitEase: easings.weighted,
+});
+
+const pressRole = press({ tapScale: 0.97, spring: springs.press });
+
+const extensionsEnter = tween(durations.moderate, easings.emphasized);
+const extensionsExit = tween(durations.base, easings.exit);
+
+// The STANDARD tier: a crossfade that travels a little under half of 18px.
+const crossfade = {
+  distance: Math.round(18 * 0.42),
+  duration: durations.moderate,
+  scale: 1 - 0.018,
+};
+
+const controlsSlot = (enter: object, exit: object) => ({
+  hidden: { opacity: 0, scale: 0.96, width: 0, marginRight: -2 },
+  visible: { opacity: 1, scale: 1, width: "auto", marginRight: 0, transition: enter },
+  exit: { opacity: 0, scale: 0.96, width: 0, marginRight: -2, transition: exit },
+});
+
+// defineTheme(dockTheme, { slots, motion: dockMotion })
+export const dockMotion: DockMotion = {
+  transitions: {
+    stack: tween(COLLAPSE, easings.enter),
+    expand,
+    surfaceResize: (distancePx) => {
+      const resize = surfaceResizeTransition(distancePx, {
+        base: 0.5,
+        min: 0.4,
+        max: durations.cinematic,
+        ease: easings.weighted,
+      });
+      return { ...resize, height: resize, width: resize };
+    },
+    surfaceArrival: tween(durations.cinematic, easings.overshoot),
+    anticipation: tween(SURFACE.anticipation, easings.weighted),
+    surfaceEnter: { ...surfaceBody.visible.transition, delay: SURFACE.bodyEnterDelay },
+    surfaceStep: swap(durations.base, easings.enter).enter,
+    surfaceExit: surfaceBody.exit.transition,
+    card,
+    cardExpanded: springs.deck,
+    cardPeek: tween(durations.fast, easings.enter),
+    fade: tween(durations.moderate, easings.emphasized),
+    text: textSwap.enter,
+    headerSwap: headerSwap.enter,
+    actionDismiss: tween(ACTION_DISMISS, easings.exit),
+    icon: tween(durations.fast, easings.enter),
+    badge: springs.badge,
+    hud: tween(durations.moderate, easings.emphasized),
+    press: pressRole.transition,
+    scrubberTooltip: tween(durations.fast, easings.emphasized),
+    scrubberFollow: springs.tooltip,
+    mediaVolume: { duration: durations.fast, ease: easings.enter },
+  },
+  variants: {
+    fade: {
+      hidden: { opacity: 0, transform: gpuTransform(6, 0.99) },
+      visible: { opacity: 1, transform: gpuTransform(0), transition: textSwap.enter },
+      exit: { opacity: 0, transform: gpuTransform(-4, 0.99), transition: textSwap.exit },
+    },
+    textCrossfade: {
+      hidden: { opacity: 0, transform: gpuTransform(crossfade.distance, crossfade.scale) },
+      visible: {
+        opacity: 1,
+        transform: gpuTransform(0),
+        transition: { duration: crossfade.duration, ease: easings.enter },
+      },
+      exit: {
+        opacity: 0,
+        transform: gpuTransform(crossfade.distance, crossfade.scale),
+        transition: {
+          duration: Math.min(crossfade.duration * 0.7, durations.moderate),
+          ease: easings.exit,
+        },
+      },
+    },
+    description: (opacity = 0.7) => ({
+      hidden: { opacity: 0, transform: gpuTransform(4, 0.99) },
+      visible: {
+        opacity,
+        transform: gpuTransform(0),
+        transition: { duration: durations.base, ease: easings.emphasized },
+      },
+      exit: {
+        opacity: 0,
+        transform: gpuTransform(-3, 0.99),
+        transition: { duration: durations.fast, ease: easings.exit },
+      },
+    }),
+    headerSwap: contentSwap({
+      travel: 4,
+      exitTravel: 4,
+      enterScale: 0.99,
+      exitScale: 0.99,
+      duration: HEADER,
+      exitDuration: durations.fast,
+      enterEase: easings.enter,
+      exitEase: easings.exit,
+    }),
+    headerRestore: {
+      hidden: { opacity: 0, transform: gpuTransform(-4, 0.99) },
+      visible: {
+        opacity: 1,
+        transform: gpuTransform(0),
+        transition: {
+          type: "tween",
+          duration: SURFACE.headerReveal,
+          delay: SURFACE.headerRevealDelay,
+          ease: easings.enter,
+        },
+      },
+      exit: { opacity: 0, transform: gpuTransform(4, 0.99), transition: textSwap.exit },
+    },
+    extensionShelf: {
+      hidden: { opacity: 0, transform: gpuTransform(5, 0.99) },
+      visible: { opacity: 1, transform: gpuTransform(0, 1), transition: extensionsEnter },
+      exit: { opacity: 0, transform: gpuTransform(-4, 0.99), transition: extensionsExit },
+    },
+    actionDismiss: {
+      hidden: { opacity: 0, transform: gpuTransform(6, 0.99) },
+      visible: {
+        opacity: 1,
+        transform: gpuTransform(0),
+        transition: { duration: durations.fast, ease: easings.enter },
+      },
+      exit: {
+        opacity: 0,
+        transform: gpuTransform(-5, 0.99),
+        transition: { duration: ACTION_DISMISS, ease: easings.exit },
+      },
+    },
+    commandBar: {
+      hidden: { opacity: 0, transform: "translate3d(5px, 0, 0) scale(0.97)" },
+      visible: (index: unknown = 0) => ({
+        opacity: 1,
+        transform: "translate3d(0px, 0, 0) scale(1)",
+        transition: {
+          duration: durations.base,
+          delay: staggerDelay(Number(index) || 0, { base: 0.02, cap: 0.12 }),
+          ease: easings.enter,
+        },
+      }),
+      exit: {
+        opacity: 0,
+        transform: "translate3d(4px, 0, 0) scale(0.98)",
+        transition: { duration: durations.fast, ease: easings.exit },
+      },
+    },
+    icon: {
+      hidden: { opacity: 0, transform: gpuTransform(0, 0.92) },
+      visible: {
+        opacity: 1,
+        transform: gpuTransform(0, 1),
+        transition: { duration: durations.fast, ease: easings.enter },
+      },
+      exit: {
+        opacity: 0,
+        transform: gpuTransform(0, 0.92),
+        transition: { duration: durations.fast, ease: easings.exit },
+      },
+    },
+    badge: {
+      hidden: { opacity: 0, transform: gpuTransform(0, 0.88) },
+      visible: { opacity: 1, transform: gpuTransform(0) },
+      exit: { opacity: 0, transform: gpuTransform(0, 0.9) },
+    },
+    hud: {
+      hidden: { opacity: 0, transform: gpuTransform(4, 0.99) },
+      visible: {
+        opacity: 1,
+        transform: gpuTransform(0),
+        transition: tween(durations.moderate, easings.emphasized),
+      },
+      exit: { opacity: 0, transform: gpuTransform(3, 0.99), transition: textSwap.exit },
+    },
+    scrubberTooltip: {
+      hidden: { opacity: 0, transform: gpuTransform(4, 0.98) },
+      visible: { opacity: 1, transform: gpuTransform(0) },
+      exit: { opacity: 0, transform: gpuTransform(3, 0.99) },
+    },
+    breadcrumbs: {
+      hidden: { opacity: 0, transform: gpuTransform(-5, 0.985) },
+      visible: { opacity: 1, transform: gpuTransform(0), transition: expand },
+      exit: { opacity: 0, transform: gpuTransform(-3, 0.99), transition: card },
+    },
+    backdrop: {
+      hidden: { opacity: 0 },
+      visible: { opacity: 1 },
+      exit: { opacity: 0 },
+    },
+    surfaceBody,
+    controlsContainer: {
+      hidden: (targetY: unknown = 0) => ({
+        opacity: 0,
+        transform: gpuTransform((Number(targetY) || 0) + 6, 0.97),
+        transition: controlSwap.exit,
+      }),
+      visible: (targetY: unknown = 0) => ({
+        opacity: 1,
+        transform: gpuTransform(Number(targetY) || 0, 1),
+        transition: controlSwap.enter,
+      }),
+      exit: (targetY: unknown = 0) => ({
+        opacity: 0,
+        transform: gpuTransform((Number(targetY) || 0) + 6, 0.97),
+        transition: controlSwap.exit,
+      }),
+    },
+    controlsAction: controlsSlot(controlSwap.enter, controlSwap.exit),
+    controlsBack: controlsSlot(controlSwap.enter, controlSwap.exit),
+    controlsClose: chip({
+      duration: durations.base,
+      exitDuration: durations.fast,
+      enterEase: easings.enter,
+      exitEase: easings.exit,
+    }),
+    press: pressRole.variants,
+    mediaVolumeThumb: { idle: { scale: 1 }, dragging: { scale: 1.18 } },
+    cardContent: {
+      hidden: { opacity: 0, transform: gpuTransform(18 * 0.35, 1 - 0.008) },
+      visible: { opacity: 1, transform: gpuTransform(0, 1) },
+    },
+  },
+  deck: {
+    elevation: {
+      rest: "0px 12px 32px 0px rgba(0,0,0,0.35), 0px 2px 8px 0px rgba(0,0,0,0.25)",
+      elevated:
+        "0px 32px 80px 0px rgba(0,0,0,0.55), 0px 8px 24px 0px rgba(0,0,0,0.35)",
+    },
+    compress: { open: 0.94, close: 0.96 },
+    // Cards further back lift a little further and grow a little less.
+    peek: (position) => {
+      const progress = Math.min(position / 3, 1);
+      return {
+        lift: position * (4 * (0.85 + progress * 0.35)),
+        scale: 1 + 0.008 * (1 - progress * 0.25),
+      };
+    },
+    exit: ({ y, scale, position }) => ({
+      opacity: 0,
+      transform: gpuTransform(
+        y,
+        scale === null ? 0.98 - Math.min(position * 0.008, 0.024) : scale * 0.98,
+      ),
+      transition: { ...cardCollapse },
+    }),
+    tapScale: 0.97,
+  },
+  drag: {
+    elastic: { top: 0.05, bottom: 0.5 },
+    range: [0, 180],
+    opacity: [1, 0.75],
+    scale: [1, 0.96],
+  },
+  skeleton: "animate-pulse motion-reduce:animate-none",
+  timings: {
+    // The action's 0.32s dismissal, overlapped 0.22s by the growth.
+    dismissAction: 0.1,
+    anticipation: 0.07,
+    expandBody: SURFACE.bodyEnter,
+    // The body's 0.76s exit plus 0.1s for the deck to settle.
+    collapseBody: 0.86,
+    restoreHeader: SURFACE.headerRestore,
+    expandStagger: 0.055,
+    expandStaggerCap: 0.16,
+    peekStagger: 0.016,
+    peekStaggerCap: 0.064,
+  },
+};