@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/variantChildRegistry.ts

@@ -0,0 +1,67 @@
+// T21 (REQ-API-053) — the per-node DIRECT variant-child registry: the native authority for the
+// orchestration (index, total) pair. Order is MOUNT REGISTRATION order (packet L3): sibling
+// mount effects run in tree order, so first render matches JSX order; a later React reorder of
+// existing keys does NOT re-register, so the index keeps first-mount order — a RECORDED
+// divergence from the pin's document-position re-sort (live reorder stagger is a declared
+// deferred sibling, SPEC-COMPONENT REQ-API-053). Unmounts compact the order; later mounts
+// append. React-free on purpose: the registry is pure bookkeeping the variant tree wires up
+// (one per variant node), unit-floored without a host.
+
+export interface VariantChildPosition {
+  /** Position among the parent's LIVE direct variant children, 0-based. */
+  readonly index: number
+  readonly total: number
+}
+
+export interface VariantChildRegistration {
+  /**
+   * The child's CURRENT (index, total) as one atomic read — never two getters a concurrent
+   * unregister could skew between. Start-time only (lifecycle edge).
+   */
+  position(): VariantChildPosition
+  /** Leave the registry, compacting later siblings' indices. Idempotence is a caller bug: a
+   * second call throws (a -1 without its +1 is bookkeeping broken, the ledger law's shape). */
+  unregister(): void
+}
+
+export interface VariantChildRegistry {
+  /** Join in mount order; the returned registration is this child's only handle. */
+  register(): VariantChildRegistration
+  /** Live member count (= every position().total). */
+  size(): number
+}
+
+export function createVariantChildRegistry(): VariantChildRegistry {
+  // Each member is its registration's identity token; order IS the array order.
+  const members: object[] = []
+  return {
+    register() {
+      const token = {}
+      members.push(token)
+      let live = true
+      return {
+        position() {
+          if (!live) {
+            throw new Error(
+              'variantChildRegistry: position() on an unregistered child — a stale handle ' +
+                'must never seed an orchestration delay (internal invariant, REQ-API-053)',
+            )
+          }
+          // alloc-ok: lifecycle-edge — read once per child start, never per frame.
+          return { index: members.indexOf(token), total: members.length }
+        },
+        unregister() {
+          if (!live) {
+            throw new Error(
+              'variantChildRegistry: double unregister — every unregister must pair with ' +
+                'exactly one register (internal invariant, REQ-API-053)',
+            )
+          }
+          live = false
+          members.splice(members.indexOf(token), 1)
+        },
+      }
+    },
+    size: () => members.length,
+  }
+}

package/src/native/motion/variantContext.tsx

@@ -0,0 +1,172 @@
+// R7 (REQ-API-032 law e) — the controlling-node variant tree. An element is CONTROLLING
+// when any variant prop carries a label; it OWNS a tree store and provides it to its
+// subtree. A non-controlling variant node (dictionary carrier) joins its closest
+// controlling ancestor's tree UNCONDITIONALLY (the pinned registration consults no prop)
+// and re-resolves the ancestor's active labels against its OWN dictionary on the
+// ancestor's activation edges. `inherit={false}` is the pinned VISUAL-STATE switch only:
+// it gates inherited initial/variant-state resolution AT MOUNT — never tree membership
+// (severing is the recorded FAIL shape). NO orchestration timing crosses this context.
+//
+// Mechanics: the snapshot is REF-CURRENT during the owner's render (children rendering in
+// the same pass read it synchronously for first paint), while notification is edge-driven
+// — gesture activation flips and post-commit definition changes publish to subscribers,
+// which re-render (memo-proof) and mirror gesture edges through their own resolvers.
+
+import { createContext } from 'react'
+import type { OrchestrationEpisode, VariantLabels } from '@unrulysystems/native-motion-core'
+import type { VariantChildRegistration } from './variantChildRegistry'
+
+/** One gesture lane's propagated state: the labels and whether the lane is ACTIVE. */
+export interface VariantTreeGestureLane {
+  readonly labels: readonly string[]
+  readonly active: boolean
+}
+
+export interface VariantTreeSnapshot {
+  /**
+   * The controlling node's initial definition when propagatable: a label form, or the
+   * `false` suppression sentinel (REQ-API-010 — suppression propagates). An object-form
+   * initial is not a label and does not propagate.
+   */
+  readonly initial: VariantLabels | false | undefined
+  /** The authored animation-time label definition (label form only; shape is preserved because
+   * Motion distinguishes `"a"` from `["a"]` when detecting a variant edge). The exit episode
+   * rides this lane too — the retained clone's animate IS the authored exit definition. */
+  readonly animate: VariantLabels | undefined
+  readonly whileTap: VariantTreeGestureLane | undefined
+  readonly whileDrag: VariantTreeGestureLane | undefined
+}
+
+export interface VariantTreeStore {
+  getSnapshot(): VariantTreeSnapshot
+  /** Subscribe to activation edges; returns the unsubscriber. */
+  subscribe(listener: () => void): () => void
+  /** Silent snapshot swap — the owner's RENDER path (same-pass children read fresh). */
+  set(next: VariantTreeSnapshot): void
+  /** Snapshot swap + notify — the owner's EDGE path (gesture flips, post-commit changes). */
+  publish(next: VariantTreeSnapshot): void
+  /**
+   * R7 laws (d)/(e): the subtree settle ledger — joined descendants report their in-flight
+   * inherited-lane animations (+1 on first command, -1 on their element settle) so an
+   * exiting controlling owner can hold Presence removal until the WHOLE subtree settles
+   * (a time-simulated retention can see neither descendant dictionaries nor their
+   * embedded per-label transitions).
+   */
+  descendantPending(): number
+  reportDescendantPending(delta: 1 | -1): void
+  /** Notified on every pending change; the exit watcher re-checks completion. */
+  subscribeDescendantSettle(listener: () => void): () => void
+}
+
+export const EMPTY_VARIANT_TREE_SNAPSHOT: VariantTreeSnapshot = {
+  initial: undefined,
+  animate: undefined,
+  whileTap: undefined,
+  whileDrag: undefined,
+}
+
+export function createVariantTreeStore(
+  initial: VariantTreeSnapshot = EMPTY_VARIANT_TREE_SNAPSHOT,
+): VariantTreeStore {
+  let snapshot = initial
+  const listeners = new Set<() => void>()
+  let pending = 0
+  const settleListeners = new Set<() => void>()
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    set(next) {
+      snapshot = next
+    },
+    publish(next) {
+      snapshot = next
+      // Live-set iteration is delete-safe: an unsubscribe during notification skips cleanly.
+      for (const listener of listeners) listener()
+    },
+    descendantPending: () => pending,
+    reportDescendantPending(delta) {
+      pending += delta
+      if (pending < 0) {
+        // A settle without a matching in-flight report is the reporter's bookkeeping broken
+        // — degrading to zero would silently release an exit early; fail loud instead.
+        throw new Error(
+          'variantTreeStore: descendant settle ledger went negative — every -1 must pair ' +
+            'with a prior +1 (internal invariant, R7 law d).',
+        )
+      }
+      for (const listener of settleListeners) listener()
+    },
+    subscribeDescendantSettle(listener) {
+      settleListeners.add(listener)
+      return () => {
+        settleListeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** The closest controlling ancestor's tree; null outside any controlling subtree. */
+export const VariantTreeContext = createContext<VariantTreeStore | null>(null)
+
+/**
+ * T21 (REQ-API-053) — the per-NODE orchestration channel. Every variant node (controlling or
+ * joined) provides one for its DIRECT variant children — the pin's `variantChildren` is
+ * per-parent, so recursion is per level, not per tree. Children register in mount order (the
+ * L3 index authority) and pull the parent's CURRENT episode at their own label application;
+ * the channel reads render-fresh refs, so a child rendering after its parent in the same
+ * commit always sees that commit's episode.
+ */
+export interface VariantOrchestrationParent {
+  /** Join the parent's DIRECT-child registry (mount order); unregister on unmount. */
+  registerChild(): VariantChildRegistration
+  /**
+   * The parent's episode for `label` on the CURRENT edge, or null when trivial (no
+   * orchestration options and no cascaded delay) — a null episode means the child starts
+   * undelayed, byte-identical to the pre-T21 command stream.
+   */
+  getEpisode(label: string): OrchestrationEpisode | null
+  /**
+   * 4c mount flush: a child whose MOUNT entrance is orchestrated defers it here instead of
+   * commanding in-render — sibling (index, total) is complete only once the whole mount
+   * wave's registration effects ran. The parent drains the queue top-down (its own effect,
+   * or its own deferred-entrance thunk when it too is orchestrated — the cascade must be
+   * set before children compute). After the first drain the latch is OPEN and later
+   * enqueues run synchronously (a late-mounting child computes against the live registry —
+   * the pin's `manuallyAnimateOnMount` sibling, packet law 9).
+   */
+  queueMountEntrance(run: () => void): void
+  /** Drain + open the latch. Idempotent; every drain preserves enqueue order. */
+  flushMountEntrances(): void
+  /**
+   * 4c `when: "beforeChildren"` (pin law 2): run `run` once the parent's OWN values for the
+   * current wave settle — immediately when no own start is pending. A superseding wave at
+   * the parent DROPS parked runs (children re-park from their own re-renders in the same
+   * commit). The release edge is the parent's element-batch settle; per-label settle
+   * granularity does not exist below it, so multi-label waves conflate (packet note).
+   */
+  parkForOwnSettle(run: () => void): void
+  /**
+   * 4c `when: "afterChildren"` (pin law 2 — any truthy non-beforeChildren string): a child
+   * that COMMANDS under a sequenced-after episode reports its start and receives the
+   * parent's current wave token; it reports settle with that token from its own settle
+   * edge. The parent's own start parks until the wave's pending count drains; a superseded
+   * wave invalidates old tokens (their late settles no-op).
+   */
+  reportChildEpisodeStart(): number
+  reportChildEpisodeSettle(waveToken: number): void
+  /**
+   * The parent's CURRENT wave token. A child holding a token from a superseded wave
+   * (retargeted before its old settle) compares against this to re-report its start into
+   * the new wave's accounting (review r1 major 4) — a stale stored token must not read
+   * as "already counted".
+   */
+  currentWaveToken(): number
+}
+
+/** The closest variant PARENT's orchestration channel; null outside any variant tree. */
+export const VariantOrchestrationContext = createContext<VariantOrchestrationParent | null>(null)