@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/systemGestureExclusion.ts

@@ -0,0 +1,61 @@
+// REQ-GESTURE-032 — Android drag hosts register system-gesture exclusion for their bounds.
+//
+// Web has no equivalent strip, so the mapping is a no-op there and on iOS. The module is
+// Android-only autolinking. Host tests mock `react-native` without Platform/NativeModules;
+// vitest throws on a missing named export, so every host access is inside try/catch — a
+// missing module is a no-op, never a throw, because a drag View still has to mount.
+import { findNodeHandle, NativeModules, Platform } from 'react-native'
+
+interface ExclusionNative {
+  readonly excludeView: (viewTag: number) => void
+  readonly clearView: (viewTag: number) => void
+}
+
+function exclusionNative(): ExclusionNative | null {
+  try {
+    if (Platform.OS !== 'android') return null
+    const mod = NativeModules.NativeMotionGestureExclusion as ExclusionNative | undefined
+    if (
+      mod === undefined ||
+      typeof mod.excludeView !== 'function' ||
+      typeof mod.clearView !== 'function'
+    ) {
+      return null
+    }
+    return mod
+  } catch {
+    return null
+  }
+}
+
+function nativeTag(node: unknown): number | null {
+  if (node === null || node === undefined || typeof node !== 'object') return null
+  const tagged = node as { __nativeTag?: unknown; _nativeTag?: unknown; nativeTag?: unknown }
+  for (const key of ['__nativeTag', '_nativeTag', 'nativeTag'] as const) {
+    const value = tagged[key]
+    if (typeof value === 'number') return value
+  }
+  try {
+    if (typeof findNodeHandle !== 'function') return null
+    const tag = findNodeHandle(node as Parameters<typeof findNodeHandle>[0])
+    return typeof tag === 'number' ? tag : null
+  } catch {
+    return null
+  }
+}
+
+/** Register this host's bounds as *this drag is mine*. No-op when the module is absent. */
+export function applyHostGestureExclusion(node: unknown): void {
+  const native = exclusionNative()
+  const tag = nativeTag(node)
+  if (native === null || tag === null) return
+  native.excludeView(tag)
+}
+
+/** Drop the registration. No-op when the module is absent. */
+export function clearHostGestureExclusion(node: unknown): void {
+  const native = exclusionNative()
+  const tag = nativeTag(node)
+  if (native === null || tag === null) return
+  native.clearView(tag)
+}

package/src/native/motion/tapGestureWiring.ts

@@ -0,0 +1,215 @@
+// The tap recognizer protocol (R5, REQ-API-030) as pure, host-agnostic wiring — MotionView
+// binds the substrate's Tap gesture events to this; the pinned semantics live HERE where they
+// are unit-testable (the dragGestureWiring precedent). Pinned contract (motion-dom
+// MotionNodeTapHandlers + framer-motion press.ts at the SS B pin): onTapStart when the press
+// begins on the element; onTap when it ends ON the element (the recognizer succeeded);
+// onTapCancel when a BEGUN press ends unrecognized — an off-element RELEASE (the up-target
+// verdict; no movement threshold exists anywhere, r4 major 27) or a competing gesture (drag)
+// activating. A press that never began dispatches nothing.
+
+import type { TapCallback, TapInfo } from '@unrulysystems/native-motion-core'
+import type { HubTapTouchPoint } from './dragHubStream'
+import type { MotionComponentId } from './motionViewController'
+import type { StyleValueGate } from './styleValueBinding'
+
+const THROW_GATE: StyleValueGate = {
+  severity: 'development',
+  report: () => {},
+  componentId: '<Motion.View>',
+}
+
+/** What the boundary receives before validation — anything the caller authored. */
+export type TapCallbackInput = TapCallback | undefined
+
+/**
+ * The coordinate slice of the substrate's tap events this wiring reads: absolute (device/page)
+ * coordinates feed TapInfo.point; RELATIVE coordinates feed the up-target verdict.
+ */
+export interface TapPointEvent {
+  readonly absoluteX: number
+  readonly absoluteY: number
+  readonly x: number
+  readonly y: number
+}
+
+export interface TapGestureWiring {
+  handleBegin(event: TapPointEvent): void
+  /** The recognizer ENDED while active; `success` is the substrate's recognition verdict. */
+  handleEnd(event: TapPointEvent, success: boolean): void
+  /** Always fires last; a begun-but-unrecognized press cancels here, exactly once. */
+  handleFinalize(event: TapPointEvent, success: boolean): void
+}
+
+export function createTapGestureWiring(options: {
+  readonly callbacks: {
+    readonly onTap?: TapCallback
+    readonly onTapStart?: TapCallback
+    readonly onTapCancel?: TapCallback
+  }
+  /**
+   * The element's current layout size, for the pinned UP-TARGET verdict (r2 major 13:
+   * motion-dom press decides success from the pointer-up target — `isNodeOrChild(target,
+   * upEvent.target)` — so leave-and-return still taps and only the RELEASE point decides).
+   * Null before the first layout: begin implies on-element, so the verdict defaults inside.
+   */
+  readonly getElementSize?: () => { readonly width: number; readonly height: number } | null
+  /**
+   * U7d (REQ-API-030 global form): the pin's `useGlobalTarget ||` short-circuit
+   * (motion-dom press/index.ts:104-112) — in global mode EVERY up resolves success and the
+   * release-point containment verdict is bypassed.
+   */
+  readonly globalTarget?: boolean
+}): TapGestureWiring {
+  const { callbacks, getElementSize } = options
+  const releasedInside = (event: TapPointEvent): boolean => {
+    if (options.globalTarget === true) return true
+    const size = getElementSize?.() ?? null
+    if (size === null) return true
+    return event.x >= 0 && event.x <= size.width && event.y >= 0 && event.y <= size.height
+  }
+  // Per-cycle state: a cancel fires only for a press that BEGAN and did not succeed.
+  let began = false
+  let succeeded = false
+  const info = (event: TapPointEvent): TapInfo => ({
+    point: { x: event.absoluteX, y: event.absoluteY },
+  })
+  return {
+    handleBegin(event) {
+      began = true
+      succeeded = false
+      callbacks.onTapStart?.(event, info(event))
+    },
+    handleEnd(event, success) {
+      if (!began || !success) return
+      // The pinned up-target law: the substrate's recognition says the press ENDED normally;
+      // whether it is a TAP or a CANCEL is decided by the RELEASE point's containment — a
+      // release off the element cancels AT that release point, never a boundary crossing.
+      if (releasedInside(event)) {
+        succeeded = true
+        callbacks.onTap?.(event, info(event))
+        return
+      }
+      succeeded = true // the cycle resolved (as a cancel); finalize must not double-cancel
+      callbacks.onTapCancel?.(event, info(event))
+    },
+    handleFinalize(event, success) {
+      if (began && !success && !succeeded) callbacks.onTapCancel?.(event, info(event))
+      began = false
+      succeeded = false
+    },
+  }
+}
+
+/**
+ * U7d (REQ-API-030 global form) — the global press observer. The pin's `press()` with
+ * `useGlobalTarget` listens on window: a primary-pointer down ANYWHERE begins the press and
+ * every up resolves it (motion-dom press/index.ts). On native the MotionRoot hub touch stream
+ * is the window analog (packet F1: observation, never a competing recognizer); this observer
+ * carries the pinned press policy at JS altitude over that stream:
+ * - the pin's start-gates (press/index.ts:17-19 `isValidPressEvent`): primary pointer only,
+ *   and never while a drag is active — START-gates only, so an ACTIVE press is not cancelled
+ *   by a drag starting;
+ * - the hub stream's multi-touch law: only the touch that began the press resolves it;
+ * - cancel arrives only from the stream's touch-cancel path (the R11 touch-steal mapping).
+ */
+export interface GlobalTapObserver {
+  onTouchDown(touch: HubTapTouchPoint, primary: boolean): void
+  onTouchUp(touch: HubTapTouchPoint): void
+  onTouchCancel(touch: HubTapTouchPoint): void
+}
+
+export function createGlobalTapObserver(options: {
+  readonly wiring: TapGestureWiring
+  /** The pin's isDragActive analog (native: the app-global per-axis drag lock). */
+  readonly isDragActive: () => boolean
+}): GlobalTapObserver {
+  const { wiring, isDragActive } = options
+  let pressing: HubTapTouchPoint | null = null
+  const eventOf = (touch: HubTapTouchPoint): TapPointEvent => ({
+    // The root stream carries screen-absolute coordinates only. The RELATIVE slots mirror the
+    // absolute ones — the global verdict never reads relative coordinates (containment is
+    // bypassed), and TapInfo.point is built from the absolute pair (the anywhere point).
+    x: touch.absoluteX,
+    y: touch.absoluteY,
+    absoluteX: touch.absoluteX,
+    absoluteY: touch.absoluteY,
+  })
+  return {
+    onTouchDown(touch, primary) {
+      // The pinned start-gates: primary pointer + no active drag, and one press per surface.
+      if (!primary || pressing !== null || isDragActive()) return
+      pressing = touch
+      wiring.handleBegin(eventOf(touch))
+    },
+    onTouchUp(touch) {
+      if (pressing === null || touch.id !== pressing.id) return
+      pressing = null
+      // Global mode: EVERY primary-pointer up resolves the press as a successful tap (the
+      // containment verdict is bypassed inside the wiring).
+      wiring.handleEnd(eventOf(touch), true)
+      wiring.handleFinalize(eventOf(touch), true)
+    },
+    onTouchCancel(touch) {
+      if (pressing === null || touch.id !== pressing.id) return
+      pressing = null
+      // The same cancel path the recognizer's failure rides: finalize without success.
+      wiring.handleEnd(eventOf(touch), false)
+      wiring.handleFinalize(eventOf(touch), false)
+    },
+  }
+}
+
+/**
+ * The tap boundary gate (R5 review r1 major 8): every PRESENT member must be a function —
+ * a malformed callback is a typed, named failure under the severity law (development throws;
+ * production reports and drops the member while the rest mount), never a raw crash inside
+ * the recognizer's dispatch.
+ */
+export function gateTapCallbackProps(
+  callbacks: {
+    readonly onTap?: TapCallbackInput
+    readonly onTapStart?: TapCallbackInput
+    readonly onTapCancel?: TapCallbackInput
+  },
+  gate: StyleValueGate = THROW_GATE,
+  componentId = '<Motion.View>',
+): { onTap?: TapCallback; onTapStart?: TapCallback; onTapCancel?: TapCallback } {
+  const accepted: { onTap?: TapCallback; onTapStart?: TapCallback; onTapCancel?: TapCallback } = {}
+  for (const key of ['onTap', 'onTapStart', 'onTapCancel'] as const) {
+    const value = callbacks[key]
+    if (value === undefined) continue
+    if (typeof value !== 'function') {
+      const error = new Error(
+        `${componentId}: "${key}" must be a function, received ${typeof value} — the tap callbacks are the ` +
+          'pinned (event, info) handlers (REQ-API-030).',
+      )
+      if (gate.severity === 'development') throw error
+      gate.report(error)
+      continue
+    }
+    accepted[key] = value
+  }
+  return accepted
+}
+
+/**
+ * The fixed-at-mount law for the tap surface (R5 review r1 major 8): the recognizer
+ * composition is mount-time structure (exactly the drag law) — a FIRST tap callback arriving
+ * after mount would be a silently dead gesture, the failure mode this package bans. Removal
+ * simply rests (the latest-ref dispatches nothing); re-addition on a mounted surface is live.
+ */
+export function gatePostMountTapArrival(
+  mountedTapRequested: boolean,
+  tapRequestedNow: boolean,
+  gate: StyleValueGate = THROW_GATE,
+  componentId: MotionComponentId,
+): void {
+  if (mountedTapRequested || !tapRequestedNow) return
+  const error = new Error(
+    `${componentId}: the tap surface is fixed at mount (REQ-API-030): onTap/onTapStart/onTapCancel arrived ` +
+      'after mount, and the recognizer composition cannot grow — remount the element with ' +
+      'the callbacks present.',
+  )
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+}

package/src/native/motion/transformOrder.ts

@@ -0,0 +1,38 @@
+// REQ-DRIVER-028 — the canonical transform composition order as PURE DATA. composeTransform.ts
+// remains the runtime owner (its worklets build their captured lookup tables from these arrays);
+// the data lives here, RN-import-free, so the transform-string parser (transformStringBinding.ts,
+// U5 W3) and any node-side consumer can derive membership/order without dragging
+// react-native-worklets into their import graph (the mappedKeys.ts precedent: data-only modules
+// for node-side classification). The order is motion-dom's `transformPropOrder`
+// (packages/motion-dom/src/render/utils/keys-transform.ts at the §B pin, motion-dom@12.42.2 /
+// checkout 61833240) restricted to the registry-shipped transform keys. The registry's
+// `perspective` key occupies the pinned `transformPerspective` slot — Motion's IN-TRANSFORM
+// perspective, which RN expresses as a `{perspective}` transform entry. A drift in either
+// authority is caught by composeTransform.test.ts (registry cross-check) and the conformance seam
+// canary (live motion-dom cross-check); this list is deliberately literal so the worklet captures
+// stay plain data (no cross-module calls on the UI runtime).
+export const NATIVE_TRANSFORM_ORDER = Object.freeze([
+  'perspective',
+  'x',
+  'y',
+  'scale',
+  'scaleX',
+  'scaleY',
+  'rotate',
+  'rotateX',
+  'rotateY',
+  'skewX',
+  'skewY',
+] as const)
+
+export type MappedTransformKey = (typeof NATIVE_TRANSFORM_ORDER)[number]
+
+// Angle-typed keys commit as RN degree strings; everything else commits numerically. Pinned by
+// test against the registry's `valueType: 'angle'` transform entries.
+export const TRANSFORM_ANGLE_KEYS = Object.freeze([
+  'rotate',
+  'rotateX',
+  'rotateY',
+  'skewX',
+  'skewY',
+] as const)

package/src/native/motion/transformStringBinding.ts

@@ -0,0 +1,200 @@
+// U5 W3 (REQ-API-026, packet contract 2) — the pinned-grammar transform-string parser. A bound
+// `transform` MotionValue<string> parses per set() into native transform components, which ride
+// the existing numeric bound-value-retarget lane (styleValueBinding.ts owns the severity
+// wrapping and the write). The grammar is EXACTLY the functions the pin's own buildTransform
+// can emit (motion-dom render/html/utils/build-transform.ts:23-91 at the pin, motion-dom@12.42.2
+// / checkout 61833240 — perspective, translate{X,Y,Z}, scale{,X,Y}, rotate{,X,Y,Z}, skew{,X,Y})
+// PLUS the user-authored template forms translate/translate3d (the pinned catalog's
+// Drag-external-handlers.tsx template emits `translate3d(${x}px, ${y}px, 0)`), restricted to
+// what native's component lane commits (NATIVE_TRANSFORM_ORDER, REQ-DRIVER-028): rotateZ, skew,
+// scaleZ/scale3d, rotate3d, matrix/matrix3d, and any non-zero z component are out of grammar and
+// REFUSE LOUD (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).
+// Units follow the pin's transformValueTypes (motion-dom value/types/maps/transform.ts:5-36):
+// lengths px, angles deg, scale unitless; a BARE number takes the key's default unit — the pin
+// routes shorthand numbers through getValueAsType with the same maps (build-transform.ts:50-57).
+// A multi-function sequence parses ONLY in native's canonical composition order: a
+// CSS-order-sensitive sequence is inexpressible in the component model, so it refuses loud
+// naming the order sensitivity — never a silent re-order.
+// This module is RN-import-free (the mappedKeys.ts precedent): the order data comes from
+// transformOrder.ts, so node-side consumers and plain unit tests never drag in
+// react-native-worklets.
+
+import { NATIVE_TRANSFORM_ORDER, type MappedTransformKey } from './transformOrder'
+
+/** The parsed components of a bound transform string — absent keys revert to their pin default. */
+export type TransformStringComponents = Partial<Record<MappedTransformKey, number>>
+
+// Canonical composition positions derive from the single data authority (NATIVE_TRANSFORM_ORDER).
+// translateZ's z sits between translateY and scale in the pin's transformPropOrder
+// (keys-transform.ts:4-22), so it orders at y + 0.5 — it writes no component (native has no z
+// channel) but still participates in the order-sensitivity check.
+const ORDER_POSITION: Readonly<Record<string, number>> = Object.freeze(
+  Object.fromEntries(NATIVE_TRANSFORM_ORDER.map((key, index) => [key, index])),
+)
+const Z_POSITION = ORDER_POSITION['y']! + 0.5
+
+/** Membership probe over the canonical component set (the plain-JS mirror of the worklet's). */
+export function isNativeTransformComponentKey(key: string): key is MappedTransformKey {
+  return ORDER_POSITION[key] !== undefined
+}
+
+type ArgumentKind = 'length' | 'angle' | 'scale'
+
+interface GrammarEntry {
+  readonly kind: ArgumentKind
+  readonly minArgs: number
+  readonly maxArgs: number
+  /** The native components the function writes, in canonical order. */
+  readonly targets: readonly MappedTransformKey[]
+  /** Argument index carrying a z component (must be the identity 0 — native has no z channel). */
+  readonly zArgument?: number
+}
+
+// The emit grammar the pin's buildTransform can produce PLUS translate/translate3d, restricted
+// to native's committed lane. The angle entries mirror TRANSFORM_ANGLE_KEYS (the registry
+// cross-check in composeTransform.test.ts pins that set); the CSS function names equal the
+// native key names for the whole angle family.
+const GRAMMAR: Readonly<Record<string, GrammarEntry>> = Object.freeze({
+  perspective: { kind: 'length', minArgs: 1, maxArgs: 1, targets: ['perspective'] },
+  translateX: { kind: 'length', minArgs: 1, maxArgs: 1, targets: ['x'] },
+  translateY: { kind: 'length', minArgs: 1, maxArgs: 1, targets: ['y'] },
+  // CSS: a missing translate y defaults to 0 — written explicitly so a later translateY/translate3d
+  // ordering check sees the occupied slot.
+  translate: { kind: 'length', minArgs: 1, maxArgs: 2, targets: ['x', 'y'] },
+  translateZ: { kind: 'length', minArgs: 1, maxArgs: 1, targets: [], zArgument: 0 },
+  translate3d: { kind: 'length', minArgs: 3, maxArgs: 3, targets: ['x', 'y'], zArgument: 2 },
+  scale: { kind: 'scale', minArgs: 1, maxArgs: 1, targets: ['scale'] },
+  scaleX: { kind: 'scale', minArgs: 1, maxArgs: 1, targets: ['scaleX'] },
+  scaleY: { kind: 'scale', minArgs: 1, maxArgs: 1, targets: ['scaleY'] },
+  rotate: { kind: 'angle', minArgs: 1, maxArgs: 1, targets: ['rotate'] },
+  rotateX: { kind: 'angle', minArgs: 1, maxArgs: 1, targets: ['rotateX'] },
+  rotateY: { kind: 'angle', minArgs: 1, maxArgs: 1, targets: ['rotateY'] },
+  skewX: { kind: 'angle', minArgs: 1, maxArgs: 1, targets: ['skewX'] },
+  skewY: { kind: 'angle', minArgs: 1, maxArgs: 1, targets: ['skewY'] },
+})
+
+const ARGUMENT_PATTERN = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))([A-Za-z%]*)$/
+
+function parseArgument(name: string, token: string, kind: ArgumentKind): number {
+  const match = ARGUMENT_PATTERN.exec(token)
+  if (match === null) {
+    throw new Error(`malformed transform string: '${token}' is not a number ('${name}')`)
+  }
+  const unit = match[2]!
+  const allowedUnits = kind === 'length' ? ['', 'px'] : kind === 'angle' ? ['', 'deg'] : ['']
+  if (!allowedUnits.includes(unit)) {
+    throw new Error(
+      `unit '${unit}' in transform function '${name}' is out of the pinned grammar — ` +
+        'lengths are px, angles deg, scale is unitless (motion-dom transformValueTypes, ' +
+        'value/types/maps/transform.ts:5-36).',
+    )
+  }
+  return Number(match[1])
+}
+
+/**
+ * Parse a bound transform string into native components. Throws a plain Error naming the
+ * unsupported form on ANY deviation from the pinned grammar — the caller (styleValueBinding)
+ * wraps it in the severity law naming the style key. 'none' parses to the identity (the pin
+ * buildTransform's all-default emission, build-transform.ts:86-88).
+ */
+export function parseTransformStringComponents(raw: string): TransformStringComponents {
+  const input = raw.trim()
+  if (input === '') throw new Error('malformed transform string: empty')
+  if (input === 'none') return {}
+  const components: Record<string, number> = {}
+  let maxPosition = -1
+  let previousName: string | null = null
+  let rest = input
+  while (rest.length > 0) {
+    const head = /^([A-Za-z][A-Za-z0-9]*)\s*\(/.exec(rest)
+    if (head === null) {
+      throw new Error(`malformed transform string near '${rest.slice(0, 24)}'`)
+    }
+    const name = head[1]!
+    const spec = GRAMMAR[name]
+    if (spec === undefined) {
+      throw new Error(
+        `transform function '${name}' is out of the pinned grammar native's component lane ` +
+          'commits (translate{X,Y,Z}/translate/translate3d, scale{,X,Y}, rotate{,X,Y}, ' +
+          'skew{X,Y}, perspective — NATIVE_TRANSFORM_ORDER, REQ-DRIVER-028).',
+      )
+    }
+    rest = rest.slice(head[0].length)
+    const close = rest.indexOf(')')
+    if (close === -1 || rest.slice(0, close).includes('(')) {
+      throw new Error(`malformed transform string: unclosed '${name}('`)
+    }
+    const inner = rest.slice(0, close)
+    rest = rest.slice(close + 1).trimStart()
+    const tokens = inner.trim() === '' ? [] : inner.split(',').map((token) => token.trim())
+    if (tokens.length < spec.minArgs || tokens.length > spec.maxArgs) {
+      const expected =
+        spec.minArgs === spec.maxArgs ? `${spec.minArgs}` : `${spec.minArgs}-${spec.maxArgs}`
+      throw new Error(
+        `transform function '${name}' takes ${expected} argument(s) in the pinned grammar, ` +
+          `got ${tokens.length}.`,
+      )
+    }
+    const values = tokens.map((token) => parseArgument(name, token, spec.kind))
+    if (spec.zArgument !== undefined && values[spec.zArgument] !== 0) {
+      throw new Error(
+        `transform function '${name}' carries a non-zero z (${String(values[spec.zArgument])}) — ` +
+          "native's component lane has no z channel (NATIVE_TRANSFORM_ORDER, REQ-DRIVER-028).",
+      )
+    }
+    // One authority per component, in canonical order only (REQ-DRIVER-028): a duplicate write
+    // or a backward step is a CSS-order-sensitive sequence the component model cannot express.
+    const positions =
+      spec.targets.length === 0 ? [Z_POSITION] : spec.targets.map((key) => ORDER_POSITION[key]!)
+    for (let index = 0; index < spec.targets.length; index++) {
+      const key = spec.targets[index]!
+      if (key in components) {
+        throw new Error(
+          `transform string writes component '${key}' twice ('${name}') — one authority per component.`,
+        )
+      }
+      if (positions[index]! <= maxPosition) {
+        throw new Error(
+          `transform string is order-sensitive: '${name}' must not follow '${previousName ?? ''}' — ` +
+            'native composes in canonical order (REQ-DRIVER-028) and cannot express ' +
+            'CSS-order-sensitive sequences.',
+        )
+      }
+      maxPosition = positions[index]!
+      // CSS translate's missing y is 0 — values[index] is always present for every other target.
+      components[key] = values[index] ?? 0
+    }
+    if (spec.targets.length === 0) {
+      if (Z_POSITION <= maxPosition) {
+        throw new Error(
+          `transform string is order-sensitive: '${name}' must not follow '${previousName ?? ''}' — ` +
+            'native composes in canonical order (REQ-DRIVER-028) and cannot express ' +
+            'CSS-order-sensitive sequences.',
+        )
+      }
+      maxPosition = Z_POSITION
+    }
+    previousName = name
+  }
+  return components
+}
+
+/**
+ * The per-set() write map: every canonical component, parsed value or pin default. The pin's
+ * imperative `element.style.transform = str` REPLACES the whole transform (build-styles.ts:52-66:
+ * a present `latestValues.transform` skips the component build entirely), so a component absent
+ * from the string reverts to identity — carried explicitly here (0; 1 for the scale family —
+ * build-transform.ts:44,47 `key.startsWith("scale") ? 1 : 0`). One multi-key
+ * bound-value-retarget write per set(), stateless.
+ */
+export function transformStringWriteMap(
+  components: TransformStringComponents,
+): Record<string, number> {
+  const map: Record<string, number> = {}
+  for (const key of NATIVE_TRANSFORM_ORDER) {
+    map[key] = components[key] ?? (key.startsWith('scale') ? 1 : 0)
+  }
+  return map
+}

package/src/native/motion/transformTemplateGate.ts

@@ -0,0 +1,45 @@
+// T17 (specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md floor 2): the transformTemplate mount gate.
+// The template executes on the UI runtime every frame, so the prop must be a FUNCTION and that
+// function must be a BRANDED worklet — `__workletHash` is the worklets serializer's only
+// discriminator (AGENTS.md), burned in by the 'worklet' babel directive in the app's pipeline.
+// An unbranded function would either silently per-frame cross back to JS (the pin's call happens
+// on the UI thread natively) or crash as a remote call mid-frame; both are refused at mount under
+// the severity law (development throws; production reports and treats the prop as absent — the
+// canonical composition paints). The brand check is NATIVE-ONLY: on web the same source compiles
+// without the worklets plugin and motion/react calls the plain function directly.
+
+import type { TransformTemplate } from '@unrulysystems/native-motion-core'
+import type { MotionComponentId, NativeSeverity } from './motionViewController'
+
+// The serializer's discriminator shape — a branded worklet carries its hash as an own property.
+type BrandedWorklet = TransformTemplate & { readonly __workletHash?: unknown }
+
+export function gateTransformTemplateProp(
+  value: unknown,
+  severity: NativeSeverity,
+  report: (error: Error) => void,
+  componentId: MotionComponentId,
+): TransformTemplate | undefined {
+  if (value === undefined) return undefined
+  const refusal = (): Error | null => {
+    if (typeof value !== 'function') {
+      return new Error(
+        `${componentId}: "transformTemplate" must be a function ` +
+          `(transform, generatedTransform) => string, received ${typeof value} (T17; pin MotionNodeOptions).`,
+      )
+    }
+    if ((value as BrandedWorklet).__workletHash === undefined) {
+      return new Error(
+        `${componentId}: "transformTemplate" must carry the 'worklet' directive — the template ` +
+          'executes on the UI runtime every frame (T17), so an un-workletized function cannot be ' +
+          "marshaled. Add 'worklet' as the function body's first statement.",
+      )
+    }
+    return null
+  }
+  const error = refusal()
+  if (error === null) return value as TransformTemplate
+  if (severity === 'development') throw error
+  report(error)
+  return undefined
+}