@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/AnimatePresence.tsx

@@ -0,0 +1,1605 @@
+// AnimatePresence, the spike (specs/M2.3-BUILD-PACKET.md): the thin React layer over
+// presenceBinding — keyed-children diffing, exit re-rendering, the exits-in-flight stepper, and the
+// usePresence context. All SEMANTICS live in the binding/controller (deterministically checked on
+// PresenceChecksScreen); this file owns only React plumbing, mirroring the MotionView split.
+//
+// Mechanics: each commit reads the keyed children's motion props into PresenceChild records and
+// syncs them; the render set is the controller's mountedKeys — a dropped child keeps rendering (its
+// last-seen element cloned with `animate = resolvedExitTarget`, so the visuals retarget through the
+// sealed MotionView→worklet-driver path) until its exit settles, at which point the stepper notices
+// the mounted set shrank and bumps a version to unmount it. The stepper drives the binding's graph
+// (core ManualClock/ManualScheduler advanced by real frame deltas) ONLY while exits are in flight —
+// idle presence costs zero frames (the M2.0 CPU lesson).
+
+import {
+  Children,
+  cloneElement,
+  createContext,
+  Fragment,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+  type RefCallback,
+} from 'react'
+import {
+  captureTransition,
+  createMotionGraph,
+  flattenVariantApplications,
+  isColor,
+  type LengthLayoutContext,
+  ManualClock,
+  ManualScheduler,
+  UNIVERSAL_SUBSET,
+  type PresenceMode,
+  type PresenceChild,
+  type Target,
+  type Transition,
+  type VariantLabels,
+  type VariantResolver,
+} from '@unrulysystems/native-motion-core'
+import {
+  createPresenceBinding,
+  exitLaneTransitionRefusal,
+  validateExitLaneTransition,
+  type PresenceBinding,
+  type PresenceLiveValues,
+  type PresenceResolvedExits,
+} from './presenceBinding'
+import { useLengthLayoutParentContext } from './lengthLayoutContext'
+import { isNativeMotionHost } from './nativeHostMarker'
+import {
+  composePopLayoutOnLayout,
+  composePopLayoutStyle,
+  readPopLayoutRect,
+  refreshPopLayoutRect,
+  resolvePopLayoutDirection,
+  type PopLayoutHostHandle,
+} from './popLayout'
+import { gateTargetWithSeverity } from './motionViewController'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import {
+  dictionaryTargetKeys,
+  gateExitTransitionEnd,
+  gateLabelDefinition,
+  gateVariantApplicationFallbacks,
+  gateVariantsDictionary,
+  isVariantLabelForm,
+  isRuntimeVariantDefinitionForm,
+  resolveVariantApplicationsGated,
+} from './variantProps'
+import type { MotionComponentId } from './motionViewController'
+
+// The per-child presence contract (REQ-PRESENCE-014): [isPresent, safeToRemove], plus the consumer
+// registration that makes a `usePresence` caller a MANUAL (deferred) exit — a child whose subtree
+// holds a registered consumer is retained past its drop until safeToRemove, exactly the spec's
+// isPresent=false interval (review cycle 1 major 2: deferral must come from the hook's existence,
+// not a static prop). Children outside an AnimatePresence are always present; safeToRemove/register
+// are then no-ops by definition (nothing retains them).
+interface PresenceRegistration {
+  readonly safeToRemove: (consumerId: string) => void
+  readonly register: (consumerId: string) => () => void
+}
+
+interface PresenceRemovalSnapshot {
+  readonly reader: PresenceLiveValuesReader
+  readonly values: PresenceLiveValues
+}
+
+interface PresenceContextValue {
+  readonly isPresent: boolean
+  readonly registration: PresenceRegistration
+  /** The AnimatePresence custom payload captured when this child entered its exit episode. */
+  readonly custom?: unknown
+  readonly removalSnapshot?: PresenceRemovalSnapshot
+  /**
+   * Pin PresenceChild: when the tracked host is a Fragment (or other non-exit host),
+   * nested motion hosts with object-form exit must register consumers and self-drive
+   * exit (r10 major 1c84dbe8f2a7). Direct MotionView keys keep the binding beginExit path.
+   */
+  readonly nestedExitAuthority: boolean
+  /**
+   * Pin PresenceChild initial={false}: suppress enter on descendants under this host
+   * (r10 major 7a3f6ce1b904). Direct hosts still receive decoratePresenceChild's clone.
+   */
+  readonly enterSuppressed: boolean
+}
+
+const PresenceContext = createContext<PresenceContextValue | null>(null)
+
+// The removal-boundary authority a MotionView registers: `read` supplies committed scalar values
+// (the null-first origin, REQ-PRESENCE-020); the optional `readResolvedExits` supplies px-RESOLVED
+// endpoints for measure-length exit arrays (reviews 2f3a8e6c1d90/7ae34b29f081) — the owning
+// MotionView resolves against its own layout context, the SAME resolution the property lane
+// performs at command time. `currentContext` carries the container's RENDER-CURRENT provider
+// context (review 493cd7e58a10): the drop capture runs in the parent's render, before the
+// retained child re-renders under a same-commit provider change.
+type PresenceLiveValuesReader = ((keys: readonly string[]) => PresenceLiveValues) & {
+  readResolvedExits?: (
+    keys: readonly string[],
+    currentContext?: LengthLayoutContext | null,
+    previousContainerContext?: LengthLayoutContext | null,
+  ) => Readonly<Record<string, readonly (number | null)[]>>
+}
+
+interface PresenceLiveValuesRegistration {
+  register(read: PresenceLiveValuesReader): () => void
+  isRegistered(read: PresenceLiveValuesReader): boolean
+}
+
+// Separate from usePresence's subtree-wide lifecycle context: only the first native MotionView host
+// under a tracked child supplies that child's committed values. MotionView places a null provider around
+// its descendants so nested hosts cannot replace the removal-boundary authority (REQ-PRESENCE-020).
+const PresenceLiveValuesContext = createContext<PresenceLiveValuesRegistration | null>(null)
+
+export function usePresenceLiveValues(
+  read: (keys: readonly string[]) => PresenceLiveValues,
+  readResolvedExits?: (
+    keys: readonly string[],
+    currentContext?: LengthLayoutContext | null,
+    previousContainerContext?: LengthLayoutContext | null,
+  ) => Readonly<Record<string, readonly (number | null)[]>>,
+): () => PresenceLiveValues | undefined {
+  // The same authority that supplies the snapshot receives it back during exit. Sibling top-level
+  // hosts remain registered as fallbacks but cannot consume the first host's committed state.
+  const presence = useContext(PresenceContext)
+  const registration = useContext(PresenceLiveValuesContext)
+  const readRef = useRef(read)
+  readRef.current = read
+  const readResolvedExitsRef = useRef(readResolvedExits)
+  readResolvedExitsRef.current = readResolvedExits
+  const stableReadRef = useRef<PresenceLiveValuesReader | null>(null)
+  if (stableReadRef.current === null) {
+    const stable: PresenceLiveValuesReader = (keys) => readRef.current(keys)
+    stable.readResolvedExits = (keys, currentContext, previousContainerContext) =>
+      readResolvedExitsRef.current?.(keys, currentContext, previousContainerContext) ?? {}
+    stableReadRef.current = stable
+  }
+  const stableRead = stableReadRef.current
+  useEffect(() => {
+    if (registration === null) return
+    return registration.register(stableRead)
+  }, [registration, stableRead])
+  const removalSnapshot = presence?.removalSnapshot
+  const resolveRemovalValues = useCallback(() => {
+    if (registration === null || removalSnapshot === undefined) return undefined
+    // React runs deleted-child passive cleanups before surviving siblings' update effects. Re-check
+    // the captured reader HERE (not during render): transferring one host's T1 snapshot to another
+    // host is ambiguous and would desynchronize property timing from presence retention.
+    if (!registration.isRegistered(removalSnapshot.reader)) {
+      throw new Error(
+        'AnimatePresence removal authority unmounted during the removal commit while another ' +
+          'top-level native host survived; the origin handoff is ambiguous (REQ-PRESENCE-020).',
+      )
+    }
+    return removalSnapshot.reader === stableRead ? removalSnapshot.values : undefined
+  }, [registration, removalSnapshot, stableRead])
+  // A top-level host introduced during the retained render has no claim on the old host's T1
+  // snapshot. Refuse during render, before MotionView can create its controller or mutate the driver.
+  // Already-mounted siblings are registered and remain legal; the passive resolver above handles
+  // an authority that disappears later in this same commit.
+  if (
+    registration !== null &&
+    removalSnapshot !== undefined &&
+    !registration.isRegistered(stableRead)
+  ) {
+    throw new Error(
+      'AnimatePresence cannot mount a new top-level native host during an active removal ' +
+        'snapshot; replacing the removal authority is ambiguous (REQ-PRESENCE-020).',
+    )
+  }
+  return resolveRemovalValues
+}
+
+export function PresenceLiveValuesBoundary({ children }: { readonly children: ReactNode }) {
+  return (
+    <PresenceLiveValuesContext.Provider value={null}>{children}</PresenceLiveValuesContext.Provider>
+  )
+}
+
+interface PresenceConsumerState {
+  readonly registered: Set<string>
+  readonly released: Set<string>
+  exiting: boolean
+  delivered: boolean
+}
+
+export interface PresenceConsumerLatch {
+  hasConsumers(key: string): boolean
+  register(key: string, consumerId: string): () => void
+  setPresent(key: string, isPresent: boolean): void
+  safeToRemove(key: string, consumerId: string): void
+  pruneUnmounted(mountedKeys: readonly string[]): void
+  // True while the key's exit episode has delivered its release and no later registration has
+  // reopened it — the container's commit-boundary check before finalizing a deferred release.
+  isDelivered(key: string): boolean
+}
+
+// One Presence controller entry is keyed by the tracked React child, but any number of manual
+// consumers may live in that child's subtree. Keep their exactly-once releases separate and open
+// the controller's key-wide latch only after every still-registered consumer has released. A
+// consumer disappearing during exit satisfies its own obligation; re-entry cancels the episode.
+// `adoptKey` is the retention-authority coupling (r5 protocol law): whenever an exit episode holds
+// unreleased consumers whose registration the drop commit's sync may not have carried into the
+// controller record, the latch adopts the key so an ANIMATION-driven record cannot resolve on
+// animation completion alone (REQ-PRESENCE-001/013/014). The controller-side seam is idempotent.
+export function createPresenceConsumerLatch(
+  releaseKey: (key: string) => void,
+  adoptKey: (key: string) => void,
+): PresenceConsumerLatch {
+  const states = new Map<string, PresenceConsumerState>()
+
+  const stateFor = (key: string): PresenceConsumerState => {
+    const existing = states.get(key)
+    if (existing !== undefined) return existing
+    const created: PresenceConsumerState = {
+      registered: new Set(),
+      released: new Set(),
+      exiting: false,
+      delivered: false,
+    }
+    states.set(key, created)
+    return created
+  }
+
+  const deliverIfReady = (key: string, state: PresenceConsumerState): void => {
+    if (!state.exiting || state.delivered) return
+    for (const consumerId of state.registered) {
+      if (!state.released.has(consumerId)) return
+    }
+    state.delivered = true
+    releaseKey(key)
+  }
+
+  return {
+    hasConsumers(key) {
+      return (states.get(key)?.registered.size ?? 0) > 0
+    },
+
+    isDelivered(key) {
+      return states.get(key)?.delivered === true
+    },
+
+    register(key, consumerId) {
+      const state = stateFor(key)
+      state.registered.add(consumerId)
+      if (state.exiting) {
+        state.released.delete(consumerId)
+        // A consumer joining a LIVE episode (a layoutId introduced mid-exit registers from the
+        // passive-effect flush after the drop) must acquire retention authority in the controller
+        // record too — the drop-time sync could not have seen it. Delivery is NOT terminal while
+        // the key still exits (r6 finding 5ed46aa1322f): an early first delivery hands retention
+        // back to the exit animation, and a consumer registering in that window REOPENS the
+        // episode — prior releases keep their marks, and the joiner's release (or unregister)
+        // delivers again exactly once. No hold is stranded: a registration after the key has
+        // resolved is bounded by the controller seam's exiting-only guard and pruneUnmounted,
+        // never by a permanently closed episode.
+        state.delivered = false
+        adoptKey(key)
+      }
+      let registered = true
+      return () => {
+        if (!registered) return
+        registered = false
+        state.registered.delete(consumerId)
+        state.released.delete(consumerId)
+        if (state.exiting) deliverIfReady(key, state)
+        // A LIVE-exit state survives its last consumer unregistering — even delivered (r7
+        // finding cd76f4209a31): a REPLACEMENT consumer registering afterwards must land in the
+        // same still-exiting episode and take the reopen path, never a fresh non-exiting state
+        // that skips adoption. pruneUnmounted discards the state once the key actually resolves.
+        if (state.registered.size === 0 && !state.exiting) states.delete(key)
+      }
+    },
+
+    setPresent(key, isPresent) {
+      // An identity can become a Presence consumer only after its parent has entered retention.
+      // Preserve that absent edge until its post-commit registration joins the same exit episode.
+      // A present key with no consumers still needs no bookkeeping at all.
+      const state = states.get(key) ?? (isPresent ? undefined : stateFor(key))
+      if (state === undefined) return
+      if (isPresent) {
+        // A consumer-less state kept alive through an exit (the r7 replacement-consumer law
+        // preserves live-exit states across unregister) has no further obligation once the key
+        // re-enters — drop it, or it would linger for the container's lifetime (pruneUnmounted
+        // only covers unmounted keys).
+        if (state.registered.size === 0) {
+          states.delete(key)
+          return
+        }
+        state.exiting = false
+        state.delivered = false
+        state.released.clear()
+        return
+      }
+      if (state.exiting) return
+      state.exiting = true
+      state.delivered = false
+      state.released.clear()
+      // No consumer may have registered yet: React installs a newly introduced layoutId's
+      // subscription in the following passive-effect flush. Do not deliver the empty set before
+      // that consumer gets its one chance to join this exit; register/safeToRemove then drive the
+      // normal conjunction, and unregister keeps the existing cleanup path intact.
+      // Consumers already registered on the exit edge also adopt: unreachable through the
+      // container today (a pre-drop registration lands `deferred` at the drop sync), but the
+      // latch cannot know the caller's sync ordering — adopting on both edges keeps authority
+      // acquisition unconditional, and the controller-side seam is idempotent.
+      if (state.registered.size > 0) {
+        adoptKey(key)
+        deliverIfReady(key, state)
+      }
+    },
+
+    safeToRemove(key, consumerId) {
+      const state = states.get(key)
+      if (
+        state === undefined ||
+        !state.exiting ||
+        !state.registered.has(consumerId) ||
+        state.released.has(consumerId)
+      ) {
+        return
+      }
+      state.released.add(consumerId)
+      deliverIfReady(key, state)
+    },
+
+    // A key with no consumer can still need a short-lived exiting marker for a layoutId that
+    // registers in this commit's passive effects. Once Presence has removed that key entirely,
+    // there can be no later registration for the episode, so discard its marker too.
+    pruneUnmounted(mountedKeys) {
+      const mounted = new Set(mountedKeys)
+      for (const key of states.keys()) {
+        if (!mounted.has(key)) states.delete(key)
+      }
+    },
+  }
+}
+
+// The pinned motion/react return shape (type-identity gate, review round 2 major 6): outside
+// any AnimatePresence → [true, null]; present inside one → [true]; exiting → [false,
+// safeToRemove]. `subscribe: false` opts out of the manual-exit registration exactly like
+// motion's flag — the caller reads presence without deferring its own removal.
+type SafeToRemove = () => void
+type AlwaysPresent = [true, null]
+type Present = [true]
+type NotPresent = [false, SafeToRemove]
+const ALWAYS_PRESENT: AlwaysPresent = [true, null]
+const PRESENT: Present = [true]
+
+export function usePresence(subscribe: boolean = true): AlwaysPresent | Present | NotPresent {
+  const context = useContext(PresenceContext)
+  const consumerId = useId()
+  const registration = context?.registration
+  const safeToRemove = useCallback(() => {
+    registration?.safeToRemove(consumerId)
+  }, [consumerId, registration])
+  // Register on mount so the container knows this child needs a manual exit; unregister on
+  // unmount. The effect re-runs only if the context identity changes (a different enclosing
+  // child slot) or the subscribe flag flips.
+  useEffect(() => {
+    if (registration === undefined || !subscribe) return
+    return registration.register(consumerId)
+  }, [consumerId, registration, subscribe])
+  if (context === null) return ALWAYS_PRESENT
+  return context.isPresent ? PRESENT : [false, safeToRemove]
+}
+
+// Read-only presence signal (SPEC-PRESENCE §usePresence family): unlike usePresence it does NOT
+// register a manual exit — reading presence never defers removal.
+export function useIsPresent(): boolean {
+  const context = useContext(PresenceContext)
+  return context === null ? true : context.isPresent
+}
+
+/** The pin's raw PresenceContext custom reader; reading never registers a removal deferral. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function usePresenceData(): any {
+  const context = useContext(PresenceContext)
+  return context?.custom
+}
+
+/**
+ * Read the presence-level custom payload for variant resolution. The context value is cached at
+ * the present → exiting edge, so a later AnimatePresence custom change cannot re-resolve an active
+ * exit (pin animation-state.ts:210-224). Present children deliberately read `undefined` and fall
+ * back to their own component custom prop.
+ */
+export function usePresenceVariantCustom(): unknown | undefined {
+  const context = useContext(PresenceContext)
+  return context?.isPresent === false ? context.custom : undefined
+}
+
+/** Pin PresenceChild policy for nested hosts (Fragment / non-exit tracked children). */
+export function usePresenceHostPolicy(): {
+  readonly nestedExitAuthority: boolean
+  readonly enterSuppressed: boolean
+  readonly isPresent: boolean
+} {
+  const context = useContext(PresenceContext)
+  if (context === null) {
+    return { nestedExitAuthority: false, enterSuppressed: false, isPresent: true }
+  }
+  return {
+    nestedExitAuthority: context.nestedExitAuthority,
+    enterSuppressed: context.enterSuppressed,
+    isPresent: context.isPresent,
+  }
+}
+
+// Non-readonly by exception (type-identity gate): the pinned motion/react AnimatePresenceProps
+// declares plain optional members, and the cross-entry Equal compares readonly modifiers too.
+export interface AnimatePresenceProps {
+  mode?: PresenceMode
+  initial?: boolean
+  onExitComplete?: () => void
+  /**
+   * Pin catalog alias (R13 V4): motion dev sandboxes still write `onRest` while the
+   * pin library surface names `onExitComplete`. Same callback — accepted as an alias,
+   * never a second lifecycle. Prefer `onExitComplete` in new product code.
+   */
+  onRest?: () => void
+  // SPEC-PRESENCE's end-state surface includes `custom` (dynamic exit variants). The spike does not
+  // implement variants, and per the fail-loud rule an accepted-but-ignored prop is a defect — so it
+  // exists on the type and THROWS if provided (never silently dropped). Typed `any`, not
+  // `unknown`: the pinned motion/react surface declares `custom?: any` and the identity gate
+  // compares the shapes verbatim.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  custom?: any
+  /**
+   * Family-6 (REQ-PRESENCE-010): when true, this nested AnimatePresence joins its parent
+   * presence exit — children exit when the parent is not present, and parent safeToRemove
+   * fires after every nested exit settles (pinned motion/react `propagate`).
+   */
+  propagate?: boolean
+  anchorX?: 'left' | 'right'
+  anchorY?: 'top' | 'bottom'
+  presenceAffectsLayout?: boolean
+  // Optional like motion/react's own surface (round 16 major 4b8c6d0e2a95: requiring it here
+  // let a childless container typecheck only through the web entry; the identity gate pins
+  // `children` across entries now). A childless container tracks nothing and renders nothing.
+  children?: ReactNode
+}
+
+// Motion props AnimatePresence reads off each keyed child element (the child stays a MotionView; the
+// container only inspects, never re-implements). A manual (deferred) exit comes ONLY from a
+// registered usePresence consumer in the child's subtree (REQ-PRESENCE-014) — the old `deferred`
+// JSX escape hatch is gone (review rounds 3/6: it was never public surface). R7 (REQ-API-032):
+// animate/exit additionally carry the label form, resolved against the child's own dictionary.
+interface MotionChildProps {
+  readonly animate?: Target | VariantLabels | VariantResolver | boolean
+  readonly exit?: Target | VariantLabels | VariantResolver
+  readonly transition?: Transition
+  readonly variants?: unknown
+  readonly style?: unknown
+  readonly onLayout?: (event: unknown) => void
+  readonly ref?: Ref<unknown>
+}
+
+function setPresenceChildRef(ref: Ref<unknown> | undefined, node: unknown): void | (() => void) {
+  if (typeof ref === 'function') return ref(node)
+  if (ref !== undefined && ref !== null) {
+    ;(ref as { current: unknown }).current = node
+  }
+}
+
+// The container's per-child target lanes (review rounds 7/8): BOTH targets ride the severity
+// boundary before any binding mutation — value shapes via gateTargetWithSeverity, and the
+// exit-keys ⊆ animate-keys rule under the same law (dev throws; production reports and refuses
+// the offending KEY). The binding's interior unconditional throws become backstops that gated
+// input never reaches.
+// Capture a caller-owned child transition ONCE into a frozen snapshot (review major 3e8bca): the R8-F1
+// filtering, the exit-lane validation, and the transition forwarded to the PresenceChild must all read the
+// SAME value — a stateful `type`/`duration` getter must not filter animate vs exit inconsistently or
+// validate one value then forward another. A malformed SHAPE stays raw so the exit-lane validator throws
+// its typed refusal (a capture would launder an array/Date into an empty `{}`).
+function captureChildTransition(transition: Transition | undefined): Transition | undefined {
+  if (transition === undefined) return undefined
+  if (typeof transition !== 'object' || transition === null || Array.isArray(transition)) {
+    return transition
+  }
+  const proto = Object.getPrototypeOf(transition) as unknown
+  if (proto !== Object.prototype && proto !== null) return transition
+  return captureTransition(transition)
+}
+
+export function gatePresenceChildTargets(
+  targets: {
+    readonly animate: Target | VariantLabels | VariantResolver | boolean | undefined
+    readonly exit: Target | VariantLabels | VariantResolver | undefined
+    // R7: the child's dictionary — label forms resolve against it, and the exit-subset law
+    // widens to the law-g mounted union (animate keys ∪ dictionary keys).
+    readonly variants?: unknown
+    // The child's transition (review major 44): drives the R8-F1 spring/keyframe-array compat refusal
+    // for the OBJECT-form animate/exit HERE — so a spring + >2-array exit is refused before presence
+    // bookkeeping (never a nonempty exit that retains the child while the property is dropped later).
+    readonly transition?: Transition | undefined
+  },
+  severity: 'development' | 'production',
+  report: (error: Error) => void,
+  componentId: MotionComponentId = '<Motion.View>',
+): {
+  animate: Target | undefined
+  exit: Target | undefined
+  /** Law g: animate keys ∪ dictionary keys — the binding's exit-key backstop admits these. */
+  mountedKeys: readonly string[]
+  /** Law f (M2 r3 major 5a64e2f0c19b): a production-REFUSED label prop must be STRIPPED
+   * from the rendered clone — one report here, never a second at the child's gate. */
+  animateLabelRefused: boolean
+  exitLabelRefused: boolean
+} {
+  // Gated SILENTLY for resolution (dev still throws): the child MotionView owns the
+  // dictionary's one-report-per-offense duty at its own mount gate — a second container
+  // report for the same entry would double-count the offense.
+  const dictionary = gateVariantsDictionary(
+    targets.variants,
+    { severity, report: () => {}, componentId },
+    componentId,
+  )
+  // A refused label prop (production; development throws) is refused AS A UNIT: the caller
+  // strips it from the rendered clone so the child's gate never re-reports the offense.
+  let animateLabelRefused = false
+  let exitLabelRefused = false
+  // The EFFECTIVE transition for the R8-F1 compat check (review major 47): an exit-lane-INVALID
+  // transition (e.g. a spring carrying `delay`) is refused and FALLS BACK to the default (non-spring)
+  // at the child, so its array target stays valid — the array must NOT be refused against a transition
+  // that itself gets refused. Only a VALID exit-lane spring triggers R8-F1. (The invalid transition is
+  // reported once by toPresenceChild's own transition gate, not double-reported here.)
+  // Capture the transition ONCE (review major 3e8bca) so the R8-F1 filtering below reads a stable value —
+  // a stateful `type` getter must not filter animate against 'spring' and exit against 'tween'.
+  const captured = captureChildTransition(targets.transition)
+  const directTargetKeys = (
+    target: Target | VariantLabels | VariantResolver | undefined,
+  ): readonly string[] =>
+    typeof target === 'object' && target !== null && !Array.isArray(target)
+      ? Object.keys(target)
+      : []
+  // Only properties actually consumed by the exit lane participate in its narrower transition
+  // vocabulary. An animate-only sibling must not invalidate the exit branch's transition map:
+  // the supplying gate still needs to see the exit property's own spring so it can refuse an
+  // incompatible keyframe array before presence bookkeeping (review major n4wse8).
+  const directPropertyKeys = [...new Set(directTargetKeys(targets.exit))]
+  const effectiveTransition: Transition | undefined =
+    captured !== undefined &&
+    exitLaneTransitionRefusal(captured, componentId, directPropertyKeys) === null
+      ? captured
+      : undefined
+  const resolveLabelTarget = (
+    prop: 'animate' | 'exit',
+    value: VariantLabels,
+  ): { target: Target | undefined; refused: boolean } => {
+    const labels = gateLabelDefinition(prop, value, { severity, report, componentId }, componentId)
+    if (labels === undefined) return { target: undefined, refused: true }
+    if (
+      labels.some(
+        (label) =>
+          dictionary !== undefined &&
+          Object.hasOwn(dictionary, label) &&
+          typeof dictionary[label] === 'function',
+      )
+    ) {
+      // The presence container has no visual element. Preserve the authored label for the direct
+      // MotionView, which resolves it with live state at enter/removal activation.
+      return { target: undefined, refused: false }
+    }
+    return {
+      target: flattenVariantApplications(
+        gateVariantApplicationFallbacks(
+          resolveVariantApplicationsGated(
+            labels,
+            dictionary,
+            { severity, report, componentId },
+            componentId,
+          ),
+          effectiveTransition,
+          { severity, report, componentId },
+          componentId,
+        ),
+      ).target,
+      refused: false,
+    }
+  }
+  let animate: Target | undefined
+  if (typeof targets.animate === 'function') {
+    // The container has no visual element and therefore cannot pre-apply the pin's live-state
+    // function. The direct MotionView resolves it at its own activation boundary.
+    animate = undefined
+  } else if (typeof targets.animate === 'boolean') {
+    // U7h (REQ-API-057): pin skips boolean — no overlay, not EMPTY_TARGET (an empty object
+    // would tighten the exit-subset law). Presence enterSuppressed sees the same absence.
+    animate = undefined
+  } else if (isVariantLabelForm(targets.animate)) {
+    const resolved = resolveLabelTarget('animate', targets.animate)
+    animate = resolved.target
+    animateLabelRefused = resolved.refused
+  } else {
+    animate =
+      targets.animate === undefined
+        ? undefined
+        : gateTargetWithSeverity(
+            targets.animate,
+            severity,
+            report,
+            true,
+            effectiveTransition,
+            componentId,
+          )
+  }
+  const exitIsLabel = isVariantLabelForm(targets.exit)
+  let exit: Target | undefined
+  if (typeof targets.exit === 'function') {
+    exit = undefined
+  } else if (exitIsLabel) {
+    const resolved = resolveLabelTarget('exit', targets.exit as VariantLabels)
+    exit = resolved.target
+    exitLabelRefused = resolved.refused
+  } else {
+    exit =
+      targets.exit === undefined
+        ? undefined
+        : gateTargetWithSeverity(
+            targets.exit as Target,
+            severity,
+            report,
+            true,
+            effectiveTransition,
+            componentId,
+          )
+  }
+  // T23 B3b: a carrier on the RESOLVED exit (object form or a label's entry) is the deferred
+  // exit-jump lane — one severity refusal here; the member drops, siblings survive.
+  if (exit !== undefined) {
+    exit = gateExitTransitionEnd(exit, { severity, report, componentId })
+  }
+  // Law-g union (M2 r1 major 8): a dictionary-named key is mounted on the child even when
+  // no animate target names it, so it is a legal exit key. The union also rides the
+  // PresenceChild to the binding's backstop (M2 r2 major 18). T23 B3b: the animate CARRIER's
+  // SUB-keys are mount-registered on the child (legal exit keys); the carrier itself is
+  // structural, never a key.
+  const animateCarrier = (animate as Record<string, unknown> | undefined)?.['transitionEnd']
+  const mountedKeys = new Set([
+    ...Object.keys(animate ?? {}).filter((key) => key !== 'transitionEnd'),
+    ...(typeof animateCarrier === 'object' && animateCarrier !== null
+      ? Object.keys(animateCarrier)
+      : []),
+    ...dictionaryTargetKeys(dictionary),
+  ])
+  // A label-form exit resolves FROM the dictionary, so its keys are dictionary keys by
+  // construction — the subset law below can never fail for it and is skipped.
+  if (exit !== undefined && !exitIsLabel) {
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(exit)) {
+      if (!mountedKeys.has(key)) {
+        const error = new Error(
+          `${componentId}: presence exit key '${key}' is not in the child's animate target or variants ` +
+            'dictionary — exit keys must be a subset of the mounted keys (REQ-API-032 law g; ' +
+            'an un-mounted key has no shared value).',
+        )
+        if (severity === 'development') throw error
+        report(error)
+        continue
+      }
+      kept[key] = value
+    }
+    exit = kept as Target
+  }
+  return { animate, exit, mountedKeys: [...mountedKeys], animateLabelRefused, exitLabelRefused }
+}
+
+export function componentIdForPresenceChild(type: unknown): MotionComponentId {
+  const visited = new Set<object>()
+  let current = type
+  for (let depth = 0; depth < 16; depth += 1) {
+    if ((typeof current !== 'object' && typeof current !== 'function') || current === null) break
+    if (visited.has(current)) break
+    visited.add(current)
+    const displayName = (current as { displayName?: unknown }).displayName
+    if (displayName === 'Motion.Text') return '<Motion.Text>'
+    if (displayName === 'Motion.Image') return '<Motion.Image>'
+    // React.memo stores its wrapped type on `.type`; forwardRef is deliberately opaque because
+    // its rendered host cannot be known without invoking user code.
+    const wrapped = (current as { type?: unknown }).type
+    if (wrapped === undefined) break
+    current = wrapped
+  }
+  return '<Motion.View>'
+}
+
+function toPresenceChild(
+  element: ReactElement,
+  key: string,
+  hasConsumer: boolean,
+  reenteringActiveExit: boolean,
+): PresenceChild & {
+  transitionConsumed: boolean
+  animateLabelRefused: boolean
+  exitLabelRefused: boolean
+} {
+  const props = element.props as MotionChildProps
+  const componentId = componentIdForPresenceChild(element.type)
+  const severity = ambientNativeSeverity()
+  // Capture the caller-owned transition ONCE at this supplying boundary (review major 3e8bca): the gate's
+  // R8-F1 filtering, the exit-lane validation, and the transition forwarded to the PresenceChild all read
+  // THIS one snapshot — a stateful accessor cannot pass the gate then mutate into an invalid/divergent
+  // config downstream.
+  const capturedTransition = captureChildTransition(props.transition)
+  const gated = gatePresenceChildTargets(
+    {
+      animate: props.animate,
+      exit: props.exit,
+      variants: props.variants,
+      transition: capturedTransition,
+    },
+    severity,
+    consoleReporter,
+    componentId,
+  )
+  const exitPresent = !(gated.exit === undefined || Object.keys(gated.exit).length === 0)
+  // The transition is CONSUMED (exit progress factory) when an exit target exists or the key
+  // re-enters an active exit — then it rides the severity law HERE (r11 major 1c3f4f0b4b77:
+  // production reports once and refuses; the binding's loud guard is the direct-consumer
+  // backstop, never the render path's crash).
+  const transitionConsumed =
+    capturedTransition !== undefined && (exitPresent || reenteringActiveExit)
+  let childTransition = capturedTransition
+  if (transitionConsumed) {
+    try {
+      const consumedKeys = reenteringActiveExit
+        ? [...new Set([...Object.keys(gated.animate ?? {}), ...Object.keys(gated.exit ?? {})])]
+        : Object.keys(gated.exit ?? {})
+      validateExitLaneTransition(childTransition, componentId, [...consumedKeys])
+    } catch (error) {
+      if (severity === 'development') throw error
+      consoleReporter(error as Error)
+      childTransition = undefined
+    }
+  }
+  return {
+    key,
+    transitionConsumed,
+    animateLabelRefused: gated.animateLabelRefused,
+    exitLabelRefused: gated.exitLabelRefused,
+    ...(gated.animate === undefined ? {} : { animate: gated.animate }),
+    // A fully-refused exit is OMITTED: the child then follows the no-exit removal path
+    // (REQ-PRESENCE-011) instead of retaining on an empty target.
+    ...(gated.exit === undefined || Object.keys(gated.exit).length === 0
+      ? {}
+      : { exit: gated.exit }),
+    ...(childTransition === undefined ? {} : { transition: childTransition }),
+    ...(gated.mountedKeys.length === 0 ? {} : { mountedKeys: gated.mountedKeys }),
+    ...(hasConsumer ? { deferred: true } : {}),
+  }
+}
+
+// Decorate one mounted child for render — exported so the checks drive the EXACT render-path logic
+// without React (the M2.2 pattern). Ordering of concerns: a retained exiting child retargets to the
+// once-resolved exit target; a present child whose enter was suppressed (container initial={false},
+// first commit) mounts settled via MotionView's initial={false} sentinel (review cycle 1 major 1:
+// suppression must reach the rendered element, not just the controller's ledger).
+export function decoratePresenceChild(
+  binding: PresenceBinding,
+  key: string,
+  element: ReactElement,
+): ReactElement {
+  const isPresent = binding.isPresent(key)
+  const exitTarget = binding.resolvedExitTarget(key)
+  // Pin PresenceChild: a Fragment is a pure key boundary + context provider — never retarget
+  // animate/exit onto it (React.Fragment accepts only key/children). Descendants self-drive
+  // exit via the shared presence context (r9 0f7c3e14a8d2).
+  if (element.type === Fragment) {
+    return element
+  }
+  if (!isPresent) {
+    // R7 law (d), ONE exit law for both forms: a label-form exit rides the SAME retained-
+    // clone path — the clone's animate carries the AUTHORED labels so the child executes
+    // exit PER LABEL through its own animate lane (law b), and it does so EVEN WHEN the
+    // local resolution is empty (M2 r2 major 17: the propagation-source shape — descendants
+    // resolve the labels; the consumer path owns removal timing). The binding's removal
+    // bookkeeping rides the resolved target where one exists.
+    const authoredExit = (element.props as MotionChildProps).exit
+    if (isRuntimeVariantDefinitionForm(authoredExit)) {
+      return cloneElement(
+        element as ReactElement<{ animate?: Target | VariantLabels | VariantResolver }>,
+        {
+          animate: authoredExit,
+        },
+      )
+    }
+    // Object-form authored exit (pin ExitAnimationFeature): when the binding has not yet
+    // resolved an exit target (deferred / multi-consumer hold), still retarget animate so
+    // the direct host flies the authored exit while descendants hold via usePresence.
+    if (exitTarget !== undefined) {
+      return cloneElement(element as ReactElement<{ animate?: Target }>, {
+        animate: exitTarget as Target,
+      })
+    }
+    if (
+      authoredExit !== undefined &&
+      typeof authoredExit === 'object' &&
+      !Array.isArray(authoredExit)
+    ) {
+      return cloneElement(element as ReactElement<{ animate?: Target }>, {
+        animate: authoredExit as Target,
+      })
+    }
+  }
+  // Enter suppress for direct hosts is applied at the container render site with the
+  // first-render ref (REQ-PRESENCE-016) — not here via sticky binding.enterSuppressed.
+  return element
+}
+
+// The deferred-capability gate under the ratified severity law (review round 5 — production
+// parity with the web shim wrapper): development throws; production reports and refuses invalid
+// values. T24 P consumes popLayout; custom is consumed by the presence context below.
+export function gateDeferredPresenceProps(
+  props: { readonly mode: PresenceMode | undefined; readonly custom: unknown },
+  severity: 'development' | 'production',
+  report: (error: Error) => void,
+): PresenceMode | undefined {
+  let effectiveMode = props.mode
+  // The mode VALUE domain is gated first (round 17 major d11c0c6e9a42): an unsupported value
+  // (`mode: 'bogus'`) is not a deferred capability, it is an invalid input — REQ-PRESENCE-017
+  // demands it fail loud, never ride into the binding as-is.
+  if (
+    props.mode !== undefined &&
+    props.mode !== 'sync' &&
+    props.mode !== 'wait' &&
+    props.mode !== 'popLayout'
+  ) {
+    const error = new Error(
+      `presence mode '${String(props.mode)}' is not a valid mode — REQ-PRESENCE-010 admits ` +
+        "'sync' | 'wait' | 'popLayout' (development throws; production reports and falls " +
+        'back to the default).',
+    )
+    if (severity === 'development') throw error
+    report(error)
+    effectiveMode = undefined
+  }
+  return effectiveMode
+}
+
+export function AnimatePresence({
+  mode,
+  initial,
+  onExitComplete,
+  onRest,
+  custom,
+  propagate = false,
+  anchorX = 'left',
+  anchorY = 'top',
+  presenceAffectsLayout = true,
+  children,
+  ...rest
+}: AnimatePresenceProps) {
+  // Unknown JS-supplied props are refused under the severity law (round 15 major
+  // 5f21d834ca90): TypeScript closes the surface at compile time; this closes it at runtime.
+  // An accepted-but-inert prop is a defect (REQ-PRESENCE-017). `root` is intrinsic-web: the
+  // native entry has no stylesheet-injection root, so runtime injection receives a precise
+  // platform refusal rather than the generic unknown-prop diagnostic.
+  for (const key of Object.keys(rest)) {
+    if ((rest as Record<string, unknown>)[key] === undefined) continue
+    const error =
+      key === 'root'
+        ? new Error(
+            "AnimatePresence prop 'root' is intrinsic-web and platform-unavailable on React " +
+              'Native; use it only on the web entry (REQ-PRESENCE-023).',
+          )
+        : new Error(
+            `AnimatePresence prop '${key}' is outside the contracted native presence surface ` +
+              '(REQ-PRESENCE-010/017).',
+          )
+    if (ambientNativeSeverity() === 'development') throw error
+    consoleReporter(error)
+  }
+  // Deferred surface gate (severity law): dev throws here, production reports + refuses —
+  // matching the web wrapper render-for-render.
+  const effectiveMode = gateDeferredPresenceProps(
+    { mode, custom },
+    ambientNativeSeverity(),
+    consoleReporter,
+  )
+  // Family-6: nested AP joins parent exit when propagate is true (pin usePresence(propagate)).
+  // Closed boolean domain (major 29845259d444): only true/false/undefined accepted.
+  let effectivePropagate = false
+  if (propagate !== undefined && propagate !== true && propagate !== false) {
+    const error = new Error(
+      `AnimatePresence prop 'propagate' must be boolean (got ${typeof propagate}); ` +
+        'invalid values are refused under the severity law (REQ-PRESENCE-010/017).',
+    )
+    if (ambientNativeSeverity() === 'development') throw error
+    consoleReporter(error)
+    effectivePropagate = false
+  } else {
+    effectivePropagate = propagate === true
+  }
+  // subscribe=false when propagate is off — register nothing.
+  const parentPresence = usePresence(effectivePropagate)
+  const isParentPresent = parentPresence[0]
+  const parentSafeToRemove =
+    parentPresence[0] === false && typeof parentPresence[1] === 'function'
+      ? parentPresence[1]
+      : null
+  // Family-6: a propagated nested container exits every mounted child while its parent is not
+  // present, even when those children remain authored in this render.
+  const forceExitAll = effectivePropagate && !isParentPresent
+  const parentSafeToRemoveRef = useRef(parentSafeToRemove)
+  parentSafeToRemoveRef.current = parentSafeToRemove
+  // One release per parent-exit episode (empty/no-exit nested case may not fire onExitComplete).
+  const releasedParentEpisodeRef = useRef(false)
+  if (isParentPresent) releasedParentEpisodeRef.current = false
+  const releaseParentOnce = (): void => {
+    if (releasedParentEpisodeRef.current) return
+    if (parentSafeToRemoveRef.current === null) return
+    releasedParentEpisodeRef.current = true
+    parentSafeToRemoveRef.current()
+  }
+  // Re-render trigger for async presence transitions (exit settle → unmount; wait-mode flushes).
+  const [, setVersion] = useState(0)
+  // Pin PresenceChild initial={false} only on the container's first render (r11/r12).
+  // Layout phase (not passive): a child layout effect must not re-render the container
+  // while the latch is still true (r12 major cc2b0e71f3a6).
+  const isInitialPresenceRenderRef = useRef(true)
+  useLayoutEffect(() => {
+    isInitialPresenceRenderRef.current = false
+  }, [])
+
+  // Behavioral props are read PER RENDER like motion/react's container (review round 6 major
+  // c4b918e2): the exit-complete callback rides a latest-ref so the binding never holds a stale
+  // closure, and a mode change recreates the rig below.
+  // R13 V4: onRest is a pin-catalog alias of onExitComplete (same lifecycle, one fire).
+  const onExitCompleteRef = useRef(onExitComplete ?? onRest)
+  onExitCompleteRef.current = onExitComplete ?? onRest
+
+  // The binding + its manually-stepped graph. The scheduler is core's ManualScheduler advanced
+  // by REAL frame deltas from the stepper below — deterministic core pieces, live time.
+  const rigRef = useRef<{
+    binding: PresenceBinding
+    scheduler: ManualScheduler
+    mode: PresenceMode | undefined
+  } | null>(null)
+  const recreated = useRef(false)
+  // The prior render's records let an idle mode swap prime the replacement binding before the
+  // current child diff. Without that handoff, `sync → popLayout` plus a removal clears the old
+  // binding first and the replacement never learns that the dropped key existed.
+  const previousPresenceChildrenRef = useRef<readonly PresenceChild[]>([])
+  const createRig = (
+    mode: PresenceMode | undefined,
+    firstRender: boolean,
+  ): { binding: PresenceBinding; scheduler: ManualScheduler; mode: PresenceMode | undefined } => {
+    const clock = new ManualClock()
+    const scheduler = new ManualScheduler(clock)
+    const graph = createMotionGraph({ clock, scheduler })
+    const binding = createPresenceBinding({
+      graph,
+      ...(mode === undefined ? {} : { mode }),
+      initial: firstRender ? (initial ?? true) : false,
+      onExitComplete: () => {
+        // Family-6: when nested under a parent exit with propagate, release the parent
+        // presence consumer after every nested exit settles (pin motion/react).
+        releaseParentOnce()
+        const callback = onExitCompleteRef.current
+        if (callback !== undefined) callback()
+        setVersion((v) => v + 1) // wait-mode enters flush after this — re-render to commit them
+      },
+    })
+    return { binding, scheduler, mode }
+  }
+  if (rigRef.current === null) {
+    rigRef.current = createRig(effectiveMode, !recreated.current)
+    recreated.current = true
+  }
+  let binding = rigRef.current.binding
+  let scheduler = rigRef.current.scheduler
+
+  // Collect keyed elements the way the PINNED oracle does (round 19 major 6ca42f0e9bd3:
+  // round-18's loud gate on text/keyless children was an UNRATIFIED divergence —
+  // SPEC-PRESENCE requires Motion compatibility, and motion/react silently filters
+  // non-element children and accepts keyless elements). Children.toArray assigns positional
+  // keys ('.0') to keyless children — the same positional identity motion itself falls back
+  // to, including its known multiple-keyless limitation; non-elements (text, numbers) are
+  // filtered without error, exactly like motion.
+  //
+  // Pin PresenceChild law (r9 major 0f7c3e14a8d2): a Fragment is ONE tracked child. Nested
+  // motion descendants register on the shared presence context and hold the whole child until
+  // every registered exit finishes. Never flatten — independent peer keys diverge from the pin
+  // (no-exit peer would leave immediately while A/C retain).
+  const elements = new Map<string, ReactElement>()
+  for (const child of Children.toArray(children)) {
+    if (!isValidElement(child)) continue
+    elements.set(String(child.key), child)
+  }
+
+  // A mode change swaps the rig (core fixes mode at construction) — but NEVER mid-exit
+  // (review round 7 major 6ab357d3: an eager swap discarded retained exiting children;
+  // SPEC-PRESENCE's retention authority holds across the flip). While exits are in flight the
+  // OLD rig keeps running and its retained children resolve under the old mode; the swap lands
+  // at the first idle render — the stepper re-renders at every settle edge, so idleness is
+  // always observed promptly. When the current render removes a key, or propagation forces every
+  // authored key out, prime the replacement from the prior render before syncing the new set so
+  // the removal is visible under the new mode. The authored set can remain unchanged on a
+  // parent-exit render.
+  if (rigRef.current.mode !== effectiveMode && binding.idle()) {
+    const previousMounted = binding.mounted()
+    const nextRig = createRig(effectiveMode, false)
+    if (forceExitAll || previousMounted.some((key) => !elements.has(key))) {
+      nextRig.binding.sync(previousPresenceChildrenRef.current)
+    }
+    rigRef.current = nextRig
+    binding = nextRig.binding
+    scheduler = nextRig.scheduler
+  }
+  const popLayoutActive = rigRef.current.mode === 'popLayout'
+
+  // usePresence consumer registry: a child whose subtree registered a consumer is a MANUAL exit
+  // (REQ-PRESENCE-014). Consumers register in effects, i.e. AFTER their first render — which is
+  // exactly the spec's shape: deferral matters at DROP time, by which the consumer has mounted.
+  const bindingRef = useRef(binding)
+  bindingRef.current = binding
+  const consumerLatchRef = useRef<PresenceConsumerLatch | null>(null)
+  // A latch delivery lands inside a passive-effect flush, but a consumer REGISTERING later in
+  // that SAME flush must still join the episode (r8 finding 9b42f2c7e1a6): a drop-time deferred
+  // record has no scalar animation to bridge the gap, so a synchronous key-wide release would
+  // resolve the controller before the late registration effect runs. Finalize releases at the
+  // NEXT commit instead — React flushes every passive effect of the commit before the version
+  // bump re-renders, so by flush time a same-flush registration has already reopened the episode
+  // and its pending release is simply dropped (the joiner's own release re-delivers).
+  const pendingReleasesRef = useRef(new Set<string>())
+  if (consumerLatchRef.current === null) {
+    consumerLatchRef.current = createPresenceConsumerLatch(
+      (key) => {
+        pendingReleasesRef.current.add(key)
+        setVersion((v) => v + 1)
+      },
+      // The r5 retention-authority coupling: a consumer joining a live exit upgrades the RETAINED
+      // controller record (deferExit), so the scalar exit completing cannot unmount the key ahead
+      // of the consumer's release. A mode-swap recreates the binding mid-life; route through the
+      // latest-ref like the release path so the adoption always lands in the live controller.
+      (key) => {
+        bindingRef.current.deferExit(key)
+      },
+    )
+  }
+  const consumerLatch = consumerLatchRef.current
+
+  // The direct native host registers a stable reader after mount. On a drop render, read it BEFORE
+  // presence mutates lifecycle state and pass the resulting immutable data through the binding/core seam.
+  const liveValueReadersRef = useRef(new Map<string, Set<PresenceLiveValuesReader>>())
+  const liveValueRegistrationCacheRef = useRef(new Map<string, PresenceLiveValuesRegistration>())
+  const liveOriginKeysRef = useRef(new Map<string, readonly string[]>())
+  // Measure-length exit keys per child (review 2f3a8e6c1d90): their retention endpoints must
+  // arrive px-resolved from the child's own layout context at the removal boundary.
+  const lengthExitKeysRef = useRef(new Map<string, readonly string[]>())
+  const removalSnapshotsRef = useRef(new Map<string, PresenceRemovalSnapshot>())
+  // PopChild's native equivalent keeps the direct host and last element available through the
+  // removal snapshot. Ref entries are keyed and stable unless the authored ref itself changes.
+  const popLayoutRectsRef = useRef(new Map<string, ReturnType<typeof readPopLayoutRect>>())
+  const popLayoutHostRefsRef = useRef(new Map<string, PopLayoutHostHandle>())
+  const popLayoutRefCallbacksRef = useRef(
+    new Map<
+      string,
+      {
+        readonly authoredRef: Ref<unknown> | undefined
+        readonly callback: RefCallback<unknown>
+      }
+    >(),
+  )
+  const lastSeenRef = useRef(new Map<string, ReactElement>())
+  // The container's RENDER-CURRENT provider context (review 493cd7e58a10): the drop capture below
+  // runs in THIS render, before the retained child re-renders under a same-commit provider
+  // change — the child reader merges it over its own (stale) box so both lanes resolve the exit
+  // against the same context. The PREVIOUS render's context object rides along (review
+  // 9d78af2e065c): identity with the child's own consumed context proves the child shares this
+  // provider chain (an update's current values are freshest); a different object means a CLOSER
+  // provider sits between container and child and must not be overwritten by the outer one.
+  const renderCurrentLengthContext = useLengthLayoutParentContext()
+  const previousLengthContextRef = useRef<LengthLayoutContext | null>(null)
+  const previousLengthContext = previousLengthContextRef.current
+  previousLengthContextRef.current = renderCurrentLengthContext
+
+  // Commit-boundary release finalization (see the pending-release law above), run from the
+  // container's own passive effect — never from render (r10 finding 4d8c6b9fe2a1): resolving
+  // the last deferred exit reaches the PUBLIC onExitComplete, and a consumer's normal
+  // setState-in-callback pattern must fire from effect context exactly like motion's (a render
+  // invocation emits React's "Cannot update a component while rendering" error and would let an
+  // abandoned render mutate the controller). Ordering still closes the r8 race: this effect is
+  // declared on the container, so React runs every descendant's registration effect first —
+  // a consumer rendered OR staged before finalization has already reopened the episode by the
+  // time this runs, and its pending release is dropped (the joiner's own release re-delivers).
+  // The version bump after a real resolution re-renders so the mounted-set read catches up;
+  // the set is cleared each flush, so a bump-triggered re-run flushes nothing (no loop), and
+  // StrictMode's double effect invocation is safe for the same reason.
+  useEffect(() => {
+    if (pendingReleasesRef.current.size === 0) return
+    let resolvedAny = false
+    for (const key of pendingReleasesRef.current) {
+      if (consumerLatch.isDelivered(key)) {
+        bindingRef.current.safeToRemove(key)
+        resolvedAny = true
+      }
+    }
+    pendingReleasesRef.current.clear()
+    if (resolvedAny) setVersion((v) => v + 1)
+  })
+
+  // Family-6 major a34778f940c7: empty/no-exit nested force-exit never fires binding
+  // onExitComplete — release the parent consumer once the forced drop is idle (effect context).
+  const forceExitAllRef = useRef(false)
+  useEffect(() => {
+    if (!forceExitAllRef.current) return
+    if (!bindingRef.current.idle()) return
+    releaseParentOnce()
+  })
+
+  // Render-time commit sync (the same class of bookkeeping Motion's own container does): the drop
+  // diff must land BEFORE this render's mounted-set read. The binding's sync is diff-based and
+  // guard-idempotent, so a StrictMode double render with the same set is a no-op.
+  // ONE gating pass per commit feeds BOTH the binding and the rendered elements (round 13
+  // major a4f209bd77e1): rendering the ORIGINAL props made MotionView re-validate and re-report
+  // what the container had already reported+refused — the web container clones its children on
+  // gated targets, so production report counts diverged across engines (REQ-PRESENCE-019).
+  const gatedTargets = new Map<
+    string,
+    {
+      animate?: Target
+      exit?: Target
+      transition?: MotionChildProps['transition']
+      animateLabelRefused?: boolean
+      exitLabelRefused?: boolean
+    }
+  >()
+  const presenceChildren = [...elements.entries()].map(([key, element]) => {
+    // PRE-sync state read: a currently-exiting key consumes the incoming transition on
+    // re-entry (r11 major 6f0d2b6721ad).
+    const reenteringActiveExit =
+      binding.mounted().includes(key) && binding.stateOf(key) === 'exiting'
+    const child = toPresenceChild(
+      element,
+      key,
+      consumerLatch.hasConsumers(key),
+      reenteringActiveExit,
+    )
+    gatedTargets.set(key, {
+      ...(child.animate === undefined ? {} : { animate: child.animate }),
+      ...(child.exit === undefined ? {} : { exit: child.exit }),
+      // A consumed transition renders GATED (round-13 parity: one gating pass feeds both
+      // the binding and the render — accepted → same value, refused → stripped).
+      ...(child.transitionConsumed ? { transition: child.transition } : {}),
+      ...(child.animateLabelRefused ? { animateLabelRefused: true } : {}),
+      ...(child.exitLabelRefused ? { exitLabelRefused: true } : {}),
+    })
+    const {
+      transitionConsumed: _consumed,
+      animateLabelRefused: _animateRefused,
+      exitLabelRefused: _exitRefused,
+      ...record
+    } = child
+    liveOriginKeysRef.current.set(
+      key,
+      Object.freeze(
+        Object.entries(record.exit ?? {})
+          .filter(
+            ([property, value]) =>
+              (Array.isArray(value) && value[0] === null) ||
+              // A scalar ANGLE exit under an explicit spring measures its committed degrees
+              // origin (review 4f95f4f8076a) — angles resolve in their own unit, but the
+              // from-current anchor still comes from the committed snapshot.
+              (typeof value === 'string' && UNIVERSAL_SUBSET.get(property)?.valueType === 'angle'),
+          )
+          .map(([property]) => property),
+      ),
+    )
+    lengthExitKeysRef.current.set(
+      key,
+      Object.freeze(
+        Object.entries(record.exit ?? {})
+          .filter(
+            ([property, value]) =>
+              // Only registry-LENGTH keys carry measure-resolved endpoints (review 4f95f4f8076a):
+              // angle strings resolve in degrees without a host and must NOT reach this channel.
+              UNIVERSAL_SUBSET.get(property)?.valueType === 'length' &&
+              ((typeof value === 'string' && !isColor(value)) ||
+                (Array.isArray(value) &&
+                  value.some((element) => typeof element === 'string' && !isColor(element)))),
+          )
+          .map(([property]) => property),
+      ),
+    )
+    return record
+  })
+  // Family-6: when nested under a parent exit with propagate, present keys are empty —
+  // every mounted child exits even while still authored under this container (pin presentKeys=[]).
+  const liveValuesByKey = new Map<string, PresenceLiveValues>()
+  const resolvedExitsByKey = new Map<string, PresenceResolvedExits>()
+  const removalSnapshots = new Map<string, PresenceRemovalSnapshot>()
+  for (const key of binding.mounted()) {
+    if (binding.stateOf(key) !== 'present') continue
+    // Forced parent exit: capture removal origins even though the child is still in `elements`.
+    if (!forceExitAll && elements.has(key)) continue
+    const originKeys = liveOriginKeysRef.current.get(key) ?? []
+    const lengthKeys = lengthExitKeysRef.current.get(key) ?? []
+    if (originKeys.length === 0 && lengthKeys.length === 0) continue
+    // React effect order defines the direct-host authority deterministically: the first mounted
+    // host wins, and removing it promotes the next still-mounted sibling without losing the key.
+    const read = liveValueReadersRef.current.get(key)?.values().next().value
+    if (read !== undefined) {
+      if (originKeys.length > 0) {
+        const values = read(originKeys)
+        liveValuesByKey.set(key, values)
+        removalSnapshots.set(key, { reader: read, values })
+      }
+      // The removal-boundary endpoint resolution (review 2f3a8e6c1d90): the child's OWN host
+      // resolves each measure-length exit array against its live layout context — the same
+      // resolveLengthToPx the property lane performs — so presence retention measures real px.
+      // The container's render-current context rides along (review 493cd7e58a10).
+      if (lengthKeys.length > 0 && read.readResolvedExits !== undefined) {
+        resolvedExitsByKey.set(
+          key,
+          read.readResolvedExits(lengthKeys, renderCurrentLengthContext, previousLengthContext),
+        )
+      }
+    }
+  }
+  const capturePopLayoutRect = (key: string, event: unknown, style: unknown): void => {
+    const rect = readPopLayoutRect(
+      event,
+      popLayoutHostRefsRef.current.get(key),
+      resolvePopLayoutDirection(style),
+    )
+    if (rect !== undefined) popLayoutRectsRef.current.set(key, rect)
+  }
+  const popLayoutRefFor = (
+    key: string,
+    authoredRef: Ref<unknown> | undefined,
+  ): RefCallback<unknown> => {
+    const cached = popLayoutRefCallbacksRef.current.get(key)
+    if (cached !== undefined && cached.authoredRef === authoredRef) return cached.callback
+    const callback: RefCallback<unknown> = (node) => {
+      if (node === null) {
+        popLayoutHostRefsRef.current.delete(key)
+        setPresenceChildRef(authoredRef, null)
+        return
+      }
+      popLayoutHostRefsRef.current.set(key, node as PopLayoutHostHandle)
+      const authoredCleanup = setPresenceChildRef(authoredRef, node)
+      return () => {
+        if (popLayoutHostRefsRef.current.get(key) === node) {
+          popLayoutHostRefsRef.current.delete(key)
+        }
+        if (typeof authoredCleanup === 'function') authoredCleanup()
+        else setPresenceChildRef(authoredRef, null)
+      }
+    }
+    popLayoutRefCallbacksRef.current.set(key, { authoredRef, callback })
+    return callback
+  }
+  // The child `onLayout` can precede an independent parent resize. Refresh parent geometry at the
+  // actual removal boundary, matching PopChildMeasure.getSnapshotBeforeUpdate rather than using a
+  // stale parent box.
+  for (const key of binding.mounted()) {
+    if (binding.stateOf(key) !== 'present') continue
+    if (!forceExitAll && elements.has(key)) continue
+    const rect = popLayoutRectsRef.current.get(key)
+    if (rect === undefined) continue
+    const source = elements.get(key) ?? lastSeenRef.current.get(key)
+    const style = (source?.props as MotionChildProps | undefined)?.style
+    popLayoutRectsRef.current.set(
+      key,
+      refreshPopLayoutRect(
+        rect,
+        popLayoutHostRefsRef.current.get(key),
+        resolvePopLayoutDirection(style),
+      ),
+    )
+  }
+  binding.sync(forceExitAll ? [] : presenceChildren, liveValuesByKey, resolvedExitsByKey)
+  previousPresenceChildrenRef.current = presenceChildren
+  forceExitAllRef.current = forceExitAll
+  // Publish only after the controller accepted the whole removal commit. The same immutable object
+  // now feeds retention and the retained host's later passive-effect command; no second live read.
+  for (const [key, snapshot] of removalSnapshots) removalSnapshotsRef.current.set(key, snapshot)
+  for (const key of elements.keys()) {
+    if (binding.stateOf(key) === 'present') removalSnapshotsRef.current.delete(key)
+  }
+  // `setPresent(false)` may create an empty state so a layoutId introduced in this commit can
+  // register after render. Drop that marker once the graph has actually removed its key; otherwise
+  // consumer-free exits would retain unreachable latch entries for the container's lifetime.
+  consumerLatch.pruneUnmounted(binding.mounted())
+  const mountedAfterSync = new Set(binding.mounted())
+  for (const key of liveValueReadersRef.current.keys()) {
+    if (!mountedAfterSync.has(key)) {
+      liveValueReadersRef.current.delete(key)
+      liveOriginKeysRef.current.delete(key)
+      lengthExitKeysRef.current.delete(key)
+    }
+  }
+  for (const key of removalSnapshotsRef.current.keys()) {
+    if (!mountedAfterSync.has(key)) removalSnapshotsRef.current.delete(key)
+  }
+  for (const key of popLayoutRectsRef.current.keys()) {
+    if (!mountedAfterSync.has(key)) popLayoutRectsRef.current.delete(key)
+  }
+  for (const key of popLayoutRefCallbacksRef.current.keys()) {
+    if (!mountedAfterSync.has(key)) popLayoutRefCallbacksRef.current.delete(key)
+  }
+
+  // Last-seen elements for retained (exiting) keys — a dropped key is absent from `elements`, so its
+  // exit clone renders from what it last looked like. Stored as GATED clones: the rendered child
+  // (present or exiting) carries exactly what the container's boundary kept — an explicitly-
+  // undefined animate/exit strips a fully-refused original (the no-exit removal path).
+  for (const [key, element] of elements) {
+    const gated = gatedTargets.get(key)
+    const authored = element.props as MotionChildProps
+    // Only forward motion props when the child authored them (or the gate produced a value).
+    // A Fragment PresenceChild has no animate/exit — cloneElement must not inject those props
+    // (React.Fragment accepts only key/children; pin wraps Fragment without retargeting it).
+    const animatePatch = isRuntimeVariantDefinitionForm(authored.animate)
+      ? gated?.animateLabelRefused === true
+        ? { animate: undefined }
+        : {}
+      : typeof authored.animate === 'boolean'
+        ? {}
+        : authored.animate !== undefined || gated?.animate !== undefined
+          ? { animate: gated?.animate }
+          : {}
+    const exitPatch = isRuntimeVariantDefinitionForm(authored.exit)
+      ? gated?.exitLabelRefused === true
+        ? { exit: undefined }
+        : {}
+      : authored.exit !== undefined || gated?.exit !== undefined
+        ? { exit: gated?.exit }
+        : {}
+    // Capture parent-relative geometry even before a mode switch into popLayout. The pinned
+    // PopChild remains mounted when pop is false so it can snapshot the same transition; the
+    // native direct host must therefore keep this observer installed across all presence modes.
+    const directNativeHost = element.type !== Fragment && isNativeMotionHost(element.type)
+    const layoutCaptureOnLayout = directNativeHost
+      ? composePopLayoutOnLayout(authored.onLayout, (event) =>
+          capturePopLayoutRect(key, event, authored.style),
+        )
+      : undefined
+    const layoutCaptureRef = directNativeHost ? popLayoutRefFor(key, authored.ref) : undefined
+    lastSeenRef.current.set(
+      key,
+      cloneElement(element as ReactElement<Record<string, unknown>>, {
+        // R7 (M2 r2 major 16): an ACCEPTED authored label form survives the clone — the
+        // rendered child must execute labels PER LABEL and keep its controlling/joined
+        // tree role; the gated flattened targets feed only the binding's bookkeeping. A
+        // production-REFUSED label prop is STRIPPED (M2 r3 major 5a64e2f0c19b: one report
+        // at this boundary, never a second at the child's gate). Object forms render
+        // gated exactly as before (one gating pass feeds binding and render).
+        ...animatePatch,
+        ...exitPatch,
+        ...(layoutCaptureOnLayout === undefined ? {} : { onLayout: layoutCaptureOnLayout }),
+        ...(layoutCaptureRef === undefined ? {} : { ref: layoutCaptureRef }),
+        ...(gated !== undefined && 'transition' in gated ? { transition: gated.transition } : {}),
+      }),
+    )
+  }
+
+  // The stepper: drive the graph with real frame deltas ONLY while exits are in flight; when the
+  // mounted set changes (an exit settled → key removed), bump the version so React unmounts it.
+  // Stops itself the moment the binding reports idle — zero per-frame cost at rest.
+  const stepperRef = useRef<{ running: boolean; raf: number; last: number }>({
+    running: false,
+    raf: 0,
+    last: 0,
+  })
+  useEffect(() => {
+    const stepper = stepperRef.current
+    if (stepper.running || binding.idle()) return
+    stepper.running = true
+    stepper.last = 0
+    const loop = (now: number): void => {
+      const dt = stepper.last === 0 ? 0 : now - stepper.last
+      stepper.last = now
+      const before = binding.mounted().join('|')
+      if (dt > 0) scheduler.frame(dt)
+      const after = binding.mounted().join('|')
+      if (before !== after) setVersion((v) => v + 1)
+      if (binding.idle()) {
+        stepper.running = false
+        return
+      }
+      stepper.raf = requestAnimationFrame(loop)
+    }
+    stepper.raf = requestAnimationFrame(loop)
+    return () => {
+      // Unmounting the container cancels the loop; the binding/graph go with it.
+      cancelAnimationFrame(stepper.raf)
+      stepper.running = false
+    }
+  })
+
+  // Per-key context values are CACHED and rebuilt only when isPresent flips: a fresh object every
+  // render would re-run every consumer's registration effect (deps: [context]) and loop. A consumer
+  // registering BUMPS the version so the next commit re-syncs with deferred=true — without the bump
+  // the controller's last-seen child predates the registration and a drop exits immediately (the
+  // live check caught exactly this).
+  const contextCacheRef = useRef(
+    new Map<
+      string,
+      {
+        isPresent: boolean
+        removalSnapshot: PresenceRemovalSnapshot | undefined
+        nestedExitAuthority: boolean
+        enterSuppressed: boolean
+        value: PresenceContextValue
+      }
+    >(),
+  )
+  // Registration identity is independent of the present/exiting value object. A presence flip
+  // must not make usePresence clean up the sole consumer before installing its exiting tuple.
+  const registrationCacheRef = useRef(new Map<string, PresenceRegistration>())
+  // The previous render's child order — the splice base for exiting children (pin parity).
+  const renderedOrderRef = useRef<readonly string[]>([])
+
+  // Render the controller's mounted set in the PIN's order (motion AnimatePresence index.tsx
+  // 125-151, T22 packet F6): PRESENT children take the CURRENT React child order; each
+  // EXITING child is spliced back at the index it held in the PREVIOUS render. The ledger's
+  // insertion order APPENDED a prepended enter (Android device evidence — data b=3-7-8-9
+  // rendered 7,8,9,3), so the ledger stays the render SET authority while order derives here.
+  const mountedNow = binding.mounted()
+  const mountedSet = new Set(mountedNow)
+  const orderedKeys: string[] = []
+  for (const key of elements.keys()) {
+    if (mountedSet.has(key) && binding.isPresent(key)) orderedKeys.push(key)
+  }
+  const previousOrder = renderedOrderRef.current
+  for (let i = 0; i < previousOrder.length; i++) {
+    const key = previousOrder[i]!
+    if (mountedSet.has(key) && !binding.isPresent(key)) {
+      orderedKeys.splice(Math.min(i, orderedKeys.length), 0, key)
+    }
+  }
+  // Fail-safe totality: every mounted key renders exactly once — a retained key absent from
+  // the previous render (unreachable by construction) appends rather than vanishes.
+  if (orderedKeys.length !== mountedNow.length) {
+    const seen = new Set(orderedKeys)
+    for (const key of mountedNow) {
+      if (!seen.has(key)) orderedKeys.push(key)
+    }
+  }
+  renderedOrderRef.current = orderedKeys
+
+  // Render through the exported decorator (exit retarget + enter suppression — the
+  // render-path logic the checks drive directly).
+  const rendered: ReactElement[] = []
+  for (const key of orderedKeys) {
+    // lastSeenRef holds the GATED clone for every present key (updated just above) and the
+    // last gated shape for retained (exiting) keys — originals never reach the render.
+    const element = lastSeenRef.current.get(key)
+    if (element === undefined) continue // unreachable: a mounted key was seen on a prior commit
+    const isPresent = binding.isPresent(key)
+    consumerLatch.setPresent(key, isPresent)
+    // REQ-PRESENCE-016 / pin: initial={false} only on the container's first render
+    // (r11/r12). Sticky binding.enterSuppressed would suppress later nested mounts.
+    const enterSuppressed = isPresent && isInitialPresenceRenderRef.current && initial === false
+    let finalElement = decoratePresenceChild(binding, key, element)
+    if (popLayoutActive && !isPresent && finalElement.type !== Fragment) {
+      const authored = finalElement.props as MotionChildProps
+      const style = composePopLayoutStyle(
+        authored.style,
+        popLayoutRectsRef.current.get(key),
+        anchorX,
+        anchorY,
+      )
+      if (style !== authored.style) {
+        finalElement = cloneElement(finalElement as ReactElement<Record<string, unknown>>, {
+          style,
+        })
+      }
+    }
+    // Direct hosts get first-render suppress via clone; Fragment hosts via context only.
+    if (enterSuppressed && finalElement.type !== Fragment) {
+      finalElement = cloneElement(finalElement as ReactElement<{ initial?: Target | false }>, {
+        initial: false,
+      })
+    }
+    const removalSnapshot = isPresent ? undefined : removalSnapshotsRef.current.get(key)
+    // Nested exit authority: Fragment (and any host without an authored object/label exit)
+    // relies on descendants to register and complete exits — pin PresenceChild law.
+    const hostExit = (element.props as MotionChildProps).exit
+    const nestedExitAuthority =
+      element.type === Fragment ||
+      hostExit === undefined ||
+      (typeof hostExit === 'object' &&
+        hostExit !== null &&
+        !Array.isArray(hostExit) &&
+        Object.keys(hostExit as object).length === 0)
+    const cached = contextCacheRef.current.get(key)
+    let contextValue: PresenceContextValue
+    if (
+      cached !== undefined &&
+      cached.isPresent === isPresent &&
+      cached.removalSnapshot === removalSnapshot &&
+      cached.nestedExitAuthority === nestedExitAuthority &&
+      cached.enterSuppressed === enterSuppressed
+    ) {
+      contextValue = presenceAffectsLayout ? { ...cached.value } : cached.value
+    } else {
+      let registration = registrationCacheRef.current.get(key)
+      if (registration === undefined) {
+        registration = {
+          // The bump is load-bearing (review cycle 3 major 4): a manual removal happens BETWEEN
+          // stepper frames, so its before/after diff never sees it — without this render trigger a
+          // deferred child that called safeToRemove stays rendered until an unrelated commit, and
+          // concurrent deferred children cannot unmount independently.
+          safeToRemove: (consumerId) => {
+            consumerLatch.safeToRemove(key, consumerId)
+          },
+          register: (consumerId) => {
+            const unregister = consumerLatch.register(key, consumerId)
+            setVersion((v) => v + 1) // re-sync so the controller learns this child is deferred
+            return () => {
+              unregister()
+              // Symmetric re-sync (review cycle 2 major 3): without it a consumer removed while its
+              // child stays present leaves stale deferred:true in the controller's last-seen child —
+              // a later drop then opens a manual exit NO live hook can release (retained forever,
+              // graph unsettled). React 18+ treats a post-unmount setState as a no-op.
+              setVersion((v) => v + 1)
+            }
+          },
+        }
+        registrationCacheRef.current.set(key, registration)
+      }
+      contextValue = {
+        isPresent,
+        registration,
+        ...(custom === undefined ? {} : { custom }),
+        nestedExitAuthority,
+        enterSuppressed,
+        ...(removalSnapshot === undefined ? {} : { removalSnapshot }),
+      }
+      contextCacheRef.current.set(key, {
+        isPresent,
+        removalSnapshot,
+        nestedExitAuthority,
+        enterSuppressed,
+        value: contextValue,
+      })
+    }
+    rendered.push(
+      <PresenceContext.Provider key={key} value={contextValue}>
+        <PresenceLiveValuesContext.Provider
+          value={
+            liveValueRegistrationCacheRef.current.get(key) ??
+            (() => {
+              const registration: PresenceLiveValuesRegistration = {
+                isRegistered(read) {
+                  return liveValueReadersRef.current.get(key)?.has(read) === true
+                },
+                register(read) {
+                  let readers = liveValueReadersRef.current.get(key)
+                  if (readers === undefined) {
+                    readers = new Set()
+                    liveValueReadersRef.current.set(key, readers)
+                  }
+                  readers.add(read)
+                  return () => {
+                    readers.delete(read)
+                    if (readers.size === 0 && liveValueReadersRef.current.get(key) === readers) {
+                      liveValueReadersRef.current.delete(key)
+                    }
+                  }
+                },
+              }
+              liveValueRegistrationCacheRef.current.set(key, registration)
+              return registration
+            })()
+          }
+        >
+          {finalElement}
+        </PresenceLiveValuesContext.Provider>
+      </PresenceContext.Provider>,
+    )
+  }
+
+  return <>{rendered}</>
+}