@unrulysystems/native-motion 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @unrulysystems/native-motion
+
+## 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
+  - @unrulysystems/native-motion-web@0.1.0-alpha.0
+  - @unrulysystems/native-motion-conformance@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,55 @@
+# @unrulysystems/native-motion
+
+The single public import (REQ-UNIVERSAL-001): one specifier resolving to two engine entries —
+AND, since the dogfood extraction (`specs/DOGFOOD-MIGRATION-BUILD-PACKET.md`), the home of the
+native runtime itself.
+
+- `src/web.ts` — `'use client'`, an EXPLICIT re-export of the universal surface from the web
+  engine (`@unrulysystems/native-motion-web`); web-internal helpers stay out of the namespace.
+- `src/native.ts` — the native runtime entry: the universal surface (`View`, `ViewProps`, `Text`,
+  `TextProps`, `Image`, `ImageProps`, `AnimatePresence` (+ pin-catalog `onRest` alias of
+  `onExitComplete`), `usePresence`, `useIsPresent`, `MotionRoot`, `MotionRootProps`,
+  `MotionLengthLayoutProvider` (parent/viewport geometry for measure-resolved `%`/`calc`),
+  `LayoutScrollOffsetProvider` + `recordLayoutScrollOffsetFromEvent` /
+  `createLayoutScrollOffsetRef` (REQ-LAYOUT-022(c) live container-scroll feed), `DragInfo` + the
+  canonical core types) over the engine in `src/native/{driver,motion}` (the worklet driver, the
+  bindings, the UI-thread layout-identity engine). `View`, `Text`, and `Image` share the FLAG 5a
+  drag family (`drag` (`'x' | 'y' | true` — both-axes ships at R15 D1, REQ-API-041),
+  `dragConstraints`, `dragElastic`, `dragSnapPoints`, `dragPropagation` (Motion's nested-drag
+  lock, R15 D1),
+  `onDragStart`/`onDrag`/`onDragEnd`), the FLAG 5b layout family (`layout`, `layoutId`,
+  `layoutScroll`), and distinct property/layout lifecycle callbacks (`onAnimationComplete`,
+  `onLayoutAnimationStart`, `onLayoutAnimationComplete`); `Text` accepts ordinary React Native
+  text children while `Image`
+  is childless and requires a valid `source`. Text's universal `as="p" | "span"` selector is
+  validated on native (nested Text accepts only `span`, preventing a divergent invalid text tree)
+  even though RN has no DOM display-mode split; the web entry uses it to preserve a catalog
+  paragraph/inline choice. `MotionRoot` owns the gesture recognizer root (a gesture-carrying host
+  outside it fails loud). Capabilities the native surface has not pulled yet are absent —
+  premature use is a build error, never a stub. The host element set is CLOSED at these three RN
+  leaf primitives (ratified 2026-07-22, BRIEF Decisions): container classes adjudicate to `View`,
+  controls animate through a `View` wrapper, and `motion.create` stays internal-only.
+- `src/verification.ts` — the engine's intrinsic verification harness (probes, deterministic
+  check screens, the choreography gallery). SHELL-ONLY by law: the proof-harness app shell
+  mounts it; it is never part of a consumer example (REQ-EXHARNESS-010).
+
+## Dual skew-checked resolution (the ratified architecture)
+
+The manifest ships BOTH resolution mechanisms — the `exports` `react-native` condition (newer
+Metro) AND the top-level `react-native` field (older Metro floor) — and two guards keep them
+from ever disagreeing:
+
+1. `scripts/check-resolution-skew.mjs` (wired into `nub run check`): asserts the condition and
+   the field point at the same file, that `browser`/`import`/`default` agree and differ from
+   the native entry, and that both entries exist on disk.
+2. `src/resolution.test.ts`: resolves the export map with `resolve.exports` — react-native →
+   native, browser/import/default → web, no engine-mixing fall-through.
+
+Type identity across entries is a COMPILE-TIME gate: `src/type-identity.keys.ts` fails
+`nub run typecheck` if a native value export is absent on web while allowing intentional pinned
+Motion additions to the web namespace. `src/type-identity.assert.ts` fails if the universal View-,
+Text-, and Image-prop subsets (`initial`/`animate`/`exit`/`transition`/`onAnimationComplete`/
+`onLayoutAnimationStart`/`onLayoutAnimationComplete`/`layout`/`layoutId`) or the pinned
+AnimatePresence props stop being
+structurally identical, or if the presence-hook signatures drift from the pinned `motion/react`
+shapes (portable across test runners because it is not a test at all).

package/android/build.gradle

@@ -0,0 +1,24 @@
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+android {
+  namespace 'com.unrulysystems.nativemotion'
+  compileSdk 36
+
+  defaultConfig {
+    minSdk 24
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-android'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/unrulysystems/nativemotion/GestureExclusionModule.kt

@@ -0,0 +1,55 @@
+package com.unrulysystems.nativemotion
+
+import android.graphics.Rect
+import android.os.Build
+import android.view.View
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.fabric.FabricUIManager
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.common.UIManagerType
+
+/**
+ * REQ-GESTURE-032 — Android drag surfaces tell the system *this drag is mine*.
+ *
+ * `View.setSystemGestureExclusionRects` is the host API; Motion does not have an equivalent
+ * because web has no edge-back strip. Mapping: no-op on web and on API < 29. Not a public
+ * prop — a drag host registers its own bounds automatically.
+ */
+@ReactModule(name = GestureExclusionModule.NAME)
+class GestureExclusionModule(
+  private val reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+  override fun getName(): String = NAME
+
+  @ReactMethod
+  fun excludeView(viewTag: Double) {
+    applyOnView(viewTag.toInt()) { view ->
+      if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) return@applyOnView
+      view.systemGestureExclusionRects = listOf(Rect(0, 0, view.width, view.height))
+    }
+  }
+
+  @ReactMethod
+  fun clearView(viewTag: Double) {
+    applyOnView(viewTag.toInt()) { view ->
+      if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) return@applyOnView
+      view.systemGestureExclusionRects = emptyList()
+    }
+  }
+
+  private fun applyOnView(tag: Int, block: (View) -> Unit) {
+    reactContext.runOnUiQueueThread {
+      val uiManager =
+        UIManagerHelper.getUIManager(reactContext, UIManagerType.FABRIC) as? FabricUIManager
+      val view = uiManager?.resolveView(tag) ?: return@runOnUiQueueThread
+      block(view)
+    }
+  }
+
+  companion object {
+    const val NAME = "NativeMotionGestureExclusion"
+  }
+}

package/android/src/main/java/com/unrulysystems/nativemotion/NativeMotionPackage.kt

@@ -0,0 +1,27 @@
+package com.unrulysystems.nativemotion
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class NativeMotionPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+    if (name == GestureExclusionModule.NAME) GestureExclusionModule(reactContext) else null
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider =
+    ReactModuleInfoProvider {
+      mapOf(
+        GestureExclusionModule.NAME to
+          ReactModuleInfo(
+            GestureExclusionModule.NAME,
+            GestureExclusionModule::class.java.name,
+            false,
+            false,
+            false,
+            false,
+          ),
+      )
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@unrulysystems/native-motion",
+  "version": "0.1.0-alpha.0",
+  "license": "MIT",
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "android/build.gradle",
+    "android/src",
+    "react-native.config.js",
+    "!src/**/*.test.*",
+    "!src/**/*.assert.ts",
+    "!src/type-identity.keys.ts",
+    "!src/**/*Fixtures.ts",
+    "!src/native/motion/reactNativeRequireStub.ts"
+  ],
+  "type": "module",
+  "main": "./src/web.ts",
+  "react-native": "./src/native.ts",
+  "exports": {
+    ".": {
+      "react-native": "./src/native.ts",
+      "browser": "./src/web.ts",
+      "import": "./src/web.ts",
+      "default": "./src/web.ts"
+    },
+    "./driver-mapped-keys": "./src/native/motion/mappedKeys.ts",
+    "./native-public-surface": "./src/native/motion/shippedSurface.ts",
+    "./verification": "./src/verification.ts"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@unrulysystems/native-motion-conformance": "0.1.0-alpha.0",
+    "@unrulysystems/native-motion-core": "0.1.0-alpha.0",
+    "@unrulysystems/native-motion-web": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^24.0.0",
+    "@types/react-dom": "^19",
+    "motion": "12.42.2",
+    "motion-dom": "12.42.2",
+    "react-dom": "19.2.3",
+    "resolve.exports": "^2.0.3",
+    "vitest": "^4.1.9"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-gesture-handler": ">=2.28.0",
+    "react-native-reanimated": ">=4.1.0",
+    "react-native-worklets": ">=0.5.0"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,14 @@
+// The mobile app also lists this package in apps/mobile/react-native.config.js — Expo's
+// RN autolinker does not discover workspace packages from this file alone.
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import com.unrulysystems.nativemotion.NativeMotionPackage;',
+        packageInstance: 'new NativeMotionPackage()',
+      },
+      ios: null,
+    },
+  },
+}

package/src/native/driver/instantWindow.ts

@@ -0,0 +1,31 @@
+// U7b — the GLOBAL instant-window authority: the `MotionGlobalConfig.instantAnimations`
+// analogue (pin: motion-dom@12.42.2 animation/interfaces/motion-value.ts:100-109). While the
+// window is open, EVERY property-lane animation start on the PRODUCT (worklet) driver — any
+// component — takes the
+// U7a instant commit (skip the generator, final keyframe on the driver's next update tick,
+// completion fires) with `delay` ZEROED. The pin's asymmetry (F2): the authored `type: false`
+// honors a nonzero delay; the global window does not. Reduced motion is orthogonal — never
+// composed here. The reference driver (core's host-agnostic parity oracle) never consults the
+// window by design; the imperative playback lane does not consult it either (U7b review minor
+// — a demand for that class should REFUSE loud there like U7a's `type: false` arm, never
+// silently run full-duration).
+//
+// Plain JS-side module state: the consult happens at JS-side transition resolution
+// (workletDriver's toPlainTransition), before anything crosses to the UI runtime, so the flag
+// never marshals. `useInstantTransition` opens the window and relocks it two post-render frames
+// later under a token guard; `disableInstantTransitions` is the pin's sibling escape hatch for a
+// stuck window.
+
+let instantWindowOpen = false
+
+export function openInstantWindow(): void {
+  instantWindowOpen = true
+}
+
+export function closeInstantWindow(): void {
+  instantWindowOpen = false
+}
+
+export function isInstantWindowOpen(): boolean {
+  return instantWindowOpen
+}

package/src/native/driver/strictModeReplay.ts

@@ -0,0 +1,20 @@
+// REQ-DRIVER-022 StrictMode-replay phase (BRIEF Decisions 2026-07-10, registry-port round 7
+// major 5). React StrictMode's dev-only setup→cleanup→setup effect replay runs the hook's
+// dispose() cleanup and then replays setup against the SAME render-created binding — now
+// disposed. Resurrection (recreate the driver and rebind shared values on replay) is a deferred
+// capability with its own future rung; until it lands the replayed setup fails loud instead of
+// leaving a mounted component holding a permanently disposed binding. RN-free on purpose: the
+// mobile vitest suite pins this contract while the binding itself stays device/e2e territory.
+//
+// Severity law note: StrictMode double-invocation exists only in development builds, so this
+// throw is dev-only by construction — production never reaches the replay phase.
+
+export function assertSetupNotReplayedOnDisposed(disposed: boolean): void {
+  if (!disposed) return
+  throw new Error(
+    'useWorkletDriver: this binding was disposed by a StrictMode setup→cleanup→setup effect ' +
+      'replay. StrictMode remount replay is a deferred capability — resurrection (recreate the ' +
+      'driver and rebind shared values on replay) is its own future rung (BRIEF Decisions ' +
+      '2026-07-10; REQ-DRIVER-022). Unwrap this tree from <StrictMode> until that rung lands.',
+  )
+}