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

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @unrulysystems/native-motion-web
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Initial alpha prerelease: the M3-era public surface (layout, presence, drag, gestures, variants,
+  orchestration, value types) with the cross-engine conformance suite published alongside the
+  runtime packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @unrulysystems/native-motion-core@0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unruly Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @unrulysystems/native-motion-web
+
+The web engine (SPEC-WEB-SHIM). A thin, validated shim over `motion/react`: wrapped `View`
+(`motion.div`), `Text` hosts (`motion.p` by default, inline `motion.span` with `as="span"`), and
+`Image` (`motion.img` with `src`/`alt` as DOM attributes) that add normalization and validation
+but **never animation semantics** — on web, the engine IS motion/react (pinned `motion@12.42.2`,
+peer). Presence (`AnimatePresence`/`usePresence`/`useIsPresent`) is a thin re-export of
+motion/react's own primitives. The ratified universal subset includes variants and
+`whileTap`/`whileDrag` state props; REQ-API-034's closed host set is `View`/`Text`/`Image`
+(ratified frozen 2026-07-22, BRIEF Decisions — `motion.create` stays internal-only).
+`layout`/`layoutId` are DECLARED since L4 and forward to real motion behind severity-law entry
+gates.
+
+## Module map (`src/`)
+
+| Module           | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `View.tsx`       | The internal wrapped-host seam for public `View`, `Text`, and `Image`: routes props (disposition table → normalize; declared component props → forward; other motion-interpretable keys → loud failure; genuine DOM attrs → through), validates targets with core's `validateTarget`, owns the FLAG 5a drag family, selects `motion.p`/`motion.span` for Text and `motion.img` for Image (childless; `src` required) — the verdict is single-sourced in core (`resolveDragConfig`, identical accept/refuse to native), Motion's shapes pass through, `dragSnapPoints` maps to `dragTransition` over core-validated points |
+| `MotionRoot.tsx` | REQ-API-022 root primitive — pass-through on web (motion/react binds recognizers per element; no gesture root needed); exists on both entries for the one-import universal surface (value-key parity)                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `disposition.ts` | The prop table (REQ-WEB-012): every public prop is pass-through / normalized / extension-mapped / rejected; compile-time exhaustive (`satisfies`), runtime-total. `dragSnapPoints` is CLASSIFIED extension-mapped so a dropped/drifted mapping is a type error (REQ-WEB-013); the runtime `dragSnapPoints`→`dragTransition` mapping over core-validated points is owned by `View.tsx` — the disposition is the guard, not the mechanism                                                                                                                                                                                   |
+| `normalize.ts`   | Pure/total prop pipeline; severity is a parameter — dev throws, production reports through the error channel and refuses the property (ratified law); pins `box-sizing: border-box`                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `snap.ts`        | The web MAPPING only (REQ-WEB-013): `nearestSnap` + `snapPointsToDragTransition` turn core-validated points into the `dragTransition.modifyTarget` projection. Drag-config VALIDATION is single-sourced in core (`resolveDragConfig`) so both engines' accepted sets are identical                                                                                                                                                                                                                                                                                                                                        |
+| `errors.ts`      | The loud-failure vocabulary (`MotionWebError` + rejection/fidelity/incompatible)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `mode.ts`        | `ambientMode()` — the one place the ambient `NODE_ENV` is read                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `jsdomWorld.ts`  | Test infrastructure: the shared jsdom world (install/restore-scoped globals via `useJsdomWorld()`, WAAPI spy) — import-order-sensitive by design; see its header                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+## Verification (Altitudes 3–6)
+
+- Vitest verifies disposition/normalize/snap tables, jsdom end-state component tests (the REAL
+  motion/react under jsdom — end states only, never mid-flight), SSR, the gesture cross-engine
+  parity flip, the variants label-form parity cases, and the L4 layout/layoutId forwarding gates.
+- **Altitude 5** (`e2e/`, Playwright, Chromium-only by ratification, `*.e2e.ts` so unit runners
+  never collect them): 22 tests across 13 specs — WAAPI-vs-analytic trajectory scrub, core-FLIP
+  math vs Chromium's rendered geometry (core-vs-browser, not native-vs-motion/react), real-mouse
+  drag→snap, presence removal timing, mid-flight interrupt continuity, the variants label-form
+  parity, the examples-gallery smoke with a zero-console-error net, the L4 App Store card
+  choreography specs, the layoutId crossfade parity counterpart
+  (LAYOUT_IDENTITY_PARITY_COUNTERPART), the Text layout-size proof, and the Image gallery
+  crossfade proof.
+- `e2e/fixtures/examples.tsx` is the examples gallery — documentation-by-example for the whole
+  ratified surface; every card self-reports through `data-*` attributes so specs and humans
+  read the same settle signal.
+
+```bash
+cd packages/native-motion-web && bunx vitest run && bun run e2e   # or: nub run e2e:web (root)
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@unrulysystems/native-motion-web",
+  "version": "0.1.0-alpha.0",
+  "license": "MIT",
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "!src/**/*.test.*",
+    "!src/jsdomWorld.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "e2e:build": "bun build e2e/fixtures/app.tsx e2e/fixtures/examples.tsx --outdir e2e/dist --target browser",
+    "e2e": "bun run e2e:build && playwright test -c e2e/playwright.config.ts"
+  },
+  "dependencies": {
+    "@unrulysystems/native-motion-core": "0.1.0-alpha.0",
+    "motion-dom": "12.42.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/jsdom": "^27.0.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19",
+    "@unrulysystems/native-motion-conformance": "0.1.0-alpha.0",
+    "jsdom": "^26.1.0",
+    "motion": "12.42.2",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "vitest": "^4.1.9"
+  },
+  "peerDependencies": {
+    "motion": "12.42.2",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/AnimatePresence.tsx

@@ -0,0 +1,284 @@
+'use client'
+// The shim's AnimatePresence: motion/react's component IS the presence engine (REQ-WEB-011).
+// T24 P forwards popLayout to motion/react, whose PopChild owns the web geometry composition;
+// T24 B1 custom is also forwarded; REQ-PRESENCE-023 preserves the pin's wider web surface.
+import { type PresenceMode } from '@unrulysystems/native-motion-core'
+// Namespace import: the single motion/react boundary the forwarded props contract targets
+// (the dedicated vi.mock("motion/react") test seam proves the alias wiring).
+import * as motionReact from 'motion/react'
+import {
+  Children,
+  cloneElement,
+  createElement,
+  isValidElement,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { MotionWebRejectionError } from './errors'
+import { ambientMode } from './mode'
+import type { NormalizeOptions } from './normalize'
+import {
+  gateTransitionWithSeverity,
+  Image,
+  silentDictionaryTargetKeys,
+  Text,
+  validateWithSeverityResult,
+} from './View'
+
+type PinnedAnimatePresenceProps = ComponentProps<typeof motionReact.AnimatePresence>
+
+// The universal presence contract remains portable, while REQ-PRESENCE-023 restores the pin's
+// wider presence surface on web. Indexed access binds every web-only domain to Motion 12.42.2.
+export interface AnimatePresenceProps {
+  mode?: PresenceMode
+  initial?: boolean
+  onExitComplete?: () => void
+  /** Pin catalog alias of onExitComplete (R13 V4); forwarded as onExitComplete to the pin. */
+  onRest?: () => void
+  // Typed `any` to match the pinned motion/react surface verbatim (the identity gate compares
+  // shapes exactly); it is gated below and never forwarded.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  custom?: any
+  /** Family-6: nested AnimatePresence joins parent exit (forwarded to the pin). */
+  propagate?: boolean
+  root?: PinnedAnimatePresenceProps['root']
+  anchorX?: PinnedAnimatePresenceProps['anchorX']
+  anchorY?: PinnedAnimatePresenceProps['anchorY']
+  presenceAffectsLayout?: PinnedAnimatePresenceProps['presenceAffectsLayout']
+  children?: ReactNode
+}
+
+/**
+ * Pin-catalog onRest → pin library onExitComplete (REQ-PRESENCE-010 R13 V4).
+ * Pure: deleting the alias (or flipping precedence) must red the web suite.
+ * `onExitComplete` wins when both are supplied — never double-fire.
+ */
+export function resolvePresenceExitComplete(
+  onExitComplete?: () => void,
+  onRest?: () => void,
+): (() => void) | undefined {
+  return onExitComplete ?? onRest
+}
+
+// The native container's child-target boundary, mirrored IN ORDER (review round 12 major 38 —
+// REQ-PRESENCE-019 universality): gate `animate`, gate `exit` — both through the same
+// validation lane the View uses, so a malformed shape or an unsupported key fails in the SAME
+// category as native (target validation, never a premature subset complaint) — and only THEN
+// apply the exit-subset rule against the GATED animate keys (round 11: an exit key outside the
+// child's animate keys has no shared value on the native engine's fixed-at-mount scope).
+// Development throws at the first offense; production reports each offense and refuses it —
+// the child is re-rendered on the GATED targets (native buildPresenceChildProps parity), so a
+// refused key never applies and the child's own boundary sees only clean values (one report
+// per offender, never two). A fully-refused exit is OMITTED: the no-exit removal path.
+function componentIdForPresenceChild(type: unknown): '<Text>' | '<View>' | '<Image>' {
+  const visited = new Set<object>()
+  let current = type
+  for (let depth = 0; depth < 16; depth += 1) {
+    if (current === Text) return '<Text>'
+    if (current === Image) return '<Image>'
+    if ((typeof current !== 'object' && typeof current !== 'function') || current === null) break
+    if (visited.has(current)) break
+    visited.add(current)
+    // React.memo stores its wrapped type on `.type`; forwardRef stays opaque because invoking
+    // it to predict its host would violate React's render ownership.
+    const wrapped = (current as { type?: unknown }).type
+    if (wrapped === undefined) break
+    current = wrapped
+  }
+  return '<View>'
+}
+
+function gateChildTargets(child: ReactElement, options: NormalizeOptions): ReactElement {
+  const componentId = componentIdForPresenceChild(child.type)
+  const childProps = child.props as {
+    readonly animate?: unknown
+    readonly exit?: unknown
+    readonly variants?: unknown
+    readonly transition?: unknown
+    readonly layout?: unknown
+    readonly whileTap?: unknown
+    readonly whileDrag?: unknown
+  }
+  if (childProps.animate === undefined && childProps.exit === undefined) return child
+  // R7 (REQ-API-032): LABEL-form child props pass through this gate untouched — the child
+  // View owns their string-only validity and motion owns their resolution; target
+  // validation on a string would be a raw shape crash.
+  const isLabelForm = (value: unknown): boolean => typeof value === 'string' || Array.isArray(value)
+  const animateIsLabel = isLabelForm(childProps.animate)
+  const exitIsLabel = isLabelForm(childProps.exit)
+  // Motion's runtime (though not its public MotionProps types at this pin) accepts a direct
+  // TargetResolver. It must reach the visual element unchanged; its result does not exist yet for
+  // this native-subset target gate to inspect (REQ-API-056).
+  const animateIsResolver = typeof childProps.animate === 'function'
+  const exitIsResolver = typeof childProps.exit === 'function'
+  // Capture and gate once here: the same frozen transition governs both presence consumers and is
+  // forwarded to the child, so an exit subset cannot validate a different timing truth from View.
+  const transition =
+    childProps.transition === undefined
+      ? undefined
+      : gateTransitionWithSeverity(childProps.transition as never, options, componentId)
+  const animateResult =
+    childProps.animate === undefined || animateIsLabel || animateIsResolver
+      ? undefined
+      : validateWithSeverityResult(
+          childProps.animate as never,
+          'animate',
+          options,
+          undefined,
+          false,
+          componentId,
+        )
+  const animate = animateResult?.target
+  const exitResult =
+    childProps.exit === undefined || exitIsLabel || exitIsResolver
+      ? undefined
+      : validateWithSeverityResult(
+          childProps.exit as never,
+          'exit',
+          options,
+          undefined,
+          false,
+          componentId,
+        )
+  let exit = exitResult?.target
+  // R7 law (g): the exit-subset rule admits the MOUNTED union — the gated object-form
+  // animate keys ∪ the dictionary's ACCEPTED target keys (M3 r1 majors 7a95f00c503d +
+  // 0a30cfcc17c2: a dictionary-named key IS mounted on the native engine, and a label-form
+  // animate resolves INSIDE that dictionary, so the union needs no resolution and the rule
+  // never skips — an unmounted exit key refuses identically on both engines). A label-form
+  // EXIT forwards ungated: its resolution is dictionary-bounded by construction.
+  if (exit !== undefined && !exitIsResolver && !animateIsResolver) {
+    const mountedKeys = new Set(Object.keys(animate ?? {}))
+    for (const key of silentDictionaryTargetKeys(childProps.variants, options, componentId)) {
+      mountedKeys.add(key)
+    }
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(exit)) {
+      if (!mountedKeys.has(key)) {
+        const error = new MotionWebRejectionError(
+          `${componentId}: presence exit key '${key}' is not in the child's mounted key set (the animate ` +
+            'target ∪ the variants dictionary, REQ-API-032 law g) — an un-mounted key has ' +
+            'no shared value.',
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+        continue
+      }
+      // `value` is drawn from `exit`, which IS the validateWithSeverity snapshot above — each keyframe
+      // array member was already materialized once (R8, review major 23), so this exit-subset forward
+      // carries the frozen snapshot to the child View, never a caller accessor read a second time.
+      kept[key] = value
+    }
+    exit = kept as never
+  }
+  return cloneElement(child as ReactElement<Record<string, unknown>>, {
+    ...(animateIsResolver || animate === undefined ? {} : { animate }),
+    ...(childProps.transition === undefined ? {} : { transition }),
+    // A LABEL exit stays the child's own prop (the View refuses it named); a fully-refused
+    // OBJECT exit is stripped so the child follows the no-exit removal path.
+    ...(exitIsLabel || exitIsResolver
+      ? {}
+      : exit === undefined || Object.keys(exit).length === 0
+        ? { exit: undefined }
+        : { exit }),
+  })
+}
+
+// Factory so tests (and advanced hosts) pin the severity mode and error channel explicitly —
+// the createView pattern; the exported AnimatePresence binds the ambient mode below.
+export function createAnimatePresence(options: NormalizeOptions) {
+  return function AnimatePresence(props: AnimatePresenceProps) {
+    const {
+      mode,
+      custom,
+      initial,
+      onExitComplete,
+      onRest,
+      propagate,
+      root,
+      anchorX,
+      anchorY,
+      presenceAffectsLayout,
+      children: rawChildren,
+      ...rest
+    } = props
+    // Unknown props still refuse under the severity law. Pin-owned web presence props are
+    // destructured above and forwarded below; native incompleteness never routes them here.
+    for (const [key, value] of Object.entries(rest as Record<string, unknown>)) {
+      if (value === undefined) continue
+      const error = new MotionWebRejectionError(
+        `AnimatePresence prop '${key}' is outside the pinned and contracted presence surfaces — ` +
+          'an unmapped Native Motion extension fails loud instead of silently no-oping ' +
+          '(REQ-WEB-015/REQ-PRESENCE-019).',
+      )
+      if (options.mode === 'development') throw error
+      options.report(error) // refused: never forwarded
+    }
+    const forwarded: Record<string, unknown> = {}
+    if (initial !== undefined) forwarded['initial'] = initial
+    if (root !== undefined) forwarded['root'] = root
+    if (anchorX !== undefined) forwarded['anchorX'] = anchorX
+    if (anchorY !== undefined) forwarded['anchorY'] = anchorY
+    if (presenceAffectsLayout !== undefined) {
+      forwarded['presenceAffectsLayout'] = presenceAffectsLayout
+    }
+    // R13 V4: pin-catalog onRest aliases onExitComplete for the pin library forward.
+    const exitComplete = resolvePresenceExitComplete(onExitComplete, onRest)
+    if (exitComplete !== undefined) forwarded['onExitComplete'] = exitComplete
+
+    // Validation order matches native render-for-render (major 58fa79fa334a / REQ-PRESENCE-019):
+    // mode → custom → propagate. Combined invalid props report the same first offense on both.
+    if (mode !== undefined) {
+      if (mode !== 'sync' && mode !== 'wait' && mode !== 'popLayout') {
+        // The mode VALUE domain is closed (round 17 major d11c0c6e9a42): an unsupported value
+        // must fail loud on both engines, never be forwarded for motion to interpret.
+        const error = new MotionWebRejectionError(
+          `presence mode '${String(mode)}' is not a valid mode — REQ-PRESENCE-010 admits ` +
+            "'sync' | 'wait' | 'popLayout' (development throws; production reports and falls " +
+            'back to the default).',
+        )
+        if (options.mode === 'development') throw error
+        options.report(error) // refused: motion runs with its default mode
+      } else {
+        forwarded['mode'] = mode
+      }
+    }
+    // T24 B1: motion/react owns presence custom precedence and activation-time binding on web.
+    if (custom !== undefined) forwarded['custom'] = custom
+    // Family-6: closed boolean domain (major 29845259d444) + forward pin true/false only.
+    if (propagate !== undefined) {
+      if (propagate !== true && propagate !== false) {
+        const error = new MotionWebRejectionError(
+          `AnimatePresence prop 'propagate' must be boolean (got ${typeof propagate}); ` +
+            'invalid values are refused under the severity law (REQ-PRESENCE-010/017).',
+        )
+        if (options.mode === 'development') throw error
+        options.report(error)
+      } else {
+        forwarded['propagate'] = propagate
+      }
+    }
+
+    // Children.map keeps keys stable across renders (prefixing is deterministic), so motion's
+    // key-tracked presence lifecycle is unaffected — the Alt-5 presence e2e pins this live.
+    // Child ACCEPTANCE is motion's own (round 19 major 6ca42f0e9bd3: round-18's loud gate was
+    // an unratified divergence from the pinned contract — motion filters non-elements
+    // silently and accepts keyless elements; the native container now mirrors that). Only
+    // ELEMENT children ride the target gate; everything else forwards for motion to filter.
+    const children = Children.map(rawChildren, (child) =>
+      isValidElement(child) ? gateChildTargets(child, options) : child,
+    )
+    return createElement(motionReact.AnimatePresence, forwarded, children)
+  }
+}
+
+/* The default error channel: loud in the console, never swallowed. */
+function consoleReporter(error: Error): void {
+  console.error(error)
+}
+
+export const AnimatePresence = createAnimatePresence({
+  mode: ambientMode(),
+  report: consoleReporter,
+})

package/src/LayoutGroup.tsx

@@ -0,0 +1,94 @@
+'use client'
+// REQ-API-036 — LayoutGroup web entry: thin validated re-export of the pin's own
+// LayoutGroup from motion/react (REQ-WEB-011). No custom web projection engine —
+// validation + severity law only; the pin owns id namespacing and projection groups.
+
+import { describeValue } from '@unrulysystems/native-motion-core'
+import { LayoutGroup as PinLayoutGroup } from 'motion/react'
+import { createElement, type ComponentProps, type ReactNode } from 'react'
+import { MotionWebRejectionError } from './errors'
+import { ambientMode } from './mode'
+import type { NormalizeOptions } from './normalize'
+
+export type LayoutGroupInherit = boolean | 'id'
+
+export interface LayoutGroupProps {
+  readonly children?: ReactNode
+  readonly id?: string | undefined
+  readonly inherit?: LayoutGroupInherit | undefined
+}
+
+const LAYOUT_GROUP_OWNER = '<LayoutGroup>' as const
+
+const ACCEPTED_PROP_NAMES = new Set(['children', 'id', 'inherit'])
+
+function refuse(options: NormalizeOptions, message: string): void {
+  const error = new MotionWebRejectionError(message)
+  if (options.mode === 'development') throw error
+  options.report(error)
+}
+
+function gateId(value: unknown, options: NormalizeOptions): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || value.length === 0) {
+    refuse(
+      options,
+      `${LAYOUT_GROUP_OWNER}: invalid id = ${describeValue(value)} — expected a non-empty string ` +
+        '(REQ-API-036).',
+    )
+    return undefined
+  }
+  return value
+}
+
+function gateInherit(value: unknown, options: NormalizeOptions): LayoutGroupInherit | undefined {
+  if (value === undefined) return undefined
+  if (value === true || value === false || value === 'id') return value
+  refuse(
+    options,
+    `${LAYOUT_GROUP_OWNER}: invalid inherit = ${describeValue(value)} — expected ` +
+      `true | false | "id" (REQ-API-036).`,
+  )
+  return undefined
+}
+
+function gateUnknownProps(
+  rest: Readonly<Record<string, unknown>>,
+  options: NormalizeOptions,
+): void {
+  for (const key of Object.keys(rest)) {
+    if (rest[key] === undefined) continue
+    if (ACCEPTED_PROP_NAMES.has(key)) continue
+    refuse(
+      options,
+      `${LAYOUT_GROUP_OWNER}: prop '${key}' is outside the contracted LayoutGroup surface ` +
+        '(REQ-API-036: id/inherit/children) — it fails loud rather than silently doing nothing.',
+    )
+  }
+}
+
+export function createLayoutGroup(options: NormalizeOptions) {
+  return function LayoutGroup({ children, id, inherit, ...rest }: LayoutGroupProps) {
+    gateUnknownProps(rest as Record<string, unknown>, options)
+    const gatedId = gateId(id, options)
+    const gatedInherit = gateInherit(inherit, options)
+
+    // exactOptionalPropertyTypes: only present keys are set; undefined must not be written.
+    type PinProps = ComponentProps<typeof PinLayoutGroup>
+    const forwarded = {
+      ...(gatedId !== undefined ? { id: gatedId } : {}),
+      ...(gatedInherit !== undefined ? { inherit: gatedInherit } : {}),
+    } satisfies PinProps
+
+    return createElement(PinLayoutGroup, forwarded, children)
+  }
+}
+
+function consoleReporter(error: Error): void {
+  console.error(error)
+}
+
+export const LayoutGroup = createLayoutGroup({
+  mode: ambientMode(),
+  report: consoleReporter,
+})

package/src/LayoutScrollOffsetProvider.tsx

@@ -0,0 +1,30 @@
+'use client'
+// Web counterpart of native LayoutScrollOffsetProvider (REQ-LAYOUT-022(c) namespace parity).
+// Pin motion/react owns container-scroll measure on overflow:scroll layoutScroll hosts — this
+// composition is a no-op passthrough so dual-entry product code can share the same tree.
+
+import type { ReactNode } from 'react'
+
+export type LayoutScrollOffset = { readonly x: number; readonly y: number }
+export type LayoutScrollOffsetRef = { current: LayoutScrollOffset }
+
+export interface LayoutScrollOffsetProviderProps {
+  readonly getOffset: () => LayoutScrollOffset
+  readonly children: ReactNode
+}
+
+export function LayoutScrollOffsetProvider({
+  children,
+}: LayoutScrollOffsetProviderProps): ReactNode {
+  return children
+}
+
+export function createLayoutScrollOffsetRef(): LayoutScrollOffsetRef {
+  return { current: { x: 0, y: 0 } }
+}
+
+/** Web: no-op (pin reads scrollLeft/scrollTop on the layoutScroll host itself). */
+export function recordLayoutScrollOffsetFromEvent(
+  _event: unknown,
+  _target: LayoutScrollOffsetRef,
+): void {}