@octane-ts/motion 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @octane-ts/motion
+
+[Framer Motion](https://motion.dev) for the [octane](https://github.com/octane-ts/octane) renderer.
+
+Motion separates a framework-agnostic animation engine (`animate`) and gesture
+primitives (`hover`, `press`) from its React components (`motion.div`,
+`AnimatePresence`). This package reuses the engine + gestures verbatim and
+reimplements the components on octane.
+
+```tsx
+// before
+import { motion, AnimatePresence } from 'motion/react';
+// after
+import { motion, AnimatePresence } from '@octane-ts/motion';
+
+function Card() @{
+  <motion.div
+    className="card"
+    initial={{ opacity: 0, y: 20 }}
+    animate={{ opacity: 1, y: 0 }}
+    transition={{ duration: 0.3 }}
+    whileHover={{ scale: 1.05 }}
+    whileTap={{ scale: 0.95 }}
+  >
+    {'hello'}
+  </motion.div>
+}
+
+function List(props) @{
+  <AnimatePresence>
+    @if (props.show) {
+      <motion.div exit={{ opacity: 0 }}>{'I fade out when removed'}</motion.div>
+    }
+  </AnimatePresence>
+}
+```
+
+## What's bound
+
+- `motion.<tag>` — `initial`, `animate`, `transition`, `whileHover`, `whileTap`,
+  `whileFocus`, `whileInView` (+ `viewport`), `exit`, `drag` (+ `dragConstraints`,
+  `onDrag*`), `layout`, `layoutId`, `variants`, plus any DOM props (className, style,
+  events, …) and `style` MotionValues spread/bound onto the element.
+- `AnimatePresence` — exit animations on removal.
+- `MotionConfig` — global `transition` / `reducedMotion` defaults via context.
+- `variants` — label resolution (`animate="visible"`) + parent→child propagation +
+  `staggerChildren` / `delayChildren` (number or `stagger()` function) / `staggerDirection`.
+- `useMotionValue()`, `useScroll()`, `useAnimate()` — MotionValues, scroll-linked
+  values, and imperative scoped animation.
+- `useTransform()`, `useSpring()`, `useMotionValueEvent()` — MotionValue composition:
+  derive a value (range-map / transformer / multi-input combiner), spring toward a
+  value or source, and subscribe to a value's events.
+- Motion's framework-agnostic helpers (`animate`, `stagger`, value types, …),
+  re-exported.
+
+## How it works
+
+octane had no public way for a runtime-proxy component to render a host element
+wrapping children, nor to provide context from plain-TS — so this package added two
+runtime primitives: `hostComponent` and `provideContext`. `motion.<tag>` renders a
+real `<tag>` through `hostComponent`, captures the node, and drives:
+
+- **Animations** from layout effects calling motion's `animate()`; **gestures** via
+  `hover()` / `press()` / `inView()`; **MotionValues** (from `useMotionValue` /
+  `useScroll`) by subscribing in `style` and writing the element directly.
+- **`MotionConfig` + `variants`** through `provideContext`: a plain-TS component
+  stamps context for its children (config defaults, active variant labels).
+- **`drag`** with pointer events (axis lock + `dragConstraints`).
+- **Exit** without any deferred-deletion machinery: octane fires cleanups *before*
+  detaching the DOM, so a leaving element's unmount cleanup clones it (outside the
+  range octane is about to remove), animates the exit on the clone, and removes it
+  when it finishes.
+- **`layout` / `layoutId`** via FLIP: measure the box, and if it moved/resized —
+  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.
+
+## 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
+`useTransform`'s output-map form (`useTransform(mv, [0, 100], { opacity: [0, 1] })`).
+
+Stagger specifics: `when: 'beforeChildren' | 'afterChildren'` parent/child sequencing
+is not implemented, and a child's stagger index is fixed at registration order (a
+keyed reorder does not re-stagger).

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@octane-ts/motion",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Framer Motion bindings for the octane renderer — reuses motion-dom's animation engine, swaps the React components for octane host components.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octane-ts/octane.git",
+    "directory": "packages/motion"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "motion": "^12.0.0",
+    "octane-ts": "0.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/context.ts

@@ -0,0 +1,59 @@
+// Contexts shared across motion components.
+import { createContext, useContext } from 'octane-ts';
+
+// MotionConfig — global defaults (transition, reduced motion) inherited by every
+// motion element below a `<MotionConfig>`.
+export interface MotionConfigValue {
+	transition?: any;
+	reducedMotion?: 'always' | 'never' | 'user';
+}
+export const MotionConfigContext = createContext<MotionConfigValue>({});
+
+// 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
+// label (Framer Motion's variant propagation).
+export interface VariantLabels {
+	initial?: string;
+	animate?: string;
+}
+export const VariantContext = createContext<VariantLabels>({});
+
+// Stagger orchestration: a motion element with `staggerChildren`/`delayChildren` in
+// its (variant) transition provides this to its variant-inheriting children, who each
+// register to get a stable index and derive a per-child animation delay from it.
+export interface StaggerOrchestration {
+	active: boolean;
+	staggerChildren: number;
+	// A number base delay, or Framer's `stagger()` / `(index, total) => delay` function.
+	delayChildren: number | ((index: number, total: number) => number);
+	staggerDirection: number;
+	// Ordered child tokens (registered in render/DOM order); index + length drive delay.
+	children: any[];
+}
+export const StaggerContext = createContext<StaggerOrchestration | null>(null);
+
+export function useMotionConfig(): MotionConfigValue {
+	return useContext(MotionConfigContext);
+}
+
+export function useInheritedVariants(): VariantLabels {
+	return useContext(VariantContext);
+}
+
+// Resolve a target that may be a variant label (string) against a `variants` map,
+// or pass an inline target object straight through.
+export function resolveVariant(value: any, variants: any): any {
+	if (typeof value === 'string') return variants ? variants[value] : undefined;
+	return value;
+}
+
+// Split a variant target into its animatable values and its `transition` (Framer
+// puts orchestration + per-variant transition options under a `transition` key on the
+// target object; the engine's `animate(el, values, options)` wants them separated).
+export function splitVariant(v: any): { values: any; transition: any } {
+	if (v && typeof v === 'object' && !Array.isArray(v) && 'transition' in v) {
+		const { transition, ...values } = v;
+		return { values, transition };
+	}
+	return { values: v, transition: undefined };
+}

package/src/index.ts

@@ -0,0 +1,519 @@
+// @octane-ts/motion — Framer Motion for the octane renderer.
+//
+// Reuses motion's framework-agnostic animation engine (`animate`), gesture
+// primitives (`hover`, `press`, `inView`), MotionValues, and scoped animation, and
+// reimplements the `motion.*` components on octane. Each `motion.tag` renders a real
+// host `<tag>` (via octane's `hostComponent` primitive), captures its node, and
+// 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 { hostComponent, useLayoutEffect, useState, provideContext } from 'octane-ts';
+import {
+	MotionConfigContext,
+	VariantContext,
+	StaggerContext,
+	resolveVariant,
+	splitVariant,
+} from './context';
+import { isMotionValue, isTransformKey, applyStyleValue } from './useMotionValue';
+import { useContext } from 'octane-ts';
+
+// 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.
+const REFS = Symbol.for('octane-motion:refs');
+const ENTER = Symbol.for('octane-motion:enter');
+const ANIMATE = Symbol.for('octane-motion:animate');
+const GESTURE = Symbol.for('octane-motion:gesture');
+const EXIT = Symbol.for('octane-motion:exit');
+const LAYOUT = Symbol.for('octane-motion:layout');
+const DRAG = Symbol.for('octane-motion:drag');
+const INVIEW = Symbol.for('octane-motion:inview');
+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');
+
+// 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 r = n.getBoundingClientRect();
+	return { left: r.left, top: r.top, width: r.width, height: r.height };
+};
+
+// Props consumed by motion (everything else is spread onto the host element).
+const MOTION_PROPS = new Set([
+	'initial',
+	'animate',
+	'transition',
+	'whileHover',
+	'whileTap',
+	'whileFocus',
+	'whileInView',
+	'viewport',
+	'exit',
+	'layout',
+	'layoutId',
+	'variants',
+	'drag',
+	'dragConstraints',
+	'dragElastic',
+	'dragMomentum',
+	'onDrag',
+	'onDragStart',
+	'onDragEnd',
+	'onAnimationComplete',
+	'children',
+]);
+
+function domProps(props: any): Record<string, any> {
+	const out: Record<string, any> = {};
+	for (const k in props) {
+		if (MOTION_PROPS.has(k)) continue;
+		if (k === 'style' && props.style && typeof props.style === 'object') {
+			// Motion values + transform shorthands (x/y/scale/…) are applied by the
+			// motion-value effect, not written to the DOM as raw style.
+			const s: Record<string, any> = {};
+			for (const sk in props.style) {
+				const v = props.style[sk];
+				if (isMotionValue(v) || isTransformKey(sk)) continue;
+				s[sk] = v;
+			}
+			out.style = s;
+		} else {
+			out[k] = props[k];
+		}
+	}
+	return out;
+}
+
+// Cheap structural key so a layout effect re-runs only when the target actually
+// changes (inline objects are a new reference every render).
+function stableKey(v: any): string {
+	return v == null ? '' : typeof v === 'string' ? v : JSON.stringify(v);
+}
+
+function whenDone(controls: any, done: () => void): void {
+	const p = controls && (controls.finished ?? controls);
+	if (p && typeof p.then === 'function') p.then(done, done);
+	else done();
+}
+
+function clamp(v: number, min: number, max: number): number {
+	return v < min ? min : v > max ? max : v;
+}
+
+function createMotionComponent(tag: string) {
+	return function MotionComponent(scope: any, props: any): void {
+		const config = useContext(MotionConfigContext);
+		const inherited = useContext(VariantContext);
+		// Read the PARENT's stagger orchestration before providing our own below.
+		const parentStagger = useContext(StaggerContext);
+		const variants = props.variants;
+
+		// Variant labels: an explicit prop wins, else inherit the parent's label.
+		const initialLabel = props.initial !== undefined ? props.initial : inherited.initial;
+		const animateLabel = props.animate !== undefined ? props.animate : inherited.animate;
+		// A child PARTICIPATES in its parent's stagger when it animates via an inherited
+		// label rather than its own `animate`.
+		const inheritsAnimate = props.animate === undefined && typeof inherited.animate === 'string';
+		const { values: resolvedInitial } = splitVariant(resolveVariant(initialLabel, variants));
+		const { values: resolvedAnimate, transition: animateVariantTransition } = splitVariant(
+			resolveVariant(animateLabel, variants),
+		);
+		const transition = animateVariantTransition ?? props.transition ?? config.transition;
+
+		// Stable holder (also our stagger token) — created before we register/provide.
+		const [latest] = useState(() => ({}) as any, REFS);
+
+		// As a child: register with the parent's orchestration to get a stable index.
+		if (parentStagger && parentStagger.active && inheritsAnimate) {
+			if (!parentStagger.children.includes(latest)) parentStagger.children.push(latest);
+			latest.staggerParent = parentStagger;
+		} else {
+			latest.staggerParent = null;
+		}
+
+		// As a parent: build/refresh OUR orchestration from our (variant) transition and
+		// provide it to children.
+		const [orch] = useState(
+			() =>
+				({
+					active: false,
+					staggerChildren: 0,
+					delayChildren: 0,
+					staggerDirection: 1,
+					children: [],
+				}) as any,
+			STAGGER_ORCH,
+		);
+		const staggerSrc = animateVariantTransition ?? props.transition;
+		orch.staggerChildren = staggerSrc?.staggerChildren ?? 0;
+		orch.delayChildren = staggerSrc?.delayChildren ?? 0;
+		orch.staggerDirection = staggerSrc?.staggerDirection ?? 1;
+		orch.active =
+			orch.staggerChildren > 0 ||
+			orch.delayChildren > 0 ||
+			typeof orch.delayChildren === 'function';
+
+		// Propagate the active labels + stagger orchestration to descendants (passing
+		// through inherited labels), before rendering children.
+		provideContext(scope, VariantContext, {
+			initial: typeof initialLabel === 'string' ? initialLabel : inherited.initial,
+			animate: typeof animateLabel === 'string' ? animateLabel : inherited.animate,
+		});
+		provideContext(scope, StaggerContext, orch);
+
+		const node = hostComponent(scope, '_m', tag, domProps(props), props.children) as HTMLElement;
+
+		// Resolve a gesture/exit target to its values + its own (per-variant) transition,
+		// so a variant target carrying a `transition` key honors it (like `animate` does).
+		const rsv = (v: any) => splitVariant(resolveVariant(v, variants));
+		const exitS = rsv(props.exit);
+		const hoverS = rsv(props.whileHover);
+		const tapS = rsv(props.whileTap);
+		const focusS = rsv(props.whileFocus);
+		const inViewS = rsv(props.whileInView);
+
+		latest.node = node;
+		latest.transition = transition;
+		latest.exit = exitS.values;
+		latest.exitTransition = exitS.transition;
+		latest.whileHover = hoverS.values;
+		latest.whileHoverTransition = hoverS.transition;
+		latest.whileTap = tapS.values;
+		latest.whileTapTransition = tapS.transition;
+		latest.whileFocus = focusS.values;
+		latest.whileFocusTransition = focusS.transition;
+		latest.whileInView = inViewS.values;
+		latest.whileInViewTransition = inViewS.transition;
+		latest.base = resolvedAnimate ?? resolvedInitial ?? {};
+		latest.drag = props.drag;
+		latest.dragConstraints = props.dragConstraints;
+		latest.onDrag = props.onDrag;
+		latest.onDragStart = props.onDragStart;
+		latest.onDragEnd = props.onDragEnd;
+
+		// `initial`: apply instantly on mount (before the animate effect runs).
+		useLayoutEffect(
+			() => {
+				if (resolvedInitial) animate(node, resolvedInitial, { duration: 0 });
+			},
+			[],
+			ENTER,
+		);
+
+		// `animate`: animate to the (resolved) target on mount and whenever it changes.
+		// If we're a stagger child, fold in our per-child delay (our index + the sibling
+		// count are both known by now — all children registered during the parent render).
+		useLayoutEffect(
+			() => {
+				if (resolvedAnimate) {
+					let t = transition;
+					const o = latest.staggerParent;
+					if (o && o.active) {
+						const index = o.children.indexOf(latest);
+						const count = o.children.length;
+						let delay: number;
+						if (typeof o.delayChildren === 'function') {
+							// Framer's stagger()/function form: delayChildren(index, total) IS the delay.
+							delay = o.delayChildren(index, count);
+						} else {
+							const offset = o.staggerDirection === 1 ? index : count - 1 - index;
+							delay = (o.delayChildren || 0) + offset * (o.staggerChildren || 0);
+						}
+						if (delay > 0) t = { ...(t || {}), delay: (t?.delay || 0) + delay };
+					}
+					const controls = animate(node, resolvedAnimate, t);
+					if (props.onAnimationComplete) whenDone(controls, () => props.onAnimationComplete());
+					return () => controls.stop();
+				}
+			},
+			[stableKey(resolvedAnimate), stableKey(transition)],
+			ANIMATE,
+		);
+
+		// As a stagger child, deregister from the parent's orchestration on unmount so
+		// indices/counts stay correct for surviving siblings.
+		useLayoutEffect(
+			() => () => {
+				const o = latest.staggerParent;
+				if (o) {
+					const i = o.children.indexOf(latest);
+					if (i >= 0) o.children.splice(i, 1);
+				}
+			},
+			[],
+			STAGGER,
+		);
+
+		// Motion values + static transform shorthands in `style`. MotionValues are
+		// subscribed (and update the element without a re-render); shorthands apply once.
+		useLayoutEffect(
+			() => {
+				const style = props.style;
+				if (!style || typeof style !== 'object') return;
+				const transformState: Record<string, any> = {};
+				const cleanups: Array<() => void> = [];
+				for (const key in style) {
+					const v = style[key];
+					if (isMotionValue(v)) {
+						const apply = (val: any) => applyStyleValue(node, key, val, transformState);
+						apply(v.get());
+						cleanups.push(v.on('change', apply));
+					} else if (isTransformKey(key)) {
+						applyStyleValue(node, key, v, transformState);
+					}
+				}
+				return () => cleanups.forEach((c) => c());
+			},
+			[],
+			MV,
+		);
+
+		// Gestures: `whileHover` / `whileTap` / `whileFocus` animate to the gesture
+		// target on start and back to the resting state on end. Targets/transition are
+		// read from `latest`, so prop changes take effect without re-binding.
+		useLayoutEffect(
+			() => {
+				const cleanups: Array<() => void> = [];
+				const gesture = (
+					bind: (el: Element, onStart: () => () => void) => () => void,
+					valuesKey: string,
+					transitionKey: string,
+				) =>
+					bind(node, () => {
+						animate(node, latest[valuesKey], latest[transitionKey] ?? latest.transition);
+						return () => {
+							animate(node, latest.base, latest.transition);
+						};
+					});
+				if (props.whileHover)
+					cleanups.push(gesture(hover as any, 'whileHover', 'whileHoverTransition'));
+				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);
+					node.addEventListener('focus', onFocus);
+					node.addEventListener('blur', onBlur);
+					cleanups.push(() => {
+						node.removeEventListener('focus', onFocus);
+						node.removeEventListener('blur', onBlur);
+					});
+				}
+				return () => cleanups.forEach((c) => c());
+			},
+			[],
+			GESTURE,
+		);
+
+		// `whileInView`: animate when the element enters the viewport, and back out
+		// when it leaves (unless `viewport.once`). Reuses motion's `inView`.
+		useLayoutEffect(
+			() => {
+				if (!props.whileInView) return;
+				const stop = inView(
+					node,
+					() => {
+						animate(node, latest.whileInView, latest.whileInViewTransition ?? latest.transition);
+						return () => {
+							if (!props.viewport?.once) animate(node, latest.base, latest.transition);
+						};
+					},
+					props.viewport,
+				);
+				return () => stop();
+			},
+			[],
+			INVIEW,
+		);
+
+		// `drag`: pointer-drag the element, updating its transform. Supports axis lock
+		// (`drag="x"`/`"y"`) and `dragConstraints` (a box of left/right/top/bottom px).
+		useLayoutEffect(
+			() => {
+				if (!props.drag) return;
+				let active = false;
+				let startX = 0;
+				let startY = 0;
+				let originX = 0;
+				let originY = 0;
+				latest.dragX ??= 0;
+				latest.dragY ??= 0;
+				const onDown = (e: any) => {
+					active = true;
+					startX = e.clientX;
+					startY = e.clientY;
+					originX = latest.dragX;
+					originY = latest.dragY;
+					latest.onDragStart?.(e, { point: { x: e.clientX, y: e.clientY } });
+				};
+				const onMove = (e: any) => {
+					if (!active) return;
+					let x = latest.drag === 'y' ? originX : originX + (e.clientX - startX);
+					let y = latest.drag === 'x' ? originY : originY + (e.clientY - startY);
+					const c = latest.dragConstraints;
+					if (c) {
+						x = clamp(x, c.left ?? -Infinity, c.right ?? Infinity);
+						y = clamp(y, c.top ?? -Infinity, c.bottom ?? Infinity);
+					}
+					latest.dragX = x;
+					latest.dragY = y;
+					node.style.transform = `translateX(${x}px) translateY(${y}px)`;
+					latest.onDrag?.(e, {
+						offset: { x: x - originX, y: y - originY },
+						point: { x: e.clientX, y: e.clientY },
+					});
+				};
+				const onUp = (e: any) => {
+					if (!active) return;
+					active = false;
+					latest.onDragEnd?.(e, { point: { x: e.clientX, y: e.clientY } });
+				};
+				node.addEventListener('pointerdown', onDown);
+				window.addEventListener('pointermove', onMove);
+				window.addEventListener('pointerup', onUp);
+				return () => {
+					node.removeEventListener('pointerdown', onDown);
+					window.removeEventListener('pointermove', onMove);
+					window.removeEventListener('pointerup', onUp);
+				};
+			},
+			[],
+			DRAG,
+		);
+
+		// `layout`: animate layout changes with FLIP. Each commit, measure the box
+		// (transform reset so it's the LAYOUT box, not the transformed one); if it
+		// moved/resized vs the previous commit, apply the inverse transform instantly
+		// then animate it back to identity. (A single-element FLIP; the full projection
+		// tree — nested/shared layout, scale correction — is out of scope.)
+		useLayoutEffect(
+			() => {
+				if (!props.layout) 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);
+				} else {
+					node.style.transform = prevTransform;
+				}
+			},
+			undefined,
+			LAYOUT,
+		);
+
+		// `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).
+		useLayoutEffect(
+			() => {
+				const id = props.layoutId;
+				if (!id) return;
+				const prev = layoutCells.get(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);
+					}
+				}
+				return () => {
+					if (node.isConnected) layoutCells.set(id, boxOf(node));
+				};
+			},
+			[],
+			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.
+		useLayoutEffect(
+			() => () => {
+				const n: HTMLElement | null = latest.node;
+				const exit = latest.exit;
+				if (!exit || !n || !n.isConnected || n.parentNode == null) return;
+				const parent = n.parentNode as HTMLElement;
+				const clone = n.cloneNode(true) as HTMLElement;
+				const rect = n.getBoundingClientRect();
+				clone.style.position = 'absolute';
+				clone.style.top = `${n.offsetTop}px`;
+				clone.style.left = `${n.offsetLeft}px`;
+				clone.style.width = `${rect.width}px`;
+				clone.style.height = `${rect.height}px`;
+				parent.appendChild(clone);
+				const controls = animate(clone, exit, latest.exitTransition ?? latest.transition);
+				whenDone(controls, () => clone.remove());
+			},
+			[],
+			EXIT,
+		);
+	};
+}
+
+// `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));
+		},
+	},
+);
+
+// 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
+// passthrough that exists for drop-in compatibility with Framer Motion's API.
+export function AnimatePresence(scope: any, props: any): void {
+	if (typeof props.children === 'function') 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(scope: any, props: any): void {
+	provideContext(scope, MotionConfigContext, {
+		transition: props.transition,
+		reducedMotion: props.reducedMotion,
+	});
+	if (typeof props.children === 'function') props.children(scope);
+}
+
+export { useAnimate } from './useAnimate';
+export { useMotionValue } from './useMotionValue';
+export { useScroll } from './useScroll';
+export { useTransform } from './useTransform';
+export { useSpring } from './useSpring';
+export { useMotionValueEvent } from './useMotionValueEvent';
+export { MotionConfigContext, VariantContext, StaggerContext } from './context';
+
+// Re-export motion's framework-agnostic helpers (animate, stagger, value types, …).
+export * from 'motion';

package/src/useAnimate.ts

@@ -0,0 +1,32 @@
+// `useAnimate` — imperative, scoped animations. Returns `[scope, animate]`: attach
+// `scope` to an element (`ref={scope}`), then `animate(scope.current, …)` or
+// `animate('selector', …)` (resolved within the scope). Reuses motion's
+// `createScopedAnimate`; the binding just provides a stable scope object + cleanup.
+import { createScopedAnimate } from 'motion';
+import { useState, useEffect } from 'octane-ts';
+
+function sub(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':ua:' + tag) : undefined;
+}
+
+export function useAnimate(...args: any[]): [any, any] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+
+	// The scope IS the ref: octane sets `scope.current` to the element when it's
+	// passed as `ref={scope}`, and `scope.animations` tracks running animations so
+	// they can be stopped on unmount.
+	const [scope] = useState(() => ({ current: null, animations: [] }) as any, sub(slot, 'scope'));
+	const [animate] = useState(() => createScopedAnimate({ scope }), sub(slot, 'animate'));
+
+	useEffect(
+		() => () => {
+			scope.animations.forEach((animation: any) => animation.stop());
+			scope.animations.length = 0;
+		},
+		[],
+		sub(slot, 'clean'),
+	);
+
+	return [scope, animate];
+}

package/src/useMotionValue.ts

@@ -0,0 +1,68 @@
+// `useMotionValue(initial)` — a stable, reactive animatable value (reuses motion's
+// `motionValue`). Bind it to a `motion.*` element via `style={{ x: mv }}`; the
+// element subscribes and updates without re-rendering (see the style-binding effect
+// in index.ts).
+import { motionValue } from 'motion';
+import { useState } from 'octane-ts';
+
+export function useMotionValue<T>(initial: T, ...args: any[]): any {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const [mv] = useState(
+		() => motionValue(initial),
+		slot !== undefined ? Symbol.for((slot.description ?? '') + ':mv') : undefined,
+	);
+	return mv;
+}
+
+// A MotionValue duck-typed (reactive get/set/subscribe).
+export function isMotionValue(v: any): boolean {
+	return v != null && typeof v.get === 'function' && typeof v.on === 'function';
+}
+
+// Transform shorthands → CSS transform functions (matching Framer Motion).
+const TRANSFORM_FN: Record<string, string> = {
+	x: 'translateX',
+	y: 'translateY',
+	z: 'translateZ',
+	scale: 'scale',
+	scaleX: 'scaleX',
+	scaleY: 'scaleY',
+	rotate: 'rotate',
+	rotateX: 'rotateX',
+	rotateY: 'rotateY',
+	rotateZ: 'rotateZ',
+	skewX: 'skewX',
+	skewY: 'skewY',
+};
+const PX_KEYS = new Set(['x', 'y', 'z']);
+const DEG_KEYS = new Set(['rotate', 'rotateX', 'rotateY', 'rotateZ', 'skewX', 'skewY']);
+const NO_UNIT = new Set(['opacity', 'zIndex', 'scale', 'scaleX', 'scaleY']);
+
+export function isTransformKey(k: string): boolean {
+	return k in TRANSFORM_FN;
+}
+
+// Apply one style/transform value to the element, rebuilding the transform string
+// from the accumulated transform-key state.
+export function applyStyleValue(
+	node: HTMLElement,
+	key: string,
+	val: any,
+	transformState: Record<string, any>,
+): void {
+	const fn = TRANSFORM_FN[key];
+	if (fn) {
+		transformState[key] = val;
+		let t = '';
+		for (const k in transformState) {
+			let v = transformState[k];
+			if (typeof v === 'number')
+				v = PX_KEYS.has(k) ? `${v}px` : DEG_KEYS.has(k) ? `${v}deg` : `${v}`;
+			t += `${TRANSFORM_FN[k]}(${v}) `;
+		}
+		node.style.transform = t.trim();
+	} else {
+		(node.style as any)[key] = typeof val === 'number' && !NO_UNIT.has(key) ? `${val}px` : val;
+	}
+}

package/src/useMotionValueEvent.ts

@@ -0,0 +1,28 @@
+// `useMotionValueEvent(value, event, callback)` — subscribe `callback` to one of a
+// MotionValue's events ('change' | 'animationStart' | 'animationComplete' |
+// 'animationCancel') for the component's lifetime. Re-subscribes if value/event/
+// callback identity changes; unsubscribes on unmount. Reuses MotionValue's `on`,
+// which returns the unsubscribe fn (and, for 'change', stops idle animations).
+import { useInsertionEffect } from 'octane-ts';
+
+function sub(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':umve:' + tag) : undefined;
+}
+
+export function useMotionValueEvent(...args: any[]): void {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const value = args[0];
+	const event = args[1] as string;
+	const callback = args[2] as (latest: any) => void;
+
+	// `value.on(event, cb)` returns the unsubscribe fn → octane uses it as cleanup.
+	// Like Framer Motion, subscribe in the INSERTION phase (before layout/passive
+	// effects) so a descendant that sets `value` in its own effect can't fire a
+	// change before this subscription exists (octane passive effects run child-first).
+	useInsertionEffect(
+		() => value.on(event, callback),
+		[value, event, callback],
+		sub(slot, 'effect'),
+	);
+}

package/src/useScroll.ts

@@ -0,0 +1,62 @@
+// `useScroll()` — scroll-linked MotionValues. Returns `{ scrollX, scrollY,
+// scrollXProgress, scrollYProgress }`; bind a progress value to a `motion.*`
+// element's style, or read it imperatively. Reuses motion's framework-agnostic
+// `scroll`.
+import { motionValue, scroll } from 'motion';
+import { useState, useEffect } from 'octane-ts';
+
+function sub(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':us:' + tag) : undefined;
+}
+
+export interface ScrollOptions {
+	container?: HTMLElement;
+	target?: HTMLElement;
+	axis?: 'x' | 'y';
+	offset?: any;
+}
+
+export function useScroll(...args: any[]): {
+	scrollX: any;
+	scrollY: any;
+	scrollXProgress: any;
+	scrollYProgress: any;
+} {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const options: ScrollOptions =
+		args.length && typeof args[0] === 'object' && args[0] !== null ? args[0] : {};
+
+	const [values] = useState(
+		() => ({
+			scrollX: motionValue(0),
+			scrollY: motionValue(0),
+			scrollXProgress: motionValue(0),
+			scrollYProgress: motionValue(0),
+		}),
+		sub(slot, 'values'),
+	);
+
+	useEffect(
+		() => {
+			// `scroll(onScroll, options)` reports offset (px) + progress (0–1) each frame.
+			const stop = scroll((progress: number, info?: any) => {
+				if (info) {
+					values.scrollX.set(info.x.current);
+					values.scrollY.set(info.y.current);
+					values.scrollXProgress.set(info.x.progress);
+					values.scrollYProgress.set(info.y.progress);
+				} else {
+					values.scrollYProgress.set(progress);
+				}
+			}, options as any);
+			return () => {
+				if (typeof stop === 'function') stop();
+			};
+		},
+		[options.container, options.target, options.axis],
+		sub(slot, 'effect'),
+	);
+
+	return values;
+}

package/src/useSpring.ts

@@ -0,0 +1,57 @@
+// `useSpring(source, options?)` — a spring-backed MotionValue (reuses motion's
+// `attachFollow` engine). Two forms:
+//   1) useSpring(mv, opts)      — output springs toward `mv` as it changes (follow).
+//   2) useSpring(initial, opts) — a settable spring; `value.set(target)` springs
+//      toward `target` over frames (`value.jump(v)` snaps instantly).
+// Bind the returned MotionValue to a `motion.*` element via `style`, or read it
+// imperatively. Returns the SAME stable MotionValue across renders.
+import { motionValue, attachFollow } from 'motion';
+import { useState, useInsertionEffect } from 'octane-ts';
+import { isMotionValue } from './useMotionValue';
+
+function sub(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':usp:' + tag) : undefined;
+}
+
+export interface SpringOptions {
+	stiffness?: number;
+	damping?: number;
+	mass?: number;
+	duration?: number;
+	bounce?: number;
+	visualDuration?: number;
+	velocity?: number;
+	restSpeed?: number;
+	restDelta?: number;
+	// Jump (don't animate) on the first source change.
+	skipInitialAnimation?: boolean;
+}
+
+export function useSpring(source: any, ...args: any[]): any {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	// First non-slot arg after `source` is the options object.
+	const options: SpringOptions =
+		args.length && typeof args[0] === 'object' && args[0] !== null ? args[0] : {};
+
+	// Seed the value from the source (matching motion's followValue).
+	const [value] = useState(
+		() => motionValue(isMotionValue(source) ? source.get() : source),
+		sub(slot, 'mv'),
+	);
+
+	// `attachFollow` wires both forms and RETURNS the correct cleanup:
+	//  - settable: an attach() interceptor that springs on every `.set()`; cleanup
+	//    stops the running animation.
+	//  - follow:   the above PLUS a `source.on('change')` subscription; cleanup
+	//    removes the subscription. So returning it gives octane correct teardown.
+	// Subscribe in the INSERTION phase (like Framer's useFollowValue) so the follow
+	// subscription exists before any descendant can mutate `source` in its own effect.
+	useInsertionEffect(
+		() => attachFollow(value, source, { type: 'spring', ...options }),
+		[JSON.stringify(options)],
+		sub(slot, 'attach'),
+	);
+
+	return value;
+}

package/src/useTransform.ts

@@ -0,0 +1,52 @@
+// `useTransform` — derive a MotionValue from one or more inputs. Four forms:
+//   1) useTransform(() => x.get() * 2)               — transformer reads other MVs
+//   2) useTransform(mv, [0, 100], [0, 1], options?)  — input→output range mapping
+//   3) useTransform([a, b], ([av, bv]) => av + bv)   — multiple inputs + combiner
+//   4) useTransform(mv, (latest) => latest * 2)      — single input + transformer
+// Reuses motion's `transformValue` (forms 1, 3, 4) and `mapValue` (form 2). The
+// output MotionValue self-subscribes to its inputs (updates are frame-scheduled); we
+// create it once and `destroy()` it on unmount, which tears those subscriptions down.
+import { transformValue, mapValue } from 'motion';
+import { useState, useEffect } from 'octane-ts';
+
+function sub(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':ut:' + tag) : undefined;
+}
+
+export function useTransform(...args: any[]): any {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	// User args = everything except a trailing compiler-injected slot symbol.
+	const a = slot !== undefined ? args.slice(0, -1) : args;
+	const [input, second, third, options] = a;
+
+	const [mv] = useState(
+		() => {
+			// Form 1: a transformer function that reads other MotionValues internally.
+			if (typeof input === 'function') {
+				return transformValue(input);
+			}
+			// Form 3: an array of MotionValue inputs + a combiner over their latest values.
+			if (Array.isArray(input)) {
+				const inputs = input;
+				const combiner = second as (latest: any[]) => any;
+				return transformValue(() => combiner(inputs.map((v) => v.get())));
+			}
+			// Form 4: a single MotionValue + a transformer over its latest scalar value.
+			if (typeof second === 'function') {
+				const inp = input;
+				const fn = second as (latest: any) => any;
+				return transformValue(() => fn(inp.get()));
+			}
+			// Form 2: single MotionValue mapped from inputRange → outputRange.
+			return mapValue(input, second as number[], third as any[], options);
+		},
+		sub(slot, 'mv'),
+	);
+
+	// `transformValue`/`mapValue` register their input-unsubscribe on the output
+	// value's `destroy` event, so destroying it on unmount is the correct teardown.
+	useEffect(() => () => mv.destroy(), [], sub(slot, 'clean'));
+
+	return mv;
+}