@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/imperativeAnimate.ts

@@ -0,0 +1,816 @@
+// REQ-API-039 — native imperative surface: standalone animate() + the controls contract the
+// catalog rows exercise (headless number/color, MotionValue, reverse via time/speed). Transitions
+// capture through the R8 prepared seam (prepareDriverCommand); the value channel drives samples —
+// no parallel imperative engine.
+
+import {
+  describeValue,
+  isColor,
+  mixColor,
+  parseColor,
+  timingGenerator,
+  toTimingConfig,
+  transformColor,
+  type MotionValue,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+import { prepareDriverCommand } from '@unrulysystems/native-motion-core/internal-driver'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import { resolveDefaultValueChannel } from './valueHooks'
+import type { ValueChannel } from './valueChannel'
+
+export const ANIMATE_OWNER = 'animate' as const
+export const USE_ANIMATE_OWNER = 'useAnimate' as const
+
+/** Public playback controls surface (catalog-exercised members) — SHALLOW, pin-aligned. */
+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 AnimationPlaybackControlsWithThen = AnimationPlaybackControls
+
+/**
+ * Shared shallow public callable (REQ-API-039). Named AnimateFn to match the web entry so
+ * dual-entry type-identity probes never expand pin overload surfaces.
+ */
+export type AnimateFn = (
+  subject: unknown,
+  keyframes?: unknown,
+  transition?: unknown,
+) => AnimationPlaybackControls
+
+export interface AnimationScope<T = unknown> {
+  current: T | null
+  animations: AnimationPlaybackControls[]
+}
+
+export interface ImperativeAnimateGate {
+  readonly severity: 'development' | 'production'
+  readonly report: (error: Error) => void
+  readonly owner: typeof ANIMATE_OWNER | typeof USE_ANIMATE_OWNER
+}
+
+export interface CreateScopedAnimateOptions {
+  readonly scope?: AnimationScope
+  readonly channel?: ValueChannel
+  readonly gate?: ImperativeAnimateGate
+  /** When true (MotionConfig.skipAnimations), commands jump to the end. */
+  readonly skipAnimations?: boolean
+}
+
+type ValueOptions = {
+  readonly duration?: number
+  readonly ease?: Transition['ease']
+  readonly type?: Transition['type']
+  readonly onUpdate?: (latest: number | string) => void
+  readonly onComplete?: () => void
+}
+
+function refuse(gate: ImperativeAnimateGate, message: string): never {
+  const error = new Error(message)
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+  // Production refuse: return a inert controls shell so call sites that ignore still
+  // cannot schedule work (caller must not assume throw). Unreachable for typed never after
+  // throw in development; production falls through to throw so createRoot/act still observe.
+  throw error
+}
+
+function isMotionValue(candidate: unknown): candidate is MotionValue<number> {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof (candidate as MotionValue<number>).get === 'function' &&
+    typeof (candidate as MotionValue<number>).set === 'function' &&
+    typeof (candidate as MotionValue<number>).getVelocity === 'function'
+  )
+}
+
+function isSequence(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value) && value.some((segment) => Array.isArray(segment))
+}
+
+/** Capture the transition through the SAME prepared seam as declarative props (R8 / REQ-DRIVER-030). */
+export function prepareImperativeTransition(
+  options: ValueOptions | undefined,
+  gate: ImperativeAnimateGate,
+  from: number,
+  to: number,
+): { readonly durationMs: number; readonly transition: Transition } {
+  const durationSec = options?.duration ?? 0.3
+  if (typeof durationSec !== 'number' || !Number.isFinite(durationSec) || durationSec < 0) {
+    refuse(
+      gate,
+      `${gate.owner}: invalid duration = ${describeValue(options?.duration)} — expected a non-negative number of seconds (REQ-API-039).`,
+    )
+  }
+  // U7a: the authored instant lane (`type: false`) ships on the DECLARATIVE property lane only.
+  // NumericPlayback is duration-based (time/speed seek) and commits a zero-duration run
+  // SYNCHRONOUSLY at construction — not the pin's next-frame commit (motion-dom
+  // motion-value.ts:122-136) — so `type: false` refuses loud here (demand-gated divergence)
+  // rather than collapsing into a tween, which is what the type normalizer below would do with it.
+  if (options?.type === false) {
+    refuse(
+      gate,
+      `${gate.owner}: type: false (the authored instant lane) is not executable by the imperative ` +
+        'playback lane — its controls are duration-based and would commit synchronously, not on ' +
+        'the next frame (U7a / G-INV-8). Use the declarative transition prop for the instant lane.',
+    )
+  }
+  // U7b scoping note (review minor): the GLOBAL instant window (useInstantTransition) is likewise
+  // not consulted on this lane — an imperative start inside the window runs full-duration. The
+  // pin's flag is global, so if that class is ever demanded here it must REFUSE loud like the
+  // arm above, never silently ignore.
+  // exactOptionalPropertyTypes: only include ease when present; type is required.
+  const authored: Transition =
+    options?.ease !== undefined
+      ? {
+          type: options.type === 'spring' ? 'spring' : 'tween',
+          duration: durationSec,
+          ease: options.ease as NonNullable<Transition['ease']>,
+        }
+      : {
+          type: options?.type === 'spring' ? 'spring' : 'tween',
+          duration: durationSec,
+        }
+  // Prepared seam: a hostile or unknown option is refused by capture/validate, never reaches a backend.
+  try {
+    const prepared = prepareDriverCommand({
+      kind: 'start',
+      targets: { value: { to, from } },
+      transition: authored,
+    })
+    if (prepared.kind !== 'start') {
+      refuse(gate, `${gate.owner}: prepared seam returned a non-start command (REQ-API-039).`)
+    }
+    const prop = prepared.targets['value']
+    if (prop === undefined) {
+      refuse(gate, `${gate.owner}: prepared seam dropped the value target (REQ-API-039).`)
+    }
+    const timing = toTimingConfig(prop.transition as Transition)
+    return {
+      durationMs: timing.duration ?? durationSec * 1000,
+      transition: prop.transition as Transition,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    refuse(gate, `${gate.owner}: ${message}`)
+  }
+}
+
+function resolvedEase(transition: Transition): NonNullable<Transition['ease']> | undefined {
+  return transition.ease
+}
+
+/**
+ * Playback controls with time/speed (catalog reverse: time = duration; speed = -1).
+ * Samples through the value channel via graph.animate; seek/reverse restart from the prepared
+ * transition snapshot — never a second raw transition path.
+ */
+class NumericPlayback implements AnimationPlaybackControlsWithThen {
+  #timeSec = 0
+  #speed = 1
+  #playing = true
+  #finished = false
+  #handle: { stop: () => void } | null = null
+  #detachComplete: (() => void) | null = null
+  #detachChange: (() => void) | null = null
+  #settle!: () => void
+  readonly finished: Promise<void>
+  readonly #durationSec: number
+  readonly #from: number
+  readonly #to: number
+  readonly #value: MotionValue<number>
+  readonly #channel: ValueChannel
+  readonly #durationMs: number
+  readonly #transition: Transition
+  readonly #onUpdate: ((latest: number) => void) | undefined
+  readonly #onComplete: (() => void) | undefined
+  readonly #onSample: ((latest: number) => void) | undefined
+
+  constructor(args: {
+    readonly channel: ValueChannel
+    readonly value: MotionValue<number>
+    readonly from: number
+    readonly to: number
+    readonly durationMs: number
+    readonly transition: Transition
+    readonly onUpdate?: (latest: number) => void
+    readonly onComplete?: () => void
+    readonly onSample?: (latest: number) => void
+    readonly skipAnimations?: boolean
+  }) {
+    this.#channel = args.channel
+    this.#value = args.value
+    this.#from = args.from
+    this.#to = args.to
+    this.#durationMs = args.durationMs
+    this.#durationSec = args.durationMs / 1000
+    this.#transition = args.transition
+    this.#onUpdate = args.onUpdate
+    this.#onComplete = args.onComplete
+    this.#onSample = args.onSample
+    this.finished = new Promise<void>((resolve) => {
+      this.#settle = resolve
+    })
+    if (args.skipAnimations || args.durationMs <= 0) {
+      this.#applyTimeProgress(1)
+      this.#markDone()
+      return
+    }
+    this.#restartFromProgress(0)
+  }
+
+  get time(): number {
+    return this.#timeSec
+  }
+
+  set time(next: number) {
+    if (this.#finished) return
+    const clamped = Math.max(0, Math.min(this.#durationSec, next))
+    this.#timeSec = clamped
+    const progress = this.#durationSec === 0 ? 1 : clamped / this.#durationSec
+    this.#applyTimeProgress(progress)
+    if (this.#playing) this.#restartFromProgress(progress)
+  }
+
+  get speed(): number {
+    return this.#speed
+  }
+
+  set speed(next: number) {
+    if (this.#finished) return
+    this.#speed = next
+    // Catalog reverse: seek to duration (may idle at endpoint) then set speed = -1 — resume
+    // from the current time even if the prior leg had no remaining travel.
+    this.#playing = true
+    const progress = this.#durationSec === 0 ? 1 : this.#timeSec / this.#durationSec
+    this.#restartFromProgress(progress)
+  }
+
+  get duration(): number {
+    return this.#durationSec
+  }
+
+  play = (): void => {
+    if (this.#finished) return
+    this.#playing = true
+    const progress = this.#durationSec === 0 ? 1 : this.#timeSec / this.#durationSec
+    this.#restartFromProgress(progress)
+  }
+
+  pause = (): void => {
+    if (this.#finished) return
+    this.#playing = false
+    this.#stopHandle()
+  }
+
+  stop = (): void => {
+    this.#stopHandle()
+    this.#playing = false
+    this.#markDone()
+  }
+
+  cancel = (): void => {
+    this.#stopHandle()
+    this.#applyTimeProgress(0)
+    this.#timeSec = 0
+    this.#playing = false
+    this.#markDone()
+  }
+
+  complete = (): void => {
+    this.#stopHandle()
+    this.#applyTimeProgress(1)
+    this.#timeSec = this.#durationSec
+    this.#markDone()
+  }
+
+  // Pin AnimationPlaybackControlsWithThen: controls are thenable (await animation).
+  // oxlint-disable-next-line unicorn/no-thenable -- pin thenable contract (REQ-API-039)
+  then(onResolve: () => void, onReject?: () => void): Promise<void> {
+    return this.finished.then(onResolve, onReject)
+  }
+
+  #sampleAtProgress(progress: number): number {
+    const p = Math.max(0, Math.min(1, progress))
+    const ease = resolvedEase(this.#transition)
+    const timing =
+      ease !== undefined && !Array.isArray(ease)
+        ? { duration: this.#durationMs, ease: ease as never }
+        : { duration: this.#durationMs, ease: 'linear' as const }
+    const gen = timingGenerator(this.#to, timing)({ from: this.#from, velocity: 0 })
+    return gen.sample(p * this.#durationMs).value
+  }
+
+  #applyTimeProgress(progress: number): void {
+    const value = this.#sampleAtProgress(progress)
+    this.#value.jump(value)
+    this.#onUpdate?.(value)
+    this.#onSample?.(value)
+  }
+
+  #markDone(): void {
+    if (this.#finished) return
+    this.#finished = true
+    this.#playing = false
+    this.#stopHandle()
+    this.#onComplete?.()
+    this.#settle()
+  }
+
+  #stopHandle(): void {
+    this.#detachComplete?.()
+    this.#detachComplete = null
+    this.#detachChange?.()
+    this.#detachChange = null
+    this.#handle?.stop()
+    this.#handle = null
+  }
+
+  #restartFromProgress(progress: number): void {
+    this.#stopHandle()
+    if (this.#speed === 0) return
+    const forward = this.#speed > 0
+    const remainingProgress = forward ? 1 - progress : progress
+    if (remainingProgress <= 1e-9) {
+      // Catalog reverse seeks to duration THEN sets speed = -1. Sitting at an endpoint with
+      // no remaining travel must NOT settle finished — only natural completion / stop / complete.
+      this.#applyTimeProgress(forward ? 1 : 0)
+      this.#timeSec = forward ? this.#durationSec : 0
+      return
+    }
+    this.#playing = true
+    const legFrom = this.#sampleAtProgress(progress)
+    const legTo = forward ? this.#to : this.#from
+    const legDurationMs = (remainingProgress * this.#durationMs) / Math.abs(this.#speed)
+    this.#startLeg(legFrom, legTo, legDurationMs, forward)
+  }
+
+  #startLeg(from: number, to: number, durationMs: number, forward: boolean): void {
+    this.#value.jump(from)
+    // Linear leg between the current visual value and the endpoint — reverse/seek always
+    // restarts a prepared-duration fraction; the full-run ease was applied in #applyTimeProgress.
+    const factory = timingGenerator(to, { duration: durationMs, ease: 'linear' })
+    const startTimeSec = this.#timeSec
+    this.#handle = this.#channel.graph.animate(this.#value, (seed) =>
+      factory({ from: seed.from, velocity: 0 }),
+    )
+    this.#detachChange = this.#value.on('change', (latest: number) => {
+      this.#onUpdate?.(latest)
+      this.#onSample?.(latest)
+      // Map visual progress of this leg back onto overall time.
+      const span = to - from
+      const legP = Math.abs(span) < 1e-12 ? 1 : (latest - from) / span
+      const clampedLeg = Math.max(0, Math.min(1, legP))
+      this.#timeSec = forward
+        ? startTimeSec + clampedLeg * (this.#durationSec - startTimeSec)
+        : startTimeSec - clampedLeg * startTimeSec
+    })
+    this.#detachComplete = this.#value.on('animationComplete', () => {
+      this.#timeSec = forward ? this.#durationSec : 0
+      this.#applyTimeProgress(forward ? 1 : 0)
+      this.#markDone()
+    })
+  }
+}
+
+function animateNumeric(
+  channel: ValueChannel,
+  value: MotionValue<number>,
+  to: number,
+  options: ValueOptions | undefined,
+  gate: ImperativeAnimateGate,
+  skipAnimations: boolean,
+  onSample?: (latest: number) => void,
+): AnimationPlaybackControlsWithThen {
+  const from = value.get()
+  if (typeof from !== 'number' || typeof to !== 'number') {
+    refuse(
+      gate,
+      `${gate.owner}: numeric animate requires number endpoints — got from=${describeValue(from)} to=${describeValue(to)} (REQ-API-039).`,
+    )
+  }
+  const prepared = prepareImperativeTransition(options, gate, from, to)
+  return new NumericPlayback({
+    channel,
+    value,
+    from,
+    to,
+    durationMs: prepared.durationMs,
+    transition: prepared.transition,
+    ...(typeof options?.onUpdate === 'function'
+      ? { onUpdate: options.onUpdate as (latest: number) => void }
+      : {}),
+    ...(typeof options?.onComplete === 'function' ? { onComplete: options.onComplete } : {}),
+    ...(onSample !== undefined ? { onSample } : {}),
+    skipAnimations,
+  })
+}
+
+function animateHeadlessNumber(
+  channel: ValueChannel,
+  from: number,
+  to: number,
+  options: ValueOptions | undefined,
+  gate: ImperativeAnimateGate,
+  skipAnimations: boolean,
+): AnimationPlaybackControlsWithThen {
+  const value = channel.graph.motionValue(from)
+  return animateNumeric(channel, value, to, options, gate, skipAnimations)
+}
+
+function animateHeadlessColor(
+  channel: ValueChannel,
+  fromRaw: string,
+  toRaw: string,
+  options: ValueOptions | undefined,
+  gate: ImperativeAnimateGate,
+  skipAnimations: boolean,
+): AnimationPlaybackControlsWithThen {
+  if (!isColor(fromRaw) || !isColor(toRaw)) {
+    refuse(
+      gate,
+      `${gate.owner}: color animate requires parseable color strings — got from=${describeValue(fromRaw)} to=${describeValue(toRaw)} (REQ-API-039).`,
+    )
+  }
+  const fromColor = parseColor(fromRaw)
+  const toColor = parseColor(toRaw)
+  const progress = channel.graph.motionValue(0)
+  const onUpdate = options?.onUpdate
+  return animateNumeric(
+    channel,
+    progress,
+    1,
+    {
+      ...options,
+      onUpdate: (p) => {
+        if (typeof p !== 'number') return
+        const mixed = transformColor(mixColor(fromColor, toColor, p))
+        onUpdate?.(mixed)
+      },
+    },
+    gate,
+    skipAnimations,
+  )
+}
+
+function isDomElement(value: unknown): value is Element {
+  return typeof Element !== 'undefined' && value instanceof Element
+}
+
+function resolveSelectorSubjects(selector: string, scope: AnimationScope | undefined): Element[] {
+  const root =
+    scope?.current !== null && scope?.current !== undefined && isDomElement(scope.current)
+      ? scope.current
+      : typeof document !== 'undefined'
+        ? document
+        : null
+  if (root === null || typeof (root as ParentNode).querySelectorAll !== 'function') return []
+  return Array.from((root as ParentNode).querySelectorAll(selector))
+}
+
+function readElementNumber(el: Element, key: string): number {
+  if (!(el instanceof HTMLElement)) return 0
+  if (key === 'opacity') {
+    const o = el.style.opacity
+    return o === '' ? 1 : Number(o)
+  }
+  if (key === 'x' || key === 'y' || key === 'scale') {
+    // Best-effort parse from transform translate/scale for catalog reverse/initial-transform.
+    const transform = el.style.transform || ''
+    if (key === 'x') {
+      const m = /translate(?:3d|X)?\(\s*([-\d.]+)/.exec(transform)
+      return m ? Number(m[1]) : 0
+    }
+    if (key === 'y') {
+      const m = /translate(?:3d)?\(\s*[^,]+,\s*([-\d.]+)/.exec(transform)
+      return m ? Number(m[1]) : 0
+    }
+    if (key === 'scale') {
+      const m = /scale\(([^)]+)\)/.exec(transform)
+      if (!m) {
+        // Catalog initial-transform starts from style.transform scale(0.1)
+        return 1
+      }
+      return Number(m[1])
+    }
+  }
+  return 0
+}
+
+function writeElementNumber(
+  el: Element,
+  key: string,
+  value: number,
+  state: ElementStyleState,
+): void {
+  if (!(el instanceof HTMLElement)) return
+  if (key === 'opacity') {
+    el.style.opacity = String(value)
+    return
+  }
+  if (key === 'x') state.x = value
+  else if (key === 'y') state.y = value
+  else if (key === 'scale') state.scale = value
+  el.style.transform = `translate(${state.x}px, ${state.y}px) scale(${state.scale})`
+}
+
+interface ElementStyleState {
+  x: number
+  y: number
+  scale: number
+}
+
+function animateElementProps(
+  channel: ValueChannel,
+  elements: readonly Element[],
+  keyframes: Record<string, number>,
+  options: ValueOptions | undefined,
+  gate: ImperativeAnimateGate,
+  skipAnimations: boolean,
+): AnimationPlaybackControlsWithThen[] {
+  const controls: AnimationPlaybackControlsWithThen[] = []
+  for (const el of elements) {
+    const state: ElementStyleState = {
+      x: readElementNumber(el, 'x'),
+      y: readElementNumber(el, 'y'),
+      scale: readElementNumber(el, 'scale'),
+    }
+    // Preserve catalog initial scale from CSS when present.
+    const cssTransform = el instanceof HTMLElement ? el.style.transform : ''
+    const scaleMatch = /scale\(([^)]+)\)/.exec(cssTransform)
+    if (scaleMatch) state.scale = Number(scaleMatch[1])
+
+    for (const [key, to] of Object.entries(keyframes)) {
+      if (typeof to !== 'number') {
+        refuse(
+          gate,
+          `${gate.owner}: element keyframe '${key}' must be a number this rung — got ${describeValue(to)} (REQ-API-039).`,
+        )
+      }
+      const from = key === 'scale' && scaleMatch ? state.scale : readElementNumber(el, key)
+      const mv = channel.graph.motionValue(from)
+      controls.push(
+        animateNumeric(channel, mv, to, options, gate, skipAnimations, (latest) => {
+          writeElementNumber(el, key, latest, state)
+        }),
+      )
+    }
+  }
+  return controls
+}
+
+class GroupPlayback implements AnimationPlaybackControlsWithThen {
+  readonly #items: AnimationPlaybackControlsWithThen[]
+  readonly finished: Promise<void>
+
+  constructor(items: AnimationPlaybackControlsWithThen[]) {
+    this.#items = items
+    this.finished = Promise.all(items.map((item) => item.finished)).then(() => undefined)
+  }
+
+  get time(): number {
+    return this.#items[0]?.time ?? 0
+  }
+
+  set time(next: number) {
+    for (const item of this.#items) item.time = next
+  }
+
+  get speed(): number {
+    return this.#items[0]?.speed ?? 1
+  }
+
+  set speed(next: number) {
+    for (const item of this.#items) item.speed = next
+  }
+
+  get duration(): number {
+    return this.#items.reduce((max, item) => Math.max(max, item.duration), 0)
+  }
+
+  play = (): void => {
+    for (const item of this.#items) item.play()
+  }
+
+  pause = (): void => {
+    for (const item of this.#items) item.pause()
+  }
+
+  stop = (): void => {
+    for (const item of this.#items) item.stop()
+  }
+
+  cancel = (): void => {
+    for (const item of this.#items) item.cancel()
+  }
+
+  complete = (): void => {
+    for (const item of this.#items) item.complete()
+  }
+
+  // oxlint-disable-next-line unicorn/no-thenable -- pin thenable contract (REQ-API-039)
+  then(onResolve: () => void, onReject?: () => void): Promise<void> {
+    return this.finished.then(onResolve, onReject)
+  }
+}
+
+function animateSequence(
+  channel: ValueChannel,
+  sequence: readonly unknown[],
+  gate: ImperativeAnimateGate,
+  scope: AnimationScope | undefined,
+  skipAnimations: boolean,
+): AnimationPlaybackControlsWithThen {
+  const controls: AnimationPlaybackControlsWithThen[] = []
+  for (const segment of sequence) {
+    // Label-only segment (timeline marker) — pin ignores for playback payload.
+    if (typeof segment === 'string') continue
+    if (!Array.isArray(segment) || segment.length < 2) {
+      refuse(
+        gate,
+        `${gate.owner}: sequence segment must be [subject, keyframes, options?] — got ${describeValue(segment)} (REQ-API-039).`,
+      )
+    }
+    const subject = segment[0]
+    const keyframes = segment[1]
+    const options = (segment[2] ?? undefined) as ValueOptions | undefined
+    if (typeof subject === 'string') {
+      const elements = resolveSelectorSubjects(subject, scope)
+      if (elements.length === 0) {
+        refuse(
+          gate,
+          `${gate.owner}: selector ${describeValue(subject)} resolved to no elements in scope (REQ-API-039).`,
+        )
+      }
+      if (typeof keyframes !== 'object' || keyframes === null || Array.isArray(keyframes)) {
+        refuse(
+          gate,
+          `${gate.owner}: element keyframes must be a plain object — got ${describeValue(keyframes)} (REQ-API-039).`,
+        )
+      }
+      controls.push(
+        ...animateElementProps(
+          channel,
+          elements,
+          keyframes as Record<string, number>,
+          options,
+          gate,
+          skipAnimations,
+        ),
+      )
+      continue
+    }
+    if (isMotionValue(subject) && typeof keyframes === 'number') {
+      controls.push(animateNumeric(channel, subject, keyframes, options, gate, skipAnimations))
+      continue
+    }
+    refuse(
+      gate,
+      `${gate.owner}: unsupported sequence subject ${describeValue(subject)} (REQ-API-039).`,
+    )
+  }
+  if (controls.length === 0) {
+    // Empty sequence (labels only): already-finished controls.
+    const empty = new NumericPlayback({
+      channel,
+      value: channel.graph.motionValue(0),
+      from: 0,
+      to: 0,
+      durationMs: 0,
+      transition: { type: 'tween', duration: 0 },
+      skipAnimations: true,
+    })
+    return empty
+  }
+  return controls.length === 1 ? controls[0]! : new GroupPlayback(controls)
+}
+
+function trackOnScope(
+  scope: AnimationScope | undefined,
+  controls: AnimationPlaybackControlsWithThen,
+): AnimationPlaybackControlsWithThen {
+  if (scope === undefined) return controls
+  scope.animations.push(controls)
+  void controls.finished.then(() => {
+    const index = scope.animations.indexOf(controls)
+    if (index >= 0) scope.animations.splice(index, 1)
+    return undefined
+  })
+  return controls
+}
+
+/** Explicit callable shape — keep inference shallow so typecheck does not expand the body. */
+export type ScopedAnimateFn = AnimateFn
+
+export function createScopedAnimate(options: CreateScopedAnimateOptions = {}): AnimateFn {
+  const scope = options.scope
+  // Channel is resolved per call so standalone animate always joins the same lazy app-default
+  // graph as useMotionValue. Scoped hooks pass their provider channel explicitly.
+  const fixedChannel = options.channel
+  const gate: ImperativeAnimateGate = options.gate ?? {
+    severity: ambientNativeSeverity(),
+    report: consoleReporter,
+    owner: scope !== undefined ? USE_ANIMATE_OWNER : ANIMATE_OWNER,
+  }
+  const skipAnimations = options.skipAnimations === true
+
+  function resolveChannel(): ValueChannel {
+    return fixedChannel ?? resolveDefaultValueChannel()
+  }
+
+  const scopedAnimate: AnimateFn = (subjectOrSequence, keyframesOrOptions?, maybeOptions?) => {
+    const channel = resolveChannel()
+    if (isSequence(subjectOrSequence)) {
+      return trackOnScope(
+        scope,
+        animateSequence(channel, subjectOrSequence, gate, scope, skipAnimations),
+      )
+    }
+
+    // animate(number, number, options?)
+    if (typeof subjectOrSequence === 'number' && typeof keyframesOrOptions === 'number') {
+      return trackOnScope(
+        scope,
+        animateHeadlessNumber(
+          channel,
+          subjectOrSequence,
+          keyframesOrOptions,
+          maybeOptions as ValueOptions | undefined,
+          gate,
+          skipAnimations,
+        ),
+      )
+    }
+
+    // animate(colorString, colorString, options?)
+    if (typeof subjectOrSequence === 'string' && typeof keyframesOrOptions === 'string') {
+      return trackOnScope(
+        scope,
+        animateHeadlessColor(
+          channel,
+          subjectOrSequence,
+          keyframesOrOptions,
+          maybeOptions as ValueOptions | undefined,
+          gate,
+          skipAnimations,
+        ),
+      )
+    }
+
+    // animate(MotionValue, number, options?)
+    if (isMotionValue(subjectOrSequence) && typeof keyframesOrOptions === 'number') {
+      return trackOnScope(
+        scope,
+        animateNumeric(
+          channel,
+          subjectOrSequence,
+          keyframesOrOptions,
+          maybeOptions as ValueOptions | undefined,
+          gate,
+          skipAnimations,
+        ),
+      )
+    }
+
+    // animate(selector, keyframes, options?) with scope
+    if (typeof subjectOrSequence === 'string' && typeof keyframesOrOptions === 'object') {
+      const elements = resolveSelectorSubjects(subjectOrSequence, scope)
+      if (elements.length === 0) {
+        refuse(
+          gate,
+          `${gate.owner}: selector ${describeValue(subjectOrSequence)} resolved to no elements in scope (REQ-API-039).`,
+        )
+      }
+      const group = animateElementProps(
+        channel,
+        elements,
+        keyframesOrOptions as Record<string, number>,
+        maybeOptions as ValueOptions | undefined,
+        gate,
+        skipAnimations,
+      )
+      const controls = group.length === 1 ? group[0]! : new GroupPlayback(group)
+      return trackOnScope(scope, controls)
+    }
+
+    refuse(
+      gate,
+      `${gate.owner}: unsupported subject ${describeValue(subjectOrSequence)} — catalog shapes are headless number/color, MotionValue, selector+keyframes, or a sequence (REQ-API-039).`,
+    )
+  }
+
+  return scopedAnimate
+}
+
+export const animate: AnimateFn = createScopedAnimate()