@unrulysystems/native-motion-web 0.1.0-alpha.0

package/src/View.tsx

@@ -0,0 +1,1356 @@
+'use client'
+// The shim's host wrappers: View, Text, and Image are shipped (REQ-API-034 closed set).
+// Thin bindings of the canonical public surface onto motion.div, Text's selected motion.p/span
+// hosts, and Image's motion.img (REQ-WEB-011: the
+// web engine IS motion/react; this file adds normalization and validation, never animation
+// semantics). Targets are validated with core's validateTarget so an invalid target behaves
+// IDENTICALLY on web and native (one API, one behavior); motion props route through the
+// disposition pipeline; unrecognized keys flow to the DOM as plain attributes (they are React
+// infra, not motion props — the typed surface rejects motion-prop typos at compile time).
+import {
+  describeValue,
+  hostCapabilities,
+  resolveInitialOverlay,
+  resolveDragConfig,
+  resolvedDragAxes,
+  targetShapeRefusal,
+  validateTargetSnapshot,
+  validateVariantEntrySnapshot,
+  variantsShapeRefusal,
+  type ResolvedDragConfig,
+  type Target,
+  type TransformTemplate,
+  type Transition,
+  type TapCallback,
+  type VariantEntry,
+  type VariantResolver,
+  type VariantLabels,
+  type VariantsDictionary,
+} from '@unrulysystems/native-motion-core'
+import {
+  initialTargetRefusal,
+  keyframeTransitionRefusal,
+  resolveTransitionForKey,
+} from '@unrulysystems/native-motion-core/internal-driver'
+import {
+  isValidMotionProp,
+  motion,
+  type DOMMotionComponents,
+  type MotionProps,
+  type MotionStyle,
+} from 'motion/react'
+import type {
+  MotionNodeFocusHandlers,
+  MotionNodeHoverHandlers,
+  Target as PinTarget,
+} from 'motion-dom'
+import {
+  createContext,
+  createElement,
+  forwardRef,
+  useContext,
+  useRef,
+  type ComponentRef,
+  type ForwardRefExoticComponent,
+  type HTMLAttributes,
+  type PropsWithoutRef,
+  type ReactNode,
+  type Ref,
+  type RefAttributes,
+} from 'react'
+import { DISPOSITIONS } from './disposition'
+import { MotionWebRejectionError } from './errors'
+import { ambientMode } from './mode'
+import {
+  captureLabelFormWithSeverity,
+  normalizeComponentProps,
+  type MotionComponentId,
+  type NormalizeOptions,
+} from './normalize'
+import { snapPointsToDragTransition } from './snap'
+import { mapWebTransitionAliases, type WebTransition } from './webTransition'
+
+function transitionForProperty(
+  transition: Transition | undefined,
+  property: string,
+): Transition | undefined {
+  return transition === undefined ? undefined : resolveTransitionForKey(transition, property)
+}
+
+// The DOM drag-and-drop handlers (onDrag/onDragStart/onDragEnd) are Omitted so the drag family
+// carries Motion's (event, info) callback shape identically to the native entry — motion/react
+// shadows the same DOM handlers on motion.div for exactly this reason (the type-identity gate
+// requires the drag callbacks to be structurally equal cross-engine).
+type IntrinsicWebTargetMembers = Pick<
+  PinTarget,
+  'filter' | 'clipPath' | 'boxShadow' | 'backgroundImage'
+>
+type WebTarget = Target & IntrinsicWebTargetMembers
+type WebVariantEntry = WebTarget & { readonly transition?: WebTransition }
+type WebVariantsDictionary = Readonly<Record<string, WebVariantEntry | VariantResolver>>
+
+interface ViewBaseProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'style' | 'onDrag' | 'onDragStart' | 'onDragEnd' | 'onAnimationStart'
+> {
+  // The universal motion props carry explicit `| undefined` so the cross-entry assignability
+  // gate (type-identity.assert.ts) holds under exactOptionalPropertyTypes: the native entry's
+  // props tolerate explicit undefined (React pass-through), so the web props must too.
+  // R7 (REQ-API-032): the LABEL form is part of the public type on both entries (the identity
+  // gate binds the widening) and EXECUTES here — motion/react owns resolution and propagation;
+  // the boundary below gates validity at core depth (M3 flipped the deferred posture).
+  readonly initial?: WebTarget | VariantLabels | false | undefined
+  readonly animate?: WebTarget | VariantLabels | boolean | undefined
+  readonly exit?: WebTarget | VariantLabels | undefined
+  readonly variants?: VariantsDictionary | WebVariantsDictionary | undefined
+  readonly inherit?: boolean | undefined
+  readonly transition?: WebTransition | undefined
+  // L4 (specs/SPEC-LAYOUT.md): layout projection, DECLARED and forwarded to real
+  // motion/react — the web engine does the projection. Entry shapes are gated below under the
+  // severity law; malformed values never reach motion as raw TypeErrors.
+  readonly layout?: boolean | 'position' | 'size' | 'preserve-aspect'
+  readonly layoutId?: string
+  // R11 M2 (REQ-LAYOUT-022 / REQ-API-038): scroll-offset measurement root — forwarded to the
+  // pin's projection node; web never re-implements projection.
+  readonly layoutScroll?: boolean
+  // motion's own style law (r15 d32a7c1e94b6): per-key MotionValue bindings are part of the
+  // supported public surface — CSSProperties rejected them and made universal code web-fail.
+  readonly style?: MotionStyle
+  // The tap family (R5, REQ-API-030): core's shared TapCallback — identical on both entries
+  // (the DragInfo precedent); PASSed through to motion's own recognizers (disposition table).
+  readonly onTap?: TapCallback
+  readonly onTapStart?: TapCallback
+  readonly onTapCancel?: TapCallback
+  // The gesture-state pair (R6, REQ-API-031; R7 REQ-API-032 adds the label form) —
+  // structurally identical to the native entry (the type-identity gate binds it). Labels
+  // validate string-only at the normalize boundary and execute through motion's own
+  // variants machinery.
+  readonly whileTap?:
+    | (WebTarget & { readonly transition?: WebTransition })
+    | VariantLabels
+    | undefined
+  readonly whileDrag?:
+    | (WebTarget & { readonly transition?: WebTransition })
+    | VariantLabels
+    | undefined
+  readonly whileHover?: MotionNodeHoverHandlers['whileHover'] | undefined
+  readonly whileFocus?: MotionNodeFocusHandlers['whileFocus'] | undefined
+  readonly onHoverStart?: (...args: unknown[]) => void
+  readonly onHoverEnd?: (...args: unknown[]) => void
+  readonly onAnimationComplete?: ((definition: unknown) => void) | undefined
+  readonly onLayoutAnimationComplete?: (() => void) | undefined
+  // T23 C (specs/T23-MIX-DISCRETE-BUILD-PACKET.md): per-frame latest-values callback — DECLARED
+  // and forwarded to real motion/react, which owns the frame loop and payload on web. The payload
+  // type is the shared cross-entry shape (string | number leaves keyed by public prop name); the
+  // type-identity gate binds it to the native entry's projection-lane member.
+  readonly onUpdate?: ((latest: Readonly<Record<string, string | number>>) => void) | undefined
+  // T17 (specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md): the pin's per-frame transform template.
+  // Core's shared TransformTemplate type — identical on both entries by construction (the
+  // TapCallback precedent); forwarded to motion/react, which owns the per-frame call. The
+  // 'worklet' directive the native mount gate requires is inert on web.
+  readonly transformTemplate?: TransformTemplate | undefined
+  // T24 B1: the dynamic-variants custom payload — forwarded to motion/react, which owns
+  // resolver invocation on this engine (`unknown` on both entries by construction).
+  readonly custom?: unknown
+}
+
+// Standard drag props remain the pin's exact web surface. Native Motion's `dragSnapPoints`
+// extension is the only overlay: it remains axis-discriminated because the pin's single
+// `modifyTarget` callback cannot represent independent two-axis snap arrays.
+type PinnedWebDragPropKeys =
+  | 'drag'
+  | 'dragConstraints'
+  | 'dragElastic'
+  | 'dragPropagation'
+  | 'dragControls'
+  | 'dragListener'
+  | 'onMeasureDragConstraints'
+  | 'onDragStart'
+  | 'onDrag'
+  | 'onDragEnd'
+  | 'dragDirectionLock'
+  | 'onDirectionLock'
+  | 'dragMomentum'
+  | 'dragTransition'
+  | 'dragSnapToOrigin'
+  | '_dragX'
+  | '_dragY'
+
+type PinnedWebDragProps = Pick<MotionProps, PinnedWebDragPropKeys>
+type NonEmptyNumberArray = readonly [number, ...number[]]
+type WebDragSnapExtension =
+  | { readonly dragSnapPoints?: undefined }
+  | {
+      readonly drag: 'x'
+      readonly dragSnapPoints: {
+        readonly x: NonEmptyNumberArray
+        readonly y?: never
+      }
+    }
+  | {
+      readonly drag: 'y'
+      readonly dragSnapPoints: {
+        readonly y: NonEmptyNumberArray
+        readonly x?: never
+      }
+    }
+
+type PinnedWebViewRemainderKeys =
+  | 'onAnimationStart'
+  | 'onBeforeLayoutMeasure'
+  | 'onLayoutMeasure'
+  | 'onLayoutAnimationStart'
+  | 'onDragTransitionEnd'
+  | 'onPanSessionStart'
+  | 'onPanStart'
+  | 'onPan'
+  | 'onPanEnd'
+  | 'globalTapTarget'
+  | 'whileInView'
+  | 'onViewportEnter'
+  | 'onViewportLeave'
+  | 'viewport'
+  | 'layoutDependency'
+  | 'layoutRoot'
+  | 'layoutAnchor'
+  | 'layoutCrossfade'
+  | 'ignoreStrict'
+  | 'values'
+  | 'propagate'
+  | 'data-framer-portal-id'
+  | 'data-framer-appear-id'
+
+type PinnedWebViewRemainder = Pick<MotionProps, PinnedWebViewRemainderKeys>
+
+export type ViewProps = ViewBaseProps &
+  PinnedWebDragProps &
+  WebDragSnapExtension &
+  PinnedWebViewRemainder
+
+// The web host declares every registry class the pinned DOM engine actually supports. Portable
+// members still ride core validation; intrinsic-web complex effects bypass Native Motion's value
+// normalizer and remain owned by motion/react (REQ-WEB-019).
+const WEB_HOST = hostCapabilities('web', ['universal', 'web-only', 'pointer-gated'])
+const INTRINSIC_WEB_TARGET_KEYS = new Set<string>([
+  'filter',
+  'clipPath',
+  'boxShadow',
+  'backgroundImage',
+])
+
+function isIntrinsicWebTargetKey(key: string): boolean {
+  return INTRINSIC_WEB_TARGET_KEYS.has(key)
+}
+
+function validateWebVariantEntrySnapshot(
+  label: string,
+  entry: unknown,
+  componentId: MotionComponentId,
+): ReturnType<typeof validateVariantEntrySnapshot> {
+  if (typeof entry === 'function' || typeof entry !== 'object' || entry === null) {
+    return validateVariantEntrySnapshot(label, entry, WEB_HOST, { componentId })
+  }
+  const prototype = Object.getPrototypeOf(entry)
+  if (prototype !== Object.prototype && prototype !== null) {
+    return validateVariantEntrySnapshot(label, entry, WEB_HOST, { componentId })
+  }
+  const portable: Record<string, unknown> = Object.create(null)
+  const intrinsic: Record<string, unknown> = Object.create(null)
+  let hasTransition = false
+  let transition: unknown
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'transition') {
+      hasTransition = true
+      transition = value
+    } else if (isIntrinsicWebTargetKey(key)) intrinsic[key] = value
+    else portable[key] = value
+  }
+  const verdict = validateVariantEntrySnapshot(label, portable, WEB_HOST, { componentId })
+  if (verdict.refusal !== null || typeof verdict.entry === 'function' || verdict.entry === null) {
+    return verdict
+  }
+  const accepted = Object.assign(Object.create(null), verdict.entry, intrinsic) as Record<
+    string,
+    unknown
+  >
+  if (hasTransition) accepted['transition'] = transition
+  return {
+    refusal: null,
+    entry: accepted as VariantEntry,
+  }
+}
+
+// Component-level motion props DECLARED on ViewProps that live outside the disposition table's
+// registry domain (they are lifecycle plumbing, not animatable capabilities). Anything motion
+// would interpret that is neither here nor in the table is an undeclared capability and fails
+// loud below.
+const DECLARED_COMPONENT_PROPS = new Set([
+  'onAnimationComplete',
+  'onLayoutAnimationComplete',
+  // T23 C: motion's own per-frame latest callback — same lifecycle-plumbing lane.
+  'onUpdate',
+])
+
+// Motion owns actual label resolution and propagation. The shim carries only the accepted label
+// selections so each descendant can validate its OWN dictionary against its OWN transition before
+// handing the original (or production-sanitized) label to Motion. This prevents a parent-internal
+// sanitized alias from becoming an observable propagated label at the next dictionary boundary.
+interface VariantTimingSelections {
+  readonly initial: readonly string[] | false | undefined
+  readonly animate: readonly string[] | undefined
+  readonly exit: readonly string[] | undefined
+  readonly whileTap: readonly string[] | undefined
+  readonly whileDrag: readonly string[] | undefined
+}
+
+const EMPTY_VARIANT_TIMING_SELECTIONS: VariantTimingSelections = {
+  initial: undefined,
+  animate: undefined,
+  exit: undefined,
+  whileTap: undefined,
+  whileDrag: undefined,
+}
+
+const VariantTimingContext = createContext<VariantTimingSelections>(EMPTY_VARIANT_TIMING_SELECTIONS)
+
+// A Text host marks its rendered descendant tree. Public View consumes that marker at its own
+// render boundary so wrappers are judged by what they render, never by predictive invocation.
+const TextNestingContext = createContext<NormalizeOptions | null>(null)
+
+function componentDragError(
+  componentId: MotionComponentId,
+  error: unknown,
+): MotionWebRejectionError {
+  const message = error instanceof Error ? error.message : describeValue(error)
+  return new MotionWebRejectionError(`${componentId}: ${message}`)
+}
+
+// CORE owns the drag verdict, while each public host owns the public diagnostic identity. Keeping
+// that identity mandatory at this adapter prevents a new Text lane from reporting anonymously.
+function resolveDragConfigForComponent(
+  input: Parameters<typeof resolveDragConfig>[0],
+  options: NormalizeOptions,
+  componentId: MotionComponentId,
+): ResolvedDragConfig | null {
+  try {
+    return resolveDragConfig(input, options.mode, (error) =>
+      options.report(componentDragError(componentId, error)),
+    )
+  } catch (error) {
+    const rejection = componentDragError(componentId, error)
+    if (options.mode === 'development') throw rejection
+    options.report(rejection)
+    return null
+  }
+}
+
+// Validate a Target with the ratified severity law. Development: core's validateTarget throws
+// through untouched (its InvalidTargetError names component, key, value, reason). Production:
+// validated PER KEY so only the offending property is refused — the catch below IS the ratified
+// production error channel ("report through the error channel and refuse the property", BRIEF
+// Decisions 2026-07-06), not suppression: every failure is reported, the property never applies.
+// Exported for the presence container (round 12 major 38): the container gates its children's
+// targets through the SAME lane the View uses, so failure categories and ordering mirror the
+// native container exactly (REQ-PRESENCE-019).
+// The transition counterpart of validateWithSeverity (r7 major 41b089c8c0af): core
+// validateTransition is the single authority (shape, vocabulary, ranges, the derived-config
+// probe); the severity split mirrors the target lane exactly.
+export function gateTransitionWithSeverity(
+  value: WebTransition,
+  options: NormalizeOptions,
+  componentId: string = '<View>',
+): WebTransition | undefined {
+  try {
+    return mapWebTransitionAliases(value, componentId)
+  } catch (error) {
+    if (!(error instanceof MotionWebRejectionError)) throw error
+    if (options.mode === 'development') throw error
+    options.report(error)
+    return undefined
+  }
+}
+
+export function validateWithSeverity(
+  target: Target,
+  propName: string,
+  options: NormalizeOptions,
+  transition: Transition | undefined = undefined,
+  componentId: MotionComponentId = '<View>',
+): Target {
+  return validateWithSeverityResult(target, propName, options, transition, false, componentId)
+    .target
+}
+
+export interface SeverityTargetResult {
+  readonly target: Target
+  /** Keys that reached the effective-transition predicate from the captured target snapshot. */
+  readonly attemptedKeys: readonly string[]
+}
+
+// Keep direct-target ownership on the same one-read snapshot that crosses into motion/react. A
+// property that passed target validation but was then refused by its effective timing transition is
+// an attempted fallback owner; an absent or malformed target is not. This distinction prevents an
+// inert element transition from surviving a reported per-property refusal without turning a truly
+// ownerless transition into a silent no-op.
+export function validateWithSeverityResult(
+  target: WebTarget,
+  propName: string,
+  options: NormalizeOptions,
+  transition: Transition | undefined = undefined,
+  initialOnly = false,
+  componentId: MotionComponentId = '<View>',
+): SeverityTargetResult {
+  const shapeRefusal = targetShapeRefusal(target, { componentId })
+  if (shapeRefusal !== null) {
+    if (options.mode === 'development') throw shapeRefusal
+    options.report(
+      new MotionWebRejectionError(`${propName} refused: ${shapeRefusal.message}`, {
+        cause: shapeRefusal,
+      }),
+    )
+    return { target: {} as Target, attemptedKeys: [] }
+  }
+  if (options.mode === 'development') {
+    // validateTargetSnapshot shape-gates first (round 9): a malformed non-object target throws the
+    // typed InvalidTargetError here, never a raw TypeError out of Object.keys. It also materializes
+    // each keyframe ARRAY member ONCE and RETURNS that snapshot (R8, review major 23): dev forwards
+    // the snapshot, not the caller's array, so motion/react's later read never re-fires an accessor.
+    const accepted: Record<string, unknown> = Object.create(null)
+    const attemptedKeys: string[] = []
+    for (const [key, rawValue] of Object.entries(target)) {
+      if (isIntrinsicWebTargetKey(key)) {
+        accepted[key] = rawValue
+        attemptedKeys.push(key)
+        continue
+      }
+      const { refusal, target: snapshot } = validateTargetSnapshot({ [key]: rawValue }, WEB_HOST, {
+        componentId,
+      })
+      if (refusal !== null) throw refusal
+      const value = (snapshot as Record<string, unknown>)[key]
+      const initialRefusal = initialOnly ? initialTargetRefusal(componentId, key, value) : null
+      if (initialRefusal !== null) throw initialRefusal
+      const timingRefusal = keyframeTransitionRefusal(
+        componentId,
+        key,
+        value,
+        transitionForProperty(transition, key),
+      )
+      if (timingRefusal !== null) throw timingRefusal
+      accepted[key] = value
+      attemptedKeys.push(key)
+    }
+    return { target: accepted as Target, attemptedKeys }
+  }
+  // Whole-target shape gate for the production lane (round 9 major 31): Object.entries below
+  // coerced numbers/booleans to the empty target with NO report and raw-TypeErrored on null —
+  // a malformed shape is refused AS A UNIT through the ratified error channel. RETURN-shaped,
+  // no catch (M3 r8 major b9eb82c0d429): only core's returned refusals are reported and
+  // dropped; a dependency fault thrown through validation keeps its exact identity.
+  const kept: Record<string, unknown> = {}
+  const attemptedKeys: string[] = []
+  for (const [key, value] of Object.entries(target)) {
+    if (isIntrinsicWebTargetKey(key)) {
+      kept[key] = value
+      attemptedKeys.push(key)
+      continue
+    }
+    // validateTargetSnapshot materializes the member's array ONCE before validation and returns it;
+    // the KEPT value is that snapshot, never the caller's raw array (one read, one truth — R8,
+    // review major 23), so motion/react never re-reads an accessor and lands an unvalidated value.
+    const { refusal, target: snapshot } = validateTargetSnapshot({ [key]: value }, WEB_HOST, {
+      componentId,
+    })
+    if (refusal !== null) {
+      options.report(
+        new MotionWebRejectionError(`${propName}.${key} refused: ${refusal.message}`, {
+          cause: refusal,
+        }),
+      )
+      continue
+    }
+    const valueSnapshot = (snapshot as Record<string, unknown>)[key]
+    attemptedKeys.push(key)
+    const initialRefusal = initialOnly
+      ? initialTargetRefusal(componentId, key, valueSnapshot)
+      : null
+    if (initialRefusal !== null) {
+      options.report(
+        new MotionWebRejectionError(`${propName}.${key} refused: ${initialRefusal.message}`, {
+          cause: initialRefusal,
+        }),
+      )
+      continue
+    }
+    const timingRefusal = keyframeTransitionRefusal(
+      componentId,
+      key,
+      valueSnapshot,
+      transitionForProperty(transition, key),
+    )
+    if (timingRefusal !== null) {
+      options.report(
+        new MotionWebRejectionError(`${propName}.${key} refused: ${timingRefusal.message}`, {
+          cause: timingRefusal,
+        }),
+      )
+      continue
+    }
+    kept[key] = valueSnapshot
+  }
+  return { target: kept as Target, attemptedKeys }
+}
+
+// R7 (REQ-API-032 law f): the web dictionary gate — outer shape AS A UNIT, every entry
+// eagerly through core's snapshot validator over the WEB host (core validity + the full
+// transition vocabulary; the native-only drivability/option laws stay native — this engine
+// drives units and executes delay/velocity). Development throws typed; production reports
+// and refuses the offending UNIT: the whole dictionary for an outer-shape offense, the
+// single ENTRY inside it. RETURN-shaped, no catch (M3 r3 majors 1b53e9337aec/13af48a64530):
+// the shape probe and the entry READ phase run foreign traps unguarded — faults, including
+// authentic same-class sentinels and replayed refusals, propagate untouched by
+// construction. The accumulator is null-prototype so an own '__proto__' label can never
+// pollute; the accepted value is the SNAPSHOT (one read, one truth) — resolution against
+// it is motion/react's (REQ-WEB-011).
+function gateVariantsWithSeverity(
+  value: unknown,
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): VariantsDictionary | undefined {
+  const shapeRefusal = variantsShapeRefusal(value)
+  if (shapeRefusal !== null) {
+    const ownedRefusal = new MotionWebRejectionError(`${componentId}: ${shapeRefusal.message}`, {
+      cause: shapeRefusal,
+    })
+    if (options.mode === 'development') throw ownedRefusal
+    options.report(ownedRefusal)
+    return undefined
+  }
+  const accepted = Object.create(null) as Record<string, VariantEntry | VariantResolver>
+  for (const [label, entry] of Object.entries(value as Record<string, unknown>)) {
+    const { refusal, entry: snapshot } = validateWebVariantEntrySnapshot(label, entry, componentId)
+    if (refusal !== null) {
+      if (options.mode === 'development') throw refusal
+      options.report(new MotionWebRejectionError(refusal.message, { cause: refusal }))
+      continue
+    }
+    // T24 B2: a resolver entry is accepted by identity. Static entries retain pin-owned nested
+    // transitions; only Native Motion's easing aliases are mapped before the pin receives them.
+    if (typeof snapshot === 'function' || snapshot === null) {
+      accepted[label] = snapshot!
+      continue
+    }
+    const rawTransition = (snapshot as Record<string, unknown>)['transition']
+    if (rawTransition === undefined) {
+      accepted[label] = snapshot
+      continue
+    }
+    const mappedTransition = gateTransitionWithSeverity(
+      rawTransition as WebTransition,
+      options,
+      `${componentId}.variants.${label}`,
+    )
+    if (mappedTransition === undefined) continue
+    accepted[label] =
+      mappedTransition === rawTransition
+        ? snapshot
+        : (Object.assign(Object.create(null), snapshot, {
+            transition: mappedTransition,
+          }) as VariantEntry)
+  }
+  return accepted as VariantsDictionary
+}
+
+function labelNames(value: unknown): readonly string[] | undefined {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value) && value.every((member) => typeof member === 'string')) {
+    return value as readonly string[]
+  }
+  return undefined
+}
+
+// Only labels selected by an animation-time supplier consume the element transition. `initial`
+// resolves synchronously and deliberately does not appear here: its scalar first-paint target is
+// legal beside a keyframed animate label using the same transition.
+function gateVariantTimingConsumers(
+  dictionary: VariantsDictionary | undefined,
+  labels: readonly string[],
+  initialLabels: readonly string[] | undefined,
+  elementTransition: Transition | undefined,
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): {
+  readonly dictionary: VariantsDictionary | undefined
+  readonly filteredLabels: ReadonlySet<string>
+  readonly initialProjection: VariantsDictionary | undefined
+  readonly initialFilteredLabels: ReadonlySet<string>
+  readonly hasElementTransitionOwner: boolean
+  readonly attemptedElementTransitionOwner: boolean
+} {
+  if (
+    dictionary === undefined ||
+    (elementTransition === undefined && initialLabels === undefined) ||
+    (labels.length === 0 && initialLabels === undefined)
+  )
+    return {
+      dictionary,
+      filteredLabels: new Set(),
+      initialProjection: dictionary,
+      initialFilteredLabels: new Set(),
+      hasElementTransitionOwner: false,
+      attemptedElementTransitionOwner: false,
+    }
+  const selected = new Set(labels)
+  const selectedInitial = new Set(initialLabels)
+  const accepted = Object.create(null) as Record<string, VariantEntry | VariantResolver>
+  const filteredLabels = new Set<string>()
+  const initialProjection = Object.create(null) as Record<string, VariantEntry>
+  const initialFilteredLabels = new Set<string>()
+  let hasElementTransitionOwner = false
+  let attemptedElementTransitionOwner = false
+  for (const [label, entry] of Object.entries(dictionary)) {
+    if (typeof entry === 'function') {
+      // T24 B2: a RESOLVER entry's target keys are unknowable before Motion invokes it at
+      // activation, so the per-key initial/timing sanitization below cannot apply — forward
+      // it untouched (the underlying motion/react owns dynamic resolution on this engine).
+      // Unreachable until the entry boundary accepts the form (validateVariantEntrySnapshot).
+      accepted[label] = entry
+      continue
+    }
+    const consumesInitial = selectedInitial.has(label)
+    const consumesTiming = selected.has(label) && entry.transition === undefined
+    if (!consumesInitial && !consumesTiming) {
+      accepted[label] = entry
+      continue
+    }
+    const targetEntries = Object.entries(entry).filter(([key]) => key !== 'transition')
+    const initial = Object.create(null) as Record<string, unknown>
+    let initialChanged = false
+    const filtered = Object.create(null) as Record<string, unknown>
+    let timingChanged = false
+    // The selected entry has handed these properties to the element transition. Preserve the
+    // attempted-vs-accepted distinction after filtering: a rejected scalar owns its one report,
+    // while only a retained property can keep the transition executable.
+    if (consumesTiming && targetEntries.length > 0) attemptedElementTransitionOwner = true
+    for (const [key, target] of targetEntries) {
+      if (isIntrinsicWebTargetKey(key)) {
+        if (consumesInitial) initial[key] = target
+        if (consumesTiming) filtered[key] = target
+        continue
+      }
+      const initialRefusal = consumesInitial ? initialTargetRefusal(componentId, key, target) : null
+      const timingRefusal = consumesTiming
+        ? keyframeTransitionRefusal(
+            componentId,
+            key,
+            target,
+            transitionForProperty(elementTransition, key),
+          )
+        : null
+      if (initialRefusal !== null) {
+        const error = new MotionWebRejectionError(initialRefusal.message, { cause: initialRefusal })
+        if (options.mode === 'development') throw error
+        options.report(error)
+        initialChanged = true
+      } else if (consumesInitial) {
+        initial[key] = target
+      }
+      if (timingRefusal !== null) {
+        const error = new MotionWebRejectionError(timingRefusal.message, { cause: timingRefusal })
+        if (options.mode === 'development') throw error
+        options.report(error)
+        timingChanged = true
+      } else if (consumesTiming) {
+        filtered[key] = target
+      }
+    }
+    if (consumesInitial) {
+      initialProjection[label] = initial as VariantEntry
+      if (initialChanged) initialFilteredLabels.add(label)
+    }
+    if (!consumesTiming) {
+      accepted[label] = entry
+      continue
+    }
+    if (timingChanged) {
+      // Motion already resolves this exact label (including inherited selections). Sanitise its
+      // original dictionary entry instead of forwarding a synthetic alias as a local prop: aliases
+      // change Motion's controlling/propagation semantics. Initial overlays use the separately
+      // scalar-gated projection, so this timing filter can never reintroduce an initial array.
+      filteredLabels.add(label)
+      accepted[label] = filtered as VariantEntry
+      if (Object.keys(filtered).length > 0) hasElementTransitionOwner = true
+      continue
+    }
+    accepted[label] = entry
+    if (targetEntries.length > 0) hasElementTransitionOwner = true
+  }
+  return {
+    dictionary: accepted as VariantsDictionary,
+    filteredLabels,
+    initialProjection: initialProjection as VariantsDictionary,
+    initialFilteredLabels,
+    hasElementTransitionOwner,
+    attemptedElementTransitionOwner,
+  }
+}
+
+function mappedLabels(
+  labels: readonly string[] | undefined,
+  aliases: ReadonlyMap<string, string>,
+): string | readonly string[] | undefined {
+  if (labels === undefined) return undefined
+  const mapped = labels.map((label) => aliases.get(label) ?? label)
+  return mapped.length === 1 ? mapped[0] : mapped
+}
+
+// R7 (REQ-API-032 law g): the ACCEPTED dictionary target keys for the presence container's
+// mounted-key union (animate keys ∪ dictionary keys). REPORT-silent, never severity-silent
+// (M3 r2 major 94ad45a8210d, the native silent-gate pattern): development still THROWS the
+// typed law-(f) refusal, so dictionary validation always outruns the exit-subset rule and
+// the error category matches native exactly; production skips the refused unit without a
+// report — the child View owns the one report in this same render pass. RETURN-shaped, no
+// catch (M3 r3 major 1b53e9337aec; the r2 ownership mechanism is superseded): a returned
+// refusal is boundary-made by construction, and anything thrown — a trap fault, a forged
+// or replayed sentinel — propagates untouched because nothing here catches it.
+export function silentDictionaryTargetKeys(
+  value: unknown,
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): ReadonlySet<string> {
+  const keys = new Set<string>()
+  if (value === undefined) return keys
+  const shapeRefusal = variantsShapeRefusal(value)
+  if (shapeRefusal !== null) {
+    if (options.mode === 'development')
+      throw new MotionWebRejectionError(`${componentId}: ${shapeRefusal.message}`, {
+        cause: shapeRefusal,
+      })
+    return keys
+  }
+  for (const [label, entry] of Object.entries(value as Record<string, unknown>)) {
+    const { refusal, entry: snapshot } = validateWebVariantEntrySnapshot(label, entry, componentId)
+    if (refusal !== null) {
+      if (options.mode === 'development') throw refusal
+      continue
+    }
+    for (const key of Object.keys(snapshot!)) {
+      if (key !== 'transition') keys.add(key)
+    }
+  }
+  return keys
+}
+
+// R7 (REQ-API-032 law f): inherit is a boolean switch — anything else refuses typed,
+// naming the contract (the native gateInheritProp's depth).
+function gateInheritWithSeverity(
+  value: unknown,
+  options: NormalizeOptions,
+  componentId: MotionComponentId = '<View>',
+): boolean | undefined {
+  if (typeof value === 'boolean') return value
+  const error = new MotionWebRejectionError(
+    `${componentId}: "inherit" must be a boolean — received ${describeValue(value)} (REQ-API-032 law f)`,
+  )
+  if (options.mode === 'development') throw error
+  options.report(error)
+  return undefined
+}
+
+const isLabelForm = (value: unknown): value is VariantLabels =>
+  typeof value === 'string' || Array.isArray(value)
+
+type MotionHostElement = DOMMotionComponents[keyof DOMMotionComponents]
+type MotionHostProps<Host extends MotionHostElement> = ViewProps &
+  Omit<React.ComponentPropsWithoutRef<Host>, keyof ViewProps | 'ref'>
+type MotionHostView<Host extends MotionHostElement> = ForwardRefExoticComponent<
+  PropsWithoutRef<MotionHostProps<Host>> & RefAttributes<ComponentRef<Host>>
+>
+
+type HostRole = 'view' | 'text' | 'image'
+
+function hasChildrenPayload(children: ReactNode | undefined): boolean {
+  return children !== undefined && children !== null && typeof children !== 'boolean'
+}
+
+function createViewForHost<Host extends MotionHostElement>(
+  element: Host,
+  options: NormalizeOptions,
+  role: HostRole = 'view',
+): MotionHostView<Host> {
+  const textHost = role === 'text'
+  const componentId: MotionComponentId =
+    role === 'text' ? '<Text>' : role === 'image' ? '<Image>' : '<View>'
+  const HostViewRuntime = forwardRef<ComponentRef<Host>, MotionHostProps<Host>>(function View(
+    props,
+    ref: Ref<ComponentRef<Host>>,
+  ) {
+    const inheritedTimingSelections = useContext(VariantTimingContext)
+    // Validation-only config default (pin owns runtime inherit; REQ-API-033 cardinality parity).
+    // The selected host contributes only its host attributes to the public component type. The
+    // runtime normalization contract remains the shared View subset, so recover that stable
+    // internal shape before routing the universal props below.
+    const viewProps = props as unknown as ViewProps & Record<string, unknown>
+    const {
+      initial,
+      animate,
+      exit,
+      transition,
+      variants,
+      inherit,
+      layout,
+      layoutId,
+      layoutScroll,
+      // The drag family is destructured OUT of `rest` (FLAG 5a): core resolveDragConfig is the
+      // single cross-engine verdict, and the mapping to motion's props is built below — so a
+      // production refusal drops the whole family (never a lenient survivor) and dragSnapPoints
+      // maps to dragTransition via nearestSnap over the SAME core-validated points native uses.
+      drag,
+      dragConstraints,
+      dragElastic,
+      dragSnapPoints,
+      dragPropagation,
+      dragControls,
+      dragListener,
+      dragDirectionLock,
+      onDirectionLock,
+      dragMomentum,
+      dragTransition,
+      dragSnapToOrigin,
+      _dragX,
+      _dragY,
+      onDragStart,
+      onDrag,
+      onDragEnd,
+      onPanSessionStart,
+      onPanStart,
+      onPan,
+      onPanEnd,
+      onMeasureDragConstraints,
+      transformTemplate,
+      custom,
+      children: suppliedChildren,
+      ...rest
+    } = viewProps
+    // Image is childless (REQ-API-034 law c/e): refuse any children payload at host render time.
+    let children = suppliedChildren
+    if (role === 'image' && hasChildrenPayload(suppliedChildren)) {
+      const error = new MotionWebRejectionError(
+        `${componentId}: Image is childless — a children payload is refused (REQ-API-034).`,
+      )
+      if (options.mode === 'development') throw error
+      options.report(error)
+      children = undefined
+    }
+
+    // Standard Motion callbacks remain pin-owned even beside the Native Motion snap extension.
+    // The extension validates only its own axis/points and never changes callback fault timing.
+    // T17: a present template must be a function — a malformed value is a typed failure under the
+    // severity law, never a raw TypeError inside motion's per-frame build-transform call. Web
+    // needs no worklet brand: motion/react calls the plain function on the main thread.
+    let gatedTransformTemplate = transformTemplate
+    if (transformTemplate !== undefined && typeof transformTemplate !== 'function') {
+      const error = new MotionWebRejectionError(
+        `${componentId}: "transformTemplate" must be a function, received ${typeof transformTemplate} — the ` +
+          'pin per-frame transform template (T17).',
+      )
+      if (options.mode === 'development') throw error
+      options.report(error)
+      gatedTransformTemplate = undefined
+    }
+    // Only the Native Motion snap extension enters the shared resolver. Standard pin drag props
+    // bypass this gate completely and remain owned by motion/react.
+    const anyDragProp = dragSnapPoints !== undefined
+    const currentDragConfig: ResolvedDragConfig | null = anyDragProp
+      ? resolveDragConfigForComponent(
+          {
+            drag,
+            dragSnapPoints,
+          },
+          options,
+          componentId,
+        )
+      : null
+
+    const dragBag: Record<string, unknown> = {}
+    // REQ-WEB-021: standard Motion drag props are pin-owned. Forward the current render's raw
+    // values without Native Motion validation, cloning, ref reads, callback wrappers, or mount
+    // freezing. `dragSnapPoints` itself is stripped; when present its modifyTarget mapping is
+    // merged after the authored inertia options and therefore intentionally wins that one key.
+    const rawDragProps: Readonly<Record<string, unknown>> = {
+      drag,
+      dragConstraints,
+      dragElastic,
+      dragPropagation,
+      dragControls,
+      dragListener,
+      dragDirectionLock,
+      onDirectionLock,
+      dragMomentum,
+      dragTransition,
+      dragSnapToOrigin,
+      _dragX,
+      _dragY,
+      onDragStart,
+      onDrag,
+      onDragEnd,
+      onMeasureDragConstraints,
+    }
+    for (const [key, value] of Object.entries(rawDragProps)) {
+      if (value !== undefined) dragBag[key] = value
+    }
+    if (currentDragConfig !== null) {
+      const snapAxis = resolvedDragAxes(currentDragConfig).find(
+        (axis) => currentDragConfig[axis]?.snap !== undefined,
+      )
+      if (snapAxis !== undefined) {
+        const mapped = snapPointsToDragTransition(currentDragConfig[snapAxis]!.snap!.points)
+        dragBag['dragTransition'] = { ...dragTransition, ...mapped }
+      }
+    }
+
+    // L4 entry shape gates (severity law; M2.6 lessons — the prop and its accepted shape are
+    // named, never a raw TypeError). Valid values forward to motion.div: real motion projects.
+    const layoutProps: Record<string, unknown> = {}
+    if (layout !== undefined) {
+      const validLayout =
+        typeof layout === 'boolean' ||
+        layout === 'position' ||
+        layout === 'size' ||
+        layout === 'preserve-aspect'
+      if (validLayout) {
+        layoutProps['layout'] = layout
+      } else {
+        const error = new MotionWebRejectionError(
+          `${componentId}: "layout" must be a boolean or 'position' | 'size' | 'preserve-aspect' — got ` +
+            `${describeValue(layout)} (specs/SPEC-LAYOUT.md)`,
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+      }
+    }
+    if (layoutId !== undefined) {
+      if (typeof layoutId === 'string' && layoutId.length > 0) {
+        layoutProps['layoutId'] = layoutId
+      } else {
+        const error = new MotionWebRejectionError(
+          `${componentId}: "layoutId" must be a non-empty string — got ${describeValue(layoutId)} ` +
+            '(specs/SPEC-LAYOUT.md)',
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+      }
+    }
+    // REQ-LAYOUT-022: boolean layoutScroll forwards to the pin; invalid values refuse at the boundary.
+    if (layoutScroll !== undefined) {
+      if (typeof layoutScroll === 'boolean') {
+        layoutProps['layoutScroll'] = layoutScroll
+      } else {
+        const error = new MotionWebRejectionError(
+          `${componentId}: "layoutScroll" must be a boolean — got ${describeValue(layoutScroll)} ` +
+            '(REQ-LAYOUT-022; specs/SPEC-LAYOUT.md)',
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+      }
+    }
+
+    // Prop routing, fail-closed (review cycle 1): motion-union keys (the disposition table's
+    // domain + style) go through normalization; a key OUR table does not declare but motion.div
+    // WOULD interpret (`isValidMotionProp`: variants, layout, whileInView, …) is an undeclared
+    // capability and fails loud under the severity law — forwarding it would ship an unratified
+    // Motion surface through the shim (the exact leak Codex reproduced). Only genuine DOM
+    // attributes (id, data-*, aria-*, DOM handlers) flow to motion.div untouched.
+    const motionBag: Record<string, unknown> = {}
+    const domAttrs: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(rest)) {
+      if (value === undefined) continue
+      if (key === 'style' || Object.hasOwn(DISPOSITIONS, key)) {
+        // The drag family (incl. dragSnapPoints) is destructured out of `rest` above and mapped via
+        // dragBag over core's verdict — it never reaches this loop; its disposition row exists purely
+        // for the compile-time exhaustiveness guard (REQ-WEB-012/013), not runtime routing.
+        motionBag[key] = value
+      } else if (DECLARED_COMPONENT_PROPS.has(key)) {
+        domAttrs[key] = value // declared lifecycle plumbing — forwarded to motion as-is
+      } else if (isValidMotionProp(key)) {
+        // REQ-WEB-020: pin-owned additions bypass the universal/native validation lanes and reach
+        // motion/react unchanged. The pin's deliberately prefix-wide predicate remains normative.
+        domAttrs[key] = value
+      } else {
+        domAttrs[key] = value
+      }
+    }
+    // Image element-specific `src` (REQ-API-034(e)): required non-empty string; alt is optional
+    // and passes through as a DOM attribute. Missing/invalid refuses only the prop.
+    if (role === 'image') {
+      const src = domAttrs['src'] ?? (rest as Record<string, unknown>)['src']
+      if (typeof src !== 'string' || src.length === 0) {
+        const error = new MotionWebRejectionError(
+          `${componentId}: "src" is required and must be a non-empty string — got ` +
+            `${describeValue(src)} (REQ-API-034).`,
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+        delete domAttrs['src']
+      }
+    }
+    // R7 (REQ-API-032): variants/inherit and the label forms EXECUTE on this engine —
+    // motion/react owns resolution, propagation, and the inherit switch (REQ-WEB-011: the
+    // shim adds validation, never animation semantics). This boundary gates VALIDITY at
+    // core depth; a refused unit never reaches motion (cross-engine sanitization parity:
+    // the native entry's controller never sees a refused unit either).
+    // Capture and validate the element transition before its target consumers. The resulting
+    // accepted local transition is what motion/react receives on the element. Keyframe
+    // cardinality validation also sees the nearest MotionConfig default when local is omitted
+    // (native MotionView effectiveElementTransition; REQ-API-033 same-shape law).
+    // tww0y1: distinguish "local omitted" from "local present but refused" — only omission
+    // inherits config for validation; a refused local must not fall back to the parent config
+    // (native gates the chosen effective transition, which is raw local when present).
+    const gatedTransition =
+      transition !== undefined
+        ? gateTransitionWithSeverity(transition, options, componentId)
+        : undefined
+    // Motion owns transition selection and keyframe timing on web. The universal target validator
+    // therefore receives no native timing policy.
+    const validationTransition = undefined
+    const targetProps: Record<string, unknown> = {}
+    const capturedInitialLabels = isLabelForm(initial)
+      ? captureLabelFormWithSeverity('initial', initial, options, componentId)
+      : undefined
+    const capturedAnimateLabels = isLabelForm(animate)
+      ? captureLabelFormWithSeverity('animate', animate, options, componentId)
+      : undefined
+    const capturedExitLabels = isLabelForm(exit)
+      ? captureLabelFormWithSeverity('exit', exit, options, componentId)
+      : undefined
+    const rawTapLabels = motionBag['whileTap']
+    const rawDragLabels = motionBag['whileDrag']
+    const capturedTapLabels = isLabelForm(rawTapLabels)
+      ? captureLabelFormWithSeverity('whileTap', rawTapLabels, options, componentId)
+      : undefined
+    const capturedDragLabels = isLabelForm(rawDragLabels)
+      ? captureLabelFormWithSeverity('whileDrag', rawDragLabels, options, componentId)
+      : undefined
+    if (isLabelForm(rawTapLabels)) {
+      if (capturedTapLabels === undefined) delete motionBag['whileTap']
+      else motionBag['whileTap'] = capturedTapLabels
+    }
+    if (isLabelForm(rawDragLabels)) {
+      if (capturedDragLabels === undefined) delete motionBag['whileDrag']
+      else motionBag['whileDrag'] = capturedDragLabels
+    }
+    const localInitialLabels = labelNames(capturedInitialLabels)
+    const localAnimateLabels = labelNames(capturedAnimateLabels)
+    const localExitLabels = labelNames(capturedExitLabels)
+    const localTapLabels = labelNames(capturedTapLabels)
+    const localDragLabels = labelNames(capturedDragLabels)
+    // Match Motion's pinned isControllingVariants law: ANY local label supplier owns the
+    // variant selection context as a unit. A child that supplies whileTap must not also validate
+    // a parent's animate label against its own transition, and inherit={false} suppresses the
+    // entire inherited mount selection.
+    const controlsVariants =
+      localInitialLabels !== undefined ||
+      localAnimateLabels !== undefined ||
+      localExitLabels !== undefined ||
+      localTapLabels !== undefined ||
+      localDragLabels !== undefined
+    const acceptsInheritedSelections = inherit !== false && !controlsVariants
+    // `initial` has one additional supplier rule: an object or `false` is a local first-paint
+    // supplier for THIS node, so an inherited initial label is not selected here. Neither form is a
+    // controlling label host, however, so the ancestor selection still propagates to descendants.
+    const hasLocalNonLabelInitialSupplier =
+      initial === false || (initial !== undefined && !isLabelForm(initial))
+    // Motion's controlling rule is label-form only. A local object target executes alongside
+    // inherited label selections, so raw prop presence cannot erase those selections from this
+    // validation-only context. An accepted local label remains the one controlling replacement.
+    const effectiveInitialLabels =
+      localInitialLabels ??
+      (hasLocalNonLabelInitialSupplier || !acceptsInheritedSelections
+        ? undefined
+        : inheritedTimingSelections.initial)
+    const effectiveAnimateLabels =
+      localAnimateLabels ??
+      (!acceptsInheritedSelections ? undefined : inheritedTimingSelections.animate)
+    const effectiveExitLabels =
+      localExitLabels ?? (!acceptsInheritedSelections ? undefined : inheritedTimingSelections.exit)
+    const effectiveTapLabels =
+      localTapLabels ??
+      (!acceptsInheritedSelections ? undefined : inheritedTimingSelections.whileTap)
+    const effectiveDragLabels =
+      localDragLabels ??
+      (!acceptsInheritedSelections ? undefined : inheritedTimingSelections.whileDrag)
+    const selectedTimingLabels = [
+      ...(effectiveAnimateLabels ?? []),
+      ...(effectiveExitLabels ?? []),
+      ...(effectiveTapLabels ?? []),
+      ...(effectiveDragLabels ?? []),
+    ]
+    let timingFilteredLabels: ReadonlySet<string> = new Set()
+    let initialFilteredLabels: ReadonlySet<string> = new Set()
+    let initialProjectionVariants: VariantsDictionary | undefined
+    if (variants !== undefined) {
+      const originalGatedVariants = gateVariantsWithSeverity(variants, options, componentId)
+      const timingGatedVariants = gateVariantTimingConsumers(
+        originalGatedVariants,
+        selectedTimingLabels,
+        effectiveInitialLabels === false ? undefined : effectiveInitialLabels,
+        validationTransition,
+        options,
+        componentId,
+      )
+      timingFilteredLabels = timingGatedVariants.filteredLabels
+      initialFilteredLabels = timingGatedVariants.initialFilteredLabels
+      const gatedVariants = timingGatedVariants.dictionary
+      initialProjectionVariants = timingGatedVariants.initialProjection
+      if (gatedVariants !== undefined) targetProps['variants'] = gatedVariants
+    }
+    const normalized = normalizeComponentProps(
+      motionBag,
+      options,
+      validationTransition,
+      componentId,
+    )
+    const mappedTap =
+      motionBag['whileTap'] === undefined ? undefined : mappedLabels(localTapLabels, new Map())
+    const mappedDrag =
+      motionBag['whileDrag'] === undefined ? undefined : mappedLabels(localDragLabels, new Map())
+    if (mappedTap !== undefined) normalized.props['whileTap'] = mappedTap
+    if (mappedDrag !== undefined) normalized.props['whileDrag'] = mappedDrag
+    if (inherit !== undefined) {
+      const gatedInherit = gateInheritWithSeverity(inherit, options, componentId)
+      if (gatedInherit !== undefined) targetProps['inherit'] = gatedInherit
+    }
+    if (initial !== undefined) {
+      // The pin's public MotionProps types do not advertise direct resolver functions, but its
+      // runtime resolveVariantFromProps path executes them when supplied through an untyped/cast
+      // boundary. Preserve that exact type/runtime asymmetry: a function reaches motion/react by
+      // identity and never enters Native Motion's object-target validator (REQ-API-056).
+      if (typeof (initial as unknown) === 'function') {
+        targetProps['initial'] = initial
+      } else if (initial === false) {
+        targetProps['initial'] = false
+      } else if (isLabelForm(initial)) {
+        if (capturedInitialLabels !== undefined) {
+          // `initial` is a first-paint supplier, not a timing consumer. It deliberately
+          // uses its own scalar-gated projection when animate needs a sanitized sibling.
+          targetProps['initial'] =
+            localInitialLabels?.some(
+              (label) => timingFilteredLabels.has(label) || initialFilteredLabels.has(label),
+            ) === true
+              ? resolveInitialOverlay(localInitialLabels, initialProjectionVariants)
+              : mappedLabels(localInitialLabels, new Map())
+        }
+      } else {
+        // `initial` paints a starting state. It does not execute the element's keyframe tween, so a
+        // scalar initial value must not be rejected merely because animate owns timing arrays.
+        targetProps['initial'] = validateWithSeverityResult(
+          initial,
+          'initial',
+          options,
+          undefined,
+          true,
+          componentId,
+        ).target
+      }
+    } else if (
+      effectiveInitialLabels !== undefined &&
+      effectiveInitialLabels !== false &&
+      effectiveInitialLabels.some(
+        (label) => timingFilteredLabels.has(label) || initialFilteredLabels.has(label),
+      )
+    ) {
+      // An inherited initial label remains Motion's propagation concern. This object overlay is
+      // the narrow production repair for a timing-sanitised shared label: it preserves the
+      // legal first paint from the immutable scalar-gated dictionary without making the child a
+      // local label controller.
+      targetProps['initial'] = resolveInitialOverlay(
+        effectiveInitialLabels,
+        initialProjectionVariants,
+      )
+    }
+    if (animate !== undefined) {
+      if (typeof animate === 'boolean') {
+        // U7h (REQ-API-057): forward the pin's boolean skip; do not validate as a target.
+        targetProps['animate'] = animate
+      } else if (typeof (animate as unknown) === 'function') {
+        targetProps['animate'] = animate
+      } else if (isLabelForm(animate)) {
+        if (capturedAnimateLabels !== undefined) {
+          targetProps['animate'] = mappedLabels(localAnimateLabels, new Map())
+        }
+      } else {
+        const result = validateWithSeverityResult(
+          animate,
+          'animate',
+          options,
+          validationTransition,
+          false,
+          componentId,
+        )
+        targetProps['animate'] = result.target
+      }
+    }
+    if (exit !== undefined) {
+      if (typeof (exit as unknown) === 'function') {
+        targetProps['exit'] = exit
+      } else if (isLabelForm(exit)) {
+        if (capturedExitLabels !== undefined) {
+          targetProps['exit'] = mappedLabels(localExitLabels, new Map())
+        }
+      } else {
+        const result = validateWithSeverityResult(
+          exit,
+          'exit',
+          options,
+          validationTransition,
+          false,
+          componentId,
+        )
+        targetProps['exit'] = result.target
+      }
+    }
+    if (gatedTransition !== undefined) {
+      targetProps['transition'] = gatedTransition
+    }
+
+    // `inherit={false}` gates only this node's mount selection. It does not make the node a
+    // controlling label host, so descendants must still receive the outer accepted labels. A
+    // genuine local label host, by contrast, resets the propagated batch as one unit.
+    const suppliedTimingSelections: VariantTimingSelections = {
+      initial:
+        localInitialLabels ?? (controlsVariants ? undefined : inheritedTimingSelections.initial),
+      animate:
+        localAnimateLabels ?? (controlsVariants ? undefined : inheritedTimingSelections.animate),
+      exit: localExitLabels ?? (controlsVariants ? undefined : inheritedTimingSelections.exit),
+      whileTap:
+        localTapLabels ?? (controlsVariants ? undefined : inheritedTimingSelections.whileTap),
+      whileDrag:
+        localDragLabels ?? (controlsVariants ? undefined : inheritedTimingSelections.whileDrag),
+    }
+    // R15 D6 (REQ-API-047): pan observation callbacks — pin owns the session without drag.
+    const panProps: Record<string, unknown> = {}
+    if (onPanSessionStart !== undefined) panProps['onPanSessionStart'] = onPanSessionStart
+    if (onPanStart !== undefined) panProps['onPanStart'] = onPanStart
+    if (onPan !== undefined) panProps['onPan'] = onPan
+    if (onPanEnd !== undefined) panProps['onPanEnd'] = onPanEnd
+    // T17: the gated template forwards to motion/react, which owns the per-frame call.
+    const templateProps: Record<string, unknown> = {}
+    if (gatedTransformTemplate !== undefined)
+      templateProps['transformTemplate'] = gatedTransformTemplate
+    // T24 B1: custom forwards untouched — motion/react resolves dynamic variants with it.
+    if (custom !== undefined) templateProps['custom'] = custom
+    const host: ReactNode = createElement(
+      element as never,
+      {
+        ref,
+        ...domAttrs,
+        ...targetProps,
+        ...layoutProps,
+        ...normalized.props,
+        ...dragBag,
+        ...panProps,
+        ...templateProps,
+      } as never,
+      children,
+    )
+    return createElement(VariantTimingContext.Provider, { value: suppliedTimingSelections }, host)
+  })
+
+  return forwardRef<ComponentRef<Host>, MotionHostProps<Host>>(function ViewBoundary(props, ref) {
+    const textNestingBoundary = useContext(TextNestingContext)
+    const nestedViewRefusalReportedRef = useRef(false)
+    if (!textHost && textNestingBoundary !== null) {
+      const error = new MotionWebRejectionError(
+        'Motion.Text cannot contain a Motion.View child; text hosts accept only text-compatible ' +
+          'ReactNode children (REQ-API-034).',
+      )
+      if (textNestingBoundary.mode === 'development') throw error
+      if (!nestedViewRefusalReportedRef.current) {
+        nestedViewRefusalReportedRef.current = true
+        textNestingBoundary.report(error)
+      }
+      return null
+    }
+    const host = createElement(HostViewRuntime, { ...props, ref } as never)
+    return textHost ? createElement(TextNestingContext.Provider, { value: options }, host) : host
+  })
+}
+
+// The one web host seam. The legacy one-argument test factory stays behaviorally identical;
+// alternate motion/react hosts must provide the normalization channel explicitly.
+export function createView(options: NormalizeOptions): MotionHostView<typeof motion.div>
+export function createView<Host extends MotionHostElement>(
+  element: Host,
+  options: NormalizeOptions,
+): MotionHostView<Host>
+export function createView<Host extends MotionHostElement>(
+  elementOrOptions: Host | NormalizeOptions,
+  maybeOptions?: NormalizeOptions,
+): MotionHostView<Host> | MotionHostView<typeof motion.div> {
+  if (maybeOptions === undefined)
+    return createViewForHost(motion.div, elementOrOptions as NormalizeOptions)
+  return createViewForHost(elementOrOptions as Host, maybeOptions)
+}
+
+/* The default error channel: loud in the console, never swallowed. */
+function consoleReporter(error: Error): void {
+  console.error(error)
+}
+
+export const View = createView(motion.div, { mode: ambientMode(), report: consoleReporter })
+
+const TEXT_OPTIONS: NormalizeOptions = {
+  // Unlike the named test factory, the public Text component cannot receive explicit options.
+  // Keep its severity decision render-fresh so the production refusal path remains testable and
+  // matches the public View's ambient contract.
+  get mode() {
+    return ambientMode()
+  },
+  report: consoleReporter,
+}
+const ParagraphText = createViewForHost(motion.p, TEXT_OPTIONS, 'text')
+const InlineText = createViewForHost(motion.span, TEXT_OPTIONS, 'text')
+
+// REQ-API-034 law (b): the catalog ports motion.p with the default block host and motion.span
+// with `as="span"`. Native accepts the selector as a semantic no-op because RN Text has no DOM
+// display-mode distinction; keeping it in the universal type makes a catalog port typecheck on
+// both entries.
+export type TextProps = Omit<MotionHostProps<typeof motion.p>, 'as'> & {
+  readonly as?: 'p' | 'span'
+}
+export const Text = forwardRef<HTMLElement, TextProps>(function Text({ as, ...props }, ref) {
+  const nestedInsideText = useContext(TextNestingContext) !== null
+  let selectedAs: 'p' | 'span' = nestedInsideText ? 'span' : 'p'
+  if (as === 'span' || (!nestedInsideText && as === 'p')) selectedAs = as
+  // A paragraph nested in Text produces an invalid DOM tree. The nesting context is the rendered
+  // ancestor, so explicit `p` is valid at the root but is an invalid selector below Text.
+  if ((as !== undefined && as !== 'p' && as !== 'span') || (nestedInsideText && as === 'p')) {
+    const error = new MotionWebRejectionError(
+      `<Text> "as" must be "p" or "span" at the root and "span" inside another Text host — got ${describeValue(as)} (REQ-API-034).`,
+    )
+    if (ambientMode() === 'development') throw error
+    consoleReporter(error)
+    // Production refuses only the invalid selector; nested Text always falls back inline.
+  }
+  const Host = selectedAs === 'span' ? InlineText : ParagraphText
+  return createElement(Host, { ...props, ref } as never)
+})
+
+const IMAGE_OPTIONS: NormalizeOptions = {
+  get mode() {
+    return ambientMode()
+  },
+  report: consoleReporter,
+}
+
+// REQ-API-034 law (c): Image covers motion.img. `src`/`alt` are ordinary DOM attributes; the
+// Motion props contract matches View; children are refused at host render.
+export type ImageProps = Omit<MotionHostProps<typeof motion.img>, 'children'> & {
+  readonly children?: never
+}
+export const Image = createViewForHost(
+  motion.img,
+  IMAGE_OPTIONS,
+  'image',
+) as ForwardRefExoticComponent<PropsWithoutRef<ImageProps> & RefAttributes<HTMLImageElement>>
+Image.displayName = 'Motion.Image'