@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/driver/uiLayoutEngine.ts

@@ -0,0 +1,845 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// The layout-identity engine the driver hosts on the UI runtime
+// (specs/LAYOUT-UITHREAD-PORT-BUILD-PACKET.md §Where the engine lives). RN-free like uiLayoutGraph
+// so vitest exercises the exact functions the UI runtime executes: workletDriver.ts owns the
+// crossings, shared-value creation, and the frame callback; this module owns the state machine —
+// holder outputs, lifecycle routing, the per-frame write set, and the exactly-once releasable
+// edge. Registry/session come from the file-tagged worklet-layout subpath ONLY (root-entry imports
+// inside UI worklets are the proven segfault trap).
+
+import {
+  createProjectionTree,
+  createLayoutIdentityRegistry,
+  type IdentityHolderHandle,
+  type IdentityHolderWrite,
+  type LayoutIdentityFlightOptions,
+  type LayoutIdentityRegistry,
+  type LayoutIdentityRole,
+  type LayoutIdToken,
+  type ProjectionTree,
+  type SpringConfig,
+  type TimingConfig,
+  type WindowSpaceRect,
+} from '@unrulysystems/native-motion-core/worklet-layout'
+import { createUiLayoutGraph, type UiLayoutGraph } from './uiLayoutGraph'
+
+// The .value cell contract shared with Reanimated's SharedValue<number> — the engine only ever
+// assigns .value, so vitest drives it with plain objects and the driver passes real shared values.
+export interface MutableNumber {
+  value: number
+}
+
+// One holder's per-frame outputs, in substrate terms (top-left anchored transform, crossfade
+// opacity, z-lift as 0/1 for zIndex/elevation mapping).
+export interface UiLayoutHolderOutputs {
+  readonly translateX: MutableNumber
+  readonly translateY: MutableNumber
+  readonly scaleX: MutableNumber
+  readonly scaleY: MutableNumber
+  readonly opacity: MutableNumber
+  readonly zLifted: MutableNumber
+}
+
+// Projection output is intentionally separate from layoutId holder output. Layout identity owns
+// shared-holder crossfades; this ledger owns component ancestry and parent-relative correction.
+// Both are consumed by MotionView's single animated-style mapper, so no per-frame JS crossing is
+// introduced when both capabilities coexist on one host.
+export interface UiProjectionOutputs {
+  readonly translateX: MutableNumber
+  readonly translateY: MutableNumber
+  readonly scaleX: MutableNumber
+  readonly scaleY: MutableNumber
+  // Reanimated accepts a two-axis percentage radius as a string, but the UI ledger stays numeric
+  // and lets the host mapper format it. NaN is the explicit "no corrected radius" sentinel.
+  readonly borderRadiusX: MutableNumber
+  readonly borderRadiusY: MutableNumber
+  // U7g (REQ-LAYOUT-024): pin scale-corrector context factors copied from the tree each frame.
+  readonly targetDeltaScaleX: MutableNumber
+  readonly targetDeltaScaleY: MutableNumber
+  readonly treeScaleX: MutableNumber
+  readonly treeScaleY: MutableNumber
+}
+
+interface UiProjectionRecord {
+  readonly componentId: string
+  readonly outputs: UiProjectionOutputs
+}
+
+// The layoutTransition flight registry's UI-global shape, mirrored structurally (this module
+// stays on the worklet-layout subpath only — root-entry imports inside UI worklets are the proven
+// segfault trap). Detach consults it to cancel a torn-down host's in-flight projection flight.
+interface ProjectionFlightRegistryUiGlobal {
+  __nativeMotionProjectionHostFrames?: Record<
+    number,
+    {
+      readonly nextGeneration: number
+      readonly frames: Record<string, { readonly generation: number }>
+    }
+  >
+  __nativeMotionProjectionHostFrameOwners?: Record<
+    number,
+    { readonly driverId: number; readonly componentId: string; readonly generation: number }
+  >
+}
+
+interface UiProjectionState {
+  readonly tree: ProjectionTree
+  readonly records: UiProjectionRecord[]
+  // Live radius feeds (seal r13, F4): an animated/gesture/bound radius channel's driver cell —
+  // the layout step reads it every frame so the tree's correction answers the CURRENT authored
+  // radius (read-current, seal r7 F5), not the mount-time flattened style. Lifecycle-edge only:
+  // attach/detach push and compact; the per-frame path reads by index.
+  readonly radiusFeeds: UiProjectionRadiusFeed[]
+  dirty: boolean
+}
+
+interface UiProjectionRadiusFeed {
+  readonly componentId: string
+  cell: MutableNumber
+  // The last value actually fed to the tree (null = never fed / fed null): the per-frame loop
+  // marks the step dirty only on a real transition, so a settled radius costs one compare.
+  lastFed: number | null
+}
+
+interface UiLayoutHolderRecord {
+  readonly id: string
+  readonly token: LayoutIdToken
+  // The enter()-minted pre-resolved handle: writeHolder's per-frame readInto dereferences it
+  // O(1) instead of re-resolving the token per painted holder per frame (round-7 major 4).
+  readonly handle: IdentityHolderHandle
+  readonly outputs: UiLayoutHolderOutputs
+  // The component-tree record that this holder's layoutId transform already paints. A lead writes
+  // its live transform into that tree so muggle descendants can correct it without applying the
+  // same FLIP transform a second time to the holder itself.
+  readonly projectionComponentId: string | null
+  // Latest common-space measurement for this mounted holder. The UI layer owns this narrow
+  // mirror because the core registry deliberately keeps holder geometry private; it lets the
+  // completion wire distinguish a comparable projection flight from a sole static commit.
+  rect: WindowSpaceRect | null
+  // Once this holder has been the current lead with a measured predecessor, its identity owns a
+  // real projection flight. It remains true through later retargets, but cannot make a holder
+  // current again after another token supersedes it.
+  ownsProjectionFlight: boolean
+}
+
+interface UiLayoutCoupling {
+  readonly id: string
+  readonly token: LayoutIdToken
+  readonly key: number
+  // Exactly-once latch: set on the emit frame so trailing frames (the callback runs until the
+  // RN-side settle edge lands) can never re-deliver, and the post-emit compaction needs no
+  // snapshot allocation (REQ-DRIVER-015).
+  fired: boolean
+}
+
+// Holders grouped per identity id: the per-frame write set is decided per ID (the registry's
+// settledness is per id), so one active flight touches only its own holders — not every mounted
+// holder on the driver (REQ-DRIVER-015's O(active) floor, review round 4 major 6).
+interface UiLayoutIdGroup {
+  readonly id: string
+  readonly records: UiLayoutHolderRecord[]
+  // `records` retains reverse-flight departures, so it cannot identify the current lead for an
+  // instant commit after the registry has already settled. This mirrors mounted membership only.
+  readonly currentTokens: LayoutIdToken[]
+  // Membership marker for `activeGroups` (the invariant: active ⟺ the group is in that list).
+  // True from any lifecycle edge (attach/commit/detach may open work) until a step observes the
+  // id settled AND has written the exact rest pose. While true the id joins the driver's
+  // in-flight accounting — REQ-LAYOUT-019: an unmeasured pending pairing has NO graph animation
+  // yet must hold the settle edge open (review round 4 major 4).
+  active: boolean
+}
+
+export interface UiLayoutState {
+  readonly graph: UiLayoutGraph
+  readonly registry: LayoutIdentityRegistry
+  // The owning worklet driver's identity: projection-flight cancellation at detach is scoped to
+  // it (seal r3, F4) — sibling drivers may host the same component ids.
+  readonly driverId: number
+  readonly groups: UiLayoutIdGroup[]
+  // The per-frame scan set (review round 5 major 1): groups enter at lifecycle edges and leave at
+  // their settle frame, so the frame loop walks O(active) groups — a settled mounted identity
+  // costs ZERO per-frame work, not even a flag check (REQ-DRIVER-015's O(active) floor).
+  readonly activeGroups: UiLayoutIdGroup[]
+  readonly couplings: UiLayoutCoupling[]
+  // Release keys emitted by a frame. The driver drains this primitive queue directly to the RN
+  // dispatcher so the UI frame never captures a nested release worklet. Capacity is prefilled at
+  // the coupling attach edge (couplings.length + releaseCount — each pending coupling fires at
+  // most once per frame); the frame writes `releaseKeys[releaseCount++]` and both drains reset
+  // only `releaseCount` (REQ-DRIVER-021: no in-frame push/truncation growth).
+  readonly releaseKeys: number[]
+  releaseCount: number
+  // The one per-frame read scratch: registry.readInto() refreshes it per painted holder — no
+  // IdentityRead/Transform records on the hot path (review round 5 major 2, REQ-DRIVER-015).
+  readonly read: IdentityHolderWrite
+  // Every Motion host joins this tree; only an actual layout participant contributes a delta.
+  // Keeping the tree beside the identity engine makes both paths UI-runtime resident and lets one
+  // frame callback produce all layout output before MotionView consumes its shared values.
+  readonly projection: UiProjectionState
+}
+
+// alloc-ok: construction — one layout slot per driver, created at first attach.
+// `driverId` scopes projection-flight cancellation at detach; -1 means no driver identity
+// (a bare engine harness — cancellation is then a no-op, never cross-driver).
+export function createUiLayoutState(spring?: SpringConfig, driverId = -1): UiLayoutState {
+  'worklet'
+  const graph = createUiLayoutGraph()
+  const registry = createLayoutIdentityRegistry({
+    graph,
+    ...(spring === undefined ? {} : { spring }),
+  })
+  return {
+    graph,
+    registry,
+    driverId,
+    groups: [],
+    activeGroups: [],
+    couplings: [],
+    releaseKeys: [],
+    releaseCount: 0,
+    read: { translateX: 0, translateY: 0, scaleX: 1, scaleY: 1, opacity: 0, zLifted: false },
+    // The frame-edge drain is this UI tree's declared report-delivery surface (seal r8, F2) —
+    // a callback cannot cross from the UI runtime, so the driver drains the ring onto the
+    // scheduleOnRN severity channel at every frame edge.
+    projection: {
+      tree: createProjectionTree({ delivery: 'drain' }),
+      records: [],
+      radiusFeeds: [],
+      dirty: false,
+    },
+  }
+}
+
+function projectionRecord(
+  state: UiProjectionState,
+  componentId: string,
+): UiProjectionRecord | undefined {
+  'worklet'
+  for (let index = 0; index < state.records.length; index += 1) {
+    const record = state.records[index]!
+    if (record.componentId === componentId) return record
+  }
+  return undefined
+}
+
+/** Register one Motion host in the UI-resident projection tree at mount. */
+export function uiProjectionAttach(
+  state: UiLayoutState,
+  componentId: string,
+  parentId: string | null,
+  outputs: UiProjectionOutputs,
+  projectionParticipant: boolean,
+  borderRadius: number | null = null,
+): void {
+  'worklet'
+  const existing = projectionRecord(state.projection, componentId)
+  if (existing !== undefined) {
+    // React's same-state rerender keeps the original UI output cells/live flight intact.
+    state.projection.tree.register(componentId, parentId, projectionParticipant)
+    state.projection.tree.setBorderRadius(componentId, borderRadius)
+    state.projection.dirty = true
+    return
+  }
+  state.projection.tree.register(componentId, parentId, projectionParticipant)
+  state.projection.tree.setBorderRadius(componentId, borderRadius)
+  // alloc-ok: lifecycle-edge — host mount; one projection record per componentId, never per frame.
+  state.projection.records.push({ componentId, outputs })
+  state.projection.dirty = true
+}
+
+/** Register, replace, or clear (null cell) a host's live radius feed (seal r13, F4). */
+export function uiSetProjectionRadiusFeed(
+  state: UiLayoutState,
+  componentId: string,
+  cell: MutableNumber | null,
+): void {
+  'worklet'
+  for (let index = 0; index < state.projection.radiusFeeds.length; index += 1) {
+    const feed = state.projection.radiusFeeds[index]!
+    if (feed.componentId !== componentId) continue
+    if (cell === null) {
+      // Write-index-free single removal at a lifecycle edge: swap-remove keeps the loop
+      // allocation-free (a radius channel disappearing clears the feed — the tree's radius
+      // then answers only the attach-time static, and the next frame's null transition marks
+      // the correction null through lastFed).
+      feed.lastFed = null
+      state.projection.radiusFeeds[index] =
+        state.projection.radiusFeeds[state.projection.radiusFeeds.length - 1]!
+      state.projection.radiusFeeds.length -= 1
+      state.projection.tree.setBorderRadius(componentId, null)
+      state.projection.dirty = true
+      return
+    }
+    feed.cell = cell
+    return
+  }
+  if (cell === null) return
+  // alloc-ok: lifecycle-edge — one feed per hosted radius channel, never per frame.
+  state.projection.radiusFeeds.push({ componentId, cell, lastFed: null })
+}
+
+/** Remove a host after its descendants have detached; core asserts invalid tree teardown loudly.
+ * alloc-ok: lifecycle-edge — host detach; the owner-registry scan (Object.keys + the loop)
+ * runs only at teardown, never per frame. */
+export function uiProjectionDetach(state: UiLayoutState, componentId: string): void {
+  'worklet'
+  state.projection.tree.unregister(componentId)
+  // Cancel the detached host's in-flight projection flight (iOS AUTO SIGABRT Phase 1.5): its
+  // host-frame record and completion owner are deleted HERE, so the next channel frame observes
+  // the vanished record and retires at that frame boundary — no further frames are scheduled
+  // for the torn-down host, and no stale setHostFrame can fire into the unregistered node.
+  // Scoped to THIS driver's identity (seal r3, F4): distinct drivers may legally host the same
+  // component id, and a detach must never cancel a sibling driver's live flight.
+  const registry = globalThis as ProjectionFlightRegistryUiGlobal
+  const owners = registry.__nativeMotionProjectionHostFrameOwners
+  if (owners !== undefined) {
+    for (const key of Object.keys(owners)) {
+      const ownerKey = Number(key)
+      const owner = owners[ownerKey]!
+      if (owner.componentId !== componentId || owner.driverId !== state.driverId) continue
+      const driverFrames = registry.__nativeMotionProjectionHostFrames?.[owner.driverId]
+      if (
+        driverFrames !== undefined &&
+        driverFrames.frames[componentId]?.generation === owner.generation
+      ) {
+        delete driverFrames.frames[componentId]
+      }
+      delete owners[ownerKey]
+    }
+  }
+  let writeIndex = 0
+  for (let index = 0; index < state.projection.records.length; index += 1) {
+    const record = state.projection.records[index]!
+    if (record.componentId !== componentId) {
+      state.projection.records[writeIndex] = record
+      writeIndex += 1
+    }
+  }
+  state.projection.records.length = writeIndex
+  // The host's live radius feed leaves with its node (seal r13, F4) — same lifecycle-edge
+  // compaction discipline as the records above.
+  let feedWriteIndex = 0
+  for (let index = 0; index < state.projection.radiusFeeds.length; index += 1) {
+    const feed = state.projection.radiusFeeds[index]!
+    if (feed.componentId !== componentId) {
+      state.projection.radiusFeeds[feedWriteIndex] = feed
+      feedWriteIndex += 1
+    }
+  }
+  state.projection.radiusFeeds.length = feedWriteIndex
+  state.projection.dirty = true
+}
+
+/** Feed a host-layout FLIP sample into the tree; source/target are already same-frame rects. */
+export function uiProjectionSetProjection(
+  state: UiLayoutState,
+  componentId: string,
+  source: {
+    readonly x: number
+    readonly y: number
+    readonly width: number
+    readonly height: number
+  },
+  target: {
+    readonly x: number
+    readonly y: number
+    readonly width: number
+    readonly height: number
+  },
+  progress: number,
+): void {
+  'worklet'
+  state.projection.tree.setProjection(componentId, source, target, progress)
+  state.projection.dirty = true
+}
+
+/**
+ * Feed the host's CURRENT layout-animation frame into the projection tree. Reanimated owns the
+ * easing and may retarget an in-flight channel, so deriving progress on the JS thread would both
+ * skew the visual frame and add a forbidden crossing. The tree treats this as a host-painted
+ * frame: it carries parent-relative geometry to descendants without replaying the host FLIP.
+ */
+export function uiProjectionSetHostFrame(
+  state: UiLayoutState,
+  componentId: string,
+  current: {
+    readonly x: number
+    readonly y: number
+    readonly width: number
+    readonly height: number
+  },
+  target: {
+    readonly x: number
+    readonly y: number
+    readonly width: number
+    readonly height: number
+  },
+): void {
+  'worklet'
+  state.projection.tree.setHostFrame(
+    componentId,
+    current.x,
+    current.y,
+    current.width,
+    current.height,
+    target.x,
+    target.y,
+    target.width,
+    target.height,
+  )
+  state.projection.dirty = true
+}
+
+function uiProjectionStep(state: UiProjectionState): boolean {
+  'worklet'
+  // Live radius feeds (seal r13, F4): the property driver's step already advanced these cells
+  // this frame (uiStepAll runs before the layout step in the same frame callback), so the
+  // tree's correction answers the frame-CURRENT authored/driver radius — read-current
+  // ownership (seal r7, F5). A non-finite or negative value feeds null (the "no corrected
+  // radius" sentinel — the authored radius is retained, never a bogus correction). Unchanged
+  // cells never mark the step dirty: a settled radius costs one compare per frame.
+  for (let index = 0; index < state.radiusFeeds.length; index += 1) {
+    const feed = state.radiusFeeds[index]!
+    const current = feed.cell.value
+    const fed = Number.isFinite(current) && current >= 0 ? current : null
+    if (fed !== feed.lastFed) {
+      feed.lastFed = fed
+      state.tree.setBorderRadius(feed.componentId, fed)
+      state.dirty = true
+    }
+  }
+  if (!state.dirty) return false
+  state.tree.project()
+  // No nested visitor worklet: the tree and output cells are UI-global state. Iteration occurs
+  // after the tree's depth-ordered calculation so every record reads its coherent final output.
+  for (let index = 0; index < state.records.length; index += 1) {
+    const record = state.records[index]!
+    const output = state.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
+    record.outputs.targetDeltaScaleX.value = output.targetDeltaScaleX
+    record.outputs.targetDeltaScaleY.value = output.targetDeltaScaleY
+    record.outputs.treeScaleX.value = output.treeScaleX
+    record.outputs.treeScaleY.value = output.treeScaleY
+  }
+  state.dirty = false
+  return true
+}
+
+// alloc-ok: lifecycle-edge — attach/commit/detach lookups only; the per-frame scan walks
+// state.activeGroups by index.
+function findGroup(state: UiLayoutState, id: string): UiLayoutIdGroup | undefined {
+  'worklet'
+  for (const group of state.groups) if (group.id === id) return group
+  return undefined
+}
+
+// alloc-ok: lifecycle-edge — get-or-create at attach only.
+function groupOf(state: UiLayoutState, id: string): UiLayoutIdGroup {
+  'worklet'
+  const existing = findGroup(state, id)
+  if (existing !== undefined) return existing
+  // Created INACTIVE: every lifecycle edge activates through activateGroup so the active flag
+  // and the activeGroups membership can never skew.
+  const group: UiLayoutIdGroup = { id, records: [], currentTokens: [], active: false }
+  state.groups.push(group)
+  return group
+}
+
+// The ONLY writer of `active: true` — the flag mirrors activeGroups membership, so a re-activated
+// already-active group must not double-enter the scan set (the step would write it twice).
+function activateGroup(state: UiLayoutState, group: UiLayoutIdGroup): void {
+  'worklet'
+  if (group.active) return
+  group.active = true
+  state.activeGroups.push(group)
+}
+
+// Drop a group from the scan set at a non-step edge (a detach that empties the id). Write-index
+// compaction — splice allocates its removed-elements array (REQ-DRIVER-015).
+function deactivateGroup(state: UiLayoutState, group: UiLayoutIdGroup): void {
+  'worklet'
+  if (!group.active) return
+  group.active = false
+  let w = 0
+  for (let i = 0; i < state.activeGroups.length; i++) {
+    const g = state.activeGroups[i]!
+    if (g !== group) {
+      state.activeGroups[w] = g
+      w += 1
+    }
+  }
+  state.activeGroups.length = w
+}
+
+function writeHolder(state: UiLayoutState, record: UiLayoutHolderRecord): void {
+  'worklet'
+  // One registry call, zero allocation: readInto refreshes the state's scratch in place
+  // (read()+zLifted() built three records and evaluated the settle check twice per holder).
+  state.registry.readInto(record.handle, state.read)
+  record.outputs.translateX.value = state.read.translateX
+  record.outputs.translateY.value = state.read.translateY
+  record.outputs.scaleX.value = state.read.scaleX
+  record.outputs.scaleY.value = state.read.scaleY
+  record.outputs.opacity.value = state.read.opacity
+  record.outputs.zLifted.value = state.read.zLifted ? 1 : 0
+  // Only a true projection lead publishes into the tree. Sole/non-lead holders must remain
+  // muggle conduits (frameTreeCenterOffset / treeScale pass-through); identity setDirectProjection
+  // would force projectionPaintedByHost and break descendant counter-scale (review major
+  // c4f8a2b19e70).
+  if (record.projectionComponentId !== null && record.ownsProjectionFlight) {
+    state.projection.tree.setDirectProjection(
+      record.projectionComponentId,
+      state.read.translateX,
+      state.read.translateY,
+      state.read.scaleX,
+      state.read.scaleY,
+    )
+    state.projection.dirty = true
+  }
+}
+
+// Drop output records the registry no longer tracks (holds() false edge). Membership only
+// changes through leave() — a trailing leave, the second leave of an exiting holder, or a full
+// id drop — so pruning runs at the detach edge, never per frame. Write-index compaction: splice
+// allocates its removed-elements array, which is banned on the UI hot path (REQ-DRIVER-015).
+function pruneDepartedRecords(state: UiLayoutState, group: UiLayoutIdGroup): void {
+  'worklet'
+  let w = 0
+  for (let i = 0; i < group.records.length; i++) {
+    const record = group.records[i]!
+    if (state.registry.holds(record.id, record.token)) {
+      group.records[w] = record
+      w += 1
+    }
+  }
+  group.records.length = w
+}
+
+// U6 W4 verification witness (the device proof cards' crossfade row): the LIVE painted opacity
+// of every record the identity still holds — the mounted lead AND an exiting retained follower,
+// never a departed ghost (pruneDepartedRecords keeps records exactly while the registry holds
+// them). Reads the cells the frame loop writes, so the witness is what the holders paint.
+// alloc-ok: lifecycle-edge — sampled by verification screens at timer edges, never the per-frame path.
+export function uiLayoutOpacityWitness(
+  state: UiLayoutState,
+  id: string,
+): { token: string; opacity: number }[] {
+  'worklet'
+  const group = findGroup(state, id)
+  if (group === undefined) return []
+  const witness: { token: string; opacity: number }[] = []
+  for (let i = 0; i < group.records.length; i++) {
+    const record = group.records[i]!
+    witness.push({ token: String(record.token), opacity: record.outputs.opacity.value })
+  }
+  return witness
+}
+
+function removeCurrentToken(group: UiLayoutIdGroup, token: LayoutIdToken): void {
+  'worklet'
+  let writeIndex = 0
+  for (let index = 0; index < group.currentTokens.length; index += 1) {
+    const current = group.currentTokens[index]!
+    if (current !== token) {
+      group.currentTokens[writeIndex] = current
+      writeIndex += 1
+    }
+  }
+  group.currentTokens.length = writeIndex
+}
+
+// A current lead can project only from a measured current predecessor. Exiting records are not
+// candidates: core's holder stack has already removed them, so their geometry cannot start this
+// mounted holder's flight.
+function hasMeasuredCurrentPredecessor(group: UiLayoutIdGroup, token: LayoutIdToken): boolean {
+  'worklet'
+  for (let currentIndex = 0; currentIndex < group.currentTokens.length; currentIndex += 1) {
+    const currentToken = group.currentTokens[currentIndex]!
+    if (currentToken === token) continue
+    for (let recordIndex = 0; recordIndex < group.records.length; recordIndex += 1) {
+      const record = group.records[recordIndex]!
+      if (record.token === currentToken && record.rect !== null) return true
+    }
+  }
+  return false
+}
+
+function recordFor(group: UiLayoutIdGroup, token: LayoutIdToken): UiLayoutHolderRecord | undefined {
+  'worklet'
+  for (let index = 0; index < group.records.length; index += 1) {
+    const record = group.records[index]!
+    if (record.token === token) return record
+  }
+  return undefined
+}
+
+// Shared constants so lifecycle edges never allocate a fresh options object (REQ-DRIVER-021).
+const INSTANT_FLIGHT = Object.freeze({ instant: true as const })
+// Empty options bag: core treats `options !== undefined` without timing as clear-to-spring
+// (identity commitRect read-current law). Distinct from omitted options (retain live mode).
+const CLEAR_FLIGHT = Object.freeze({}) as LayoutIdentityFlightOptions
+
+/**
+ * Build registry flight options from primitive edge args (worklet-safe; no options object close-over).
+ * alloc-ok: lifecycle-edge — attach/commit/detach only; never per frame.
+ *
+ * `optionsPresent` preserves the core tri-state (tjynor 6a42f09de8c1, T22 spring alike):
+ * - false → omit options (retain live session config)
+ * - true + timing/spring null → empty options (clear authored config → default spring)
+ * - true + timing OR spring → set that flight config (single-outcome upstream, L1)
+ */
+function flightOptions(
+  instant: boolean,
+  timing: TimingConfig | null,
+  spring: SpringConfig | null,
+  optionsPresent: boolean,
+): LayoutIdentityFlightOptions | undefined {
+  'worklet'
+  if (!optionsPresent) return undefined
+  if (timing !== null && spring !== null) {
+    // Malformed pair (review r2 minor 2): pass BOTH through — the registry's
+    // assertSingleFlightMode owns the fail-loud rejection (single-flight-mode law); a
+    // preference here would silently drop one config.
+    return instant ? { instant: true, timing, spring } : { timing, spring }
+  }
+  if (instant && timing === null && spring === null) return INSTANT_FLIGHT
+  if (instant)
+    return timing !== null ? { instant: true, timing } : { instant: true, spring: spring! }
+  if (timing !== null) return { timing }
+  if (spring !== null) return { spring }
+  return CLEAR_FLIGHT
+}
+
+// alloc-ok: lifecycle-edge — holder mount; builds the holder record once.
+// `instant` (REQ-API-035): settle the shared flight + crossfade on this edge under MotionConfig
+// reducedMotion / skipAnimations / isStatic — pin type:false, no multi-frame layoutId flight.
+// `timing` (family-3): duration/ease tween for the shared projection flight when authored.
+// `optionsPresent` (family-3): JS edge restated policy (even when timing is cleared).
+export function uiLayoutAttach(
+  state: UiLayoutState,
+  id: string,
+  token: LayoutIdToken,
+  rect: WindowSpaceRect | null,
+  outputs: UiLayoutHolderOutputs,
+  instant = false,
+  projectionComponentId: string | null = null,
+  timing: TimingConfig | null = null,
+  spring: SpringConfig | null = null,
+  optionsPresent = false,
+): LayoutIdentityRole {
+  'worklet'
+  const opts = flightOptions(instant, timing, spring, optionsPresent)
+  const { role, handle } =
+    opts === undefined
+      ? state.registry.enter(id, token, rect)
+      : state.registry.enter(id, token, rect, opts)
+  const group = groupOf(state, id)
+  const record: UiLayoutHolderRecord = {
+    id,
+    token,
+    handle,
+    outputs,
+    projectionComponentId,
+    rect,
+    // Lead owns the projection flight. Exclusive remount handoff is lead without concurrent
+    // predecessor records in the UI group (core registry handoff), so do not require a measured
+    // group predecessor — that would leave ownsProjectionFlight false and starve completion.
+    ownsProjectionFlight: role === 'lead',
+  }
+  group.records.push(record)
+  group.currentTokens.push(token)
+  activateGroup(state, group) // an entering pairing may open a flight — or a pending measurement
+  writeHolder(state, record) // paint the mount frame — attach must not wait for the next step
+  return role
+}
+
+// alloc-ok: lifecycle-edge — lead commit only; the optional flight-options object is not per-frame.
+export function uiLayoutCommit(
+  state: UiLayoutState,
+  id: string,
+  token: LayoutIdToken,
+  rect: WindowSpaceRect,
+  instant = false,
+  timing: TimingConfig | null = null,
+  spring: SpringConfig | null = null,
+  optionsPresent = false,
+): boolean {
+  'worklet'
+  const group = findGroup(state, id)
+  const record = group === undefined ? undefined : recordFor(group, token)
+  const currentLead = group?.currentTokens[group.currentTokens.length - 1] === token
+  // Mirror the core's actual geometry precondition before it receives this measured edge. A
+  // sole holder (or a current lead whose predecessors never measured) has no comparable rect to
+  // project from; force-instant changes timing only and must not convert that static commit into
+  // layout-completion ownership.
+  if (record !== undefined) {
+    record.rect = rect
+    if (currentLead && hasMeasuredCurrentPredecessor(group!, token)) {
+      record.ownsProjectionFlight = true
+    }
+  }
+  // fail-loud first: unknown ids/holders never mark work. Flight options only on edges.
+  const opts = flightOptions(instant, timing, spring, optionsPresent)
+  if (opts === undefined) state.registry.commitRect(id, token, rect)
+  else state.registry.commitRect(id, token, rect, opts)
+  if (group !== undefined) activateGroup(state, group) // a lead commit starts or retargets the flight
+  return currentLead && record?.ownsProjectionFlight === true
+}
+
+// alloc-ok: lifecycle-edge — holder unmount; the optional flight-options object is not per-frame.
+export function uiLayoutDetach(
+  state: UiLayoutState,
+  id: string,
+  token: LayoutIdToken,
+  instant = false,
+  timing: TimingConfig | null = null,
+  spring: SpringConfig | null = null,
+  optionsPresent = false,
+): void {
+  'worklet'
+  const opts = flightOptions(instant, timing, spring, optionsPresent)
+  if (opts === undefined) state.registry.leave(id, token)
+  else state.registry.leave(id, token, opts)
+  const group = findGroup(state, id)
+  if (group === undefined) return // leave() throws for unknown ids — nothing tracked here
+  removeCurrentToken(group, token)
+  pruneDepartedRecords(state, group)
+  if (group.records.length === 0) {
+    // No painted holders left for this id: drop the group — from the scan set FIRST (a stale
+    // active entry would be stepped against a registry that no longer tracks the id), then from
+    // the mounted list (write-index compaction, see above).
+    deactivateGroup(state, group)
+    let w = 0
+    for (let i = 0; i < state.groups.length; i++) {
+      const g = state.groups[i]!
+      if (g !== group) {
+        state.groups[w] = g
+        w += 1
+      }
+    }
+    state.groups.length = w
+    return
+  }
+  activateGroup(state, group) // a lead leaving begins the reverse flight / crossfade
+}
+
+// Register a releasable→safeToRemove coupling. Checked against the registry AT registration on
+// the UI runtime: a holder that is already releasable emits NOW instead of storing — a stored
+// coupling with no frames scheduled would strand the callback (the immediate-release frontier,
+// L2 review cycle 3 major 7, re-checked here because the JS-side pre-check races the scheduled
+// registration).
+// alloc-ok: lifecycle-edge — release-coupling registration at the presence edge.
+export function uiLayoutCouple(
+  state: UiLayoutState,
+  id: string,
+  token: LayoutIdToken,
+  key: number,
+  emitRelease: (key: number) => void,
+): void {
+  'worklet'
+  if (state.registry.releasable(id, token)) {
+    emitRelease(key)
+    return
+  }
+  state.couplings.push({ id, token, key, fired: false })
+  // Prefill release capacity at the lifecycle edge (alloc-ok): a frame can emit at most one key
+  // per pending coupling on top of any not-yet-drained residue, so
+  // capacity >= couplings.length + releaseCount keeps every in-frame indexed write in bounds.
+  const required = state.couplings.length + state.releaseCount
+  if (required > state.releaseKeys.length) state.releaseKeys[required - 1] = 0
+}
+
+export function uiLayoutUncouple(state: UiLayoutState, key: number): void {
+  'worklet'
+  let w = 0
+  for (let i = 0; i < state.couplings.length; i++) {
+    const coupling = state.couplings[i]!
+    if (coupling.key !== key) {
+      state.couplings[w] = coupling
+      w += 1
+    }
+  }
+  state.couplings.length = w
+}
+
+// The driver's in-flight accounting for the layout engine: graph work OR any id not yet observed
+// settled. REQ-LAYOUT-019 — the registry's settledness (which holds an unmeasured pending pairing
+// open) is part of this answer, never the graph alone. Used by the frame step's return AND the
+// RN-side settle-edge re-check, so both consult one definition.
+export function uiLayoutActive(state: UiLayoutState): boolean {
+  'worklet'
+  // O(1): activeGroups IS the in-flight id set — no scan over mounted groups (round 5 major 1).
+  return state.activeGroups.length > 0 || !state.graph.isSettled()
+}
+
+// One frame: advance the layout graph, refresh the ACTIVE ids' holder outputs, then carry any
+// releasable edges. Returns whether the layout engine still has in-flight work (joins the
+// driver's REQ-DRIVER-020 settle edge). Hot-path discipline (REQ-DRIVER-015): no allocation on
+// any per-frame path — write-index compaction instead of splice/snapshot copies — and per-frame
+// work scales with ACTIVE identities only: the loop walks activeGroups, so a settled mounted id
+// is not even flag-checked (an id's holders are written while it is in flight plus one final
+// rest-pose frame at its settle edge, where it leaves the scan set).
+export function uiLayoutStep(state: UiLayoutState, dtMs: number): boolean {
+  'worklet'
+  // Age exclusive-remount handoffs before graph step so a same-commit successor attach
+  // (onLayout deferred to this frame) still sees the handoff, while long-delayed remounts expire.
+  state.registry.tickExclusiveHandoffs()
+  state.graph.frame(dtMs)
+  let w = 0
+  for (let i = 0; i < state.activeGroups.length; i++) {
+    const group = state.activeGroups[i]!
+    const settled = state.registry.isSettled(group.id)
+    // Write while unsettled AND on the settle frame itself — the flip frame lands the exact rest
+    // pose (identity transform, opacity 1, z-lift 0); afterwards the id costs nothing per frame.
+    // Indexed loops throughout the frame path: for..of allocates its iterator on Hermes.
+    for (let r = 0; r < group.records.length; r++) writeHolder(state, group.records[r]!)
+    if (settled) group.active = false
+    else {
+      state.activeGroups[w] = group
+      w += 1
+    }
+  }
+  state.activeGroups.length = w
+  // Holder writes update direct layoutId transforms first; the tree projects only after every
+  // current lead published its frame, so a targetless descendant observes that same UI frame.
+  const projectionWrote = uiProjectionStep(state.projection)
+  const anyActive = w > 0
+  // The fired latch (not removal order) carries exactly-once: the frame callback keeps running
+  // until the RN-side settle edge lands, and an unlatched coupling would re-emit on every
+  // trailing frame — duplicate safeToRemove deliveries, the fail-open the live-leg review round
+  // established (2026-07-09). Keys are queued for the driver to cross directly via scheduleOnRN,
+  // avoiding a nested worklet closure inside the UI frame's serialized graph.
+  let anyFired = false
+  for (let i = 0; i < state.couplings.length; i++) {
+    const coupling = state.couplings[i]!
+    if (coupling.fired) continue
+    if (!state.registry.releasable(coupling.id, coupling.token)) continue
+    coupling.fired = true
+    anyFired = true
+    state.releaseKeys[state.releaseCount] = coupling.key
+    state.releaseCount += 1
+  }
+  if (anyFired) {
+    let w = 0
+    for (let i = 0; i < state.couplings.length; i++) {
+      const coupling = state.couplings[i]!
+      if (!coupling.fired) {
+        state.couplings[w] = coupling
+        w += 1
+      }
+    }
+    state.couplings.length = w
+  }
+  // Keep the frame loop alive while exclusive-remount handoffs age out (no active group after
+  // sole leave would otherwise stop steps before the 8-frame grace completes).
+  return (
+    projectionWrote ||
+    anyActive ||
+    !state.graph.isSettled() ||
+    state.registry.hasPendingExclusiveHandoffs()
+  )
+}