@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/addScaleCorrector.ts

@@ -0,0 +1,97 @@
+// U7g (REQ-LAYOUT-024): native addScaleCorrector. Pin motion-dom scale-correction.ts merges
+// into a JS map; native projection runs on the UI thread so every `correct` must be a branded
+// worklet (F1). CSS-variable keys and unmapped keys refuse loud (no native meaning). boxShadow
+// has no native mapping (F3) — never a silent built-in.
+
+import { scheduleOnUI } from 'react-native-worklets'
+import { NUMERIC_STYLE_KEY_NAMES } from './mappedKeys'
+import { installScaleCorrectorOnUI } from './scaleCorrectorRegistry'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+
+export interface ScaleCorrectionContext {
+  readonly targetDelta: {
+    readonly x: { readonly scale: number }
+    readonly y: { readonly scale: number }
+  }
+  readonly treeScale: { readonly x: number; readonly y: number }
+}
+
+export type ScaleCorrector = (
+  latest: number | string,
+  context: ScaleCorrectionContext,
+) => number | string
+
+export interface ScaleCorrectorDefinition {
+  readonly correct: ScaleCorrector
+  readonly applyTo?: readonly string[]
+}
+
+export interface ScaleCorrectorMap {
+  readonly [key: string]: ScaleCorrectorDefinition
+}
+
+type BrandedWorklet = ScaleCorrector & { readonly __workletHash?: unknown }
+
+const BINDABLE = new Set<string>(NUMERIC_STYLE_KEY_NAMES)
+
+function isCssVariableName(key: string): boolean {
+  return key.startsWith('--')
+}
+
+function refusalForEntry(key: string, definition: ScaleCorrectorMap[string]): Error | null {
+  if (isCssVariableName(key)) {
+    return new Error(
+      `addScaleCorrector: "${key}" is a CSS variable — native has no CSS-variable style ` +
+        'surface (REQ-LAYOUT-024). Register a bindable native style key.',
+    )
+  }
+  if (!BINDABLE.has(key)) {
+    return new Error(
+      `addScaleCorrector: "${key}" is not a bindable native style key (REQ-LAYOUT-024). ` +
+        'Native scale correction applies to mapped numeric layout-style keys only.',
+    )
+  }
+  if (typeof definition.correct !== 'function') {
+    return new Error(
+      `addScaleCorrector: "${key}".correct must be a function (latest, context) => value.`,
+    )
+  }
+  if ((definition.correct as BrandedWorklet).__workletHash === undefined) {
+    return new Error(
+      `addScaleCorrector: "${key}".correct must carry the 'worklet' directive — native ` +
+        'projection corrects on the UI runtime every frame (REQ-LAYOUT-024 F1). Add ' +
+        "'worklet' as the function body's first statement.",
+    )
+  }
+  const applyTo = definition.applyTo
+  if (applyTo !== undefined) {
+    for (const target of applyTo) {
+      if (isCssVariableName(target) || !BINDABLE.has(target)) {
+        return new Error(
+          `addScaleCorrector: "${key}".applyTo contains "${target}", which is not a ` +
+            'bindable native style key (REQ-LAYOUT-024).',
+        )
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Register per-frame projection scale correctors. Each `correct` runs on the UI runtime
+ * during an active projection transform (the pin's addScaleCorrector channel).
+ */
+export function addScaleCorrector(correctors: ScaleCorrectorMap): void {
+  const severity = ambientNativeSeverity()
+  for (const key of Object.keys(correctors)) {
+    const definition = correctors[key]!
+    const error = refusalForEntry(key, definition)
+    if (error !== null) {
+      if (severity === 'development') throw error
+      consoleReporter(error)
+      continue
+    }
+    const applyTo = definition.applyTo === undefined ? null : [...definition.applyTo]
+    scheduleOnUI(installScaleCorrectorOnUI, key, definition.correct, applyTo)
+  }
+}

package/src/native/motion/colorEndpointUiFeed.ts

@@ -0,0 +1,32 @@
+// Endpoint SharedValue feeds must not mutate from the JS guest (iOS serialization hang,
+// PROOF §SIGABRT-1 Q3 / host-feed law): a JS-thread `cell.value = …` on a Reanimated SharedValue
+// schedules flushUIQueue → workletFunction → mutable, the hang tail
+// /__closure/workletFunction/__closure/mutable/__closure. Mount-time makeMutable is fine (no
+// guest write); retargets ride scheduleOnUI + this named worklet (primitive/branded args only).
+
+import type { RGBA } from '@unrulysystems/native-motion-core'
+
+/**
+ * UI-lane writer for a color keyframe endpoint sequence SharedValue.
+ * Call only via scheduleOnUI(setColorEndpointSequenceOnUI, cell, sequence).
+ */
+export function setColorEndpointSequenceOnUI(
+  sequenceCell: { value: readonly RGBA[] },
+  sequence: readonly RGBA[],
+): void {
+  'worklet'
+  sequenceCell.value = sequence
+}
+
+/**
+ * UI-lane writer for a discrete [from, to] keyword pair SharedValue (T23 B2b — same guest-write
+ * law as the color feed; strings are primitive-safe for the crossing).
+ * Call only via scheduleOnUI(setDiscreteEndpointPairOnUI, cell, pair).
+ */
+export function setDiscreteEndpointPairOnUI(
+  pairCell: { value: readonly string[] },
+  pair: readonly string[],
+): void {
+  'worklet'
+  pairCell.value = pair
+}

package/src/native/motion/colorProjection.ts

@@ -0,0 +1,39 @@
+// L1's color projection seam (specs/L1-BUILD-PACKET.md §semantics 3): the ONE function that turns a
+// driver progress scalar into the RN backgroundColor string, shared by the animated-style worklet and
+// the deterministic checks so the two paths can never fork (the M2.4 routePanEnd exported-seam
+// pattern). Pure core plumbing — SPRING owns the [0,100] progress convention (REQ-SPRING-013), core
+// value-types own the linear-light mix + byte-exact rgba() projection (REQ-VALUETYPE-006). Runs on
+// the UI runtime (worklet-tagged core dist, the M2.1-proven crossing).
+
+import { mixColor, transformColor, type RGBA } from '@unrulysystems/native-motion-core'
+
+// progress rides the driver's [0, 100] internal convention; the mix seam consumes a [0, 1] fraction.
+export function projectColor(from: RGBA, to: RGBA, progress: number): string {
+  'worklet'
+  return transformColor(mixColor(from, to, progress / 100))
+}
+
+// The SEQUENCE projection for a color keyframe array (R8 M2, review major 35): the driver drives a
+// numeric PROGRESS keyframe array [0 … 100] so the shipped keyframe generator owns offsets/per-segment
+// easing; this maps the live progress to a position through the RGBA sequence, then mixColors the
+// adjacent pair for that segment. A 2-color sequence reduces EXACTLY to `projectColor`
+// (position = progress/100, segment 0). The sequence is length ≥2 (validated upstream).
+export function projectColorSequence(sequence: readonly RGBA[], progress: number): string {
+  'worklet'
+  const lastSegment = sequence.length - 2 // ≥0 for a length-≥2 sequence
+  const position = (progress / 100) * (sequence.length - 1)
+  const floored = Math.floor(position)
+  const segment = floored < 0 ? 0 : floored > lastSegment ? lastSegment : floored
+  return transformColor(mixColor(sequence[segment]!, sequence[segment + 1]!, position - segment))
+}
+
+// The RGBA the sequence renders at `progress` (the un-projected sibling of `projectColorSequence`):
+// the JS-side re-seed of a color UPDATE reads the live color THROUGH the sequence (major 35), replacing
+// the old two-endpoint `mixColor(from, to, …)`. Same segment math; returns the mixed RGBA, not a string.
+export function sampleColorSequence(sequence: readonly RGBA[], progress: number): RGBA {
+  const lastSegment = sequence.length - 2 // ≥0 for a length-≥2 sequence
+  const position = (progress / 100) * (sequence.length - 1)
+  const floored = Math.floor(position)
+  const segment = floored < 0 ? 0 : floored > lastSegment ? lastSegment : floored
+  return mixColor(sequence[segment]!, sequence[segment + 1]!, position - segment)
+}

package/src/native/motion/composeTransform.ts

@@ -0,0 +1,271 @@
+import { scheduleOnRN } from 'react-native-worklets'
+import {
+  buildTransformTemplateArgs,
+  parseTransformTemplateOutput,
+  type TransformTemplate,
+} from '@unrulysystems/native-motion-core'
+import { deferUiOriginatedCallback } from '../driver/workletDriver'
+import { isMotionValue } from './styleValueBinding'
+import {
+  NATIVE_TRANSFORM_ORDER,
+  TRANSFORM_ANGLE_KEYS,
+  type MappedTransformKey,
+} from './transformOrder'
+
+// REQ-DRIVER-028 — canonical transform composition order. The order/angle DATA lives in
+// transformOrder.ts (RN-import-free, so the U5-W3 transform-string parser shares the single
+// authority without dragging react-native-worklets into its graph); this module stays the
+// runtime owner — the composite RN `transform` array is built in pinned Motion's order so
+// authoring order never changes the visual result. Re-exported here so every existing consumer
+// (MotionView, layoutTransition, the registry cross-check test) keeps one import site.
+export { NATIVE_TRANSFORM_ORDER, TRANSFORM_ANGLE_KEYS, type MappedTransformKey }
+
+// The RN transform entry name differs from the Motion target key only for the translations.
+const RN_ENTRY_NAME: Record<MappedTransformKey, string> = Object.freeze({
+  perspective: 'perspective',
+  x: 'translateX',
+  y: 'translateY',
+  scale: 'scale',
+  scaleX: 'scaleX',
+  scaleY: 'scaleY',
+  rotate: 'rotate',
+  rotateX: 'rotateX',
+  rotateY: 'rotateY',
+  skewX: 'skewX',
+  skewY: 'skewY',
+})
+
+// Plain-object lookups (not Sets): worklet captures stay in the most conservative shareable
+// shape — records of primitives — so serialization can never be the failure mode on the UI runtime.
+const ANGLE_KEY_INDEX: Record<string, 1> = Object.freeze(
+  Object.fromEntries(TRANSFORM_ANGLE_KEYS.map((key) => [key, 1 as const])),
+)
+const ORDER_INDEX: Record<string, number> = Object.freeze(
+  Object.fromEntries(NATIVE_TRANSFORM_ORDER.map((key, index) => [key, index])),
+)
+
+// Membership probe for MotionView's animated-style worklet: routes a mounted key to the transform
+// composite vs the plain style path without hand-listing keys at the call site.
+export function isMappedTransformKey(key: string): key is MappedTransformKey {
+  'worklet'
+  return ORDER_INDEX[key] !== undefined
+}
+
+// Layout's Reanimated-owned frames must name transform entries exactly like the ordinary
+// animated-style lane. Keeping the translation aliases here prevents a layout/property flight
+// from producing `{ x }` or `{ y }`, which React Native does not recognize as transform entries.
+export function nativeTransformEntryName(key: MappedTransformKey): string {
+  'worklet'
+  return RN_ENTRY_NAME[key]
+}
+
+/**
+ * Layout's host-proxy mirror is another producer of the same RN transform array as the ordinary
+ * animated-style lane. Keeping its ordering lookup here prevents an authoring-order divergence
+ * between the two producers (REQ-DRIVER-028).
+ */
+export function compareMappedTransformKeys(a: MappedTransformKey, b: MappedTransformKey): number {
+  'worklet'
+  return ORDER_INDEX[a]! - ORDER_INDEX[b]!
+}
+
+// Pure and workletized: MotionView's animated style calls this on the UI runtime every frame; unit
+// tests call it as a plain function. Captures are frozen plain data only (order table, name map,
+// angle set) — no cross-module calls cross the worklet boundary.
+
+/** Family-5 gate result: finite numeric seeds vs mapped keys that must be severity-refused + stripped. */
+export type StaticTransformStyleGate = {
+  readonly seeds: Readonly<Record<string, number>>
+  readonly refusedKeys: readonly MappedTransformKey[]
+}
+
+/**
+ * Family-5: classify every authored mapped transform shorthand on a flattened style bag.
+ * Finite numbers seed composeTransform; exact public MotionValues leave for the binding lane
+ * (full surface, same predicate as styleValueBinding); any other present value is refused
+ * (NaN / Infinity / string / near-MotionValue / opaque) so the host never keeps a silent
+ * RN-dropped residual.
+ */
+export function gateStaticTransformStyle(
+  style: Readonly<Record<string, unknown>>,
+): StaticTransformStyleGate {
+  const seeds: Record<string, number> = {}
+  const refusedKeys: MappedTransformKey[] = []
+  for (let i = 0; i < NATIVE_TRANSFORM_ORDER.length; i++) {
+    const key = NATIVE_TRANSFORM_ORDER[i]!
+    if (!Object.prototype.hasOwnProperty.call(style, key)) continue
+    const value = style[key]
+    // Full MotionValue only — partial duck-types are refused (not left for a crashing attach).
+    if (isMotionValue(value)) continue
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      seeds[key] = value
+    } else {
+      refusedKeys.push(key)
+    }
+  }
+  return { seeds, refusedKeys }
+}
+
+/**
+ * Family-5: extract finite numeric Motion transform shorthands from a flattened style record.
+ * Pure JS (not a worklet) — called at render to seed composeTransform for static style transforms.
+ */
+export function extractStaticTransformSeeds(
+  style: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, number>> {
+  return gateStaticTransformStyle(style).seeds
+}
+
+export function composeTransform(
+  values: Readonly<Record<string, number>>,
+): Record<string, number | string>[] {
+  'worklet'
+  const authored = Object.keys(values)
+  const present: string[] = []
+  let pathRotation = 0
+  for (let i = 0; i < authored.length; i++) {
+    const key = authored[i]!
+    if (key === 'pathRotation') {
+      pathRotation = values.pathRotation ?? 0
+      continue
+    }
+    if (ORDER_INDEX[key] === undefined) {
+      // The unmapped-key path is a driver-registry skew surfaced at the animated-style worklet —
+      // an operating condition on a LIVE UI callback, never an invariant worth a UI throw (seal
+      // r7, F1, iOS AUTO SIGABRT campaign): the key is REFUSED from the output and reported once
+      // per key per app run through the scheduleOnRN severity channel. The UI-global dedupe is
+      // required because module state is cloned per worklet materialization and never persists.
+      const refusalGlobal = globalThis as UnmappedTransformKeyRefusalUiGlobal
+      if (refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals === undefined)
+        refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals = {}
+      if (refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals[key] === undefined) {
+        refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals[key] = true
+        scheduleOnRN(reportUnmappedTransformKeyRefusal, key)
+      }
+      continue
+    }
+    present.push(key)
+  }
+  present.sort((a, b) => ORDER_INDEX[a]! - ORDER_INDEX[b]!)
+  const out: Record<string, number | string>[] = []
+  for (let i = 0; i < present.length; i++) {
+    const key = present[i] as MappedTransformKey
+    const value = values[key]!
+    out.push({
+      [nativeTransformEntryName(key)]: ANGLE_KEY_INDEX[key] === 1 ? `${value}deg` : value,
+    })
+  }
+  // U8 (REQ-API-059): pin composes pathRotation as a separate additive rotate after the user's
+  // rotate so concurrent rotate is never clobbered. Skip when zero (pin `if (pathRotation)`).
+  if (pathRotation) out.push({ rotate: `${pathRotation}deg` })
+  return out
+}
+
+interface UnmappedTransformKeyRefusalUiGlobal {
+  __nativeMotionUnmappedTransformKeyRefusals?: Record<string, true>
+}
+
+/**
+ * T17 (specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md floor 3): the per-frame template path. The
+ * branded-worklet template is called ON THE UI RUNTIME with the pin's two args (typed values map
+ * with defaults included, generated string with defaults excluded); its return string parses into
+ * the RN transform array in authored order — prepend/append/reorder all expressible. A throwing
+ * template or an off-grammar return is a severity refusal on a LIVE UI callback (never a UI
+ * throw — a terminate on device): the template's output is refused, the canonical composition
+ * paints, and the failure reports ONCE per component through scheduleOnRN (the unmapped-key
+ * precedent: UI-global dedupe because module state is cloned per worklet materialization).
+ */
+// The refusal ledger cap (review minor 1) — mirrors the projection-radius ledger's law. DECLARED
+// ABOVE its reader: `composeTransformWithTemplate` is a worklet, and a worklet's captured-argument
+// object is evaluated at its own declaration position. Sitting below the reader, this const was
+// captured as `undefined`, so `ids.length >= undefined` was always false and the eviction this
+// bound exists to trigger never ran — the ledger grew without limit while its comment claimed it
+// was "bounded like every cache". Pinned by check-worklet-forward-refs.
+const MAX_TRANSFORM_TEMPLATE_REFUSAL_IDS = 256
+
+export function composeTransformWithTemplate(
+  values: Readonly<Record<string, number>>,
+  template: TransformTemplate,
+  componentId: string,
+): Record<string, number | string>[] {
+  'worklet'
+  // Driver-registry skew must never vanish silently because a template owns composition
+  // (review minor 2): surface unmapped keys through the SAME refusal channel as the canonical
+  // lane and keep them out of the template args (no typeable unit exists for them).
+  const mapped: Record<string, number> = {}
+  const authored = Object.keys(values)
+  for (let i = 0; i < authored.length; i++) {
+    const key = authored[i]!
+    if (key === 'pathRotation') continue
+    if (ORDER_INDEX[key] === undefined) {
+      const refusalGlobal = globalThis as UnmappedTransformKeyRefusalUiGlobal
+      if (refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals === undefined)
+        refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals = {}
+      if (refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals[key] === undefined) {
+        refusalGlobal.__nativeMotionUnmappedTransformKeyRefusals[key] = true
+        scheduleOnRN(reportUnmappedTransformKeyRefusal, key)
+      }
+      continue
+    }
+    mapped[key] = values[key]!
+  }
+  try {
+    const args = buildTransformTemplateArgs(mapped)
+    return parseTransformTemplateOutput(template(args.values, args.generated))
+  } catch (error) {
+    const refusalGlobal = globalThis as TransformTemplateRefusalUiGlobal
+    if (refusalGlobal.__nativeMotionTransformTemplateRefusals === undefined)
+      refusalGlobal.__nativeMotionTransformTemplateRefusals = {}
+    const ledger = refusalGlobal.__nativeMotionTransformTemplateRefusals
+    if (ledger[componentId] === undefined) {
+      // Bounded like every cache (review minor 1): insertion-ordered eviction past the cap —
+      // the OLDEST episode's entry drops (it reports again if still live), the newest always
+      // fires. Runs only on a first-fire per id, never per frame.
+      const ids = Object.keys(ledger)
+      if (ids.length >= MAX_TRANSFORM_TEMPLATE_REFUSAL_IDS) delete ledger[ids[0]!]
+      ledger[componentId] = true
+      scheduleOnRN(
+        reportTransformTemplateRefusal,
+        componentId,
+        error instanceof Error ? error.message : String(error),
+      )
+    }
+    return composeTransform(values)
+  }
+}
+
+interface TransformTemplateRefusalUiGlobal {
+  __nativeMotionTransformTemplateRefusals?: Record<string, true>
+}
+
+// The RN-side severity-law reporter for a template failure (T17): one JS task out of the
+// scheduleOnRN dispatch extent — development throws; production reports through the error
+// channel while the canonical composition paints (the template's output is refused). The UI
+// side never throws.
+function reportTransformTemplateRefusal(componentId: string, message: string): void {
+  const error = new Error(
+    `${componentId}: transformTemplate failed and its output was refused — the canonical ` +
+      `transform composition painted instead (T17). Cause: ${message}`,
+  )
+  deferUiOriginatedCallback(() => {
+    if (typeof __DEV__ === 'undefined' || __DEV__ !== false) throw error
+    console.error(error)
+  })
+}
+
+// The RN-side severity-law reporter for a driver-mapped-key violation (seal r7, F1): delivered
+// one JS task out of the scheduleOnRN dispatch extent (the seal-r3 seam) — development throws;
+// production reports through the error channel while the key is refused from the transform
+// output. The UI side never throws (a bare std::terminate on device).
+declare const __DEV__: boolean | undefined
+
+function reportUnmappedTransformKeyRefusal(key: string): void {
+  const error = new Error(
+    `composeTransform: transform key '${key}' is not driver-mapped (REQ-DRIVER-027/-028) — ` +
+      'refused from the transform output (iOS AUTO SIGABRT campaign).',
+  )
+  deferUiOriginatedCallback(() => {
+    if (typeof __DEV__ === 'undefined' || __DEV__ !== false) throw error
+    console.error(error)
+  })
+}

package/src/native/motion/constraintMeasure.ts

@@ -0,0 +1,157 @@
+// REQ-GESTURE-028 / REQ-API-042 (R15 D2) — the grab-time constraint MEASURE seam. The pin
+// reads both page boxes synchronously when it resolves (a cache miss or its own
+// measure/resize invalidation machinery); native has no synchronous page-box read, so
+// MotionView's wiring measures asynchronously at EVERY grab (the freshness superset) and the
+// wiring defers begin until the boxes land. The draggable's LAYOUT box is the visual frame
+// MINUS the live drag value per dragged axis (the pin's projection.layout.layoutBox is
+// transform-independent; the drag value applies on top of layout, so layout = visual − value).
+// The constraint element is anything exposing measureInWindow (a mounted host ref); the pin's
+// invariant fails loudly when it doesn't resolve. Errors here carry NO component prefix —
+// ownership lands at exactly one boundary (MotionView's componentDragError, review r11
+// minor 1).
+
+import { describeValue, type Driver, type ElementHandle } from '@unrulysystems/native-motion-core'
+import type { DragAxis } from '@unrulysystems/native-motion-core'
+import type { ConstraintsMeasure, ConstraintsMeasureBoxes } from './dragGestureWiring'
+
+/** Safe reject payload — never throws on hostile throwables (Object.create(null)). */
+function asRejectError(error: unknown): Error {
+  if (error instanceof Error) return error
+  // describeValue is total over revoked proxies / null-prototype objects (core formatter law).
+  return new Error(describeValue(error))
+}
+
+// The pin's invariant surface (VEDC "drag-constraints-ref"): a ref whose `.current` is not a
+// mounted measurable element at drag start is a loud failure, never a mount-time guess and
+// never a silent unconstrained grab.
+export function isMeasurableConstraintTarget(target: unknown): target is {
+  measureInWindow(callback: (x: number, y: number, width: number, height: number) => void): void
+} {
+  return (
+    typeof target === 'object' &&
+    target !== null &&
+    'measureInWindow' in target &&
+    typeof (target as { measureInWindow?: unknown }).measureInWindow === 'function'
+  )
+}
+
+interface MeasurableHost {
+  measureInWindow(callback: (x: number, y: number, width: number, height: number) => void): void
+}
+
+// Build the wiring's measure seam over the draggable's own measurable host ref, the driver
+// (for the live per-axis values), and the element handle. `axes` are the element's DRAGGED
+// axes: a live driver value exists only on those — an axis with no drag channel has no driver
+// registration at all (liveFor on it THROWS, REQ-DRIVER-025), and its drag value is zero, so
+// its layout span IS the visual span (the pin's transform-independent layoutBox analog).
+export function createConstraintMeasure(options: {
+  readonly driver: Driver
+  readonly handle: ElementHandle
+  readonly axes: readonly DragAxis[]
+  readonly hostRef: () => MeasurableHost | null
+  /**
+   * REQ-API-043 page-point correction at the measure ingest boundary (transformPagePoint).
+   * Applied to measured window boxes so ref constraints under transformed ancestors match
+   * the pin's page-space math.
+   */
+  readonly transformPagePoint?:
+    | ((point: { readonly x: number; readonly y: number }) => {
+        readonly x: number
+        readonly y: number
+      })
+    | undefined
+}): ConstraintsMeasure {
+  const { driver, handle, axes, hostRef, transformPagePoint } = options
+  const mapBox = (
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+  ): { readonly min: number; readonly max: number } => {
+    if (transformPagePoint === undefined) {
+      return { min: x, max: x + width }
+    }
+    // Corner-transform so scale/offset ancestors correct both position and extent.
+    const tl = transformPagePoint({ x, y })
+    const br = transformPagePoint({ x: x + width, y: y + height })
+    return { min: tl.x, max: br.x }
+  }
+  const mapBoxY = (
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+  ): { readonly min: number; readonly max: number } => {
+    if (transformPagePoint === undefined) {
+      return { min: y, max: y + height }
+    }
+    const tl = transformPagePoint({ x, y })
+    const br = transformPagePoint({ x: x + width, y: y + height })
+    return { min: tl.y, max: br.y }
+  }
+  return (container) =>
+    new Promise<ConstraintsMeasureBoxes>((resolve, reject) => {
+      const target = container.current
+      if (!isMeasurableConstraintTarget(target)) {
+        reject(
+          new Error(
+            "a dragConstraints ref must be passed to another component's ref " +
+              'prop — the constraint element is unmounted or not measurable at drag start ' +
+              '(REQ-API-042; the pin invariant, VEDC "drag-constraints-ref").',
+          ),
+        )
+        return
+      }
+      const host = hostRef()
+      if (host === null) {
+        reject(new Error("the draggable's host is not measurable at drag start (REQ-API-042)."))
+        return
+      }
+      // The pin reads the draggable's LAYOUT box (transform-independent): the visual frame
+      // minus the live drag value per DRAGGED axis (layout = visual − value; the session's
+      // value applies on top of layout; a non-dragged axis carries no drag value at all).
+      // The live read happens INSIDE the measure callback (review r5 major 2): the delivered
+      // frame and the live value must pair at the same instant — reading live at dispatch would
+      // inject the UI-measure latency as a per-frame jitter into the layout box. The callbacks
+      // run OUTSIDE the Promise executor's scope, so a callback-time failure (a disposed driver
+      // after unmount — review r8 major 2) must REJECT explicitly, never escape raw and leave
+      // the measurement pending forever.
+      let draggableBox: ConstraintsMeasureBoxes['draggableBox'] | null = null
+      let containerBox: ConstraintsMeasureBoxes['containerBox'] | null = null
+      const commit = (): void => {
+        if (draggableBox !== null && containerBox !== null) {
+          resolve({ draggableBox, containerBox })
+        }
+      }
+      host.measureInWindow((x, y, width, height) => {
+        try {
+          const liveX = axes.includes('x') ? driver.liveFor(handle, 'x').value : 0
+          const liveY = axes.includes('y') ? driver.liveFor(handle, 'y').value : 0
+          const mappedX = mapBox(x, y, width, height)
+          const mappedY = mapBoxY(x, y, width, height)
+          draggableBox = {
+            x: { min: mappedX.min - liveX, max: mappedX.max - liveX },
+            y: { min: mappedY.min - liveY, max: mappedY.max - liveY },
+          }
+          commit()
+        } catch (error) {
+          // transformPagePoint / live read may throw — reject so the deferred grab is not
+          // stranded (G-INV-7). Never String(error) on hostile throwables (seal review r6 major).
+          reject(asRejectError(error))
+        }
+      })
+      target.measureInWindow((x, y, width, height) => {
+        try {
+          containerBox = {
+            x: mapBox(x, y, width, height),
+            y: mapBoxY(x, y, width, height),
+          }
+          commit()
+        } catch (error) {
+          // transformPagePoint may throw — reject so the deferred grab is not stranded
+          // (G-INV-7; seal review r3 major / r6 major String-safety).
+          reject(asRejectError(error))
+        }
+      })
+    })
+}

package/src/native/motion/deferredPendingSnapshots.ts

@@ -0,0 +1,25 @@
+// REQ-VALUETYPE-013 — split command vs deferred-pending animate snapshots under gesture hold.
+// review-1785228898857-1thixx: full-scope pending must see the declarative authority (including
+// held keys still in animate); commands must exclude held keys (protectedKeys).
+
+/**
+ * `command` — keys safe to retarget now (not gesture-held).
+ * `deferredPending` — full declarative animate authority for pending abandon/rebuild (never
+ * held-filtered; absence means product removed the key from animate).
+ */
+export function splitCommandAndDeferredAnimateSnapshots(
+  declarativeAnimate: Readonly<Record<string, unknown>>,
+  held: ReadonlySet<string>,
+): {
+  readonly command: Record<string, unknown>
+  readonly deferredPending: Record<string, unknown>
+} {
+  const command: Record<string, unknown> = {}
+  for (const key of Object.keys(declarativeAnimate)) {
+    if (!held.has(key)) command[key] = declarativeAnimate[key]
+  }
+  return {
+    command,
+    deferredPending: { ...declarativeAnimate },
+  }
+}

package/src/native/motion/discreteProjection.ts

@@ -0,0 +1,36 @@
+// The discrete keyword projection seam (T23 B, packet design law B) — the projectColorSequence
+// pattern: the driver animates a [0, 100] progress channel in a shared value; the animated-style
+// worklet projects the committed keyword from per-key endpoint shared values each frame. This is
+// the ONE projection both the style worklet and deterministic checks call, parity-bound to core
+// mixDiscrete by discreteProjection.test.ts so the two statements of the law — both of its paths,
+// the mixVisibility step and the zero-slot constant — can never fork.
+//
+// The law is RESTATED inline rather than calling mixDiscrete because a worklet capture must stay
+// primitive — no captured Set, so invisible-set membership is checked inline. Both statements are
+// bound together by discreteProjection.test.ts over every pair class, so they cannot fork.
+//
+// ONE deliberate asymmetry: `mixDiscrete` refuses an endpoint that is not a discrete keyword, and
+// this does not. A worklet must be TOTAL — a UI-runtime throw is banned (check:no-ui-throw) — and
+// the controller only ever registers keyword pairs, so the guard belongs at the exported core
+// symbol a caller can reach directly, not on the frame path. The parity binding covers the keyword
+// family, which is the only family that reaches here.
+//
+// H3: a both-visible pair used to be refused before registration, and this worklet's final arm
+// doubled as a total fallback for it — holding the ORIGIN, which is not what the pin does. That
+// pair is now legal and reaches here, so the constant arm is explicit rather than incidental.
+export function projectDiscreteStep(from: string, to: string, progress: number): string {
+  'worklet'
+  if (from === 'none' || from === 'hidden') {
+    // Invisible ORIGIN appears at start: origin only while p <= 0 (the pin's origin arm — a
+    // both-invisible pair takes this arm first, exactly like mixDiscrete).
+    return progress <= 0 ? from : to
+  }
+  if (to === 'none' || to === 'hidden') {
+    // Invisible TARGET disappears at end: target only once p >= 100 (the internal channel is
+    // [0, 100]; core's mixDiscrete sees the same instant as p >= 1).
+    return progress >= 100 ? to : from
+  }
+  // Both visible: the pin's zero-slot template publishes the TARGET at every progress, negative
+  // and zero included. Not a step — nothing here reads `progress` at all.
+  return to
+}