@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/driver/uiLayoutGraph.ts

@@ -0,0 +1,338 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// The production UI-runtime graph adapter for the layout-identity engine
+// (specs/LAYOUT-UITHREAD-PORT-BUILD-PACKET.md §The UI-runtime graph adapter). The registry/session
+// need a MotionGraph host for their rect channels + crossfade scalar; the class-based core graph
+// must not cross onto the UI runtime (spike Residual Segfault Risks), so this plain-object graph
+// is constructed and stepped entirely UI-side by the driver's frame loop. RN-free on purpose: the
+// 'worklet' directives are inert on the JS thread, so vitest exercises the SAME functions the UI
+// runtime executes. Function-level directives are babel-workletized per-function in app source
+// (the motion/colorProjection.ts precedent, device-proven).
+
+import {
+  DT_CLAMP_MS,
+  MAX_VELOCITY_DELTA_MS,
+  type ActivityHandle,
+  type Animation,
+  type Generator,
+  type GeneratorFactory,
+  type MotionGraph,
+  type MotionValue,
+  type MotionValueEvent,
+  type ValueChangeListener,
+} from '@unrulysystems/native-motion-core/worklet-layout'
+
+interface UiLayoutAnimation extends Animation {
+  done: boolean
+  /**
+   * Ledger/ownership teardown with or without the end-of-animation velocity cleanup (r19):
+   * interruption carries velocity into the successor seed, so it finishes WITHOUT cleanup;
+   * a direct stop() cleans up (r17).
+   */
+  __finish(runEndCleanup: boolean): void
+}
+
+interface UiLayoutMotionValue extends MotionValue<number> {
+  __active: UiLayoutAnimation | null
+  __applyAnimationSample(value: number, velocity: number): void
+  __endAnimation(): void
+  /** Fire a lifecycle event on this value (r15 e18b6f40a2d7 — the union is EMITTED, not just accepted). */
+  __emit(event: 'animationStart' | 'animationComplete' | 'animationCancel' | 'destroy'): void
+}
+
+interface UiLayoutActiveAnimation {
+  readonly value: UiLayoutMotionValue
+  readonly generator: Generator
+  readonly handle: UiLayoutAnimation
+  elapsedMs: number
+}
+
+// The graph surface the layout engine steps: core's MotionGraph plus the driver-owned frame
+// advance (the driver's useFrameCallback calls frame(dt); there is no scheduler in this graph by
+// design — REQ-DRIVER-011 keeps the frame source singular and driver-owned).
+export interface UiLayoutGraph extends MotionGraph {
+  frame(dtMs: number): void
+}
+
+// alloc-ok: construction — one motion value per projection channel, created at pairing time;
+// the per-frame writers (__applyAnimationSample/set) run indexed with zero allocation.
+function createUiLayoutMotionValue(initial: number, now: () => number): UiLayoutMotionValue {
+  'worklet'
+  let value = initial
+  // Core MotionValueImpl's EXACT sample-window model (r20 26d0a09db7f4 — a manual-write
+  // timestamp alone missed same-frame compounding, identical-write suppression, and the
+  // clock velocity of listener writes): the animated velocity takes precedence while a
+  // flight drives the value; manual writes roll the frame window only when time moved.
+  let animatedVelocity: number | null = null
+  let prev: number | null = null
+  let prevUpdatedAtMs: number | null = null
+  let updatedAtMs = now()
+  const listeners: Array<ValueChangeListener<number>> = []
+  // 'change' listeners take the latest value (the pinned payload); lifecycle listeners take
+  // none — one storage shape, lifecycle emission casts to the payload-free call.
+  const eventListeners: Record<MotionValueEvent, Array<(latest: number) => void>> = {
+    change: [],
+    animationStart: [],
+    animationComplete: [],
+    animationCancel: [],
+    destroy: [],
+  }
+  const mv: UiLayoutMotionValue = {
+    __active: null,
+    __applyAnimationSample(next, nextVelocity) {
+      value = next
+      animatedVelocity = nextVelocity
+      // Indexed: this runs per animation per vsync — for..of allocates its iterator on Hermes.
+      for (let i = 0; i < listeners.length; i++) listeners[i]!(value)
+      for (let i = 0; i < eventListeners.change.length; i++) eventListeners.change[i]!(value)
+    },
+    __endAnimation() {
+      // Core MotionValueImpl.endAnimation() verbatim (r20): clears the animated velocity AND
+      // resets the clock window — the registry's EPSILON_VEL settle floor clears, and no
+      // stale manual sample can synthesize a velocity against the flight's final value.
+      animatedVelocity = null
+      prev = null
+      prevUpdatedAtMs = null
+      updatedAtMs = now()
+    },
+    get: () => value,
+    set(next) {
+      // Core set() verbatim (r20): a manual write reverts to clock velocity; the frame window
+      // rolls only when time moved (same-frame writes COMPOUND); identical writes do not
+      // notify. The layout channels are session-driven — no gesture-lane write rides this.
+      animatedVelocity = null
+      const nowMs = now()
+      if (nowMs !== updatedAtMs) {
+        prev = value
+        prevUpdatedAtMs = updatedAtMs
+        updatedAtMs = nowMs
+      }
+      const previous = value
+      value = next
+      if (value !== previous) {
+        for (let i = 0; i < listeners.length; i++) listeners[i]!(value)
+        for (let i = 0; i < eventListeners.change.length; i++) eventListeners.change[i]!(value)
+      }
+    },
+    jump(next) {
+      // Core jump() VERBATIM (r16/r17/r20): set (window semantics + identical-write
+      // suppression + clock velocity for the change listener) -> window reset -> stop whose
+      // cancellation reads 0 with the animation still observable.
+      mv.set(next)
+      prev = null
+      prevUpdatedAtMs = null
+      updatedAtMs = now()
+      mv.stop()
+    },
+    // alloc-ok: lifecycle-edge — listener registration; the unsubscriber's splice runs at detach.
+    subscribe(listener) {
+      listeners.push(listener)
+      // alloc-ok: lifecycle-edge — the unsubscriber runs at holder detach, never per frame.
+      return () => {
+        const at = listeners.indexOf(listener)
+        if (at >= 0) listeners.splice(at, 1)
+      }
+    },
+    getVelocity: () => {
+      // Core getVelocity() verbatim: the animated velocity wins while a flight drives the
+      // value; otherwise the clock formula over the manual-write window, stale -> 0.
+      if (animatedVelocity !== null) return animatedVelocity
+      if (prev === null || prevUpdatedAtMs === null) return 0
+      if (now() - updatedAtMs > MAX_VELOCITY_DELTA_MS) return 0
+      const dtMs = Math.min(updatedAtMs - prevUpdatedAtMs, MAX_VELOCITY_DELTA_MS)
+      if (dtMs <= 0) return 0
+      return ((value - prev) * 1000) / dtMs
+    },
+    // alloc-ok: lifecycle-edge — event-listener registration; the unsubscriber runs at detach.
+    on(event, listener) {
+      eventListeners[event].push(listener)
+      // alloc-ok: lifecycle-edge — the unsubscriber runs at holder detach, never per frame.
+      return () => {
+        const at = eventListeners[event].indexOf(listener)
+        if (at >= 0) eventListeners[event].splice(at, 1)
+      }
+    },
+    // Liveness IS the __active handle (set at animate, nulled at stop and natural completion).
+    isAnimating: () => mv.__active !== null,
+    // Lifecycle emission (r15 e18b6f40a2d7): indexed — completion emits inside the vsync loop.
+    __emit(event) {
+      const list = eventListeners[event]
+      for (let i = 0; i < list.length; i++) (list[i] as () => void)()
+    },
+    stop() {
+      if (mv.__active !== null) {
+        // Pinned ORDER (r17): the cancellation is notified while the animation is still
+        // observable; the handle's ledger/liveness/velocity cleanup runs after.
+        mv.__emit('animationCancel')
+        mv.__active.stop()
+        mv.__active = null
+      }
+    },
+    destroy() {
+      // Pinned teardown ORDER (r16 major 1): destroy announces FIRST (the listener observes
+      // the live animation), then the SILENT stop — never an animationCancel from teardown.
+      mv.__emit('destroy')
+      if (mv.__active !== null) {
+        mv.__active.stop()
+        mv.__active = null
+      }
+      listeners.length = 0
+      eventListeners.change.length = 0
+      eventListeners.animationStart.length = 0
+      eventListeners.animationComplete.length = 0
+      eventListeners.animationCancel.length = 0
+      eventListeners.destroy.length = 0
+    },
+  }
+  return mv
+}
+
+// alloc-ok: construction — one graph per layout slot; the per-frame surface is frame()/
+// isSettled()/activeAnimationCount(), which allocate nothing.
+export function createUiLayoutGraph(): UiLayoutGraph {
+  'worklet'
+  const animations: UiLayoutActiveAnimation[] = []
+  let openActivities = 0
+  // The graph's frame clock (r19): RAW frame time accumulated like core's ManualClock — the
+  // manual-write velocity window reads it; animations still advance by CLAMPED dt.
+  let nowMs = 0
+  // Live (not-done) animation count, maintained at the edges that flip `done` — the ONLY two
+  // writers are handle.stop() and frame()'s natural completion, both latched on !done so a
+  // stop-then-frame or double-stop decrements exactly once. isSettled() is the hottest read on
+  // the frame path (per active id and per painted holder through the session's sync()), so it
+  // must be O(1) with zero allocation — a scan here made settle checks O(animations) each and
+  // the frame quadratic across concurrent identities (REQ-DRIVER-015, review round 6 major 1).
+  let liveAnimations = 0
+
+  const graph: UiLayoutGraph = {
+    motionValue<T = number>(initial: T): MotionValue<T> {
+      // alloc-ok: lifecycle-edge — the clock-read closure is created once per VALUE at
+      // pairing time (the factory never runs on the vsync path).
+      return createUiLayoutMotionValue(initial as number, () => nowMs) as unknown as MotionValue<T>
+    },
+    derived() {
+      // ui-throw-ok: assert — a programmer-error refusal for an API outside the layout-engine
+      // crossing; no production caller (a dev-only trap, never a UI delivery).
+      throw new Error(
+        'uiLayoutGraph: derived values are not part of the layout engine crossing (specs/LAYOUT-UITHREAD-PORT-BUILD-PACKET.md).',
+      )
+    },
+    // alloc-ok: lifecycle-edge — flight start/retarget (session.springTo), never per frame.
+    animate(value: MotionValue<number>, factory: GeneratorFactory): Animation {
+      const motionValue = value as UiLayoutMotionValue
+      // Interruption ORDER (r19/r20, core-graph parity): the outgoing handle LATCHES first
+      // (core's markFinished-before-notify — a reentrant listener stop() hits the
+      // exactly-once latch, never a null dereference), the cancellation is notified while
+      // liveness is still observable (a valid listener may write the value), ownership
+      // clears, and only THEN does the successor seed read the CURRENT state
+      // (REQ-CORE-002/REQ-LAYOUT-018 continuity — including the listener write's clock
+      // velocity, which core's set() law now computes here too).
+      const outgoing = motionValue.__active
+      if (outgoing !== null && !outgoing.done) {
+        // Core's markFinished shape EXACTLY (r21): only the exactly-once latch flips before
+        // the notification — the listener still observes a LIVE graph (isAnimating true,
+        // count 1, unsettled). Ledger and ownership clear AFTER, in a finally (r22): a
+        // THROWING listener propagates loud but must never wedge the settle edge — frame()
+        // compacts done handles by ledger, so an unrepaired decrement is permanent.
+        outgoing.done = true
+        try {
+          motionValue.__emit('animationCancel')
+        } finally {
+          liveAnimations -= 1
+          if (motionValue.__active === outgoing) motionValue.__active = null
+        }
+      }
+      const generator = factory({ from: motionValue.get(), velocity: motionValue.getVelocity() })
+      const handle: UiLayoutAnimation = {
+        done: false,
+        __finish(runEndCleanup) {
+          if (handle.done) return // exactly-once: a second finish must not skew the ledger
+          handle.done = true
+          liveAnimations -= 1
+          // Ownership coherence (r16 major 3): __active clears either way; the
+          // end-of-animation velocity cleanup (r17) runs ONLY outside interruption — a
+          // retarget carries velocity into the successor seed (r18/r19).
+          if (motionValue.__active === handle) {
+            motionValue.__active = null
+            if (runEndCleanup) motionValue.__endAnimation()
+          }
+        },
+        stop() {
+          handle.__finish(true)
+        },
+      }
+      motionValue.__active = handle
+      animations.push({ value: motionValue, generator, handle, elapsedMs: 0 })
+      liveAnimations += 1
+      // Core parity (graph.animate): the start event fires after the stopper is installed.
+      motionValue.__emit('animationStart')
+      return handle
+    },
+    activeAnimationCount: () => liveAnimations,
+    // alloc-ok: lifecycle-edge — measure-wait handle creation at the fail-closed edge.
+    registerActivity(): ActivityHandle {
+      openActivities += 1
+      let released = false
+      return {
+        release() {
+          if (released) return
+          released = true
+          openActivities -= 1
+        },
+      }
+    },
+    isSettled: () => liveAnimations === 0 && openActivities === 0,
+    whenSettled() {
+      // ui-throw-ok: assert — a programmer-error refusal for an API outside the layout-engine
+      // crossing; no production caller (a dev-only trap, never a UI delivery).
+      throw new Error(
+        'uiLayoutGraph: whenSettled is not part of the layout engine crossing — the driver frame loop owns the settle edge (specs/LAYOUT-UITHREAD-PORT-BUILD-PACKET.md).',
+      )
+    },
+    frame(dtMs) {
+      // REQ-CLOCK-003 (core graph semantics, packages/core/src/graph.ts): clamp per-frame elapsed
+      // so a large gap after backgrounding does not jump the flight forward unbounded — the live
+      // driver feeds real vsync deltas here (review round 2026-07-09: frame(5000) completed a
+      // spring in one step while element-driver props stayed clamped inside stepProp).
+      // Hot-path discipline (REQ-DRIVER-015): completion handled inline (an animation's end only
+      // touches its own value) and finished entries compacted by write index — no completed
+      // snapshot array, no splice garbage, zero allocation per vsync (review round 4 major 6).
+      nowMs += dtMs
+      const clampedDt = dtMs > DT_CLAMP_MS ? DT_CLAMP_MS : dtMs
+      let anyDone = false
+      // Indexed loop: for..of allocates its iterator on Hermes — banned on the vsync path.
+      for (let i = 0; i < animations.length; i++) {
+        const animation = animations[i]!
+        if (animation.handle.done) {
+          anyDone = true // a stop() between frames leaves a done entry to compact below
+          continue
+        }
+        animation.elapsedMs += clampedDt
+        const sample = animation.generator.sample(animation.elapsedMs)
+        animation.value.__applyAnimationSample(sample.value, sample.velocity)
+        if (sample.done) {
+          animation.handle.done = true // this branch only reaches !done entries — one decrement
+          liveAnimations -= 1
+          if (animation.value.__active === animation.handle) {
+            animation.value.__active = null
+            animation.value.__endAnimation()
+            animation.value.__emit('animationComplete')
+          }
+          anyDone = true
+        }
+      }
+      // Compact finished entries so a long-lived driver graph does not grow per flight.
+      if (anyDone) {
+        let w = 0
+        for (let i = 0; i < animations.length; i++) {
+          const animation = animations[i]!
+          if (!animation.handle.done) {
+            animations[w] = animation
+            w += 1
+          }
+        }
+        animations.length = w
+      }
+    },
+  }
+  return graph
+}