@octanejs/motion 0.1.32 → 0.1.33

package/README.md

@@ -43,6 +43,12 @@ function List(props) @{
   events, …) and `style` MotionValues spread/bound onto the element.
 - `AnimatePresence` — exit animations on removal.
 - `MotionConfig` — global `transition` / `reducedMotion` defaults via context.
+- `useReducedMotion()` — a live `prefers-reduced-motion` subscription; operating-system
+  setting changes update mounted consumers.
+- `LayoutGroup` — namespaces `layoutId` values so independent shared-layout surfaces
+  do not cross-animate.
+- `LazyMotion` + `domAnimation` / `domMax` + `m` — feature-gated hosts. The
+  `./react-m` entry exposes every HTML/SVG host as a named export.
 - `variants` — label resolution (`animate="visible"`) + parent→child propagation +
   `staggerChildren` / `delayChildren` (number or `stagger()` function) / `staggerDirection`.
 - `useMotionValue()`, `useScroll()`, `useAnimate()` — MotionValues, scroll-linked
@@ -74,13 +80,15 @@ real `<tag>` through `hostComponent`, captures the node, and drives:
   vs the previous commit (`layout`) or a same-id element that just unmounted
   (`layoutId`) — apply the inverse transform then animate it back to identity. The
   same cleanup-before-detach ordering lets a leaving `layoutId` element record its
-  box for the next one.
+  box for a same-commit replacement; unused boxes expire after that commit.
+  `layout="position"` applies only translation, `layout="size"` only scaling, and
+  layout animations use `transition.layout` when provided.
 
 ## Not yet ported
 
 The full layout **projection tree** — nested projection, child scale correction, and
 continuous shared-layout during drag (the `layout`/`layoutId` here are single-element
-FLIPs). Also drag momentum/elastic physics, reduced-motion enforcement, and
+FLIPs). Also drag momentum/elastic physics and
 `useTransform`'s output-map form (`useTransform(mv, [0, 100], { opacity: [0, 1] })`).
 
 Stagger specifics: `when: 'beforeChildren' | 'afterChildren'` parent/child sequencing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/motion",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -35,20 +35,22 @@
     "README.md"
   ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./react-m": "./src/react-m.ts"
   },
   "dependencies": {
     "motion": "^12.42.2"
   },
   "peerDependencies": {
-    "octane": "0.1.33"
+    "octane": "0.1.34"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",
     "vitest": "^4.1.10",
-    "octane": "0.1.33"
+    "octane": "0.1.34"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run --root ../.. --project motion",
+    "typecheck": "tsgo --noEmit -p tsconfig.json"
   }
 }

package/src/context.ts

@@ -6,8 +6,39 @@ import { createContext, useContext } from 'octane';
 export interface MotionConfigValue {
 	transition?: any;
 	reducedMotion?: 'always' | 'never' | 'user';
+	shouldReduceMotion?: boolean;
 }
-export const MotionConfigContext = createContext<MotionConfigValue>({});
+export const MotionConfigContext = createContext<MotionConfigValue>({
+	reducedMotion: 'never',
+	shouldReduceMotion: false,
+});
+
+// LayoutGroup namespaces shared layout ids. Nested groups inherit and compose
+// ids by default, matching Motion's `parent-child-layoutId` convention.
+export interface LayoutGroupValue {
+	id?: string;
+	/** @internal Collision-free namespace segments used by the layoutId registry. */
+	layoutIdNamespace?: readonly string[];
+}
+export const LayoutGroupContext = createContext<LayoutGroupValue>({});
+
+export interface MotionFeatureBundle {
+	animation: boolean;
+	gestures: boolean;
+	drag: boolean;
+	layout: boolean;
+}
+
+export interface LazyMotionValue {
+	features: MotionFeatureBundle | null;
+	strict: boolean;
+	provided: boolean;
+}
+export const LazyMotionContext = createContext<LazyMotionValue>({
+	features: null,
+	strict: false,
+	provided: false,
+});
 
 // Variant labels propagated from a parent motion element to its descendants, so a
 // child with `variants` but no explicit `animate` inherits the parent's active

package/src/index.ts

@@ -7,16 +7,37 @@
 // drives animation/gesture/layout/drag from layout effects — exactly the refs +
 // effects + rendering path this is meant to exercise.
 import { animate, hover, press, inView } from 'motion';
-import { childSlot, hostComponent, useLayoutEffect, useState, provideContext } from 'octane';
 import {
+	childSlot,
+	hostComponent,
+	useContext,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useState,
+	provideContext,
+} from 'octane';
+import {
+	LayoutGroupContext,
+	LazyMotionContext,
 	MotionConfigContext,
 	VariantContext,
 	StaggerContext,
+	type MotionFeatureBundle,
 	resolveVariant,
 	splitVariant,
 } from './context';
 import { isMotionValue, isTransformKey, applyStyleValue } from './useMotionValue';
-import { useContext } from 'octane';
+import { useReducedMotionAtSlot } from './useReducedMotion';
+import {
+	layoutAnimationMode,
+	layoutCellKey,
+	layoutTransition,
+	projectLayout,
+	recordLayoutCell,
+	takeLayoutCell,
+	type LayoutBox,
+} from './layout';
 
 // A plain-TS component gets its OWN block per instance (componentSlot), so fixed
 // slot symbols don't collide across instances — and these are distinct within one.
@@ -32,18 +53,12 @@ const MV = Symbol.for('octane-motion:motionvalues');
 const LAYOUT_ID = Symbol.for('octane-motion:layoutid');
 const STAGGER_ORCH = Symbol.for('octane-motion:stagger-orch');
 const STAGGER = Symbol.for('octane-motion:stagger');
+const CONFIG_REDUCED = Symbol.for('octane-motion:config-reduced');
+const LAYOUT_GROUP_STATE = Symbol.for('octane-motion:layout-group-state');
+const LAZY_STATE = Symbol.for('octane-motion:lazy-state');
+const LAZY_EFFECT = Symbol.for('octane-motion:lazy-effect');
 
-// Shared-element registry: a `layoutId` element records its box on unmount; the
-// next element to mount with the same id crossfades (FLIPs) from it. (A basic
-// shared-layout "magic move"; the full projection tree is out of scope.)
-interface Box {
-	left: number;
-	top: number;
-	width: number;
-	height: number;
-}
-const layoutCells = new Map<string, Box>();
-const boxOf = (n: HTMLElement): Box => {
+const boxOf = (n: HTMLElement): LayoutBox => {
 	const r = n.getBoundingClientRect();
 	return { left: r.left, top: r.top, width: r.width, height: r.height };
 };
@@ -110,13 +125,93 @@ function clamp(v: number, min: number, max: number): number {
 	return v < min ? min : v > max ? max : v;
 }
 
-function createMotionComponent(tag: string) {
+const POSITIONAL_KEYS = new Set([
+	'width',
+	'height',
+	'top',
+	'left',
+	'right',
+	'bottom',
+	'transform',
+	'transformPerspective',
+	'x',
+	'y',
+	'z',
+	'translateX',
+	'translateY',
+	'translateZ',
+	'scale',
+	'scaleX',
+	'scaleY',
+	'rotate',
+	'rotateX',
+	'rotateY',
+	'rotateZ',
+	'skew',
+	'skewX',
+	'skewY',
+]);
+
+function reducedTransition(values: any, transition: any, shouldReduceMotion: boolean): any {
+	if (!shouldReduceMotion || values == null || typeof values !== 'object') return transition;
+
+	let reduced: Record<string, any> | null = null;
+	for (const key in values) {
+		if (!POSITIONAL_KEYS.has(key)) continue;
+		const next = (reduced ??= { ...(transition || {}) });
+		const valueTransition =
+			transition?.[key] != null && typeof transition[key] === 'object' ? transition[key] : {};
+		next[key] = { ...valueTransition, type: false, delay: 0, duration: 0 };
+	}
+	return reduced ?? transition;
+}
+
+function animateTarget(
+	node: HTMLElement,
+	values: any,
+	transition: any,
+	shouldReduceMotion: boolean,
+): any {
+	return animate(node, values, reducedTransition(values, transition, shouldReduceMotion));
+}
+
+export type MotionComponent = (props: any, scope: any) => void;
+
+function createMotionComponent(tag: string, preloadedFeatures: boolean): MotionComponent {
 	return function MotionComponent(props: any, scope: any): void {
 		const config = useContext(MotionConfigContext);
+		const layoutGroup = useContext(LayoutGroupContext);
+		const lazy = useContext(LazyMotionContext);
 		const inherited = useContext(VariantContext);
 		// Read the PARENT's stagger orchestration before providing our own below.
 		const parentStagger = useContext(StaggerContext);
 		const variants = props.variants;
+		const features = preloadedFeatures ? domMax : lazy.features;
+		const animationEnabled = preloadedFeatures || features?.animation === true;
+		const gesturesEnabled = preloadedFeatures || features?.gestures === true;
+		const dragEnabled = preloadedFeatures || features?.drag === true;
+		const layoutEnabled = preloadedFeatures || features?.layout === true;
+		const shouldReduceMotion = config.shouldReduceMotion === true;
+		const layoutIdKey =
+			props.layoutId === undefined
+				? undefined
+				: layoutCellKey(
+						layoutGroup.layoutIdNamespace ?? (layoutGroup.id ? [layoutGroup.id] : undefined),
+						props.layoutId,
+					);
+
+		// Reason: browser bundlers replace this expression even though they do not
+		// define a global `process`; guarding `process` would silently disable strict mode.
+		if (
+			process.env.NODE_ENV !== 'production' &&
+			preloadedFeatures &&
+			lazy.provided &&
+			lazy.strict
+		) {
+			throw new Error(
+				'You have rendered a `motion` component within a strict `LazyMotion` component. Import and render from `@octanejs/motion/react-m` instead.',
+			);
+		}
 
 		// Variant labels: an explicit prop wins, else inherit the parent's label.
 		const initialLabel = props.initial !== undefined ? props.initial : inherited.initial;
@@ -201,11 +296,18 @@ function createMotionComponent(tag: string) {
 		latest.onDrag = props.onDrag;
 		latest.onDragStart = props.onDragStart;
 		latest.onDragEnd = props.onDragEnd;
+		latest.shouldReduceMotion = shouldReduceMotion;
+		latest.animationEnabled = animationEnabled;
+		latest.layoutEnabled = layoutEnabled;
+		latest.layoutIdKey = layoutIdKey;
+		latest.layoutMode = layoutAnimationMode(props.layout);
 
 		// `initial`: apply instantly on mount (before the animate effect runs).
 		useLayoutEffect(
 			() => {
-				if (resolvedInitial) animate(node, resolvedInitial, { duration: 0 });
+				if (animationEnabled && resolvedInitial) {
+					animate(node, resolvedInitial, { duration: 0 });
+				}
 			},
 			[],
 			ENTER,
@@ -216,7 +318,7 @@ function createMotionComponent(tag: string) {
 		// count are both known by now — all children registered during the parent render).
 		useLayoutEffect(
 			() => {
-				if (resolvedAnimate) {
+				if (animationEnabled && resolvedAnimate) {
 					let t = transition;
 					const o = latest.staggerParent;
 					if (o && o.active) {
@@ -232,12 +334,12 @@ function createMotionComponent(tag: string) {
 						}
 						if (delay > 0) t = { ...(t || {}), delay: (t?.delay || 0) + delay };
 					}
-					const controls = animate(node, resolvedAnimate, t);
+					const controls = animateTarget(node, resolvedAnimate, t, latest.shouldReduceMotion);
 					if (props.onAnimationComplete) whenDone(controls, () => props.onAnimationComplete());
 					return () => controls.stop();
 				}
 			},
-			[stableKey(resolvedAnimate), stableKey(transition)],
+			[animationEnabled, stableKey(resolvedAnimate), stableKey(transition), shouldReduceMotion],
 			ANIMATE,
 		);
 
@@ -284,6 +386,7 @@ function createMotionComponent(tag: string) {
 		// read from `latest`, so prop changes take effect without re-binding.
 		useLayoutEffect(
 			() => {
+				if (!gesturesEnabled) return;
 				const cleanups: Array<() => void> = [];
 				const gesture = (
 					bind: (el: Element, onStart: () => () => void) => () => void,
@@ -291,9 +394,14 @@ function createMotionComponent(tag: string) {
 					transitionKey: string,
 				) =>
 					bind(node, () => {
-						animate(node, latest[valuesKey], latest[transitionKey] ?? latest.transition);
+						animateTarget(
+							node,
+							latest[valuesKey],
+							latest[transitionKey] ?? latest.transition,
+							latest.shouldReduceMotion,
+						);
 						return () => {
-							animate(node, latest.base, latest.transition);
+							animateTarget(node, latest.base, latest.transition, latest.shouldReduceMotion);
 						};
 					});
 				if (props.whileHover)
@@ -301,8 +409,14 @@ function createMotionComponent(tag: string) {
 				if (props.whileTap) cleanups.push(gesture(press as any, 'whileTap', 'whileTapTransition'));
 				if (props.whileFocus) {
 					const onFocus = () =>
-						animate(node, latest.whileFocus, latest.whileFocusTransition ?? latest.transition);
-					const onBlur = () => animate(node, latest.base, latest.transition);
+						animateTarget(
+							node,
+							latest.whileFocus,
+							latest.whileFocusTransition ?? latest.transition,
+							latest.shouldReduceMotion,
+						);
+					const onBlur = () =>
+						animateTarget(node, latest.base, latest.transition, latest.shouldReduceMotion);
 					node.addEventListener('focus', onFocus);
 					node.addEventListener('blur', onBlur);
 					cleanups.push(() => {
@@ -312,7 +426,7 @@ function createMotionComponent(tag: string) {
 				}
 				return () => cleanups.forEach((c) => c());
 			},
-			[],
+			[gesturesEnabled],
 			GESTURE,
 		);
 
@@ -320,20 +434,27 @@ function createMotionComponent(tag: string) {
 		// when it leaves (unless `viewport.once`). Reuses motion's `inView`.
 		useLayoutEffect(
 			() => {
-				if (!props.whileInView) return;
+				if (!gesturesEnabled || !props.whileInView) return;
 				const stop = inView(
 					node,
 					() => {
-						animate(node, latest.whileInView, latest.whileInViewTransition ?? latest.transition);
+						animateTarget(
+							node,
+							latest.whileInView,
+							latest.whileInViewTransition ?? latest.transition,
+							latest.shouldReduceMotion,
+						);
 						return () => {
-							if (!props.viewport?.once) animate(node, latest.base, latest.transition);
+							if (!props.viewport?.once) {
+								animateTarget(node, latest.base, latest.transition, latest.shouldReduceMotion);
+							}
 						};
 					},
 					props.viewport,
 				);
 				return () => stop();
 			},
-			[],
+			[gesturesEnabled],
 			INVIEW,
 		);
 
@@ -341,7 +462,7 @@ function createMotionComponent(tag: string) {
 		// (`drag="x"`/`"y"`) and `dragConstraints` (a box of left/right/top/bottom px).
 		useLayoutEffect(
 			() => {
-				if (!props.drag) return;
+				if (!dragEnabled || !props.drag) return;
 				let active = false;
 				let startX = 0;
 				let startY = 0;
@@ -388,7 +509,7 @@ function createMotionComponent(tag: string) {
 					window.removeEventListener('pointerup', onUp);
 				};
 			},
-			[],
+			[dragEnabled],
 			DRAG,
 		);
 
@@ -399,21 +520,28 @@ function createMotionComponent(tag: string) {
 		// tree — nested/shared layout, scale correction — is out of scope.)
 		useLayoutEffect(
 			() => {
-				if (!props.layout) return;
+				if (!layoutEnabled || !props.layout) {
+					latest.layoutBox = undefined;
+					return;
+				}
 				const prevTransform = node.style.transform;
 				node.style.transform = '';
 				const r = node.getBoundingClientRect();
 				const box = { left: r.left, top: r.top, width: r.width, height: r.height };
 				const prev = latest.layoutBox;
 				latest.layoutBox = box;
-				if (!prev) return;
-				const dx = prev.left - box.left;
-				const dy = prev.top - box.top;
-				const sx = box.width ? prev.width / box.width : 1;
-				const sy = box.height ? prev.height / box.height : 1;
-				if (dx || dy || sx !== 1 || sy !== 1) {
-					node.style.transform = `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
-					animate(node, { transform: 'translate(0px, 0px) scale(1, 1)' }, transition);
+				if (!prev) {
+					node.style.transform = prevTransform;
+					return;
+				}
+				const projection = projectLayout(prev, box, latest.layoutMode);
+				if (projection) {
+					if (latest.shouldReduceMotion) {
+						node.style.transform = prevTransform;
+					} else {
+						node.style.transform = projection.from;
+						animate(node, { transform: projection.to }, layoutTransition(latest.transition));
+					}
 				} else {
 					node.style.transform = prevTransform;
 				}
@@ -423,41 +551,43 @@ function createMotionComponent(tag: string) {
 		);
 
 		// `layoutId`: shared-element crossfade. On mount, if a same-id element recently
-		// unmounted, FLIP from its recorded box to ours; on unmount, record our box for
-		// the next same-id element (the cleanup runs while still in the DOM).
+		// unmounted, FLIP from its recorded box to ours.
 		useLayoutEffect(
 			() => {
-				const id = props.layoutId;
+				if (!layoutEnabled) return;
+				const id = layoutIdKey;
 				if (!id) return;
-				const prev = layoutCells.get(id);
+				const prev = takeLayoutCell(id);
 				if (prev) {
-					layoutCells.delete(id);
-					node.style.transform = '';
-					const box = boxOf(node);
-					const dx = prev.left - box.left;
-					const dy = prev.top - box.top;
-					const sx = box.width ? prev.width / box.width : 1;
-					const sy = box.height ? prev.height / box.height : 1;
-					if (dx || dy || sx !== 1 || sy !== 1) {
-						node.style.transform = `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
-						animate(node, { transform: 'translate(0px, 0px) scale(1, 1)' }, latest.transition);
+					if (!latest.shouldReduceMotion) {
+						const prevTransform = node.style.transform;
+						node.style.transform = '';
+						const box = boxOf(node);
+						const projection = projectLayout(prev, box, latest.layoutMode);
+						if (projection) {
+							node.style.transform = projection.from;
+							animate(node, { transform: projection.to }, layoutTransition(latest.transition));
+						} else {
+							node.style.transform = prevTransform;
+						}
 					}
 				}
-				return () => {
-					if (node.isConnected) layoutCells.set(id, boxOf(node));
-				};
 			},
-			[],
+			[layoutEnabled, layoutIdKey],
 			LAYOUT_ID,
 		);
 
-		// Exit: this effect's CLEANUP runs on unmount, while the node is still in the
-		// DOM (octane fires cleanups before detaching). We clone the leaving node
-		// OUTSIDE the block's range (so octane's removal doesn't take the clone),
-		// animate the exit on the clone, and remove the clone when it finishes.
+		// Unmount: this cleanup runs while the node is still in the DOM. Record shared
+		// layout state here—not in the keyed claim effect, whose cleanup also runs on
+		// dependency changes—then clone any exiting node outside the block's range.
 		useLayoutEffect(
 			() => () => {
 				const n: HTMLElement | null = latest.node;
+				const layoutId = latest.layoutIdKey;
+				if (latest.layoutEnabled && layoutId && n?.isConnected) {
+					recordLayoutCell(layoutId, boxOf(n));
+				}
+				if (!latest.animationEnabled) return;
 				const exit = latest.exit;
 				if (!exit || !n || !n.isConnected || n.parentNode == null) return;
 				const parent = n.parentNode as HTMLElement;
@@ -469,7 +599,12 @@ function createMotionComponent(tag: string) {
 				clone.style.width = `${rect.width}px`;
 				clone.style.height = `${rect.height}px`;
 				parent.appendChild(clone);
-				const controls = animate(clone, exit, latest.exitTransition ?? latest.transition);
+				const controls = animateTarget(
+					clone,
+					exit,
+					latest.exitTransition ?? latest.transition,
+					latest.shouldReduceMotion,
+				);
 				whenDone(controls, () => clone.remove());
 			},
 			[],
@@ -478,17 +613,41 @@ function createMotionComponent(tag: string) {
 	};
 }
 
+export const domAnimation: MotionFeatureBundle = Object.freeze({
+	animation: true,
+	gestures: true,
+	drag: false,
+	layout: false,
+});
+
+export const domMax: MotionFeatureBundle = Object.freeze({
+	animation: true,
+	gestures: true,
+	drag: true,
+	layout: true,
+});
+
+export type MotionProxy = Record<string, MotionComponent>;
+
+function motionProxy(preloadedFeatures: boolean): MotionProxy {
+	return new Proxy(
+		{},
+		{
+			get(cache: Record<string, MotionComponent>, tag: string | symbol) {
+				if (typeof tag !== 'string') return undefined;
+				return cache[tag] ?? (cache[tag] = createMotionComponent(tag, preloadedFeatures));
+			},
+		},
+	);
+}
+
 // `motion.div`, `motion.span`, … — a proxy that lazily builds (and caches) a
 // component per tag.
-export const motion: any = new Proxy(
-	{},
-	{
-		get(cache: any, tag: string | symbol) {
-			if (typeof tag !== 'string') return undefined;
-			return cache[tag] ?? (cache[tag] = createMotionComponent(tag));
-		},
-	},
-);
+export const motion = motionProxy(true);
+
+// `m` renders the same hosts but activates animation/gesture/layout behavior
+// only from its nearest LazyMotion feature bundle.
+export const m = motionProxy(false);
 
 // AnimatePresence — renders its children; each `motion.*` with an `exit` prop
 // self-animates its own removal (see the exit cleanup above), so this is a thin
@@ -497,13 +656,122 @@ export function AnimatePresence(props: any, scope: any): void {
 	renderTransparentChildren(props.children, scope);
 }
 
+export interface LayoutGroupProps {
+	children?: unknown;
+	id?: string;
+	inherit?: boolean | 'id';
+}
+
+export function LayoutGroup(props: LayoutGroupProps, scope: any): void {
+	const parent = useContext(LayoutGroupContext);
+	const value = useMemo(
+		() => {
+			const inherit = props.inherit ?? true;
+			const inheritId = inherit === true || inherit === 'id';
+			const id =
+				inheritId && parent.id ? (props.id ? `${parent.id}-${props.id}` : parent.id) : props.id;
+			const parentNamespace = parent.layoutIdNamespace ?? (parent.id ? [parent.id] : undefined);
+			const layoutIdNamespace =
+				inheritId && parent.id
+					? props.id
+						? [...(parentNamespace ?? [parent.id]), props.id]
+						: parentNamespace
+					: props.id
+						? [props.id]
+						: undefined;
+			return { id, layoutIdNamespace };
+		},
+		[parent.id, parent.layoutIdNamespace, props.id, props.inherit],
+		LAYOUT_GROUP_STATE,
+	);
+	provideContext(scope, LayoutGroupContext, value);
+	renderTransparentChildren(props.children, scope);
+}
+
 // MotionConfig — provides global defaults (transition, reduced motion) to every
 // motion element below it. A plain-TS component: stamps the config context, then
 // renders children.
 export function MotionConfig(props: any, scope: any): void {
+	const parent = useContext(MotionConfigContext);
+	const reducedMotion = props.reducedMotion ?? parent.reducedMotion ?? 'never';
+	// Octane slots hooks by call site, so this subscription can stay conditional.
+	// Avoid paying for matchMedia listeners when the policy never consults it.
+	const userPreference = reducedMotion === 'user' ? useReducedMotionAtSlot(CONFIG_REDUCED) : false;
 	provideContext(scope, MotionConfigContext, {
-		transition: props.transition,
-		reducedMotion: props.reducedMotion,
+		transition: props.transition ?? parent.transition,
+		reducedMotion,
+		shouldReduceMotion: reducedMotion === 'always' || (reducedMotion === 'user' && userPreference),
+	});
+	renderTransparentChildren(props.children, scope);
+}
+
+export type LazyMotionFeatures =
+	| MotionFeatureBundle
+	| (() =>
+			| Promise<MotionFeatureBundle | { default: MotionFeatureBundle }>
+			| MotionFeatureBundle
+			| { default: MotionFeatureBundle });
+
+export interface LazyMotionProps {
+	children?: unknown;
+	features: LazyMotionFeatures;
+	strict?: boolean;
+}
+
+interface LoadedLazyFeatures {
+	features: MotionFeatureBundle | null;
+	error?: { value: unknown };
+}
+
+function normalizeFeatures(
+	value: MotionFeatureBundle | { default: MotionFeatureBundle },
+): MotionFeatureBundle {
+	return 'default' in value ? value.default : value;
+}
+
+export function LazyMotion(props: LazyMotionProps, scope: any): void {
+	const [loaded, setLoaded] = useState<LoadedLazyFeatures>(() => ({ features: null }), LAZY_STATE);
+	const source = props.features;
+	const isLoader = typeof source === 'function';
+	const features = isLoader ? loaded.features : normalizeFeatures(source);
+	if (isLoader && loaded.error) throw loaded.error.value;
+
+	// Match Motion's mount-time loader semantics. In particular, an idiomatic
+	// inline `features={() => import(...)}` must survive parent re-renders.
+	useEffect(
+		() => {
+			if (typeof source !== 'function') return;
+			let current = true;
+			const fail = (error: unknown) => {
+				if (current) setLoaded({ features: null, error: { value: error } });
+			};
+			try {
+				void Promise.resolve(source()).then((value) => {
+					if (!current) return;
+					let features: MotionFeatureBundle;
+					try {
+						features = normalizeFeatures(value);
+					} catch (error) {
+						fail(error);
+						return;
+					}
+					setLoaded({ features });
+				}, fail);
+			} catch (error) {
+				fail(error);
+			}
+			return () => {
+				current = false;
+			};
+		},
+		[],
+		LAZY_EFFECT,
+	);
+
+	provideContext(scope, LazyMotionContext, {
+		features,
+		strict: props.strict === true,
+		provided: true,
 	});
 	renderTransparentChildren(props.children, scope);
 }
@@ -518,7 +786,15 @@ export { useScroll } from './useScroll';
 export { useTransform } from './useTransform';
 export { useSpring } from './useSpring';
 export { useMotionValueEvent } from './useMotionValueEvent';
-export { MotionConfigContext, VariantContext, StaggerContext } from './context';
+export { useReducedMotion } from './useReducedMotion';
+export {
+	LayoutGroupContext,
+	LazyMotionContext,
+	MotionConfigContext,
+	VariantContext,
+	StaggerContext,
+} from './context';
 
 // Re-export motion's framework-agnostic helpers (animate, stagger, value types, …).
 export * from 'motion';
+export type { TargetAndTransition, Transition } from 'motion';

package/src/layout.ts

@@ -0,0 +1,102 @@
+export interface LayoutBox {
+	left: number;
+	top: number;
+	width: number;
+	height: number;
+}
+
+export type LayoutAnimationMode = true | 'position' | 'size';
+
+export interface LayoutProjection {
+	from: string;
+	to: string;
+}
+
+export function layoutAnimationMode(layout: unknown): LayoutAnimationMode {
+	return layout === 'position' || layout === 'size' ? layout : true;
+}
+
+export function projectLayout(
+	previous: LayoutBox,
+	next: LayoutBox,
+	mode: LayoutAnimationMode,
+): LayoutProjection | null {
+	const translate = mode !== 'size';
+	const scale = mode !== 'position';
+	const x = translate ? previous.left - next.left : 0;
+	const y = translate ? previous.top - next.top : 0;
+	const scaleX = scale && next.width ? previous.width / next.width : 1;
+	const scaleY = scale && next.height ? previous.height / next.height : 1;
+
+	if (x === 0 && y === 0 && scaleX === 1 && scaleY === 1) return null;
+	if (mode === 'position') {
+		return {
+			from: `translate(${x}px, ${y}px)`,
+			to: 'translate(0px, 0px)',
+		};
+	}
+	if (mode === 'size') {
+		return {
+			from: `scale(${scaleX}, ${scaleY})`,
+			to: 'scale(1, 1)',
+		};
+	}
+	return {
+		from: `translate(${x}px, ${y}px) scale(${scaleX}, ${scaleY})`,
+		to: 'translate(0px, 0px) scale(1, 1)',
+	};
+}
+
+export function layoutTransition(transition: any): any {
+	const selected = transition?.layout ?? transition?.default ?? transition;
+	if (selected !== transition && selected?.inherit && transition) {
+		const { inherit: _inherit, ...valueTransition } = selected;
+		return { ...transition, ...valueTransition };
+	}
+	return selected;
+}
+
+export function layoutCellKey(namespace: readonly string[] | undefined, layoutId: unknown): string {
+	let key = '';
+	if (namespace) {
+		for (const segment of namespace) key += `${segment.length}:${segment}|`;
+	}
+	const id = String(layoutId);
+	return `${key}${id.length}:${id}`;
+}
+
+// Shared layout snapshots only bridge replacements in the current synchronous
+// commit. Preserve every handoff in that commit, then expire anything unclaimed
+// at the next microtask so no snapshot survives into a later turn.
+const layoutCells = new Map<string, LayoutBox>();
+let pendingClear: object | null = null;
+
+function scheduleLayoutCellClear(): void {
+	if (pendingClear) return;
+	const token = {};
+	pendingClear = token;
+	queueMicrotask(() => {
+		if (pendingClear !== token) return;
+		layoutCells.clear();
+		pendingClear = null;
+	});
+}
+
+export function recordLayoutCell(id: string, box: LayoutBox): void {
+	layoutCells.set(id, box);
+	scheduleLayoutCellClear();
+}
+
+export function takeLayoutCell(id: string): LayoutBox | undefined {
+	const box = layoutCells.get(id);
+	if (box) layoutCells.delete(id);
+	return box;
+}
+
+export const layoutCellsForTests = {
+	size: (): number => layoutCells.size,
+	reset(): void {
+		layoutCells.clear();
+		pendingClear = null;
+	},
+};

package/src/react-m.ts

@@ -0,0 +1,174 @@
+// Tree-shakable-style named host surface matching `motion/react-m`.
+//
+// Each export is the lazy-feature variant of its corresponding motion host.
+// Consumers normally use this entry as a namespace:
+//   import * as m from '@octanejs/motion/react-m'
+//   <m.div />
+import { m } from './index';
+
+export const {
+	a,
+	abbr,
+	address,
+	animate,
+	area,
+	article,
+	aside,
+	audio,
+	b,
+	base,
+	bdi,
+	bdo,
+	big,
+	blockquote,
+	body,
+	button,
+	canvas,
+	caption,
+	circle,
+	cite,
+	clipPath,
+	code,
+	col,
+	colgroup,
+	data,
+	datalist,
+	dd,
+	defs,
+	del,
+	desc,
+	details,
+	dfn,
+	dialog,
+	div,
+	dl,
+	dt,
+	ellipse,
+	em,
+	embed,
+	feBlend,
+	feColorMatrix,
+	feComponentTransfer,
+	feComposite,
+	feConvolveMatrix,
+	feDiffuseLighting,
+	feDisplacementMap,
+	feDistantLight,
+	feDropShadow,
+	feFlood,
+	feFuncA,
+	feFuncB,
+	feFuncG,
+	feFuncR,
+	feGaussianBlur,
+	feImage,
+	feMerge,
+	feMergeNode,
+	feMorphology,
+	feOffset,
+	fePointLight,
+	feSpecularLighting,
+	feSpotLight,
+	feTile,
+	feTurbulence,
+	fieldset,
+	figcaption,
+	figure,
+	filter,
+	footer,
+	foreignObject,
+	form,
+	g,
+	h1,
+	h2,
+	h3,
+	h4,
+	h5,
+	h6,
+	head,
+	header,
+	hgroup,
+	hr,
+	html,
+	i,
+	iframe,
+	image,
+	img,
+	input,
+	ins,
+	kbd,
+	keygen,
+	label,
+	legend,
+	li,
+	line,
+	linearGradient,
+	link,
+	main,
+	map,
+	mark,
+	marker,
+	mask,
+	menu,
+	menuitem,
+	metadata,
+	meter,
+	nav,
+	object,
+	ol,
+	optgroup,
+	option,
+	output,
+	p,
+	param,
+	path,
+	pattern,
+	picture,
+	polygon,
+	polyline,
+	pre,
+	progress,
+	q,
+	radialGradient,
+	rect,
+	rp,
+	rt,
+	ruby,
+	s,
+	samp,
+	script,
+	section,
+	select,
+	small,
+	source,
+	span,
+	stop,
+	strong,
+	style,
+	sub,
+	summary,
+	sup,
+	svg,
+	symbol,
+	table,
+	tbody,
+	td,
+	text,
+	textPath,
+	textarea,
+	tfoot,
+	th,
+	thead,
+	time,
+	title,
+	tr,
+	track,
+	tspan,
+	u,
+	ul,
+	use,
+	video,
+	view,
+	wbr,
+	webview,
+} = m;

package/src/useReducedMotion.ts

@@ -0,0 +1,86 @@
+// `useReducedMotion()` — subscribe to the user's operating-system preference.
+//
+// Motion's React hook reads the shared `prefers-reduced-motion` query. This
+// binding keeps the query shared too, but also publishes later `change` events
+// so mounted Octane consumers update when the setting changes.
+import { useSyncExternalStore } from 'octane';
+
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+type MatchMedia = typeof window.matchMedia;
+
+let activeMatchMedia: MatchMedia | null = null;
+let activeQuery: MediaQueryList | null = null;
+let detachActiveQuery: (() => void) | null = null;
+const listeners = new Set<() => void>();
+
+function notifyListeners(): void {
+	for (const listener of listeners) listener();
+}
+
+function attachQuery(query: MediaQueryList): () => void {
+	const onChange = () => notifyListeners();
+
+	if (typeof query.addEventListener === 'function') {
+		query.addEventListener('change', onChange);
+		return () => query.removeEventListener('change', onChange);
+	}
+
+	// Safari < 14 exposes the deprecated MediaQueryList listener API only.
+	query.addListener(onChange);
+	return () => query.removeListener(onChange);
+}
+
+function getQuery(): MediaQueryList | null {
+	if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+		return null;
+	}
+
+	const matchMedia = window.matchMedia;
+	if (activeQuery === null || activeMatchMedia !== matchMedia) {
+		detachActiveQuery?.();
+		detachActiveQuery = null;
+		activeMatchMedia = matchMedia;
+		activeQuery = matchMedia.call(window, REDUCED_MOTION_QUERY);
+		if (listeners.size > 0) detachActiveQuery = attachQuery(activeQuery);
+	}
+
+	return activeQuery;
+}
+
+function getSnapshot(): boolean {
+	return getQuery()?.matches ?? false;
+}
+
+function getServerSnapshot(): boolean {
+	return false;
+}
+
+function subscribe(listener: () => void): () => void {
+	listeners.add(listener);
+	const query = getQuery();
+	if (query !== null && detachActiveQuery === null) {
+		detachActiveQuery = attachQuery(query);
+	}
+
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size === 0) {
+			detachActiveQuery?.();
+			detachActiveQuery = null;
+		}
+	};
+}
+
+export function useReducedMotionAtSlot(slot: symbol): boolean {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot, slot);
+}
+
+export function useReducedMotion(): boolean;
+export function useReducedMotion(...args: any[]): boolean {
+	// Calls from compiled `.tsrx` append the call-site slot. Accept no public
+	// arguments, but deliberately strip that compiler-owned trailing Symbol.
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot, slot);
+}