@motion.page/sdk 1.2.0 → 1.2.1

package/README.md

@@ -19,6 +19,7 @@ A high-performance animation SDK with a declarative API. Scroll-triggered animat
   - [Motion()](#motion-function)
   - [Motion Static Methods](#motion-static-methods)
   - [Motion.context](#motioncontext--dynamic-content--spa)
+  - [Motion.responsive](#motionresponsive--responsive-breakpoint-variants)
   - [Motion.utils](#motionutils)
   - [Timeline](#timeline)
   - [Triggers](#triggers)
@@ -284,6 +285,7 @@ Calling `Motion()` with the same name on an already-existing timeline returns it
 | `Motion.refreshScrollTriggers` | `(): void` | Recalculate all scroll trigger start/end positions (call after layout changes). |
 | `Motion.cleanup` | `(): void` | Remove ScrollTrigger spacer and marker DOM nodes from the document. |
 | `Motion.context` | `(fn: () => void): MotionContext` | Create a scoped context that tracks all timelines created during `fn()`. Returns a `MotionContext` with `revert()`, `refresh()`, and `add(fn)` methods. Essential for dynamic content (AJAX filters, SPA navigation, infinite scroll). |
+| `Motion.responsive` | `(name, variants, breakpoints): ResponsiveManager` | Register a reactive timeline whose per-breakpoint variant is live-swapped as the viewport crosses a breakpoint — no page reload. `variants` is a sparse map of `desktop` / `laptop` / `tablet` / `phone` factories; `breakpoints` is `{ laptops, tablets, phones }` in px. Returns a manager with `getActiveTier()` and `destroy()`. |
 
 #### Examples
 
@@ -344,6 +346,53 @@ ctx.add(() => {
 });
 ```
 
+#### Motion.responsive — Responsive Breakpoint Variants
+
+Use `Motion.responsive()` to give one timeline a different animation per viewport tier. Instead of compiling a separate block per breakpoint, you register a **sparse map of variant factories** and the SDK live-swaps the active variant as the viewport crosses a breakpoint — it kills the previous tier's timeline and builds the new one, with **no page reload**.
+
+```ts
+Motion.responsive(
+  'hero',
+  {
+    // Each tier is a factory that builds AND registers its timeline.
+    desktop: () =>
+      Motion('hero', '.title', {
+        from: { opacity: 0, x: -120 },
+        duration: 1,
+      }).onPageLoad(),
+
+    phone: () =>
+      Motion('hero', '.title', {
+        from: { opacity: 0, y: 40 },
+        duration: 0.6,
+      }).onPageLoad(),
+  },
+  { laptops: 992, tablets: 768, phones: 576 } // breakpoint boundaries in px
+);
+```
+
+**Tiers & ranges.** There are four tiers — `desktop`, `laptop`, `tablet`, `phone`. The `breakpoints` object sets the boundaries, and each tier owns a width range (with the values above):
+
+| Tier | Active range |
+|------|--------------|
+| `desktop` | `≥ 993px` (above `laptops`) |
+| `laptop` | `769px – 992px` |
+| `tablet` | `577px – 768px` |
+| `phone` | `≤ 576px` (at or below `phones`) |
+
+**Sparse maps cascade up.** You only define the tiers you care about. A tier with no variant falls back to the nearest **wider** tier that does. In the example above, `laptop` and `tablet` widths both use the `desktop` variant; only `phone` width switches to the phone variant.
+
+**Return value — the manager.** `Motion.responsive()` returns a `ResponsiveManager`:
+
+```ts
+const hero = Motion.responsive('hero', { /* variants */ }, { laptops: 992, tablets: 768, phones: 576 });
+
+hero.getActiveTier(); // 'desktop' | 'laptop' | 'tablet' | 'phone' | null — the tier currently driving the page
+hero.destroy();       // remove the breakpoint listeners and kill the active variant
+```
+
+> In SSR or environments without `matchMedia`, the `desktop` variant is built once with no live swapping. If the responsive runtime is tree-shaken out of a custom bundle that has no responsive timelines, the call best-effort builds the `desktop` variant and returns `undefined`.
+
 ---
 
 ### Motion.utils

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion.page/sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "High-performance CSS animation SDK with scroll, hover, gesture, and cursor triggers",
   "type": "module",
   "main": "dist/index.js",