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

package/src/animate.ts

@@ -0,0 +1,39 @@
+'use client'
+// REQ-API-039 / REQ-WEB-021 — the web value is the raw pin, including its complete overload
+// family and graceful empty-subject behavior. The shallow named compatibility types below remain
+// mapped Native Motion extension names; they do not narrow the exported web value.
+//
+// Return type is deliberately a SHALLOW public contract (not pin overload expansion) so the
+// dual-entry type-identity gate does not hang tsgo on motion's animate overloads.
+
+import { animate as pinAnimate } from 'motion/react'
+import type { NormalizeOptions } from './normalize'
+
+export const ANIMATE_OWNER = 'animate' as const
+
+/** Public playback controls surface (catalog-exercised members). */
+export interface AnimationPlaybackControls {
+  time: number
+  speed: number
+  duration: number
+  readonly finished: Promise<unknown>
+  play: () => void
+  pause: () => void
+  stop: () => void
+  cancel: () => void
+  complete: () => void
+  then: (onResolve: () => void, onReject?: () => void) => Promise<void>
+}
+
+export type AnimateFn = (
+  subject: unknown,
+  keyframes?: unknown,
+  transition?: unknown,
+) => AnimationPlaybackControls
+
+/** Internal test seam retained for compatibility; it returns the raw pin without adding policy. */
+export function createAnimate(_options: NormalizeOptions): typeof pinAnimate {
+  return pinAnimate
+}
+
+export const animate = pinAnimate

package/src/disposition.ts

@@ -0,0 +1,167 @@
+// The prop disposition table (REQ-WEB-012): every public prop has exactly ONE disposition —
+// pass-through, normalized, extension-mapped, or rejected(loud). Compile-time exhaustiveness:
+// the `satisfies Record<PublicPropKey, Disposition>` clause makes a Target key or gesture key
+// without a row a TYPE ERROR (keyof Target is the literal union core builds from its own literal
+// key arrays). Runtime totality: dispositionFor throws on any undeclared key. The registry
+// stores keys widened to string, so the drift guard lives in disposition.test.ts — the same
+// compile-time↔runtime bridge pattern core's component types use against the registry.
+import type { Target } from '@unrulysystems/native-motion-core'
+import { MotionWebIncompatibleError } from './errors'
+
+export type RejectionReason =
+  // Historical refusal categories remain in the error vocabulary for mapped extensions and
+  // schema migrations. Intrinsic-web/pointer capabilities no longer use them (REQ-WEB-019).
+  | 'deferred-spike-scope'
+  | 'outside-universal-target'
+  // Reserved for the native-extension registry category (empty today): a capability with no
+  // faithful web mapping fails loud naming the platform it requires (REQ-WEB-015).
+  | 'native-only-on-web'
+
+export type Disposition =
+  | { readonly kind: 'pass-through' }
+  // Reserved (REQ-WEB-012 names four dispositions): no current prop differs in shape between the
+  // canonical public surface and motion/react, so no row uses 'normalized' yet.
+  | { readonly kind: 'normalized' }
+  // The touch-first extension mapping (REQ-WEB-013): `dragSnapPoints` is CLASSIFIED here as
+  // extension-mapped so the `satisfies` exhaustiveness guard covers it (a dropped or drifted mapping
+  // is a TYPE ERROR). The View performs the actual `dragSnapPoints` → `dragTransition.modifyTarget`
+  // mapping over core-validated points — the disposition is the classification, not the mechanism.
+  | { readonly kind: 'extension-mapped'; readonly extension: 'dragSnapPoints' }
+  | { readonly kind: 'rejected'; readonly reason: RejectionReason }
+
+// Gesture keys mirror the registry's gesture/pointer-gated entries; web-effect keys mirror its
+// web-only entries. Literal unions (the registry widens to string); the drift-guard test pins
+// set equality in both directions.
+type GestureKey =
+  | 'whileTap'
+  | 'onTap'
+  | 'onTapStart'
+  | 'onTapCancel'
+  | 'drag'
+  | 'dragPropagation'
+  | 'dragControls'
+  | 'dragListener'
+  | 'onMeasureDragConstraints'
+  | 'whileDrag'
+  | 'onDrag'
+  | 'onDragStart'
+  | 'onDragEnd'
+  | 'whileHover'
+  | 'onHoverStart'
+  | 'onHoverEnd'
+  | 'whileFocus'
+type WebEffectKey = 'filter' | 'clipPath' | 'boxShadow' | 'backgroundImage'
+// Touch-first extension keys (REQ-WEB-013): public props beyond motion/react's own surface that map
+// to a Motion prop. Exported so the drift-guard test pins set equality against the table.
+export const EXTENSION_KEYS = ['dragSnapPoints'] as const
+type ExtensionKey = (typeof EXTENSION_KEYS)[number]
+// Structural target members (T23 B3): carriers that live INSIDE a target whose SUB-keys are the
+// capabilities — they have no registry entry of their own. Declared so the drift guard stays
+// fail-closed on genuinely phantom rows while the table stays total over keyof Target.
+export const STRUCTURAL_TARGET_KEYS = ['transitionEnd'] as const
+
+type PublicPropKey = keyof Target | GestureKey | WebEffectKey | ExtensionKey
+
+const PASS: Disposition = Object.freeze({ kind: 'pass-through' })
+export const DISPOSITIONS = Object.freeze({
+  // Transforms — canonical shapes ARE motion/react shapes.
+  x: PASS,
+  y: PASS,
+  scale: PASS,
+  scaleX: PASS,
+  scaleY: PASS,
+  rotate: PASS,
+  rotateX: PASS,
+  rotateY: PASS,
+  skewX: PASS,
+  skewY: PASS,
+  perspective: PASS,
+  // Opacity + colors.
+  opacity: PASS,
+  backgroundColor: PASS,
+  color: PASS,
+  borderColor: PASS,
+  // Discrete keywords (T23 B): motion/react's own mixVisibility drives display/visibility on
+  // web — the shim passes them through untouched.
+  display: PASS,
+  visibility: PASS,
+  // T23 B3: transitionEnd is a target-level sub-target motion/react executes natively
+  // (visual-element-target.ts:159-168 — values jump at settle); the shim forwards it whole.
+  transitionEnd: PASS,
+  // Layout props.
+  width: PASS,
+  height: PASS,
+  top: PASS,
+  right: PASS,
+  bottom: PASS,
+  left: PASS,
+  borderRadius: PASS,
+  borderTopLeftRadius: PASS,
+  borderTopRightRadius: PASS,
+  borderBottomLeftRadius: PASS,
+  borderBottomRightRadius: PASS,
+  borderWidth: PASS,
+  borderTopWidth: PASS,
+  borderRightWidth: PASS,
+  borderBottomWidth: PASS,
+  borderLeftWidth: PASS,
+  margin: PASS,
+  marginTop: PASS,
+  marginRight: PASS,
+  marginBottom: PASS,
+  marginLeft: PASS,
+  padding: PASS,
+  paddingTop: PASS,
+  paddingRight: PASS,
+  paddingBottom: PASS,
+  paddingLeft: PASS,
+  // Gesture capability + event callbacks — motion/react's own surface, zero new semantics.
+  drag: PASS,
+  dragPropagation: PASS,
+  // R15 D3 (REQ-API-043): pin's own dragControls hub + dragListener gate — pass-through.
+  dragControls: PASS,
+  dragListener: PASS,
+  onMeasureDragConstraints: PASS,
+  onDrag: PASS,
+  onDragStart: PASS,
+  onDragEnd: PASS,
+  onTap: PASS,
+  onTapStart: PASS,
+  onTapCancel: PASS,
+  onHoverStart: PASS,
+  onHoverEnd: PASS,
+  // Gesture-STATE props: R6 (REQ-API-031) shipped the OBJECT form into motion's own
+  // gesture-state machinery; R7 (REQ-API-032) shipped the LABEL form — string-only
+  // validity at the normalize boundary, resolution/propagation motion's own. The
+  // REQ-WEB-019: pointer/keyboard states are intrinsic-web and therefore remain raw pin
+  // pass-throughs on this entry. Native keeps its platform-unavailable refusal.
+  whileTap: PASS,
+  whileDrag: PASS,
+  whileHover: PASS,
+  whileFocus: PASS,
+  // Registry-owned intrinsic-web effects. Motion owns their value grammar and interpolation;
+  // the shim does not apply Native Motion's portable-target normalizer to them.
+  filter: PASS,
+  clipPath: PASS,
+  boxShadow: PASS,
+  backgroundImage: PASS,
+  // Touch-first extension (REQ-WEB-013): classified extension-mapped so a dropped/drifted mapping is
+  // a compile-time error; the View owns the runtime dragSnapPoints → dragTransition projection.
+  dragSnapPoints: Object.freeze({
+    kind: 'extension-mapped',
+    extension: 'dragSnapPoints',
+  }) as Disposition,
+} satisfies Record<PublicPropKey, Disposition>)
+
+// Runtime totality guard (REQ-WEB-012): an undeclared key is schema drift — it throws in EVERY
+// mode; it is never a user error to be report-and-refused.
+export function dispositionFor(key: string): Disposition {
+  const disposition = (DISPOSITIONS as Record<string, Disposition>)[key]
+  if (disposition === undefined) {
+    throw new MotionWebIncompatibleError(
+      `no disposition declared for prop "${key}" — the web shim's disposition table must stay ` +
+        'total over the public prop union (REQ-WEB-012)',
+    )
+  }
+  return disposition
+}

package/src/dragControls.ts

@@ -0,0 +1,3 @@
+// REQ-WEB-021: imperative drag controls are owned by the pinned web engine. Preserve the
+// constructor, hook, hub identity, option domain, and empty-subscriber behavior verbatim.
+export { DragControls, useDragControls } from 'motion/react'

package/src/errors.ts

@@ -0,0 +1,30 @@
+// Loud-failure vocabulary (REQ-WEB-015 + the ratified severity law, 2026-07-06): development
+// throws, production reports through the error channel and REFUSES the offending property. The
+// classes here are pure data — severity is applied by the caller (see normalize.ts), never by an
+// ambient environment read inside this package.
+
+export type WebErrorMode = 'development' | 'production'
+export type WebErrorReporter = (error: MotionWebError) => void
+
+export class MotionWebError extends Error {
+  override name = 'MotionWebError'
+}
+
+// A capability the web engine must refuse at this scope: a ratified spike deferral, a registry
+// member outside the universal Target, or (once the category is populated) a native-only
+// extension. Messages name the capability and where it CAN run (REQ-WEB-015).
+export class MotionWebRejectionError extends MotionWebError {
+  override name = 'MotionWebRejectionError'
+}
+
+// A legal input motion/react cannot express faithfully — a recorded divergence, e.g. differing
+// per-axis snap sets through the single axis-blind modifyTarget.
+export class MotionWebFidelityError extends MotionWebError {
+  override name = 'MotionWebFidelityError'
+}
+
+// A malformed or internally-inconsistent input (non-finite numbers, snap points for an axis that
+// is not dragged, an undeclared prop key) — never projected into behavior.
+export class MotionWebIncompatibleError extends MotionWebError {
+  override name = 'MotionWebIncompatibleError'
+}

package/src/index.ts

@@ -0,0 +1,157 @@
+'use client'
+// Web driver-peer entry (SPEC-WEB-SHIM). The 'use client' directive is the ratified RSC posture
+// (2026-07-06): the shim ships its own client-component boundary, matching motion/react.
+//
+// The runtime surface is the spike's universal set: the View/Text/Image wrappers (normalization +
+// validation over motion.div / motion.p|span / motion.img) and motion/react's own presence
+// primitives re-exported under the public names (REQ-WEB-011 thin re-export — zero new
+// semantics). REQ-API-034's closed host set ships here; premature use of anything outside it is a
+// build error, never a silent no-op or an undefined component (REQ-WEB-015/016).
+
+export type {
+  DragControlOptions,
+  DragControlsHandle,
+  DragInfo,
+  TapCallback,
+  TapInfo,
+  MotionTargetProps,
+  Target,
+  TransformProperties,
+  TransformTemplate,
+  Transition,
+  TransitionType,
+} from '@unrulysystems/native-motion-core'
+
+export {
+  Image,
+  Text,
+  View,
+  createView,
+  type ImageProps,
+  type TextProps,
+  type ViewProps,
+} from './View'
+
+// REQ-WEB-019: raw pin namespaces. Native's smaller host floor never narrows the web engine's
+// intrinsic DOM/SVG hosts or motion.create custom-component factory.
+export { motion, m } from 'motion/react'
+
+// REQ-WEB-018: Motion-owned public additions stay raw on web while native remains scoped. Keep
+// this list explicit: every exported name is classified by the parity census, so an accidental
+// low-level barrel expansion fails closed instead of silently enlarging the product contract.
+export {
+  AnimateSharedLayout,
+  LazyMotion,
+  Reorder,
+  domAnimation,
+  domMax,
+  useAnimateMini,
+  useAnimationControls,
+  useInView,
+  useMotionTemplate,
+  useReducedMotion,
+  useTime,
+  useViewportScroll,
+} from 'motion/react'
+
+// U7b (REQ-WEB-011): the pin's global instant-animation window pair, raw re-exports — zero
+// new semantics. useInstantTransition returns the callback that opens the window
+// (MotionGlobalConfig.instantAnimations, forceUpdate, two-postRender-frame token-guarded
+// close — framer-motion utils/use-instant-transition.ts:9-41); disableInstantTransitions
+// clears the flag directly (:43-45).
+export { disableInstantTransitions, useInstantTransition } from 'motion/react'
+
+// Presence: motion/react's own lifecycle primitives ARE the web engine's presence semantics
+// (REQ-WEB-011); the native runtime binds core's createPresenceController to the same names.
+// The container rides the shim wrapper so popLayout is forwarded to the pin's PopChild geometry
+// composition, matching the native host contract; T24 B1 custom is forwarded through the wrapper,
+// and the hooks stay raw motion re-exports so their presence context is unchanged.
+export { AnimatePresence, createAnimatePresence } from './AnimatePresence'
+export { usePresence, useIsPresent, usePresenceData } from 'motion/react'
+// R4 — the public value channel (REQ-API-025..027): raw motion/react re-exports (REQ-WEB-011
+// thin re-export, zero new semantics) — the same real hooks the pinned oracle ships. The
+// MotionValue type follows for name parity with the native entry (engine-specific by design).
+export {
+  useMotionValue,
+  useMotionValueEvent,
+  useSpring,
+  useTransform,
+  useVelocity,
+} from 'motion/react'
+export { MotionValue } from 'motion/react'
+// REQ-API-037: raw pin hook value; separately named compatibility types remain cross-entry mapped.
+export { useScroll, type ScrollMotionValues, type UseScrollOptions } from './useScroll'
+// R12 M1 (REQ-API-039): thin validated re-export of the pin's animate / useAnimate —
+// entry-gate validation only; the pin owns all playback semantics. AnimateFn is the
+// shallow public callable type (dual-entry type-identity must not see pin overloads).
+export { animate, createAnimate, type AnimateFn, type AnimationPlaybackControls } from './animate'
+export { useAnimate, type AnimationScope, type UseAnimateReturn } from './useAnimate'
+// R13 M1 (REQ-API-040): thin re-export of the pin's useCycle (REQ-WEB-011).
+export { useCycle, type Cycle, type CycleState } from './useCycle'
+// R15 D3 (REQ-API-043): pin hub + empty-start fail-loud (G-INV-8; REQ-WEB-011 session semantics).
+export { useDragControls, DragControls } from './dragControls'
+// R13 value-breadth (REQ-VALUETYPE-013): no-op on web (pin measures); namespace parity with native.
+export {
+  MotionLengthLayoutProvider,
+  type MotionLengthLayoutProviderProps,
+} from './MotionLengthLayoutProvider'
+// R13 V2 (REQ-LAYOUT-022(c)): no-op composition on web (pin owns overflow:scroll measure).
+export {
+  LayoutScrollOffsetProvider,
+  createLayoutScrollOffsetRef,
+  recordLayoutScrollOffsetFromEvent,
+  type LayoutScrollOffset,
+  type LayoutScrollOffsetProviderProps,
+  type LayoutScrollOffsetRef,
+} from './LayoutScrollOffsetProvider'
+// Product dual-authority release helpers (absolute origin + project-then-snap) — key parity
+// with the dual public entry and the gallery dogfood surface.
+export { absoluteDragOrigin, selectReleaseTarget } from '@unrulysystems/native-motion-core'
+// REQ-WEB-011: utilities are raw pin values on web. Native's scoped core implementations never
+// project their narrower domains or identities onto this entry.
+export { mix, stagger, wrap } from 'motion/react'
+// U7g (REQ-LAYOUT-024): the pin's scale-corrector channel, raw re-export.
+export { addScaleCorrector } from 'motion/react'
+// U7j (REQ-API-058): the pin's JS-frame clock, raw re-export. Native implements the
+// same shape on the value-channel stepper. The `frame` scheduler stays residual.
+export { frameData } from 'motion/react'
+export type { FrameData } from 'motion-dom'
+// U8 (REQ-API-059): pin parametric path factory. Types live on motion-dom; motion/react
+// re-exports the value at runtime. Native implements the same call shape in core.
+export { arc } from 'motion-dom'
+export type { ArcOptions } from 'motion-dom'
+// The R4 public option-type NAMES exist on both entries (r13 major 4 — the namespace gate only
+// covers value exports); shapes are engine-specific by design. Web semantics come straight from
+// the pinned motion-dom types: SpringValueOptions is the exact options type motion's useSpring
+// accepts (its UseSpringOptions alias is unexported upstream), and TransformOptions is
+// motion-dom's own generic re-surfaced with a `never` default so the bare name resolves like
+// the native entry's.
+export type SpringValueOptions = MotionDomSpringOptions &
+  Pick<MotionDomFollowValueOptions, 'skipInitialAnimation'>
+export type TransformOptions<T = never> = MotionDomTransformOptions<T>
+
+// FLAG 5a (REQ-API-022): the root primitive — pass-through on web (no gesture root needed);
+// exists on both entries for the one-import universal surface (value-key parity).
+export { MotionRoot, type MotionRootProps } from './MotionRoot'
+// R10 M1 (REQ-API-035): thin validated re-export of the pin's MotionConfig — entry-gate
+// validation only; the pin owns subtree defaults and reducedMotion behavior.
+export {
+  MotionConfig,
+  createMotionConfig,
+  type MotionConfigProps,
+  type MotionConfigTransition,
+  type ReducedMotionConfig,
+} from './MotionConfig'
+// R10 M2 (REQ-API-036): thin validated re-export of the pin's LayoutGroup — entry-gate
+// validation only; the pin owns id namespacing and projection groups.
+export {
+  LayoutGroup,
+  createLayoutGroup,
+  type LayoutGroupInherit,
+  type LayoutGroupProps,
+} from './LayoutGroup'
+import type {
+  FollowValueOptions as MotionDomFollowValueOptions,
+  SpringOptions as MotionDomSpringOptions,
+  TransformOptions as MotionDomTransformOptions,
+} from 'motion-dom'

package/src/mode.ts

@@ -0,0 +1,12 @@
+// Ambient severity-mode resolution — the ONE place the React layer reads the environment (the
+// pure layer takes mode as a parameter; flagged at M2). Bundlers statically replace
+// process.env.NODE_ENV on web; anything not 'production' is development (fail-loud default).
+import type { WebErrorMode } from './errors'
+
+declare const process: { env?: { NODE_ENV?: string } } | undefined
+
+export function ambientMode(): WebErrorMode {
+  return typeof process !== 'undefined' && process.env?.NODE_ENV === 'production'
+    ? 'production'
+    : 'development'
+}