@birdapi/velinstyle 1.2.1 → 1.3.0

package/core/motion/data/registry.json

@@ -0,0 +1,352 @@
+{
+  "schema": "velinstyle.motion.registry",
+  "version": 1,
+  "presets": [
+    {
+      "id": "fade",
+      "title": "Fade",
+      "description": "Opacity entrance; layout-safe default reveal.",
+      "kind": "preset",
+      "category": "hero",
+      "tags": ["entrance"],
+      "duration": 400,
+      "fps": "60",
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--fade",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "slide",
+      "title": "Slide Up",
+      "description": "Slide from below into view.",
+      "kind": "preset",
+      "category": "cards",
+      "tags": ["entrance", "slide"],
+      "duration": 500,
+      "fps": "60",
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--slide-up",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "slide-down",
+      "title": "Slide Down",
+      "description": "Slide from above into view.",
+      "kind": "preset",
+      "category": "navigation",
+      "tags": ["entrance", "slide"],
+      "duration": 500,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--slide-down",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "slide-left",
+      "title": "Slide Left",
+      "description": "Slide from the inline-end.",
+      "kind": "preset",
+      "category": "lists",
+      "tags": ["entrance", "slide"],
+      "duration": 500,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--slide-left",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "slide-right",
+      "title": "Slide Right",
+      "description": "Slide from the inline-start.",
+      "kind": "preset",
+      "category": "lists",
+      "tags": ["entrance", "slide"],
+      "duration": 500,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--slide-right",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "zoom",
+      "title": "Zoom / Scale",
+      "description": "Scale-in entrance for cards and media.",
+      "kind": "preset",
+      "category": "media",
+      "tags": ["entrance", "scale"],
+      "duration": 450,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--scale",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "blur",
+      "title": "Blur In",
+      "description": "Soft fade/blur entrance (maps to fade-in utility).",
+      "kind": "preset",
+      "category": "overlay",
+      "tags": ["entrance"],
+      "duration": 500,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "beta",
+      "cssClass": "velin-animate-fade-in",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "flip",
+      "title": "Flip / Scale In",
+      "description": "Attention scale-in for emphasis.",
+      "kind": "preset",
+      "category": "feedback",
+      "tags": ["attention"],
+      "duration": 400,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "beta",
+      "cssClass": "velin-animate-scale-in",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "lift",
+      "title": "Hover Lift",
+      "description": "Subtle lift on hover for interactive cards and buttons.",
+      "kind": "preset",
+      "category": "buttons",
+      "tags": ["hover"],
+      "duration": 200,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-hover",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "pulse",
+      "title": "Pulse",
+      "description": "Attention pulse; prefer finite loops under performance policy.",
+      "kind": "preset",
+      "category": "feedback",
+      "tags": ["attention"],
+      "duration": 1000,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-pulse",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "shake",
+      "title": "Shake",
+      "description": "Error/attention shake feedback.",
+      "kind": "preset",
+      "category": "forms",
+      "tags": ["attention", "feedback"],
+      "duration": 400,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-shake",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "bounce",
+      "title": "Bounce",
+      "description": "Playful bounce entrance or attention.",
+      "kind": "preset",
+      "category": "feedback",
+      "tags": ["attention"],
+      "duration": 600,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-bounce",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "shimmer",
+      "title": "Shimmer",
+      "description": "Loading shimmer surface (skeleton companion).",
+      "kind": "preset",
+      "category": "loading",
+      "tags": ["loading"],
+      "duration": 1200,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-skeleton",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "heroReveal",
+      "title": "Hero Reveal",
+      "description": "Staggered entrance for hero content; layout-safe; reduced-motion fallback.",
+      "kind": "preset",
+      "category": "hero",
+      "tags": ["entrance", "stagger"],
+      "duration": 600,
+      "fps": "60",
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "stable",
+      "cssClass": "velin-animate-on-scroll--fade",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "parallax",
+      "title": "Parallax",
+      "description": "Scroll-driven parallax shift.",
+      "kind": "preset",
+      "category": "media",
+      "tags": ["scroll"],
+      "duration": 0,
+      "reducedMotion": true,
+      "layoutSafe": false,
+      "status": "stable",
+      "cssClass": "velin-parallax",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "fadeOut",
+      "title": "Fade Out",
+      "description": "Exit fade (planned composition with timelines).",
+      "kind": "preset",
+      "category": "overlay",
+      "tags": ["exit"],
+      "duration": 300,
+      "reducedMotion": true,
+      "layoutSafe": true,
+      "status": "beta",
+      "cssClass": "velin-animate-fade-out",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    }
+  ],
+  "timelines": [
+    {
+      "id": "hero-intro",
+      "title": "Hero Intro",
+      "description": "Title → subtitle → buttons → image",
+      "kind": "timeline",
+      "category": "hero",
+      "steps": ["title", "subtitle", "buttons", "image"],
+      "status": "beta",
+      "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "card-stagger",
+      "title": "Card Stagger",
+      "description": "Sequential card entrance labels.",
+      "kind": "timeline",
+      "category": "cards",
+      "steps": ["card-1", "card-2", "card-3"],
+      "status": "beta",
+      "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    }
+  ],
+  "transitions": [
+    {
+      "id": "cross-fade",
+      "title": "Cross Fade",
+      "description": "Page/view cross-fade (View Transition friendly).",
+      "kind": "transition",
+      "category": "page",
+      "status": "planned",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "modal-enter",
+      "title": "Modal Enter",
+      "description": "Overlay modal entrance transition.",
+      "kind": "transition",
+      "category": "modal",
+      "status": "planned",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "drawer-enter",
+      "title": "Drawer Enter",
+      "description": "Drawer slide transition.",
+      "kind": "transition",
+      "category": "drawer",
+      "status": "planned",
+      "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    }
+  ],
+  "physics": [
+    {
+      "id": "spring",
+      "title": "Spring",
+      "description": "Spring easing token mapping (runtime simulation later).",
+      "kind": "physics",
+      "category": "feedback",
+      "status": "planned",
+      "token": "--velin-ease-spring",
+      "compatibility": { "cssOnly": true, "runtime": false, "webComponents": false, "studio": true, "production": true, "review": true, "cli": true }
+    },
+    {
+      "id": "elastic",
+      "title": "Elastic",
+      "description": "Elastic easing token mapping.",
+      "kind": "physics",
+      "category": "feedback",
+      "status": "planned",
+      "token": "--velin-ease-elastic",
+      "compatibility": { "cssOnly": true, "runtime": false, "webComponents": false, "studio": true, "production": true, "review": true, "cli": true }
+    }
+  ],
+  "composers": [
+    {
+      "id": "sequence",
+      "title": "Sequence Composer",
+      "description": "Ordered fade/wait/slide composition API.",
+      "kind": "composer",
+      "category": "page",
+      "status": "planned",
+      "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true }
+    }
+  ],
+  "triggers": [
+    { "id": "load", "title": "Load", "description": "Start when document/module initializes.", "kind": "trigger", "category": "page", "status": "stable", "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "visible", "title": "Visible", "description": "Start when element enters the viewport (IntersectionObserver).", "kind": "trigger", "category": "page", "status": "stable", "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "hidden", "title": "Hidden", "description": "Fire when element leaves the viewport. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "page", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "hover", "title": "Hover", "description": "Pointer enter / hover.", "kind": "trigger", "category": "buttons", "status": "stable", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "focus", "title": "Focus", "description": "Keyboard/pointer focus.", "kind": "trigger", "category": "forms", "status": "stable", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "click", "title": "Click", "description": "Pointer activation.", "kind": "trigger", "category": "buttons", "status": "stable", "compatibility": { "cssOnly": false, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "scroll", "title": "Scroll", "description": "Scroll-linked or scroll-progress trigger.", "kind": "trigger", "category": "page", "status": "stable", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "idle", "title": "Idle", "description": "After user idle timeout. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "feedback", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "media", "title": "Media", "description": "Match media query condition. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "page", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "container", "title": "Container", "description": "Container query / size trigger. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "cards", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "theme", "title": "Theme", "description": "Theme change trigger. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "page", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "custom", "title": "Custom", "description": "Custom event name via velin-trigger-event. (Planned — runtime falls back to visible.)", "kind": "trigger", "category": "page", "status": "planned", "compatibility": { "cssOnly": false, "runtime": false, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } }
+  ],
+  "policies": [
+    { "id": "safe", "title": "Safe", "description": "Default layout-safe motion with capped durations.", "kind": "policy", "category": "page", "status": "stable", "maxDurationMs": 800, "allowInfinite": false, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "reduced", "title": "Reduced", "description": "Honors prefers-reduced-motion first; shorten or skip decorative motion.", "kind": "policy", "category": "page", "status": "stable", "maxDurationMs": 200, "forceReduced": true, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "marketing", "title": "Marketing", "description": "Expressive hero motion allowed within caps.", "kind": "policy", "category": "hero", "status": "stable", "maxDurationMs": 1200, "allowInfinite": false, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "minimal", "title": "Minimal", "description": "Very little motion; feedback only.", "kind": "policy", "category": "page", "status": "stable", "maxDurationMs": 300, "allowInfinite": false, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "accessibility", "title": "Accessibility", "description": "Strict reduced-motion + focus-safe interactions.", "kind": "policy", "category": "page", "status": "stable", "maxDurationMs": 200, "forceReduced": true, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "performance", "title": "Performance", "description": "FPS-friendly; ban infinite decorative loops.", "kind": "policy", "category": "page", "status": "stable", "maxDurationMs": 600, "allowInfinite": false, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "disabled", "title": "Disabled", "description": "All motion off.", "kind": "policy", "category": "page", "status": "stable", "disabled": true, "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } }
+  ],
+  "blueprints": [
+    { "id": "landing", "title": "Landing", "description": "Hero reveal + staggered sections + CTA hover.", "kind": "blueprint", "category": "hero", "status": "beta", "presets": ["heroReveal", "fade", "lift"], "timeline": "hero-intro", "policy": "marketing", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "dashboard", "title": "Dashboard", "description": "Minimal card stagger for admin shells.", "kind": "blueprint", "category": "cards", "status": "beta", "presets": ["fade", "slide"], "timeline": "card-stagger", "policy": "minimal", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "pricing", "title": "Pricing", "description": "Pricing cards with stagger and lift.", "kind": "blueprint", "category": "cards", "status": "beta", "presets": ["slide", "lift"], "policy": "marketing", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "portfolio", "title": "Portfolio", "description": "Media zoom + parallax-safe reveals.", "kind": "blueprint", "category": "media", "status": "beta", "presets": ["zoom", "fade"], "policy": "marketing", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "shop", "title": "Shop", "description": "Product cards and feedback pulses.", "kind": "blueprint", "category": "cards", "status": "planned", "presets": ["fade", "lift"], "policy": "safe", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "forum", "title": "Forum", "description": "List slides and form feedback.", "kind": "blueprint", "category": "lists", "status": "planned", "presets": ["slide", "shake"], "policy": "safe", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "docs", "title": "Docs", "description": "Minimal fade for documentation pages.", "kind": "blueprint", "category": "page", "status": "beta", "presets": ["fade"], "policy": "minimal", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "blog", "title": "Blog", "description": "Article hero fade and card slides.", "kind": "blueprint", "category": "hero", "status": "planned", "presets": ["fade", "slide"], "policy": "safe", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "crm", "title": "CRM", "description": "Table-safe minimal motion.", "kind": "blueprint", "category": "tables", "status": "planned", "presets": ["fade"], "policy": "performance", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } },
+    { "id": "login", "title": "Login", "description": "Form feedback and focus-safe motion.", "kind": "blueprint", "category": "forms", "status": "beta", "presets": ["fade", "shake"], "policy": "accessibility", "compatibility": { "cssOnly": true, "runtime": true, "webComponents": true, "studio": true, "production": true, "review": true, "cli": true } }
+  ]
+}

package/core/motion/effects.js

@@ -9,16 +9,24 @@ const EFFECT_MAP = {
   'slide-left': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-left'],
   'slide-right': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-right'],
   scale: ['velin-animate-on-scroll', 'velin-animate-on-scroll--scale'],
+  zoom: ['velin-animate-on-scroll', 'velin-animate-on-scroll--scale'],
   parallax: ['velin-parallax'],
   'parallax-slow': ['velin-parallax', 'velin-parallax--slow'],
   hover: ['velin-animate-hover'],
   'hover-lift': ['velin-animate-hover'],
+  lift: ['velin-animate-hover'],
   flip: ['velin-animate-scale-in'],
   blur: ['velin-animate-fade-in'],
+  pulse: ['velin-animate-pulse'],
+  shake: ['velin-animate-shake'],
+  bounce: ['velin-animate-bounce'],
+  shimmer: ['velin-skeleton'],
+  heroReveal: ['velin-animate-on-scroll', 'velin-animate-on-scroll--fade'],
+  fadeOut: ['velin-animate-fade-out'],
 };
 
 /**
- * Apply motion effect classes from velin-* attribute values.
+ * Apply motion effect classes from velin-* attribute values or velin-motion preset.
  * @param {HTMLElement} el
  * @param {Record<string, string>} attrs keyed by effect name
  */
@@ -26,6 +34,12 @@ export function applyEffects(el, attrs = {}) {
   const classes = new Set();
   for (const [name, value] of Object.entries(attrs)) {
     if (value === 'false' || value === 'off') continue;
+    if (name === 'motion' && value && value !== 'true') {
+      const presetKey = value;
+      const mapped = EFFECT_MAP[presetKey];
+      if (mapped) mapped.forEach((c) => classes.add(c));
+      continue;
+    }
     const mapped = EFFECT_MAP[name];
     if (mapped) mapped.forEach((c) => classes.add(c));
     if (name === 'slide' && value && value !== 'true' && value !== '') {
@@ -52,3 +66,5 @@ export function prefersReducedMotion() {
     window.matchMedia('(prefers-reduced-motion: reduce)').matches
   );
 }
+
+export { EFFECT_MAP };

package/core/motion/index.js

@@ -2,24 +2,62 @@ import { observeInView, disconnectInViewObserver } from './scheduler.js';
 import { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS } from './effects.js';
 import { enhanceStagger } from './stagger.js';
 import { bindSmoothScroll } from './scroll.js';
+import { armMotionElement, readTrigger } from './triggers.js';
+import { applyMotionVars, resolvePolicy, shouldDisableMotion } from './policy.js';
+import { enhanceTimelines } from './timeline.js';
+import { enhanceSequences, Motion } from './composer.js';
+import {
+  loadMotionRegistry,
+  listPresets,
+  listPolicies,
+  catalogSummary,
+  getPreset,
+  resolvePresetId,
+} from './registry.js';
 
-const MOTION_ATTRS = ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover'];
+const LEGACY_ATTRS = ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover'];
 
 let teardownFns = [];
 
 /**
- * Initialize motion system: in-view reveals, stagger, smooth scroll anchors.
+ * Create a motion engine bound to an optional policy.
+ * @param {{ policy?: string }} [options]
+ */
+export function createMotionEngine(options = {}) {
+  const policy = resolvePolicy(options.policy || 'safe');
+  return {
+    policy,
+    registry: () => loadMotionRegistry(),
+    catalog: catalogSummary,
+    listPresets,
+    listPolicies,
+    init: (opts = {}) => initMotion({ ...opts, policy: policy.id }),
+    Motion,
+  };
+}
+
+/**
+ * Initialize motion system: unified velin-motion + triggers + legacy attrs.
  * @param {object} [options]
  * @param {HTMLElement|Document} [options.root]
  * @param {string} [options.selector]
+ * @param {string} [options.policy]
  */
 export function initMotion(options = {}) {
   const root = options.root || (typeof document !== 'undefined' ? document : null);
   if (!root) return () => {};
 
+  const policy = resolvePolicy(
+    options.policy
+      || root.documentElement?.getAttribute?.('data-velin-motion-policy')
+      || root.querySelector?.('[data-velin-motion-policy]')?.getAttribute('data-velin-motion-policy')
+      || 'safe',
+  );
+
   const selector =
     options.selector ||
     [
+      '[velin-motion]',
       '[velin-reveal]',
       '[velin-fade]',
       '[velin-slide]',
@@ -30,32 +68,48 @@ export function initMotion(options = {}) {
     ].join(',');
 
   const elements = root.querySelectorAll(selector);
-  const reduced = prefersReducedMotion();
+  const reduced = shouldDisableMotion(policy) || prefersReducedMotion();
 
   for (const el of elements) {
     if (el.dataset.velinMotionInit) continue;
     el.dataset.velinMotionInit = '1';
 
+    applyMotionVars(el, policy);
+
     const attrs = {};
-    for (const name of MOTION_ATTRS) {
+    const motionPreset = el.getAttribute('velin-motion');
+    if (motionPreset) {
+      attrs.motion = motionPreset;
+      const resolved = resolvePresetId(motionPreset);
+      if (resolved?.id) attrs[resolved.id] = 'true';
+    }
+    for (const name of LEGACY_ATTRS) {
       if (el.hasAttribute(name)) attrs[name.replace('velin-', '')] = el.getAttribute(name) || 'true';
     }
     applyEffects(el, attrs);
 
-    if (reduced) {
+    if (reduced || el.dataset.velinMotion === 'off') {
       markVisible(el);
       continue;
     }
 
-    const stop = observeInView(el, (node) => markVisible(node));
+    const stop = armMotionElement(el, () => applyEffects(el, attrs));
     teardownFns.push(stop);
   }
 
   enhanceStagger(root);
   bindSmoothScroll(root);
+  enhanceTimelines(root);
+  enhanceSequences(root);
 
   return () => {
-    teardownFns.forEach((fn) => fn());
+    teardownFns.forEach((fn) => {
+      try {
+        fn();
+      } catch {
+        /* ignore */
+      }
+    });
     teardownFns = [];
     disconnectInViewObserver();
   };
@@ -69,8 +123,57 @@ export function initReveal(options = {}) {
   });
 }
 
-export const velinMotion = { init: initMotion, observe: observeInView, markVisible, VISIBLE_CLASS };
+export const velinMotion = {
+  init: initMotion,
+  observe: observeInView,
+  markVisible,
+  VISIBLE_CLASS,
+  createEngine: createMotionEngine,
+  readTrigger,
+};
+
 export { observeInView, disconnectInViewObserver } from './scheduler.js';
-export { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS } from './effects.js';
+export { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS, EFFECT_MAP } from './effects.js';
 export { enhanceStagger, applyStagger } from './stagger.js';
 export { smoothScrollTo, bindSmoothScroll } from './scroll.js';
+export {
+  loadMotionRegistry,
+  listPresets,
+  listPolicies,
+  listTriggers,
+  listBlueprints,
+  listTimelines,
+  listMotion,
+  getPreset,
+  getPolicy,
+  getTrigger,
+  getTimeline,
+  getBlueprint,
+  catalogSummary,
+  resolvePresetId,
+  NAMESPACES,
+} from './registry.js';
+export {
+  bindTrigger,
+  readTrigger,
+  armMotionElement,
+  TRIGGER_V1,
+  TRIGGER_V2,
+  ALL_TRIGGERS,
+} from './triggers.js';
+export {
+  resolvePolicy,
+  listMotionPolicies,
+  shouldDisableMotion,
+  capDuration,
+  validatePolicy,
+  applyMotionVars,
+} from './policy.js';
+export { scanMotionHtml, doctorMotionHtml, collectMotionElements } from './scan.js';
+export { analyzeMotionHtml } from './analyze.js';
+export { runTimeline, enhanceTimelines } from './timeline.js';
+export { Motion, sequence, fade, slide, wait, rotate, blur, preset, enhanceSequences } from './composer.js';
+export { runViewTransition, applyTransitionHint, getTransitionPreset } from './transitions.js';
+export { emitMotionBlueprint } from './blueprint.js';
+export { optimizeMotionHtml } from './optimize.js';
+export { reviewMotionHtml } from './review.js';

package/core/motion/optimize.js

@@ -0,0 +1,44 @@
+/**
+ * Safe motion optimize — cap durations, strip infinite where safe.
+ * @param {string} html
+ * @param {{ write?: boolean, maxDuration?: number }} [opts]
+ */
+export function optimizeMotionHtml(html, opts = {}) {
+  const max = opts.maxDuration ?? 800;
+  let next = String(html || '');
+  const changes = [];
+
+  next = next.replace(/velin-duration\s*=\s*["'](\d+)["']/gi, (full, n) => {
+    const v = Number(n);
+    if (v > max) {
+      changes.push(`capped duration ${v} → ${max}`);
+      return `velin-duration="${max}"`;
+    }
+    return full;
+  });
+
+  next = next.replace(/velin-delay\s*=\s*["'](\d+)["']/gi, (full, n) => {
+    const v = Number(n);
+    if (v > 500) {
+      changes.push(`capped delay ${v} → 500`);
+      return `velin-delay="500"`;
+    }
+    return full;
+  });
+
+  const beforeInf = next;
+  next = next.replace(/\s*velin-animate[^\s"']*--infinite/gi, (m) => {
+    changes.push(`removed infinite modifier ${m.trim()}`);
+    return '';
+  });
+  if (next !== beforeInf && !changes.some((c) => c.includes('infinite'))) {
+    changes.push('stripped infinite animation classes');
+  }
+
+  return {
+    ok: true,
+    changed: changes.length > 0,
+    changes,
+    html: next,
+  };
+}