@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/valueHooks.ts

@@ -0,0 +1,901 @@
+// The public value-channel hooks on the native entry (REQ-API-025/-026/-027): pinned-oracle names
+// and semantics over CORE's graph — useMotionValue returns the exact graph value the driver seam
+// reads (never a wrapper copy), useTransform derives on core's JS-side graph, useSpring couples a
+// follower through core's spring resolution, useVelocity mirrors core's velocity law. The web
+// entry re-exports motion/react's own hooks under the same names (type-identity namespace parity).
+//
+// Transform parameters re-apply on every commit like the pinned hook (the dependency set alone
+// is fixed at first render); spring coupling identity is fixed per mount. Subscriptions attach
+// per effect lifetime, so a StrictMode replay detaches and re-attaches without orphaning work.
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useInsertionEffect,
+  useRef,
+  type ReactNode,
+} from 'react'
+import {
+  collectMotionValueReads,
+  mix,
+  parseValue,
+  resolveSpringGenerator,
+  transformValue,
+  type MotionValue,
+  type MotionValueEvent,
+  type SpringConfig,
+} from '@unrulysystems/native-motion-core'
+import {
+  createDirectPublicMotionValue,
+  type MotionValueDriverPort,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import { createValueChannel, type ValueChannel } from './valueChannel'
+
+// ——— channel injection ———————————————————————————————————————————————————————————————————————
+
+const ValueChannelContext = createContext<ValueChannel | null>(null)
+
+/**
+ * Private native observation boundary for an identity-channel MotionValue's transported cache.
+ * The cache owns velocity authority; observer frames only decide when React-side consumers
+ * re-read it. Keeping both behind one injected port makes frame cadence deterministic without a
+ * synchronous source read or a wall-clock timer.
+ */
+export interface ValueHooksIdentityChannelPort {
+  now(): number
+  readTransportedCachedVelocity(source: MotionValue<number>, atTimestampMs: number): number
+  subscribeTransportedChange(source: MotionValue<number>, listener: () => void): () => void
+  requestObserverFrame(callback: (atTimestampMs: number) => void): () => void
+  observeSynchronousCrossings(): ValueHooksIdentityChannelCrossingObservation
+}
+
+export interface ValueHooksIdentityChannelCrossingObservation {
+  readonly synchronousJsToUiReadCount: number
+}
+
+export interface ValueHooksIdentityChannelCrossingObserver {
+  observe(): ValueHooksIdentityChannelCrossingObservation
+}
+
+export interface CanonicalValueHooksIdentityRegistration {
+  readonly source: MotionValue<number>
+  readonly driverPort: MotionValueDriverPort<number>
+}
+
+export interface CreateCanonicalValueHooksIdentityChannelPortOptions {
+  readonly registrations: readonly CanonicalValueHooksIdentityRegistration[]
+  readonly clock: { now(): number }
+  readonly observerScheduler: {
+    requestObserverFrame(callback: (atTimestampMs: number) => void): () => void
+  }
+  /** Read-only instrumentation owned by the crossing adapter, never by the cache-read callback. */
+  readonly crossingObserver: ValueHooksIdentityChannelCrossingObserver
+}
+
+export type ValueHooksIdentityChannelInvariant =
+  | 'UNREGISTERED_CANONICAL_SOURCE'
+  | 'MISMATCHED_CANONICAL_SOURCE'
+  | 'MISSING_CANONICAL_CHANNEL_PORT'
+  | 'DUPLICATE_CANONICAL_CHANNEL_PORT'
+
+export class ValueHooksIdentityChannelInvariantError extends Error {
+  override name = 'ValueHooksIdentityChannelInvariantError'
+  readonly code = 'NATIVE_MOTION_VALUE_HOOKS_IDENTITY_CHANNEL_INVARIANT' as const
+  readonly invariant: ValueHooksIdentityChannelInvariant
+
+  constructor(invariant: ValueHooksIdentityChannelInvariant) {
+    super(`native-motion: value-hooks identity-channel invariant '${invariant}' failed`)
+    this.invariant = invariant
+  }
+}
+
+function canonicalRegistrationFor(
+  registrations: readonly CanonicalValueHooksIdentityRegistration[],
+  source: MotionValue<number>,
+): CanonicalValueHooksIdentityRegistration {
+  const registration = registrations.find((candidate) => candidate.source === source)
+  if (registration === undefined) {
+    throw new ValueHooksIdentityChannelInvariantError('UNREGISTERED_CANONICAL_SOURCE')
+  }
+  if (registration.driverPort.value !== source) {
+    throw new ValueHooksIdentityChannelInvariantError('MISMATCHED_CANONICAL_SOURCE')
+  }
+  return registration
+}
+
+/**
+ * Production-shaped adapter from the exact-identity CORE port to hook observation. Cache reads
+ * stay on JS; the separately owned crossing observer makes that claim measurable rather than
+ * letting an injected read callback self-attest.
+ */
+export function createCanonicalValueHooksIdentityChannelPort(
+  options: CreateCanonicalValueHooksIdentityChannelPortOptions,
+): ValueHooksIdentityChannelPort {
+  return {
+    now: () => options.clock.now(),
+    readTransportedCachedVelocity(source, atTimestampMs) {
+      return canonicalRegistrationFor(options.registrations, source).driverPort.readCachedVelocity(
+        atTimestampMs,
+      )
+    },
+    subscribeTransportedChange(source, listener) {
+      canonicalRegistrationFor(options.registrations, source)
+      return source.subscribe(() => listener())
+    },
+    requestObserverFrame: (callback) => options.observerScheduler.requestObserverFrame(callback),
+    observeSynchronousCrossings: () => options.crossingObserver.observe(),
+  }
+}
+
+export type ValueHooksIdentityChannelResolution =
+  | { readonly kind: 'EXPLICIT_PROVIDER'; readonly port: ValueHooksIdentityChannelPort }
+  | { readonly kind: 'CANONICAL_VALUE_CHANNEL'; readonly port: ValueHooksIdentityChannelPort }
+
+const canonicalIdentityPorts = new WeakMap<ValueChannel, ValueHooksIdentityChannelPort>()
+
+/** Registers the one canonical identity observer for a channel; cleanup is identity-guarded. */
+export function registerCanonicalValueHooksIdentityChannelPort(
+  channel: ValueChannel,
+  port: ValueHooksIdentityChannelPort,
+): () => void {
+  if (canonicalIdentityPorts.has(channel)) {
+    throw new ValueHooksIdentityChannelInvariantError('DUPLICATE_CANONICAL_CHANNEL_PORT')
+  }
+  canonicalIdentityPorts.set(channel, port)
+  return () => {
+    if (canonicalIdentityPorts.get(channel) === port) canonicalIdentityPorts.delete(channel)
+  }
+}
+
+/** The production resolution seam `useVelocity` must consume; explicit injection is test-only. */
+export function resolveValueHooksIdentityChannelPort(
+  channel: ValueChannel,
+  explicitPort: ValueHooksIdentityChannelPort | null,
+): ValueHooksIdentityChannelResolution {
+  if (explicitPort !== null) return { kind: 'EXPLICIT_PROVIDER', port: explicitPort }
+  const port = canonicalIdentityPorts.get(channel)
+  if (port === undefined) {
+    throw new ValueHooksIdentityChannelInvariantError('MISSING_CANONICAL_CHANNEL_PORT')
+  }
+  return { kind: 'CANONICAL_VALUE_CHANNEL', port }
+}
+
+const ValueHooksIdentityChannelContext = createContext<ValueHooksIdentityChannelPort | null>(null)
+
+export function ValueHooksIdentityChannelProvider(props: {
+  readonly port: ValueHooksIdentityChannelPort
+  readonly children?: ReactNode
+}): ReturnType<typeof createElement> {
+  return createElement(
+    ValueHooksIdentityChannelContext.Provider,
+    { value: props.port },
+    props.children,
+  )
+}
+
+// The app-default runtime: ONE module singleton so values compose across the whole tree (the
+// pinned oracle's global frameloop model). Lazy so tests that always inject never create it.
+let defaultChannel: ValueChannel | null = null
+/**
+ * The one app-default graph. Imperative commands import this resolver instead of creating a
+ * sibling singleton, so standalone animation and hook-created MotionValues share interruption
+ * and settle accounting.
+ */
+export function resolveDefaultValueChannel(): ValueChannel {
+  if (defaultChannel === null) defaultChannel = createValueChannel()
+  return defaultChannel
+}
+
+/** Test seam for deterministic frames; production always uses the lazy app-default graph. */
+export function setDefaultValueChannelForTests(channel: ValueChannel | null): void {
+  defaultChannel = channel
+}
+
+export function ValueChannelProvider(props: {
+  readonly channel: ValueChannel
+  readonly children?: ReactNode
+}): ReturnType<typeof createElement> {
+  return createElement(ValueChannelContext.Provider, { value: props.channel }, props.children)
+}
+
+export function useValueChannel(): ValueChannel {
+  return useContext(ValueChannelContext) ?? resolveDefaultValueChannel()
+}
+
+// ——— useMotionValue (REQ-API-025) ————————————————————————————————————————————————————————————
+
+export function useMotionValue<T = number>(initial: T): MotionValue<T> {
+  const channel = useValueChannel()
+  const ref = useRef<MotionValue<T> | null>(null)
+  if (ref.current === null) ref.current = createDirectPublicMotionValue(channel.graph, initial)
+  return ref.current
+}
+
+/**
+ * Native subsystem factory for graph-fed values such as scroll offsets. It is intentionally absent
+ * from the package entry: only a consumer's direct `useMotionValue` call receives public-direct
+ * provenance.
+ */
+export function useInternalMotionValue<T = number>(initial: T): MotionValue<T> {
+  const channel = useValueChannel()
+  const ref = useRef<MotionValue<T> | null>(null)
+  if (ref.current === null) ref.current = channel.graph.motionValue(initial)
+  return ref.current
+}
+
+// ——— useMotionValueEvent (REQ-API-027) ———————————————————————————————————————————————————————
+
+export function useMotionValueEvent<T>(
+  value: MotionValue<T>,
+  event: 'change',
+  handler: (latest: T) => void,
+): void
+export function useMotionValueEvent<T>(
+  value: MotionValue<T>,
+  event: Exclude<MotionValueEvent, 'change'>,
+  handler: () => void,
+): void
+export function useMotionValueEvent<T>(
+  value: MotionValue<T>,
+  event: MotionValueEvent,
+  handler: ((latest: T) => void) | (() => void),
+): void {
+  // Latest-ref so the subscription never holds a stale closure (the presence-rig pattern).
+  // Payload typing follows the pinned union (r2 major a66e69c0f004): 'change' delivers the
+  // latest value; the lifecycle events carry no payload. The change handler FORWARDS the
+  // event's own payload (r16 major 2) — a later re-read of mutable state corrupts event
+  // identity under reentrant writes.
+  const latest = useRef(handler)
+  latest.current = handler
+  useInsertionEffect(() => {
+    if (event === 'change') {
+      return value.on('change', (latestValue: T) =>
+        (latest.current as (payload: T) => void)(latestValue),
+      )
+    }
+    return value.on(event as Exclude<MotionValueEvent, 'change'>, () =>
+      (latest.current as () => void)(),
+    )
+  }, [value, event])
+}
+
+// ——— useTransform (REQ-API-027, the five pinned public forms) ————————————————————————————————
+
+export type SingleTransformer<I, O> = (input: I) => O
+export type MultiTransformer<I, O> = (inputs: I[]) => O
+export type EasingFunction = (progress: number) => number
+
+// Generic like the pinned motion-dom TransformOptions<T> (r13 major 4 — the name must resolve
+// identically through both entries, including the generic form); `never` default keeps the
+// bare name valid, matching the web entry's re-surfaced default.
+export interface TransformOptions<T = never> {
+  /** Clamp input to the range (the pinned default). */
+  readonly clamp?: boolean
+  /**
+   * Easing between each pair of range stops (pinned contract: an array must be one item
+   * shorter than the ranges — one easing per segment).
+   */
+  readonly ease?: EasingFunction | readonly EasingFunction[]
+  /** Custom per-segment interpolator, overriding the typed mix (pinned contract). */
+  readonly mixer?: (from: T, to: T) => (progress: number) => unknown
+}
+
+// A faithful port of the pinned interpolate (motion-dom utils/interpolate.ts at the §B pin,
+// review r3): single-stop and equal-two-output constants; the zero-delta first-segment guard;
+// a highest→lowest input reverses BOTH ranges but NOT the ease array (ease[i] belongs to the
+// i-th segment of the REVERSED ranges); mixers are created ONCE per segment with the easing
+// piped in; clamp bounds the INPUT to the range ends. The typed default mixer rides core's
+// parity-pinned value types (numbers lerp; strings parse once per endpoint and mix per
+// family). One deliberate, recorded divergence: a short ease array is a LOUD failure here —
+// the pin silently pipes a broken segment (fail-loud law over pinned undefined behavior).
+function buildInterpolator(
+  inputRangeAuthored: readonly number[],
+  outputRangeAuthored: readonly (number | string)[],
+  options: TransformOptions,
+): (input: number) => unknown {
+  // The shipped mixing families are number and string (core parseValue's parity-pinned
+  // types). Objects/composites belong to the value-breadth successor work — without a custom
+  // mixer they fail TYPED here (r14 major 9), never as parseValue's raw internals.
+  if (options.mixer === undefined) {
+    for (const output of outputRangeAuthored) {
+      if (typeof output !== 'number' && typeof output !== 'string') {
+        throw new Error(
+          `useTransform: output ${JSON.stringify(output)} is outside the shipped mixing ` +
+            'families (number | string) — object/composite outputs are deferred to the ' +
+            'value-breadth rung; supply options.mixer to interpolate them (REQ-API-027, ' +
+            'specs/R4-VALUE-CHANNEL-BUILD-PACKET.md).',
+        )
+      }
+    }
+  }
+  if (inputRangeAuthored.length !== outputRangeAuthored.length) {
+    throw new Error(
+      `useTransform: inputRange and outputRange must be the same length ` +
+        `(got ${inputRangeAuthored.length}/${outputRangeAuthored.length}) — REQ-API-027`,
+    )
+  }
+  if (inputRangeAuthored.length === 1) return () => outputRangeAuthored[0]
+  if (inputRangeAuthored.length === 2 && outputRangeAuthored[0] === outputRangeAuthored[1]) {
+    return () => outputRangeAuthored[1]
+  }
+  const isZeroDeltaRange = inputRangeAuthored[0] === inputRangeAuthored[1]
+  const descending = inputRangeAuthored[0]! > inputRangeAuthored[inputRangeAuthored.length - 1]!
+  const input = descending ? [...inputRangeAuthored].reverse() : inputRangeAuthored
+  const output = descending ? [...outputRangeAuthored].reverse() : outputRangeAuthored
+
+  const segments = input.length - 1
+  const easings: readonly EasingFunction[] | null =
+    options.ease === undefined
+      ? null
+      : Array.isArray(options.ease)
+        ? options.ease
+        : Array.from({ length: segments }, () => options.ease as EasingFunction)
+  if (easings !== null && easings.length !== segments) {
+    throw new Error(
+      `useTransform: an ease array must be one item shorter than the ranges ` +
+        `(${segments} segments, got ${easings.length} easings) — the pinned contract`,
+    )
+  }
+  const mixerFactory = options.mixer as
+    | ((from: number | string, to: number | string) => (progress: number) => unknown)
+    | undefined
+  // Mixers once per segment (the pinned createMixers), easing piped into each.
+  const mixers: Array<(progress: number) => unknown> = []
+  for (let i = 0; i < segments; i++) {
+    const from = output[i]!
+    const to = output[i + 1]!
+    let segmentMixer: (progress: number) => unknown
+    if (mixerFactory !== undefined) {
+      segmentMixer = mixerFactory(from, to)
+    } else if (typeof from === 'number' && typeof to === 'number') {
+      segmentMixer = (progress) => from + (to - from) * progress
+    } else {
+      const typedFrom = parseValue(typeof from === 'number' ? String(from) : from)
+      const typedTo = parseValue(typeof to === 'number' ? String(to) : to)
+      segmentMixer = (progress) => transformValue(mix(typedFrom, typedTo, progress))
+    }
+    if (easings !== null) {
+      const easing = easings[i]!
+      const baseMixer = segmentMixer
+      segmentMixer = (progress) => baseMixer(easing(progress))
+    }
+    mixers.push(segmentMixer)
+  }
+
+  const interpolator = (value: number): unknown => {
+    if (isZeroDeltaRange && value < input[0]!) return output[0]
+    let i = 0
+    if (mixers.length > 1) {
+      for (; i < input.length - 2; i++) {
+        if (value < input[i + 1]!) break
+      }
+    }
+    const from = input[i]!
+    const to = input[i + 1]!
+    // Pinned motion-utils progress: a zero-delta segment reports progress 1, not 0.
+    const progress = to === from ? 1 : (value - from) / (to - from)
+    return mixers[i]!(progress)
+  }
+  const clampInput = options.clamp !== false
+  return clampInput
+    ? (value: number) =>
+        interpolator(Math.min(Math.max(value, input[0]!), input[input.length - 1]!))
+    : interpolator
+}
+
+export function useTransform<O extends number | string>(
+  value: MotionValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly O[],
+  // The generic FLOWS into the options (r16 major 4, the pinned TransformOptions<O>): a
+  // custom mixer's inferred params are O, never `never`.
+  options?: TransformOptions<O>,
+): MotionValue<O>
+// The documented mixer EXCEPTION (r15 7a0e46b8f213): arbitrary output types compile when — and
+// only when — a custom `mixer` interpolates them (`mixer` REQUIRED here; the narrowed form
+// above owns the mixer-less calls). Runtime already routes every segment through the supplied
+// mixer, so no runtime branch changes.
+export function useTransform<O>(
+  value: MotionValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly O[],
+  options: Omit<TransformOptions<O>, 'mixer'> & {
+    readonly mixer: (from: O, to: O) => (progress: number) => unknown
+  },
+): MotionValue<O>
+// The pinned OUTPUT-MAP form (r11): one input, an object of output ranges, a record of derived
+// values back — keys must stay constant across renders (the pinned contract).
+export function useTransform<T extends Record<string, readonly (number | string)[]>>(
+  value: MotionValue<number>,
+  inputRange: readonly number[],
+  outputMap: T,
+  // Pinned: TransformOptions<T[keyof T][number]> — the mixer sees the union of output types.
+  options?: TransformOptions<T[keyof T][number]>,
+): { [K in keyof T]: MotionValue<T[K][number]> }
+export function useTransform<I, O>(
+  input: MotionValue<I>,
+  transformer: SingleTransformer<I, O>,
+): MotionValue<O>
+export function useTransform<I, O>(
+  input: readonly MotionValue<I>[],
+  transformer: MultiTransformer<I, O>,
+): MotionValue<O>
+export function useTransform<O>(transformer: () => O): MotionValue<O>
+export function useTransform(
+  first: MotionValue<unknown> | readonly MotionValue<unknown>[] | (() => unknown),
+  second?: unknown,
+  third?: unknown,
+  fourth?: unknown,
+): MotionValue<unknown> | Record<string, MotionValue<unknown>> {
+  const channel = useValueChannel()
+  // The output-map form derives ONE value per key over a shared input (r11, the pinned fifth
+  // form); every other form derives a single value. Both ride the same handle lifecycle.
+  const isOutputMap =
+    isMotionValue(first) &&
+    Array.isArray(second) &&
+    typeof third === 'object' &&
+    third !== null &&
+    !Array.isArray(third)
+  // Computes ride refs refreshed EVERY render, so re-parameterized ranges/transformers take
+  // effect like the pinned hook (r2 — never silently init-once); the dependency set and (for
+  // the map form) the KEY SET stay fixed at first render (the pinned contract).
+  const computesRef = useRef<Record<string, () => unknown>>({})
+  if (isOutputMap) {
+    const source = first as MotionValue<number>
+    const inputRange = second as readonly number[]
+    const outputMap = third as Record<string, readonly (number | string)[]>
+    const options = (fourth as TransformOptions | undefined) ?? {}
+    for (const [key, outputRange] of Object.entries(outputMap)) {
+      const interpolate = buildInterpolator(inputRange, outputRange, options)
+      computesRef.current[key] = () => interpolate(source.get())
+    }
+  } else {
+    computesRef.current[SINGLE_KEY] = resolveTransformCompute(first, second, third, fourth)
+  }
+  const ref = useRef<Record<string, DerivedHandle> | null>(null)
+  if (ref.current === null) {
+    const handles: Record<string, DerivedHandle> = {}
+    const dependencies = resolveTransformDependencies(first)
+    for (const key of Object.keys(computesRef.current)) {
+      handles[key] = deriveFrom(channel, dependencies, () => computesRef.current[key]!())
+      // Render-phase creation leaves NO live input subscription (r8): an aborted concurrent
+      // render or a discarded StrictMode render must never retain the sources. The initial
+      // value was computed at construction; the commit's attach below resubscribes and resyncs.
+      handles[key].detach()
+    }
+    ref.current = handles
+  } else {
+    // Re-parameterization applies SYNCHRONOUSLY during render like the pinned hook (r4: a
+    // consumer reading during the same render pass must see the new mapping, not wait for a
+    // passive effect). The outputs are non-React stores, so a render-phase resync is legal.
+    for (const handle of Object.values(ref.current)) handle.refresh()
+  }
+  // Subscriptions attach per INSERTION-effect lifetime (r8 — live before any layout effect can
+  // write); a StrictMode replay detaches and RE-attaches the same output values (r3).
+  useInsertionEffect(() => {
+    const handles = Object.values(ref.current!)
+    for (const handle of handles) handle.attach()
+    return () => {
+      for (const handle of handles) handle.detach()
+    }
+  }, [])
+  // The record itself is identity-stable across renders (r12 major b27f0d61ac48 — the pinned
+  // hook's useConstant): consumers hold it in dependency arrays and memo comparisons.
+  const recordRef = useRef<Record<string, MotionValue<unknown>> | null>(null)
+  if (isOutputMap) {
+    if (recordRef.current === null) {
+      const out: Record<string, MotionValue<unknown>> = {}
+      for (const [key, handle] of Object.entries(ref.current)) out[key] = handle.value
+      recordRef.current = out
+    }
+    return recordRef.current
+  }
+  return ref.current[SINGLE_KEY]!.value
+}
+
+// The single-output forms store their one compute/handle under this reserved key.
+const SINGLE_KEY = '__single__'
+
+// The dependency set per pinned form, resolved ONCE at first render.
+function resolveTransformDependencies(
+  first: MotionValue<unknown> | readonly MotionValue<unknown>[] | (() => unknown),
+): readonly MotionValue<unknown>[] {
+  if (typeof first === 'function') return [...collectMotionValueReads(first).reads]
+  if (Array.isArray(first)) return first as readonly MotionValue<unknown>[]
+  return [first as MotionValue<unknown>]
+}
+
+// The compute per pinned form, rebuilt every render from the CURRENT arguments.
+function resolveTransformCompute(
+  first: MotionValue<unknown> | readonly MotionValue<unknown>[] | (() => unknown),
+  second?: unknown,
+  third?: unknown,
+  fourth?: unknown,
+): () => unknown {
+  // Form 4 — reactive compute.
+  if (typeof first === 'function') return first as () => unknown
+  // Form 1 — range mapping.
+  if (isMotionValue(first) && Array.isArray(second)) {
+    const interpolate = buildInterpolator(
+      second as readonly number[],
+      third as readonly (number | string)[],
+      (fourth as TransformOptions | undefined) ?? {},
+    )
+    const source = first as MotionValue<number>
+    return () => interpolate(source.get())
+  }
+  // Form 3 — multi-input function.
+  if (Array.isArray(first)) {
+    const inputs = first as readonly MotionValue<unknown>[]
+    const transformer = second as MultiTransformer<unknown, unknown>
+    return () => transformer(inputs.map((input) => input.get()))
+  }
+  // Form 2 — single-input function.
+  const input = first as MotionValue<unknown>
+  const transformer = second as SingleTransformer<unknown, unknown>
+  return () => transformer(input.get())
+}
+
+function isMotionValue(candidate: unknown): candidate is MotionValue<unknown> {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof (candidate as MotionValue<unknown>).get === 'function' &&
+    typeof (candidate as MotionValue<unknown>).subscribe === 'function' &&
+    typeof (candidate as MotionValue<unknown>).getVelocity === 'function'
+  )
+}
+
+interface DerivedHandle {
+  readonly value: MotionValue<unknown>
+  attach(): void
+  detach(): void
+  refresh(): void
+}
+
+// EVERY derivation rides CORE's derived graph (r5: string/color inputs included — the graph's
+// DerivedSource contract is structural over any MotionValue<T>), so frame-coalesced topological
+// flushing makes ALL diamonds emit one final value (REQ-VALUE-013), and the re-attachable
+// lifecycle (attach/detach/refresh) survives StrictMode replays with pending dirt CANCELLED on
+// detach. No subscription fallback exists — one derivation authority.
+function deriveFrom(
+  channel: ValueChannel,
+  dependencies: readonly MotionValue<unknown>[],
+  compute: () => unknown,
+): DerivedHandle {
+  const value = channel.graph.derived(dependencies, () => compute())
+  return {
+    value,
+    attach: () => value.attachInputs(),
+    detach: () => value.detachInputs(),
+    refresh: () => value.refresh(),
+  }
+}
+
+// ——— useMotionTemplate (REQ-API-025, U5) ———————————————————————————————————————————————————————
+
+// A faithful port of the pinned tagged-template hook (framer-motion/src/value/
+// use-motion-template.ts:28-52 at the §B pin) over the same deriveFrom machinery useTransform
+// rides — exactly as the pin's delegates to useCombineMotionValues (use-combine-values.ts:7-45):
+// the FIRST value computes synchronously at creation, the compute is rebuilt EVERY render so
+// static (non-MotionValue) interpolations read the CURRENT closure (the pin's buildValue), only
+// MotionValue interpolations are dependencies, and attach/detach follows the insertion-effect
+// lifetime (the pinned unsubscribe + cancelFrame cleanup).
+export function useMotionTemplate(
+  fragments: TemplateStringsArray,
+  ...values: Array<MotionValue<unknown> | number | string>
+): MotionValue<string> {
+  const channel = useValueChannel()
+  const buildRef = useRef<() => string>(() => '')
+  buildRef.current = () => {
+    let output = ``
+    for (let i = 0; i < fragments.length; i++) {
+      output += fragments[i]
+      const value = values[i]
+      // The pinned truthiness check verbatim (use-motion-template.ts:43): a falsy static
+      // interpolation (0, '') is OMITTED, not rendered.
+      if (value) output += (isMotionValue(value) ? value.get() : value) as string | number
+    }
+    return output
+  }
+  const ref = useRef<DerivedHandle | null>(null)
+  if (ref.current === null) {
+    // The dependency set is fixed at first render like useTransform's (the pinned contract);
+    // render-phase creation holds NO live input subscription (r8).
+    ref.current = deriveFrom(channel, values.filter(isMotionValue), () => buildRef.current())
+    ref.current.detach()
+  } else {
+    // Re-captured statics apply SYNCHRONOUSLY during render (r4; the pin calls updateValue()
+    // during render) — a same-pass reader sees the new statics, not one commit later.
+    ref.current.refresh()
+  }
+  useInsertionEffect(() => {
+    const handle = ref.current!
+    handle.attach()
+    return () => handle.detach()
+  }, [])
+  return ref.current.value as MotionValue<string>
+}
+
+// ——— useSpring (REQ-API-027) —————————————————————————————————————————————————————————————————
+
+/**
+ * The PUBLIC spring options (r12 major 9d31a6c8f0e2): a standalone type in the pinned public
+ * units — `duration` is SECONDS like motion's SpringOptions, never core's ms-based SpringConfig
+ * (an internal type that must not leak through the public API). `skipInitialAnimation` is the
+ * pinned FollowValueOptions member: the first tracked-source change jumps instead of animating.
+ */
+export interface SpringValueOptions {
+  readonly stiffness?: number
+  readonly damping?: number
+  readonly mass?: number
+  /** Spring duration in SECONDS (the pinned public unit). */
+  readonly duration?: number
+  /** 0 = no bounce, 1 = extremely bouncy (pinned semantics; pairs with `duration`). */
+  readonly bounce?: number
+  /** Perceptual duration in seconds; overrides `duration` when set (pinned semantics). */
+  readonly visualDuration?: number
+  readonly velocity?: number
+  /** Rest threshold on speed, units/sec (pinned member; follow default 0.01). */
+  readonly restSpeed?: number
+  /** Rest threshold on distance-to-target, value units (pinned member; follow default 0.001). */
+  readonly restDelta?: number
+  /** The first change from a tracked source JUMPS instead of animating (pinned member). */
+  readonly skipInitialAnimation?: boolean
+}
+
+const MILLISECONDS_PER_SECOND = 1000
+
+/**
+ * The ONE public→core unit boundary (r12): seconds convert to core's ms here and nowhere else.
+ * `visualDuration` passes through — core's SpringConfig already takes it in seconds.
+ */
+// The pinned follow-path settle defaults (motion-dom follow-value.ts at the SS B pin:
+// `restDelta: 0.001, restSpeed: 0.01, ...options`): applied before the caller's options so an
+// explicit member always wins.
+const FOLLOW_REST_DELTA = 0.001
+const FOLLOW_REST_SPEED = 0.01
+
+export function resolveSpringValueConfig(options: SpringValueOptions): SpringConfig {
+  const config: {
+    stiffness?: number
+    damping?: number
+    mass?: number
+    duration?: number
+    bounce?: number
+    visualDuration?: number
+    velocity?: number
+    restSpeed?: number
+    restDelta?: number
+  } = {}
+  if (options.stiffness !== undefined) config.stiffness = options.stiffness
+  if (options.damping !== undefined) config.damping = options.damping
+  if (options.mass !== undefined) config.mass = options.mass
+  if (options.duration !== undefined) {
+    config.duration = options.duration * MILLISECONDS_PER_SECOND
+  }
+  if (options.bounce !== undefined) config.bounce = options.bounce
+  if (options.visualDuration !== undefined) config.visualDuration = options.visualDuration
+  if (options.velocity !== undefined) config.velocity = options.velocity
+  if (options.restSpeed !== undefined) config.restSpeed = options.restSpeed
+  if (options.restDelta !== undefined) config.restDelta = options.restDelta
+  return config
+}
+
+// The pinned velocity override (r14 major 7 — follow-value.ts spreads `...options` AFTER the
+// sampled velocity, so an explicit `velocity` option replaces the seed's). Carry/zero by
+// resolution type (REQ-SPRING-007) still applies downstream.
+// The follow path's settle defaults ride the PUBLIC options (pinned spread order — defaults
+// first, the caller's members win), keeping resolveSpringValueConfig a pure unit mapping.
+function resolveFollowSpringConfig(options: SpringValueOptions): SpringConfig {
+  return resolveSpringValueConfig({
+    restDelta: FOLLOW_REST_DELTA,
+    restSpeed: FOLLOW_REST_SPEED,
+    ...options,
+  })
+}
+
+function withSeedVelocity(
+  factory: ReturnType<typeof resolveSpringGenerator>,
+  velocity: number | undefined,
+): ReturnType<typeof resolveSpringGenerator> {
+  if (velocity === undefined) return factory
+  return (seed) => factory({ from: seed.from, velocity })
+}
+
+export function useSpring(
+  source: MotionValue<number> | number,
+  options: SpringValueOptions = {},
+): MotionValue<number> {
+  const channel = useValueChannel()
+  // The LATEST options ride a ref (r12 major 19a46e8b3c75): a retarget after a rerender uses
+  // the current config, never the first render's capture.
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const ref = useRef<MotionValue<number> | null>(null)
+  const followerRef = useRef<MotionValue<number> | null>(null)
+  // The LIVE tracked-source unsubscribe (r15 91d5aa6cb730): destroy() must detach it like the
+  // pinned attachFollow teardown — a source outliving a destroyed follower must never animate
+  // the corpse. Written by the attach effect; read by the wrapper's destroy.
+  const sourceDetachRef = useRef<(() => void) | undefined>(undefined)
+  if (ref.current === null) {
+    const initial = isMotionValue(source) ? (source as MotionValue<number>).get() : source
+    const follower = channel.graph.motionValue(initial)
+    followerRef.current = follower
+    const springTo = (target: number): void => {
+      channel.graph.animate(
+        follower,
+        withSeedVelocity(
+          resolveSpringGenerator(target, resolveFollowSpringConfig(optionsRef.current)),
+          optionsRef.current.velocity,
+        ),
+      )
+    }
+    // The returned value IS the follower for reads/subscriptions; `set` retargets the coupling
+    // spring (the pinned useSpring semantic) and `jump` teleports — both delegate every other
+    // behavior to the ONE underlying graph value (no parallel state, REQ-DRIVER-029).
+    ref.current = {
+      get: () => follower.get(),
+      set: springTo,
+      // Core jump owns the pinned order (update -> notify -> stop; r16 major 1) — a wrapper
+      // pre-stop would emit the cancellation BEFORE the change event, reversing the oracle.
+      jump: (value: number) => follower.jump(value),
+      subscribe: (listener) => follower.subscribe(listener),
+      getVelocity: () => follower.getVelocity(),
+      // The two-overload public `on` (r16 major 5): delegate by narrowing the event — the
+      // wrapper adds no shape of its own.
+      on: ((event: MotionValueEvent, listener: (latest: number) => void) =>
+        event === 'change'
+          ? follower.on('change', listener)
+          : follower.on(event, listener as unknown as () => void)) as MotionValue<number>['on'],
+      stop: () => follower.stop(),
+      isAnimating: () => follower.isAnimating(),
+      destroy: () => {
+        // Pinned attachFollow removes the source listener when the follower is destroyed.
+        sourceDetachRef.current?.()
+        sourceDetachRef.current = undefined
+        follower.destroy()
+      },
+    }
+  }
+  // Serialized options as the attach dependency — the PINNED re-parameterization law
+  // (use-follow-value.ts at the §B pin attaches on `[value, JSON.stringify(options)]`): an
+  // options change re-attaches the coupling, which also resets skipInitialAnimation's
+  // first-change tracking exactly like the pinned attachFollow lifetime.
+  const serializedOptions = JSON.stringify(options)
+  useInsertionEffect(() => {
+    const follower = followerRef.current!
+    // Pinned FollowValueOptions.skipInitialAnimation: the FIRST tracked change per attach
+    // lifetime jumps; subsequent changes animate.
+    let sawFirstChange = false
+    const unsubscribe = isMotionValue(source)
+      ? (source as MotionValue<number>).subscribe(() => {
+          const target = (source as MotionValue<number>).get()
+          const skipFirst = optionsRef.current.skipInitialAnimation === true && !sawFirstChange
+          sawFirstChange = true
+          if (skipFirst) {
+            follower.jump(target)
+            return
+          }
+          channel.graph.animate(
+            follower,
+            withSeedVelocity(
+              resolveSpringGenerator(target, resolveFollowSpringConfig(optionsRef.current)),
+              optionsRef.current.velocity,
+            ),
+          )
+        })
+      : undefined
+    sourceDetachRef.current = unsubscribe
+    return () => {
+      // The PINNED attachFollow cleanup shape (r14 major 8): a TRACKED source's cleanup only
+      // removes listeners — an options-change reattach must never freeze a mid-flight
+      // follower (the next source change animates under the new options). The DIRECT form's
+      // cleanup IS stopAnimation in the pin, so an options change stops its in-flight spring.
+      if (unsubscribe !== undefined) unsubscribe()
+      else follower.stop()
+      if (sourceDetachRef.current === unsubscribe) sourceDetachRef.current = undefined
+    }
+    // Coupling identity is fixed per (channel, options) attach lifetime; `source` identity is
+    // fixed at first render like the pinned hook's `value`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [serializedOptions])
+  useInsertionEffect(() => {
+    const follower = followerRef.current!
+    return () => {
+      // UNMOUNT stops the coupling spring for BOTH forms — the r2 major 58aa03d1a law: a
+      // source outliving its consumer must not keep animating orphaned work in the shared
+      // graph. (Options-change reattaches above deliberately do not pass through here.)
+      follower.stop()
+    }
+  }, [])
+  return ref.current
+}
+
+// ——— useVelocity (REQ-API-027) ———————————————————————————————————————————————————————————————
+
+export function useVelocity(source: MotionValue<number>): MotionValue<number> {
+  const channel = useValueChannel()
+  const explicitPort = useContext(ValueHooksIdentityChannelContext)
+  // The identity-channel cache port resolves ONCE at first render (the pinned dependency-fixing
+  // contract): an explicit provider wins (test-only); the canonical channel registration is the
+  // production seam. Without either, the source is an ordinary graph value and the legacy
+  // core-graph observation below applies — cache-only observation needs no fallback crossing.
+  const resolutionRef = useRef<ValueHooksIdentityChannelResolution | null>(null)
+  if (
+    resolutionRef.current === null &&
+    (explicitPort !== null || canonicalIdentityPorts.has(channel))
+  ) {
+    resolutionRef.current = resolveValueHooksIdentityChannelPort(channel, explicitPort)
+  }
+  const resolution = resolutionRef.current
+  const ref = useRef<MotionValue<number> | null>(null)
+  // Seed from the CURRENT source velocity (r12 major 5ce847a2d913, the pinned hook's
+  // `useMotionValue(value.getVelocity())`): mounting against an already-moving source must not
+  // report a phantom zero until the next change arrives. The identity channel reads the
+  // TRANSPORTED CACHE (zero synchronous UI crossings, Decision 13) — never source.getVelocity().
+  if (ref.current === null) {
+    ref.current = channel.graph.motionValue(
+      resolution === null
+        ? source.getVelocity()
+        : resolution.port.readTransportedCachedVelocity(source, resolution.port.now()),
+    )
+  }
+  const out = ref.current
+  useInsertionEffect(() => {
+    if (resolution !== null) {
+      const port = resolution.port
+      // Cache-only observer cadence: observer frames re-read the transported cache — never a
+      // synchronous source read, never a wall-clock timer, never an animationComplete
+      // subscription (a completion has no cache authority; staleness decay is the only zero).
+      let cancelFrame: (() => void) | null = null
+      const arm = (): void => {
+        if (cancelFrame !== null) return
+        cancelFrame = port.requestObserverFrame((atTimestampMs) => {
+          cancelFrame = null
+          const cached = port.readTransportedCachedVelocity(source, atTimestampMs)
+          out.set(cached)
+          if (cached !== 0) arm()
+        })
+      }
+      const unsubscribe = port.subscribeTransportedChange(source, () => {
+        const cached = port.readTransportedCachedVelocity(source, port.now())
+        out.set(cached)
+        if (cached !== 0) arm()
+      })
+      // Arm only while nonzero: a zero cache needs no decay re-reads.
+      if (out.get() !== 0) arm()
+      return () => {
+        if (cancelFrame !== null) cancelFrame()
+        unsubscribe()
+      }
+    }
+    // A manual sample goes stale silently — change events stop arriving, so a nonzero velocity
+    // would otherwise persist forever (review r1 major 5). Each sample arms ONE bounded trailing
+    // re-read past core's staleness window; getVelocity() itself reports the decay to zero.
+    let trailing: ReturnType<typeof setTimeout> | null = null
+    const sample = (): void => {
+      out.set(source.getVelocity())
+      if (trailing !== null) clearTimeout(trailing)
+      trailing = setTimeout(() => {
+        trailing = null
+        const decayed = source.getVelocity()
+        out.set(decayed)
+        channel.kick()
+      }, VELOCITY_DECAY_RESAMPLE_MS)
+    }
+    const unsubscribeChange = source.subscribe(sample)
+    // Core's rest law: an animation ending puts the value at rest — mirror the zero explicitly.
+    const unsubscribeComplete = source.on('animationComplete', () => out.set(0))
+    return () => {
+      if (trailing !== null) clearTimeout(trailing)
+      unsubscribeChange()
+      unsubscribeComplete()
+    }
+  }, [source, out, channel, resolution])
+  return out
+}
+
+// Just past core's MAX_VELOCITY_DELTA_MS staleness window, so the re-read observes the decay.
+const VELOCITY_DECAY_RESAMPLE_MS = 60