@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/gestureStateGate.ts

@@ -0,0 +1,563 @@
+// The gesture-state boundary gate (R6, REQ-API-031; R7 REQ-API-032 adds the label form): an
+// orphan whileDrag (no drag axis) refuses under the R6-F2 native law (the pinned web engine
+// leaves it silently inert — a recorded divergence; this package never ships a silently dead
+// gesture surface); a whileDrag key colliding with the drag axis is a dual-authority refusal
+// (REQ-DRIVER-029); embedded transitions split from the target; the remaining target
+// validates through the SAME core boundary the animate lane rides (REQ-API-013). A LABEL
+// definition resolves against the element's gated dictionary (entries already carry core
+// validity + native drivability from the dictionary gate) into a per-key-attributed layer
+// (law b); the member conflicts (axis, bound XOR) apply identically to both forms.
+
+import {
+  describeValue,
+  InvalidTargetError,
+  InvalidTransitionError,
+  captureTransition,
+  flattenVariantApplications,
+  hostCapabilities,
+  TARGET_PROPERTY_KEYS,
+  validateTargetRefusal,
+  validateTransitionRefusal,
+  type DragAxis,
+  type Target,
+  type Transition,
+  type VariantResolver,
+  type VariantsDictionary,
+} from '@unrulysystems/native-motion-core'
+import {
+  executableLengthValueRefusal,
+  resolveTransitionForKey,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import type { GestureStateLayer } from './gestureStateResolver'
+import {
+  isNativeExecutableLengthValue,
+  NATIVE_PROPERTY_TRANSITION_OPTIONS,
+  nativeMountTargetValueKind,
+} from './shippedSurface'
+import { keyframeTransitionRefusal } from '@unrulysystems/native-motion-core/internal-driver'
+import {
+  captureBoundedArray,
+  capturedArrayDescription,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import type { StyleValueGate } from './styleValueBinding'
+import type { MotionComponentId } from './motionViewController'
+import { gateLabelDefinition, resolveVariantApplicationsGated } from './variantProps'
+
+const THROW_GATE: StyleValueGate = {
+  severity: 'development',
+  report: () => {},
+  componentId: '<Motion.View>',
+}
+const NATIVE_HOST = hostCapabilities('native', ['universal', 'native-extension'])
+const TRANSITION_MAP_KEYS = new Set<string>(['default', 'layout', ...TARGET_PROPERTY_KEYS])
+
+function hasTransitionMap(transition: Transition): boolean {
+  return Reflect.ownKeys(transition).some(
+    (key) => typeof key === 'string' && TRANSITION_MAP_KEYS.has(key),
+  )
+}
+
+function nativePropertyTransitionRefusal(
+  componentId: MotionComponentId,
+  path: string,
+  transition: Transition,
+  propertyKeys: readonly string[] = ['__root__'],
+): Error | null {
+  const refusalForOption = (
+    option: string,
+    optionValue: unknown,
+    optionPath: string,
+  ): Error | null =>
+    NATIVE_PROPERTY_TRANSITION_OPTIONS.has(option)
+      ? null
+      : new InvalidTransitionError(
+          componentId,
+          option,
+          optionValue,
+          optionPath +
+            ' is not executable by the native property lane (it drives: ' +
+            NATIVE_PROPERTY_TRANSITION_OPTIONS.options.join(', ') +
+            ') — a silently inert option is refused (G-INV-8, shippedSurface.ts)',
+        )
+
+  const refusalForFlatTransition = (selected: Transition, selectedPath: string): Error | null => {
+    for (const option of Reflect.ownKeys(selected)) {
+      if (typeof option !== 'string' || TRANSITION_MAP_KEYS.has(option) || option === 'inherit')
+        continue
+      const optionValue = (selected as Record<string, unknown>)[option]
+      if (optionValue === undefined) continue
+      const refusal = refusalForOption(option, optionValue, selectedPath + '.' + option)
+      if (refusal !== null) return refusal
+    }
+    return null
+  }
+
+  if (!hasTransitionMap(transition)) return refusalForFlatTransition(transition, path)
+
+  const source = transition as Record<PropertyKey, unknown>
+  const selectors = propertyKeys.length === 0 ? ['__root__'] : propertyKeys
+  const seen = new Set<string>()
+  for (const propertyKey of selectors) {
+    const mapKey =
+      Object.hasOwn(source, propertyKey) &&
+      source[propertyKey] !== undefined &&
+      source[propertyKey] !== null
+        ? propertyKey
+        : Object.hasOwn(source, 'default') && source['default'] !== undefined
+          ? 'default'
+          : 'root'
+    if (seen.has(mapKey)) continue
+    seen.add(mapKey)
+    const selected = resolveTransitionForKey(transition, propertyKey)
+    const refusal = refusalForFlatTransition(
+      selected,
+      mapKey === 'root' ? path : path + '.' + mapKey,
+    )
+    if (refusal !== null) return refusal
+  }
+  return null
+}
+
+// Capture a caller-owned embedded transition ONCE into a frozen snapshot (review major 0cb829). A malformed
+// SHAPE (primitive, array, prototype-carrying) stays raw so validateTransitionRefusal throws its typed
+// refusal rather than a capture laundering it into an empty `{}`.
+function captureEmbeddedTransition(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 interface GestureStatePropsInput {
+  readonly whileTap?: unknown
+  readonly whileDrag?: unknown
+}
+
+export interface AcceptedGestureState {
+  whileTap?: GestureStateLayer
+  whileDrag?: GestureStateLayer
+}
+
+export interface GestureStateGateResult {
+  readonly state: AcceptedGestureState
+  /** A property selected the element transition before production refused that property. */
+  readonly fallbackAttempted: boolean
+}
+
+export function gateGestureStateProps(
+  props: GestureStatePropsInput,
+  context: {
+    readonly dragAxes: readonly DragAxis[]
+    /** Style-bound keys (REQ-DRIVER-029 XOR): a bound key can never be gesture-driven. */
+    readonly boundKeys?: readonly string[]
+    /** Exact direct-public numeric bindings whose identity channel owns declarative collisions. */
+    readonly identityEligibleBoundKeys?: readonly string[]
+    /** R7: the element's GATED dictionary — label definitions resolve against it (law a). */
+    readonly variantsDictionary?: VariantsDictionary | undefined
+    /**
+     * The element transition's caller-independent snapshot. A gesture member without an attributed or
+     * embedded transition executes through this fallback, so its target/timing pair is gated here too.
+     */
+    readonly elementTransition?: Transition | undefined
+    // T24 B1: the component custom payload for RESOLVER labels in gesture-state slots.
+    readonly custom?: unknown
+    readonly readValueState?:
+      | (() => {
+          readonly current: Readonly<Record<string, unknown>>
+          readonly velocity: Readonly<Record<string, number>>
+        })
+      | undefined
+    readonly componentId?: MotionComponentId
+  },
+  gate: StyleValueGate = THROW_GATE,
+): AcceptedGestureState {
+  return gateGestureStatePropsWithEvidence(props, context, gate).state
+}
+
+/**
+ * Keep fallback-attempt evidence beside the accepted layers. The public-shaped layer object remains
+ * free of bookkeeping; MotionView alone needs this to avoid a second inert-transition report.
+ */
+export function gateGestureStatePropsWithEvidence(
+  props: GestureStatePropsInput,
+  context: {
+    readonly dragAxes: readonly DragAxis[]
+    readonly boundKeys?: readonly string[]
+    readonly identityEligibleBoundKeys?: readonly string[]
+    readonly variantsDictionary?: VariantsDictionary | undefined
+    readonly elementTransition?: Transition | undefined
+    // T24 B1: the component custom payload for RESOLVER labels in gesture-state slots.
+    readonly custom?: unknown
+    readonly readValueState?:
+      | (() => {
+          readonly current: Readonly<Record<string, unknown>>
+          readonly velocity: Readonly<Record<string, number>>
+        })
+      | undefined
+    readonly componentId?: MotionComponentId
+  },
+  gate: StyleValueGate = THROW_GATE,
+): GestureStateGateResult {
+  const componentId = context.componentId ?? '<Motion.View>'
+  const accepted: AcceptedGestureState = {}
+  let fallbackAttempted = false
+  const refuse = (error: Error): void => {
+    if (gate.severity === 'development') throw error
+    gate.report(error)
+  }
+  /**
+   * The member conflicts BOTH forms ride (per-KEY granularity, r4 major 20): the drag-axis
+   * collision and the bound-key XOR (REQ-DRIVER-029) — the error, or null when the member
+   * is conflict-free.
+   */
+  const memberConflict = (key: 'whileTap' | 'whileDrag', memberKey: string): Error | null => {
+    if (key === 'whileDrag' && context.dragAxes.includes(memberKey as DragAxis)) {
+      return new Error(
+        `${componentId}: R6 scope: whileDrag names the drag axis key '${memberKey}' — a key has ONE ` +
+          'reconciliation authority (REQ-DRIVER-029); the recognizer owns the axis while ' +
+          'dragging.',
+      )
+    }
+    if (
+      context.boundKeys?.includes(memberKey) === true &&
+      context.identityEligibleBoundKeys?.includes(memberKey) !== true
+    ) {
+      return new Error(
+        `${componentId}: R6 scope: '${memberKey}' is style-bound AND a ${key} target key — a key has ONE ` +
+          'reconciliation authority (REQ-DRIVER-029); drive it through the binding or the ' +
+          'gesture state, never both.',
+      )
+    }
+    return null
+  }
+  for (const key of ['whileTap', 'whileDrag'] as const) {
+    const value = props[key]
+    if (value === undefined) continue
+    if (typeof value === 'function' || typeof value === 'string' || Array.isArray(value)) {
+      // The LABEL form (R7, law b): normalize the definition, resolve against the gated
+      // dictionary (a local miss contributes nothing — law a's propagation-source shape),
+      // flatten to per-key attribution, then run the SAME member conflicts the object form
+      // runs. Core validity, drivability, and the property-lane option law already ran at
+      // the dictionary gate — an entry that failed them never reached this dictionary.
+      const labels =
+        typeof value === 'function'
+          ? null
+          : gateLabelDefinition(key, value as string | readonly unknown[], gate, componentId)
+      if (labels === undefined) continue // production refused the label prop — no layer
+      if (key === 'whileDrag' && context.dragAxes.length === 0) {
+        refuse(
+          new Error(
+            `${componentId}: "whileDrag" requires an enabled drag axis — without one the state could never ` +
+              'activate (a silently dead gesture surface; R6-F2 native law, recorded ' +
+              'divergence from the pinned inertness).',
+          ),
+        )
+        continue
+      }
+      const definition: string | readonly string[] | VariantResolver =
+        typeof value === 'function' ? (value as VariantResolver) : labels!
+      const hasResolver =
+        typeof definition === 'function' ||
+        definition.some(
+          (label) =>
+            context.variantsDictionary !== undefined &&
+            Object.hasOwn(context.variantsDictionary, label) &&
+            typeof context.variantsDictionary[label] === 'function',
+        )
+      if (hasResolver) {
+        accepted[key] = {
+          target: {},
+          resolveAtActivation: () => {
+            const applications = resolveVariantApplicationsGated(
+              definition,
+              context.variantsDictionary,
+              gate,
+              componentId,
+              context.custom,
+              context.readValueState,
+            )
+            const synthetic: Record<string, Target & { transition?: Transition }> = {}
+            const syntheticLabels: string[] = []
+            applications.forEach((application, index) => {
+              const label = `__activation_${index}`
+              syntheticLabels.push(label)
+              synthetic[label] = {
+                ...application.target,
+                ...(application.transition === undefined
+                  ? {}
+                  : { transition: application.transition }),
+              }
+            })
+            const resolved = gateGestureStatePropsWithEvidence(
+              { [key]: syntheticLabels },
+              { ...context, variantsDictionary: synthetic },
+              gate,
+            ).state[key]
+            return resolved ?? { target: {} }
+          },
+        }
+        continue
+      }
+      const flattened = flattenVariantApplications(
+        resolveVariantApplicationsGated(
+          definition,
+          context.variantsDictionary,
+          gate,
+          componentId,
+          context.custom,
+          context.readValueState,
+        ),
+      )
+      const labelTarget: Record<string, unknown> = {}
+      const labelTransitions: Record<string, Transition> = {}
+      for (const [memberKey, memberValue] of Object.entries(flattened.target)) {
+        const conflict = memberConflict(key, memberKey)
+        if (conflict !== null) {
+          refuse(conflict)
+          continue
+        }
+        // The label lane runs the SAME native-depth executable matrix as the object lane
+        // (review 91d41675d511): a label-resolved scalar or array element outside the matrix
+        // refuses at the supplying boundary, never latently at activation.
+        if (nativeMountTargetValueKind(memberKey) !== 'color') {
+          const labelLengthRefusal = executableLengthValueRefusal(memberKey, memberValue)
+          if (labelLengthRefusal !== null) {
+            refuse(
+              new Error(
+                `${componentId}: R6 scope: ${key}.${memberKey} received ${describeValue(memberValue)} — ` +
+                  `${labelLengthRefusal} (REQ-API-031).`,
+              ),
+            )
+            continue
+          }
+        }
+        // A resolved label's per-key attribution wins; otherwise it inherits the element transition
+        // just like the object form. Validate the EFFECTIVE transition before constructing the resolver
+        // so a timing mismatch cannot wait until gesture activation.
+        let attributed: Transition | undefined = flattened.transitions[memberKey]
+        // The SAME property-lane option law the object form runs on its embedded transition
+        // (review r2 major 1): the dictionary gate ADMITS the tree-lane orchestration options
+        // (they are legal on the animate lane, where the channel executes them), so a
+        // gesture-pulled label's attribution must refuse them HERE — gesture-lane wave
+        // orchestration is an unshipped REQ-API-053 deferred sibling, and an admitted key
+        // would ride a retarget into the property lane. Production drops the ATTRIBUTION only
+        // (the member survives on the element fallback, which the resolver supplies
+        // driver-clean) — mirroring the object form's transition-drop granularity.
+        if (attributed !== undefined) {
+          const attributionRefusal = nativePropertyTransitionRefusal(
+            componentId,
+            key + '.' + memberKey,
+            attributed,
+            [memberKey],
+          )
+          if (attributionRefusal !== null) {
+            refuse(attributionRefusal)
+            attributed = undefined
+          }
+        }
+        const effectiveTransition =
+          attributed !== undefined
+            ? resolveTransitionForKey(attributed, memberKey)
+            : context.elementTransition === undefined
+              ? undefined
+              : resolveTransitionForKey(context.elementTransition, memberKey)
+        // Evidence reads the LOCAL attribution: a production-dropped orchestration-bearing
+        // attribution really does consume the element fallback (the object form's drop path
+        // reaches the same conclusion through its own local `transition`).
+        if (attributed === undefined && context.elementTransition !== undefined) {
+          fallbackAttempted = true
+        }
+        const timingRefusal = keyframeTransitionRefusal(
+          componentId,
+          memberKey,
+          memberValue,
+          effectiveTransition,
+        )
+        if (timingRefusal !== null) {
+          refuse(timingRefusal)
+          continue
+        }
+        labelTarget[memberKey] = memberValue
+        if (attributed !== undefined) labelTransitions[memberKey] = effectiveTransition!
+      }
+      accepted[key] = {
+        target: labelTarget as Target,
+        ...(Object.keys(labelTransitions).length === 0 ? {} : { transitions: labelTransitions }),
+      }
+      continue
+    }
+    // PLAIN targets only (r3 major 16): a prototype-carrying object (new Date(0)) destructures
+    // to an empty target and would mount a silently dead gesture layer.
+    const proto =
+      typeof value === 'object' && value !== null ? Object.getPrototypeOf(value) : undefined
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      (proto !== Object.prototype && proto !== null)
+    ) {
+      refuse(
+        new Error(
+          `${componentId}: "${key}" must be a plain target object, received ${value === null ? 'null' : typeof value} (REQ-API-031).`,
+        ),
+      )
+      continue
+    }
+    if (key === 'whileDrag' && context.dragAxes.length === 0) {
+      refuse(
+        new Error(
+          `${componentId}: "whileDrag" requires an enabled drag axis — without one the state could never ` +
+            'activate (a silently dead gesture surface; R6-F2 native law, recorded divergence ' +
+            'from the pinned inertness).',
+        ),
+      )
+      continue
+    }
+    // Read `value.transition` EXACTLY ONCE via the destructure (review major a13e69f) — re-reading it for
+    // the capture would observe an outer-property accessor twice. Capture the embedded transition ONCE
+    // (review major 0cb829): it is validated here AND stored in the accepted layer that gesture activation
+    // later executes — a caller-owned accessor validated as `0.2` must not mutate to `-1` after this render
+    // and change what the gesture forwards. A malformed SHAPE stays raw so validateTransitionRefusal throws
+    // its typed refusal (a capture would launder it).
+    const { transition: rawTransition, ...target } = value as Target & { transition?: Transition }
+    let transition = captureEmbeddedTransition(rawTransition)
+    // The embedded transition is runtime-validated like any other member (r4 major 21,
+    // G-INV-8): `transition: null` must never ride a nullish fallback into "absent".
+    // Production drops the malformed member with a named report; the target survives.
+    // Beyond core's vocabulary/range law, the NATIVE property lane executes only its own
+    // option set (r5 major d6c3850af147): `delay` is rebased by the property driver and
+    // `velocity` seeds the spring since T21 — the surviving refusal exemplar is a tree-lane
+    // orchestration key, which this lane never reads and must never ride as a silent no-op.
+    // RETURN-shaped, no catch (M3 r8 major b9eb82c0d429): only a returned/constructed
+    // refusal is refused; a dependency fault thrown through core validation propagates
+    // with its exact identity.
+    const transitionRefusal = validateTransitionRefusal(transition, {
+      componentId,
+    })
+    if (transitionRefusal !== null) {
+      refuse(transitionRefusal)
+      transition = undefined
+    } else if (transition !== undefined) {
+      const nativeTransitionRefusal = nativePropertyTransitionRefusal(
+        componentId,
+        key + '.transition',
+        transition,
+        Object.keys(target),
+      )
+      if (nativeTransitionRefusal !== null) {
+        refuse(nativeTransitionRefusal)
+        transition = undefined
+      }
+    }
+    // PER-KEY validation (r3 major 16) mirroring the shared severity law's granularity: core
+    // validateTarget AND the native drivability law per member — development throws on the
+    // first offender, production reports it and KEEPS the valid members. The drivability check
+    // exists because a unit string (x: '10px') is core-valid but this rung's native lanes
+    // drive numbers (rgba keys ride the color lane) — accepting it would mount a dead value.
+    const acceptedTarget: Record<string, unknown> = {}
+    for (const [memberKey, rawMember] of Object.entries(target)) {
+      // Per-KEY refusal (r4 major 20; the bound XOR strips HERE, r3 major 17): the conflict
+      // drops this member only — valid siblings survive, the severity law's granularity.
+      const conflict = memberConflict(key, memberKey)
+      if (conflict !== null) {
+        refuse(conflict)
+        continue
+      }
+      // Materialize a keyframe ARRAY member into a frozen snapshot ONCE, before validation (review
+      // major 40, the r3-major-16 one-read law): an accessor-backed array could return a valid member
+      // to the validator and a different value (null) when the controller later reads it. The single
+      // frozen snapshot is the ONE truth validated AND forwarded — a scalar is already immutable.
+      let memberValue: unknown = rawMember
+      if (Array.isArray(rawMember)) {
+        const capture = captureBoundedArray(rawMember)
+        if (capture.kind !== 'captured') {
+          refuse(
+            new InvalidTargetError(
+              componentId,
+              memberKey,
+              capturedArrayDescription(capture),
+              'keyframe arrays must have a safe bounded length (REQ-API-033)',
+            ),
+          )
+          continue
+        }
+        memberValue = capture.values
+      }
+      const memberRefusal = validateTargetRefusal(
+        { [memberKey]: memberValue } as Target,
+        NATIVE_HOST,
+        {
+          componentId,
+        },
+      )
+      if (memberRefusal !== null) {
+        refuse(memberRefusal)
+        continue
+      }
+      const valueKind = nativeMountTargetValueKind(memberKey)
+      // Both lanes drive a scalar OR a keyframe ARRAY (REQ-API-033 on the gesture-state surface, majors
+      // 31 + 35): core validation already proved a well-formed same-value-type array, and the
+      // value-agnostic resolver + array-aware controller drive it — the color lane through the progress
+      // projection (projectColorSequence). Length strings ride the ONE key-aware executable matrix
+      // element-wise (review 91d41675d511): positional keys, auto for width/height only.
+      const lengthRefusal =
+        valueKind === 'color' ? null : executableLengthValueRefusal(memberKey, memberValue)
+      const drivable =
+        valueKind === 'color'
+          ? typeof memberValue === 'string' || Array.isArray(memberValue)
+          : isNativeExecutableLengthValue(memberKey, memberValue)
+      if (!drivable) {
+        refuse(
+          new Error(
+            `${componentId}: R6 scope: ${key}.${memberKey} received ${describeValue(memberValue)} — ${
+              lengthRefusal ??
+              `the native ${valueKind} lane drives ${
+                valueKind === 'color'
+                  ? 'color strings or a color keyframe array'
+                  : 'numbers, numeric keyframe arrays, or measure-resolved positional lengths'
+              }; the supplied value is not executable (REQ-API-031).`
+            }`,
+          ),
+        )
+        continue
+      }
+      // R8-F1 at the SUPPLYING boundary (review major 42): a keyframe array member under an EMBEDDED
+      // spring interpolates exactly two keyframes — a longer array is refused EAGERLY here (production
+      // reports + drops the member, siblings survive) instead of an uncaught controller throw on
+      // activation. An array with NO embedded spring rides the element-transition fallback, refused by
+      // the controller's own severity-aware compat filter.
+      const effectiveTransition =
+        transition !== undefined
+          ? resolveTransitionForKey(transition, memberKey)
+          : context.elementTransition === undefined
+            ? undefined
+            : resolveTransitionForKey(context.elementTransition, memberKey)
+      // A supplied embedded transition owns this member even when it is later refused. Only a member
+      // authored without one attempts the element fallback.
+      // A malformed embedded transition is refused before this member is evaluated. If the
+      // surviving target then reaches the element fallback, it is a real fallback attempt just
+      // like an omitted embedded transition; raw authorship is not execution ownership.
+      if (transition === undefined && context.elementTransition !== undefined) {
+        fallbackAttempted = true
+      }
+      // R8 M2-B (REQ-API-033 law d): validate this layer's EMBEDDED keyframe timing. Shape-valid
+      // count mismatches use the pin's offsets/easing fallback; keyframe-only timing on a scalar
+      // remains inert and refuses. Report + drop per member under severity; siblings survive.
+      const timingRefusal = keyframeTransitionRefusal(
+        componentId,
+        memberKey,
+        memberValue,
+        effectiveTransition,
+      )
+      if (timingRefusal !== null) {
+        refuse(timingRefusal)
+        continue
+      }
+      acceptedTarget[memberKey] = memberValue
+    }
+    accepted[key] = { target: acceptedTarget as Target, transition }
+  }
+  return { state: accepted, fallbackAttempted }
+}