@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/keyframeTiming.ts

@@ -0,0 +1,7 @@
+// The keyframe timing cross-field law is owned by CORE's raw Driver.command preparation boundary.
+// Native supplying lanes import it only through the deliberately gated internal-driver subpath, so the
+// controller, gesture, variant, presence, reference driver, and worklet driver cannot drift apart.
+export {
+  keyframeTimingRefusal,
+  keyframeTransitionRefusal,
+} from '@unrulysystems/native-motion-core/internal-driver'

package/src/native/motion/layoutIdBinding.ts

@@ -0,0 +1,261 @@
+// The layoutId binding's brain (specs/LAYOUT-UITHREAD-PORT-BUILD-PACKET.md §The binding after the
+// port): RN-side wiring for core's layout-identity registry, whose per-frame engine now lives in
+// the DRIVER's UI-runtime state (`WorkletDriverBinding.layout`). This layer owns only (a) fail-loud
+// onLayout rect validation (the M2.5 posture, reused not forked), (b) attach/commit/detach routing
+// so a mounting RN view enters unmeasured and its first commitLayout supplies the rect, and (c) the
+// holder-output handoff: screens bind animated styles to `sharedViewFor` shared values the UI
+// frame loop writes — there is no per-frame JS read and no JS stepper anymore. The
+// releasable→safeToRemove coupling AnimatePresence consumes rides the driver's exactly-once
+// release edge (PRESENCE owns the mounted lifetime; the registry only reports when the crossfade
+// is done with the element).
+
+import { toWindowSpaceRect, type WindowSpaceRect } from '@unrulysystems/native-motion-core'
+import type {
+  LayoutIdentityRole,
+  LayoutIdToken,
+} from '@unrulysystems/native-motion-core/worklet-layout'
+import type {
+  LayoutIdentityHolderOpacityWitness,
+  LayoutIdentityHolderShared,
+  WorkletDriverBinding,
+} from '../driver/workletDriver'
+import { toValidatedLayoutRect, type LayoutRectShape } from './layoutProjection'
+
+export interface LayoutIdentityMeasureHandle {
+  readonly measureInWindow: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void
+}
+
+export type LayoutIdentityMeasureInput = LayoutIdentityMeasureHandle | WindowSpaceRect
+
+/** Per-edge options for layout-identity lifecycle (REQ-API-035 MotionConfig → layoutId lane). */
+export interface LayoutIdentityBindingOptions {
+  readonly instant?: boolean
+  /** Stable component-tree address of the host whose live layoutId transform is being painted. */
+  readonly projectionComponentId?: string
+  /**
+   * Family-3 layoutId transition: duration/ease tween for the shared projection flight
+   * (TimingConfig is ms). Host maps authored seconds via toTimingConfig before this edge.
+   */
+  readonly timing?: import('@unrulysystems/native-motion-core').TimingConfig
+  /**
+   * T22 layoutId transition: per-flight spring (engine SpringConfig ms — physics or
+   * time-defined). Mutually exclusive with `timing` (single-outcome resolver, L1).
+   */
+  readonly spring?: import('@unrulysystems/native-motion-core').SpringConfig
+}
+
+export interface LayoutIdentityBinding {
+  /** Root driver that owns this identity registry and its shared projection tree. */
+  readonly projectionBinding?: WorkletDriverBinding
+  // A view begins holding `id`. Real RN holders pass a host handle; deterministic check screens may
+  // pass an already-branded synthetic common-space rect. Raw onLayout rects are not accepted.
+  attach(
+    id: string,
+    token: LayoutIdToken,
+    measure?: LayoutIdentityMeasureInput | null,
+    options?: LayoutIdentityBindingOptions,
+  ): LayoutIdentityRole
+  // Feed one host handle or branded synthetic rect that can provide a common-space measurement.
+  // Malformed measured fields fail loud naming the field — never coerced (M2.5 §semantics 6 posture).
+  commitLayout(
+    id: string,
+    token: LayoutIdToken,
+    measure: LayoutIdentityMeasureInput,
+    options?: LayoutIdentityBindingOptions,
+    onMeasuredCommit?: (startedFlight: boolean) => void,
+  ): void
+  // One holder's animated-style outputs, written by the UI frame loop (transform, opacity, z-lift
+  // as 0/1). Replaces the deleted per-frame JS `view()` read.
+  sharedViewFor(id: string, token: LayoutIdToken): LayoutIdentityHolderShared
+  // U6 W4 verification witness (the device proof cards' crossfade row): the live painted opacity
+  // of every holder record the identity still holds (mounted lead + exiting retained follower).
+  opacityWitnessFor(id: string): readonly LayoutIdentityHolderOpacityWitness[]
+  // Stop holding. A lead detaching begins the reverse flight and rides as exiting until
+  // releasable; detaching again (or after settle) completes the removal — registry `leave`
+  // semantics verbatim.
+  // Returns whether this detach retained the holder as an exiting record. A trailing or sole
+  // holder drops immediately; a leading reverse flight remains held until its terminal detach.
+  detach(id: string, token: LayoutIdToken, options?: LayoutIdentityBindingOptions): boolean
+  releasable(id: string, token: LayoutIdToken): boolean
+  isSettled(id: string): boolean
+  // Registry membership (holders ∪ exiting). Presence beginExit peeks before detach.
+  holds(id: string, token: LayoutIdToken): boolean
+  // True while this token is the current lead. Trailing followers of a live flight are false.
+  isLead(id: string, token: LayoutIdToken): boolean
+  subscribeSettled(id: string, onSettled: () => void): () => void
+  // Couple an exiting holder's release to a presence callback: fires EXACTLY ONCE when the
+  // registry reports the crossfade is done with the holder (driver-owned first-report-wins latch;
+  // an already-releasable holder fires at registration). Returns an uncouple for
+  // unmount-before-settle.
+  coupleRelease(id: string, token: LayoutIdToken, safeToRemove: () => void): () => void
+}
+
+function isMeasureHandle(input: LayoutIdentityMeasureInput): input is LayoutIdentityMeasureHandle {
+  return (
+    typeof input === 'object' &&
+    input !== null &&
+    'measureInWindow' in input &&
+    typeof input.measureInWindow === 'function'
+  )
+}
+
+function toValidatedWindowSpaceRect(rect: LayoutRectShape): WindowSpaceRect {
+  return toWindowSpaceRect(toValidatedLayoutRect(rect))
+}
+
+// REQ-LAYOUT-011/016/019: a host read ahead of the view's first layout pass reports a 0×0 window
+// rect — the native null read. It is not a registry rect: skip the commit so the holder stays
+// unmeasured (identity transform + unsettled) and the next layout epoch re-enters the measure.
+// Never coerced into a projection and never thrown through the host callback (the 2026-09-08 r2
+// walk FATAL). Non-finite fields remain a loud caller/host defect via toValidatedLayoutRect.
+function isNotYetLaidOut(rect: LayoutRectShape): boolean {
+  return (
+    typeof rect.width === 'number' &&
+    Number.isFinite(rect.width) &&
+    typeof rect.height === 'number' &&
+    Number.isFinite(rect.height) &&
+    (rect.width <= 0 || rect.height <= 0)
+  )
+}
+
+function requestWindowSpaceMeasure(
+  input: LayoutIdentityMeasureInput,
+  commit: (rect: WindowSpaceRect) => void,
+): void {
+  if (!isMeasureHandle(input)) {
+    commit(input)
+    return
+  }
+  input.measureInWindow((x, y, width, height) => {
+    const rect = { x, y, width, height }
+    if (isNotYetLaidOut(rect)) return
+    commit(toValidatedWindowSpaceRect(rect))
+  })
+}
+
+// The binding is created over a live or manual `WorkletDriverBinding` (the driver hook/factory the
+// screen already owns); the flight spring is the driver's `layoutSpring` option — one config per
+// driver, fixed at the layout slot's creation.
+export function createLayoutIdentityBinding(driver: WorkletDriverBinding): LayoutIdentityBinding {
+  const layout = driver.layout
+
+  // Each measurement request mints a JS-side epoch. Async host measurements capture this object,
+  // so a newer request, detach, or detach→reattach invalidates only that holder's older pending
+  // work. The driver remains fail-loud for direct constructive commits; this gate handles solely
+  // the stale completion class that cannot safely throw from a host callback (REQ-LAYOUT-016/018).
+  const measurementEpochs = new Map<LayoutIdToken, { readonly id: string }>()
+
+  const commitIfCurrent = (
+    epoch: { readonly id: string },
+    token: LayoutIdToken,
+    measured: WindowSpaceRect,
+    options?: LayoutIdentityBindingOptions,
+    onMeasuredCommit?: (startedFlight: boolean) => void,
+  ): void => {
+    if (measurementEpochs.get(token) !== epoch) return
+    // A host measurement can arrive in a later JS turn. Read the flight edge at the actual
+    // driver commit, rather than at the earlier onLayout request, so a mounted retarget cannot
+    // lose its completion arm while measureInWindow is pending. Callers without lifecycle
+    // completion ownership keep the established one-way commit path.
+    // The ordinary binding path has no completion owner and deliberately needs only commitRect;
+    // preserve that smaller test/runtime seam by consulting settledness only when one was supplied.
+    const settledBefore =
+      onMeasuredCommit === undefined || options?.instant === true
+        ? false
+        : layout.isSettled(epoch.id)
+    const committedLead =
+      options === undefined
+        ? layout.commitRect(epoch.id, token, measured)
+        : layout.commitRect(epoch.id, token, measured, options)
+    if (onMeasuredCommit !== undefined) {
+      // A force-instant lead stays settled before and after its commit, so settledness cannot
+      // identify its completed flight. The driver reports the current holder role at the commit
+      // edge; sole/trailing commits return false and never arm an unrelated completion callback.
+      // The ordinary lane retains its existing settled-edge proof, avoiding a callback for a
+      // no-op lead measure that began no projection work.
+      onMeasuredCommit(
+        options?.instant === true ? committedLead : settledBefore && !layout.isSettled(epoch.id),
+      )
+    }
+  }
+
+  // Keep the default three-argument path for ordinary identity calls. A component-tree address
+  // is a lifecycle-only extension that the UI engine needs to publish a live layoutId transform.
+  const flightOpts = (
+    options?: LayoutIdentityBindingOptions,
+  ): LayoutIdentityBindingOptions | undefined => {
+    if (
+      options?.instant !== true &&
+      options?.projectionComponentId === undefined &&
+      options?.timing === undefined &&
+      options?.spring === undefined
+    )
+      return undefined
+    return {
+      ...(options?.instant === true ? { instant: true as const } : {}),
+      ...(options?.projectionComponentId === undefined
+        ? {}
+        : { projectionComponentId: options.projectionComponentId }),
+      ...(options?.timing === undefined ? {} : { timing: options.timing }),
+      ...(options?.spring === undefined ? {} : { spring: options.spring }),
+    }
+  }
+
+  return {
+    projectionBinding: driver,
+    attach(id, token, measure, options) {
+      // Enter unmeasured, then let the (possibly async) host measurement land as the first
+      // commit — identical routing for handles and pre-branded rects.
+      const opts = flightOpts(options)
+      const role =
+        opts === undefined ? layout.attach(id, token, null) : layout.attach(id, token, null, opts)
+      const epoch = { id }
+      measurementEpochs.set(token, epoch)
+      if (measure !== undefined && measure !== null) {
+        requestWindowSpaceMeasure(measure, (measured) => {
+          commitIfCurrent(epoch, token, measured, opts)
+        })
+      }
+      return role
+    },
+
+    commitLayout(id, token, measure, options, onMeasuredCommit) {
+      const attachedEpoch = measurementEpochs.get(token)
+      if (attachedEpoch === undefined || attachedEpoch.id !== id) {
+        throw new Error(
+          `layoutId binding: commitLayout for '${id}' requires an attached holder; ` +
+            'constructive measurement calls after detach are lifecycle defects.',
+        )
+      }
+      const epoch = { id }
+      measurementEpochs.set(token, epoch)
+      const opts = flightOpts(options)
+      requestWindowSpaceMeasure(measure, (measured) => {
+        commitIfCurrent(epoch, token, measured, opts, onMeasuredCommit)
+      })
+    },
+
+    sharedViewFor: (id, token) => layout.sharedFor(id, token),
+
+    opacityWitnessFor: (id) => layout.opacityWitnessFor(id),
+
+    detach(id, token, options) {
+      const opts = flightOpts(options)
+      const exitingHolderRetained =
+        opts === undefined ? layout.detach(id, token) : layout.detach(id, token, opts)
+      const epoch = measurementEpochs.get(token)
+      if (epoch?.id === id) measurementEpochs.delete(token)
+      return exitingHolderRetained
+    },
+
+    releasable: (id, token) => layout.releasable(id, token),
+    isSettled: (id) => layout.isSettled(id),
+    holds: (id, token) => (typeof layout.holds === 'function' ? layout.holds(id, token) : false),
+    isLead: (id, token) => (typeof layout.isLead === 'function' ? layout.isLead(id, token) : true),
+    subscribeSettled: (id, onSettled) => layout.subscribeSettled(id, onSettled),
+
+    coupleRelease: (id, token, safeToRemove) => layout.coupleRelease(id, token, safeToRemove),
+  }
+}

package/src/native/motion/layoutIdFlightConfig.ts

@@ -0,0 +1,51 @@
+// Family-3 + T22: map gated element transitions to the layoutId projection flight config.
+import {
+  toSpringConfig,
+  toTimingConfig,
+  type SpringConfig,
+  type TimingConfig,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+
+/**
+ * ONE resolver, three outcomes (T22 L1): executable tween shapes → `timing` (ms), typed spring
+ * shapes (physics or time-defined) → `spring` (engine SpringConfig, ms), anything else →
+ * undefined (the driver-global flight spring). Mutually exclusive by construction — the gate
+ * admits exactly what this resolver executes (G-INV-8 both directions).
+ */
+export type LayoutIdFlightConfig =
+  | { readonly timing: TimingConfig; readonly spring?: undefined }
+  | { readonly spring: SpringConfig; readonly timing?: undefined }
+
+/**
+ * Duration-only / tween paths ship as flight timing; `type: 'spring'` ships as a per-flight
+ * spring through toSpringConfig (velocity never reaches here — the gate refuses it on layoutId,
+ * REQ-LAYOUT-023 b). Instant/reduced-motion is handled by forceInstant, not here. Duration-only
+ * (type omitted) injects easeOut — same law as ordinary layout projection
+ * (MotionView createNoFlashLayoutTransition / pinned Motion).
+ */
+export function resolveLayoutIdFlightConfig(
+  transition: Transition | undefined,
+): LayoutIdFlightConfig | undefined {
+  if (transition === undefined) return undefined
+  if (transition.type === 'spring') return { spring: toSpringConfig(transition) }
+  // Catalog residuals author duration-only (type omitted) or explicit tween.
+  if (transition.duration === undefined && transition.type !== 'tween') return undefined
+  // Per-segment ease lists require a keyframe-array property target — never layoutId flight
+  // (Array of easings, not a 4-number cubic-bezier).
+  const ease = transition.ease ?? transition.easings ?? transition.easing
+  if (Array.isArray(ease) && ease.length > 0 && typeof ease[0] !== 'number') return undefined
+  const timing = toTimingConfig(transition)
+  if (timing.duration === undefined && timing.ease === undefined && transition.type !== 'tween')
+    return undefined
+  const durationOnlyTween =
+    transition.type === undefined &&
+    transition.duration !== undefined &&
+    transition.ease === undefined &&
+    transition.easings === undefined &&
+    transition.easing === undefined
+  if (durationOnlyTween) {
+    return { timing: { ...timing, ease: 'easeOut' } }
+  }
+  return { timing }
+}

package/src/native/motion/layoutProjection.ts

@@ -0,0 +1,89 @@
+// The layout binding's brain (specs/M2.5-BUILD-PACKET.md): validated RN onLayout rects → core's
+// projection session. The session owns ALL projection math (FLIP inversion, visual-rect springs,
+// retarget continuity, settle); this layer owns only (a) fail-loud rect validation, (b) the
+// token-keyed previous-rect capture (the FIRST rect is the initial measure — before=null → no
+// projection on mount, fail-closed), and (c) begin-vs-retarget routing (a layout change lands as
+// `begin` from idle and as `retarget` mid-flight).
+//
+import {
+  createProjectionSession,
+  type MotionGraph,
+  type ProjectionSession,
+  type Rect,
+  type SpringConfig,
+} from '@unrulysystems/native-motion-core'
+
+// The fields this binding reads off an RN onLayout payload. Loose on purpose — validation IS the
+// contract; a malformed rect fails loud naming the field, never coerced.
+export interface LayoutRectShape {
+  readonly x?: unknown
+  readonly y?: unknown
+  readonly width?: unknown
+  readonly height?: unknown
+}
+
+export interface LayoutProjectionOptions {
+  readonly graph: MotionGraph
+  readonly token: string
+  readonly spring?: SpringConfig
+}
+
+export interface LayoutProjection {
+  // Feed one validated layout rect. First rect = initial measure (no projection); subsequent rects
+  // begin (from idle) or retarget (mid-flight) the projection.
+  onLayoutRect(rect: LayoutRectShape): void
+  // The last validated rect this binding has seen (the projection's layout frame), or null.
+  lastRect(): Rect | null
+  readonly session: ProjectionSession
+}
+
+// Fail-loud field extraction (packet §semantics 6): a missing or non-numeric layout field is a
+// caller/host bug — naming the field beats coercing to 0 and projecting a garbage delta.
+function requireNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `layout projection: onLayout field '${field}' is ${JSON.stringify(value)} — a finite number ` +
+        'is required and is never coerced (specs/M2.5-BUILD-PACKET.md §semantics 6).',
+    )
+  }
+  return value
+}
+
+// Exported for sibling layout bindings (L2's layoutIdBinding) that must apply the SAME
+// fail-loud posture — one validation, reused not forked (specs/L2-BUILD-PACKET.md §semantics 6).
+export function toValidatedLayoutRect(rect: LayoutRectShape): Rect {
+  return {
+    x: requireNumber(rect.x, 'x'),
+    y: requireNumber(rect.y, 'y'),
+    width: requireNumber(rect.width, 'width'),
+    height: requireNumber(rect.height, 'height'),
+  }
+}
+
+export function createLayoutProjection(options: LayoutProjectionOptions): LayoutProjection {
+  const session = createProjectionSession({
+    graph: options.graph,
+    ...(options.spring === undefined ? {} : { spring: options.spring }),
+  })
+  // The projection's layout frame: the last rect the host committed. The FIRST rect is the initial
+  // measure — before=null means no projection on mount (fail-closed, packet §semantics 4).
+  let last: Rect | null = null
+
+  return {
+    onLayoutRect(shape) {
+      const rect = toValidatedLayoutRect(shape) // validate BEFORE any state change — a bad rect never half-applies
+      const previous = last
+      last = rect
+      if (previous === null) return // initial measure: nothing to project from
+      // A layout change lands as `begin` from idle and as `retarget` mid-flight — the session owns
+      // the continuity math either way (packet §semantics 3).
+      if (session.state() === 'idle') {
+        session.begin(options.token, previous, rect)
+      } else {
+        session.retarget(rect)
+      }
+    },
+    lastRect: () => last,
+    session,
+  }
+}

package/src/native/motion/layoutScroll.ts

@@ -0,0 +1,204 @@
+// REQ-LAYOUT-022 / REQ-API-038 — layoutScroll: scroll-offset measurement roots for the
+// layout-identity path. React context stack + measure-handle correction; CORE owns the rect
+// math (accountForLayoutScroll). No parallel measurement stack. Boolean gate lives next to
+// the other layout prop gates in MotionView (same severity path).
+//
+// Pin (motion@12.42.2): HTMLProjectionNode.measureScroll reads instance.scrollLeft/scrollTop
+// (container scroll on the layoutScroll element); DocumentProjectionNode is the always-on
+// window-scroll root. Catalog layout-stress-scroll puts layoutScroll on the overflow:scroll
+// motion.div that IS the scroller.
+//
+// Native (REQ-LAYOUT-022(c), R13 V2 live-offset): stack + pure math, plus a public composition
+// path for live non-zero container scroll without expanding the element set. Closed hosts
+// View/Text/Image still do not emit onScroll on device; product code feeds offsets via
+// LayoutScrollOffsetProvider (consumer ScrollView onScroll / useScroll MotionValue getters).
+// Pin-faithful: measureScroll of a non-scroller is {0,0} until a live source is registered.
+
+import {
+  accountForLayoutScroll,
+  type LayoutScrollOffset,
+  type Rect,
+} from '@unrulysystems/native-motion-core'
+import { createContext, createElement, useContext, type ReactNode } from 'react'
+import type { LayoutIdentityMeasureHandle } from './layoutIdBinding'
+
+export type { LayoutScrollOffset }
+
+export type LayoutScrollOffsetRef = { current: LayoutScrollOffset }
+
+/**
+ * Pin measureScroll equivalent for native: fold a scroll event into the layoutScroll root's
+ * live offset ref. Accepts RN `nativeEvent.contentOffset` and DOM scrollLeft/scrollTop.
+ * No-op on unrecognized shapes (never throws — measure path stays total).
+ */
+function finiteOffsetComponent(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `layoutScroll offset ${label} must be a finite number (received ${describeOffset(value)}; REQ-LAYOUT-022)`,
+    )
+  }
+  return value
+}
+
+function describeOffset(value: unknown): string {
+  if (typeof value === 'number') return String(value)
+  return `${typeof value}`
+}
+
+function asFiniteOffset(x: unknown, y: unknown): LayoutScrollOffset {
+  return {
+    x: finiteOffsetComponent(x === undefined ? 0 : x, 'x'),
+    y: finiteOffsetComponent(y === undefined ? 0 : y, 'y'),
+  }
+}
+
+export function recordLayoutScrollOffsetFromEvent(
+  event: unknown,
+  target: LayoutScrollOffsetRef,
+): void {
+  if (event === null || typeof event !== 'object') return
+  const record = event as Record<string, unknown>
+  const nativeEvent = record['nativeEvent']
+  if (nativeEvent !== null && typeof nativeEvent === 'object') {
+    const contentOffset = (nativeEvent as Record<string, unknown>)['contentOffset']
+    if (contentOffset !== null && typeof contentOffset === 'object') {
+      const offset = contentOffset as { x?: unknown; y?: unknown }
+      // Absent axes default to 0; present non-finite values fail loud before projection math.
+      target.current = asFiniteOffset(
+        offset.x === undefined ? 0 : offset.x,
+        offset.y === undefined ? 0 : offset.y,
+      )
+      return
+    }
+  }
+  if (typeof record['scrollLeft'] === 'number' || typeof record['scrollTop'] === 'number') {
+    target.current = asFiniteOffset(
+      record['scrollLeft'] === undefined ? 0 : record['scrollLeft'],
+      record['scrollTop'] === undefined ? 0 : record['scrollTop'],
+    )
+  }
+}
+
+/**
+ * Resolve the live offset for a layoutScroll root at measure time: prefer host instance
+ * fields when present (DOM / instrumented hosts), else the scroll-event-fed ref.
+ */
+export function readLayoutScrollRootOffset(
+  host: unknown,
+  offsetRef: LayoutScrollOffsetRef,
+): LayoutScrollOffset {
+  if (host !== null && typeof host === 'object') {
+    const node = host as Record<string, unknown>
+    if (typeof node['scrollLeft'] === 'number' || typeof node['scrollTop'] === 'number') {
+      return asFiniteOffset(
+        typeof node['scrollLeft'] === 'number' ? node['scrollLeft'] : 0,
+        typeof node['scrollTop'] === 'number' ? node['scrollTop'] : 0,
+      )
+    }
+    const contentOffset = node['contentOffset']
+    if (
+      contentOffset !== null &&
+      typeof contentOffset === 'object' &&
+      ('x' in contentOffset || 'y' in contentOffset)
+    ) {
+      const co = contentOffset as { x?: unknown; y?: unknown }
+      return asFiniteOffset(co.x === undefined ? 0 : co.x, co.y === undefined ? 0 : co.y)
+    }
+  }
+  const current = offsetRef.current
+  return asFiniteOffset(current.x, current.y)
+}
+
+/** Wrap a measureInWindow handle so the committed rect is content-space (pin removeElementScroll). */
+export function withLayoutScrollCorrection(
+  handle: LayoutIdentityMeasureHandle,
+  offsets: readonly LayoutScrollOffset[],
+): LayoutIdentityMeasureHandle {
+  if (offsets.length === 0) return handle
+  return {
+    measureInWindow(callback) {
+      handle.measureInWindow((x, y, width, height) => {
+        const corrected = accountForLayoutScroll({ x, y, width, height }, offsets)
+        callback(corrected.x, corrected.y, corrected.width, corrected.height)
+      })
+    },
+  }
+}
+
+/** Snapshot offsets from live getters (read at measure time, not at provider mount). */
+export function readLayoutScrollOffsets(
+  getters: readonly (() => LayoutScrollOffset)[],
+): LayoutScrollOffset[] {
+  const offsets: LayoutScrollOffset[] = []
+  for (let i = 0; i < getters.length; i++) {
+    // The getter's OWN throw propagates as a fault (never caught here); the RESULT's shape is a
+    // public-boundary contract (review badd85f67c43): a non-null offset RECORD, never an array —
+    // otherwise the axes read raw-TypeErrors or silently defaults to {0,0}.
+    const raw: unknown = getters[i]!()
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      const received = raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw
+      throw new Error(
+        `layoutScroll getOffset() must return an offset record {x, y} (received ${received}; REQ-LAYOUT-022)`,
+      )
+    }
+    const record = raw as { x?: unknown; y?: unknown }
+    offsets.push(asFiniteOffset(record.x, record.y))
+  }
+  return offsets
+}
+
+/** Correct a plain rect (test / pre-branded synthetic measure path). */
+export function correctLayoutRectForScroll(
+  rect: Rect,
+  offsets: readonly LayoutScrollOffset[],
+): Rect {
+  return accountForLayoutScroll(rect, offsets)
+}
+
+// Stack of offset getters from layoutScroll=true ancestors (root → leaf).
+const LayoutScrollStackContext = createContext<readonly (() => LayoutScrollOffset)[]>([])
+
+export function useLayoutScrollOffsetGetters(): readonly (() => LayoutScrollOffset)[] {
+  return useContext(LayoutScrollStackContext)
+}
+
+export function useLayoutScrollOffsets(): readonly LayoutScrollOffset[] {
+  return readLayoutScrollOffsets(useLayoutScrollOffsetGetters())
+}
+
+export function LayoutScrollStackProvider({
+  getter,
+  children,
+}: {
+  readonly getter: () => LayoutScrollOffset
+  readonly children: ReactNode
+}): ReactNode {
+  const parent = useContext(LayoutScrollStackContext)
+  const stack = parent.length === 0 ? [getter] : [...parent, getter]
+  return createElement(LayoutScrollStackContext.Provider, { value: stack }, children)
+}
+
+/**
+ * Public composition (R13 V2 / REQ-LAYOUT-022(c) live-offset): inject a live container-scroll
+ * offset into the layoutScroll stack without a new host element. Product wraps scrollable
+ * content (e.g. RN ScrollView children) so nested layout / layoutId measures correct for
+ * mid-scroll flights. `getOffset` is read at measure time (ref / MotionValue.get), never
+ * snapshotted at provider mount.
+ */
+export interface LayoutScrollOffsetProviderProps {
+  readonly getOffset: () => LayoutScrollOffset
+  readonly children: ReactNode
+}
+
+export function LayoutScrollOffsetProvider({
+  getOffset,
+  children,
+}: LayoutScrollOffsetProviderProps): ReactNode {
+  // Boundary validate at measure time via readLayoutScrollOffsets (finite x/y).
+  return createElement(LayoutScrollStackProvider, { getter: getOffset, children })
+}
+
+/** Empty offset ref for ScrollView / useScroll feed composition. */
+export function createLayoutScrollOffsetRef(): LayoutScrollOffsetRef {
+  return { current: { x: 0, y: 0 } }
+}