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

package/dist/gesture/viewportConstraints.cjs

@@ -0,0 +1,38 @@
+"use strict";
+// REQ-GESTURE-028 (R15 D2) — the VIEWPORT constraints computation, the pin's
+// `calcViewportAxisConstraints` verbatim (framer-motion `drag/utils/constraints.ts` at the §B
+// pin, motion@12.42.2 / 61833240): bounds for the drag value relative to the draggable's
+// CURRENT layout box at grab — `min = container.min − layout.min`,
+// `max = container.max − layout.max` — then FLIPPED per axis when the container is shorter
+// than the child (the negative-range case: the child fits past both edges). Host-agnostic
+// (REQ-CORE-003); both engines compute identical bounds from the same measured boxes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveViewportConstraints = resolveViewportConstraints;
+exports.progressWithinSpan = progressWithinSpan;
+// One axis of viewport constraints. `layout` is the draggable's CURRENT layout span at grab;
+// `container` is the measured constraint element's span (already corrected into the same
+// coordinate space).
+function resolveViewportConstraints(layout, container) {
+    let min = container.min - layout.min;
+    let max = container.max - layout.max;
+    // The pin's flip: when the container is SHORTER than the child, swap the pair (the child
+    // can only rubber-band past both edges — the range is negative before the swap).
+    if (container.max - container.min < layout.max - layout.min) {
+        ;
+        [min, max] = [max, min];
+    }
+    return { min, max };
+}
+// The pin's `calcOrigin` for a point source (VEDC scalePositionWithinConstraints, review
+// major 3): the progress of a value within a constraint span, clamped to [0, 1]. A degenerate
+// (zero-length) span reports 0.5 — the pin's neither-branch case exactly. TOTAL (review r4
+// major 3): a non-finite span (an open-sided hook replacement, legal) yields no NaN — an
+// open-ended progress is unrepresentable, reported as the degenerate 0.5; callers that can
+// keep the live value should (the wiring's rescale does).
+function progressWithinSpan(value, span) {
+    const length = span.max - span.min;
+    if (!Number.isFinite(length) || length <= 0)
+        return 0.5;
+    const progress = (value - span.min) / length;
+    return progress < 0 ? 0 : progress > 1 ? 1 : progress;
+}

package/dist/gesture/viewportConstraints.d.cts

@@ -0,0 +1,6 @@
+export interface AxisSpan {
+    readonly min: number;
+    readonly max: number;
+}
+export declare function resolveViewportConstraints(layout: AxisSpan, container: AxisSpan): AxisSpan;
+export declare function progressWithinSpan(value: number, span: AxisSpan): number;

package/dist/gesture/viewportConstraints.d.ts

@@ -0,0 +1,6 @@
+export interface AxisSpan {
+    readonly min: number;
+    readonly max: number;
+}
+export declare function resolveViewportConstraints(layout: AxisSpan, container: AxisSpan): AxisSpan;
+export declare function progressWithinSpan(value: number, span: AxisSpan): number;

package/dist/gesture/viewportConstraints.js

@@ -0,0 +1,34 @@
+// REQ-GESTURE-028 (R15 D2) — the VIEWPORT constraints computation, the pin's
+// `calcViewportAxisConstraints` verbatim (framer-motion `drag/utils/constraints.ts` at the §B
+// pin, motion@12.42.2 / 61833240): bounds for the drag value relative to the draggable's
+// CURRENT layout box at grab — `min = container.min − layout.min`,
+// `max = container.max − layout.max` — then FLIPPED per axis when the container is shorter
+// than the child (the negative-range case: the child fits past both edges). Host-agnostic
+// (REQ-CORE-003); both engines compute identical bounds from the same measured boxes.
+// One axis of viewport constraints. `layout` is the draggable's CURRENT layout span at grab;
+// `container` is the measured constraint element's span (already corrected into the same
+// coordinate space).
+export function resolveViewportConstraints(layout, container) {
+    let min = container.min - layout.min;
+    let max = container.max - layout.max;
+    // The pin's flip: when the container is SHORTER than the child, swap the pair (the child
+    // can only rubber-band past both edges — the range is negative before the swap).
+    if (container.max - container.min < layout.max - layout.min) {
+        ;
+        [min, max] = [max, min];
+    }
+    return { min, max };
+}
+// The pin's `calcOrigin` for a point source (VEDC scalePositionWithinConstraints, review
+// major 3): the progress of a value within a constraint span, clamped to [0, 1]. A degenerate
+// (zero-length) span reports 0.5 — the pin's neither-branch case exactly. TOTAL (review r4
+// major 3): a non-finite span (an open-sided hook replacement, legal) yields no NaN — an
+// open-ended progress is unrepresentable, reported as the degenerate 0.5; callers that can
+// keep the live value should (the wiring's rescale does).
+export function progressWithinSpan(value, span) {
+    const length = span.max - span.min;
+    if (!Number.isFinite(length) || length <= 0)
+        return 0.5;
+    const progress = (value - span.min) / length;
+    return progress < 0 ? 0 : progress > 1 ? 1 : progress;
+}

package/dist/graph.cjs

@@ -0,0 +1,226 @@
+"use strict";
+// The motion graph: value factory, derived graph, animation registry, and settle ledger. Owns the
+// injected clock/scheduler and registers a single per-frame step. Each frame advances active
+// animations (by accumulated, dt-clamped elapsed), flushes dirty derived nodes in topological order,
+// then reconciles settle. Zero host dependencies (REQ-CORE-003).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMotionGraph = createMotionGraph;
+const motion_value_1 = require("./motion-value.cjs");
+const derived_1 = require("./derived.cjs");
+const constants_1 = require("./config/constants.cjs");
+/** Handle to one in-flight animation. `done` is true once it completes or is stopped/interrupted. */
+class AnimationHandle {
+    #finished = false;
+    #onStop;
+    constructor(onStop) {
+        this.#onStop = onStop;
+    }
+    get done() {
+        return this.#finished;
+    }
+    /** @internal Mark finished without running the stop hook (completion / interruption path). */
+    markFinished() {
+        this.#finished = true;
+    }
+    stop() {
+        if (this.#finished)
+            return;
+        this.#finished = true;
+        this.#onStop();
+    }
+}
+class MotionGraphImpl {
+    #clock;
+    // Dirty derived nodes live in a reusable creation-index-sorted slot list, not a Set
+    // (REQ-DRIVER-021, packet §6 ordinary local-JS repair): mark dedupes and inserts by indexed
+    // binary-search/shift, and the flush drains the front by index — no Set growth or iterator on
+    // the frame path. The sort keeps the drain exactly the old min-first topological order.
+    #dirtySlots = [];
+    #animations = new Map();
+    // Command-edge-grown completion slots: the frame step writes finished records by index and the
+    // completion pass drains by count — no fresh completion array, no Map iterator, no push.
+    #completedSlots = [];
+    #completedCount = 0;
+    #frameClampedDt = 0;
+    #creationCounter = 0;
+    #openActivities = 0;
+    #wasSettled = true;
+    // One retained settle-resolver list, drained by index and reset by length — never replaced
+    // with a fresh array on the settle edge.
+    #settleResolvers = [];
+    constructor(options) {
+        this.#clock = options.clock;
+        options.scheduler.onFrame((dtMs) => this.#frameStep(dtMs));
+    }
+    motionValue(initial) {
+        return new motion_value_1.MotionValueImpl(initial, this.#clock);
+    }
+    derived(inputs, compute) {
+        // Both public call shapes erase to this unknown[] implementation; the graph passes each
+        // input's live get() positionally, so the runtime match is by construction.
+        return new derived_1.DerivedValue(this.#creationCounter++, inputs, compute, (node) => this.#markDirtyIntoReusableSlot(node));
+    }
+    animate(value, factory) {
+        if (!(value instanceof motion_value_1.MotionValueImpl)) {
+            throw new Error('native-motion-core: animate() requires a MotionValue created by this graph, not a derived/read-only value');
+        }
+        // Interruption (REQ-CORE-002): stop the prior animation on this value and seed the new generator
+        // with the value's current value+velocity so motion continues from the present visual state.
+        // Replacing the map entry keeps the active count net-unchanged across the swap.
+        const prior = this.#animations.get(value);
+        if (prior) {
+            prior.handle.markFinished();
+            // Pinned lifecycle: the interrupted animation never completed — it was cancelled.
+            value.emitEvent('animationCancel');
+        }
+        const seed = { from: value.get(), velocity: value.getVelocity() };
+        const generator = factory(seed);
+        const handle = new AnimationHandle(() => this.#removeAnimation(value, handle));
+        this.#animations.set(value, { value, generator, handle, elapsedMs: 0 });
+        value.attachAnimationStopper(() => handle.stop());
+        value.emitEvent('animationStart');
+        this.#reconcileSettleFromPrefilledSlots();
+        return handle;
+    }
+    activeAnimationCount() {
+        return this.#animations.size;
+    }
+    registerActivity() {
+        this.#openActivities += 1;
+        this.#reconcileSettleFromPrefilledSlots();
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.#openActivities -= 1;
+                this.#reconcileSettleFromPrefilledSlots();
+            },
+        };
+    }
+    isSettled() {
+        return this.#animations.size === 0 && this.#openActivities === 0;
+    }
+    whenSettled() {
+        if (this.isSettled())
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#settleResolvers.push(resolve);
+        });
+    }
+    #markDirtyIntoReusableSlot(node) {
+        // Sorted insertion by creationIndex (unique per node): the membership check IS the binary
+        // search — an already-dirty node is found and skipped, exactly like the old Set dedupe.
+        const slots = this.#dirtySlots;
+        let lo = 0;
+        let hi = slots.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            const midIndex = slots[mid].creationIndex;
+            if (midIndex === node.creationIndex)
+                return;
+            if (midIndex < node.creationIndex)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        // Indexed tail shift; capacity grows only to the frame's high-water mark, then is reused.
+        for (let i = slots.length; i > lo; i--)
+            slots[i] = slots[i - 1];
+        slots[lo] = node;
+    }
+    #removeAnimation(value, handle) {
+        const record = this.#animations.get(value);
+        if (record && record.handle === handle) {
+            this.#animations.delete(value);
+            record.value.endAnimation();
+            this.#reconcileSettleFromPrefilledSlots();
+        }
+    }
+    // Stable per-instance frame callback for the active-animation scan: Map.prototype.forEach walks
+    // the map's internal slots (no per-frame iterator object) with the same live-iteration semantics
+    // as the old for..of — entries appended mid-scan are visited, deleted entries are skipped.
+    #sampleActiveAnimation = (record) => {
+        record.elapsedMs += this.#frameClampedDt;
+        const sample = record.generator.sample(record.elapsedMs);
+        record.value.applyAnimationSample(sample.value, sample.velocity);
+        if (sample.done) {
+            this.#completedSlots[this.#completedCount] = record;
+            this.#completedCount += 1;
+        }
+    };
+    #frameStep(dtMs) {
+        // REQ-CLOCK-003: clamp per-frame elapsed so a large gap after backgrounding does not jump the
+        // graph forward unbounded. Animations advance by accumulated clamped elapsed, which is also what
+        // makes the trajectory a pure function of elapsed time (dt-robust) when no clamp triggers.
+        this.#frameClampedDt = Math.min(dtMs, constants_1.DT_CLAMP_MS);
+        this.#completedCount = 0;
+        this.#animations.forEach(this.#sampleActiveAnimation);
+        this.#completeFinishedAnimationsFromPrefilledSlots();
+        // Animations write their target values before the derived flush, so derived values observe
+        // post-animation inputs within the same frame (glitch-free).
+        this.#flushDirtyDerivedFromPrefilledSlots();
+        this.#reconcileSettleFromPrefilledSlots();
+    }
+    #completeFinishedAnimationsFromPrefilledSlots() {
+        const completed = this.#completedSlots;
+        const count = this.#completedCount;
+        for (let i = 0; i < count; i++) {
+            const record = completed[i];
+            completed[i] = undefined;
+            record.handle.markFinished();
+            this.#animations.delete(record.value);
+            record.value.endAnimation();
+            record.value.emitEvent('animationComplete');
+        }
+    }
+    // Flush dirty derived nodes in ascending creation index. A node depends only on earlier-created
+    // nodes, so lowest-index-first is a valid topological order: recomputing a node may notify and
+    // re-dirty a higher-index dependent, which this same drain then processes — glitch-free within one
+    // frame. The graph is acyclic by construction; the iteration guard is a loud backstop (REQ-VALUE-013).
+    // The slot list is kept sorted by #markDirtyIntoReusableSlot, so the front IS the minimum — the
+    // drain pops it by indexed shift (no Set iterator per frame, REQ-DRIVER-021).
+    #flushDirtyDerivedFromPrefilledSlots() {
+        let guard = 0;
+        const maxIterations = 1_000_000;
+        const slots = this.#dirtySlots;
+        while (slots.length > 0) {
+            if (++guard > maxIterations) {
+                throw new Error('native-motion-core: derived graph flush did not converge (cycle detected)');
+            }
+            const next = slots[0];
+            for (let i = 1; i < slots.length; i++)
+                slots[i - 1] = slots[i];
+            slots.length -= 1;
+            next.flush();
+        }
+    }
+    // Settle ledger (REQ-SETTLE-001/002): the graph is settled iff no active animations and no open
+    // activity handles. Resolve pending `whenSettled` promises exactly on the transition into settled;
+    // re-arm on the transition out. Fail-closed: while any source is open, resolvers stay pending.
+    // The resolver list is retained and drained by index — never replaced by a fresh array.
+    #reconcileSettleFromPrefilledSlots() {
+        const settled = this.isSettled();
+        if (settled && !this.#wasSettled) {
+            this.#wasSettled = true;
+            const resolvers = this.#settleResolvers;
+            const count = resolvers.length;
+            // Invoke BEFORE clearing: truncating first would delete the very prefix being drained. A
+            // resolver-time whenSettled() appends past `count` and survives the drain, exactly like
+            // the old replacement array.
+            for (let i = 0; i < count; i++)
+                resolvers[i]();
+            let tail = 0;
+            for (let i = count; i < resolvers.length; i++)
+                resolvers[tail++] = resolvers[i];
+            resolvers.length = tail;
+        }
+        else if (!settled && this.#wasSettled) {
+            this.#wasSettled = false;
+        }
+    }
+}
+function createMotionGraph(options) {
+    return new MotionGraphImpl(options);
+}

package/dist/graph.d.cts

@@ -0,0 +1,2 @@
+import type { MotionGraph, MotionGraphOptions } from "./types.cjs";
+export declare function createMotionGraph(options: MotionGraphOptions): MotionGraph;

package/dist/graph.d.ts

@@ -0,0 +1,2 @@
+import type { MotionGraph, MotionGraphOptions } from "./types.js";
+export declare function createMotionGraph(options: MotionGraphOptions): MotionGraph;

package/dist/graph.js

@@ -0,0 +1,223 @@
+// The motion graph: value factory, derived graph, animation registry, and settle ledger. Owns the
+// injected clock/scheduler and registers a single per-frame step. Each frame advances active
+// animations (by accumulated, dt-clamped elapsed), flushes dirty derived nodes in topological order,
+// then reconciles settle. Zero host dependencies (REQ-CORE-003).
+import { MotionValueImpl } from "./motion-value.js";
+import { DerivedValue } from "./derived.js";
+import { DT_CLAMP_MS } from "./config/constants.js";
+/** Handle to one in-flight animation. `done` is true once it completes or is stopped/interrupted. */
+class AnimationHandle {
+    #finished = false;
+    #onStop;
+    constructor(onStop) {
+        this.#onStop = onStop;
+    }
+    get done() {
+        return this.#finished;
+    }
+    /** @internal Mark finished without running the stop hook (completion / interruption path). */
+    markFinished() {
+        this.#finished = true;
+    }
+    stop() {
+        if (this.#finished)
+            return;
+        this.#finished = true;
+        this.#onStop();
+    }
+}
+class MotionGraphImpl {
+    #clock;
+    // Dirty derived nodes live in a reusable creation-index-sorted slot list, not a Set
+    // (REQ-DRIVER-021, packet §6 ordinary local-JS repair): mark dedupes and inserts by indexed
+    // binary-search/shift, and the flush drains the front by index — no Set growth or iterator on
+    // the frame path. The sort keeps the drain exactly the old min-first topological order.
+    #dirtySlots = [];
+    #animations = new Map();
+    // Command-edge-grown completion slots: the frame step writes finished records by index and the
+    // completion pass drains by count — no fresh completion array, no Map iterator, no push.
+    #completedSlots = [];
+    #completedCount = 0;
+    #frameClampedDt = 0;
+    #creationCounter = 0;
+    #openActivities = 0;
+    #wasSettled = true;
+    // One retained settle-resolver list, drained by index and reset by length — never replaced
+    // with a fresh array on the settle edge.
+    #settleResolvers = [];
+    constructor(options) {
+        this.#clock = options.clock;
+        options.scheduler.onFrame((dtMs) => this.#frameStep(dtMs));
+    }
+    motionValue(initial) {
+        return new MotionValueImpl(initial, this.#clock);
+    }
+    derived(inputs, compute) {
+        // Both public call shapes erase to this unknown[] implementation; the graph passes each
+        // input's live get() positionally, so the runtime match is by construction.
+        return new DerivedValue(this.#creationCounter++, inputs, compute, (node) => this.#markDirtyIntoReusableSlot(node));
+    }
+    animate(value, factory) {
+        if (!(value instanceof MotionValueImpl)) {
+            throw new Error('native-motion-core: animate() requires a MotionValue created by this graph, not a derived/read-only value');
+        }
+        // Interruption (REQ-CORE-002): stop the prior animation on this value and seed the new generator
+        // with the value's current value+velocity so motion continues from the present visual state.
+        // Replacing the map entry keeps the active count net-unchanged across the swap.
+        const prior = this.#animations.get(value);
+        if (prior) {
+            prior.handle.markFinished();
+            // Pinned lifecycle: the interrupted animation never completed — it was cancelled.
+            value.emitEvent('animationCancel');
+        }
+        const seed = { from: value.get(), velocity: value.getVelocity() };
+        const generator = factory(seed);
+        const handle = new AnimationHandle(() => this.#removeAnimation(value, handle));
+        this.#animations.set(value, { value, generator, handle, elapsedMs: 0 });
+        value.attachAnimationStopper(() => handle.stop());
+        value.emitEvent('animationStart');
+        this.#reconcileSettleFromPrefilledSlots();
+        return handle;
+    }
+    activeAnimationCount() {
+        return this.#animations.size;
+    }
+    registerActivity() {
+        this.#openActivities += 1;
+        this.#reconcileSettleFromPrefilledSlots();
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.#openActivities -= 1;
+                this.#reconcileSettleFromPrefilledSlots();
+            },
+        };
+    }
+    isSettled() {
+        return this.#animations.size === 0 && this.#openActivities === 0;
+    }
+    whenSettled() {
+        if (this.isSettled())
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#settleResolvers.push(resolve);
+        });
+    }
+    #markDirtyIntoReusableSlot(node) {
+        // Sorted insertion by creationIndex (unique per node): the membership check IS the binary
+        // search — an already-dirty node is found and skipped, exactly like the old Set dedupe.
+        const slots = this.#dirtySlots;
+        let lo = 0;
+        let hi = slots.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            const midIndex = slots[mid].creationIndex;
+            if (midIndex === node.creationIndex)
+                return;
+            if (midIndex < node.creationIndex)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        // Indexed tail shift; capacity grows only to the frame's high-water mark, then is reused.
+        for (let i = slots.length; i > lo; i--)
+            slots[i] = slots[i - 1];
+        slots[lo] = node;
+    }
+    #removeAnimation(value, handle) {
+        const record = this.#animations.get(value);
+        if (record && record.handle === handle) {
+            this.#animations.delete(value);
+            record.value.endAnimation();
+            this.#reconcileSettleFromPrefilledSlots();
+        }
+    }
+    // Stable per-instance frame callback for the active-animation scan: Map.prototype.forEach walks
+    // the map's internal slots (no per-frame iterator object) with the same live-iteration semantics
+    // as the old for..of — entries appended mid-scan are visited, deleted entries are skipped.
+    #sampleActiveAnimation = (record) => {
+        record.elapsedMs += this.#frameClampedDt;
+        const sample = record.generator.sample(record.elapsedMs);
+        record.value.applyAnimationSample(sample.value, sample.velocity);
+        if (sample.done) {
+            this.#completedSlots[this.#completedCount] = record;
+            this.#completedCount += 1;
+        }
+    };
+    #frameStep(dtMs) {
+        // REQ-CLOCK-003: clamp per-frame elapsed so a large gap after backgrounding does not jump the
+        // graph forward unbounded. Animations advance by accumulated clamped elapsed, which is also what
+        // makes the trajectory a pure function of elapsed time (dt-robust) when no clamp triggers.
+        this.#frameClampedDt = Math.min(dtMs, DT_CLAMP_MS);
+        this.#completedCount = 0;
+        this.#animations.forEach(this.#sampleActiveAnimation);
+        this.#completeFinishedAnimationsFromPrefilledSlots();
+        // Animations write their target values before the derived flush, so derived values observe
+        // post-animation inputs within the same frame (glitch-free).
+        this.#flushDirtyDerivedFromPrefilledSlots();
+        this.#reconcileSettleFromPrefilledSlots();
+    }
+    #completeFinishedAnimationsFromPrefilledSlots() {
+        const completed = this.#completedSlots;
+        const count = this.#completedCount;
+        for (let i = 0; i < count; i++) {
+            const record = completed[i];
+            completed[i] = undefined;
+            record.handle.markFinished();
+            this.#animations.delete(record.value);
+            record.value.endAnimation();
+            record.value.emitEvent('animationComplete');
+        }
+    }
+    // Flush dirty derived nodes in ascending creation index. A node depends only on earlier-created
+    // nodes, so lowest-index-first is a valid topological order: recomputing a node may notify and
+    // re-dirty a higher-index dependent, which this same drain then processes — glitch-free within one
+    // frame. The graph is acyclic by construction; the iteration guard is a loud backstop (REQ-VALUE-013).
+    // The slot list is kept sorted by #markDirtyIntoReusableSlot, so the front IS the minimum — the
+    // drain pops it by indexed shift (no Set iterator per frame, REQ-DRIVER-021).
+    #flushDirtyDerivedFromPrefilledSlots() {
+        let guard = 0;
+        const maxIterations = 1_000_000;
+        const slots = this.#dirtySlots;
+        while (slots.length > 0) {
+            if (++guard > maxIterations) {
+                throw new Error('native-motion-core: derived graph flush did not converge (cycle detected)');
+            }
+            const next = slots[0];
+            for (let i = 1; i < slots.length; i++)
+                slots[i - 1] = slots[i];
+            slots.length -= 1;
+            next.flush();
+        }
+    }
+    // Settle ledger (REQ-SETTLE-001/002): the graph is settled iff no active animations and no open
+    // activity handles. Resolve pending `whenSettled` promises exactly on the transition into settled;
+    // re-arm on the transition out. Fail-closed: while any source is open, resolvers stay pending.
+    // The resolver list is retained and drained by index — never replaced by a fresh array.
+    #reconcileSettleFromPrefilledSlots() {
+        const settled = this.isSettled();
+        if (settled && !this.#wasSettled) {
+            this.#wasSettled = true;
+            const resolvers = this.#settleResolvers;
+            const count = resolvers.length;
+            // Invoke BEFORE clearing: truncating first would delete the very prefix being drained. A
+            // resolver-time whenSettled() appends past `count` and survives the drain, exactly like
+            // the old replacement array.
+            for (let i = 0; i < count; i++)
+                resolvers[i]();
+            let tail = 0;
+            for (let i = count; i < resolvers.length; i++)
+                resolvers[tail++] = resolvers[i];
+            resolvers.length = tail;
+        }
+        else if (!settled && this.#wasSettled) {
+            this.#wasSettled = false;
+        }
+    }
+}
+export function createMotionGraph(options) {
+    return new MotionGraphImpl(options);
+}