@octane-xplat/motion 0.0.0 → 0.7.1

package/LICENSE.motion

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 [Motion](https://motion.dev) B.V.
+
+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,15 @@
+# @octane-xplat/motion
+
+Declarative numeric motion for Octane UI on web, iOS, and Android. Use
+`motion.View`, `motion.Row`, or `motion.Pressable` with `initial`, `animate`,
+and `transition`. Bound motion values update hosts without rendering each frame.
+
+See the [motion guide](../../docs/animation-gestures.md) and maintained
+[MotionDemo](examples/MotionDemo.tsrx). Use the [PresenceDemo](examples/PresenceDemo.tsrx) for retained exits.
+The [compatibility record](UPSTREAM.md)
+defines the supported subset and differences from `@octanejs/motion`.
+
+Build with `pnpm --filter @octane-xplat/motion build`; run DOM/engine tests with
+`pnpm --filter @octane-xplat/motion test` and universal lifecycle tests with
+`pnpm --filter @octane-xplat/motion exec vitest run --config vitest.native.config.mts`.
+Native compilation and object-driver tests are not physical-device evidence.

package/UPSTREAM.md

@@ -0,0 +1,61 @@
+# Motion compatibility
+
+The behavioral reference is `@octanejs/motion` source package version 0.1.56,
+inspected from Octane main on 2026-09-29. Its UPSTREAM.md pins Motion 12.42.2
+(commit `40e8756c63b258c9dd07de9501cb788410eefb02`). This package pins
+`motion-dom@12.42.2` and bundles its pure numeric generators and interpolation.
+The adapter is original code; it does not copy upstream's DOM host factory.
+
+| Contract                                         | Upstream reference under packages/motion                          | Xplat implementation / evidence                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Initial and changing targets, equal destinations | src/index.ts; tests/conformance/rerender.test.ts, effects.test.ts | Compiled wrappers over UI; components.web.test.tsrx                                               |
+| Numeric spring/tween samples                     | Motion's motion-dom animation/generators                          | Reused generators; engine.test.ts compares irregular-time samples                                 |
+| Stable value, subscriptions, style replacement   | src/useMotionValue.ts; tests/conformance/motionValue.test.ts      | Numeric adapter with native clock; components.web.test.tsrx                                       |
+| Spring set versus jump; follow source            | src/useSpring.ts; tests/conformance/useSpring.test.ts             | Owned spring interception and cleanup; hook tests                                                 |
+| Derived numeric values                           | src/useTransform.ts; tests/conformance/useTransform.test.ts       | Upstream interpolation, direct subscriptions; hook tests                                          |
+| Config and reduced motion                        | src/context.ts; tests/conformance/reducedMotionConfig.test.ts     | Context inheritance; transforms settle immediately, opacity may animate                           |
+| Exit lifecycle                                   | src/index.ts; tests/conformance/exit.test.ts                      | Deliberate live-subtree retention on both leaves; presence.web.test.tsrx and native presence test |
+| Retained hosts on native                         | Not a DOM binding concern                                         | components.mobile.test.tsrx uses the universal object driver                                      |
+
+Source links: [Octane motion](https://github.com/octanejs/octane/tree/main/packages/motion),
+[upstream ledger](https://github.com/octanejs/octane/blob/main/packages/motion/UPSTREAM.md),
+[Motion pin](https://github.com/motiondivision/motion/tree/40e8756c63b258c9dd07de9501cb788410eefb02).
+
+## Deliberate boundaries
+
+- Numeric values only. No CSS strings, keyframe arrays, variants, layout,
+  gesture presets, declarative drag, or broad framework-neutral re-export.
+- Host APIs use shared UI names rather than DOM tags. Existing UI props remain
+  available; motion owns transform channels and opacity. Put pre-existing CSS
+  transforms on an outer container. Conflicting writers are errors.
+- `set` on a plain value stops its current animation, making gesture takeover
+  explicit and immediate. A spring value intercepts `set`; `jump` stops and snaps.
+- MotionConfig defaults to `reducedMotion="never"`, matching the reference;
+  choose `user` for system preferences. Config does not cross separate roots and
+  does not alter imperative value.animate calls: consult useReducedMotion there.
+- Timing uses a platform clock. NativeScript exposes frame scheduling through a
+  module; Motion's scheduler captures a global rAF and its values use browser
+  timing globals. The numeric adapter avoids changing application globals.
+- The same generator runs on web/native. WAAPI and native Animation acceleration
+  are deferred until interruption and transform composition preserve this contract.
+- Springs are physical (not duration/bounce based); duration belongs to tweens.
+  Default declarative transition is a 0.3-second easeInOut tween. Targets are
+  absolute; scale multiplies scaleX/scaleY. Opacity is clamped to 0–1 at the host. Reduced transforms have no delay.
+
+## Presence divergence
+
+`Presence present={...}` retains actual components and their state/subscriptions
+until all registered exits finish. Upstream's `AnimatePresence` is a passthrough
+and exiting DOM hosts clone themselves during cleanup. We deliberately do not
+reuse that path or claim its cleanup timing. Presence renders an explicit View
+wrapper, blocks interaction during exit, and restores interaction on reversal.
+An ancestor unmount always disposes immediately. Nested boundaries are independent.
+
+## Verification limits
+
+Unit and DOM tests establish bounded behavior, not full Framer Motion parity.
+Universal object-driver tests establish retention and lifecycle without an OS.
+Physical iOS/Android interruption, cancellation, gesture velocity/arbitration,
+background/resume, and frame pacing are pending. Native system preference
+observation polls at 500 ms while subscribed and refreshes on resume; Android
+uses animator_duration_scale. Real-device accessibility behavior remains pending.