solidjs-motion 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,374 @@
+import { AnimationPlaybackControls, MotionValue, PanInfo, PressGestureInfo, ResolvedValues, SpringOptions, Transition } from 'motion';
+import { InertiaOptions } from 'motion-dom';
+import { Accessor, Component, JSX } from 'solid-js';
+export type { AnimationPlaybackControls, MotionValue, PanInfo, ResolvedValues, SpringOptions, Transition, };
+/**
+ * Callable {@link MotionValue} — has every MotionValue method (`.get`, `.set`,
+ * `.jump`, `.on`, `.getVelocity`, ...) AND can be invoked as a Solid-tracked
+ * Accessor. Returned by `createMotionValue`, `createTransform`,
+ * `createSpring`, `createTime`, `createVelocity`, and `createTemplate`.
+ *
+ * - `mv()` — Solid-tracked read (use in JSX, `createEffect`, `createMemo`)
+ * - `mv.get()` — sync untracked read (motion engine's API; matches motion/react)
+ * - `mv.set(v)` / `mv.jump(v)` — imperative writes (also trigger the Solid
+ *   signal via an internal `mv.on("change", ...)` bridge)
+ *
+ * Passes motion's `isMotionValue` (duck-typed on `.getVelocity`), so the same
+ * value can be used as a target in `useMotion({ animate: { x: mv } })` or as
+ * the target of `animate(mv, 100)`.
+ */
+export type MotionValueAccessor<T> = MotionValue<T> & (() => T);
+/** Per-press info delivered to onPressStart / onPress / onPressCancel. */
+export type PressInfo = PressGestureInfo;
+/**
+ * Options for {@link DragControls.start}.
+ *
+ * Only `snapToCursor` is exposed for v0.1 (Q9b — anything else can be added
+ * non-breakingly later).
+ */
+export type DragControlsStartOptions = {
+    /**
+     * When true, center the dragged element under the pointer on drag-start.
+     * Useful for "drag handle hand-off" patterns where the handle and the
+     * dragged element are distinct — the user clicks the handle and the
+     * dragged element jumps to follow the pointer.
+     */
+    snapToCursor?: boolean;
+};
+/**
+ * Imperative drag controls returned from `createDragControls()`. Defined
+ * locally because motion's public `motion` export doesn't surface its
+ * DragControls class type.
+ *
+ * Usage (Q9): one controls instance binds to one motion element via
+ * `dragControls: controls` in MotionOptions. A separate UI element (e.g., a
+ * drag-handle button) captures the pointer event and forwards it via
+ * `controls.start(event)`, decoupling the drag-listener element from the
+ * element that actually moves.
+ */
+export type DragControls = {
+    /**
+     * Begin a drag from an externally-captured pointer event. Bypasses
+     * createDrag's threshold gate — drag starts immediately at the event's
+     * coordinates (the user explicitly invoked, so no "did they really
+     * mean it" hysteresis is needed).
+     *
+     * No-op when no motion element is currently registered with this
+     * controls instance.
+     */
+    start: (event: PointerEvent, options?: DragControlsStartOptions) => void;
+};
+type Numeric = number | MotionValue<number> | Accessor<number>;
+type Stringish = string | MotionValue<string> | Accessor<string>;
+type AnyValue = Numeric | Stringish;
+/** A property value or an array of values (keyframe sequence). */
+export type Keyframes<T> = T | T[];
+export type Target = {
+    x?: Keyframes<Numeric | Stringish>;
+    y?: Keyframes<Numeric | Stringish>;
+    z?: Keyframes<Numeric | Stringish>;
+    scale?: Keyframes<Numeric>;
+    scaleX?: Keyframes<Numeric>;
+    scaleY?: Keyframes<Numeric>;
+    scaleZ?: Keyframes<Numeric>;
+    rotate?: Keyframes<Numeric | Stringish>;
+    rotateX?: Keyframes<Numeric | Stringish>;
+    rotateY?: Keyframes<Numeric | Stringish>;
+    rotateZ?: Keyframes<Numeric | Stringish>;
+    skew?: Keyframes<Numeric | Stringish>;
+    skewX?: Keyframes<Numeric | Stringish>;
+    skewY?: Keyframes<Numeric | Stringish>;
+    transformPerspective?: Keyframes<Numeric>;
+    transformOrigin?: Stringish;
+    opacity?: Keyframes<Numeric>;
+    zIndex?: Keyframes<Numeric>;
+    transition?: Transition;
+    [key: string]: Keyframes<AnyValue> | Transition | undefined;
+};
+/** A single variant — a target shape, or a function producing one from `custom`. */
+export type Variant = Target | ((custom: unknown) => Target);
+/** A named map of variants. */
+export type Variants = Record<string, Variant>;
+/** What can be passed where a variant name is expected (string, array of strings). */
+export type VariantLabels = string | string[];
+/** What can drive an animation: a target object, a variant name, or an array of names. */
+export type AnimateValue = Target | VariantLabels;
+export type ViewportOptions = {
+    /** Stop observing after first entry (default false). */
+    once?: boolean;
+    /** rootMargin string passed to IntersectionObserver. */
+    margin?: string;
+    /**
+     * Threshold(s) at which IntersectionObserver fires its callback.
+     *
+     * - `"some"` (default) — fires the moment any pixel intersects.
+     * - `"all"` — fires only when fully visible.
+     * - `number` 0–1 — single threshold; fires at that intersection ratio.
+     * - `number[]` — an array of thresholds; fires at each crossing. Use this
+     *   for continuous `intersectionRatio` updates (e.g., for scroll-linked
+     *   fades). With a single threshold the observer is silent between
+     *   crossings, so `entry.intersectionRatio` stays stale.
+     */
+    amount?: "some" | "all" | number | number[];
+    /** Solid-style accessor returning the root element; defaults to viewport. */
+    root?: () => Element | null;
+};
+/**
+ * Drag bounds (Q8). Three shapes:
+ *
+ * - **Numeric** (`{ top, left, right, bottom }`): absolute MV-value bounds.
+ *   Missing keys are unbounded on that side.
+ * - **HTMLElement**: container the dragged element must stay inside. Bounds
+ *   are computed at drag-start from the container's bounding rect.
+ * - **`() => HTMLElement | null`**: Solid-style accessor for a reactive
+ *   container ref. Called at drag-start.
+ */
+export type DragConstraints = {
+    top?: number;
+    left?: number;
+    right?: number;
+    bottom?: number;
+} | HTMLElement | (() => HTMLElement | null);
+export type DragOptions = {
+    drag?: boolean | "x" | "y";
+    dragConstraints?: DragConstraints;
+    /** Elastic resistance past constraints (0–1, default 0.5). */
+    dragElastic?: number;
+    /** Carry momentum after release (default true). */
+    dragMomentum?: boolean;
+    /**
+     * Options for the momentum / snap-back animation. Inertia by default
+     * (Q15d preset). Shallow-merges over the defaults — user fields override
+     * any single setting (bounceStiffness, timeConstant, etc.).
+     */
+    dragTransition?: Partial<InertiaOptions>;
+    /** Snap back to origin on release (default false). */
+    dragSnapToOrigin?: boolean;
+    /** Imperatively-triggered drag (from createDragControls). */
+    dragControls?: DragControls;
+};
+export type MotionCallbacks = {
+    onAnimationStart?: () => void;
+    onAnimationComplete?: (definition: AnimateValue) => void;
+    onAnimationCancel?: () => void;
+    onUpdate?: (latest: ResolvedValues) => void;
+    onHoverStart?: (e: PointerEvent) => void;
+    onHoverEnd?: (e: PointerEvent) => void;
+    /** Press began. `info.success` isn't meaningful yet — see {@link onPress} / {@link onPressCancel}. */
+    onPressStart?: (e: PointerEvent) => void;
+    /** Press completed with the pointer still over the element. */
+    onPress?: (e: PointerEvent, info: PressInfo) => void;
+    /** Press cancelled — pointer left the element before pointer-up. */
+    onPressCancel?: (e: PointerEvent, info: PressInfo) => void;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onPanStart?: (e: PointerEvent, info: PanInfo) => void;
+    onPan?: (e: PointerEvent, info: PanInfo) => void;
+    onPanEnd?: (e: PointerEvent, info: PanInfo) => void;
+    onViewportEnter?: (entry: IntersectionObserverEntry) => void;
+    onViewportLeave?: (entry: IntersectionObserverEntry) => void;
+    onDragStart?: (e: PointerEvent, info: PanInfo) => void;
+    onDrag?: (e: PointerEvent, info: PanInfo) => void;
+    onDragEnd?: (e: PointerEvent, info: PanInfo) => void;
+    onDragTransitionEnd?: () => void;
+};
+export type MotionOptions = MotionCallbacks & DragOptions & {
+    /** Starting state. `false` means "don't apply an initial style". */
+    initial?: AnimateValue | false;
+    /** Target the element animates to. */
+    animate?: AnimateValue;
+    /** Target applied when component unmounts inside <Presence>. */
+    exit?: AnimateValue;
+    /** Hover gesture target. */
+    hover?: AnimateValue;
+    /** Press gesture target. */
+    press?: AnimateValue;
+    /** Focus gesture target. */
+    focus?: AnimateValue;
+    /** Viewport gesture target. */
+    inView?: AnimateValue;
+    /** Viewport observer config for the inView gesture. */
+    inViewOptions?: ViewportOptions;
+    /**
+     * Visual-state target applied while a drag gesture is active. Like
+     * other gesture targets, this can be a Target object or a variant
+     * label. Common idiom: `whileDrag: { scale: 1.05 }` for a lift-while-
+     * dragging effect — composes with drag's translation via the shared
+     * VisualElement (Q5/C-lean).
+     */
+    whileDrag?: AnimateValue;
+    /**
+     * Minimum cumulative pointer movement (in px) before pan/drag start fires.
+     * Distinguishes a pan from a click. Q11a default: 3px (matches motion).
+     */
+    panThreshold?: number;
+    /** Default transition applied to every property in animate/gesture targets. */
+    transition?: Transition;
+    /** Named variant map; resolved by variant name in animate/gesture targets. */
+    variants?: Variants;
+    /** Value passed to function variants. */
+    custom?: unknown;
+};
+/**
+ * The element types `useMotion` can attach to. HTMLElement covers the bulk;
+ * SVGElement is included so `motion.path`, `motion.circle`, etc. (Phase 4)
+ * thread through without a `ref` type-cast. `createMotion` only uses methods
+ * available on both (style, addEventListener, getBoundingClientRect) so the
+ * union is honored at runtime. Drag stays HTMLElement-only via an
+ * `instanceof` check in createMotion's body — motion-dom's VisualElement
+ * layer is HTML-specific.
+ */
+export type MotionElement = HTMLElement | SVGElement;
+/**
+ * Motion's transform-shortcut keys and their value types. Each key may be
+ * a value OR a `MotionValue` holding that value.
+ *
+ * Value units (when expressed as a `number`):
+ *   - `x` / `y` / `z` / `transformPerspective` → px
+ *   - `scale*` → dimensionless multiplier
+ *   - `rotate*` / `skew*` → deg
+ *
+ * Strings with explicit units pass through verbatim (e.g.
+ * `x: "50%"`, `rotate: "0.5turn"`).
+ *
+ * Variance note: motion's `MotionValue<T>` is invariant in `T` (it has both
+ * `get(): T` and `set(v: T)`), which means a user's `MotionValue<number>`
+ * cannot widen to `MotionValue<number | string>`. We use `MotionValue<any>`
+ * across the shortcut value types so a literal `createMotionValue(1)` is
+ * assignable as `x` / `y` / etc. without forcing the caller to type the MV
+ * with the full union. Type-safety on the value side is mostly recovered by
+ * the runtime: `formatProperty` and `transformFunctionFor` handle the
+ * number/string distinction.
+ */
+type AnyMotionValue = MotionValue<any>;
+export type MotionTransformShortcuts = {
+    x?: number | string | AnyMotionValue;
+    y?: number | string | AnyMotionValue;
+    z?: number | string | AnyMotionValue;
+    scale?: number | string | AnyMotionValue;
+    scaleX?: number | string | AnyMotionValue;
+    scaleY?: number | string | AnyMotionValue;
+    scaleZ?: number | string | AnyMotionValue;
+    rotate?: number | string | AnyMotionValue;
+    rotateX?: number | string | AnyMotionValue;
+    rotateY?: number | string | AnyMotionValue;
+    rotateZ?: number | string | AnyMotionValue;
+    skew?: number | string | AnyMotionValue;
+    skewX?: number | string | AnyMotionValue;
+    skewY?: number | string | AnyMotionValue;
+    transformPerspective?: number | string | AnyMotionValue;
+};
+/**
+ * Widen each value of `T` to also accept any `MotionValue`. Pragmatic shape:
+ * motion's `MotionValue<T>` is invariant in T, so a strict per-key
+ * `MotionValue<NonNullable<T[K]>>` would reject e.g. `MotionValue<number>` for
+ * a `width: string | number` key. `MotionValue<any>` is the necessary
+ * escape hatch — the runtime always normalizes via `mv.get()` and
+ * `formatProperty`.
+ */
+type WithMotionValues<T> = {
+    [K in keyof T]?: T[K] | AnyMotionValue;
+};
+/**
+ * The `style` prop shape for motion-aware elements: every native CSS
+ * property (with values optionally widened to a `MotionValue`), plus motion's
+ * transform-shortcut keys (with the same widening).
+ *
+ * Some CSS individual-transform properties (`scale`, `rotate`) collide with
+ * motion shortcut keys of the same name. We strip them from the CSS side
+ * before intersecting — motion's semantics win, the legacy CSS individual-
+ * transform path is a corner case users almost never reach for.
+ *
+ * @example
+ * const scale = createMotionValue(1)
+ * const m = useMotion({})
+ * <div {...m({ style: { scale, opacity: 0.5, color: "red" } })} />
+ */
+export type MotionStyle = MotionTransformShortcuts & WithMotionValues<Omit<JSX.CSSProperties, keyof MotionTransformShortcuts>>;
+export type ElementProps = Omit<JSX.HTMLAttributes<MotionElement>, "ref" | "style"> & {
+    ref?: ((el: MotionElement) => void) | MotionElement | undefined;
+    style?: MotionStyle;
+};
+export type MotionMergedProps<P extends ElementProps> = Omit<P, "ref" | "style"> & {
+    style: MotionStyle & JSX.CSSProperties;
+    ref: (el: MotionElement) => void;
+    "data-motion-hydrated"?: "";
+};
+export type MotionGetProps = <P extends ElementProps>(userProps?: P) => MotionMergedProps<P>;
+export type UseMotionResult = MotionGetProps & {
+    /** Opt-in: wrap descendant motion elements to receive this element's variant context. */
+    Provider: Component<{
+        children: JSX.Element;
+    }>;
+};
+/** Propagates the variant state from a parent motion element to descendants. */
+export type VariantContextValue = {
+    variants?: Accessor<Variants | undefined>;
+    /** Propagated only when the parent's `initial` is a variant name (not `false` or an explicit Target). */
+    initial?: Accessor<VariantLabels | undefined>;
+    animate?: Accessor<VariantLabels | undefined>;
+    hover?: Accessor<VariantLabels | undefined>;
+    press?: Accessor<VariantLabels | undefined>;
+    focus?: Accessor<VariantLabels | undefined>;
+    inView?: Accessor<VariantLabels | undefined>;
+    exit?: Accessor<VariantLabels | undefined>;
+    custom?: Accessor<unknown>;
+    transition?: Accessor<Transition | undefined>;
+};
+/**
+ * Wired with a no-op default; the real implementation is provided by
+ * `<Presence>` and `useAnimatePresence()` in Phase 3.
+ *
+ * Inverted shape vs. motion-react's `AnimatePresenceProps`: the child
+ * registers a `runExit` callable that knows how to animate ITSELF out (closes
+ * over its own state machine). Presence just coordinates timing — it doesn't
+ * resolve targets or merge transitions. See ADR 0003.
+ *
+ * - `register(el, runExit)` — called from `createMotion` when `opts.exit` is
+ *   set. `runExit` flips the state machine's `exit` flag and awaits the
+ *   resulting animate's completion.
+ * - `unregister(el)` — Presence (or the hook's `exit()`) prunes after exit.
+ *   createMotion deliberately omits self-unregister; Solid disposes the
+ *   child owner well before transition-group's onExit runs.
+ * - `beforeUnmount(el)` — Presence (or the hook's `exit()`) dispatches to the
+ *   registered `runExit`. Returns a resolved promise if no `runExit` is
+ *   registered, so non-exit children pass through cleanly.
+ * - `registerEnter` / `beforeMount` — symmetric to the exit pair. createMotion
+ *   defers its first-mount animate when it's inside a real Presence (the
+ *   no-op default has no `registerEnter`) because the element may be off-DOM
+ *   at the moment the gesture-state-machine first iterates (e.g., the new
+ *   child during a `mode: "wait"` swap is created BEFORE the old child's
+ *   exit completes). Running motion's `animate()` on a disconnected element
+ *   completes off-DOM and the final `commitStyles` silently no-ops, leaving
+ *   the element painted at its `initial` target when it finally enters the
+ *   DOM. Presence's `onEnter` (switch) / `onChange.added` (list) calls
+ *   `beforeMount(el)` once the element is actually connected; the child's
+ *   registered `runEnter` flips its readiness signal and the state machine
+ *   dispatches the first animate against a live element.
+ * - `initial` — when an enclosing `<Presence initial={false}>` (or the hook
+ *   with `initial: false`) is active, descendants suppress their first-mount
+ *   animation. Accessor-shaped so the implementation can flip post-mount.
+ */
+export type PresenceContextValue = {
+    register: (el: MotionElement, runExit: () => Promise<void>) => void;
+    unregister: (el: MotionElement) => void;
+    beforeUnmount: (el: MotionElement) => Promise<void>;
+    registerEnter?: (el: MotionElement, runEnter: () => void) => void;
+    beforeMount?: (el: MotionElement) => void;
+    initial?: Accessor<boolean>;
+};
+/** <MotionConfig> provides defaults that flow to every descendant motion element. */
+export type MotionConfigContextValue = {
+    /** "always" forces snap; "never" ignores system pref; "user" respects prefers-reduced-motion. */
+    reducedMotion: Accessor<"always" | "never" | "user">;
+    /** Default transition merged with descendant transitions (descendant wins on conflict). */
+    transition: Accessor<Transition | undefined>;
+    /** CSP nonce applied to any inline style emissions (advanced). */
+    nonce: Accessor<string | undefined>;
+};
+export type MotionConfigProps = {
+    reducedMotion?: "always" | "never" | "user";
+    transition?: Transition;
+    nonce?: string;
+    children: JSX.Element;
+};

package/dist/src/use-motion.d.ts

@@ -0,0 +1,35 @@
+import { MotionOptions, Transition, UseMotionResult } from './types';
+/**
+ * Wire motion to an element via a getter function.
+ *
+ * ```tsx
+ * const motion = useMotion({
+ *   initial: { opacity: 0, y: 20 },
+ *   animate: { opacity: 1, y: 0 },
+ *   transition: { duration: 0.6 },
+ * })
+ *
+ * <div {...motion({ class: "card" })}>Hello</div>
+ * ```
+ *
+ * **Reactive form**: pass a function to track signals.
+ * ```tsx
+ * useMotion(() => ({ animate: { x: x() } }))
+ * ```
+ *
+ * **Variant context propagation**: `useMotion` only *consumes* the parent
+ * variant context. To propagate to descendants, wrap them in `motion.Provider`:
+ * ```tsx
+ * const m = useMotion({ animate: "visible", variants })
+ * <div {...m()}>
+ *   <m.Provider>
+ *     <ChildMotion />
+ *   </m.Provider>
+ * </div>
+ * ```
+ *
+ * For the common "JSX wrapper does propagation automatically" pattern, use
+ * `<motion.div>` (Phase 4).
+ */
+export declare function useMotion(opts: MotionOptions | (() => MotionOptions)): UseMotionResult;
+export type { Transition };

package/dist/src/variants.d.ts

@@ -0,0 +1,64 @@
+import { Context } from 'solid-js';
+import { MotionOptions, Target, VariantContextValue, VariantLabels, Variants } from './types';
+/**
+ * Solid context propagating variant state from a motion ancestor to its
+ * descendants. Only the wrapper components (`<motion.div>`, `motion(...)`)
+ * provide a value. Bare `useMotion` consumers can opt in via the `Provider`
+ * returned alongside the getter.
+ */
+export declare const VariantContext: Context<VariantContextValue>;
+export declare function useVariantContext(): VariantContextValue;
+/**
+ * Resolve a variant label (or array of labels) against a variants map and the
+ * current `custom` value. Returns a {@link Target} object, or `null` if nothing
+ * resolves.
+ *
+ * Resolution rules locked in Phase 1 Q4:
+ *
+ * - Child's own `variants` always wins for a given name (sub-1A).
+ * - No cascade: if a child has no `variants` of its own, parent's are NOT
+ *   consulted (sub-1B / Pattern X). Callers pass `variants = undefined` in
+ *   that case and this returns `null`.
+ * - String + array forms both supported; array variants merge in order
+ *   (later wins on conflicting keys).
+ * - Function variants are invoked with `custom`; the value can be any type.
+ *
+ * @example
+ * const variants = { visible: { opacity: 1 }, hidden: { opacity: 0 } }
+ * resolveVariant("visible", variants, undefined)
+ * // { opacity: 1 }
+ *
+ * resolveVariant(["visible", "highlighted"], variants, undefined)
+ * // merged in order, last variant's keys override
+ *
+ * resolveVariant("visible", { visible: (i: number) => ({ x: i * 10 }) }, 3)
+ * // { x: 30 }
+ */
+export declare function resolveVariant(names: VariantLabels | undefined, variants: Variants | undefined, custom: unknown): Target | null;
+/**
+ * Determine the effective variant name for a given motion state. If the caller
+ * provided an explicit value (string, array, or Target object), that wins.
+ * Otherwise the parent context's value (per gesture/state) is used as a fall-
+ * back.
+ *
+ * Returns the explicit value as-is when it's a Target object (used by callers
+ * to detect "explicit target — skip variant lookup entirely").
+ */
+export declare function effectiveLabels(own: VariantLabels | Target | undefined, parent: VariantLabels | undefined): VariantLabels | Target | undefined;
+/**
+ * A motion node is "controlling variants" when any of its variant slots
+ * (`initial`, `animate`, `hover`, `press`, `focus`, `inView`, `exit`) carries
+ * a variant *label* (string or array of strings).
+ *
+ * Mirrors motion-dom's same-named check. A controlling node opts OUT of
+ * inheriting its parent's variant cascade — it provides its own. Descendants
+ * with no controlling props of their own DO inherit from the nearest
+ * controlling ancestor.
+ *
+ * Behavior is binary (any single controlling-slot label flips the node into
+ * controlling mode); not per-slot.
+ *
+ * Object-shaped values (`animate: \{ x: 100 \}`) do NOT make a node
+ * controlling — they're treated as targets, not as variant references.
+ */
+export declare function isControllingVariants(opts: MotionOptions): boolean;

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "solidjs-motion",
+  "version": "0.1.0",
+  "description": "An animation library for SolidJS — port of motion/react patterns built on the framework-agnostic motion package",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "solid": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "dev": "vite build --watch",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "bench": "vitest bench --run --config vitest.bench.config.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist node_modules",
+    "publish:npm": "bun run build && npm publish --access public",
+    "publish:jsr": "bunx jsr publish"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0",
+    "motion": "^12.0.0",
+    "motion-dom": "^12.0.0"
+  },
+  "dependencies": {
+    "@solid-primitives/refs": "^1.1.3",
+    "@solid-primitives/transition-group": "^1.1.2"
+  },
+  "devDependencies": {
+    "@solidjs/testing-library": "^0.8.10",
+    "@testing-library/jest-dom": "^6.9.1",
+    "jsdom": "^29.1.1",
+    "motion": "^12.38.0",
+    "motion-dom": "^12.38.0",
+    "solid-js": "^1.9.13",
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.0",
+    "vite-plugin-solid": "^2.11.12",
+    "vitest": "^4.1.6"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "animation",
+    "motion",
+    "framer-motion",
+    "spring",
+    "transition",
+    "gesture"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidjs-motion/motion.git",
+    "directory": "packages/motion"
+  },
+  "bugs": {
+    "url": "https://github.com/solidjs-motion/motion/issues"
+  },
+  "homepage": "https://github.com/solidjs-motion/motion#readme",
+  "license": "MIT"
+}

package/src/default-values.ts

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// Default value table for transform-class and a few well-known CSS properties.
+// Used by the gesture state machine's "removed keys" fallback (Q7): when a
+// higher-priority gesture deactivates and no lower-priority state defines a
+// key, we animate the key back to:
+//   1. the user's `initial` target (captured at mount) — handled at call site
+//   2. otherwise the value from this table
+//   3. otherwise `null` (motion's animate() reads from computed style)
+//
+// The values here mirror motion-dom's conventions (scale → 1, x/y/z → 0,
+// rotate/skew → 0, opacity → 1). We don't import motion-dom's defaultValueTypes
+// directly because (a) it's a value-type system, not a defaults table, and
+// (b) keeping a stable local source insulates us from motion-dom internal churn.
+// ---------------------------------------------------------------------------
+
+const TRANSFORM_DEFAULTS: Readonly<Record<string, number>> = {
+  // Translate
+  x: 0,
+  y: 0,
+  z: 0,
+  translateX: 0,
+  translateY: 0,
+  translateZ: 0,
+  // Scale (multiplicative identity)
+  scale: 1,
+  scaleX: 1,
+  scaleY: 1,
+  scaleZ: 1,
+  // Rotate
+  rotate: 0,
+  rotateX: 0,
+  rotateY: 0,
+  rotateZ: 0,
+  // Skew
+  skew: 0,
+  skewX: 0,
+  skewY: 0,
+  // Perspective
+  perspective: 0,
+  transformPerspective: 0,
+  // Opacity (the one non-transform key with a strong default)
+  opacity: 1,
+}
+
+/**
+ * Look up the canonical fallback value for a property key. Returns the table
+ * value if known, else `null` — which motion's `animate()` interprets as
+ * "read from computed style at animation start."
+ */
+export function getMotionDefault(key: string): number | null {
+  return TRANSFORM_DEFAULTS[key] ?? null
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+// Public API surface.
+
+// Re-exports from the upstream motion engine.
+export { animate, inView, isMotionValue, motionValue, scroll, spring } from "motion"
+// Context layer.
+export { MotionConfig, MotionConfigContext, useMotionConfig } from "./motion-config"
+// motion proxy (Phase 4) — indexable surface yielding cached, motion-aware
+// tag-components per HTML/SVG tag. `motion.create` (the HOC entry point)
+// lands in the follow-up commit.
+export { MOTION_OPT_KEYS, type Motion, motion } from "./motion-proxy"
+// Presence — exit-animation coordinator + imperative hook (Phase 3).
+export {
+  Presence,
+  type PresenceProps,
+  type UseAnimatePresenceOptions,
+  type UseAnimatePresenceResult,
+  useAnimatePresence,
+} from "./presence"
+export { PresenceContext, usePresenceContext } from "./presence-context"
+// Imperative motion primitive (advanced — most users want useMotion instead).
+export { createDragControls } from "./primitives/createDragControls"
+export {
+  type CreateInViewOptions,
+  type CreateInViewResult,
+  createInView,
+} from "./primitives/createInView"
+export { createMotion } from "./primitives/createMotion"
+export {
+  type CreatePanOptions,
+  type CreatePanResult,
+  createPan,
+  type PanAxisPair,
+} from "./primitives/createPan"
+export {
+  type CreateScrollOptions,
+  type CreateScrollResult,
+  createScroll,
+} from "./primitives/createScroll"
+// MotionValue family — callable-hybrid primitives. Every value returned here
+// is both a Solid Accessor (call it: `mv()`) AND a motion.MotionValue
+// (methods: `.get`, `.set`, `.jump`, `.on`, etc.).
+export {
+  createMotionValue,
+  createMotionValueEvent,
+  createSpring,
+  createTemplate,
+  createTime,
+  createTransform,
+  createVelocity,
+  toSignal,
+} from "./primitives/motion-value"
+// Reduced motion.
+export { createReducedMotion, shouldReduceMotion } from "./reduced-motion"
+// Style helper (also useful for users with custom directives or imperative DOM).
+export { targetToStyle } from "./style"
+export type * from "./types"
+// Canonical hook.
+export { useMotion } from "./use-motion"
+// Variant resolution.
+export { effectiveLabels, resolveVariant, useVariantContext, VariantContext } from "./variants"