@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/gestureStateResolver.ts

@@ -0,0 +1,286 @@
+// The gesture-state priority resolver (R6, REQ-API-031) as pure, host-agnostic logic. The
+// pinned law (motion-dom variantPriorityOrder + animation-state removed-key handling): a
+// layer's activation OVERLAYS the keys it names unless a higher ACTIVE layer holds them; its
+// deactivation REVERTS each named key to the next-lower ACTIVE layer's definition — animated
+// with the DESTINATION layer's transition (R6-F1), else the element transition — falling to
+// the caller's base resolution (REQ-API-011) when no layer defines the key. Unnamed keys
+// never move (the partial-overlay law, REQ-API-002/012). MotionView wires recognizer
+// lifecycles to setActive and applies the returned retargets through the existing update lane.
+
+import {
+  ORCHESTRATION_OPTION_KEYS,
+  type Target,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+
+const ORCHESTRATION_KEY_SET: ReadonlySet<string> = new Set(ORCHESTRATION_OPTION_KEYS)
+
+/**
+ * The driver-lane strip (T21, REQ-API-053): the tree-lane orchestration options execute at the
+ * variant-tree altitude (MotionView's orchestration channel) — a driver-facing consumer of the
+ * same bag takes the remainder. A bag without the keys flows by IDENTITY.
+ */
+export function stripOrchestrationOptions(
+  transition: Transition | undefined,
+): Transition | undefined {
+  if (transition === undefined) return undefined
+  const keys = Reflect.ownKeys(transition)
+  if (!keys.some((key) => typeof key === 'string' && ORCHESTRATION_KEY_SET.has(key))) {
+    return transition
+  }
+  const stripped: Record<PropertyKey, unknown> = {}
+  for (const key of keys) {
+    if (typeof key !== 'string' || ORCHESTRATION_KEY_SET.has(key)) continue
+    stripped[key] = (transition as Record<string, unknown>)[key]
+  }
+  return stripped as Transition
+}
+
+/** The shipped subset of the pinned variantPriorityOrder, LOW to HIGH. */
+export const GESTURE_STATE_PRIORITY = ['animate', 'whileTap', 'whileDrag'] as const
+export type GestureStateLayerName = (typeof GESTURE_STATE_PRIORITY)[number]
+
+export interface GestureStateLayer {
+  readonly target: Target
+  /** Runtime-only functional definition, materialized exactly once on the activation edge. */
+  readonly resolveAtActivation?: (() => GestureStateLayer) | undefined
+  /** The layer's own transition; absent → the element transition applies (R6-F1). */
+  readonly transition?: Transition | undefined
+  /**
+   * R7 (REQ-API-032 law b): per-key attribution from a label-form definition — the
+   * transition of the label application that last named the key. Consulted FIRST; an
+   * unattributed key falls back down the R6-F1 chain (layer transition, else element).
+   */
+  readonly transitions?: Readonly<Record<string, Transition>> | undefined
+}
+
+export interface GestureStateRetarget {
+  readonly key: string
+  readonly value: unknown
+  readonly transition: Transition | undefined
+}
+
+export interface GestureStateResolver {
+  /**
+   * Flip a layer's active state; returns the retargets the flip produces, in the layer
+   * target's key order. Idempotent: a no-op flip returns nothing.
+   */
+  setActive(layer: GestureStateLayerName, active: boolean): GestureStateRetarget[]
+  /**
+   * Keys currently OWNED by an active non-animate layer — a render-lane animate update must
+   * exclude them or it would clobber the live gesture state (motion's protectedKeys law).
+   */
+  heldKeys(): ReadonlySet<string>
+  /**
+   * Reconcile every ACTIVE layer against its LIVE definition (r5 major 2f0ea1c7d3b4): a
+   * changed value retargets, a removed key reverts to its lower destination, and a vanished
+   * layer deactivates fully (revert everything it applied, clear the active bit — never a
+   * latch). Idempotent: an unchanged layer contributes nothing. The caller runs this once
+   * per render, after refreshing the live layers.
+   */
+  reconcile(): GestureStateRetarget[]
+  /**
+   * Re-emit every key an active non-animate layer currently OWNS, with the live definition's
+   * value and destination transition (review 2d7c3be235a4). The caller runs this on a MEASURE
+   * epoch (parent/viewport context change, or a landed intrinsic auto measure): reconcile()
+   * compares RAW values, so a context-only change to a measure-resolved target ('50%', 'auto',
+   * calc) emits nothing on its own. Numeric re-issues diff to no-ops in the update lane.
+   */
+  reissueActiveTargets(): GestureStateRetarget[]
+}
+
+export function createGestureStateResolver(options: {
+  /**
+   * LIVE layer access (r4 major 19): read at every flip/query, never snapshotted — an animate
+   * rerender or a changed gesture target is in force the moment the caller's accessor reflects
+   * it (motion's animation-state reads current props the same way).
+   */
+  readonly layers: () => Partial<Record<GestureStateLayerName, GestureStateLayer>>
+  /** REQ-API-011: the style-base value a key reverts to when no active layer defines it. */
+  readonly baseValueFor: (key: string) => unknown
+  readonly elementTransition?: (() => Transition | undefined) | undefined
+}): GestureStateResolver {
+  const { layers: readLayers, baseValueFor } = options
+  const elementTransition = (): Transition | undefined => options.elementTransition?.()
+  const active = new Set<GestureStateLayerName>(['animate']) // animate is always active
+  // What each ACTIVE layer overlaid (its definition snapshot at activation, kept current by
+  // reconcile): deactivation and reconcile revert from THIS, never from the live definition —
+  // a definition that changed or vanished while active must still revert what it applied.
+  const applied = new Map<GestureStateLayerName, Record<string, unknown>>()
+  const activatedDefinitions = new Map<GestureStateLayerName, GestureStateLayer>()
+
+  const layerIndex = (layer: GestureStateLayerName): number => GESTURE_STATE_PRIORITY.indexOf(layer)
+
+  const layerFor = (
+    name: GestureStateLayerName,
+    live: Partial<Record<GestureStateLayerName, GestureStateLayer>> = readLayers(),
+  ): GestureStateLayer | undefined => activatedDefinitions.get(name) ?? live[name]
+
+  /**
+   * The R6-F1 chain with R7's per-key attribution first (law b). The winning bag is stripped
+   * of tree-lane orchestration options at this single choke point (T21, review r2 major 1):
+   * an ANIMATE-layer attribution may legally carry a variant ROOT bag with the keys (the
+   * tree lane executes them at label application), but every retarget this resolver emits
+   * feeds a property-lane command — a driver-facing read takes the remainder.
+   */
+  const transitionFor = (layer: GestureStateLayer, key: string): Transition | undefined =>
+    stripOrchestrationOptions(layer.transitions?.[key] ?? layer.transition ?? elementTransition())
+
+  /** The highest ACTIVE layer defining `key`, or null. */
+  const owningLayer = (key: string): GestureStateLayerName | null => {
+    const layers = readLayers()
+    for (let i = GESTURE_STATE_PRIORITY.length - 1; i >= 0; i--) {
+      const name = GESTURE_STATE_PRIORITY[i]!
+      if (!active.has(name)) continue
+      const layer = layerFor(name, layers)
+      if (layer !== undefined && key in layer.target) return name
+    }
+    return null
+  }
+
+  const destinationFor = (key: string): GestureStateRetarget | null => {
+    const owner = owningLayer(key)
+    if (owner !== null) {
+      const layer = layerFor(owner)!
+      return {
+        key,
+        value: (layer.target as Record<string, unknown>)[key],
+        transition: transitionFor(layer, key),
+      }
+    }
+    const base = baseValueFor(key)
+    // No layer and no base: the resolver never invents a destination — the caller's mount
+    // law owns that case (REQ-API-011 resolved the first paint; an unmoved key stays put).
+    if (base === undefined) return null
+    return { key, value: base, transition: elementTransition() }
+  }
+
+  /**
+   * The applied snapshot of an ACTIVE layer. Activation always records one (setActive's
+   * activate path), so absence is the resolver's own bookkeeping broken — degrading to an
+   * empty target would silently turn a release into a no-op and leave values stuck
+   * (r6 minor 3d497c80a16b); fail loud instead.
+   */
+  const appliedFor = (layer: GestureStateLayerName): Record<string, unknown> => {
+    const snapshot = applied.get(layer)
+    if (snapshot === undefined) {
+      throw new Error(
+        `gestureStateResolver: active layer '${layer}' has no applied snapshot — ` +
+          'activation must record one (internal invariant, r6 minor 3d497c80a16b).',
+      )
+    }
+    return snapshot
+  }
+
+  /** Revert `keys` after `layer` released them: each key goes to its fresh destination. */
+  const revertKeys = (
+    layer: GestureStateLayerName,
+    keys: readonly string[],
+  ): GestureStateRetarget[] => {
+    const retargets: GestureStateRetarget[] = []
+    for (const key of keys) {
+      // A HIGHER active holder keeps the key — the release changes nothing for it.
+      const newOwner = owningLayer(key)
+      if (newOwner !== null && layerIndex(newOwner) > layerIndex(layer)) continue
+      const destination = destinationFor(key)
+      if (destination !== null) retargets.push(destination)
+    }
+    return retargets
+  }
+
+  return {
+    reconcile() {
+      const layers = readLayers()
+      const retargets: GestureStateRetarget[] = []
+      for (const name of GESTURE_STATE_PRIORITY) {
+        if (name === 'animate' || !active.has(name)) continue
+        const authoredDefinition = layers[name]
+        const appliedTarget = appliedFor(name)
+        if (authoredDefinition === undefined) {
+          // The layer left the tree while active: full deactivation, bit cleared (no latch).
+          active.delete(name)
+          applied.delete(name)
+          activatedDefinitions.delete(name)
+          retargets.push(...revertKeys(name, Object.keys(appliedTarget)))
+          continue
+        }
+        const definition = layerFor(name, layers)!
+        const current = definition.target as Record<string, unknown>
+        const removed = Object.keys(appliedTarget).filter((key) => !(key in current))
+        retargets.push(...revertKeys(name, removed))
+        for (const [key, value] of Object.entries(current)) {
+          if (key in appliedTarget && appliedTarget[key] === value) continue
+          // Added or changed: retarget only if THIS layer owns the key right now.
+          if (owningLayer(key) !== name) continue
+          retargets.push({ key, value, transition: transitionFor(definition, key) })
+        }
+        applied.set(name, { ...current })
+      }
+      return retargets
+    },
+    heldKeys() {
+      const layers = readLayers()
+      const held = new Set<string>()
+      for (const name of GESTURE_STATE_PRIORITY) {
+        if (name === 'animate' || !active.has(name)) continue
+        const layer = layerFor(name, layers)
+        if (layer === undefined) continue
+        for (const key of Object.keys(layer.target)) {
+          if (owningLayer(key) === name) held.add(key)
+        }
+      }
+      return held
+    },
+    reissueActiveTargets() {
+      const layers = readLayers()
+      const retargets: GestureStateRetarget[] = []
+      for (const name of GESTURE_STATE_PRIORITY) {
+        if (name === 'animate' || !active.has(name)) continue
+        const layer = layerFor(name, layers)
+        if (layer === undefined) continue
+        for (const key of Object.keys(layer.target)) {
+          // Only the OWNING layer re-issues its key — a higher active holder's value wins.
+          if (owningLayer(key) !== name) continue
+          retargets.push({
+            key,
+            value: (layer.target as Record<string, unknown>)[key],
+            transition: transitionFor(layer, key),
+          })
+        }
+      }
+      return retargets
+    },
+    setActive(layer, isActive) {
+      if (layer === 'animate') return [] // the base layer never flips
+      if (active.has(layer) === isActive) return [] // idempotent
+      if (isActive) {
+        const authoredDefinition = readLayers()[layer]
+        if (authoredDefinition === undefined) return [] // nothing to overlay; stays inactive
+        const definition = authoredDefinition.resolveAtActivation?.() ?? authoredDefinition
+        if (authoredDefinition.resolveAtActivation !== undefined) {
+          activatedDefinitions.set(layer, definition)
+        }
+        active.add(layer)
+        applied.set(layer, { ...(definition.target as Record<string, unknown>) })
+        const retargets: GestureStateRetarget[] = []
+        for (const key of Object.keys(definition.target)) {
+          // A HIGHER active layer holds the key: the flip changes nothing for it.
+          if (owningLayer(key) !== layer) continue
+          retargets.push({
+            key,
+            value: (definition.target as Record<string, unknown>)[key],
+            transition: transitionFor(definition, key),
+          })
+        }
+        return retargets
+      }
+      // Deactivation reverts what was APPLIED (r5 major 2f0ea1c7d3b4) — the live definition
+      // may have shrunk or vanished since activation; the applied snapshot is the truth.
+      const appliedTarget = appliedFor(layer)
+      active.delete(layer)
+      applied.delete(layer)
+      activatedDefinitions.delete(layer)
+      return revertKeys(layer, Object.keys(appliedTarget))
+    },
+  }
+}