@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/layoutTransition.ts

@@ -0,0 +1,1302 @@
+// The L3 no-flash layout transition (specs/L3-BUILD-PACKET.md §path B): a custom Reanimated
+// LayoutAnimationFunction whose commit-hook `initialValues` paint the first post-commit frame at
+// the OLD rect (zero wrong frames — proven by probe 2), and whose per-channel animations step
+// CORE's generators (no forked math, REQ-DRIVER-003) toward the new layout. The inversion
+// is expressed in origin-space by the commit hook itself (initialValues = current rect ≡ the
+// FLIP inversion at t0); core owns the TRAJECTORY: `resolveSpringGenerator` or `timingGenerator`
+// seeds each channel, `stepProp` advances it (dt-clamped internally, REQ-CLOCK-003), and a
+// mid-flight spring re-seeds via `retargetSpring` from the live (value, velocity) — C0/C1
+// continuity, the session's own interruption law. Reanimated's layout channels are UI-thread
+// paint props, not
+// layout-authoritative style: probe 2 measured that the committed layout stays truthful during
+// the flight (REQ-LAYOUT-001 posture, no measurement feedback). Distinct from the forbidden
+// sharedTransitionTag machinery, which stays off.
+//
+// Structure: `buildCoreLayoutChannel` is the PURE AnimationObject builder (deterministically
+// driven by the checks rows via manual onStart/onFrame); `defineAnimation` wraps it only at the
+// transition boundary (Reanimated resolves the definition worklet-side).
+
+import {
+  resolveSpringGenerator,
+  retargetSpring,
+  stepProp,
+  timingGenerator,
+  type Generator,
+  type ProjectionTree,
+  type SpringConfig,
+  type TimingConfig,
+} from '@unrulysystems/native-motion-core'
+import {
+  defineAnimation,
+  makeMutable,
+  type AnimationObject,
+  type LayoutAnimationFunction,
+} from 'react-native-reanimated'
+import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets'
+import {
+  compareMappedTransformKeys,
+  nativeTransformEntryName,
+  type MappedTransformKey,
+} from './composeTransform'
+import { refuseUnsafeSerializablePayload } from './serializablePayload'
+
+// The channel animation's mutable state, decorated by Reanimated at runtime. `prop` mirrors the
+// driver's PropStep shape (generator + accumulated elapsed) so the trajectory is core's exactly.
+export interface CoreLayoutChannelAnimation extends AnimationObject<number> {
+  onStart: (
+    animation: CoreLayoutChannelAnimation,
+    value: number,
+    now: number,
+    previous: CoreLayoutChannelAnimation | null | undefined,
+  ) => void
+  onFrame: (animation: CoreLayoutChannelAnimation, now: number) => boolean
+  current: number
+  lastTimestamp: number
+  delayUntil: number
+  prop: { generator: Generator; elapsed: number; value: number; done: boolean } | null
+  completionReported: boolean
+  projectionCompletionReported: boolean
+}
+
+export type LayoutGeneratorConfig =
+  | { readonly type: 'spring'; readonly config: SpringConfig; readonly delayMs?: number }
+  | { readonly type: 'tween'; readonly config: TimingConfig; readonly delayMs?: number }
+
+// One stale projection-tree report as the tree's drain surfaces it (iOS AUTO SIGABRT Phase 1.5):
+// typed off the core tree's drain so the declaration sets of the core layout barrels stay pinned.
+type StaleProjectionNodeReport = ReturnType<ProjectionTree['drainStaleReports']>[number]
+
+// Deliver every drained stale-tree report to RN through the established scheduleOnRN severity
+// channel (Phase 1 pattern). A quiet frame drains the shared frozen empty array — the index loop
+// allocates nothing (REQ-DRIVER-021; for..of is banned here for the iterator).
+function reportStaleProjectionReports(
+  projection: { readonly tree: Pick<ProjectionTree, 'drainStaleReports'> },
+  onStaleProjectionNodeRefusal?: (report: StaleProjectionNodeReport) => void,
+): void {
+  'worklet'
+  const staleReports = projection.tree.drainStaleReports()
+  for (let index = 0; index < staleReports.length; index += 1) {
+    if (onStaleProjectionNodeRefusal !== undefined)
+      scheduleOnRN(onStaleProjectionNodeRefusal, staleReports[index]!)
+  }
+}
+
+// Retire ONE projection host-frame channel at its terminal edge — completion OR unseeded
+// retirement (iOS AUTO SIGABRT seal r2, F2). Generation-scoped: at zero remaining channels the
+// frame record and its completion owner release, exactly like the normal completion path. A
+// module-level worklet so the produced channel's closure stays primitive-only (a nested callable
+// capture serializes a second worklet graph — undefined on the iOS UI runtime).
+function retireProjectionHostFrameChannel(
+  driverId: number,
+  componentId: string,
+  generation: number,
+  ownerKey?: number,
+): void {
+  'worklet'
+  const projectionGlobal = globalThis as ProjectionHostUiGlobal
+  const driverFrames = projectionGlobal.__nativeMotionProjectionHostFrames?.[driverId]
+  const frame = driverFrames?.frames[componentId]
+  if (frame === undefined || frame.generation !== generation) return
+  frame.remainingChannels -= 1
+  if (frame.remainingChannels > 0) return
+  delete driverFrames!.frames[componentId]
+  if (ownerKey === undefined) return
+  const owners = projectionGlobal.__nativeMotionProjectionHostFrameOwners
+  const owner = owners?.[ownerKey]
+  if (
+    owner?.driverId === driverId &&
+    owner.componentId === componentId &&
+    owner.generation === generation
+  )
+    delete owners![ownerKey]
+}
+
+// Retire ONE transform-mirror flight channel at its terminal edge — completion OR unseeded
+// retirement (seal r2, F2). Generation-scoped: at zero remaining channels the flight record
+// releases, so no mirror stays awake on a flight its host has finished.
+function retireLayoutTransformMirrorFlightChannel(key: number, generation: number): void {
+  'worklet'
+  const flights = (globalThis as LayoutTransformMirrorUiGlobal)
+    .__nativeMotionLayoutTransformMirrorFlights
+  const flight = flights?.flights[key]
+  if (flight === undefined || flight.generation !== generation) return
+  flight.remainingChannels -= 1
+  if (flight.remainingChannels === 0) delete flights!.flights[key]
+}
+
+// Seal-r15 F2 proof witnesses for the layout-completion callback (the settle-gap card): plain
+// primitive counters on the UI global — they never ride the channel under test, so a dead
+// crossing cannot hide them. Seal-r16 F2: mutations are gated on the arm flag (set only when
+// the proof app's marker is present); ordinary settle/completion paths allocate nothing. The
+// JS-side last-pushed cell is filled from MotionView's layoutCompletion (engine-internal
+// reader) — this worklet body must not capture non-worklet helpers (worklet-closures gate).
+interface ProofLayoutCallbackUiGlobal {
+  __nativeMotionProofWitnessArmed?: boolean
+  __nativeMotionProofLayoutCallbackInvocations?: number
+  __nativeMotionProofLayoutCallbackEpochDrops?: number
+  __nativeMotionProofLayoutCallbackCancelled?: number
+  __nativeMotionProofLayoutOnCompleteScheduled?: number
+}
+
+/**
+ * A property-driver transform that must remain visible while Reanimated owns the same host's
+ * layout frame. Reanimated's layout proxy receives only geometry values, so each layout frame
+ * otherwise replaces the driver's whole `transform` array. The mirror makes that array part of
+ * the layout result and reads the driver's UI-runtime value at the same frame boundary.
+ */
+export interface LayoutTransformMirror {
+  readonly key: MappedTransformKey
+  readonly shared: { readonly value: number }
+  // The driver owns both values on the UI runtime. `target` changes with the currently active
+  // command (rather than capturing the base `animate` target), while `active` keeps gesture
+  // holds live until their release command takes ownership.
+  readonly target: { readonly value: number }
+  readonly active: { readonly value: boolean }
+}
+
+/**
+ * Primitive address of the ancestor-owned UI projection ledger. The layout callback captures this
+ * data only; it never captures a callable worklet or crosses back to JS on a host frame.
+ */
+export interface LayoutProjectionHostFeed {
+  readonly driverId: number
+  readonly componentId: string
+}
+
+type LayoutTransformMirrorAnimation = AnimationObject<string | number> & {
+  current: string | number
+}
+
+interface MirrorConfigurableLayoutTransition extends LayoutAnimationFunction {
+  configureLayoutTransformMirrors(enabled: boolean): void
+  configureProjectionHostFeed(feed: LayoutProjectionHostFeed | null): void
+}
+
+/** Configure a concrete host transition with its UI-resident projection-tree address. */
+export function configureLayoutProjectionHostFeed(
+  transition: LayoutAnimationFunction,
+  feed: LayoutProjectionHostFeed | null,
+): void {
+  ;(transition as Partial<MirrorConfigurableLayoutTransition>).configureProjectionHostFeed?.(feed)
+}
+
+// Guest-side SharedValue writes (`cell.value = …` from JS) ride reanimated's modify-scheduling
+// lane: each write becomes scheduleOnUI(() => { mutable.value = … }), then worklets'
+// flushUIQueue wraps that job as createSerializable(() => workletFunction(...workletArgs)).
+// The live hang tail was exactly that shape:
+//   /__closure/workletFunction/__closure/mutable/__closure
+// (PROOF §SIGABRT-1 wedge recurrence Q3). Layout-enabled hosts call configureProjectionHostFeed
+// on every render — guest writes there would mint that graph on the gallery/lightbox path.
+// Module-level worklet + primitive args (M1-r19 / reassert shape): the UI lane mutates the
+// cells; the guest only serializes a named worklet and branded SharedValue refs.
+function setProjectionHostFeedCellsOnUI(
+  driverIdCell: { value: number },
+  componentIdCell: { value: string },
+  driverId: number,
+  componentId: string,
+): void {
+  'worklet'
+  driverIdCell.value = driverId
+  componentIdCell.value = componentId
+}
+
+function createLayoutTransformMirror(
+  mirror: LayoutTransformMirror,
+  completionKey: number | undefined,
+  flightGeneration: number | undefined,
+): LayoutTransformMirrorAnimation {
+  'worklet'
+  return {
+    onStart(animation) {
+      'worklet'
+      const current = mirror.shared.value
+      animation.current =
+        mirror.key === 'rotate' ||
+        mirror.key === 'rotateX' ||
+        mirror.key === 'rotateY' ||
+        mirror.key === 'skewX' ||
+        mirror.key === 'skewY'
+          ? `${current}deg`
+          : current
+    },
+    onFrame(animation) {
+      'worklet'
+      const current = mirror.shared.value
+      animation.current =
+        mirror.key === 'rotate' ||
+        mirror.key === 'rotateX' ||
+        mirror.key === 'rotateY' ||
+        mirror.key === 'skewX' ||
+        mirror.key === 'skewY'
+          ? `${current}deg`
+          : current
+      // Reanimated permanently retires an animation after its first `true` frame. A property can
+      // be idle at host-flight start yet activate later through a gesture, exit, or bound value;
+      // keep this transform mirror awake until that real geometry flight ends. This nested frame
+      // worklet must not capture another callable worklet: Reanimated serializes those closures
+      // independently and iOS resolved the helper as undefined at runtime. Read the primitive
+      // UI-global ledger directly instead.
+      if (completionKey !== undefined && flightGeneration !== undefined) {
+        const flight = (globalThis as LayoutTransformMirrorUiGlobal)
+          .__nativeMotionLayoutTransformMirrorFlights?.flights[completionKey]
+        if (flight?.generation === flightGeneration) return false
+      }
+      // Property and layout consume the same gated transition. Keep the layout's transform
+      // entry live until the property lane reaches its target; then both complete together.
+      return !mirror.active.value && Math.abs(current - mirror.target.value) <= 0.000_001
+    },
+    current:
+      mirror.key === 'rotate' ||
+      mirror.key === 'rotateX' ||
+      mirror.key === 'rotateY' ||
+      mirror.key === 'skewX' ||
+      mirror.key === 'skewY'
+        ? `${mirror.shared.value}deg`
+        : mirror.shared.value,
+  }
+}
+
+/**
+ * Preserve transform targets from the driver while a host-layout transition writes its own frame.
+ * A transform key absent from this list remains solely driver-owned, so ordinary property-only
+ * animation never acquires a layout dependency.
+ */
+export function mirrorLayoutTransformValues(
+  transition: LayoutAnimationFunction,
+  mirrors: readonly LayoutTransformMirror[],
+  completionEpoch?: LayoutCompletionEpoch,
+): LayoutAnimationFunction | undefined {
+  // The host transition creates its UI-global ledger only when an actual transform mirror needs
+  // to observe it. `MotionView` always visits this adapter, including the zero-mirror case.
+  const mirrorConfigurable = transition as Partial<MirrorConfigurableLayoutTransition>
+  mirrorConfigurable.configureLayoutTransformMirrors?.(mirrors.length > 0)
+  if (mirrors.length === 0) return transition
+  // The wedge law (iOS AUTO SIGABRT): every record the produced wrapper captures must be a
+  // finite, acyclic payload — a cyclic/unbounded mirror graph would peg the main thread inside
+  // SerializableObject::toJSValue, not fail at schedule time. Dev throws at this factory edge;
+  // production reports and the mirror lane is REFUSED (seal r7, F2): undefined means no layout
+  // transition at all — the host keeps its last valid static layout, never an unmirrored
+  // transition substituted silently (that fallback erases/freezes live transforms).
+  if (refuseUnsafeSerializablePayload(mirrors, 'mirrors') !== null) return undefined
+  // Do not leak authoring/mount order into the host proxy. `composeTransform` is the ordinary
+  // lane's canonical producer; this mirror follows the same single source of truth.
+  const orderedMirrors = [...mirrors].sort((a, b) => compareMappedTransformKeys(a.key, b.key))
+  // A NAMED declarator (iOS AUTO SIGABRT seal, F1): the closure graph roots produced worklets by
+  // declarator name — an anonymous wrapper would take a positional plugin alias and evade the
+  // closure roots entirely (the exact device-only invisibility the seal fixes).
+  const mirroredTransition: LayoutAnimationFunction = (values) => {
+    'worklet'
+    const result = transition(values)
+    const completionKey = completionEpoch?.key
+    const flightGeneration =
+      completionKey === undefined
+        ? undefined
+        : currentLayoutTransformMirrorFlightGeneration(completionKey)
+    return {
+      ...result,
+      animations: {
+        ...result.animations,
+        transform: orderedMirrors.map((mirror) => ({
+          [nativeTransformEntryName(mirror.key)]: createLayoutTransformMirror(
+            mirror,
+            completionKey,
+            flightGeneration,
+          ),
+        })),
+      },
+    } as unknown as ReturnType<LayoutAnimationFunction>
+  }
+  return mirroredTransition
+}
+
+// A layout transition function is read-current on every React render, while Reanimated may still
+// deliver a terminal callback from the prior host commit. The host key crosses rebuilt functions
+// as a primitive; the mutable epoch lives only in the UI runtime because Worklets deserializes a
+// fresh ordinary-object capture for every rebuilt function.
+export interface LayoutCompletionEpoch {
+  readonly key: number
+}
+
+let nextLayoutCompletionEpochKey = 1
+
+// The UI-global owner registry needs a hard bound: cancellation and teardown release owners,
+// while a pathological live tree fails loud instead of retaining unbounded completion state.
+// Never evict a live owner — that would silently suppress its public callback.
+export const MAX_ACTIVE_LAYOUT_COMPLETION_OWNERS = 512
+
+// Transform mirrors have a separate UI-global lifetime from public completion callbacks. Bound
+// them independently: never evict a live mirror, because its host can still receive an authority
+// change before its geometry settles.
+export const MAX_ACTIVE_LAYOUT_TRANSFORM_MIRROR_FLIGHTS = 512
+
+// Host-frame records are separate UI-global state from completion/mirror owners. They are active
+// only while a host layout channel can still publish geometry into the projection tree, and must
+// never become an unbounded tombstone registry when flights are cancelled or hosts unmount.
+export const MAX_ACTIVE_PROJECTION_HOST_FRAMES = 512
+
+export function createLayoutCompletionEpoch(): LayoutCompletionEpoch {
+  return { key: nextLayoutCompletionEpochKey++ }
+}
+
+interface LayoutCompletionUiGlobal {
+  __nativeMotionLayoutCompletionState?: {
+    nextGeneration: number
+    readonly activeEpochs: Record<number, number>
+  }
+}
+
+// A host layout flight and its transform mirrors run as independent Reanimated animations. This
+// UI-global ledger gives them one primitive, generation-guarded lifecycle without serializing a
+// mutable capture into each worklet. A superseding host flight replaces the record, so old channel
+// completions cannot wake or finish the new flight.
+interface LayoutTransformMirrorUiGlobal {
+  __nativeMotionLayoutTransformMirrorFlights?: {
+    nextGeneration: number
+    readonly flights: Record<number, { readonly generation: number; remainingChannels: number }>
+  }
+}
+
+// The host layout callback runs inside Reanimated, while the projection tree is owned by the
+// driver's UI-global ledger. Keep the bridge structural and primitive-only: importing/capturing
+// driver worklets here would serialize a second callable graph and reproduces the iOS crash this
+// module is specifically designed to avoid.
+interface ProjectionHostFrame {
+  readonly generation: number
+  currentOriginX: number
+  currentOriginY: number
+  currentWidth: number
+  currentHeight: number
+  readonly targetOriginX: number
+  readonly targetOriginY: number
+  readonly targetWidth: number
+  readonly targetHeight: number
+  remainingChannels: number
+}
+
+interface ProjectionHostFrames {
+  nextGeneration: number
+  readonly frames: Record<string, ProjectionHostFrame>
+}
+
+/**
+ * The layout callback is serialized to Reanimated's UI runtime before a host can begin a
+ * geometry flight. A lexical `let` mutated by render-time configuration is cloned as its initial
+ * `null` value into that worklet, which silently drops the parent frame on device. These two
+ * cells are the deliberate cross-runtime address: they are set at the React edge and read only
+ * as primitive values in the frame callback.
+ */
+interface ProjectionHostFeedCells {
+  readonly driverId: { value: number }
+  readonly componentId: { value: string }
+}
+
+interface ProjectionHostUiGlobal {
+  __nativeMotionProjectionHostFrames?: Record<number, ProjectionHostFrames>
+  __nativeMotionProjectionHostFrameOwners?: Record<
+    number,
+    { readonly driverId: number; readonly componentId: string; readonly generation: number }
+  >
+  __nativeMotionDrivers?: Record<
+    number,
+    {
+      readonly layout: {
+        readonly projection: {
+          readonly tree: {
+            setHostFrame(
+              componentId: string,
+              currentX: number,
+              currentY: number,
+              currentWidth: number,
+              currentHeight: number,
+              targetX: number,
+              targetY: number,
+              targetWidth: number,
+              targetHeight: number,
+            ): void
+            clearProjection(componentId: string): void
+            project(): void
+            output(componentId: string): {
+              readonly translateX: number
+              readonly translateY: number
+              readonly scaleX: number
+              readonly scaleY: number
+              readonly borderRadius: { readonly x: number; readonly y: number } | null
+              readonly targetDeltaScaleX: number
+              readonly targetDeltaScaleY: number
+              readonly treeScaleX: number
+              readonly treeScaleY: number
+            }
+            drainStaleReports(): readonly StaleProjectionNodeReport[]
+          }
+          readonly records: readonly {
+            readonly componentId: string
+            readonly outputs: {
+              readonly translateX: { value: number }
+              readonly translateY: { value: number }
+              readonly scaleX: { value: number }
+              readonly scaleY: { value: number }
+              readonly borderRadiusX: { value: number }
+              readonly borderRadiusY: { value: number }
+              readonly targetDeltaScaleX: { value: number }
+              readonly targetDeltaScaleY: { value: number }
+              readonly treeScaleX: { value: number }
+              readonly treeScaleY: { value: number }
+            }
+          }[]
+          dirty: boolean
+        }
+      } | null
+    }
+  >
+}
+
+function layoutTransformMirrorFlights(): NonNullable<
+  LayoutTransformMirrorUiGlobal['__nativeMotionLayoutTransformMirrorFlights']
+> {
+  'worklet'
+  const global = globalThis as LayoutTransformMirrorUiGlobal
+  if (global.__nativeMotionLayoutTransformMirrorFlights === undefined) {
+    global.__nativeMotionLayoutTransformMirrorFlights = { nextGeneration: 0, flights: {} }
+  }
+  return global.__nativeMotionLayoutTransformMirrorFlights
+}
+
+// Keep this module-scope worklet primitive-only. In particular, do not return a worklet closure
+// from here for `defineAnimation` to capture: Worklets would serialize that nested graph per host
+// flight, recreating the iOS AB-BA wedge that attempt 15 intentionally removed.
+function beginLayoutTransformMirrorFlight(key: number, channelCount: number): number | undefined {
+  'worklet'
+  const state = layoutTransformMirrorFlights()
+  if (
+    state.flights[key] === undefined &&
+    Object.keys(state.flights).length >= MAX_ACTIVE_LAYOUT_TRANSFORM_MIRROR_FLIGHTS
+  ) {
+    return undefined
+  }
+  state.nextGeneration += 1
+  const generation = state.nextGeneration
+  state.flights[key] = { generation, remainingChannels: channelCount }
+  return generation
+}
+
+function currentLayoutTransformMirrorFlightGeneration(key: number): number | undefined {
+  'worklet'
+  return (globalThis as LayoutTransformMirrorUiGlobal).__nativeMotionLayoutTransformMirrorFlights
+    ?.flights[key]?.generation
+}
+
+function beginLayoutCompletionFlight(key: number): number | undefined {
+  'worklet'
+  const global = globalThis as LayoutCompletionUiGlobal
+  if (global.__nativeMotionLayoutCompletionState === undefined) {
+    global.__nativeMotionLayoutCompletionState = {
+      nextGeneration: 0,
+      activeEpochs: {},
+    }
+  }
+  const state = global.__nativeMotionLayoutCompletionState
+  // Generations are globally monotonic, rather than per-key counters discarded on completion.
+  // A late A callback can therefore never equal a later C callback after B completed and released
+  // this host key. The map holds ACTIVE owners only: an entry is released by its own terminal
+  // callback, and a new flight on the same host supersedes the old one. Do not evict another
+  // active host to impose an arbitrary cache limit — that would suppress its real completion.
+  if (
+    state.activeEpochs[key] === undefined &&
+    Object.keys(state.activeEpochs).length >= MAX_ACTIVE_LAYOUT_COMPLETION_OWNERS
+  ) {
+    return undefined
+  }
+  state.nextGeneration += 1
+  const next = state.nextGeneration
+  state.activeEpochs[key] = next
+  return next
+}
+
+function isCurrentLayoutCompletionFlight(key: number, epoch: number): boolean {
+  'worklet'
+  const global = globalThis as LayoutCompletionUiGlobal
+  return global.__nativeMotionLayoutCompletionState?.activeEpochs[key] === epoch
+}
+
+function completeLayoutCompletionFlight(key: number, epoch: number): void {
+  'worklet'
+  const global = globalThis as LayoutCompletionUiGlobal
+  if (global.__nativeMotionLayoutCompletionState?.activeEpochs[key] === epoch)
+    delete global.__nativeMotionLayoutCompletionState.activeEpochs[key]
+}
+
+// The public start callback's per-LOGICAL-flight qualification ledger (U7e). The pin
+// fires onLayoutAnimationStart from didUpdate when the rounded target changed or no
+// animation is active (create-projection-node.ts:527-560; boxEqualsRounded). A start-
+// driven rerender rebuilds the worklet and Reanimated cancels the replaced animation —
+// that rebound is the SAME flight, so cancel must NOT release this ledger (device proof
+// 870c5b64 / f841bc52). Settle also must not: Reanimated re-runs the layout function
+// at complete (iOS 21e910d0: starts@[+2037,+5063]), which is extra host granularity,
+// not a pin didUpdate. A later React generation overwrites and starts (review M2).
+// Lifetime teardown still releases.
+interface LayoutFlightStartUiGlobal {
+  __nativeMotionLayoutFlightStarts?: {
+    readonly flights: Record<number, { generation: number }>
+  }
+}
+
+function beginLayoutFlightStart(key: number, generation: number): boolean {
+  'worklet'
+  const global = globalThis as LayoutFlightStartUiGlobal
+  if (global.__nativeMotionLayoutFlightStarts === undefined) {
+    global.__nativeMotionLayoutFlightStarts = { flights: {} }
+  }
+  const flights = global.__nativeMotionLayoutFlightStarts.flights
+  const active = flights[key]
+  // Same React didUpdate (own geometry + inherited parent generation): a start-driven
+  // rerender or a second Yoga commit can carry a different rounded box (iOS 66f7ccfc
+  // flight A; Android C+15ms). That is not a pin retarget. A new generation is.
+  if (active !== undefined && active.generation === generation) return false
+  flights[key] = { generation }
+  return true
+}
+
+function clearLayoutCompletionEpoch(key: number): void {
+  'worklet'
+  const global = globalThis as LayoutCompletionUiGlobal
+  if (global.__nativeMotionLayoutCompletionState !== undefined)
+    delete global.__nativeMotionLayoutCompletionState.activeEpochs[key]
+  // Inlined start-qualification release: this worklet crosses by reference through scheduleOnUI,
+  // so its body stays primitive-only (the projection release below carries the same law).
+  const flightStartGlobal = globalThis as LayoutFlightStartUiGlobal
+  if (flightStartGlobal.__nativeMotionLayoutFlightStarts !== undefined)
+    delete flightStartGlobal.__nativeMotionLayoutFlightStarts.flights[key]
+  const mirrorGlobal = globalThis as LayoutTransformMirrorUiGlobal
+  if (mirrorGlobal.__nativeMotionLayoutTransformMirrorFlights !== undefined)
+    delete mirrorGlobal.__nativeMotionLayoutTransformMirrorFlights.flights[key]
+  // Inlined projection host-frame + tree release: this worklet crosses to the UI runtime by
+  // reference through scheduleOnUI, so its body must stay primitive-only — a helper worklet
+  // call resolves undefined after the crossing. Cancel/teardown must clear BOTH the UI-global
+  // registry and the tree cell so cancelled mid-flight geometry cannot be re-projected
+  // (review major c7e4a91f2b08).
+  const projectionGlobal = globalThis as ProjectionHostUiGlobal
+  const owner = projectionGlobal.__nativeMotionProjectionHostFrameOwners?.[key]
+  if (owner !== undefined) {
+    const frame =
+      projectionGlobal.__nativeMotionProjectionHostFrames?.[owner.driverId]?.frames[
+        owner.componentId
+      ]
+    if (frame !== undefined && frame.generation === owner.generation)
+      delete projectionGlobal.__nativeMotionProjectionHostFrames?.[owner.driverId]?.frames[
+        owner.componentId
+      ]
+    delete projectionGlobal.__nativeMotionProjectionHostFrameOwners?.[key]
+    const projection = projectionGlobal.__nativeMotionDrivers?.[owner.driverId]?.layout?.projection
+    if (projection !== undefined) {
+      projection.tree.clearProjection(owner.componentId)
+      projection.tree.project()
+      for (let index = 0; index < projection.records.length; index += 1) {
+        const record = projection.records[index]!
+        const output = projection.tree.output(record.componentId)
+        record.outputs.translateX.value = output.translateX
+        record.outputs.translateY.value = output.translateY
+        record.outputs.scaleX.value = output.scaleX
+        record.outputs.scaleY.value = output.scaleY
+        record.outputs.borderRadiusX.value = output.borderRadius?.x ?? Number.NaN
+        record.outputs.borderRadiusY.value = output.borderRadius?.y ?? Number.NaN
+      }
+      projection.dirty = false
+    }
+  }
+}
+
+// React owns host teardown while the completion registry lives on UI. Layout enablement owns a
+// key lifetime: a disabled→enabled host receives a fresh key, so delayed old-lifetime cleanup
+// cannot release the replacement flight's owner.
+export function teardownLayoutCompletionEpoch(epoch: LayoutCompletionEpoch): void {
+  scheduleOnUI(clearLayoutCompletionEpoch, epoch.key)
+}
+
+// Pure builder for one layout channel (originX/originY/width/height) moving toward `to` with
+// core's math. Springs re-seed through retargetSpring for C1 velocity carry. Tweens seed core's
+// timing generator from the host-provided live value; timing intentionally ignores velocity.
+export function buildCoreLayoutChannel(
+  to: number,
+  transition: LayoutGeneratorConfig,
+  mirrorFlightKey?: number,
+  mirrorFlightGeneration?: number,
+  projectionDriverId?: number,
+  projectionComponentId?: string,
+  projectionGeneration?: number,
+  projectionChannel?: 'originX' | 'originY' | 'width' | 'height',
+  onUnseededChannelRefusal?: (code: string) => void,
+  onStaleProjectionNodeRefusal?: (report: StaleProjectionNodeReport) => void,
+): CoreLayoutChannelAnimation {
+  'worklet'
+  return {
+    onStart(animation, value, now, previous) {
+      'worklet'
+      // A live previous channel means this layout change interrupted an in-flight one: re-seed
+      // from its (value, velocity) via retargetSpring — never from rest (the C1 law). A settled
+      // or absent previous seeds from rest at the host-provided start value. Reanimated passes
+      // `undefined` (not null) when there is no previous animation — check both, or the very
+      // first commit crashes the UI runtime (observed on-device, packet Findings).
+      let generator: Generator
+      if (transition.type === 'tween') {
+        generator = timingGenerator(to, transition.config)({ from: value, velocity: 0 })
+      } else {
+        const livePrevious =
+          previous !== null &&
+          previous !== undefined &&
+          previous.prop !== null &&
+          !previous.prop.done
+            ? previous.prop
+            : null
+        generator =
+          livePrevious !== null
+            ? retargetSpring(livePrevious.generator, livePrevious.elapsed, to, transition.config)
+            : resolveSpringGenerator(to, transition.config)({ from: value, velocity: 0 })
+      }
+      // Motion's JSAnimation subtracts its signed delay from currentTime before sampling. A
+      // negative delay therefore starts this channel partway through CORE's trajectory, rather
+      // than merely making its positive-delay hold deadline lie in the past.
+      const delayMs = transition.delayMs ?? 0
+      animation.prop = {
+        generator,
+        elapsed: delayMs < 0 ? -delayMs : 0,
+        value,
+        done: false,
+      }
+      animation.lastTimestamp = now
+      // Only a positive delay holds frames. Negative delay is represented by the seeded CORE
+      // elapsed clock above, so every channel starts from the same advanced trajectory point.
+      animation.delayUntil = now + (delayMs > 0 ? delayMs : 0)
+      animation.current = value
+    },
+    onFrame(animation, now) {
+      'worklet'
+      const prop = animation.prop
+      if (prop === null) {
+        // A frame before onStart is a Reanimated contract violation — but a UI-thread throw is
+        // a bare std::terminate on device (iOS AUTO SIGABRT), never a refusal. Report the
+        // unseeded channel to RN through the established scheduleOnRN severity channel and
+        // retire it: returning true ends the animation, preserving the last valid visual
+        // state (never seed or coast a corrupt channel).
+        if (onUnseededChannelRefusal !== undefined)
+          scheduleOnRN(onUnseededChannelRefusal, 'layout-channel-unseeded')
+        // Terminal for EVERY owner (seal r2, F2): retire this channel from both flight ledgers
+        // exactly as a completion would — generation-scoped — so neither ledger waits forever
+        // on a channel that never started (mirrors would stay awake; the seeded host-frame
+        // record would be retained on a still-mounted host).
+        if (
+          projectionDriverId !== undefined &&
+          projectionComponentId !== undefined &&
+          projectionGeneration !== undefined
+        )
+          retireProjectionHostFrameChannel(
+            projectionDriverId,
+            projectionComponentId,
+            projectionGeneration,
+            mirrorFlightKey,
+          )
+        if (mirrorFlightKey !== undefined && mirrorFlightGeneration !== undefined)
+          retireLayoutTransformMirrorFlightChannel(mirrorFlightKey, mirrorFlightGeneration)
+        return true
+      }
+      const frameStart = animation.lastTimestamp
+      animation.lastTimestamp = now
+      if (now < animation.delayUntil) return false
+      // Delay is a clock offset around CORE's generator, identical for every channel. Once the
+      // window ends, only the post-delay slice reaches stepProp; trajectory math stays CORE's.
+      const activeStart = frameStart < animation.delayUntil ? animation.delayUntil : frameStart
+      stepProp(prop, now - activeStart)
+      animation.current = prop.value
+      // A host-layout channel is the only faithful per-frame source for its geometry. The frame
+      // record and projection tree both live on UI; this is deliberately direct global mutation,
+      // not a nested callable-worklet capture or a JS↔UI crossing.
+      if (
+        projectionDriverId !== undefined &&
+        projectionComponentId !== undefined &&
+        projectionGeneration !== undefined &&
+        projectionChannel !== undefined
+      ) {
+        const projectionGlobal = globalThis as ProjectionHostUiGlobal
+        const frame =
+          projectionGlobal.__nativeMotionProjectionHostFrames?.[projectionDriverId]?.frames[
+            projectionComponentId
+          ]
+        if (frame !== undefined && frame.generation === projectionGeneration) {
+          switch (projectionChannel) {
+            case 'originX':
+              frame.currentOriginX = prop.value
+              break
+            case 'originY':
+              frame.currentOriginY = prop.value
+              break
+            case 'width':
+              frame.currentWidth = prop.value
+              break
+            case 'height':
+              frame.currentHeight = prop.value
+              break
+          }
+          const projection =
+            projectionGlobal.__nativeMotionDrivers?.[projectionDriverId]?.layout?.projection
+          if (projection !== undefined) {
+            projection.tree.setHostFrame(
+              projectionComponentId,
+              frame.currentOriginX,
+              frame.currentOriginY,
+              frame.currentWidth,
+              frame.currentHeight,
+              frame.targetOriginX,
+              frame.targetOriginY,
+              frame.targetWidth,
+              frame.targetHeight,
+            )
+            projection.tree.project()
+            for (let index = 0; index < projection.records.length; index += 1) {
+              const record = projection.records[index]!
+              const output = projection.tree.output(record.componentId)
+              record.outputs.translateX.value = output.translateX
+              record.outputs.translateY.value = output.translateY
+              record.outputs.scaleX.value = output.scaleX
+              record.outputs.scaleY.value = output.scaleY
+              record.outputs.borderRadiusX.value = output.borderRadius?.x ?? Number.NaN
+              record.outputs.borderRadiusY.value = output.borderRadius?.y ?? Number.NaN
+            }
+            projection.dirty = false
+            // Drain the tree's stale-report ring on this frame edge (iOS AUTO SIGABRT Phase
+            // 1.5): teardown races surface through the RN severity channel, never a UI throw.
+            reportStaleProjectionReports(projection, onStaleProjectionNodeRefusal)
+          }
+          if (prop.done && !animation.projectionCompletionReported) {
+            animation.projectionCompletionReported = true
+            retireProjectionHostFrameChannel(
+              projectionDriverId,
+              projectionComponentId,
+              projectionGeneration,
+              mirrorFlightKey,
+            )
+          }
+        } else if (frame === undefined) {
+          // The host detached mid-flight and its frame record is gone (iOS AUTO SIGABRT Phase
+          // 1.5): retire the torn-down flight at this frame boundary — prop.done runs the
+          // completion bookkeeping below, no further frames are scheduled for the host, and the
+          // last painted value (animation.current, already advanced this frame) is preserved.
+          prop.done = true
+        }
+      }
+      if (prop.done && !animation.completionReported) {
+        animation.completionReported = true
+        if (mirrorFlightKey !== undefined && mirrorFlightGeneration !== undefined) {
+          // This onFrame belongs to Reanimated's deferred defineAnimation factory. The mirror
+          // flight ledger retires through a module-level worklet so this closure stays
+          // primitive-only (a nested callable serializes a second worklet graph — undefined on
+          // the iOS UI runtime). The registry data itself is UI-global.
+          retireLayoutTransformMirrorFlightChannel(mirrorFlightKey, mirrorFlightGeneration)
+        }
+      }
+      return prop.done
+    },
+    current: to,
+    lastTimestamp: 0,
+    delayUntil: 0,
+    prop: null,
+    completionReported: false,
+    projectionCompletionReported: false,
+  }
+}
+
+// The deterministic verification screen owns this spring-specific seam. Preserve it as a thin
+// wrapper so the generic channel adds tween support without invalidating the existing spring proof.
+export function buildCoreSpringChannel(
+  to: number,
+  spring: SpringConfig,
+): CoreLayoutChannelAnimation {
+  'worklet'
+  return buildCoreLayoutChannel(to, { type: 'spring', config: spring })
+}
+
+// The default flight spring — the ratified session default (LAYOUT_PROJECTION_SPRING profile).
+const DEFAULT_SPRING: SpringConfig = { stiffness: 550, damping: 45 }
+const DEFAULT_TRANSITION: LayoutGeneratorConfig = {
+  type: 'spring',
+  config: DEFAULT_SPRING,
+  delayMs: 0,
+}
+
+export type LayoutTransitionChannels = 'both' | 'position' | 'size' | 'preserve-aspect'
+
+// Motion's pinned projection oracle treats aspect ratios within 0.2 as preserved. This constant
+// configures channel selection only; CORE remains the sole owner of each selected channel's math.
+const PRESERVED_ASPECT_RATIO_TOLERANCE = 0.2
+
+// One channel wrapped for Reanimated's layout-animation slot. The `starting` decoration value is
+// the channel's current paint value; the factory builds the pure channel worklet-side.
+function coreLayoutChannel(
+  to: number,
+  transition: LayoutGeneratorConfig,
+  mirrorFlightKey?: number,
+  mirrorFlightGeneration?: number,
+  projectionDriverId?: number,
+  projectionComponentId?: string,
+  projectionGeneration?: number,
+  projectionChannel?: 'originX' | 'originY' | 'width' | 'height',
+  onUnseededChannelRefusal?: (code: string) => void,
+  onStaleProjectionNodeRefusal?: (report: StaleProjectionNodeReport) => void,
+): number {
+  'worklet'
+  // A NAMED declarator (iOS AUTO SIGABRT seal, F1 — the closure graph roots produced worklets by
+  // declarator name; an inline arrow would take a positional plugin alias and evade the roots).
+  // Captures stay primitives only: the lifecycle mutation stays in the module-scope worklet
+  // above, never in a dynamically-created completion worklet captured by this factory.
+  const coreLayoutAnimationFactory = (): CoreLayoutChannelAnimation => {
+    'worklet'
+    return buildCoreLayoutChannel(
+      to,
+      transition,
+      mirrorFlightKey,
+      mirrorFlightGeneration,
+      projectionDriverId,
+      projectionComponentId,
+      projectionGeneration,
+      projectionChannel,
+      onUnseededChannelRefusal,
+      onStaleProjectionNodeRefusal,
+    )
+  }
+  return defineAnimation<CoreLayoutChannelAnimation>(
+    to,
+    coreLayoutAnimationFactory,
+  ) as unknown as number
+}
+
+// Build the no-flash layout transition: initialValues = the current (pre-commit) rect — the
+// first post-commit frame paints the OLD rect — and channel animations = core generators toward
+// the target rect.
+export function createNoFlashLayoutTransition(
+  generatorConfig: LayoutGeneratorConfig = DEFAULT_TRANSITION,
+  channels: LayoutTransitionChannels = 'both',
+  onComplete?: () => void,
+  onStart?: () => void,
+  completionEpoch: LayoutCompletionEpoch = createLayoutCompletionEpoch(),
+  onOwnerLimitRefusal?: () => void,
+  onMirrorFlightLimitRefusal?: () => void,
+  onUnseededChannelRefusal?: (code: string) => void,
+  onProjectionHostFrameCapRefusal?: (code: string) => void,
+  onStaleProjectionNodeRefusal?: (report: StaleProjectionNodeReport) => void,
+  // The PUBLIC layout-flight start callback (U7e): unlike the internal onStart (which runs at
+  // EVERY commit — the combined-flight reset must not weaken), this crossing is qualified per
+  // logical flight (beginLayoutFlightStart: React generation, the pin's didUpdate analogue).
+  onFlightStart?: () => void,
+  // Incremented when the React layout signature changes (mode / authored transition /
+  // layout-relevant style). The primitive is the test/fallback capture; the mutable cell
+  // is the live didUpdate read so a mid-flight retarget on a STALE layout function still
+  // sees the new generation (Android 57acf50c dropped C's start — the in-flight worklet
+  // still held B's captured generation).
+  layoutFlightGeneration = 0,
+  layoutFlightGenerationCell?: { value: number },
+): LayoutAnimationFunction | undefined {
+  // The wedge law (iOS AUTO SIGABRT): the generator config rides the produced worklet's closure
+  // into the UI runtime — it must be a finite, acyclic payload. Dev throws at the factory edge;
+  // production reports and the layout request is REFUSED (seal r7, F2): undefined means no
+  // transition at all — the host keeps its last valid static layout, never a pinned default
+  // transition substituted silently (an invalid authored transition running with different
+  // timing).
+  if (refuseUnsafeSerializablePayload(generatorConfig, 'generatorConfig') !== null) return undefined
+  const safeGeneratorConfig = generatorConfig
+  // Extract before entering the worklet. The key is primitive capture data, so Worklets preserves
+  // identity across rebuilt layout functions even though it clones the containing JS object.
+  const completionKey = completionEpoch.key
+  const flightGeneration = layoutFlightGeneration
+  const flightGenerationCell = layoutFlightGenerationCell
+  let hasLayoutTransformMirrors = false
+  // `configureProjectionHostFeed` runs after this function is constructed. Unlike a lexical
+  // variable, a Reanimated mutable stays shared when `layoutTransition` is serialized, so the
+  // root host's frame reaches the same ancestor-owned tree as its nested descendants.
+  const projectionHostFeed: ProjectionHostFeedCells = {
+    driverId: makeMutable(-1),
+    componentId: makeMutable(''),
+  }
+  const layoutTransition: MirrorConfigurableLayoutTransition = (values) => {
+    'worklet'
+
+    // Only public completion owners enter the UI registry. Layout-only flights have no terminal
+    // callback that could release an entry, so registering them would retain a dead owner and
+    // eventually interfere with unrelated hosts.
+    const flightEpoch =
+      onComplete === undefined ? undefined : beginLayoutCompletionFlight(completionKey)
+    if (onComplete !== undefined && flightEpoch === undefined && onOwnerLimitRefusal !== undefined)
+      scheduleOnRN(onOwnerLimitRefusal)
+
+    const beginMirrorFlight = (channelCount: number): number | undefined => {
+      'worklet'
+      if (!hasLayoutTransformMirrors) return undefined
+      const generation = beginLayoutTransformMirrorFlight(completionKey, channelCount)
+      if (generation === undefined && onMirrorFlightLimitRefusal !== undefined)
+        scheduleOnRN(onMirrorFlightLimitRefusal)
+      return generation
+    }
+
+    // A combined layout/layoutId host owns a completion epoch per ACTUAL host flight, never per
+    // React render. This UI commit edge is the faithful start boundary for Reanimated layout.
+    if (onStart !== undefined) scheduleOnRN(onStart)
+    // The PUBLIC start crossing is qualified per LOGICAL flight (React generation — the pin's
+    // didUpdate analogue). The internal onStart above keeps firing per commit — the F1
+    // combined-flight reset is never weakened by the qualification.
+    const liveGeneration =
+      flightGenerationCell !== undefined ? flightGenerationCell.value : flightGeneration
+    if (onFlightStart !== undefined && beginLayoutFlightStart(completionKey, liveGeneration))
+      scheduleOnRN(onFlightStart)
+
+    // `preserve-aspect` follows Motion's documented conditional: a material ratio change snaps
+    // size to the host layout and animates position only. The 0.2 comparison matches the pinned
+    // oracle's `shouldAnimatePositionOnly`; it selects channels and never forks trajectory math.
+    const currentAspectRatio = values.currentWidth / values.currentHeight
+    const targetAspectRatio = values.targetWidth / values.targetHeight
+    const positionOnly =
+      channels === 'position' ||
+      (channels === 'preserve-aspect' &&
+        !(Math.abs(currentAspectRatio - targetAspectRatio) <= PRESERVED_ASPECT_RATIO_TOLERANCE))
+
+    // Register the host's initial/current rectangle in a UI-global record. The frame channels
+    // below mutate only their scalar field and flush the ancestor tree from that same record.
+    // A new host commit replaces the generation, so stale completion frames cannot restart it.
+    const projectionChannelCount = positionOnly || channels === 'size' ? 2 : 4
+    const configuredProjectionDriverId = projectionHostFeed.driverId.value
+    const configuredProjectionComponentId = projectionHostFeed.componentId.value
+    const projectionDriverId =
+      configuredProjectionDriverId >= 0 ? configuredProjectionDriverId : undefined
+    const projectionComponentId =
+      configuredProjectionComponentId.length > 0 ? configuredProjectionComponentId : undefined
+    let projectionGeneration: number | undefined
+    // Capacity pressure is a bounded DEGRADATION, never a process kill (iOS AUTO SIGABRT): the
+    // projection host-frame cap refuses ONLY the projection enhancement/flight for the excess
+    // host — it takes the plain layout path, one cap report reaches RN through scheduleOnRN,
+    // and the animation itself completes. The 512 cap itself stands.
+    let projectionCapRefused = false
+    const projectionGlobal = globalThis as ProjectionHostUiGlobal
+    if (projectionDriverId !== undefined && projectionComponentId !== undefined) {
+      if (projectionGlobal.__nativeMotionProjectionHostFrames === undefined)
+        projectionGlobal.__nativeMotionProjectionHostFrames = {}
+      if (projectionGlobal.__nativeMotionProjectionHostFrameOwners === undefined)
+        projectionGlobal.__nativeMotionProjectionHostFrameOwners = {}
+      if (
+        projectionGlobal.__nativeMotionProjectionHostFrameOwners[completionKey] === undefined &&
+        Object.keys(projectionGlobal.__nativeMotionProjectionHostFrameOwners).length >=
+          MAX_ACTIVE_PROJECTION_HOST_FRAMES
+      ) {
+        projectionCapRefused = true
+        if (onProjectionHostFrameCapRefusal !== undefined)
+          scheduleOnRN(onProjectionHostFrameCapRefusal, 'projection-host-frame-cap')
+      }
+    }
+    if (
+      !projectionCapRefused &&
+      projectionDriverId !== undefined &&
+      projectionComponentId !== undefined
+    ) {
+      // The ids-defined block above always initializes these maps first — asserted, never re-checked.
+      const hostFrames = projectionGlobal.__nativeMotionProjectionHostFrames!
+      const hostFrameOwners = projectionGlobal.__nativeMotionProjectionHostFrameOwners!
+      let driverFrames = hostFrames[projectionDriverId]
+      if (driverFrames === undefined) {
+        driverFrames = { nextGeneration: 0, frames: {} }
+        hostFrames[projectionDriverId] = driverFrames
+      }
+      driverFrames.nextGeneration += 1
+      projectionGeneration = driverFrames.nextGeneration
+      driverFrames.frames[projectionComponentId] = {
+        generation: projectionGeneration,
+        currentOriginX: channels === 'size' ? values.targetOriginX : values.currentOriginX,
+        currentOriginY: channels === 'size' ? values.targetOriginY : values.currentOriginY,
+        currentWidth: positionOnly ? values.targetWidth : values.currentWidth,
+        currentHeight: positionOnly ? values.targetHeight : values.currentHeight,
+        targetOriginX: values.targetOriginX,
+        targetOriginY: values.targetOriginY,
+        targetWidth: values.targetWidth,
+        targetHeight: values.targetHeight,
+        remainingChannels: projectionChannelCount,
+      }
+      hostFrameOwners[completionKey] = {
+        driverId: projectionDriverId,
+        componentId: projectionComponentId,
+        generation: projectionGeneration,
+      }
+      // Positive-delay channels do not enter onFrame until their hold expires. Seed the exact
+      // initial host rect now so targetless descendants counter-scale from the first painted
+      // hold frame instead of visibly inheriting the parent's inverted scale.
+      const projection =
+        projectionGlobal.__nativeMotionDrivers?.[projectionDriverId]?.layout?.projection
+      const frame = driverFrames.frames[projectionComponentId]
+      if (projection !== undefined && frame !== undefined) {
+        projection.tree.setHostFrame(
+          projectionComponentId,
+          frame.currentOriginX,
+          frame.currentOriginY,
+          frame.currentWidth,
+          frame.currentHeight,
+          frame.targetOriginX,
+          frame.targetOriginY,
+          frame.targetWidth,
+          frame.targetHeight,
+        )
+        projection.tree.project()
+        for (let index = 0; index < projection.records.length; index += 1) {
+          const record = projection.records[index]!
+          const output = projection.tree.output(record.componentId)
+          record.outputs.translateX.value = output.translateX
+          record.outputs.translateY.value = output.translateY
+          record.outputs.scaleX.value = output.scaleX
+          record.outputs.scaleY.value = output.scaleY
+          record.outputs.borderRadiusX.value = output.borderRadius?.x ?? Number.NaN
+          record.outputs.borderRadiusY.value = output.borderRadius?.y ?? Number.NaN
+        }
+        projection.dirty = false
+        // The commit edge drains the tree's stale-report ring too (iOS AUTO SIGABRT Phase 1.5):
+        // teardown races from superseded lanes surface through the RN severity channel.
+        reportStaleProjectionReports(projection, onStaleProjectionNodeRefusal)
+      }
+    }
+
+    // Reanimated owns the commit-hook lifecycle, so its terminal callback is the only faithful
+    // settle edge for `layout`. Cancellation and success both release the projection host record:
+    // a cancelled frame must not keep feeding obsolete geometry into a later tree traversal.
+    let completionDelivered = false
+    const callback =
+      onComplete === undefined
+        ? undefined
+        : (finished: boolean): void => {
+            'worklet'
+            // Seal-r15 F2 proof witnesses (primitive counters, never the channel under test;
+            // seal-r16 F2: only when the proof app armed the UI cells — zero-cost otherwise):
+            // invocations vs epoch-guard drops vs cancellations vs onComplete scheduled — each
+            // pair names a different dead link. No scheduleOnRN of proof helpers here: the
+            // worklet-closures gate forbids capturing non-worklet module functions; JS-side
+            // last-pushed cells are filled from MotionView.layoutCompletion.
+            const proofGlobal = globalThis as ProofLayoutCallbackUiGlobal
+            const proofArmed = proofGlobal.__nativeMotionProofWitnessArmed === true
+            if (proofArmed) {
+              proofGlobal.__nativeMotionProofLayoutCallbackInvocations =
+                (proofGlobal.__nativeMotionProofLayoutCallbackInvocations ?? 0) + 1
+            }
+            if (
+              flightEpoch === undefined ||
+              !isCurrentLayoutCompletionFlight(completionKey, flightEpoch)
+            ) {
+              if (proofArmed) {
+                proofGlobal.__nativeMotionProofLayoutCallbackEpochDrops =
+                  (proofGlobal.__nativeMotionProofLayoutCallbackEpochDrops ?? 0) + 1
+              }
+              return
+            }
+            // Same primitive-only rule as clearLayoutCompletionEpoch: nested worklet bodies must
+            // not call helper worklets. Cancel and success both release the host-frame registry
+            // AND clear the tree cell so cancelled mid-flight geometry cannot be re-projected.
+            const projectionGlobal = globalThis as ProjectionHostUiGlobal
+            const projectionOwner =
+              projectionGlobal.__nativeMotionProjectionHostFrameOwners?.[completionKey]
+            if (projectionOwner !== undefined) {
+              const projectionFrame =
+                projectionGlobal.__nativeMotionProjectionHostFrames?.[projectionOwner.driverId]
+                  ?.frames[projectionOwner.componentId]
+              if (
+                projectionFrame !== undefined &&
+                projectionFrame.generation === projectionOwner.generation
+              )
+                delete projectionGlobal.__nativeMotionProjectionHostFrames?.[
+                  projectionOwner.driverId
+                ]?.frames[projectionOwner.componentId]
+              delete projectionGlobal.__nativeMotionProjectionHostFrameOwners?.[completionKey]
+              const projection =
+                projectionGlobal.__nativeMotionDrivers?.[projectionOwner.driverId]?.layout
+                  ?.projection
+              if (projection !== undefined) {
+                projection.tree.clearProjection(projectionOwner.componentId)
+                projection.tree.project()
+                for (let index = 0; index < projection.records.length; index += 1) {
+                  const record = projection.records[index]!
+                  const output = projection.tree.output(record.componentId)
+                  record.outputs.translateX.value = output.translateX
+                  record.outputs.translateY.value = output.translateY
+                  record.outputs.scaleX.value = output.scaleX
+                  record.outputs.scaleY.value = output.scaleY
+                  record.outputs.borderRadiusX.value = output.borderRadius?.x ?? Number.NaN
+                  record.outputs.borderRadiusY.value = output.borderRadius?.y ?? Number.NaN
+                }
+                projection.dirty = false
+              }
+            }
+            if (!finished) {
+              if (proofArmed) {
+                proofGlobal.__nativeMotionProofLayoutCallbackCancelled =
+                  (proofGlobal.__nativeMotionProofLayoutCallbackCancelled ?? 0) + 1
+              }
+              completeLayoutCompletionFlight(completionKey, flightEpoch)
+              // Do not release the start ledger on cancel: a start-driven rerender rebuilds
+              // this worklet and Reanimated cancels the replaced animation — that rebound
+              // must not re-arm the public callback (device proof f841bc52). Settle also
+              // keeps the ledger (iOS 21e910d0 re-fire-at-settle). A later React generation
+              // overwrites; lifetime teardown still releases.
+              return
+            }
+            if (completionDelivered) return
+            completionDelivered = true
+            completeLayoutCompletionFlight(completionKey, flightEpoch)
+            // Do not release the start ledger on settle: Reanimated re-invokes this
+            // worklet at complete with the same React generation (iOS 21e910d0 flight A
+            // starts=2 at +2037,+5063). That is extra host-commit granularity, not a
+            // pin didUpdate. A later React generation overwrites the ledger in
+            // beginLayoutFlightStart. Teardown still releases.
+            if (proofArmed) {
+              proofGlobal.__nativeMotionProofLayoutOnCompleteScheduled =
+                (proofGlobal.__nativeMotionProofLayoutOnCompleteScheduled ?? 0) + 1
+            }
+            scheduleOnRN(onComplete)
+          }
+
+    if (positionOnly) {
+      const mirrorFlightGeneration = beginMirrorFlight(2)
+      return {
+        initialValues: {
+          originX: values.currentOriginX,
+          originY: values.currentOriginY,
+        },
+        animations: {
+          originX: coreLayoutChannel(
+            values.targetOriginX,
+            safeGeneratorConfig,
+            completionKey,
+            mirrorFlightGeneration,
+            projectionDriverId,
+            projectionComponentId,
+            projectionGeneration,
+            'originX',
+            onUnseededChannelRefusal,
+            onStaleProjectionNodeRefusal,
+          ),
+          originY: coreLayoutChannel(
+            values.targetOriginY,
+            safeGeneratorConfig,
+            completionKey,
+            mirrorFlightGeneration,
+            projectionDriverId,
+            projectionComponentId,
+            projectionGeneration,
+            'originY',
+            onUnseededChannelRefusal,
+            onStaleProjectionNodeRefusal,
+          ),
+        },
+        ...(callback === undefined ? {} : { callback }),
+      }
+    }
+
+    if (channels === 'size') {
+      const mirrorFlightGeneration = beginMirrorFlight(2)
+      return {
+        initialValues: {
+          width: values.currentWidth,
+          height: values.currentHeight,
+        },
+        animations: {
+          width: coreLayoutChannel(
+            values.targetWidth,
+            safeGeneratorConfig,
+            completionKey,
+            mirrorFlightGeneration,
+            projectionDriverId,
+            projectionComponentId,
+            projectionGeneration,
+            'width',
+            onUnseededChannelRefusal,
+            onStaleProjectionNodeRefusal,
+          ),
+          height: coreLayoutChannel(
+            values.targetHeight,
+            safeGeneratorConfig,
+            completionKey,
+            mirrorFlightGeneration,
+            projectionDriverId,
+            projectionComponentId,
+            projectionGeneration,
+            'height',
+            onUnseededChannelRefusal,
+            onStaleProjectionNodeRefusal,
+          ),
+        },
+        ...(callback === undefined ? {} : { callback }),
+      }
+    }
+
+    const mirrorFlightGeneration = beginMirrorFlight(4)
+    return {
+      initialValues: {
+        originX: values.currentOriginX,
+        originY: values.currentOriginY,
+        width: values.currentWidth,
+        height: values.currentHeight,
+      },
+      animations: {
+        originX: coreLayoutChannel(
+          values.targetOriginX,
+          safeGeneratorConfig,
+          completionKey,
+          mirrorFlightGeneration,
+          projectionDriverId,
+          projectionComponentId,
+          projectionGeneration,
+          'originX',
+          onUnseededChannelRefusal,
+          onStaleProjectionNodeRefusal,
+        ),
+        originY: coreLayoutChannel(
+          values.targetOriginY,
+          safeGeneratorConfig,
+          completionKey,
+          mirrorFlightGeneration,
+          projectionDriverId,
+          projectionComponentId,
+          projectionGeneration,
+          'originY',
+          onUnseededChannelRefusal,
+          onStaleProjectionNodeRefusal,
+        ),
+        width: coreLayoutChannel(
+          values.targetWidth,
+          safeGeneratorConfig,
+          completionKey,
+          mirrorFlightGeneration,
+          projectionDriverId,
+          projectionComponentId,
+          projectionGeneration,
+          'width',
+          onUnseededChannelRefusal,
+          onStaleProjectionNodeRefusal,
+        ),
+        height: coreLayoutChannel(
+          values.targetHeight,
+          safeGeneratorConfig,
+          completionKey,
+          mirrorFlightGeneration,
+          projectionDriverId,
+          projectionComponentId,
+          projectionGeneration,
+          'height',
+          onUnseededChannelRefusal,
+          onStaleProjectionNodeRefusal,
+        ),
+      },
+      ...(callback === undefined ? {} : { callback }),
+    }
+  }
+  layoutTransition.configureLayoutTransformMirrors = (enabled) => {
+    hasLayoutTransformMirrors = enabled
+  }
+  layoutTransition.configureProjectionHostFeed = (feed) => {
+    scheduleOnUI(
+      setProjectionHostFeedCellsOnUI,
+      projectionHostFeed.driverId,
+      projectionHostFeed.componentId,
+      feed?.driverId ?? -1,
+      feed?.componentId ?? '',
+    )
+  }
+  return layoutTransition
+}