@unrulysystems/native-motion-web 0.1.0-alpha.0

package/src/normalize.ts

@@ -0,0 +1,324 @@
+// The component-prop normalization pipeline (REQ-WEB-012/013/015): pure, total, side-effect-
+// free. Severity is a PARAMETER (ratified 2026-07-06: dev throws; production reports through the
+// error channel and refuses the offending property) — the React layer resolves the ambient mode;
+// this module never reads the environment.
+import {
+  describeValue,
+  captureTransition,
+  hostCapabilities,
+  validateTargetSnapshot,
+  UNIVERSAL_SUBSET,
+  type Target,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+import {
+  captureBoundedArray,
+  capturedArrayDescription,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import { dispositionFor } from './disposition'
+import {
+  MotionWebIncompatibleError,
+  MotionWebRejectionError,
+  type MotionWebError,
+  type WebErrorMode,
+  type WebErrorReporter,
+} from './errors'
+import { mapWebTransitionAliases, type WebTransition } from './webTransition'
+
+export interface NormalizeOptions {
+  readonly mode: WebErrorMode
+  readonly report: WebErrorReporter
+}
+
+export type MotionComponentId = '<View>' | '<Text>' | '<Image>'
+
+export interface NormalizedComponentProps {
+  // The motion/react-shaped prop bag: refused props removed, extensions mapped, style pinned.
+  readonly props: Record<string, unknown>
+  // Prop paths refused in production mode (dev throws instead) — reported, never silent.
+  readonly refused: readonly string[]
+  /** Gesture members that reached an element fallback before severity filtering. */
+  readonly attemptedElementTransitionOwners: readonly string[]
+}
+
+// The host boundary must validate exactly the record it hands to motion/react. Plain transitions are
+// captured through CORE's bounded timing snapshot; malformed outer shapes stay raw so core can issue its
+// existing typed refusal. Getter faults deliberately escape untouched.
+export function captureTransitionSnapshot(value: unknown): unknown {
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype === Object.prototype || prototype === null)
+      return captureTransition(value as Transition)
+  }
+  return value
+}
+
+const BOX_SIZING_PIN = 'border-box'
+
+function rejectionMessage(key: string, reason: string): string {
+  switch (reason) {
+    case 'deferred-spike-scope':
+      return (
+        `"${key}" is deferred from the first-spike universal subset (ratified 2026-07-06) — ` +
+        'it fails loudly on every engine until its own rung lands'
+      )
+    case 'outside-universal-target':
+      return (
+        `"${key}" is a web-only registry member outside the universal Target — the universal ` +
+        'surface refuses it on every engine (core validateTarget parity)'
+      )
+    default:
+      return `"${key}" requires the native platform and has no faithful web mapping (REQ-WEB-015)`
+  }
+}
+
+const WEB_HOST = hostCapabilities('web', ['universal'])
+
+/**
+ * R7 (REQ-API-032 law f): the label-form validity gate the web boundary shares across every
+ * label-carrying prop (initial/animate/exit at the View, whileTap/whileDrag here). A string
+ * is a label; an array must be string-only and refuses naming the offending INDEX — the
+ * same depth the native gate enforces. Resolution and propagation are motion/react's
+ * (REQ-WEB-011); validity is this boundary's. Returns whether the definition is accepted
+ * (development throws instead of returning false).
+ */
+export function gateLabelFormWithSeverity(
+  propName: string,
+  definition: string | readonly unknown[],
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): boolean {
+  return captureLabelFormWithSeverity(propName, definition, options, componentId) !== undefined
+}
+
+/** Capture a label form exactly once and return the immutable value Motion receives. */
+export function captureLabelFormWithSeverity(
+  propName: string,
+  definition: string | readonly unknown[],
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): string | readonly string[] | undefined {
+  if (typeof definition === 'string') return definition
+  const capturedDefinition = captureBoundedArray(definition)
+  if (capturedDefinition.kind !== 'captured') {
+    const error = new MotionWebRejectionError(
+      `${componentId}: "${propName}" label array must have a safe length — received ${capturedArrayDescription(capturedDefinition)} ` +
+        '(REQ-API-032 law f)',
+    )
+    if (options.mode === 'development') throw error
+    options.report(error)
+    return undefined
+  }
+  const length = capturedDefinition.values.length
+  const captured: string[] = []
+  captured.length = length
+  for (let index = 0; index < length; index++) {
+    const member = Object.hasOwn(capturedDefinition.values, index)
+      ? capturedDefinition.values[index]
+      : undefined
+    if (typeof member === 'string') {
+      captured[index] = member
+      continue
+    }
+    // describeValue, never JSON.stringify (M3 r1 major cdc42f01c118): a BigInt member
+    // would crash the FORMATTER itself — a raw serialize TypeError replacing the typed
+    // law-(f) refusal in development and escaping unreported in production.
+    const error = new MotionWebRejectionError(
+      `${componentId}: "${propName}" label array member at index ${index} must be a string — received ` +
+        `${describeValue(member)} (REQ-API-032 law f; the label array is ` +
+        'string-only)',
+    )
+    if (options.mode === 'development') throw error
+    options.report(error)
+    return undefined
+  }
+  return Object.freeze(captured)
+}
+
+export function normalizeComponentProps(
+  input: Readonly<Record<string, unknown>>,
+  options: NormalizeOptions,
+  _fallbackTransition: WebTransition | undefined = undefined,
+  componentId: MotionComponentId = '<View>',
+): NormalizedComponentProps {
+  const refused: string[] = []
+  const attemptedElementTransitionOwners: string[] = []
+  // Dev throws; production reports and records the refusal. Returns true when the prop must be
+  // dropped from the output (production path).
+  const refuse = (error: MotionWebError, propPath: string): void => {
+    if (options.mode === 'development') throw error
+    options.report(error)
+    refused.push(propPath)
+  }
+
+  const props: Record<string, unknown> = {}
+
+  // The drag family (drag/dragConstraints/dragElastic/dragSnapPoints + callbacks) is NOT routed
+  // here (FLAG 5a): the View owns it — core resolveDragConfig is the single cross-engine verdict,
+  // and the View maps dragSnapPoints to dragTransition via nearestSnap over core-validated points.
+  // This lane handles the animatable-target + gesture-callback props that pass straight to motion.
+  for (const [key, value] of Object.entries(input)) {
+    if (key === 'style') continue // handled below: the pin composes with user style
+    const disposition = dispositionFor(key)
+    switch (disposition.kind) {
+      case 'pass-through':
+        // The tap trio's callbacks are gated for SHAPE before motion sees them (R5 review r6
+        // major 36 — the shared severity law; native's boundary gates the same way): a
+        // present-but-non-function member is a typed refusal, never a raw crash inside
+        // motion's recognizer dispatch.
+        // The gesture-state pair (R6 object form; R7 adds the LABEL form, REQ-API-032):
+        // labels validate string-only (naming the index) and PASS to motion — motion
+        // resolves them against its own variants context (law b's web leg; REQ-WEB-011).
+        // Object-form depth mirrors the NATIVE gate (r1 major 6) — null/non-object shapes
+        // refuse typed, the embedded transition splits, and the remaining target validates
+        // through core exactly like animate.
+        if ((key === 'whileTap' || key === 'whileDrag') && value !== undefined) {
+          if (typeof value === 'string' || Array.isArray(value)) {
+            const labels = captureLabelFormWithSeverity(key, value, options, componentId)
+            if (labels !== undefined) props[key] = labels
+            break
+          }
+          const proto =
+            typeof value === 'object' && value !== null ? Object.getPrototypeOf(value) : undefined
+          if (
+            typeof value !== 'object' ||
+            value === null ||
+            (proto !== Object.prototype && proto !== null)
+          ) {
+            // PLAIN targets only (r2 major 13): a prototype-carrying object (Date, class
+            // instance) destructures to an empty target and would forward silently.
+            refuse(
+              new MotionWebRejectionError(
+                `${componentId}: "${key}" must be a plain target object, received ${value === null ? 'null' : typeof value} (REQ-API-031).`,
+              ),
+              key,
+            )
+            break
+          }
+          // Read the embedded transition exactly once, then build the target from the remaining own
+          // keys. Destructuring plus Object.entries would invoke an accessor twice and could validate
+          // one transition while motion receives another.
+          const stateDefinition = value as Record<string, unknown>
+          const rawStateTransition = stateDefinition['transition']
+          const stateTarget: Record<string, unknown> = Object.create(null)
+          for (const memberKey of Object.keys(stateDefinition)) {
+            if (memberKey !== 'transition') stateTarget[memberKey] = stateDefinition[memberKey]
+          }
+          let stateTransition: unknown = rawStateTransition
+          if (rawStateTransition !== undefined) {
+            try {
+              stateTransition = mapWebTransitionAliases(
+                rawStateTransition as WebTransition,
+                `${componentId}.${key}.transition`,
+              )
+            } catch (error) {
+              if (!(error instanceof MotionWebRejectionError)) throw error
+              refuse(error, `${key}.transition`)
+              stateTransition = undefined
+            }
+          }
+          // PER-KEY severity (the shared law, r2 major 13): each member validates alone —
+          // development throws on the first offender; production reports it and keeps the
+          // valid members.
+          const acceptedTarget: Record<string, unknown> = {}
+          for (const [memberKey, memberValue] of Object.entries(stateTarget)) {
+            // REQ-WEB-019: Motion owns intrinsic-web value grammar and timing. Native Motion's
+            // portable complex-value validator deliberately refuses these keys, so applying it
+            // here would project the native gap onto the web engine.
+            if (UNIVERSAL_SUBSET.get(memberKey)?.universality === 'web-only') {
+              acceptedTarget[memberKey] = memberValue
+              continue
+            }
+            // validateTargetSnapshot materializes the member's keyframe ARRAY ONCE before validation
+            // and returns that snapshot; the ACCEPTED value is the snapshot, never the caller's raw
+            // array (one read, one truth — R8, review major 23), so motion never re-reads an accessor.
+            const { refusal: memberRefusal, target: memberSnapshot } = validateTargetSnapshot(
+              { [memberKey]: memberValue } as Target,
+              WEB_HOST,
+              {
+                componentId,
+              },
+            )
+            if (memberRefusal !== null) {
+              refuse(
+                new MotionWebRejectionError(memberRefusal.message, { cause: memberRefusal }),
+                `${key}.${memberKey}`,
+              )
+              continue
+            }
+            const acceptedValue = (memberSnapshot as Record<string, unknown>)[memberKey]
+            acceptedTarget[memberKey] = acceptedValue
+          }
+          props[key] =
+            stateTransition === undefined
+              ? acceptedTarget
+              : { ...acceptedTarget, transition: stateTransition }
+          break
+        }
+        if (
+          (key === 'onTap' || key === 'onTapStart' || key === 'onTapCancel') &&
+          value !== undefined &&
+          typeof value !== 'function'
+        ) {
+          refuse(
+            new MotionWebRejectionError(
+              `${componentId}: "${key}" must be a function, received ${typeof value} — the tap callbacks are ` +
+                'the pinned (event, info) handlers (REQ-API-030).',
+            ),
+            key,
+          )
+          break
+        }
+        props[key] = value
+        break
+      case 'rejected':
+        refuse(
+          new MotionWebRejectionError(
+            `${componentId}: ${rejectionMessage(key, disposition.reason)}`,
+          ),
+          key,
+        )
+        break
+      case 'normalized':
+        // No prop declares 'normalized' yet (REQ-WEB-012 reserves the kind); reaching it means
+        // the table gained a row without a pipeline branch — schema drift, fail loud.
+        throw new MotionWebIncompatibleError(
+          `prop "${key}" declares the 'normalized' disposition but no normalizer is wired`,
+        )
+      case 'extension-mapped':
+        // The View owns the runtime extension mapping (dragSnapPoints → dragTransition, REQ-WEB-013):
+        // it destructures the extension family out BEFORE this lane runs. Reaching here means routing
+        // dropped it — schema/routing drift, fail loud (never forward an unmapped extension to motion).
+        throw new MotionWebIncompatibleError(
+          `prop "${key}" is extension-mapped (View-owned, REQ-WEB-013) and must not reach the ` +
+            'normalize lane — routing drift',
+        )
+      default: {
+        const exhaustive: never = disposition
+        throw new MotionWebIncompatibleError(`unreachable disposition: ${String(exhaustive)}`)
+      }
+    }
+  }
+
+  // The ratified border-box pin: RN computes layout as border-box, so the shim pins the same on
+  // web or a width animation means a different rendered box per engine. A conflicting user value
+  // is refused loudly — the pin always wins, never silently.
+  const userStyle = (input['style'] ?? {}) as Readonly<Record<string, unknown>>
+  const { boxSizing: userBoxSizing, ...restStyle } = userStyle
+  if (userBoxSizing !== undefined && userBoxSizing !== BOX_SIZING_PIN) {
+    refuse(
+      new MotionWebRejectionError(
+        `${componentId}: style.boxSizing: ${describeValue(userBoxSizing)} conflicts with the shim's border-box pin ` +
+          '(ratified 2026-07-06): cross-engine layout parity requires border-box',
+      ),
+      'style.boxSizing',
+    )
+  }
+  props['style'] = { ...restStyle, boxSizing: BOX_SIZING_PIN }
+
+  return {
+    props,
+    refused,
+    attemptedElementTransitionOwners: Object.freeze(attemptedElementTransitionOwners),
+  }
+}

package/src/snap.ts

@@ -0,0 +1,82 @@
+// dragSnapPoints → dragTransition.modifyTarget MAPPING (REQ-WEB-013). The public shape is ratified
+// (2026-07-06): ABSOLUTE positions in the drag value's own coordinate space, one array per axis.
+// motion/react's modifyTarget is `(v: number) => number` with NO axis identity (verified against
+// the pinned motion-dom@12.42.2 types).
+//
+// VALIDATION of the drag family (shape verdicts, axis consistency, both-axes/free-drag deferrals)
+// is single-sourced in core (`@unrulysystems/native-motion-core` resolveDragConfig, FLAG 5a) so
+// both engines resolve identical accepted sets. This module is now the web-specific MAPPING only:
+// nearestSnap turns core-validated points into the modifyTarget projection the web View forwards.
+import { MotionWebIncompatibleError } from './errors'
+
+export type DragAxis = 'x' | 'y' | true
+
+export interface DragSnapPoints {
+  readonly x?: readonly number[]
+  readonly y?: readonly number[]
+}
+
+export interface WebDragTransition {
+  readonly modifyTarget: (target: number) => number
+}
+
+function describeShape(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  return typeof value
+}
+
+// A defensive guard on nearestSnap's own public input (it is independently callable): a non-array
+// or non-finite member is a TYPED failure, never a raw TypeError. Core has already validated the
+// points that reach the web View, so this is defense-in-depth on the standalone mapping.
+function invalidSnapSet(
+  points: readonly number[],
+  label: string,
+): MotionWebIncompatibleError | null {
+  if (!Array.isArray(points)) {
+    return new MotionWebIncompatibleError(
+      `${label} must be an array of finite numbers, got ${describeShape(points)}`,
+    )
+  }
+  if (points.length === 0) {
+    return new MotionWebIncompatibleError(`${label} must declare at least one snap point`)
+  }
+  for (const point of points) {
+    if (typeof point !== 'number' || !Number.isFinite(point)) {
+      return new MotionWebIncompatibleError(
+        `${label} must contain only finite numbers, got ${String(point)}`,
+      )
+    }
+  }
+  return null
+}
+
+export function nearestSnap(snapPoints: readonly number[]): (target: number) => number {
+  const invalid = invalidSnapSet(snapPoints, 'snap points')
+  if (invalid) throw invalid
+  // Ascending order + strict improvement makes exact-midpoint ties resolve toward the SMALLER
+  // snap value, so projection is deterministic and independent of declaration order.
+  const points = [...snapPoints].sort((a, b) => a - b)
+  return (target: number) => {
+    if (!Number.isFinite(target)) {
+      throw new MotionWebIncompatibleError(
+        `snap projection requires a finite target, got ${String(target)}`,
+      )
+    }
+    let best = Number.NaN
+    let bestDistance = Number.POSITIVE_INFINITY
+    for (const point of points) {
+      const distance = Math.abs(target - point)
+      if (distance < bestDistance) {
+        best = point
+        bestDistance = distance
+      }
+    }
+    return best
+  }
+}
+
+// The web mapping: core-validated points → the dragTransition motion.div receives (REQ-WEB-013).
+export function snapPointsToDragTransition(points: readonly number[]): WebDragTransition {
+  return { modifyTarget: nearestSnap(points) }
+}

package/src/useAnimate.ts

@@ -0,0 +1,18 @@
+'use client'
+// REQ-API-039 — web useAnimate entry: thin re-export of the pin's useAnimate from motion/react
+// (REQ-WEB-011). No custom web animation engine; scope + playback are the pin's.
+//
+// Public return type is a SHALLOW pair (not pin generics) so dual-entry type-identity does not
+// hang tsgo on motion's scoped-animate overload surface.
+
+import { useAnimate as pinUseAnimate } from 'motion/react'
+import type { AnimationPlaybackControls } from './animate'
+
+export interface AnimationScope<T = unknown> {
+  current: T | null
+  animations: AnimationPlaybackControls[]
+}
+
+export type UseAnimateReturn = ReturnType<typeof pinUseAnimate>
+
+export const useAnimate = pinUseAnimate

package/src/useCycle.ts

@@ -0,0 +1,12 @@
+'use client'
+// REQ-API-040 — useCycle web entry: thin re-export of the pin's useCycle from motion/react
+// (REQ-WEB-011). Zero new semantics; native owns the React-state twin for RN.
+// Cycle/CycleState type names are declared here for dual-entry type-export parity (native
+// exports the same names); runtime is solely the pin hook.
+
+import { useCycle as pinUseCycle } from 'motion/react'
+
+export type Cycle = (i?: number) => void
+export type CycleState<T> = [T, Cycle]
+
+export const useCycle: typeof pinUseCycle = pinUseCycle

package/src/useScroll.ts

@@ -0,0 +1,19 @@
+'use client'
+// REQ-API-037 — raw pin useScroll on web. The named option/return aliases remain the finite
+// Native Motion compatibility mapping; the exported hook value itself retains the pin's exact
+// signature, lifecycle, option ownership, and fault identity.
+
+import { useScroll as pinUseScroll } from 'motion/react'
+import type { RefObject } from 'react'
+
+export type UseScrollOptions = {
+  readonly container?: RefObject<HTMLElement | null> | undefined
+  readonly target?: RefObject<HTMLElement | null> | undefined
+  readonly axis?: 'x' | 'y' | undefined
+  readonly offset?: readonly unknown[] | undefined
+}
+
+/** Pin return shape — engine MotionValues (motion/react), name-parity with the native entry. */
+export type ScrollMotionValues = ReturnType<typeof pinUseScroll>
+
+export const useScroll = pinUseScroll

package/src/webTransition.ts

@@ -0,0 +1,69 @@
+import type { Transition as CoreTransition } from '@unrulysystems/native-motion-core'
+import type { Transition as PinTransition } from 'motion/react'
+import { MotionWebRejectionError } from './errors'
+
+/** Motion's full web transition surface plus Native Motion's portable easing aliases. */
+export type WebTransition = PinTransition | CoreTransition
+
+function mapFlatAliases(value: unknown, owner: string): unknown {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return value
+  const source = value as Record<string, unknown>
+  const aliases = (['easing', 'easings'] as const)
+    .filter((key) => Object.hasOwn(source, key))
+    .map((key) => ({ key, value: source[key] }))
+    .filter((entry) => entry.value !== undefined)
+  if (aliases.length === 0) return value
+  const ease = Object.hasOwn(source, 'ease') ? source['ease'] : undefined
+  if (aliases.length > 1 || ease !== undefined) {
+    const active = [...(ease === undefined ? [] : ['ease']), ...aliases.map(({ key }) => key)]
+    throw new MotionWebRejectionError(
+      `${owner}: transition may declare only one of ease, easing, or easings; received ${active.join(', ')}`,
+    )
+  }
+  const mapped: Record<PropertyKey, unknown> = Object.create(Object.getPrototypeOf(value))
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === 'easing' || key === 'easings') continue
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (descriptor !== undefined) Object.defineProperty(mapped, key, descriptor)
+  }
+  Object.defineProperty(mapped, 'ease', {
+    value: aliases[0]!.value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  })
+  return mapped
+}
+
+/**
+ * Map only Native Motion's easing aliases. Identity is preserved when no alias occurs. Property,
+ * default, and layout transition bags are mapped one level beneath the root, matching Motion's
+ * transition-with-value-overrides shape without inspecting option payloads recursively.
+ */
+export function mapWebTransitionAliases(
+  transition: WebTransition,
+  owner = '<View>',
+): WebTransition {
+  const root = mapFlatAliases(transition, owner)
+  if (typeof root !== 'object' || root === null || Array.isArray(root)) return root as WebTransition
+  const source = root as Record<string, unknown>
+  const replacements = new Map<string, unknown>()
+  for (const key of Object.keys(source)) {
+    const original = source[key]
+    const nested = mapFlatAliases(original, `${owner}.${key}`)
+    if (nested === original) continue
+    replacements.set(key, nested)
+  }
+  if (replacements.size === 0) return root as WebTransition
+  const descriptors = Object.getOwnPropertyDescriptors(root)
+  for (const [key, nested] of replacements) {
+    const original = descriptors[key]
+    descriptors[key] = {
+      value: nested,
+      enumerable: original?.enumerable === true,
+      configurable: original?.configurable ?? true,
+      writable: original !== undefined && 'writable' in original ? original.writable : true,
+    }
+  }
+  return Object.create(Object.getPrototypeOf(root), descriptors) as WebTransition
+}