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

package/dist/motion-value.cjs

@@ -0,0 +1,189 @@
+"use strict";
+// MotionValue implementation (REQ-VALUE-001/010/011/012). Clock-timestamped velocity follows
+// Motion 12.42.2's `motionValue.getVelocity` formula (the parity target pinned by M1b conformance):
+// velocity from the last two timed samples, zero once the last sample is older than the staleness
+// window, zero for non-numeric values. `subscribe` never triggers a host render.
+//
+// Two write paths, deliberately distinct (see M1-BUILD-PACKET gotchas): `set`/`jump` are the manual,
+// clock-timestamped path; `applyAnimationSample` is the animation path that writes value+velocity
+// straight from a generator without re-deriving velocity from the clock. While an animation drives
+// this value, `getVelocity` reports the animation velocity; a manual `set`/`jump` reverts to the
+// clock-sampled velocity. Methods below the public interface are internal seams for the graph.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MotionValueImpl = void 0;
+const collect_reads_1 = require("./collect-reads.cjs");
+const constants_1 = require("./config/constants.cjs");
+const subscriptions_1 = require("./subscriptions.cjs");
+class MotionValueImpl {
+    #clock;
+    #subs = new subscriptions_1.Subscriptions();
+    #current;
+    // Previous *numeric* sample and the two timestamps used for clock velocity. `#prev` is undefined
+    // whenever the prior value was non-numeric or after a teleport, which forces velocity to 0.
+    #prev;
+    #updatedAt;
+    #prevUpdatedAt;
+    // Velocity supplied by the driving animation, if any; takes precedence over the clock sample.
+    #animatedVelocity;
+    // Stop hook installed by the graph while an animation drives this value (REQ from `stop`).
+    #stopAnimation;
+    constructor(initial, clock) {
+        this.#current = initial;
+        this.#clock = clock;
+        this.#updatedAt = clock.now();
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#animatedVelocity = undefined;
+        this.#stopAnimation = undefined;
+    }
+    get() {
+        (0, collect_reads_1.reportMotionValueRead)(this);
+        return this.#current;
+    }
+    set(value) {
+        // Manual write reverts velocity tracking to the clock path.
+        this.#animatedVelocity = undefined;
+        // The pinned FRAME window (motion-dom updateAndNotify at the SS B pin, r15 4cf8a7d291e3):
+        // the previous sample rolls ONLY when time moved, so every same-frame write keeps
+        // comparing against the frame-START value and their velocities COMPOUND like the pin —
+        // never a per-write replacement that hides intra-frame motion.
+        const now = this.#clock.now();
+        if (now !== this.#updatedAt) {
+            this.#prev = typeof this.#current === 'number' ? this.#current : undefined;
+            this.#prevUpdatedAt = this.#updatedAt;
+            this.#updatedAt = now;
+        }
+        const previous = this.#current;
+        this.#current = value;
+        // Pinned suppression: an identical-value write does not notify (strict !== like the pin).
+        if (this.#current !== previous)
+            this.#subs.emitChange(this.#current);
+    }
+    jump(value) {
+        // Pinned jump ORDER (motion-dom `jump(v, endAnimation = true)`, r16/r17 — sealed by the
+        // motion-seams canary): (1) updateAndNotify — EXACTLY the set() path, so the change
+        // listener reads the teleport write's CLOCK velocity (never the generator's) with the
+        // animation still live; (2) the velocity window resets; (3) stop() — whose cancellation
+        // is notified while the animation is still observable and reads velocity 0. A dead flight
+        // can never overwrite the teleported value on the next frame (r15 59b71ef82c44).
+        this.set(value);
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#updatedAt = this.#clock.now();
+        this.stop();
+    }
+    subscribe(listener) {
+        return this.#subs.subscribe(listener);
+    }
+    getVelocity() {
+        if (this.#animatedVelocity !== undefined)
+            return this.#animatedVelocity;
+        const current = this.#current;
+        const prev = this.#prev;
+        const prevUpdatedAt = this.#prevUpdatedAt;
+        if (typeof current !== 'number' || prev === undefined || prevUpdatedAt === undefined)
+            return 0;
+        // Stale: no fresh sample within the window → treat as at rest (REQ-VALUE-011).
+        if (this.#clock.now() - this.#updatedAt > constants_1.MAX_VELOCITY_DELTA_MS)
+            return 0;
+        const dt = Math.min(this.#updatedAt - prevUpdatedAt, constants_1.MAX_VELOCITY_DELTA_MS);
+        if (dt <= 0)
+            return 0;
+        return ((current - prev) * 1000) / dt;
+    }
+    on(event, listener) {
+        // The implementation signature stays broad for delegation; it is NOT a public overload
+        // (r16 major 5 — lifecycle listeners are payload-free by contract).
+        return this.#subs.on(event, listener);
+    }
+    // The stop hook exists exactly while an animation drives this value (installed at animate,
+    // removed at endAnimation) — it IS the animation-liveness state, so no second flag can skew.
+    isAnimating() {
+        return this.#stopAnimation !== undefined;
+    }
+    stop() {
+        const stopper = this.#stopAnimation;
+        if (stopper === undefined)
+            return;
+        // Pinned lifecycle ORDER (r17, sealed by the motion-seams canary): the cancellation is
+        // notified while the animation is STILL OBSERVABLE (the pin clears `animation` only after
+        // notifying); the stopper — which also clears liveness through endAnimation — runs after.
+        // The emission lives here, not in destroy(), whose teardown is not a cancel.
+        this.#subs.emit('animationCancel');
+        stopper();
+    }
+    destroy() {
+        // Pinned teardown ORDER (r16 major 1): destroy announces itself FIRST — the listener
+        // observes the still-live animation — then the silent stop (never an animationCancel from
+        // teardown), then subscriptions drop.
+        this.#subs.emit('destroy');
+        this.#stopAnimation?.();
+        this.#subs.clear();
+    }
+    // --- internal seams for the graph (not part of the public MotionValue contract) ---------------
+    /**
+     * @internal Write an animation-produced sample: value and velocity straight from the generator,
+     * bypassing the clock-velocity path so velocity is not double-counted.
+     */
+    applyAnimationSample(value, velocity) {
+        this.#current = value;
+        this.#animatedVelocity = velocity;
+        this.#subs.emitChange(this.#current);
+    }
+    /** @internal Fire a lifecycle event (`animationStart`/`animationComplete`) on this value. */
+    emitEvent(event) {
+        this.#subs.emit(event);
+    }
+    /** @internal Install the stop hook the graph uses to wire `value.stop()` to the registry. */
+    attachAnimationStopper(stop) {
+        this.#stopAnimation = stop;
+    }
+    /**
+     * @internal Driver-port seam (REQ-VALUE-015): drop the stop hook WITHOUT invoking it — the
+     * token-blind public-control-slot clear changes `isAnimating()` only and must never stop the
+     * retained physical execution (pinned post-listener slot clear).
+     */
+    detachAnimationStopper() {
+        this.#stopAnimation = undefined;
+    }
+    /** @internal Driver-port seam: change-observer presence for transported-write classification. */
+    hasChangeObservers() {
+        return this.#subs.hasChangeObservers();
+    }
+    /** @internal Driver-port seam: derived-dependent presence among the change listeners. */
+    hasDerivedDependentObserver() {
+        return this.#subs.hasDerivedDependentObserver();
+    }
+    /**
+     * @internal Driver-port seam: adopt an externally transported numeric sample — the value plus
+     * its OWNED sample history (never clock re-derived) — with change notification under the
+     * caller's control: transported writes notify; guarded candidate-cache terminals and
+     * synchronous snapshots adopt silently. A throwing observer propagates unchanged (the pinned
+     * notify law); the caller owns drain progress accounting across that abort.
+     */
+    applyExternalNumericSample(value, previousValue, currentTimestampMs, previousTimestampMs, notifyChange) {
+        this.#animatedVelocity = undefined;
+        this.#current = value;
+        this.#prev = previousValue;
+        this.#prevUpdatedAt = previousTimestampMs;
+        this.#updatedAt = currentTimestampMs;
+        if (notifyChange)
+            this.#subs.emitChange(this.#current);
+    }
+    /**
+     * @internal Called when the animation driving this value ends (natural completion or stop). Puts
+     * the value at rest at its current value as of now: clears the animation velocity AND resets the
+     * clock-velocity samples (so `getVelocity` cannot leak a stale manual velocity from a `set` that
+     * preceded the animation, nor synthesize one from the animation's final value against a stale
+     * previous sample). Removes the stop hook. NOT called on interruption, where the current velocity
+     * must carry into the replacement generator's seed.
+     */
+    endAnimation() {
+        this.#animatedVelocity = undefined;
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#updatedAt = this.#clock.now();
+        this.#stopAnimation = undefined;
+    }
+}
+exports.MotionValueImpl = MotionValueImpl;

package/dist/motion-value.d.cts

@@ -0,0 +1,51 @@
+import type { Clock, MotionValue, MotionValueEvent, ValueChangeListener } from "./types.cjs";
+export declare class MotionValueImpl<T> implements MotionValue<T> {
+    #private;
+    constructor(initial: T, clock: Clock);
+    get(): T;
+    set(value: T): void;
+    jump(value: T): void;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    getVelocity(): number;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    isAnimating(): boolean;
+    stop(): void;
+    destroy(): void;
+    /**
+     * @internal Write an animation-produced sample: value and velocity straight from the generator,
+     * bypassing the clock-velocity path so velocity is not double-counted.
+     */
+    applyAnimationSample(value: T, velocity: number): void;
+    /** @internal Fire a lifecycle event (`animationStart`/`animationComplete`) on this value. */
+    emitEvent(event: Exclude<MotionValueEvent, 'change'>): void;
+    /** @internal Install the stop hook the graph uses to wire `value.stop()` to the registry. */
+    attachAnimationStopper(stop: () => void): void;
+    /**
+     * @internal Driver-port seam (REQ-VALUE-015): drop the stop hook WITHOUT invoking it — the
+     * token-blind public-control-slot clear changes `isAnimating()` only and must never stop the
+     * retained physical execution (pinned post-listener slot clear).
+     */
+    detachAnimationStopper(): void;
+    /** @internal Driver-port seam: change-observer presence for transported-write classification. */
+    hasChangeObservers(): boolean;
+    /** @internal Driver-port seam: derived-dependent presence among the change listeners. */
+    hasDerivedDependentObserver(): boolean;
+    /**
+     * @internal Driver-port seam: adopt an externally transported numeric sample — the value plus
+     * its OWNED sample history (never clock re-derived) — with change notification under the
+     * caller's control: transported writes notify; guarded candidate-cache terminals and
+     * synchronous snapshots adopt silently. A throwing observer propagates unchanged (the pinned
+     * notify law); the caller owns drain progress accounting across that abort.
+     */
+    applyExternalNumericSample(value: T, previousValue: number | undefined, currentTimestampMs: number, previousTimestampMs: number | undefined, notifyChange: boolean): void;
+    /**
+     * @internal Called when the animation driving this value ends (natural completion or stop). Puts
+     * the value at rest at its current value as of now: clears the animation velocity AND resets the
+     * clock-velocity samples (so `getVelocity` cannot leak a stale manual velocity from a `set` that
+     * preceded the animation, nor synthesize one from the animation's final value against a stale
+     * previous sample). Removes the stop hook. NOT called on interruption, where the current velocity
+     * must carry into the replacement generator's seed.
+     */
+    endAnimation(): void;
+}

package/dist/motion-value.d.ts

@@ -0,0 +1,51 @@
+import type { Clock, MotionValue, MotionValueEvent, ValueChangeListener } from "./types.js";
+export declare class MotionValueImpl<T> implements MotionValue<T> {
+    #private;
+    constructor(initial: T, clock: Clock);
+    get(): T;
+    set(value: T): void;
+    jump(value: T): void;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    getVelocity(): number;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    isAnimating(): boolean;
+    stop(): void;
+    destroy(): void;
+    /**
+     * @internal Write an animation-produced sample: value and velocity straight from the generator,
+     * bypassing the clock-velocity path so velocity is not double-counted.
+     */
+    applyAnimationSample(value: T, velocity: number): void;
+    /** @internal Fire a lifecycle event (`animationStart`/`animationComplete`) on this value. */
+    emitEvent(event: Exclude<MotionValueEvent, 'change'>): void;
+    /** @internal Install the stop hook the graph uses to wire `value.stop()` to the registry. */
+    attachAnimationStopper(stop: () => void): void;
+    /**
+     * @internal Driver-port seam (REQ-VALUE-015): drop the stop hook WITHOUT invoking it — the
+     * token-blind public-control-slot clear changes `isAnimating()` only and must never stop the
+     * retained physical execution (pinned post-listener slot clear).
+     */
+    detachAnimationStopper(): void;
+    /** @internal Driver-port seam: change-observer presence for transported-write classification. */
+    hasChangeObservers(): boolean;
+    /** @internal Driver-port seam: derived-dependent presence among the change listeners. */
+    hasDerivedDependentObserver(): boolean;
+    /**
+     * @internal Driver-port seam: adopt an externally transported numeric sample — the value plus
+     * its OWNED sample history (never clock re-derived) — with change notification under the
+     * caller's control: transported writes notify; guarded candidate-cache terminals and
+     * synchronous snapshots adopt silently. A throwing observer propagates unchanged (the pinned
+     * notify law); the caller owns drain progress accounting across that abort.
+     */
+    applyExternalNumericSample(value: T, previousValue: number | undefined, currentTimestampMs: number, previousTimestampMs: number | undefined, notifyChange: boolean): void;
+    /**
+     * @internal Called when the animation driving this value ends (natural completion or stop). Puts
+     * the value at rest at its current value as of now: clears the animation velocity AND resets the
+     * clock-velocity samples (so `getVelocity` cannot leak a stale manual velocity from a `set` that
+     * preceded the animation, nor synthesize one from the animation's final value against a stale
+     * previous sample). Removes the stop hook. NOT called on interruption, where the current velocity
+     * must carry into the replacement generator's seed.
+     */
+    endAnimation(): void;
+}

package/dist/motion-value.js

@@ -0,0 +1,185 @@
+// MotionValue implementation (REQ-VALUE-001/010/011/012). Clock-timestamped velocity follows
+// Motion 12.42.2's `motionValue.getVelocity` formula (the parity target pinned by M1b conformance):
+// velocity from the last two timed samples, zero once the last sample is older than the staleness
+// window, zero for non-numeric values. `subscribe` never triggers a host render.
+//
+// Two write paths, deliberately distinct (see M1-BUILD-PACKET gotchas): `set`/`jump` are the manual,
+// clock-timestamped path; `applyAnimationSample` is the animation path that writes value+velocity
+// straight from a generator without re-deriving velocity from the clock. While an animation drives
+// this value, `getVelocity` reports the animation velocity; a manual `set`/`jump` reverts to the
+// clock-sampled velocity. Methods below the public interface are internal seams for the graph.
+import { reportMotionValueRead } from "./collect-reads.js";
+import { MAX_VELOCITY_DELTA_MS } from "./config/constants.js";
+import { Subscriptions } from "./subscriptions.js";
+export class MotionValueImpl {
+    #clock;
+    #subs = new Subscriptions();
+    #current;
+    // Previous *numeric* sample and the two timestamps used for clock velocity. `#prev` is undefined
+    // whenever the prior value was non-numeric or after a teleport, which forces velocity to 0.
+    #prev;
+    #updatedAt;
+    #prevUpdatedAt;
+    // Velocity supplied by the driving animation, if any; takes precedence over the clock sample.
+    #animatedVelocity;
+    // Stop hook installed by the graph while an animation drives this value (REQ from `stop`).
+    #stopAnimation;
+    constructor(initial, clock) {
+        this.#current = initial;
+        this.#clock = clock;
+        this.#updatedAt = clock.now();
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#animatedVelocity = undefined;
+        this.#stopAnimation = undefined;
+    }
+    get() {
+        reportMotionValueRead(this);
+        return this.#current;
+    }
+    set(value) {
+        // Manual write reverts velocity tracking to the clock path.
+        this.#animatedVelocity = undefined;
+        // The pinned FRAME window (motion-dom updateAndNotify at the SS B pin, r15 4cf8a7d291e3):
+        // the previous sample rolls ONLY when time moved, so every same-frame write keeps
+        // comparing against the frame-START value and their velocities COMPOUND like the pin —
+        // never a per-write replacement that hides intra-frame motion.
+        const now = this.#clock.now();
+        if (now !== this.#updatedAt) {
+            this.#prev = typeof this.#current === 'number' ? this.#current : undefined;
+            this.#prevUpdatedAt = this.#updatedAt;
+            this.#updatedAt = now;
+        }
+        const previous = this.#current;
+        this.#current = value;
+        // Pinned suppression: an identical-value write does not notify (strict !== like the pin).
+        if (this.#current !== previous)
+            this.#subs.emitChange(this.#current);
+    }
+    jump(value) {
+        // Pinned jump ORDER (motion-dom `jump(v, endAnimation = true)`, r16/r17 — sealed by the
+        // motion-seams canary): (1) updateAndNotify — EXACTLY the set() path, so the change
+        // listener reads the teleport write's CLOCK velocity (never the generator's) with the
+        // animation still live; (2) the velocity window resets; (3) stop() — whose cancellation
+        // is notified while the animation is still observable and reads velocity 0. A dead flight
+        // can never overwrite the teleported value on the next frame (r15 59b71ef82c44).
+        this.set(value);
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#updatedAt = this.#clock.now();
+        this.stop();
+    }
+    subscribe(listener) {
+        return this.#subs.subscribe(listener);
+    }
+    getVelocity() {
+        if (this.#animatedVelocity !== undefined)
+            return this.#animatedVelocity;
+        const current = this.#current;
+        const prev = this.#prev;
+        const prevUpdatedAt = this.#prevUpdatedAt;
+        if (typeof current !== 'number' || prev === undefined || prevUpdatedAt === undefined)
+            return 0;
+        // Stale: no fresh sample within the window → treat as at rest (REQ-VALUE-011).
+        if (this.#clock.now() - this.#updatedAt > MAX_VELOCITY_DELTA_MS)
+            return 0;
+        const dt = Math.min(this.#updatedAt - prevUpdatedAt, MAX_VELOCITY_DELTA_MS);
+        if (dt <= 0)
+            return 0;
+        return ((current - prev) * 1000) / dt;
+    }
+    on(event, listener) {
+        // The implementation signature stays broad for delegation; it is NOT a public overload
+        // (r16 major 5 — lifecycle listeners are payload-free by contract).
+        return this.#subs.on(event, listener);
+    }
+    // The stop hook exists exactly while an animation drives this value (installed at animate,
+    // removed at endAnimation) — it IS the animation-liveness state, so no second flag can skew.
+    isAnimating() {
+        return this.#stopAnimation !== undefined;
+    }
+    stop() {
+        const stopper = this.#stopAnimation;
+        if (stopper === undefined)
+            return;
+        // Pinned lifecycle ORDER (r17, sealed by the motion-seams canary): the cancellation is
+        // notified while the animation is STILL OBSERVABLE (the pin clears `animation` only after
+        // notifying); the stopper — which also clears liveness through endAnimation — runs after.
+        // The emission lives here, not in destroy(), whose teardown is not a cancel.
+        this.#subs.emit('animationCancel');
+        stopper();
+    }
+    destroy() {
+        // Pinned teardown ORDER (r16 major 1): destroy announces itself FIRST — the listener
+        // observes the still-live animation — then the silent stop (never an animationCancel from
+        // teardown), then subscriptions drop.
+        this.#subs.emit('destroy');
+        this.#stopAnimation?.();
+        this.#subs.clear();
+    }
+    // --- internal seams for the graph (not part of the public MotionValue contract) ---------------
+    /**
+     * @internal Write an animation-produced sample: value and velocity straight from the generator,
+     * bypassing the clock-velocity path so velocity is not double-counted.
+     */
+    applyAnimationSample(value, velocity) {
+        this.#current = value;
+        this.#animatedVelocity = velocity;
+        this.#subs.emitChange(this.#current);
+    }
+    /** @internal Fire a lifecycle event (`animationStart`/`animationComplete`) on this value. */
+    emitEvent(event) {
+        this.#subs.emit(event);
+    }
+    /** @internal Install the stop hook the graph uses to wire `value.stop()` to the registry. */
+    attachAnimationStopper(stop) {
+        this.#stopAnimation = stop;
+    }
+    /**
+     * @internal Driver-port seam (REQ-VALUE-015): drop the stop hook WITHOUT invoking it — the
+     * token-blind public-control-slot clear changes `isAnimating()` only and must never stop the
+     * retained physical execution (pinned post-listener slot clear).
+     */
+    detachAnimationStopper() {
+        this.#stopAnimation = undefined;
+    }
+    /** @internal Driver-port seam: change-observer presence for transported-write classification. */
+    hasChangeObservers() {
+        return this.#subs.hasChangeObservers();
+    }
+    /** @internal Driver-port seam: derived-dependent presence among the change listeners. */
+    hasDerivedDependentObserver() {
+        return this.#subs.hasDerivedDependentObserver();
+    }
+    /**
+     * @internal Driver-port seam: adopt an externally transported numeric sample — the value plus
+     * its OWNED sample history (never clock re-derived) — with change notification under the
+     * caller's control: transported writes notify; guarded candidate-cache terminals and
+     * synchronous snapshots adopt silently. A throwing observer propagates unchanged (the pinned
+     * notify law); the caller owns drain progress accounting across that abort.
+     */
+    applyExternalNumericSample(value, previousValue, currentTimestampMs, previousTimestampMs, notifyChange) {
+        this.#animatedVelocity = undefined;
+        this.#current = value;
+        this.#prev = previousValue;
+        this.#prevUpdatedAt = previousTimestampMs;
+        this.#updatedAt = currentTimestampMs;
+        if (notifyChange)
+            this.#subs.emitChange(this.#current);
+    }
+    /**
+     * @internal Called when the animation driving this value ends (natural completion or stop). Puts
+     * the value at rest at its current value as of now: clears the animation velocity AND resets the
+     * clock-velocity samples (so `getVelocity` cannot leak a stale manual velocity from a `set` that
+     * preceded the animation, nor synthesize one from the animation's final value against a stale
+     * previous sample). Removes the stop hook. NOT called on interruption, where the current velocity
+     * must carry into the replacement generator's seed.
+     */
+    endAnimation() {
+        this.#animatedVelocity = undefined;
+        this.#prev = undefined;
+        this.#prevUpdatedAt = undefined;
+        this.#updatedAt = this.#clock.now();
+        this.#stopAnimation = undefined;
+    }
+}