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

package/dist/driver/step.cjs

@@ -0,0 +1,55 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-NATIVE-DRIVER §Requirements — the pure, time-integrated per-frame step (REQ-DRIVER-012/015). Each
+// animated property advances by ACCUMULATED elapsed time and reads its value off a generator — the
+// SPRING/TIMING analytic trajectory, single-sourced (REQ-DRIVER-003: the driver executes motion, it never
+// defines it). The step is a pure function of `(state, elapsedMs)`: it mutates the passed-in state in place
+// (allocation-free hot path, REQ-DRIVER-015 — the "shared-value write") and reads no clock, host, or
+// wall-clock time. Because the value is sampled at accumulated elapsed time, the trajectory at simulated
+// `t` is invariant to how `[0, t]` is partitioned into frames. Host-agnostic (REQ-CORE-003): relative
+// imports only.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampElapsed = clampElapsed;
+exports.stepProp = stepProp;
+const constants_1 = require("../config/constants.cjs");
+// Clamp one frame's elapsed time to the core dt-ceiling (REQ-CLOCK-003 / REQ-DRIVER-012), single-sourced in
+// `config/constants` — consumed here, never re-declared. A post-background gap advances the trajectory by
+// at most the ceiling, so a large real-time jump cannot teleport a value past its target.
+function clampElapsed(elapsedMs) {
+    return elapsedMs > constants_1.DT_CLAMP_MS ? constants_1.DT_CLAMP_MS : elapsedMs;
+}
+// Advance one property by a single (clamped) frame. Mutates `prop` in place; deterministic in
+// `(prop, elapsedMs)`. A settled property holds — it neither advances nor re-samples (REQ-DRIVER-020
+// quiesce, and O(active) work, REQ-DRIVER-015). Sampling at the accumulated elapsed time is what makes the
+// trajectory dt-cadence invariant (REQ-DRIVER-012).
+function stepProp(prop, elapsedMs) {
+    if (prop.done)
+        return;
+    const delta = clampElapsed(elapsedMs);
+    const next = prop.elapsed + delta;
+    if (delta > 0 && next === prop.elapsed) {
+        // Precision-freeze termination (r12 major 4f6e2d1b8a70; sampling corrected r13 major
+        // 7f1c9e2a4b60): the accumulator has exhausted float precision at this cadence
+        // (ulp(elapsed) > delta) — no future frame can advance it, so an un-done trajectory
+        // would stay active FOREVER. Terminate at the trajectory's settled state: sampled at
+        // max(elapsed, SETTLE_HORIZON_MS) — never a REWIND (a pre-seeded elapsed beyond the
+        // horizon keeps its own, already-final sample) and always at-or-past the instant
+        // validateTransition guarantees every accepted config is done. Zero-delta frames are
+        // untouched (the tick-count purity pin).
+        prop.value =
+            prop.generator.finalValue ??
+                prop.generator.sample(Math.max(prop.elapsed, constants_1.SETTLE_HORIZON_MS)).value;
+        prop.done = true;
+        return;
+    }
+    prop.elapsed = next;
+    const sample = prop.generator.sample(prop.elapsed);
+    // The pin's `getFinalKeyframe` position: `JSAnimation` applies it INSIDE `tick`, gated on
+    // `holdTime === null && (state === 'finished' || (state === 'running' && done))`, and only then
+    // calls `finish()`, which never touches the value. So a trajectory whose resting value differs
+    // from its terminal sample commits the former. Only a fractional `repeat` fold declares one today (REQ-TIMING-003) — everything else
+    // leaves `finalValue` absent and is untouched. Applied here rather than in the fold so BOTH
+    // drivers inherit it from one implementation, and so `sample` stays a faithful seek.
+    prop.value = sample.done ? (prop.generator.finalValue ?? sample.value) : sample.value;
+    prop.done = sample.done;
+}

package/dist/driver/step.d.cts

@@ -0,0 +1,9 @@
+import type { Generator } from "../types.cjs";
+export interface PropStep {
+    readonly generator: Generator;
+    elapsed: number;
+    value: number;
+    done: boolean;
+}
+export declare function clampElapsed(elapsedMs: number): number;
+export declare function stepProp(prop: PropStep, elapsedMs: number): void;

package/dist/driver/step.d.ts

@@ -0,0 +1,9 @@
+import type { Generator } from "../types.js";
+export interface PropStep {
+    readonly generator: Generator;
+    elapsed: number;
+    value: number;
+    done: boolean;
+}
+export declare function clampElapsed(elapsedMs: number): number;
+export declare function stepProp(prop: PropStep, elapsedMs: number): void;

package/dist/driver/step.js

@@ -0,0 +1,52 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-NATIVE-DRIVER §Requirements — the pure, time-integrated per-frame step (REQ-DRIVER-012/015). Each
+// animated property advances by ACCUMULATED elapsed time and reads its value off a generator — the
+// SPRING/TIMING analytic trajectory, single-sourced (REQ-DRIVER-003: the driver executes motion, it never
+// defines it). The step is a pure function of `(state, elapsedMs)`: it mutates the passed-in state in place
+// (allocation-free hot path, REQ-DRIVER-015 — the "shared-value write") and reads no clock, host, or
+// wall-clock time. Because the value is sampled at accumulated elapsed time, the trajectory at simulated
+// `t` is invariant to how `[0, t]` is partitioned into frames. Host-agnostic (REQ-CORE-003): relative
+// imports only.
+import { DT_CLAMP_MS, SETTLE_HORIZON_MS } from "../config/constants.js";
+// Clamp one frame's elapsed time to the core dt-ceiling (REQ-CLOCK-003 / REQ-DRIVER-012), single-sourced in
+// `config/constants` — consumed here, never re-declared. A post-background gap advances the trajectory by
+// at most the ceiling, so a large real-time jump cannot teleport a value past its target.
+export function clampElapsed(elapsedMs) {
+    return elapsedMs > DT_CLAMP_MS ? DT_CLAMP_MS : elapsedMs;
+}
+// Advance one property by a single (clamped) frame. Mutates `prop` in place; deterministic in
+// `(prop, elapsedMs)`. A settled property holds — it neither advances nor re-samples (REQ-DRIVER-020
+// quiesce, and O(active) work, REQ-DRIVER-015). Sampling at the accumulated elapsed time is what makes the
+// trajectory dt-cadence invariant (REQ-DRIVER-012).
+export function stepProp(prop, elapsedMs) {
+    if (prop.done)
+        return;
+    const delta = clampElapsed(elapsedMs);
+    const next = prop.elapsed + delta;
+    if (delta > 0 && next === prop.elapsed) {
+        // Precision-freeze termination (r12 major 4f6e2d1b8a70; sampling corrected r13 major
+        // 7f1c9e2a4b60): the accumulator has exhausted float precision at this cadence
+        // (ulp(elapsed) > delta) — no future frame can advance it, so an un-done trajectory
+        // would stay active FOREVER. Terminate at the trajectory's settled state: sampled at
+        // max(elapsed, SETTLE_HORIZON_MS) — never a REWIND (a pre-seeded elapsed beyond the
+        // horizon keeps its own, already-final sample) and always at-or-past the instant
+        // validateTransition guarantees every accepted config is done. Zero-delta frames are
+        // untouched (the tick-count purity pin).
+        prop.value =
+            prop.generator.finalValue ??
+                prop.generator.sample(Math.max(prop.elapsed, SETTLE_HORIZON_MS)).value;
+        prop.done = true;
+        return;
+    }
+    prop.elapsed = next;
+    const sample = prop.generator.sample(prop.elapsed);
+    // The pin's `getFinalKeyframe` position: `JSAnimation` applies it INSIDE `tick`, gated on
+    // `holdTime === null && (state === 'finished' || (state === 'running' && done))`, and only then
+    // calls `finish()`, which never touches the value. So a trajectory whose resting value differs
+    // from its terminal sample commits the former. Only a fractional `repeat` fold declares one today (REQ-TIMING-003) — everything else
+    // leaves `finalValue` absent and is untouched. Applied here rather than in the fold so BOTH
+    // drivers inherit it from one implementation, and so `sample` stays a faithful seek.
+    prop.value = sample.done ? (prop.generator.finalValue ?? sample.value) : sample.value;
+    prop.done = sample.done;
+}

package/dist/driver/tiers.cjs

@@ -0,0 +1,40 @@
+"use strict";
+// SPEC-NATIVE-DRIVER §Requirements — prop-tier classification (REQ-DRIVER-017). The driver routes each
+// animatable property to one of two substrate execution paths, DERIVED from the SUBSET registry class (a
+// single source — never a second hand-list) so a new prop key auto-tiers by its class. Host-agnostic
+// (REQ-CORE-003): relative imports only.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tierFor = tierFor;
+const subset_1 = require("../subset/index.cjs");
+// CapabilityClass → tier. This is a `Record` over the CLOSED class union, so adding a class to the registry
+// breaks this build until it is tiered here — a compile-time drift guard. `null` means the class carries no
+// execution tier: `gesture` is not an animatable value; `webEffect` has no native execution strategy yet.
+// The commit-tier membership of visual-but-layout-classed props (e.g. `borderRadius`) is the §G vetoable —
+// conservatively commit here (registry-class-derived), a candidate fast-tier promotion pending human review.
+const TIER_BY_CLASS = {
+    transform: 'fast',
+    opacity: 'fast',
+    color: 'fast',
+    layoutProp: 'commit',
+    // Discrete keywords (T23 B) execute on the color-lane pattern — a shared-value progress channel
+    // projected in the style worklet, no per-frame Yoga commit and no settle-reconcile obligation
+    // (the step writes the keyword at most twice per animation). `display: none↔flex` reflows when
+    // the step FIRES, but that is the property's own semantic, not a commit-tier animation.
+    discrete: 'fast',
+    gesture: null,
+    webEffect: null,
+};
+// Resolve a property's execution tier, or fail loud (REQ-DRIVER-017 / REQ-API-005): an unknown property and
+// a non-animatable class both throw a descriptive error naming the property — the driver never silently
+// mis-routes or drops a prop.
+function tierFor(key) {
+    const entry = subset_1.UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        throw new Error(`no driver execution tier for '${key}': it is not a Universal-Subset property.`);
+    }
+    const tier = TIER_BY_CLASS[entry.class];
+    if (tier === null) {
+        throw new Error(`'${key}' (class '${entry.class}') is not a driver-animatable value; it has no execution tier.`);
+    }
+    return tier;
+}

package/dist/driver/tiers.d.cts

@@ -0,0 +1,2 @@
+export type PropTier = 'fast' | 'commit';
+export declare function tierFor(key: string): PropTier;

package/dist/driver/tiers.d.ts

@@ -0,0 +1,2 @@
+export type PropTier = 'fast' | 'commit';
+export declare function tierFor(key: string): PropTier;

package/dist/driver/tiers.js

@@ -0,0 +1,37 @@
+// SPEC-NATIVE-DRIVER §Requirements — prop-tier classification (REQ-DRIVER-017). The driver routes each
+// animatable property to one of two substrate execution paths, DERIVED from the SUBSET registry class (a
+// single source — never a second hand-list) so a new prop key auto-tiers by its class. Host-agnostic
+// (REQ-CORE-003): relative imports only.
+import { UNIVERSAL_SUBSET } from "../subset/index.js";
+// CapabilityClass → tier. This is a `Record` over the CLOSED class union, so adding a class to the registry
+// breaks this build until it is tiered here — a compile-time drift guard. `null` means the class carries no
+// execution tier: `gesture` is not an animatable value; `webEffect` has no native execution strategy yet.
+// The commit-tier membership of visual-but-layout-classed props (e.g. `borderRadius`) is the §G vetoable —
+// conservatively commit here (registry-class-derived), a candidate fast-tier promotion pending human review.
+const TIER_BY_CLASS = {
+    transform: 'fast',
+    opacity: 'fast',
+    color: 'fast',
+    layoutProp: 'commit',
+    // Discrete keywords (T23 B) execute on the color-lane pattern — a shared-value progress channel
+    // projected in the style worklet, no per-frame Yoga commit and no settle-reconcile obligation
+    // (the step writes the keyword at most twice per animation). `display: none↔flex` reflows when
+    // the step FIRES, but that is the property's own semantic, not a commit-tier animation.
+    discrete: 'fast',
+    gesture: null,
+    webEffect: null,
+};
+// Resolve a property's execution tier, or fail loud (REQ-DRIVER-017 / REQ-API-005): an unknown property and
+// a non-animatable class both throw a descriptive error naming the property — the driver never silently
+// mis-routes or drops a prop.
+export function tierFor(key) {
+    const entry = UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        throw new Error(`no driver execution tier for '${key}': it is not a Universal-Subset property.`);
+    }
+    const tier = TIER_BY_CLASS[entry.class];
+    if (tier === null) {
+        throw new Error(`'${key}' (class '${entry.class}') is not a driver-animatable value; it has no execution tier.`);
+    }
+    return tier;
+}

package/dist/driver/types.cjs

@@ -0,0 +1,9 @@
+"use strict";
+// SPEC-NATIVE-DRIVER §Requirements — the host-agnostic Driver interface + command types (REQ-DRIVER-010/
+// 013). `core` DEFINES this interface; the native worklet driver and the web driver are peers that
+// IMPLEMENT it (they import core; core imports no driver, no host, no `react-native-*`). The interface is
+// the sole coupling point, so the substrate is replaceable without changing the public contract. The
+// command surface is a discriminated union — an illegal command is unrepresentable, no permissive index
+// signature, no `any` (REQ-DRIVER-015 type discipline). Host-agnostic (REQ-CORE-003): imports only the
+// public `Transition` shape (relative).
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/driver/types.d.cts

@@ -0,0 +1,68 @@
+import type { Transition } from "../component/index.cjs";
+import type { PathChannelGeometry } from "../motion-arc.cjs";
+import type { DefaultTransition, InertiaTransition } from "../transition.cjs";
+export type InternalDriverTransition = Transition | DefaultTransition | InertiaTransition;
+export type PropTransition = InternalDriverTransition;
+export interface PathChannelSpec extends PathChannelGeometry {
+    readonly transition: PropTransition;
+}
+export type ElementHandle = number & {
+    readonly __elementHandle: unique symbol;
+};
+export type PropTargetTo = number | readonly (number | null)[];
+export interface PropTarget {
+    readonly to: PropTargetTo;
+    readonly from: number;
+    readonly velocity?: number;
+    readonly transition?: PropTransition;
+}
+export interface PreparedPropTarget {
+    readonly to: PropTargetTo;
+    readonly from: number;
+    readonly velocity: number;
+    readonly transition: PropTransition;
+}
+export interface LivePropState {
+    readonly value: number;
+    readonly velocity: number;
+}
+export type DriverCommand = {
+    readonly kind: 'start';
+    readonly targets: Readonly<Record<string, PropTarget>>;
+    readonly transition: Transition;
+    readonly releasesGesture?: boolean;
+    readonly path?: PathChannelSpec;
+} | {
+    readonly kind: 'retarget';
+    readonly targets: Readonly<Record<string, number>>;
+    readonly transition: Transition;
+    readonly targetTransitions?: Readonly<Record<string, PropTransition>>;
+} | {
+    readonly kind: 'stop';
+};
+export type PreparedDriverCommand = {
+    readonly kind: 'start';
+    readonly targets: Readonly<Record<string, PreparedPropTarget>>;
+    readonly releasesGesture: boolean;
+    readonly path?: PathChannelSpec;
+} | {
+    readonly kind: 'retarget';
+    readonly targets: Readonly<Record<string, number>>;
+    readonly transition: Transition;
+    readonly targetTransitions?: Readonly<Record<string, PropTransition>>;
+} | {
+    readonly kind: 'stop';
+};
+export interface Driver {
+    register(initial: Readonly<Record<string, number>>): ElementHandle;
+    command(handle: ElementHandle, command: DriverCommand): void;
+    step(elapsedMs: number): void;
+    committed(handle: ElementHandle): Readonly<Record<string, number>>;
+    setActive(handle: ElementHandle, active: boolean): void;
+    isActive(handle: ElementHandle): boolean;
+    write(handle: ElementHandle, values: Readonly<Record<string, number>>, velocities?: Readonly<Record<string, number>>): void;
+    liveFor(handle: ElementHandle, key: string): LivePropState;
+}
+export type PreparedDriver = Omit<Driver, 'command'> & {
+    command(handle: ElementHandle, command: PreparedDriverCommand): void;
+};

package/dist/driver/types.d.ts

@@ -0,0 +1,68 @@
+import type { Transition } from "../component/index.js";
+import type { PathChannelGeometry } from "../motion-arc.js";
+import type { DefaultTransition, InertiaTransition } from "../transition.js";
+export type InternalDriverTransition = Transition | DefaultTransition | InertiaTransition;
+export type PropTransition = InternalDriverTransition;
+export interface PathChannelSpec extends PathChannelGeometry {
+    readonly transition: PropTransition;
+}
+export type ElementHandle = number & {
+    readonly __elementHandle: unique symbol;
+};
+export type PropTargetTo = number | readonly (number | null)[];
+export interface PropTarget {
+    readonly to: PropTargetTo;
+    readonly from: number;
+    readonly velocity?: number;
+    readonly transition?: PropTransition;
+}
+export interface PreparedPropTarget {
+    readonly to: PropTargetTo;
+    readonly from: number;
+    readonly velocity: number;
+    readonly transition: PropTransition;
+}
+export interface LivePropState {
+    readonly value: number;
+    readonly velocity: number;
+}
+export type DriverCommand = {
+    readonly kind: 'start';
+    readonly targets: Readonly<Record<string, PropTarget>>;
+    readonly transition: Transition;
+    readonly releasesGesture?: boolean;
+    readonly path?: PathChannelSpec;
+} | {
+    readonly kind: 'retarget';
+    readonly targets: Readonly<Record<string, number>>;
+    readonly transition: Transition;
+    readonly targetTransitions?: Readonly<Record<string, PropTransition>>;
+} | {
+    readonly kind: 'stop';
+};
+export type PreparedDriverCommand = {
+    readonly kind: 'start';
+    readonly targets: Readonly<Record<string, PreparedPropTarget>>;
+    readonly releasesGesture: boolean;
+    readonly path?: PathChannelSpec;
+} | {
+    readonly kind: 'retarget';
+    readonly targets: Readonly<Record<string, number>>;
+    readonly transition: Transition;
+    readonly targetTransitions?: Readonly<Record<string, PropTransition>>;
+} | {
+    readonly kind: 'stop';
+};
+export interface Driver {
+    register(initial: Readonly<Record<string, number>>): ElementHandle;
+    command(handle: ElementHandle, command: DriverCommand): void;
+    step(elapsedMs: number): void;
+    committed(handle: ElementHandle): Readonly<Record<string, number>>;
+    setActive(handle: ElementHandle, active: boolean): void;
+    isActive(handle: ElementHandle): boolean;
+    write(handle: ElementHandle, values: Readonly<Record<string, number>>, velocities?: Readonly<Record<string, number>>): void;
+    liveFor(handle: ElementHandle, key: string): LivePropState;
+}
+export type PreparedDriver = Omit<Driver, 'command'> & {
+    command(handle: ElementHandle, command: PreparedDriverCommand): void;
+};

package/dist/driver/types.js

@@ -0,0 +1,8 @@
+// SPEC-NATIVE-DRIVER §Requirements — the host-agnostic Driver interface + command types (REQ-DRIVER-010/
+// 013). `core` DEFINES this interface; the native worklet driver and the web driver are peers that
+// IMPLEMENT it (they import core; core imports no driver, no host, no `react-native-*`). The interface is
+// the sole coupling point, so the substrate is replaceable without changing the public contract. The
+// command surface is a discriminated union — an illegal command is unrepresentable, no permissive index
+// signature, no `any` (REQ-DRIVER-015 type discipline). Host-agnostic (REQ-CORE-003): imports only the
+// public `Transition` shape (relative).
+export {};