@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/styleValueBinding.ts

@@ -0,0 +1,657 @@
+// Style-bound public MotionValues (REQ-API-026 / REQ-DRIVER-029): a bound value's DIRECT writes
+// commit through the driver's binding lane — one crossing per set(), the same event-shaped
+// cadence gesture writes ride, never a frame loop. Unlike a gesture write, a direct set settles
+// immediately and cannot manufacture a finger hold. Review r1 major 1 law: a bound
+// value REFUSES animation-driven traffic — a JS-side animation would cross the bridge every
+// frame (the stall the Elsewhere stress toggle exists to expose), so `animationStart` on a
+// bound value fails under the severity law naming the driver-derived-channel successor rung.
+// Two string-binding classes join the numeric one (REQ-API-026): U5's rgba class (COLOR_KEY_NAMES,
+// mappedKeys.ts) binds a MotionValue<string> and publishes through the settled-color pattern —
+// a fresh `[c, c]` endpoint sequence at PROGRESS_END through the controller's onColorEndpoints
+// port (packet F3), the same delivery static authored colors use; U5 W3's `transform` key binds a
+// MotionValue<string> parsed per set() with the pinned transform-function grammar
+// (transformStringBinding.ts) and written through the SAME numeric retarget lane as ONE multi-key
+// map (parsed components at their values, absent components reset to their pin defaults — the
+// pin's imperative `element.style.transform = str` replaces the whole transform,
+// motion-dom build-styles.ts:52-66). A bound color is validated at
+// split AND per set() (core's strict isColor + parseColor validator, REQ-VALUETYPE-008
+// lineage): the pin binds any string verbatim (motion@12.42.2 scrape-motion-values.ts:6-29),
+// native keeps its standing loud policy. A bound transform string is validated the same way —
+// the pinned-grammar parse refuses loud naming the key and the unsupported form. General
+// string/unit binding beyond the rgba class and `transform` stays deferred with the same loud,
+// named failure.
+
+import {
+  describeValue,
+  isColor,
+  parseColor,
+  type ElementHandle,
+  type MotionValue,
+  type RGBA,
+} from '@unrulysystems/native-motion-core'
+import { isDirectPublicNumericMotionValue } from '@unrulysystems/native-motion-core/internal-driver'
+import type { WorkletDriverBinding } from '../driver/workletDriver'
+import {
+  COLOR_KEY_NAMES,
+  NUMERIC_STYLE_KEY_NAMES,
+  TRANSFORM_KEY_NAMES,
+  TRANSFORM_STRING_KEY_NAME,
+} from './mappedKeys'
+import { NATIVE_TRANSFORM_ORDER } from './transformOrder'
+import {
+  isNativeTransformComponentKey,
+  parseTransformStringComponents,
+  transformStringWriteMap,
+} from './transformStringBinding'
+
+// The rgba-class binding set (U5): the literal class array as a membership probe. mappedKeys is
+// data-only (no RN imports), and its registry cross-check test binds the class to the shipped
+// color keys — the same set the controller's isColorKey classifies through the registry.
+const COLOR_BINDABLE_KEYS: ReadonlySet<string> = new Set<string>(COLOR_KEY_NAMES)
+const IDENTITY_CHANNEL_NUMERIC_KEYS: ReadonlySet<string> = new Set<string>([
+  ...TRANSFORM_KEY_NAMES,
+  ...NUMERIC_STYLE_KEY_NAMES,
+])
+
+/** A bound entry's value: numeric on the numeric-natured keys, a color string on the rgba class. */
+export type BoundStyleValue = MotionValue<number> | MotionValue<string>
+
+/**
+ * Shape hint shared by full public MotionValues and partial duck-types. Objects with get +
+ * subscribe but a missing runtime surface must never be treated as ordinary statics (they would
+ * reach the RN host bag) or as full MotionValues (attach would TypeError) — family-5 major
+ * 285dacf76bfe.
+ */
+export function hasMotionValueShapeHints(candidate: unknown): boolean {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof (candidate as { get?: unknown }).get === 'function' &&
+    typeof (candidate as { subscribe?: unknown }).subscribe === 'function'
+  )
+}
+
+/**
+ * Exact public MotionValue duck-type used by every style / transform binding authority.
+ * Requires the full runtime surface the binding attach path immediately invokes (get/set/jump/
+ * subscribe/getVelocity/on/stop/isAnimating/destroy). Partial objects are refused separately.
+ */
+export function isMotionValue(candidate: unknown): candidate is MotionValue<unknown> {
+  if (!hasMotionValueShapeHints(candidate)) return false
+  const value = candidate as MotionValue<unknown>
+  return (
+    typeof value.set === 'function' &&
+    typeof value.jump === 'function' &&
+    typeof value.getVelocity === 'function' &&
+    typeof value.on === 'function' &&
+    typeof value.stop === 'function' &&
+    typeof value.isAnimating === 'function' &&
+    typeof value.destroy === 'function'
+  )
+}
+
+/** Partial duck-type: MotionValue-shaped hints without the full public surface. */
+export function isNearMotionValue(candidate: unknown): boolean {
+  return hasMotionValueShapeHints(candidate) && !isMotionValue(candidate)
+}
+
+export interface StyleValueGate {
+  readonly severity: 'development' | 'production'
+  readonly report: (error: Error) => void
+  /**
+   * Public host identity for errors emitted by the shared style-binding lanes.
+   * Required — a silent Motion.View default would launder Text refusals as View (R9 M2 r15).
+   */
+  readonly componentId: '<Motion.View>' | '<Motion.Text>' | '<Motion.Image>'
+}
+
+const THROW_GATE: StyleValueGate = {
+  severity: 'development',
+  report: () => {},
+  componentId: '<Motion.View>',
+}
+
+const componentPrefix = (gate: StyleValueGate): string => `${gate.componentId}: `
+
+export interface SplitBoundStyle {
+  /** Style entries whose value is a public MotionValue, keyed by style key. */
+  readonly bound: Record<string, BoundStyleValue>
+  /** The one scalar snapshot captured while admitting each bound entry. */
+  readonly resolved: Record<string, number | string>
+  /** The remaining plain entries, untouched (the existing static-style seeding path). */
+  readonly statics: Record<string, unknown>
+}
+
+const motionViewAuthoredStyleMountPreparationBrand: unique symbol = Symbol(
+  'native-motion.motion-view-authored-style-mount-preparation',
+)
+
+/**
+ * Opaque result of the authored-style split MotionView runs during mount. Identity-channel
+ * adapters consume this object instead of accepting a second caller-authored key/value map, so
+ * the value identity registered with the driver is necessarily the one extracted from `style`.
+ */
+export interface MotionViewAuthoredStyleMountPreparation {
+  readonly [motionViewAuthoredStyleMountPreparationBrand]: true
+  readonly boundStyleValues: Record<string, BoundStyleValue>
+  readonly resolvedBoundStyleValues: Record<string, number | string>
+  readonly staticStyleValues: Record<string, unknown>
+}
+
+/**
+ * The exact native identity-channel admission class. The caller supplies the already captured
+ * scalar so this predicate never performs a collector-visible public read.
+ */
+export function isIdentityChannelEligibleBoundStyleValue(
+  key: string,
+  value: MotionValue<unknown>,
+  resolvedCurrentValue: unknown,
+): value is MotionValue<number> {
+  return (
+    IDENTITY_CHANNEL_NUMERIC_KEYS.has(key) &&
+    !value.isAnimating() &&
+    isDirectPublicNumericMotionValue(value, resolvedCurrentValue)
+  )
+}
+
+export interface IdentityChannelEligibleBoundStyleSnapshot {
+  readonly keys: readonly string[]
+  readonly resolvedStyleValues: Readonly<Record<string, number>>
+}
+
+/** Selects exact eligible bindings from the mount snapshot without re-reading any MotionValue. */
+export function identityChannelEligibleBoundStyleSnapshot(
+  preparation: MotionViewAuthoredStyleMountPreparation,
+): IdentityChannelEligibleBoundStyleSnapshot {
+  const keys: string[] = []
+  const resolvedStyleValues: Record<string, number> = {}
+  for (const [key, value] of Object.entries(preparation.boundStyleValues)) {
+    const resolved = preparation.resolvedBoundStyleValues[key]
+    if (!isIdentityChannelEligibleBoundStyleValue(key, value, resolved)) continue
+    if (typeof resolved !== 'number') continue
+    keys.push(key)
+    resolvedStyleValues[key] = resolved
+  }
+  return { keys, resolvedStyleValues }
+}
+
+// The bound-color verdict (U5): a color-bound value must be a string core's strict color
+// validator accepts — anything else refuses loud per the severity law, naming the key (the
+// controller's color lane treats an unparseable color target the same way,
+// motionViewController.ts:1075-1087). The barrel-legal pair does the validation: `isColor` is the
+// TOTAL shape gate (named/hex/rgb/hsl), `parseColor` the strict validator — together they are
+// exactly core's parseColorVerdict, whose verdict form is core-internal by the ratified
+// value-types barrel law (value-types/index.ts). Returns the parsed RGBA, or null after a
+// production report (the write is refused; the host keeps the last good value).
+function boundColorValue(key: string, value: unknown, gate: StyleValueGate): RGBA | null {
+  let parsed: RGBA | null = null
+  let reason: string | null = null
+  if (typeof value === 'string') {
+    if (!isColor(value)) {
+      reason = `Cannot parse ${JSON.stringify(value)} as a color`
+    } else {
+      try {
+        parsed = parseColor(value)
+      } catch (error) {
+        // The shape gate passed, so a throw here is the strict validator's OWN refusal (a plain
+        // Error carrying the refusal message — core's verdict chain never throws anything else).
+        // Anything else is a dependency fault and propagates unmasked (M3 r7/r8's no-catch law).
+        if (error instanceof Error && error.constructor === Error) reason = error.message
+        else throw error
+      }
+    }
+  }
+  if (parsed !== null) return parsed
+  const error = new Error(
+    `${componentPrefix(gate)}style-bound MotionValue on color key '${key}' holds ${describeValue(value)}; ` +
+      'a bound color must be a color string (hex/rgb/hsl/named, REQ-API-026)' +
+      `${reason !== null ? ` — ${reason}` : ''}.`,
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+  return null
+}
+
+// The bound-transform verdict (U5 W3): a transform-bound value must be a string the pinned-grammar
+// parser accepts (transformStringBinding.ts) — anything else refuses loud per the severity law,
+// naming the key and the unsupported form (the pin hands the string to the browser, which
+// silently drops invalid CSS; native keeps its standing loud policy — declared refuse-class
+// debt, REQ-API-026). Returns the FULL 11-component write map (parsed values; absent components
+// reset to their pin defaults — the pin's imperative replace drops them), or null after a
+// production report (the write is refused; the host keeps the last good components).
+function boundTransformWriteMap(
+  value: unknown,
+  gate: StyleValueGate,
+): Record<string, number> | null {
+  let map: Record<string, number> | null = null
+  let reason: string | null = null
+  if (typeof value === 'string') {
+    try {
+      map = transformStringWriteMap(parseTransformStringComponents(value))
+    } catch (error) {
+      // The parser throws only plain Errors carrying the refusal reason; anything else is a
+      // dependency fault and propagates unmasked (M3 r7/r8's no-catch law).
+      if (error instanceof Error && error.constructor === Error) reason = error.message
+      else throw error
+    }
+  }
+  if (map !== null) return map
+  const error = new Error(
+    `${componentPrefix(gate)}style-bound MotionValue on 'transform' holds ${describeValue(value)}; ` +
+      'a bound transform must be a transform-function string in the pinned grammar (the pin ' +
+      'buildTransform emit set plus translate/translate3d, REQ-API-026, U5 W3)' +
+      `${reason !== null ? ` — ${reason}` : ''}.`,
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+  return null
+}
+
+// The near-MotionValue partial duck-type refusal — identical at split and reconcile: never a
+// static host residual, never an attach TypeError.
+function refuseNearMotionValue(key: string, gate: StyleValueGate): void {
+  const error = new Error(
+    `${componentPrefix(gate)}style value on '${key}' is a partial MotionValue duck-type ` +
+      `(missing full public surface set/jump/on/stop/isAnimating/destroy/getVelocity); ` +
+      'refused under the severity law — supply a real MotionValue or a plain static.',
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+}
+
+// Per-entry VALUE validation against the key's binding class (REQ-API-026): numeric-natured keys
+// take a number-holding MotionValue; the rgba class takes a string-holding MotionValue whose
+// current value parses as a color; `transform` takes a string-holding MotionValue whose current
+// value parses with the pinned transform grammar. Development throws; production reports and the
+// entry is refused. Used where a binding is ADMITTED (the mount split, a new/swapped source at
+// reconcile) — never for an already-attached identity, whose per-write lane owns value validity.
+type BoundEntryResolution =
+  | { readonly accepted: true; readonly current: number | string }
+  | { readonly accepted: false }
+
+function resolveBoundEntry(
+  key: string,
+  value: MotionValue<unknown>,
+  gate: StyleValueGate,
+): BoundEntryResolution {
+  const current = value.get()
+  if (key === TRANSFORM_STRING_KEY_NAME) {
+    // U5 W3: `transform` binds a MotionValue<string> in the pinned grammar — a numeric MV or an
+    // out-of-grammar string refuses here (never the unmapped-key gate downstream).
+    return boundTransformWriteMap(current, gate) === null
+      ? { accepted: false }
+      : { accepted: true, current: current as string }
+  }
+  if (COLOR_BINDABLE_KEYS.has(key)) {
+    return boundColorValue(key, current, gate) === null
+      ? { accepted: false }
+      : { accepted: true, current: current as string }
+  }
+  if (typeof current !== 'number') {
+    const error = new Error(
+      `${componentPrefix(gate)}R4 scope: style-bound MotionValue on '${key}' holds ${describeValue(current)}; ` +
+        'numeric keys bind only numeric MotionValues — the rgba class ' +
+        '(backgroundColor/color/borderColor) and `transform` bind MotionValue<string> ' +
+        '(REQ-API-026, U5); ' +
+        'general string/unit binding stays deferred to the value-breadth rung.',
+    )
+    if (gate.severity === 'development') throw error
+    gate.report(error) // production: refuse the binding, mount the rest
+    return { accepted: false }
+  }
+  return { accepted: true, current }
+}
+
+// Splits bound entries out of a flattened style. A bound value outside its key's class fails
+// under the severity law (REQ-API-014 lineage): development throws; production reports and
+// REFUSES the binding (the key falls out entirely — never a garbage host write). The classes
+// (REQ-API-026): numeric-natured keys take a number-holding MotionValue; the rgba class takes a
+// string-holding MotionValue whose current value parses as a color; `transform` takes a
+// string-holding MotionValue whose current value parses with the pinned transform grammar.
+// Near-MotionValue partial
+// duck-types are the same severity refusal — never static host residual, never attach TypeError.
+export function splitBoundStyleValues(
+  flattened: Record<string, unknown>,
+  gate: StyleValueGate = THROW_GATE,
+): SplitBoundStyle {
+  const bound: Record<string, BoundStyleValue> = {}
+  const resolved: Record<string, number | string> = {}
+  const statics: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(flattened)) {
+    if (isNearMotionValue(value)) {
+      refuseNearMotionValue(key, gate)
+      continue
+    }
+    if (!isMotionValue(value)) {
+      statics[key] = value
+      continue
+    }
+    const resolution = resolveBoundEntry(key, value, gate)
+    if (!resolution.accepted) continue
+    bound[key] = value as BoundStyleValue
+    resolved[key] = resolution.current
+  }
+  return { bound, resolved, statics }
+}
+
+/**
+ * The single authored-style entrance used by MotionView mount preparation and the exact-identity
+ * adapter. The wrapper-shaped argument keeps `style`—not a parallel `boundValues` fixture—as the
+ * source of truth while reusing the existing validation and severity law unchanged.
+ */
+export function prepareMotionViewAuthoredStyleForMount(
+  props: { readonly style: Record<string, unknown> },
+  gate: StyleValueGate = THROW_GATE,
+): MotionViewAuthoredStyleMountPreparation {
+  const { bound, resolved, statics } = splitBoundStyleValues(props.style, gate)
+  return {
+    [motionViewAuthoredStyleMountPreparationBrand]: true,
+    boundStyleValues: bound,
+    resolvedBoundStyleValues: resolved,
+    staticStyleValues: statics,
+  }
+}
+
+/**
+ * The RENDER-reconcile counterpart to the mount split (U5 device-proof fix). The reconcile runs
+ * after EVERY commit and answers one question: which (key → MotionValue) bindings does the
+ * current style declare? It reconciles IDENTITIES, not values:
+ *
+ * - An identity-UNCHANGED entry (same source already attached) carries over untouched — even
+ *   while the source holds a value the write lane just refused. Value validity is a per-WRITE
+ *   concern: the write lane reported the refusal at set() time and kept the last good host
+ *   value; re-validating here re-reports the same refusal on every render (a flood) and drops
+ *   the key, detaching the subscription so a later VALID set() never reaches the host. The
+ *   pin's posture: the refused write is dropped, the binding lives, the next valid set()
+ *   applies.
+ * - A NEW or SWAPPED source is value-validated exactly like the mount split before it may bind
+ *   (development throws; production reports once and the key stays unbound).
+ */
+export function reconcileBoundStyleValues(
+  flattened: Record<string, unknown>,
+  attached: Readonly<Record<string, BoundStyleValue>> | null,
+  gate: StyleValueGate = THROW_GATE,
+): Record<string, BoundStyleValue> {
+  return reconcileBoundStyleValuesWithIdentityEligibility(flattened, attached, [], gate)
+    .boundStyleValues
+}
+
+export interface BoundStyleIdentityReconciliation {
+  readonly boundStyleValues: Record<string, BoundStyleValue>
+  readonly identityEligibleBoundKeys: readonly string[]
+  /** One-read snapshots for new or swapped bindings; unchanged identities are intentionally absent. */
+  readonly resolvedReplacementStyleValues: Readonly<Record<string, number | string>>
+}
+
+/**
+ * MotionView's render reconciliation. Existing identities inherit their bind-time verdict; a new
+ * or swapped source is read once for ordinary binding validation and exact identity eligibility.
+ */
+export function reconcileBoundStyleValuesWithIdentityEligibility(
+  flattened: Record<string, unknown>,
+  attached: Readonly<Record<string, BoundStyleValue>> | null,
+  attachedIdentityEligibleBoundKeys: readonly string[],
+  gate: StyleValueGate = THROW_GATE,
+): BoundStyleIdentityReconciliation {
+  const bound: Record<string, BoundStyleValue> = {}
+  const identityEligibleBoundKeys: string[] = []
+  const resolvedReplacementStyleValues: Record<string, number | string> = {}
+  for (const [key, value] of Object.entries(flattened)) {
+    if (isNearMotionValue(value)) {
+      refuseNearMotionValue(key, gate)
+      continue
+    }
+    if (!isMotionValue(value)) continue
+    if (attached?.[key] === value) {
+      bound[key] = value as BoundStyleValue
+      if (attachedIdentityEligibleBoundKeys.includes(key)) identityEligibleBoundKeys.push(key)
+      continue
+    }
+    const resolution = resolveBoundEntry(key, value, gate)
+    if (!resolution.accepted) continue
+    bound[key] = value as BoundStyleValue
+    resolvedReplacementStyleValues[key] = resolution.current
+    if (isIdentityChannelEligibleBoundStyleValue(key, value, resolution.current)) {
+      identityEligibleBoundKeys.push(key)
+    }
+  }
+  return { boundStyleValues: bound, identityEligibleBoundKeys, resolvedReplacementStyleValues }
+}
+
+/**
+ * The UPDATE lane's XOR gate (review r8 major 270052714f55): the one-authority-per-key law
+ * holds through the whole lifecycle, so an animate target arriving on a currently-BOUND key is
+ * rejected exactly like the mount-time crossover (development throws; production reports and
+ * refuses the key while the rest of the update proceeds). U5 W3: a bound `transform` occupies
+ * the WHOLE transform component space (the pin's bound string replaces the component build
+ * entirely, motion-dom build-styles.ts:52-66), so an animate target on ANY transform shorthand
+ * while `transform` is bound is the same dual-authority violation.
+ */
+export function gateUpdateAgainstBindings<T extends Record<string, unknown>>(
+  gatedTarget: T,
+  boundKeys: readonly string[],
+  gate: StyleValueGate = THROW_GATE,
+  identityEligibleBoundKeys: readonly string[] = [],
+): T {
+  const transformBound = boundKeys.includes(TRANSFORM_STRING_KEY_NAME)
+  for (const key of Object.keys(gatedTarget)) {
+    const boundHit = boundKeys.includes(key)
+    const transformHit = transformBound && isNativeTransformComponentKey(key)
+    if (!boundHit && !transformHit) continue
+    if (boundHit && identityEligibleBoundKeys.includes(key)) continue
+    const error = new Error(
+      boundHit
+        ? `${componentPrefix(gate)}R4 scope: '${key}' is style-bound AND received an animate target — a key has ONE ` +
+            'reconciliation authority (REQ-DRIVER-029); drive it through the binding or the ' +
+            'target, never both.'
+        : `${componentPrefix(gate)}R4 scope: '${key}' received an animate target while 'transform' is style-bound — ` +
+            'a bound transform occupies the WHOLE transform component space, so one authority ' +
+            'covers every shorthand (REQ-DRIVER-029); drive it through the binding or the ' +
+            'target, never both.',
+    )
+    if (gate.severity === 'development') throw error
+    gate.report(error)
+    delete gatedTarget[key]
+  }
+  return gatedTarget
+}
+
+/**
+ * Strip EVERY MotionValue-shaped entry from a flattened style (review r8 major 53d5f6c1f50e):
+ * the host must never receive a raw MotionValue object — including bindings the severity lane
+ * REFUSED (non-numeric on a numeric key, invalid color on an rgba key, unmapped, partial
+ * duck-types), which are absent from the accepted set but still present in the authored style.
+ * Shape hints alone (get+subscribe) are enough to strip; incomplete surfaces must not reach RN
+ * (family-5 major 285dacf76bfe).
+ */
+export function stripMotionValueEntries(
+  flattened: Record<string, unknown>,
+): Record<string, unknown> {
+  const stripped: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(flattened)) {
+    if (!hasMotionValueShapeHints(value)) stripped[key] = value
+  }
+  return stripped
+}
+
+/**
+ * The per-render bound reconcile gate (r15 major 2f0c634bd8e1): the bindable set is the
+ * BOUND-AT-MOUNT key set — never the full mounted key set. A key mounted declaratively already
+ * has a driver registration; accepting a later binding on it would put two authorities on one
+ * key (the old registration and the new binding coexist). Identity swaps/removals within the
+ * mounted bound set pass; a key currently targeted by animate is the r8 crossover refusal.
+ * Returns the accepted bound map (production drops refused keys; development throws).
+ */
+export function gateRenderBoundKeys(
+  renderBound: Record<string, BoundStyleValue>,
+  mount: {
+    readonly mountedBoundKeys: readonly string[]
+    readonly animateKeys: readonly string[]
+    readonly identityEligibleBoundKeys?: readonly string[]
+    /** Exact direct-numeric bindings admitted by an empty-controller replacement mount. */
+    readonly identityEligibleGrowBoundKeys?: readonly string[]
+  },
+  gate: StyleValueGate = THROW_GATE,
+): Record<string, BoundStyleValue> {
+  for (const key of Object.keys(renderBound)) {
+    // Both crossover directions are refused (r8): a binding appearing on a key the animate
+    // prop currently targets is the same dual-authority violation as the reverse. U5 W3: a
+    // bound `transform` occupies the WHOLE transform component space, so an animate target on
+    // any transform shorthand crosses it.
+    const animateCrossover = mount.animateKeys.some(
+      (animateKey) =>
+        animateKey === key ||
+        (key === TRANSFORM_STRING_KEY_NAME && isNativeTransformComponentKey(animateKey)),
+    )
+    if (animateCrossover && mount.identityEligibleBoundKeys?.includes(key) !== true) {
+      const error = new Error(
+        key === TRANSFORM_STRING_KEY_NAME
+          ? `${componentPrefix(gate)}R4 scope: 'transform' is style-bound AND a declarative target names a transform ` +
+              'shorthand — a bound transform occupies the WHOLE transform component space, so ' +
+              'one authority covers every shorthand (REQ-DRIVER-029).'
+          : `${componentPrefix(gate)}R4 scope: '${key}' is a declarative target AND became style-bound — a key has ONE ` +
+              'reconciliation authority (REQ-DRIVER-029).',
+      )
+      if (gate.severity === 'development') throw error
+      gate.report(error)
+      delete renderBound[key]
+      continue
+    }
+    if (
+      !mount.mountedBoundKeys.includes(key) &&
+      mount.identityEligibleGrowBoundKeys?.includes(key) !== true
+    ) {
+      const error = new Error(
+        `${componentPrefix(gate)}R4 scope: style-bound key '${key}' was not BOUND at mount — binding authority is ` +
+          'fixed at mount per key (a declaratively-mounted key keeps its driver registration; ' +
+          'a late binding would be a second authority — REQ-API-026/REQ-DRIVER-029).',
+      )
+      if (gate.severity === 'development') throw error
+      gate.report(error)
+      delete renderBound[key]
+    }
+  }
+  return renderBound
+}
+
+/**
+ * The bound-key set as an OCCUPANCY list for gates that compare target key names
+ * (gateGestureStateProps): a bound `transform` occupies every transform shorthand
+ * (U5 W3, REQ-DRIVER-029) — the gesture-state XOR must see the whole component space, not just
+ * the literal bound key.
+ */
+export function expandBoundAuthorityKeys(boundKeys: readonly string[]): readonly string[] {
+  if (!boundKeys.includes(TRANSFORM_STRING_KEY_NAME)) return boundKeys
+  return [...boundKeys, ...NATIVE_TRANSFORM_ORDER]
+}
+
+export interface StyleValueBinding {
+  /**
+   * Subscribe the bound values and materialize their current values through the lane. By
+   * default every key pushes; the rebind lane passes ONLY the swapped keys (r12 minor
+   * e14a9c72f6b3 — unchanged keys already sit at their live value on the host, so a rebind
+   * writes exactly one crossing per changed key).
+   */
+  attach(pushKeys?: readonly string[]): void
+  detach(): void
+}
+
+export function createStyleValueBinding(
+  binding: WorkletDriverBinding,
+  handle: ElementHandle,
+  bound: Readonly<Record<string, BoundStyleValue>>,
+  gate: StyleValueGate = THROW_GATE,
+  // U5 (packet F3): the rgba-class delivery port — MotionView's onColorEndpoints hook, the SAME
+  // port the controller's static-color path feeds (MotionView.tsx:3542). A bound color publishes
+  // a fresh settled `[c, c]` sequence per write; the key's driver progress rests at PROGRESS_END
+  // from mount (addStaticKeys), so no projection machinery and no numeric lane crossing exists.
+  onColorEndpoints?: (key: string, sequence: readonly RGBA[]) => void,
+): StyleValueBinding {
+  let unsubscribes: Array<() => void> | null = null
+  // The animation-refusal law (review r1 major 1): an animation driving a bound value is
+  // per-frame JS→UI traffic. Fail loud naming the successor rung; production reports and
+  // stops the offending animation (fail-closed — the element keeps its last written value).
+  const refuseAnimation = (key: string, value: BoundStyleValue): void => {
+    const error = new Error(
+      `${componentPrefix(gate)}R4 scope: style-bound MotionValue on '${key}' is being driven by a JS-side ` +
+        'animation — per-frame bridge traffic is refused (REQ-DRIVER-029). Animate the ' +
+        'element property directly (driver-side), or wait for the driver-derived channel ' +
+        'rung (specs/R4-VALUE-CHANNEL-BUILD-PACKET.md).',
+    )
+    value.stop()
+    if (gate.severity === 'development') throw error
+    gate.report(error)
+  }
+  // One delivery writer per bound entry (U5): rgba-class entries validate the color string and
+  // publish the settled sequence; U5 W3's `transform` entry parses the string with the pinned
+  // grammar and writes the FULL component map through the SAME numeric retarget lane (one
+  // multi-key write per set() — uiApplyWrite validates all keys before mutating any,
+  // workletDriver.ts:1501-1518); numeric entries validate per write too (U5 review round 1
+  // MAJOR 1 — the render reconcile no longer re-validates held values after 8be94db5, so this
+  // arm is the ONLY checkpoint a non-number set() on an attached numeric binding meets:
+  // development throws, production reports and keeps the last good write). A color key without
+  // the port is a wiring invariant violation (the component always threads it) — loud, never a
+  // silent drop.
+  const writerFor = (key: string): ((latest: unknown) => void) => {
+    if (key === TRANSFORM_STRING_KEY_NAME) {
+      return (latest) => {
+        const map = boundTransformWriteMap(latest, gate)
+        if (map === null) return // production: refuse the write, keep the last good components
+        binding.driver.write(handle, map, undefined, 'bound-value-retarget')
+      }
+    }
+    if (!COLOR_BINDABLE_KEYS.has(key)) {
+      return (latest) => {
+        if (typeof latest !== 'number') {
+          const error = new Error(
+            `${componentPrefix(gate)}style-bound MotionValue on '${key}' holds ${describeValue(latest)}; ` +
+              'a bound numeric key writes only numbers — the write is refused under the ' +
+              'severity law (REQ-API-026, REQ-DRIVER-029).',
+          )
+          if (gate.severity === 'development') throw error
+          gate.report(error)
+          return // production: refuse the write, keep the last good value
+        }
+        binding.driver.write(handle, { [key]: latest }, undefined, 'bound-value-retarget')
+      }
+    }
+    if (onColorEndpoints === undefined) {
+      throw new Error(
+        `${componentPrefix(gate)}style-bound color key '${key}' has no onColorEndpoints delivery ` +
+          'port — the MotionView wiring invariant is broken (U5, REQ-API-026).',
+      )
+    }
+    const publish = onColorEndpoints
+    return (latest) => {
+      const parsed = boundColorValue(key, latest, gate)
+      if (parsed === null) return // production: refuse the write, keep the last good value
+      publish(key, [parsed, parsed]) // settled: from = to (constant projection), packet F3
+    }
+  }
+  return {
+    attach(pushKeys?: readonly string[]): void {
+      if (unsubscribes !== null) return
+      for (const [key, value] of Object.entries(bound)) {
+        // A value ALREADY animating at attach gets the same refusal as one that starts while
+        // bound (r12 major 4f2c9b7a1e06): a late mount or source swap must not open a
+        // per-frame channel the animationStart listener can never observe.
+        if (value.isAnimating()) refuseAnimation(key, value)
+        // Materialize the CURRENT value at attach (r11): a set() that landed before attachment
+        // (the layout-effect window) must reach the host — the subscription alone would wait
+        // for the NEXT change and leave the element stale.
+        if (pushKeys === undefined || pushKeys.includes(key)) {
+          writerFor(key)(value.get())
+        }
+      }
+      unsubscribes = Object.entries(bound).flatMap(([key, value]) => [
+        value.subscribe(writerFor(key)),
+        value.on('animationStart', () => refuseAnimation(key, value)),
+      ])
+    },
+    detach(): void {
+      if (unsubscribes === null) return
+      for (const unsubscribe of unsubscribes) unsubscribe()
+      unsubscribes = null
+    },
+  }
+}