@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/identityValueChannelControllerReconciliation.ts

@@ -0,0 +1,176 @@
+import type { BoundStyleValue } from './styleValueBinding'
+
+export const IDENTITY_VALUE_CHANNEL_CONTROLLER_RECONCILIATION_INVARIANT =
+  'NATIVE_MOTION_IDENTITY_VALUE_CHANNEL_CONTROLLER_RECONCILIATION_INVARIANT' as const
+
+export class IdentityValueChannelControllerReconciliationInvariantError extends Error {
+  readonly code = IDENTITY_VALUE_CHANNEL_CONTROLLER_RECONCILIATION_INVARIANT
+  readonly reason = 'replacement-snapshot-missing' as const
+  readonly key: string
+
+  constructor(key: string) {
+    super(
+      `native-motion: identity value-channel replacement '${key}' has no captured scalar snapshot`,
+    )
+    this.name = 'IdentityValueChannelControllerReconciliationInvariantError'
+    this.key = key
+  }
+}
+
+export interface IdentityValueChannelControllerDetachBoundValueEdge {
+  readonly kind: 'DETACH_BOUND_VALUE'
+  readonly key: string
+  readonly value: BoundStyleValue
+  readonly identityEligible: boolean
+}
+
+export interface IdentityValueChannelControllerAttachBoundValueEdge {
+  readonly kind: 'ATTACH_BOUND_VALUE'
+  readonly key: string
+  readonly value: BoundStyleValue
+  readonly resolvedValue: number | string
+  readonly identityEligible: boolean
+}
+
+export type IdentityValueChannelControllerElementReconciliationChange =
+  | {
+      readonly kind: 'REPLACE_BOUND_VALUE'
+      readonly key: string
+      readonly previousValue: BoundStyleValue
+      readonly replacementValue: BoundStyleValue
+      readonly replacementResolvedValue: number | string
+      readonly previousIdentityEligible: boolean
+      readonly replacementIdentityEligible: boolean
+      readonly orderedEdges: readonly [
+        IdentityValueChannelControllerDetachBoundValueEdge,
+        IdentityValueChannelControllerAttachBoundValueEdge,
+      ]
+    }
+  | {
+      readonly kind: 'REMOVE_BOUND_VALUE'
+      readonly key: string
+      readonly previousValue: BoundStyleValue
+      readonly previousIdentityEligible: true
+      readonly orderedEdges: readonly [IdentityValueChannelControllerDetachBoundValueEdge]
+    }
+  | {
+      readonly kind: 'ATTACH_BOUND_VALUE'
+      readonly key: string
+      readonly replacementValue: BoundStyleValue
+      readonly replacementResolvedValue: number | string
+      readonly replacementIdentityEligible: true
+      readonly orderedEdges: readonly [IdentityValueChannelControllerAttachBoundValueEdge]
+    }
+
+export interface IdentityValueChannelControllerElementReconciliationPlan {
+  readonly changes: readonly IdentityValueChannelControllerElementReconciliationChange[]
+}
+
+export interface PlanIdentityValueChannelControllerElementReconciliationOptions {
+  readonly previousBoundStyleValues: Readonly<Record<string, BoundStyleValue>>
+  readonly previousIdentityEligibleBoundKeys: readonly string[]
+  readonly nextBoundStyleValues: Readonly<Record<string, BoundStyleValue>>
+  readonly nextIdentityEligibleBoundKeys: readonly string[]
+  /** One-read snapshots for new or replaced values only; unchanged identities are deliberately absent. */
+  readonly resolvedReplacementStyleValues: Readonly<Record<string, number | string>>
+}
+
+function capturedReplacementValue(
+  key: string,
+  resolvedReplacementStyleValues: Readonly<Record<string, number | string>>,
+): number | string {
+  if (!Object.prototype.hasOwnProperty.call(resolvedReplacementStyleValues, key)) {
+    throw new IdentityValueChannelControllerReconciliationInvariantError(key)
+  }
+  return resolvedReplacementStyleValues[key]!
+}
+
+/**
+ * Produces the exact-reference commit plan consumed by the controller adapter. Previous authored
+ * key order owns replacements/removals; genuinely new eligible keys follow next-style order.
+ */
+export function planIdentityValueChannelControllerElementReconciliation(
+  options: PlanIdentityValueChannelControllerElementReconciliationOptions,
+): IdentityValueChannelControllerElementReconciliationPlan {
+  const changes: IdentityValueChannelControllerElementReconciliationChange[] = []
+  const previousKeys = Object.keys(options.previousBoundStyleValues)
+  const nextKeys = Object.keys(options.nextBoundStyleValues)
+  const orderedKeys = [
+    ...previousKeys,
+    ...nextKeys.filter(
+      (key) => !Object.prototype.hasOwnProperty.call(options.previousBoundStyleValues, key),
+    ),
+  ]
+
+  for (const key of orderedKeys) {
+    const previousValue = options.previousBoundStyleValues[key]
+    const replacementValue = options.nextBoundStyleValues[key]
+    if (previousValue === replacementValue) continue
+
+    const previousIdentityEligible = options.previousIdentityEligibleBoundKeys.includes(key)
+    const replacementIdentityEligible = options.nextIdentityEligibleBoundKeys.includes(key)
+    if (!previousIdentityEligible && !replacementIdentityEligible) continue
+
+    if (previousValue !== undefined && replacementValue === undefined) {
+      if (!previousIdentityEligible) continue
+      const detach = {
+        kind: 'DETACH_BOUND_VALUE',
+        key,
+        value: previousValue,
+        identityEligible: true,
+      } as const
+      changes.push({
+        kind: 'REMOVE_BOUND_VALUE',
+        key,
+        previousValue,
+        previousIdentityEligible: true,
+        orderedEdges: [detach],
+      })
+      continue
+    }
+
+    if (replacementValue === undefined) continue
+    const replacementResolvedValue = capturedReplacementValue(
+      key,
+      options.resolvedReplacementStyleValues,
+    )
+    const attach = {
+      kind: 'ATTACH_BOUND_VALUE',
+      key,
+      value: replacementValue,
+      resolvedValue: replacementResolvedValue,
+      identityEligible: replacementIdentityEligible,
+    } as const
+    if (previousValue === undefined) {
+      if (!replacementIdentityEligible) continue
+      changes.push({
+        kind: 'ATTACH_BOUND_VALUE',
+        key,
+        replacementValue,
+        replacementResolvedValue,
+        replacementIdentityEligible: true,
+        orderedEdges: [attach],
+      })
+      continue
+    }
+
+    const detach = {
+      kind: 'DETACH_BOUND_VALUE',
+      key,
+      value: previousValue,
+      identityEligible: previousIdentityEligible,
+    } as const
+    changes.push({
+      kind: 'REPLACE_BOUND_VALUE',
+      key,
+      previousValue,
+      replacementValue,
+      replacementResolvedValue,
+      previousIdentityEligible,
+      replacementIdentityEligible,
+      orderedEdges: [detach, attach],
+    })
+  }
+
+  return { changes }
+}

package/src/native/motion/identityValueChannelLaneMarker.ts

@@ -0,0 +1,14 @@
+// The identity-channel lane marker shared by the controller and the adapter binding (REQ-API-061).
+// Kept dependency-free on purpose: every consumer of the controller can load it without pulling
+// the adapter's driver graph (several suites resolve no react-native-worklets at all).
+
+/**
+ * Command-level lane marker the controller stamps on declarative animate updates (its
+ * `animateScope`-carrying update lane). A top-level symbol never crosses into the prepared driver
+ * protocol and never serializes, so the delegate and every command trace stay oblivious; the
+ * identity adapter alone reads it to keep the declarative lane on a timed trajectory while a
+ * gesture-state/presence retarget of the same shape takes the host-resolved carrier commit.
+ */
+export const IDENTITY_DECLARATIVE_LANE_COMMAND: unique symbol = Symbol(
+  'native-motion.identity-value-channel.declarative-lane-command',
+)