@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/presenceBinding.ts

@@ -0,0 +1,382 @@
+// The presence binding's brain (specs/M2.3-BUILD-PACKET.md): the non-React layer AnimatePresence
+// wraps thinly — the same controller/component split MotionView uses. It owns (a) the boundary
+// guards (core validation FIRST, then the exit-keys ⊆ animate-keys spike guard — the M2.2 lessons:
+// guard every phase, validation-first ordering), and (b) the pass-through to core's
+// createPresenceController, which owns retention/settle/cancel/mode ordering. Checks drive THIS
+// surface deterministically with a ManualClock/ManualScheduler graph; the React container adds only
+// keyed-children plumbing and the exits-in-flight rAF stepper.
+//
+import {
+  InvalidTransitionError,
+  captureTransition,
+  validateTransitionRefusal,
+  createPresenceController,
+  springKeyframeCountRefusal,
+  type MotionGraph,
+  type PresenceChild,
+  type PresenceController,
+  type PresenceMode,
+  type PresenceState,
+  type ResolvedTargetValue,
+  type ResolvedValue,
+  type Target,
+  type Transition,
+  TARGET_PROPERTY_KEYS,
+} from '@unrulysystems/native-motion-core'
+import { resolveTransitionForKey } from '@unrulysystems/native-motion-core/internal-driver'
+import { materializeTargetArrays, validateAgainstNativeHost } from './motionViewController'
+import { NATIVE_PROPERTY_TRANSITION_OPTIONS, exitLaneInexecutableOption } from './shippedSurface'
+import { keyframeTimingRefusal } from './keyframeTiming'
+
+export type PresenceLiveValues = Readonly<Record<string, ResolvedValue>>
+
+// Host-RESOLVED px endpoints for measure-length exit arrays (review 2f3a8e6c1d90), captured at the
+// removal boundary from the child's own layout context — the same resolution the property lane
+// performs. Mirrors core's PresenceResolvedExits structurally (the presence barrel does not export
+// it, same as PresenceLiveValues above).
+export type PresenceResolvedExits = Readonly<Record<string, readonly (number | null)[]>>
+
+const TRANSITION_MAP_KEYS = new Set<string>(['default', 'layout', ...TARGET_PROPERTY_KEYS])
+
+function transitionMapSourceKey(transition: Transition, key: string): string {
+  const source = transition as Record<PropertyKey, unknown>
+  if (
+    TRANSITION_MAP_KEYS.has(key) &&
+    Object.hasOwn(source, key) &&
+    source[key] !== undefined &&
+    source[key] !== null
+  )
+    return key
+  if (Object.hasOwn(source, 'default') && source.default !== undefined && source.default !== null)
+    return 'default'
+  return 'root'
+}
+
+function hasTransitionMap(transition: Transition): boolean {
+  return Reflect.ownKeys(transition).some(
+    (key) => typeof key === 'string' && TRANSITION_MAP_KEYS.has(key),
+  )
+}
+
+export interface PresenceBindingOptions {
+  readonly graph: MotionGraph
+  // Passed through verbatim — popLayout shares core's sync ordering; native geometry composition
+  // is applied by the presence renderer around the retained child.
+  readonly mode?: PresenceMode
+  readonly initial?: boolean
+  readonly onExitComplete?: () => void
+}
+
+// The controller surface the container consumes, plus the binding-level guards. Mirrors the
+// controller names 1:1 so nothing is re-invented (REQ-PRESENCE-010 altitude).
+export interface PresenceBinding {
+  // Boundary-guarded commit: validates every child's exit target through core FIRST
+  // (InvalidTargetError for unknown/off-host keys), then enforces exit-keys ⊆ animate-keys (an
+  // un-mounted exit key has no shared value at the MotionView altitude — fail loud HERE, never late
+  // in the driver), then hands the set to the controller. `resolvedExitsByKey` carries the host's
+  // px-resolved endpoints for measure-length exit arrays (review 2f3a8e6c1d90).
+  sync(
+    children: readonly PresenceChild[],
+    liveValuesByKey?: ReadonlyMap<string, PresenceLiveValues>,
+    resolvedExitsByKey?: ReadonlyMap<string, PresenceResolvedExits>,
+  ): void
+  mounted(): readonly string[]
+  stateOf(key: string): PresenceState
+  isPresent(key: string): boolean
+  safeToRemove(key: string): void
+  // Mid-exit manual-authority adoption (REQ-PRESENCE-001/013/014): a consumer registering into a
+  // live exit episode upgrades the retained controller record — see PresenceController.deferExit.
+  deferExit(key: string): void
+  resolvedExitTarget(key: string): Readonly<Record<string, ResolvedTargetValue>> | undefined
+  enterSuppressed(key: string): boolean
+  exitProgress(key: string): number | undefined
+  // True when the graph has no in-flight presence work — the container's stepper stop signal.
+  idle(): boolean
+  // Exposed for the container/checks; never re-wrapped.
+  readonly controller: PresenceController
+}
+
+// Boundary guard for one child, run BEFORE any controller mutation so an invalid commit never
+// partially applies (fail-closed, REQ-API-013 altitude). Ordering is the contract (M2.2 review
+// lessons): core validation FIRST — an unknown/off-host key in animate OR exit throws the pipeline's
+// InvalidTargetError — then the spike's exit-keys ⊆ animate-keys guard (an un-mounted exit key has
+// no shared value at the MotionView altitude; letting it through dies late in the driver).
+/**
+ * The exit lane's transition law, exported for the container's severity gate (r11 major
+ * 1c3f4f0b4b77): core validateTransition plus the exit-lane vocabulary — the presence exit
+ * generator never reads delay or velocity; explicitly-undefined options read as absent
+ * (core semantics, r10 major 6ac18d94e2f7). Loud by design; severity callers wrap it.
+ */
+export function exitLaneTransitionRefusal(
+  transition: PresenceChild['transition'],
+  componentId: string,
+  propertyKeys?: readonly string[],
+): Error | null {
+  if (transition === undefined) return null
+  const coreRefusal = validateTransitionRefusal(transition, { componentId })
+  if (coreRefusal !== null) return coreRefusal
+  if (hasTransitionMap(transition)) {
+    // Generic core validation above checks every authored branch's shape and ranges. The exit lane's
+    // executable vocabulary is narrower, so apply it only after the actual exit properties select a
+    // branch; unused root/default/named bags cannot reject a reachable exit.
+    if (propertyKeys === undefined || propertyKeys.length === 0) return null
+    const source = transition as Transition
+    const seen = new Set<string>()
+    for (const key of propertyKeys) {
+      const sourceKey = transitionMapSourceKey(source, key)
+      if (seen.has(sourceKey)) continue
+      seen.add(sourceKey)
+      const refusal = exitLaneTransitionRefusal(resolveTransitionForKey(source, key), componentId)
+      if (refusal !== null) return refusal
+    }
+    return null
+  }
+  // The exit generator's executable vocabulary is defined over every authored own field, not just
+  // enumerable ones. Core has already closed symbols/unknowns; inspect all retained string keys here
+  // so a non-enumerable lane-inert option cannot survive into the exit progress factory.
+  for (const option of Reflect.ownKeys(transition)) {
+    if (typeof option !== 'string') continue
+    const value = (transition as Record<string, unknown>)[option]
+    if (value === undefined) continue
+    // U7a: the authored instant lane (`type: false`) is property-lane only. The exit progress
+    // factory advances a 0→1 progress curve, not a per-value animation, so `type: false` would
+    // ride along as a default-duration tween — the silently-inert class this gate exists to
+    // refuse. Demand-gated divergence, same shape as the repeat family below.
+    if (option === 'type' && value === false) {
+      return new InvalidTransitionError(
+        componentId,
+        'type',
+        false,
+        'the exit lane cannot execute type: false — the exit generator advances a PROGRESS ' +
+          'factory, not a per-value animation, so the authored instant lane never reaches it ' +
+          '(U7a / G-INV-8). Instant exit is a scoped successor rung; drive it on the property ' +
+          'lane instead.',
+      )
+    }
+    if (exitLaneInexecutableOption(option)) {
+      return new InvalidTransitionError(
+        componentId,
+        option,
+        value,
+        `is not executable by the exit lane — the exit generator advances a PROGRESS factory, ` +
+          `not a sampled generator, so it never reads '${option}' and the option would ride ` +
+          'along inert (G-INV-8). This family on the presence exit lane is a scoped successor ' +
+          `rung; drive it on the property lane instead (T18-a repeat, T18-b delay).`,
+      )
+    }
+    if (!NATIVE_PROPERTY_TRANSITION_OPTIONS.has(option)) {
+      return new InvalidTransitionError(
+        componentId,
+        option,
+        value,
+        `not executable by the exit lane (it drives: ` +
+          `${NATIVE_PROPERTY_TRANSITION_OPTIONS.options.join(', ')}) — a silently inert ` +
+          'option is refused (G-INV-8, shippedSurface.ts)',
+      )
+    }
+  }
+  return null
+}
+
+export function validateExitLaneTransition(
+  transition: PresenceChild['transition'],
+  componentId: string,
+  propertyKeys?: readonly string[],
+): void {
+  const refusal = exitLaneTransitionRefusal(transition, componentId, propertyKeys)
+  if (refusal !== null) throw refusal
+}
+
+// R8-F1 for the exit/animate arrays under a VALID exit-lane spring (review major 46 — the direct-
+// consumer backstop the public container gate mirrors): a spring interpolates exactly two keyframes.
+// Runs only AFTER exitLaneTransitionRefusal passed, so an invalid transition (falls back to default)
+// never triggers it. Loud by design — a container consumer refuses/reports before reaching here.
+function assertExitArraySpringCompat(child: PresenceChild): void {
+  for (const target of [child.animate, child.exit]) {
+    if (target === undefined) continue
+    for (const [key, value] of Object.entries(target)) {
+      if (!Array.isArray(value)) continue
+      const transition =
+        child.transition === undefined
+          ? undefined
+          : resolveTransitionForKey(child.transition as Transition, key)
+      if (transition?.type !== 'spring') continue
+      const refusal = springKeyframeCountRefusal(value.length)
+      if (refusal !== null) throw refusal
+    }
+  }
+}
+
+// R8 M2-B (REQ-API-033 law d): the direct-consumer keyframe-timing backstop (mirrors the spring one
+// above, review major 46). It validates offset/easing shapes for directly-`sync`'d children; count-
+// mismatched `times` fall back to even offsets, missing segment easings are linear, extras are
+// ignored, and keyframe-only timing still refuses as inert on a scalar member.
+// The public container's exit/animate lanes route through gateTargetWithSeverity (keyBoundaryRefusal),
+// so this covers only the DIRECT `createPresenceBinding` consumer. Loud by design (after the transition
+// validated), per key.
+function assertExitArrayKeyframeTiming(child: PresenceChild): void {
+  for (const target of [child.animate, child.exit]) {
+    if (target === undefined) continue
+    for (const [key, value] of Object.entries(target)) {
+      const transition =
+        child.transition === undefined
+          ? undefined
+          : resolveTransitionForKey(child.transition as Transition, key)
+      const refusal = keyframeTimingRefusal(
+        `<AnimatePresence child '${child.key}'>`,
+        key,
+        value,
+        transition,
+      )
+      if (refusal !== null) throw refusal
+    }
+  }
+}
+
+function guardChild(
+  child: PresenceChild,
+  consumesTransition: boolean,
+  reenteringActiveExit = false,
+): void {
+  // The captured transition seeds the presence graph's exit progress factory (r9 major
+  // 4fe88c31a121) — consumed when the child carries an exit target OR re-enters an ACTIVE
+  // exit episode (r11 major 6f0d2b6721ad: re-entry hands the incoming transition to
+  // progressFactory regardless of the current exit prop). Outside those cases presence
+  // never consumes it (r10 major b2e74f1309ac) and the child's own MotionView gate owns it.
+  if (consumesTransition) {
+    const consumedKeys = reenteringActiveExit
+      ? [...new Set([...Object.keys(child.animate ?? {}), ...Object.keys(child.exit ?? {})])]
+      : Object.keys(child.exit ?? {})
+    validateExitLaneTransition(child.transition, `<AnimatePresence child '${child.key}'>`, [
+      ...consumedKeys,
+    ])
+  }
+  if (child.animate !== undefined) validateAgainstNativeHost(child.animate)
+  if (child.exit !== undefined) {
+    validateAgainstNativeHost(child.exit)
+    // R7 law g (M2 r2 major 18): the mounted set is the UNION of the animate keys and every
+    // dictionary-named key the container derived — a dictionary key has a shared value even
+    // when no animate target names it. The backstop stays fail-closed outside the union.
+    const mountedKeys = new Set([...Object.keys(child.animate ?? {}), ...(child.mountedKeys ?? [])])
+    for (const key of Object.keys(child.exit)) {
+      if (!mountedKeys.has(key)) {
+        throw new Error(
+          `M2.3 scope: exit key '${key}' on child '${child.key}' was never mounted ` +
+            `(mounted keys: ${[...mountedKeys].join(', ') || 'none'}) — declare it in animate ` +
+            'or the variants dictionary so a shared value exists ' +
+            '(specs/M2.3-BUILD-PACKET.md §semantics 6; REQ-API-032 law g).',
+        )
+      }
+    }
+  }
+  // R8-F1 backstop LAST (review major 46/58): the direct-consumer spring/keyframe-array compat check
+  // runs only AFTER core validated the transition AND the target SHAPE — a malformed target (e.g.
+  // `exit:{x:[]}`) throws its TYPED InvalidTargetError first (validation-first contract), never the
+  // generic cross-field spring error. An invalid transition already threw above; a well-formed array is
+  // all that reaches here.
+  if (consumesTransition) {
+    assertExitArraySpringCompat(child)
+    assertExitArrayKeyframeTiming(child)
+  }
+}
+
+// Hand the controller an IMMUTABLE snapshot of every keyframe array + the transition (review major 64):
+// guardChild validates the caller-owned child, but `beginExit` RE-reads its arrays during exit-target
+// resolution — an accessor-backed `[0,100]` returning `100` to the validator and `null` on the next read
+// would forward `[0,null]` into retained state. The child is validated by the time it reaches here, so
+// the snapshot mirrors exactly what validation saw (one-read / one-truth, the major-30/40 lineage).
+function materializeChild(child: PresenceChild): PresenceChild {
+  const { animate, exit, transition, ...rest } = child
+  return {
+    ...rest,
+    ...(animate !== undefined ? { animate: materializeIfPlain(animate) } : {}),
+    ...(exit !== undefined ? { exit: materializeIfPlain(exit) } : {}),
+    ...(transition !== undefined ? { transition: captureTransitionIfPlain(transition) } : {}),
+  }
+}
+
+// Materialize a plain-object target's keyframe arrays; a MALFORMED target (null, primitive, array, or a
+// PROTOTYPE-carrying object like `Date`/a class instance) passes through UNTOUCHED so guardChild's core
+// validation throws the TYPED InvalidTargetError (materialize runs BEFORE validation for the one-read, so
+// it must never crash on — nor LAUNDER into an empty record — the input validation is meant to reject).
+function materializeIfPlain(target: Target): Target {
+  if (typeof target !== 'object' || target === null || Array.isArray(target)) return target
+  const proto = Object.getPrototypeOf(target) as unknown
+  if (proto !== Object.prototype && proto !== null) return target
+  return materializeTargetArrays(target)
+}
+
+// Capture the transition ONCE (review major 64): guardChild's validateExitLaneTransition + the controller's
+// beginExit both read it, so a caller-owned accessor `duration` would be observed repeatedly and could
+// change after sync. A MALFORMED shape (null, primitive, array, prototype-carrying) passes through so
+// validateExitLaneTransition throws the TYPED refusal — the null-proto capture keeps an own `__proto__`.
+function captureTransitionIfPlain(
+  transition: NonNullable<PresenceChild['transition']>,
+): NonNullable<PresenceChild['transition']> {
+  const t = transition as unknown
+  const proto = typeof t === 'object' && t !== null ? Object.getPrototypeOf(t) : undefined
+  if (
+    typeof t !== 'object' ||
+    t === null ||
+    Array.isArray(t) ||
+    (proto !== Object.prototype && proto !== null)
+  ) {
+    return transition
+  }
+  return captureTransition(transition)
+}
+
+export function createPresenceBinding(options: PresenceBindingOptions): PresenceBinding {
+  // Mode passes through verbatim: popLayout's geometry behavior is owned by the native presence
+  // renderer while the controller retains the same keyed lifecycle ordering.
+  const controller = createPresenceController({
+    graph: options.graph,
+    ...(options.mode === undefined ? {} : { mode: options.mode }),
+    ...(options.initial === undefined ? {} : { initial: options.initial }),
+    ...(options.onExitComplete === undefined ? {} : { onExitComplete: options.onExitComplete }),
+  })
+
+  return {
+    sync(children, liveValuesByKey, resolvedExitsByKey) {
+      // Guard EVERY child before the controller sees ANY of them — no partial commits. The
+      // consumption predicate reads PRE-sync state: a key currently exiting consumes the
+      // incoming transition on re-entry (r11 major 6f0d2b6721ad).
+      const mounted = controller.mountedKeys()
+      // Materialize each child into an IMMUTABLE snapshot FIRST, then validate + forward THAT (review
+      // major 64): validating the caller-owned child before snapshotting reads its accessor arrays twice
+      // (validation, then materialization), so the value validated could differ from the value retained.
+      // The snapshot is the ONE truth guardChild validates AND the controller resolves.
+      const snapshots = children.map(materializeChild)
+      for (const child of snapshots) {
+        const reenteringActiveExit =
+          mounted.includes(child.key) && controller.stateOf(child.key) === 'exiting'
+        guardChild(child, child.exit !== undefined || reenteringActiveExit, reenteringActiveExit)
+      }
+      const capturedLiveValues = new Map<string, PresenceLiveValues>()
+      for (const [key, values] of liveValuesByKey ?? []) {
+        capturedLiveValues.set(key, Object.freeze({ ...values }))
+      }
+      // The same one-read capture for host-resolved endpoints (review 2f3a8e6c1d90): clone + freeze
+      // every endpoint array so a caller-side mutation cannot rewrite the retained measurement.
+      const capturedResolvedExits = new Map<string, PresenceResolvedExits>()
+      for (const [key, exits] of resolvedExitsByKey ?? []) {
+        const frozen: Record<string, readonly (number | null)[]> = {}
+        for (const [property, endpoints] of Object.entries(exits)) {
+          frozen[property] = Object.freeze([...endpoints])
+        }
+        capturedResolvedExits.set(key, Object.freeze(frozen))
+      }
+      controller.syncChildren(snapshots, capturedLiveValues, capturedResolvedExits)
+    },
+    mounted: () => controller.mountedKeys(),
+    stateOf: (key) => controller.stateOf(key),
+    isPresent: (key) => controller.isPresent(key),
+    safeToRemove: (key) => controller.safeToRemove(key),
+    deferExit: (key) => controller.deferExit(key),
+    resolvedExitTarget: (key) => controller.resolvedExitTarget(key),
+    enterSuppressed: (key) => controller.enterSuppressed(key),
+    exitProgress: (key) => controller.exitProgress(key),
+    idle: () => options.graph.isSettled(),
+    controller,
+  }
+}

package/src/native/motion/scaleCorrectorRegistry.ts

@@ -0,0 +1,123 @@
+// UI-global user scale-corrector map (REQ-LAYOUT-024). Named module-level worklet + primitive
+// payloads only (AB-BA hang-class: no worklet-capturing-worklet). The correct function is
+// passed as a worklet argument, never closed over.
+
+import type { ScaleCorrector } from './addScaleCorrector'
+
+interface MutableScaleCorrectionContext {
+  targetDelta: { x: { scale: number }; y: { scale: number } }
+  treeScale: { x: number; y: number }
+}
+
+interface InstalledCorrector {
+  readonly correct: ScaleCorrector
+  readonly applyTo: readonly string[] | null
+}
+
+interface ScaleCorrectorRegistryUiGlobal {
+  __nativeMotionScaleCorrectors?: Record<string, InstalledCorrector>
+}
+
+function scaleCorrectorRegistry(): NonNullable<
+  ScaleCorrectorRegistryUiGlobal['__nativeMotionScaleCorrectors']
+> {
+  'worklet'
+  const global = globalThis as ScaleCorrectorRegistryUiGlobal
+  if (global.__nativeMotionScaleCorrectors === undefined) {
+    global.__nativeMotionScaleCorrectors = {}
+  }
+  return global.__nativeMotionScaleCorrectors
+}
+
+export function installScaleCorrectorOnUI(
+  key: string,
+  correct: ScaleCorrector,
+  applyTo: readonly string[] | null,
+): void {
+  'worklet'
+  scaleCorrectorRegistry()[key] = { correct, applyTo }
+}
+
+// One reused context object (REQ-DRIVER-021): correct() reads it synchronously, so per-call
+// field mutation is safe. A fresh object per frame would break that law.
+function scaleCorrectionContext(): MutableScaleCorrectionContext {
+  'worklet'
+  const global = globalThis as ScaleCorrectorRegistryUiGlobal & {
+    __nativeMotionScaleCorrectionContext?: MutableScaleCorrectionContext
+  }
+  if (global.__nativeMotionScaleCorrectionContext === undefined) {
+    global.__nativeMotionScaleCorrectionContext = {
+      targetDelta: { x: { scale: 1 }, y: { scale: 1 } },
+      treeScale: { x: 1, y: 1 },
+    }
+  }
+  return global.__nativeMotionScaleCorrectionContext
+}
+
+/**
+ * Apply a registered corrector to one authored latest. `transformActive` is the pin's
+ * `transform !== "none"` gate. Missing corrector or inactive transform returns `latest`.
+ */
+export function applyInstalledScaleCorrector(
+  key: string,
+  latest: number | string,
+  targetDeltaScaleX: number,
+  targetDeltaScaleY: number,
+  treeScaleX: number,
+  treeScaleY: number,
+  transformActive: boolean,
+): number | string {
+  'worklet'
+  if (!transformActive) return latest
+  const installed = scaleCorrectorRegistry()[key]
+  if (installed === undefined) return latest
+  const context = scaleCorrectionContext()
+  context.targetDelta.x.scale = targetDeltaScaleX
+  context.targetDelta.y.scale = targetDeltaScaleY
+  context.treeScale.x = treeScaleX
+  context.treeScale.y = treeScaleY
+  return installed.correct(latest, context)
+}
+
+/**
+ * Pin create-projection-node.ts:2102-2106 — when `applyTo` is set, write the
+ * corrected value onto those keys and skip the source key; otherwise write source.
+ */
+export function writeInstalledScaleCorrector(
+  out: Record<string, unknown>,
+  key: string,
+  latest: number | string,
+  targetDeltaScaleX: number,
+  targetDeltaScaleY: number,
+  treeScaleX: number,
+  treeScaleY: number,
+  transformActive: boolean,
+): void {
+  'worklet'
+  const corrected = applyInstalledScaleCorrector(
+    key,
+    latest,
+    targetDeltaScaleX,
+    targetDeltaScaleY,
+    treeScaleX,
+    treeScaleY,
+    transformActive,
+  )
+  const applyTo = scaleCorrectorRegistry()[key]?.applyTo ?? null
+  if (applyTo !== null) {
+    for (let i = 0; i < applyTo.length; i++) {
+      out[applyTo[i]!] = corrected
+    }
+    return
+  }
+  out[key] = corrected
+}
+
+export function resetScaleCorrectorRegistryForTests(): void {
+  delete (globalThis as ScaleCorrectorRegistryUiGlobal).__nativeMotionScaleCorrectors
+  delete (
+    globalThis as ScaleCorrectorRegistryUiGlobal & {
+      __nativeMotionScaleCorrectionContext?: unknown
+    }
+  ).__nativeMotionScaleCorrectionContext
+}