@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/transitionGate.ts

@@ -0,0 +1,435 @@
+// The ELEMENT transition boundary (r7 major 41b089c8c0af; lane law r9 762e9d0a4c77,
+// consumer-set law r11 3a1b5478e6c2; T18-b REQ-API-050): the `transition` prop feeds every
+// animation consumer the element mounts, and ONE authored config must execute IDENTICALLY on
+// all of them (the web engine applies it whole). It gates once here: core validateTransition
+// (shape, vocabulary, ranges, derived-config probe) plus the native option laws — `velocity` is
+// executed by BOTH native lanes since T21 F3 (property spring seeding, REQ-SPRING-007; the
+// layout flight's toSpringConfig) and refuses only on a layoutId flight (spring physics,
+// family-3); `delay` is executable by the layout builder AND
+// by the property lane (T18-b taught it the REQ-TIMING-004 rebase), so any element with a
+// layout or property consumer accepts it and both lanes delay identically. A layoutId flight
+// still refuses it — our FLIP machinery never reads the element transition's delay while the
+// pin passes transition options into projection flights: a recorded divergence, demand-gated
+// (T18-b L5). A WHOLLY consumer-less element stores the shape-validated config DORMANT
+// (T23 D): the pin consumes the element transition lazily (getDefaultTransition), so nothing
+// executes and nothing is silently inert — G-INV-8 is scoped to elements with at least one
+// mounted consumer that cannot execute the option; a consumer mounting on a later render
+// re-gates the same snapshot with real consumers.
+
+import {
+  InvalidTransitionError,
+  captureTransition,
+  TARGET_PROPERTY_KEYS,
+  validateTransitionRefusal,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+import {
+  keyframeTimingRefusal,
+  resolveTransitionForKey,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import type { StyleValueGate } from './styleValueBinding'
+import type { MotionComponentId } from './motionViewController'
+
+const capturedElementTransitions = new WeakSet<object>()
+const genericallyValidatedElementTransitions = new WeakSet<object>()
+const TRANSITION_MAP_KEYS = new Set<string>(['default', 'layout', ...TARGET_PROPERTY_KEYS])
+
+function hasTransitionMap(transition: Transition): boolean {
+  return Reflect.ownKeys(transition).some(
+    (key) => typeof key === 'string' && TRANSITION_MAP_KEYS.has(key),
+  )
+}
+
+function transitionMapSourceKey(transition: Transition, key: string): string {
+  const source = transition as Record<PropertyKey, unknown>
+  if (
+    TRANSITION_MAP_KEYS.has(key) &&
+    Object.hasOwn(source, key) &&
+    source[key] !== undefined &&
+    source[key] !== null
+  )
+    return key
+  if (Object.hasOwn(source, 'default') && source.default !== undefined && source.default !== null)
+    return 'default'
+  return 'root'
+}
+
+function sanitizedTransitionMap(
+  transition: Transition,
+  invalidSources: ReadonlySet<string>,
+): Transition | undefined {
+  // Removing a selected source changes the resolver's fallback path. Unless every newly exposed
+  // fallback has been gated for the same mounted consumer, preserving the map would let an invalid
+  // root/default option cross the production boundary without a report. Refuse the map atomically.
+  if (invalidSources.size > 0) return undefined
+  const source = transition as Record<PropertyKey, unknown>
+  const out: Record<PropertyKey, unknown> = Object.create(null)
+  const keepRoot = !invalidSources.has('root')
+  for (const key of Reflect.ownKeys(source)) {
+    if (typeof key === 'string' && TRANSITION_MAP_KEYS.has(key)) {
+      if (!invalidSources.has(key)) {
+        const descriptor = Object.getOwnPropertyDescriptor(source, key)
+        if (descriptor !== undefined)
+          Object.defineProperty(out, key, {
+            value: descriptor.value,
+            enumerable: descriptor.enumerable === true,
+            configurable: true,
+            writable: true,
+          })
+      }
+      continue
+    }
+    if (!keepRoot) continue
+    const descriptor = Object.getOwnPropertyDescriptor(source, key)
+    if (descriptor !== undefined)
+      Object.defineProperty(out, key, {
+        value: descriptor.value,
+        enumerable: descriptor.enumerable === true,
+        configurable: true,
+        writable: true,
+      })
+  }
+  return Reflect.ownKeys(out).length === 0 ? undefined : (Object.freeze(out) as Transition)
+}
+
+// A plain-object transition can be captured into a frozen snapshot; a malformed SHAPE (primitive, array,
+// prototype-carrying) must stay raw so core's validateTransition throws its typed refusal rather than a
+// capture laundering it into an empty `{}`.
+function isPlainTransition(value: Transition): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value) as unknown
+  return proto === Object.prototype || proto === null
+}
+
+// Capture the authored element transition before more than one supplying boundary needs it. Motion.View
+// passes this ONE snapshot to the render-time gesture gate, the element consumer-set gate, and the
+// mount-time gesture gate, so validation and execution never observe different caller-owned truths.
+export function captureElementTransition(value: Transition | undefined): Transition | undefined {
+  if (value === undefined) return undefined
+  if (!isPlainTransition(value)) return value
+  // Motion.View has already captured this snapshot for an earlier supplying boundary. Preserve identity
+  // so the gesture gate validates exactly the transition later handed to layout/property consumers.
+  if (capturedElementTransitions.has(value)) return value
+  const snapshot = captureTransition(value)
+  capturedElementTransitions.add(snapshot)
+  return snapshot
+}
+
+// Settle the generic core transition contract before a supplied snapshot can become an effective
+// fallback for another surface. Gesture-state targets inherit the element transition, so passing a
+// malformed raw value into their keyframe predicate would make an implementation detail (`.times`)
+// throw before the established typed transition refusal. Successful snapshots are remembered only to
+// avoid rerunning the pure validation when the consumer-set gate receives this exact captured truth.
+export function gateElementTransitionShape(
+  value: Transition | undefined,
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): Transition | undefined {
+  if (value === undefined) return undefined
+  // Capture runs OUTSIDE the try (review major 4e229b): a FOREIGN accessor/proxy fault must preserve
+  // its identity instead of being reported as an ordinary malformed transition.
+  const snapshot = captureElementTransition(value)
+  if (snapshot === undefined) return undefined
+  if (
+    typeof snapshot === 'object' &&
+    snapshot !== null &&
+    genericallyValidatedElementTransitions.has(snapshot)
+  ) {
+    return snapshot
+  }
+  // RETURN-shaped validation is intentional: a returned refusal is the transition boundary's typed
+  // input error, while a dependency fault thrown by validation must retain its identity rather than
+  // being mistaken for a production-reportable malformed transition.
+  const refusal = validateTransitionRefusal(snapshot, { componentId })
+  if (refusal !== null) {
+    if (gate.severity === 'development') throw refusal
+    gate.report(refusal)
+    return undefined // production: refuse the malformed prop before any fallback consumes it
+  }
+  if (typeof snapshot === 'object' && snapshot !== null) {
+    genericallyValidatedElementTransitions.add(snapshot)
+  }
+  return snapshot
+}
+
+// The repeat-family key this transition authored, or null. `repeat` is named first so the common
+// refusal points at the option the author actually reached for; the companions are still named
+// when they appear alone (core validation refuses that pairing, but this lane law must not depend
+// on the order the two gates run in).
+const REPEAT_FAMILY_KEYS = ['repeat', 'repeatType', 'repeatDelay'] as const
+
+function repeatFamilyKey(transition: Transition): (typeof REPEAT_FAMILY_KEYS)[number] | null {
+  for (const key of REPEAT_FAMILY_KEYS) {
+    if (transition[key] !== undefined) return key
+  }
+  return null
+}
+
+export function gateElementTransition(
+  value: Transition | undefined,
+  context: {
+    readonly consumers: {
+      /** True when the layout BUILDER consumes the element transition (layout prop truthy). */
+      readonly layout: boolean
+      /** True when property commands consume it (animate keys or gesture layers mounted). */
+      readonly property: boolean
+      /**
+       * Family-3: true when layoutId projection flight consumes duration/ease tween timing.
+       * Does not execute delay or spring physics options.
+       */
+      readonly layoutId?: boolean
+      /** Concrete property keys let a map resolve only the consumers this element actually owns. */
+      readonly propertyKeys?: readonly string[]
+    }
+  },
+  gate: StyleValueGate,
+  componentId: MotionComponentId = '<Motion.View>',
+): Transition | undefined {
+  // This second stage applies only the native consumer-set law. Generic shape/vocabulary/range
+  // validation was already settled by `gateElementTransitionShape` before any gesture can inherit the
+  // transition; direct callers still receive that authority through this wrapper.
+  const snapshot = gateElementTransitionShape(value, gate, componentId)
+  if (snapshot === undefined) return undefined
+  if (hasTransitionMap(snapshot)) {
+    const propertyKeys = context.consumers.propertyKeys
+    const candidates = new Map<
+      string,
+      {
+        readonly transition: Transition
+        consumers: {
+          layout: boolean
+          property: boolean
+          layoutId?: boolean
+        }
+      }
+    >()
+    const addCandidate = (
+      selectorKey: string,
+      consumers: { layout: boolean; property: boolean; layoutId?: boolean },
+    ): void => {
+      const sourceKey = transitionMapSourceKey(snapshot, selectorKey)
+      const existing = candidates.get(sourceKey)
+      if (existing !== undefined) {
+        existing.consumers.layout ||= consumers.layout
+        existing.consumers.property ||= consumers.property
+        existing.consumers.layoutId ||= consumers.layoutId === true
+        return
+      }
+      candidates.set(sourceKey, {
+        transition: resolveTransitionForKey(snapshot, selectorKey),
+        consumers: { ...consumers },
+      })
+    }
+
+    // Select the concrete mounted consumers first. Generic validation above still checks every
+    // authored branch's shape/ranges; these lane rules apply only to branches this host actually
+    // executes, so an unused repeat/keyframe bag cannot poison a valid map.
+    if (context.consumers.layout || context.consumers.layoutId === true) {
+      addCandidate('layout', {
+        layout: true,
+        property: false,
+        ...(context.consumers.layoutId === true ? { layoutId: true } : {}),
+      })
+    }
+    if (context.consumers.property) {
+      const selectedPropertyKeys =
+        propertyKeys === undefined || propertyKeys.length === 0 ? ['__root__'] : propertyKeys
+      for (const key of selectedPropertyKeys) {
+        addCandidate(key, { layout: false, property: true })
+      }
+    }
+    if (candidates.size === 0) {
+      addCandidate('__root__', { layout: false, property: false })
+    }
+
+    const invalidSources = new Set<string>()
+    for (const [sourceKey, candidate] of candidates) {
+      const gated = gateElementTransition(
+        candidate.transition,
+        { consumers: candidate.consumers },
+        gate,
+        componentId,
+      )
+      if (gated === undefined) invalidSources.add(sourceKey)
+    }
+    return sanitizedTransitionMap(snapshot, invalidSources)
+  }
+  const layoutId = context.consumers.layoutId === true
+  // T23 D (transition-config): a WHOLLY consumer-less element — no layout, no property owner,
+  // no layoutId (the map path's synthesized __root__ candidate included) — stores the
+  // shape-validated snapshot DORMANT. The per-option consumer-execution laws below need a
+  // consumer to be inert AGAINST; with none mounted the config waits, exactly like the pin's
+  // lazy getDefaultTransition consumption, and any later-mounted consumer re-gates it.
+  if (!context.consumers.layout && !context.consumers.property && !layoutId) {
+    return snapshot
+  }
+  let refusal: Error | null = null
+  // `velocity` is EXECUTED by both native lanes since T21 F3: the property lane's spring
+  // seeding (authored velocity overrides the live reseed, REQ-SPRING-007) and the layout
+  // flight's spring config (toSpringConfig carries it). The pre-T21 unconditional inert
+  // refusal is retired (review r1 major 2); layoutId flights still refuse it below with the
+  // rest of the spring-physics family.
+  // T18-a L4 (REQ-API-049): the repeat family has exactly one executable owner, a PROPERTY
+  // command. A layout/layoutId flight animates one snapshot delta, so repeating it would replay
+  // the same decay N times — degenerate at best, and it would fold repeat semantics into the
+  // layout engine's completion accounting. The pin lets the option flow into a flight; we refuse
+  // it loud instead of executing something meaningless (recorded divergence). The split case is
+  // refused for the same reason `times` is: one authored transition must execute identically on
+  // every consumer it reaches.
+  if (refusal === null) {
+    const repeated = repeatFamilyKey(snapshot)
+    if (repeated !== null) {
+      if (!context.consumers.property) {
+        refusal = new InvalidTransitionError(
+          componentId,
+          repeated,
+          snapshot[repeated],
+          'only a property animation can repeat — a layout/layoutId flight animates a single ' +
+            'snapshot delta, so repeating it would replay the same decay (T18-a L4 / G-INV-8, ' +
+            'shippedSurface.ts)',
+        )
+      } else if (context.consumers.layout || layoutId) {
+        refusal = new InvalidTransitionError(
+          componentId,
+          repeated,
+          snapshot[repeated],
+          'the repeat family cannot split across shared layout/layoutId and property consumers ' +
+            '— one authored transition must execute identically on every consumer, and a ' +
+            'flight never repeats (T18-a L4 / G-INV-8)',
+        )
+      }
+    }
+  }
+  // U7a: the authored instant lane (`type: false`) is PROPERTY-lane only — the property lane
+  // commits the final keyframe on the driver's next update tick (the pin's makeAnimationInstant,
+  // motion-dom@12.42.2 motion-value.ts:89-98,122-136). A layout/layoutId flight has no
+  // instant-commit wiring, so the option refuses loud here rather than silently flying the
+  // default spring (G-INV-8) — a recorded divergence, demand-gated like the layoutId `delay`
+  // refusal below. The mixed-consumer arm is the split-execution law: one authored transition
+  // must execute identically on every consumer, and a flight cannot execute this one.
+  if (refusal === null && snapshot.type === false && (context.consumers.layout || layoutId)) {
+    refusal = new InvalidTransitionError(
+      componentId,
+      'type',
+      false,
+      'a layout/layoutId flight cannot execute type: false — the authored instant lane is ' +
+        'property-only (the property lane commits the final keyframe on the next update tick); ' +
+        'a recorded divergence, demand-gated to a layout-instant successor rung ' +
+        '(U7a / G-INV-8, shippedSurface.ts)',
+    )
+  }
+  // `times` and a per-segment `ease` list have exactly one executable owner: a property
+  // keyframe-array command. Layout / layoutId flights have no such target.
+  if (refusal === null && !context.consumers.property) {
+    refusal = keyframeTimingRefusal(componentId, '<layout>', 0, snapshot)
+  }
+  // Split-execution ban: property can consume keyframe timing while layout/layoutId cannot
+  // (2vqwp8 83b5e1d407ac — layoutId+property was missing from the mixed check).
+  if (refusal === null && context.consumers.property && (context.consumers.layout || layoutId)) {
+    const timingRefusal = keyframeTimingRefusal(componentId, '<property>', 0, snapshot)
+    if (timingRefusal !== null) {
+      refusal = new InvalidTransitionError(
+        componentId,
+        timingRefusal.key,
+        timingRefusal.value,
+        'keyframe-only timing cannot split across shared layout/layoutId and property ' +
+          'consumers — one authored transition must execute identically on every consumer ' +
+          '(REQ-API-033 law d / family-3)',
+      )
+    }
+  }
+  // Family-3 + T22 layoutId flight: typed springs (type:'spring', physics or time-defined)
+  // execute as a per-flight spring (REQ-LAYOUT-023 a). Two refusals survive: `velocity` — the
+  // pin's own projection forces velocity: 0, so executing an authored number would EXCEED the
+  // pin, and silently dropping it is the G-INV-8 class; and physics options WITHOUT
+  // type:'spring' — no resolvable flight config (the pin runs that bag as an untyped tween
+  // that silently ignores the physics; we refuse loud instead). U7c (REQ-SPRING-014):
+  // `restDelta`/`restSpeed` join the physics family — executed under an explicit type:'spring'
+  // (toSpringConfig carries them into the flight spring), refused in the untyped bag below.
+  if (refusal === null && layoutId && snapshot.velocity !== undefined) {
+    refusal = new InvalidTransitionError(
+      componentId,
+      'velocity',
+      snapshot.velocity,
+      'layoutId projection flight refuses velocity — the pinned projection forces velocity 0 ' +
+        'on every flight (REQ-LAYOUT-023 b / G-INV-8)',
+    )
+  }
+  if (
+    refusal === null &&
+    layoutId &&
+    snapshot.type !== 'spring' &&
+    (snapshot.stiffness !== undefined ||
+      snapshot.damping !== undefined ||
+      snapshot.mass !== undefined ||
+      snapshot.bounce !== undefined ||
+      snapshot.visualDuration !== undefined ||
+      snapshot.restDelta !== undefined ||
+      snapshot.restSpeed !== undefined)
+  ) {
+    const springKey =
+      snapshot.stiffness !== undefined
+        ? 'stiffness'
+        : snapshot.damping !== undefined
+          ? 'damping'
+          : snapshot.mass !== undefined
+            ? 'mass'
+            : snapshot.bounce !== undefined
+              ? 'bounce'
+              : snapshot.visualDuration !== undefined
+                ? 'visualDuration'
+                : snapshot.restDelta !== undefined
+                  ? 'restDelta'
+                  : 'restSpeed'
+    const springValue = snapshot[springKey]
+    refusal = new InvalidTransitionError(
+      componentId,
+      springKey,
+      springValue,
+      'layoutId projection flight executes spring options only under an explicit ' +
+        "type: 'spring' — an untyped physics bag has no resolvable flight config " +
+        '(REQ-LAYOUT-023 b / G-INV-8)',
+    )
+  }
+  // Ease-only / easings-only without duration or type:tween does not resolve to flight timing
+  // (layoutIdFlightTiming) — refuse rather than silent spring fallback (tjynor e30b75a4c19f).
+  if (
+    refusal === null &&
+    layoutId &&
+    snapshot.duration === undefined &&
+    snapshot.type !== 'tween' &&
+    (snapshot.ease !== undefined || snapshot.easings !== undefined || snapshot.easing !== undefined)
+  ) {
+    const easeKey =
+      snapshot.ease !== undefined ? 'ease' : snapshot.easings !== undefined ? 'easings' : 'easing'
+    refusal = new InvalidTransitionError(
+      componentId,
+      easeKey,
+      snapshot.ease ?? snapshot.easings ?? snapshot.easing,
+      'layoutId projection flight requires duration or type:tween with ease — ease-only ' +
+        'options are residual (REQ-LAYOUT-023 / G-INV-8)',
+    )
+  }
+  if (refusal === null && layoutId && snapshot.delay !== undefined) {
+    // T18-b (REQ-API-050 / packet L5): the property lane executes the delay rebase, so the
+    // split-execution refusal is RETIRED — an element mixing layout and property consumers
+    // delays both lanes identically, matching the web engine. The consumer-less arm retired
+    // at T23 D (the dormant accept above returns before any option law). What remains is the
+    // layoutId arm, restated as the divergence it is: the pin passes transition options into
+    // projection flights; our FLIP machinery never reads the element transition's delay.
+    // Recorded divergence, demand-gated to a successor rung — not a "cannot execute".
+    refusal = new InvalidTransitionError(
+      componentId,
+      'delay',
+      snapshot.delay,
+      'a layoutId projection flight never reads the element transition\u2019s delay — not ' +
+        'executed, a recorded divergence from the pin (whose projection flights consume ' +
+        'transition options); demand-gated to a layoutId-flight-delay successor rung ' +
+        '(REQ-API-050, T18-b L5, shippedSurface.ts)',
+    )
+  }
+  if (refusal === null) return snapshot
+  if (gate.severity === 'development') throw refusal
+  gate.report(refusal)
+  return undefined // production: refuse the prop, mount with the default transition
+}

package/src/native/motion/useAnimate.ts

@@ -0,0 +1,52 @@
+// REQ-API-039 — useAnimate on the native entry: [scope, animate] with unmount-stop of tracked
+// animations (pin useUnmountEffect law). Scoped animate resolves selectors inside scope.current
+// and routes every command through the prepared seam (imperativeAnimate.ts).
+
+import { useEffect, useMemo } from 'react'
+import { useMotionConfig } from './MotionConfig'
+import {
+  createScopedAnimate,
+  type AnimateFn,
+  type AnimationScope,
+  USE_ANIMATE_OWNER,
+} from './imperativeAnimate'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import { useValueChannel } from './valueHooks'
+
+export type { AnimateFn, AnimationPlaybackControls, AnimationScope } from './imperativeAnimate'
+
+/** Shallow public pair — mirrors web useAnimate (REQ-API-039; dual-entry type-identity). */
+export type UseAnimateReturn<T = unknown> = readonly [AnimationScope<T>, AnimateFn]
+
+export function useAnimate<T = unknown>(): UseAnimateReturn<T> {
+  const scope = useMemo<AnimationScope<T>>(
+    () => ({
+      current: null,
+      animations: [],
+    }),
+    [],
+  )
+  const { skipAnimations } = useMotionConfig()
+  const channel = useValueChannel()
+  const severity = ambientNativeSeverity()
+  const animate = useMemo(
+    () =>
+      createScopedAnimate({
+        scope: scope as AnimationScope,
+        channel,
+        skipAnimations,
+        gate: { severity, report: consoleReporter, owner: USE_ANIMATE_OWNER },
+      }),
+    [scope, channel, skipAnimations, severity],
+  )
+
+  // Pin useUnmountEffect law: every animation tracked on scope.animations stops on unmount.
+  useEffect(() => {
+    return () => {
+      for (const animation of scope.animations) animation.stop()
+      scope.animations.length = 0
+    }
+  }, [scope])
+
+  return [scope, animate]
+}

package/src/native/motion/useCycle.ts

@@ -0,0 +1,44 @@
+// REQ-API-040 — useCycle on the native entry: pin-faithful cycle through a fixed item list.
+// Pin: framer-motion use-cycle.ts (motion@12.42.2) — [current, cycle]; cycle() advances with
+// wrap; cycle(i) jumps to index. Web re-exports motion/react's useCycle (entry parity).
+
+import { useCallback, useRef, useState } from 'react'
+
+export type Cycle = (i?: number) => void
+export type CycleState<T> = [T, Cycle]
+
+/** Pin wrap (motion-utils): map v into [min, max). */
+function wrap(min: number, max: number, v: number): number {
+  const rangeSize = max - min
+  if (rangeSize === 0) return min
+  return ((((v - min) % rangeSize) + rangeSize) % rangeSize) + min
+}
+
+/**
+ * Cycles through a series of values (Motion-shaped). Returns `[current, cycle]` where
+ * `cycle()` advances to the next item (wrapping) and `cycle(i)` jumps to index `i`.
+ *
+ * Zero items refuse (REQ-API-040) — the pin would leave undefined state; native fails loud.
+ */
+export function useCycle<T>(...items: T[]): CycleState<T> {
+  if (items.length === 0) {
+    throw new Error(
+      'useCycle: at least one item is required (REQ-API-040) — an empty cycle has no current state.',
+    )
+  }
+
+  const index = useRef(0)
+  const [item, setItem] = useState(items[index.current] as T)
+
+  const runCycle = useCallback(
+    (next?: number) => {
+      index.current = typeof next !== 'number' ? wrap(0, items.length, index.current + 1) : next
+      setItem(items[index.current] as T)
+    },
+    // Pin: items.length first so identity churn still matches on length; then items.
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- pin dependency law
+    [items.length, ...items],
+  )
+
+  return [item, runCycle]
+}

package/src/native/motion/useInstantTransition.ts

@@ -0,0 +1,68 @@
+// U7b — useInstantTransition + disableInstantTransitions on the native entry (the
+// instant-transition lane's hook surface). Pin: framer-motion@12.42.2
+// utils/use-instant-transition.ts:9-45 — the hook returns a callback that opens the GLOBAL
+// instant window (native's MotionGlobalConfig.instantAnimations analogue, driver/instantWindow),
+// force-renders the calling component, runs the user's callback, and relocks TWO post-render
+// frames later under the render-count TOKEN guard: a back-to-back call bumps the token, so the
+// stale unlock bails and the window extends (the pin's own test,
+// use-instant-transition.test.tsx:150-176, is the model). There is deliberately NO frame
+// cancellation: an unmounted caller's pending unlock still closes the window, so unmount never
+// leaks it. The window itself (skip generator, final keyframe next update tick, delay ZEROED —
+// F2's asymmetry vs the authored type:false) is consulted at the driver's JS-side transition
+// resolution and pinned in workletDriver.lanes.test.ts. Web re-exports the raw pin.
+//
+// Two native deltas from the pin's mechanics, neither semantic: the force-render is a plain
+// useReducer dispatch (the repo's own idiom — the pin's frame.postRender deferral exists for
+// pre-18 batching; React 18 batches the callback's own setStates into the same commit), and the
+// two post-render frames are nested requestAnimationFrames (native has no motion-dom frame
+// loop). The returned callback is STABLE across the forced renders (the packet's contract): the
+// count the token derives from rides a ref, so identity never changes.
+
+import { useCallback, useEffect, useReducer, useRef } from 'react'
+import { closeInstantWindow, openInstantWindow } from '../driver/instantWindow'
+
+/**
+ * The pin's `useInstantTransition`: a callback that runs `callback` inside the global instant
+ * window — every animation starting inside it (any component, any motion value) skips its
+ * generator and commits its final keyframe on the driver's next update tick, with `delay`
+ * zeroed. The window closes two post-render frames after the last call.
+ */
+export function useInstantTransition(): (callback: () => void) => void {
+  const [forcedRenderCount, forceUpdate] = useReducer((count: number) => count + 1, 0)
+  const forcedRenderCountRef = useRef(forcedRenderCount)
+  forcedRenderCountRef.current = forcedRenderCount
+  const unlockOnFrameRef = useRef(-1)
+
+  useEffect(() => {
+    // Relock after TWO animation frames — one would unblock before the forced render's
+    // animations even start (the pin's double frame.postRender).
+    requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        // The token guard: a back-to-back call recorded a NEWER token after this effect
+        // scheduled, so this stale unlock bails — the window extends instead of closing
+        // early (pin :150-176). No cancellation on unmount: the latest pending unlock
+        // still matches its token and closes the window, so unmount never leaks it.
+        if (forcedRenderCount !== unlockOnFrameRef.current) return
+        closeInstantWindow()
+      }),
+    )
+  }, [forcedRenderCount])
+
+  return useCallback(
+    (callback: () => void) => {
+      openInstantWindow()
+      forceUpdate()
+      callback()
+      unlockOnFrameRef.current = forcedRenderCountRef.current + 1
+    },
+    [forceUpdate],
+  )
+}
+
+/**
+ * The pin's sibling export (use-instant-transition.ts:43-45): clears the global instant window
+ * immediately — the escape hatch for a stuck window.
+ */
+export function disableInstantTransitions(): void {
+  closeInstantWindow()
+}

package/src/native/motion/useReducedMotion.ts

@@ -0,0 +1,58 @@
+// U7a (the REQ-API-027-adjacent hook row) — useReducedMotion on the native entry: the pin's
+// ACTUAL semantics, not its docblock's. Pin: framer-motion@12.42.2
+// utils/reduced-motion/use-reduced-motion.ts:37-58 — a mount-time SNAPSHOT of the OS
+// reduced-motion preference, frozen for the hook's lifetime: a frozen `useState` initial with NO
+// setter, NO effect, NO subscription (the docblock's "actively respond to changes" is stale; the
+// file's own TODO concedes it). The fidelity doctrine forbids "improving" on that, so native
+// takes NO `reduceMotionChanged` subscription either (packet F1 — the no-re-render test is the
+// unit's fidelity pin). Web re-exports the raw pin (native-motion-web/src/index.ts).
+//
+// The one platform difference is the async transient (packet F2): RN's answer is a promise
+// where the pin's `matchMedia` read is synchronous, so the first-render value is `false` — the
+// pin's own matchMedia-absent fallback (reduced-motion/index.ts:19) — and the resolved OS value
+// replaces it ONCE, inside the mount's snapshot window.
+
+import { useEffect, useState } from 'react'
+import { AccessibilityInfo } from 'react-native'
+
+declare const __DEV__: boolean | undefined
+
+// The pin's warnOnce (motion-utils): one console.warn per key, dev-only.
+const warnedKeys = new Set<string>()
+function warnOnce(condition: boolean, message: string, key: string): void {
+  if (condition || warnedKeys.has(key)) return
+  warnedKeys.add(key)
+  console.warn(message)
+}
+
+/**
+ * Whether the OS reduced-motion preference was enabled at mount, as a frozen snapshot. First
+ * render returns `false`; the resolved OS value lands once, asynchronously. The return type is
+ * the pin's wider `boolean | null` shape (the pin's `null` is its SSR/no-window read; native has
+ * no SSR host, so the value is never null in practice).
+ */
+export function useReducedMotion(): boolean | null {
+  const [shouldReduceMotion, setShouldReduceMotion] = useState<boolean | null>(false)
+  useEffect(() => {
+    // The MotionConfig cancel-flag pattern (MotionConfig.tsx:350-377), minus its subscription:
+    // ONE read per mount, one state update on resolve, swallowed after unmount.
+    let cancelled = false
+    void AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (!cancelled) setShouldReduceMotion(enabled === true)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+  if (typeof __DEV__ === 'undefined' || __DEV__ !== false) {
+    // The pin's dev-only warnOnce, verbatim message + key (use-reduced-motion.ts:45-51). It
+    // fires from the render body like the pin's — on the resolve re-render, never on the
+    // first (false) frame.
+    warnOnce(
+      shouldReduceMotion !== true,
+      'You have Reduced Motion enabled on your device. Animations may not appear as expected.',
+      'reduced-motion-disabled',
+    )
+  }
+  return shouldReduceMotion
+}