@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/shippedSurface.ts

@@ -0,0 +1,843 @@
+import {
+  isLengthTarget,
+  isPositionalLengthAxis,
+  POSITIONAL_LENGTH_AXES,
+  ORCHESTRATION_OPTION_KEYS,
+  TRANSITION_OPTION_KEYS,
+  UNIVERSAL_SUBSET,
+} from '@unrulysystems/native-motion-core'
+// The executable value matrix is verdict-shaped — it rides the internal-driver seam (review
+// ab7c5370fc5a), never the public root.
+import { executableLengthValueRefusal } from '@unrulysystems/native-motion-core/internal-driver'
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value
+  for (const key of Object.getOwnPropertyNames(value)) {
+    deepFreeze((value as Record<string, unknown>)[key])
+  }
+  return Object.freeze(value)
+}
+
+// The exported components and the parity classifier read this one data-only declaration. Keep it
+// RN-free: node-side tooling must be able to import the public-surface fact without loading the
+// native entry. Each vocabulary follows the props the component itself consumes or validates; host
+// props forwarded by View are intentionally not represented as Motion capabilities here.
+const VIEW_MOTION_PROP_NAMES = [
+  'initial',
+  'animate',
+  'exit',
+  'transition',
+  'style',
+  'layout',
+  'layoutId',
+  // R11 M2 (REQ-LAYOUT-022 / REQ-API-038): scroll-offset measurement root on the host.
+  'layoutScroll',
+  'onAnimationComplete',
+  'onLayoutAnimationComplete',
+  // U7e (REQ-LAYOUT-001 lineage): the layout-flight start callback.
+  'onLayoutAnimationStart',
+  'drag',
+  'dragConstraints',
+  'dragElastic',
+  'dragSnapPoints',
+  'dragPropagation',
+  // R15 D3 (REQ-API-043): imperative hub + element-originated start gate.
+  'dragControls',
+  'dragListener',
+  // R15 D4 (REQ-API-044): direction lock.
+  'dragDirectionLock',
+  'onDirectionLock',
+  // R15 D5 (REQ-API-045 / REQ-API-046): release physics + external drag values.
+  'dragMomentum',
+  'dragTransition',
+  'dragSnapToOrigin',
+  '_dragX',
+  '_dragY',
+  'onPanSessionStart',
+  'onPanStart',
+  'onPan',
+  'onPanEnd',
+  'onMeasureDragConstraints',
+  'onDragStart',
+  'onDrag',
+  'onDragEnd',
+  // The tap family (R5, REQ-API-030).
+  'onTap',
+  'onTapStart',
+  'onTapCancel',
+  // U7d (REQ-API-030 global form): the press observes the MotionRoot hub touch stream.
+  'globalTapTarget',
+  // The gesture-state pair (R6, REQ-API-031).
+  'whileTap',
+  'whileDrag',
+  // The variants surface (R7, REQ-API-032): the dictionary + the pinned visual-state switch;
+  // initial/animate/exit/whileTap/whileDrag additionally accept the label form under it.
+  'variants',
+  'inherit',
+  // T17 (specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md): the pin's per-frame transform template —
+  // a branded-worklet function on native (mount gate), parsed through the bounded core grammar.
+  'transformTemplate',
+  // T23 C (pin VisualElement.ts:574-586): the per-frame latest-values callback — one UI→JS
+  // marshal per frame while any committed value changes, primitive-only payload.
+  'onUpdate',
+  // T24 B1 (pin resolve-variants.ts:32-70): the dynamic-variants custom payload — the
+  // non-exit default for RESOLVER invocation; any value is legal (the pin types it `any`),
+  // and it never crosses to the UI runtime (JS-altitude resolution only).
+  'custom',
+] as const
+
+// MotionView destructures these in its component boundary and rejects other Motion capabilities
+// through gateDeferredViewProps. The container surfaces are deliberately separate: their rest-prop
+// gates reject any prop outside these exact lists, so they must never inherit View's vocabulary.
+const ANIMATE_PRESENCE_PROP_NAMES = [
+  'mode',
+  'initial',
+  'onExitComplete',
+  'onRest',
+  // Family-6: nested AnimatePresence joins parent exit (REQ-PRESENCE-010 / pin propagate).
+  'propagate',
+  // T24 B1: presence custom is consumed by exit variant resolution.
+  'custom',
+  // P2a (REQ-PRESENCE-023): portable pin presence options.
+  'anchorX',
+  'anchorY',
+  'presenceAffectsLayout',
+  'children',
+] as const
+
+const MOTION_ROOT_PROP_NAMES = ['children'] as const
+
+// REQ-API-035: MotionConfig is a provider, not a host element. nonce is accepted on the web
+// entry and fails loud on native (WEB-ONLY-BY-LAW); it still appears here so the surface
+// records the contracted prop name the classifier and both entries share.
+const MOTION_CONFIG_PROP_NAMES = [
+  'children',
+  'transition',
+  'reducedMotion',
+  'nonce',
+  'isStatic',
+  'skipAnimations',
+  // R15 D3 (REQ-API-043): page-point correction under transformed ancestors.
+  'transformPagePoint',
+] as const
+
+// REQ-API-036: LayoutGroup is a provider, not a host element. id/inherit mirror the pin.
+const LAYOUT_GROUP_PROP_NAMES = ['children', 'id', 'inherit'] as const
+
+// These literal domains are the node-safe reflection of the public engine contracts. The parity
+// classifier consumes this data rather than treating a prop name as proof that every value Motion
+// accepts is native-ready. Authorities: Transition/Easing in packages/core/src/component/types.ts
+// and packages/core/src/timing.ts; AnimatePresenceProps and gateDeferredPresenceProps in the
+// sibling AnimatePresence.tsx; target leaves in core's validateTarget/normalizeCapability path.
+// Property commands marshal only the values emitted by the component converters and driver's
+// `type` discriminator. `delay` ships here since T18-b (REQ-API-050): the property lane executes
+// it as the REQ-TIMING-004 elapsed-time rebase around the fold, so it is no longer a silent
+// no-op on this lane.
+const PROPERTY_TRANSITION_VALUE_DOMAINS = {
+  // U7a: `false` is the authored instant lane (the pin's makeAnimationInstant) — the property
+  // lane commits the final keyframe on the driver's next update tick, delay honored. The LAYOUT
+  // domain below keeps the spring/tween-only copy: those lanes refuse the instant lane loud
+  // (transitionGate), so their domain must not admit it.
+  type: { kind: 'enum', values: ['spring', 'tween', false] },
+  duration: { kind: 'number' },
+  delay: { kind: 'number' },
+  // R8 M2-B (REQ-API-033 law d): the property lane crosses toKeyframesConfig, so for a KEYFRAME-ARRAY
+  // target `ease` may be a single easing OR a PER-SEGMENT list of easings (one per segment). The
+  // `easing-list` domain admits both; the keyframe-count cross-field length law is enforced at the
+  // supplying boundary (keyframeTiming.ts), which no value domain can express.
+  // Family-2: Motion-named curve set (circ/back/anticipate) ships. Catalog `easings` is an alias of
+  // `ease` (same domain); converters normalize to `ease` (toKeyframesConfig / toTimingConfig).
+  ease: {
+    kind: 'easing-list',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  easings: {
+    kind: 'easing-list',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  easing: {
+    kind: 'easing-list',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  // R8 M2-B (REQ-API-033 law d): custom keyframe OFFSETS (0–1), one per keyframe — a keyframes-generator
+  // param. The layout builder never interpolates a keyframe array, so `times` is PROPERTY-lane only and
+  // is deliberately absent from the layout transition domain below (no option accepted but inert).
+  times: { kind: 'number-array' },
+  stiffness: { kind: 'number' },
+  damping: { kind: 'number' },
+  mass: { kind: 'number' },
+  bounce: { kind: 'number' },
+  visualDuration: { kind: 'number' },
+  // T21 (REQ-API-053): authored spring velocity — the physics-family seed, executed by core
+  // `resolveSpringGenerator` (an authored number replaces the live seed velocity on every start,
+  // the pin's animateMotionValue options spread). Executed by the LAYOUT lane too (r2 review
+  // major 2): the flight's sampled spring reads it from the same core generator config
+  // (`toSpringConfig` carries it), so it appears in the layout domain below. Only layoutId
+  // flights refuse it, with the rest of the spring-physics family (`transitionGate`).
+  velocity: { kind: 'number' },
+  // U7c (REQ-SPRING-014): the authored settle thresholds. PROPERTY lane: executed — toSpringConfig
+  // forwards them untransformed into the solver's settle condition (a spring; a tween accepts and
+  // IGNORES them, exactly like the pin — its tween/keyframes generators never read them).
+  // LAYOUT lane: executed — the flight's sampled spring builds from the same toSpringConfig (the
+  // velocity precedent). LayoutId: executed under an explicit type:'spring' flight, refused in an
+  // untyped physics bag (transitionGate). EXIT lane: refused loud (below) — the normalized 0→1
+  // progress factory would misapply value-units thresholds in progress units (the velocity
+  // recorded-divergence class).
+  restDelta: { kind: 'number' },
+  restSpeed: { kind: 'number' },
+  // T18-a (REQ-API-049): the repeat family. PROPERTY-lane only — a layout/layoutId flight animates
+  // one snapshot delta and never repeats it (packet L4), so these are deliberately absent from the
+  // layout transition domain below and `transitionGate` refuses them on those lanes.
+  repeat: { kind: 'number' },
+  repeatType: { kind: 'enum', values: ['loop', 'reverse', 'mirror'] },
+  repeatDelay: { kind: 'number' },
+  // U8 (REQ-API-059): `arc()` factory result. Identifiers (useMemo binding) and calls are valid.
+  path: { kind: 'path' },
+} as const
+
+// The property lane's executable option set (r5 major d6c3850af147): the gesture-state gate
+// refuses any option outside it — an option the lane never reads (`velocity`, pre-T21) must fail
+// loud, never ride along as a silent no-op (G-INV-8). RUNTIME-immutable (r6 major
+// c61e8a3b52df): a bare Set's ReadonlySet typing is compile-time-only (add/delete remain
+// callable and Object.freeze cannot seal Set internals), so this authority is the module's
+// frozen-membership shape — no mutation surface exists to legalize a refused option.
+/**
+ * Property-lane options the PRESENCE EXIT lane cannot execute (T18-a fix-up, review MAJOR).
+ *
+ * The exit lane drives a progress factory, not a sampled generator fold, so these options
+ * have no meaning there — an exit transition carrying one would ride along doing nothing,
+ * which is the exact silently-inert class G-INV-8 exists to refuse. It is enumerated
+ * EXPLICITLY rather than derived, because derivation is the defect: the exit lane's
+ * vocabulary gate read the property lane's record, so shipping the repeat family on the
+ * property lane silently widened a different lane's fail-closed gate. `delay` joined at
+ * T18-b for the same reason (REQ-API-050): the property lane executes the rebase, the exit
+ * progress factory never reads it. `velocity` joined at T21 (REQ-API-053) likewise: it is a
+ * per-value physics seed in value units/s, and the exit lane drives one NORMALIZED 0→1
+ * progress factory — a units-bearing velocity has no meaning on that curve, so it is refused
+ * loud (in the pin, exit runs as ordinary per-value animations where authored velocity works;
+ * refusing here is the same recorded-divergence class as `repeat`). U7c (REQ-SPRING-014):
+ * `restDelta`/`restSpeed` join for the same reason — value-units / units-per-second thresholds
+ * are meaningless on the normalized curve, and worse, the factory's progress springs build
+ * through `toSpringConfig`, so an accepted threshold would apply in PROGRESS units and could
+ * settle the 0→1 curve mid-flight (a wrong unmount, not just an inert ride-along).
+ * `shippedSurface.exitLane.test.ts` ("exit-lane vocabulary is a total, explicit
+ * partition of the property lane") keeps this
+ * partition exhaustive, so a future property option cannot slip through unclassified.
+ *
+ * This is a recorded DIVERGENCE from the pin, not a match: the pinned Motion runs `exit` as an
+ * ordinary animation (`ExitAnimationFeature` awaits `setActive("exit", …)`), so `repeat` works
+ * there and an endless exit repeat means the element never unmounts. Executing it here is a
+ * scoped successor rung; refusing loud is the honest interim.
+ */
+export const EXIT_LANE_INEXECUTABLE_OPTIONS = Object.freeze([
+  'repeat',
+  'repeatType',
+  'repeatDelay',
+  'delay',
+  'velocity',
+  // U7c (REQ-SPRING-014): value-units settle thresholds — refused on the normalized 0→1 exit
+  // progress factory (see the header above).
+  'restDelta',
+  'restSpeed',
+  // U8 (REQ-API-059): the parametric path channel is driven by the element's own transition
+  // through the driver (progress 0→1000); the exit lane's normalized 0→1 progress factory has
+  // no path channel, so `path` would ride along inert — refused loud like the repeat family.
+  'path',
+] as const)
+
+const EXIT_LANE_INEXECUTABLE_SET: ReadonlySet<string> = new Set(EXIT_LANE_INEXECUTABLE_OPTIONS)
+
+/**
+ * The options the exit lane's progress factory DOES execute — enumerated, not derived. Together
+ * with `EXIT_LANE_INEXECUTABLE_OPTIONS` this partitions the property lane's option record exactly;
+ * `shippedSurface.exitLane.test.ts` asserts that totality, so adding a property-lane option without deciding
+ * what the exit lane does with it fails the gate instead of silently defaulting to "executable".
+ * That default is what shipped the T18-a regression.
+ */
+export const EXIT_LANE_EXECUTABLE_OPTIONS = Object.freeze([
+  'type',
+  'duration',
+  'ease',
+  'easings',
+  'easing',
+  'times',
+  'stiffness',
+  'damping',
+  'mass',
+  'bounce',
+  'visualDuration',
+] as const)
+
+const EXIT_LANE_EXECUTABLE_SET: ReadonlySet<string> = new Set(EXIT_LANE_EXECUTABLE_OPTIONS)
+
+export function exitLaneInexecutableOption(option: string): boolean {
+  return EXIT_LANE_INEXECUTABLE_SET.has(option)
+}
+
+/** True when the exit lane can actually run this option. Unknown options are NOT executable. */
+export function exitLaneExecutableOption(option: string): boolean {
+  return EXIT_LANE_EXECUTABLE_SET.has(option)
+}
+
+/** The property-lane option names, for the totality floor. */
+export const PROPERTY_TRANSITION_OPTION_NAMES: readonly string[] = Object.freeze(
+  Object.keys(PROPERTY_TRANSITION_VALUE_DOMAINS),
+)
+
+const PROPERTY_TRANSITION_OPTION_SET = new Set(Object.keys(PROPERTY_TRANSITION_VALUE_DOMAINS))
+export const NATIVE_PROPERTY_TRANSITION_OPTIONS = Object.freeze({
+  options: Object.freeze(Object.keys(PROPERTY_TRANSITION_VALUE_DOMAINS)) as readonly string[],
+  has(value: string): boolean {
+    // Closured Set membership (r6 minor 9b752a446d91): object-property lookup answers true
+    // for prototype members (toString, constructor) — a membership authority must not.
+    return PROPERTY_TRANSITION_OPTION_SET.has(value)
+  },
+})
+
+// Reanimated's layout transition builder consumes the authored delay itself, in addition to the
+// converter-owned options above. Since the T21 r1 fix-up the layout flight EXECUTES authored
+// `velocity` (review r2 major 2): the flight's sampled spring channels build from the core
+// generator config that `toSpringConfig` carries it into (REQ-SPRING-007's authored-override
+// law — the duration family zeroes it like any seed), so `velocity` belongs to this domain;
+// only layoutId flights refuse it, with the rest of the spring-physics family (transitionGate).
+// The layout builder interpolates a single from→to (never a keyframe array), so it takes a
+// SINGLE `ease` only and does NOT consume the keyframe-timing params `times` (R8 M2-B) — both
+// are property-lane keyframe-array params, absent here (no option accepted but inert). This is
+// why the layout domain is NOT the full transition vocabulary: it is the scalar options +
+// `delay`, minus the keyframe-only `times`.
+const LAYOUT_TRANSITION_VALUE_DOMAINS = {
+  // NOT the property domain's `type`: U7a's authored instant lane (`type: false`) is
+  // property-only — the layout/layoutId lanes refuse it loud (transitionGate), so this domain
+  // keeps the closed spring/tween vocabulary.
+  type: { kind: 'enum', values: ['spring', 'tween'] },
+  duration: PROPERTY_TRANSITION_VALUE_DOMAINS.duration,
+  ease: {
+    kind: 'easing',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  // Family-2: scalar layout alias of ease (per-segment lists remain property-lane only —
+  // easing-list domain is not used here, so a list shape is domain-invalid on layout).
+  easings: {
+    kind: 'easing',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  easing: {
+    kind: 'easing',
+    values: [
+      'linear',
+      'easeIn',
+      'easeOut',
+      'easeInOut',
+      'circIn',
+      'circOut',
+      'circInOut',
+      'backIn',
+      'backOut',
+      'backInOut',
+      'anticipate',
+    ],
+  },
+  stiffness: PROPERTY_TRANSITION_VALUE_DOMAINS.stiffness,
+  damping: PROPERTY_TRANSITION_VALUE_DOMAINS.damping,
+  mass: PROPERTY_TRANSITION_VALUE_DOMAINS.mass,
+  bounce: PROPERTY_TRANSITION_VALUE_DOMAINS.bounce,
+  visualDuration: PROPERTY_TRANSITION_VALUE_DOMAINS.visualDuration,
+  velocity: PROPERTY_TRANSITION_VALUE_DOMAINS.velocity,
+  // U7c (REQ-SPRING-014): the layout flight's sampled spring builds through toSpringConfig, which
+  // carries the authored settle thresholds — executed here exactly like velocity.
+  restDelta: PROPERTY_TRANSITION_VALUE_DOMAINS.restDelta,
+  restSpeed: PROPERTY_TRANSITION_VALUE_DOMAINS.restSpeed,
+  delay: PROPERTY_TRANSITION_VALUE_DOMAINS.delay,
+} as const
+
+export type NativeMountTargetValueKind = 'number' | 'color' | 'discrete'
+
+// This is the data-only mirror of MotionView's actual mount split: colors are projected through
+// the color lane, discrete keywords (T23 B) through the keyword-step lane, and every other target
+// key reaches the numeric worklet driver. The controller calls this same function before
+// registration, so catalog validation cannot be more permissive than native mounting (notably,
+// core-valid px/deg/rad strings still fail the numeric lane).
+export function nativeMountTargetValueKind(key: string): NativeMountTargetValueKind {
+  const valueType = UNIVERSAL_SUBSET.get(key)?.valueType
+  if (valueType === 'rgba') return 'color'
+  if (valueType === 'discrete') return 'discrete'
+  return 'number'
+}
+
+// The positional keys whose length STRINGS the native numeric lane can measure-resolve
+// (REQ-VALUETYPE-013): %/auto/pin-simple-calc/px execute only here (resolveLengthToPx is
+// axis-scoped). The ONE authority is core's executable value matrix (review 91d41675d511) —
+// the variants gate, the gesture-state gate, and the style-base gate all read it, so no
+// boundary admits a string the lane cannot drive.
+export const NATIVE_MEASURE_LENGTH_KEYS = Object.freeze({
+  keys: POSITIONAL_LENGTH_AXES as readonly string[],
+  has(key: string): boolean {
+    return isPositionalLengthAxis(key)
+  },
+})
+export function isNativeMeasureLengthKey(key: string): boolean {
+  return isPositionalLengthAxis(key)
+}
+
+// The strict DRIVABILITY predicate over core's executable matrix (review 91d41675d511): the
+// numeric lane drives numbers, or length STRINGS the matrix executes — scalar or every keyframe
+// element (null-first is the legal from-current marker). The walker alone returns null for
+// non-length strings (the value-type lane owns those refusals); the gates need the strict
+// either/or, so non-length strings read as undrivable here.
+export function isNativeExecutableLengthValue(key: string, value: unknown): boolean {
+  if (typeof value === 'number') return true
+  if (Array.isArray(value)) {
+    return value.every(
+      (element, index) =>
+        (element === null && index === 0) ||
+        typeof element === 'number' ||
+        (typeof element === 'string' &&
+          isLengthTarget(element) &&
+          executableLengthValueRefusal(key, element) === null),
+    )
+  }
+  return (
+    typeof value === 'string' &&
+    isLengthTarget(value) &&
+    executableLengthValueRefusal(key, value) === null
+  )
+}
+
+const COMPONENT_VALUE_DOMAINS = {
+  View: {
+    initial: { kind: 'target-or-false' },
+    animate: { kind: 'target-or-boolean' },
+    exit: { kind: 'target' },
+    transition: { kind: 'transition' },
+    // These domains reflect the native mount boundaries rather than merely documenting prop names:
+    // layout/layoutId are gated before registration, drag is resolved through core, and style's
+    // transform leaves share core's target normalizer with the animated target lane.
+    style: { kind: 'style' },
+    layout: { kind: 'layout' },
+    layoutId: { kind: 'layout-id' },
+    layoutScroll: { kind: 'boolean' },
+    onAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationStart: { kind: 'callback' },
+    drag: { kind: 'drag-config' },
+    dragConstraints: { kind: 'drag-config' },
+    dragElastic: { kind: 'drag-config' },
+    dragSnapPoints: { kind: 'drag-config' },
+    dragPropagation: { kind: 'drag-config' },
+    dragControls: { kind: 'drag-config' },
+    dragListener: { kind: 'drag-config' },
+    // R15 D4 (REQ-API-044)
+    dragDirectionLock: { kind: 'drag-config' },
+    onDirectionLock: { kind: 'callback' },
+    dragMomentum: { kind: 'drag-config' },
+    dragTransition: { kind: 'drag-config' },
+    dragSnapToOrigin: { kind: 'drag-config' },
+    _dragX: { kind: 'drag-config' },
+    _dragY: { kind: 'drag-config' },
+    onPanSessionStart: { kind: 'callback' },
+    onPanStart: { kind: 'callback' },
+    onPan: { kind: 'callback' },
+    onPanEnd: { kind: 'callback' },
+    onMeasureDragConstraints: { kind: 'callback' },
+    onDragStart: { kind: 'callback' },
+    onDrag: { kind: 'callback' },
+    onDragEnd: { kind: 'callback' },
+    onTap: { kind: 'callback' },
+    onTapStart: { kind: 'callback' },
+    onTapCancel: { kind: 'callback' },
+    // U7d (REQ-API-030 global form): the root-observing press scope flag.
+    globalTapTarget: { kind: 'boolean' },
+    whileTap: { kind: 'target' },
+    whileDrag: { kind: 'target' },
+    // R7 (REQ-API-032): the dictionary validates per entry through the SAME target/transition
+    // boundaries the animate lane rides; label-form VALUES on the target props re-derive in
+    // the parity ledger pass (the R7 M4 milestone owns the classifier's label disposition).
+    variants: { kind: 'variants-dictionary' },
+    inherit: { kind: 'boolean' },
+  },
+  // REQ-API-034 law (b): Text executes the exact same Motion vocabulary through the shared host
+  // seam. Its RN-only text props are ordinary forwarded host props, not Motion capabilities.
+  Text: {
+    initial: { kind: 'target-or-false' },
+    animate: { kind: 'target-or-boolean' },
+    exit: { kind: 'target' },
+    transition: { kind: 'transition' },
+    style: { kind: 'style' },
+    layout: { kind: 'layout' },
+    layoutId: { kind: 'layout-id' },
+    layoutScroll: { kind: 'boolean' },
+    onAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationStart: { kind: 'callback' },
+    drag: { kind: 'drag-config' },
+    dragConstraints: { kind: 'drag-config' },
+    dragElastic: { kind: 'drag-config' },
+    dragSnapPoints: { kind: 'drag-config' },
+    dragPropagation: { kind: 'drag-config' },
+    dragControls: { kind: 'drag-config' },
+    dragListener: { kind: 'drag-config' },
+    dragDirectionLock: { kind: 'drag-config' },
+    onDirectionLock: { kind: 'callback' },
+    dragMomentum: { kind: 'drag-config' },
+    dragTransition: { kind: 'drag-config' },
+    dragSnapToOrigin: { kind: 'drag-config' },
+    _dragX: { kind: 'drag-config' },
+    _dragY: { kind: 'drag-config' },
+    onPanSessionStart: { kind: 'callback' },
+    onPanStart: { kind: 'callback' },
+    onPan: { kind: 'callback' },
+    onPanEnd: { kind: 'callback' },
+    onMeasureDragConstraints: { kind: 'callback' },
+    onDragStart: { kind: 'callback' },
+    onDrag: { kind: 'callback' },
+    onDragEnd: { kind: 'callback' },
+    onTap: { kind: 'callback' },
+    onTapStart: { kind: 'callback' },
+    onTapCancel: { kind: 'callback' },
+    // U7d (REQ-API-030 global form): the root-observing press scope flag.
+    globalTapTarget: { kind: 'boolean' },
+    whileTap: { kind: 'target' },
+    whileDrag: { kind: 'target' },
+    variants: { kind: 'variants-dictionary' },
+    inherit: { kind: 'boolean' },
+  },
+  // REQ-API-034 law (c): Image is the same Motion vocabulary on a childless host. Element-
+  // specific `source` is a host prop, not a Motion capability row.
+  Image: {
+    initial: { kind: 'target-or-false' },
+    animate: { kind: 'target-or-boolean' },
+    exit: { kind: 'target' },
+    transition: { kind: 'transition' },
+    style: { kind: 'style' },
+    layout: { kind: 'layout' },
+    layoutId: { kind: 'layout-id' },
+    layoutScroll: { kind: 'boolean' },
+    onAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationComplete: { kind: 'callback' },
+    onLayoutAnimationStart: { kind: 'callback' },
+    drag: { kind: 'drag-config' },
+    dragConstraints: { kind: 'drag-config' },
+    dragElastic: { kind: 'drag-config' },
+    dragSnapPoints: { kind: 'drag-config' },
+    dragPropagation: { kind: 'drag-config' },
+    dragControls: { kind: 'drag-config' },
+    dragListener: { kind: 'drag-config' },
+    dragDirectionLock: { kind: 'drag-config' },
+    onDirectionLock: { kind: 'callback' },
+    dragMomentum: { kind: 'drag-config' },
+    dragTransition: { kind: 'drag-config' },
+    dragSnapToOrigin: { kind: 'drag-config' },
+    _dragX: { kind: 'drag-config' },
+    _dragY: { kind: 'drag-config' },
+    onPanSessionStart: { kind: 'callback' },
+    onPanStart: { kind: 'callback' },
+    onPan: { kind: 'callback' },
+    onPanEnd: { kind: 'callback' },
+    onMeasureDragConstraints: { kind: 'callback' },
+    onDragStart: { kind: 'callback' },
+    onDrag: { kind: 'callback' },
+    onDragEnd: { kind: 'callback' },
+    onTap: { kind: 'callback' },
+    onTapStart: { kind: 'callback' },
+    onTapCancel: { kind: 'callback' },
+    // U7d (REQ-API-030 global form): the root-observing press scope flag.
+    globalTapTarget: { kind: 'boolean' },
+    whileTap: { kind: 'target' },
+    whileDrag: { kind: 'target' },
+    variants: { kind: 'variants-dictionary' },
+    inherit: { kind: 'boolean' },
+  },
+  AnimatePresence: {
+    // T24 P: native presence composes the retained child's last parent-relative rect; web forwards
+    // the same mode to motion/react's PopChild.
+    mode: { kind: 'enum', values: ['sync', 'wait', 'popLayout'] },
+    initial: { kind: 'boolean' },
+    onExitComplete: { kind: 'callback' },
+    // R13 V4: pin-catalog alias of onExitComplete (same callback lifecycle).
+    onRest: { kind: 'callback' },
+    // Family-6: nested AP joins parent exit (REQ-PRESENCE-010).
+    propagate: { kind: 'boolean' },
+  },
+  // REQ-API-035: provider vocabulary (not a Motion host element).
+  MotionConfig: {
+    transition: { kind: 'transition' },
+    reducedMotion: { kind: 'enum', values: ['always', 'never', 'user'] },
+    nonce: { kind: 'string' },
+    isStatic: { kind: 'boolean' },
+    skipAnimations: { kind: 'boolean' },
+    // R15 D3 (REQ-API-043): function domain — accepted by name; runtime gate owns the shape.
+    transformPagePoint: { kind: 'callback' },
+  },
+  // REQ-API-036: LayoutGroup provider vocabulary. inherit is true | false | "id" — the
+  // classifier has no mixed boolean/string enum domain; the prop is accepted by name and the
+  // runtime gate owns the closed vocabulary (same posture as provider props without a domain).
+  LayoutGroup: {
+    id: { kind: 'string' },
+  },
+} as const
+
+const NATIVE_TYPE_EXPORTS = [
+  'MotionTargetProps',
+  'Target',
+  'Transition',
+  'TransitionType',
+  'DragInfo',
+  // R5 (REQ-API-030): the tap payload types ship on both entries.
+  'TapInfo',
+  'TapCallback',
+  // R15 D3 (REQ-API-043): imperative hub types (seal review r10 major — classifier authority).
+  'DragControlOptions',
+  'DragControlsHandle',
+  'DragControls',
+  'ImageProps',
+  'TextProps',
+  'ViewProps',
+  'MotionRootProps',
+  'MotionConfigProps',
+  'MotionConfigTransition',
+  'ReducedMotionConfig',
+  'LayoutGroupProps',
+  'LayoutGroupInherit',
+  'MotionValue',
+  // R11 M1 (REQ-API-037)
+  'ScrollMotionValues',
+  'UseScrollOptions',
+  'ArcOptions',
+] as const
+
+// MotionView forwards ordinary RN host props, but its gate rejects this finite oracle vocabulary
+// plus these semantic prefixes. Keeping the predicate with the shipped surface lets node tooling
+// distinguish a forwarded host prop (for example onClick in a web sandbox) from a known, rejected
+// Motion capability without recreating a broad classifier-side name heuristic.
+const VIEW_DEFERRED_MOTION_PROP_NAMES = [
+  'animate',
+  'exit',
+  'variants',
+  'initial',
+  'style',
+  'values',
+  'transition',
+  'transformTemplate',
+  'custom',
+  'inherit',
+  'onBeforeLayoutMeasure',
+  'onAnimationStart',
+  'onAnimationComplete',
+  'onUpdate',
+  'onDragStart',
+  'onDrag',
+  'onDragEnd',
+  'onMeasureDragConstraints',
+  'onDirectionLock',
+  'onDragTransitionEnd',
+  '_dragX',
+  '_dragY',
+  'onHoverStart',
+  'onHoverEnd',
+  'onViewportEnter',
+  'onViewportLeave',
+  // U7d: globalTapTarget is SHIPPED (View surface) but stays in this vocabulary list — the
+  // predicate is pinned-vocabulary, not shipped-ness (the oracle canary; animate/transition
+  // precedents). Shipped members are destructured before the deferred gate sees them.
+  'globalTapTarget',
+  'propagate',
+  'ignoreStrict',
+  'viewport',
+] as const
+
+const viewDeferredMotionPropNames = new Set<string>(VIEW_DEFERRED_MOTION_PROP_NAMES)
+
+export function isNativeViewMotionProp(key: string): boolean {
+  // MOTION VOCABULARY, not shipped-ness: shipped members (drag/onTap/whileTap/whileDrag/…)
+  // are destructured out of `rest` by the component and never reach the deferred gate — this
+  // predicate must keep matching the pinned isValidMotionProp shape (the oracle canary).
+  return (
+    key.startsWith('while') ||
+    (key.startsWith('drag') && key !== 'draggable') ||
+    key.startsWith('layout') ||
+    key.startsWith('onTap') ||
+    key.startsWith('onPan') ||
+    (key.startsWith('onLayout') && key !== 'onLayout') ||
+    viewDeferredMotionPropNames.has(key)
+  )
+}
+
+function immutableMembership(values: readonly string[]) {
+  const members = new Set(values)
+  return Object.freeze({
+    size: members.size,
+    has(value: string): boolean {
+      return members.has(value)
+    },
+  })
+}
+
+function immutableComponentProps(propsByComponent: Readonly<Record<string, readonly string[]>>) {
+  const memberships = new Map(
+    Object.entries(propsByComponent).map(([component, props]) => [
+      component,
+      immutableMembership(props),
+    ]),
+  )
+  return Object.freeze({
+    get(component: string): ReturnType<typeof immutableMembership> | undefined {
+      return memberships.get(component)
+    },
+  })
+}
+
+function immutableValueDomains(
+  domainsByComponent: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+) {
+  const domains = new Map(
+    Object.entries(domainsByComponent).map(([component, props]) => [
+      component,
+      new Map(Object.entries(props).map(([prop, domain]) => [prop, deepFreeze(domain)])),
+    ]),
+  )
+  return Object.freeze({
+    get(component: string, prop: string): unknown {
+      return domains.get(component)?.get(prop)
+    },
+  })
+}
+
+export const NATIVE_SHIPPED_SURFACE = deepFreeze({
+  // The catalog's `motion`/`m` factories normalize to the native public `View` export. Keep this
+  // mapping with the engine surface so the parity classifier never maintains a private whitelist.
+  motionFactoryImports: immutableMembership(['motion', 'm']),
+  viewMotionPropNames: VIEW_MOTION_PROP_NAMES,
+  viewMotionProps: immutableMembership(VIEW_MOTION_PROP_NAMES),
+  typeExports: immutableMembership(NATIVE_TYPE_EXPORTS),
+  componentProps: immutableComponentProps({
+    View: VIEW_MOTION_PROP_NAMES,
+    Text: VIEW_MOTION_PROP_NAMES,
+    Image: VIEW_MOTION_PROP_NAMES,
+    AnimatePresence: ANIMATE_PRESENCE_PROP_NAMES,
+    MotionRoot: MOTION_ROOT_PROP_NAMES,
+    MotionConfig: MOTION_CONFIG_PROP_NAMES,
+    LayoutGroup: LAYOUT_GROUP_PROP_NAMES,
+  }),
+  transitionOptions: immutableMembership(TRANSITION_OPTION_KEYS),
+  // T21 (REQ-API-053): the tree-lane family — shipped at the transition ROOT only, consumed
+  // by the variant tree's start scheduling (never a driver/layout option; map entries and
+  // layout bags refuse). Single-sourced from core so the classifier tracks the engine.
+  orchestrationTransitionOptions: immutableMembership(ORCHESTRATION_OPTION_KEYS),
+  propertyTransitionValueDomains: PROPERTY_TRANSITION_VALUE_DOMAINS,
+  layoutTransitionValueDomains: LAYOUT_TRANSITION_VALUE_DOMAINS,
+  componentValueDomains: immutableValueDomains(COMPONENT_VALUE_DOMAINS),
+  components: immutableMembership([
+    'View',
+    'Text',
+    'Image',
+    'AnimatePresence',
+    'MotionRoot',
+    'MotionConfig',
+    'LayoutGroup',
+  ]),
+  // R4 shipped the public value channel (REQ-API-025..027); R11 M1 adds useScroll (REQ-API-037);
+  // R12 M1 adds useAnimate + free-function animate (REQ-API-039); R13 M1 adds useCycle
+  // (REQ-API-040); T21 ships stagger from both entries (REQ-API-053); T23 A ships mix from
+  // both entries. U5 ships useMotionTemplate (REQ-API-025). U7a adds useReducedMotion (the
+  // pin's mount-time snapshot). U7b adds useInstantTransition + disableInstantTransitions (the
+  // global instant window). U7i adds useViewportScroll (deprecated zero-arg alias of useScroll).
+  // Deferred: useAnimation, useElementScroll (the other deprecated alias).
+  hooks: immutableMembership([
+    'useIsPresent',
+    'usePresence',
+    'useMotionValue',
+    'useMotionValueEvent',
+    'useMotionTemplate',
+    'useScroll',
+    // U7i (REQ-API-037(e)): deprecated zero-arg alias of useScroll().
+    'useViewportScroll',
+    'useSpring',
+    'useTransform',
+    'useVelocity',
+    'useAnimate',
+    'useCycle',
+    'useReducedMotion',
+    // U7b: the global instant window — the opener hook plus the pin's sibling flag-clear (one
+    // pin surface, use-instant-transition.ts:9-45).
+    'useInstantTransition',
+    'disableInstantTransitions',
+    // R15 D3 (REQ-API-043): imperative drag hub (hook + constructible class).
+    'useDragControls',
+    'DragControls',
+    // Free-function export — membership here is the parity classifier's runtime-import authority
+    // (signals.ts treats non-use* names as import.*; hooks.has gates both).
+    'animate',
+    // T24 W: public page-domain modulo helper, shared with the native entry.
+    'wrap',
+    // T21 (REQ-API-053): the public stagger() cascade factory, shipped by both entries.
+    'stagger',
+    // T23 A: the public mix() utility — one core implementation on both entries.
+    'mix',
+    // U7g (REQ-LAYOUT-024): user scale-corrector registration (web is the raw pin).
+    'addScaleCorrector',
+    // U7j (REQ-API-058): read-only JS-frame clock. The `frame` scheduler stays residual.
+    'frameData',
+    // U8 (REQ-API-059): parametric arc path factory.
+    'arc',
+  ]),
+})