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

package/dist/worklet-layout/layout/projection.js

@@ -0,0 +1,98 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-LAYOUT §2/§4a — the pure FLIP projection math (REQ-LAYOUT-002/011). Given a `before` rect (where the
+// element was) and an `after` rect (where the host layout engine just placed it), `invert` yields the
+// transform-only correction that makes the element — already laid out at `after` — appear at `before`.
+// Driving progress 0→1 lerps that correction to identity, so at settle the element is coincident with the
+// host layout and the applied transform is identity (Motion keeps layout authority; we animate the
+// transition only). Host-agnostic, no graph/clock — the progress itself is driven by the reused SPRING in
+// the session (M4). All transforms are about the rect's TOP-LEFT origin (transformOrigin 0,0), which keeps
+// the invert/apply algebra exact and composable; a center/other origin is an M2 parity refinement (§7).
+import { EPSILON_POS, EPSILON_SCALE } from "./constants.js";
+/** The no-op correction: element sits exactly on its host layout. */
+export const IDENTITY_TRANSFORM = {
+    translateX: 0,
+    translateY: 0,
+    scaleX: 1,
+    scaleY: 1,
+};
+// Linear interpolation of a single transform scalar by the (spring-driven) progress. Deliberately a scalar
+// lerp, NOT value-types `mixNumeric` — that wraps a NumericValue for typed style interpolation, which is
+// overkill for a raw geometric component. The reused SPRING supplies `progress`; this only shapes it.
+function lerp(from, to, progress) {
+  'worklet';
+    return from + (to - from) * progress;
+}
+function assertMeasurable(rect) {
+  'worklet';
+    // A zero/negative/non-finite dimension would divide-by-zero (or NaN) the scale — fail loud, never fabricate
+    // a garbage delta (REQ-LAYOUT-011). Position may be any finite number; only the dimensions must be > 0.
+    if (!Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height) ||
+        rect.width <= 0 ||
+        rect.height <= 0) {
+        // ui-throw-ok: unreachable from the UI path — tree.setProjection validates BOTH rects
+        // (finite fields; positive target dimensions) before calling projectAtProgress (seal r11,
+        // F2a), so this assert cannot fire from the UI-reachable set. invert's remaining callers are
+        // JS-thread (session transform, web engine, verification), where the REQ-LAYOUT-011
+        // fail-loud contract stands.
+        throw new Error(`layout: cannot project onto a rect with non-positive/non-finite dimensions (measure returned width=${rect.width}, height=${rect.height})`);
+    }
+}
+/**
+ * The FLIP invert (REQ-LAYOUT-002): the transform that makes an element currently laid out at `after` appear
+ * at `before`. Scaling is about the top-left origin, so the top-left stays put under scale and the translate
+ * is the raw origin delta. `applyTransformToRect(invert(b, a), a)` reproduces `b` exactly.
+ */
+// alloc-ok: js-thread — record-building API for JS-side callers (session.transform, web engine,
+// verification); the UI frame path inverts field-wise inside the registry's readInto.
+export function invert(before, after) {
+  'worklet';
+    assertMeasurable(after);
+    return {
+        translateX: before.x - after.x,
+        translateY: before.y - after.y,
+        scaleX: before.width / after.width,
+        scaleY: before.height / after.height,
+    };
+}
+/**
+ * The projection correction at animation progress `p` (REQ-LAYOUT-002/017): lerp each component from the
+ * invert at `p=0` (element at `before`) to identity at `p=1` (element on the host layout). Recomputed from
+ * the cached before/after and the current progress — never by re-measuring.
+ */
+// alloc-ok: js-thread — record-building API for JS-side callers and verification; not on the UI
+// frame path (readInto owns the per-frame projection math).
+export function projectAtProgress(before, after, progress) {
+  'worklet';
+    const from = invert(before, after);
+    return {
+        translateX: lerp(from.translateX, IDENTITY_TRANSFORM.translateX, progress),
+        translateY: lerp(from.translateY, IDENTITY_TRANSFORM.translateY, progress),
+        scaleX: lerp(from.scaleX, IDENTITY_TRANSFORM.scaleX, progress),
+        scaleY: lerp(from.scaleY, IDENTITY_TRANSFORM.scaleY, progress),
+    };
+}
+/**
+ * Apply a transform (translate + scale about the rect's top-left) to a rect, yielding the visual rect. Used
+ * for assertions and for the retarget seam's `currentVisual` (M4). Translate is in the unscaled frame; size
+ * scales in place.
+ */
+// alloc-ok: js-thread — record-building API for assertions and the retarget seam's JS-side
+// currentVisual; not on the UI frame path.
+export function applyTransformToRect(t, rect) {
+  'worklet';
+    return {
+        x: rect.x + t.translateX,
+        y: rect.y + t.translateY,
+        width: rect.width * t.scaleX,
+        height: rect.height * t.scaleY,
+    };
+}
+/** Whether a transform is within the settle epsilons of identity (translate ≤ pos eps, scale ≤ scale eps). */
+export function isIdentity(t, epsPos = EPSILON_POS, epsScale = EPSILON_SCALE) {
+    return (Math.abs(t.translateX) < epsPos &&
+        Math.abs(t.translateY) < epsPos &&
+        Math.abs(t.scaleX - 1) < epsScale &&
+        Math.abs(t.scaleY - 1) < epsScale);
+}

package/dist/worklet-layout/layout/session.js

@@ -0,0 +1,206 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-LAYOUT §2/§4a — the projection SESSION (REQ-LAYOUT-002/011/018/019). Drives an element's visual rect
+// to its host-computed layout through the reused SPRING, exposing the transform-only correction the substrate
+// executes. A mid-flight host layout change retargets from the current visual position AND velocity (C0/C1);
+// a null read fails closed to identity + unsettled; settle is measurement-availability. Host-agnostic — no
+// driver/React/Fabric import; drives the injected MotionGraph + built SPRING generators, no forked math.
+//
+// Modeling decision (deviates from the build packet's single-progress sketch): the visual rect is animated
+// PER COMPONENT — four motion values (x, y, width, height) each springing toward the after-rect. A single
+// scalar progress cannot preserve velocity continuity across ALL axes on a retarget (the progress→visual-
+// velocity ratio differs per component), whereas per-component springs get C0/C1 for free from the graph's
+// seed-from-live (REQ-API-003) — exactly as GESTURE's owned retarget does. transform() is then the FLIP
+// invert of the live visual rect against the after rect, which is identity at settle (REQ-LAYOUT-002).
+import { resolveSpringGenerator } from "../transition.js";
+import { timingGenerator } from "../timing.js";
+import { IDENTITY_TRANSFORM, invert } from "./projection.js";
+// Near-critical projection spring (physics ⇒ carries the seeded velocity, REQ-SPRING-007) — minimal overshoot
+// for a layout settle. Config constant, not an inline literal; refinable — the exact feel binds cross-engine
+// parity at M2, not the M1 continuity/identity/settle invariants (§7 vetoable).
+const LAYOUT_PROJECTION_SPRING = { stiffness: 550, damping: 45 };
+// alloc-ok: construction — one session per layout-identity pairing; the per-frame surface is
+// sync()/settledAgainst()/writeVisualInto(), which allocate nothing.
+export function createProjectionSession(options) {
+  'worklet';
+    const { graph } = options;
+    const spring = options.spring ?? LAYOUT_PROJECTION_SPRING;
+    const timing = options.timing;
+    // The visual rect, tracked as four independently-animated motion values (see the modeling note above).
+    const vx = graph.motionValue(0);
+    const vy = graph.motionValue(0);
+    const vw = graph.motionValue(0);
+    const vh = graph.motionValue(0);
+    let state = 'idle';
+    let measured = false;
+    let currentAfter = null;
+    let anims = [];
+    // Held while unmeasured (a null read): there is no in-flight animation to keep the graph unsettled, yet the
+    // element is not settled — it is waiting for a valid measurement (REQ-LAYOUT-019 / G-INV-7 analog).
+    let measureHandle;
+    function acquireMeasureHandle() {
+        if (measureHandle === undefined)
+            measureHandle = graph.registerActivity();
+    }
+    function releaseMeasureHandle() {
+        measureHandle?.release();
+        measureHandle = undefined;
+    }
+    function stopAnims() {
+        // Indexed + length=0: sync() reaches this on the settle frame, so a for..of iterator and a
+        // fresh array are frame-executed garbage (round-7 major 3; REQ-DRIVER-021).
+        for (let i = 0; i < anims.length; i++)
+            anims[i].stop();
+        anims.length = 0;
+    }
+    // Drive each visual channel toward the after-rect. Spring path: graph seeds {from, velocity} for
+    // C0/C1 retarget (REQ-CORE-002 / REQ-API-003). Timing path (family-3): duration/ease tween — seed
+    // velocity is ignored by timingGenerator (REQ-TIMING-001); retarget reseeds from live value.
+    // Do NOT stop the prior animation first — stop() clears animated velocity and breaks spring C1.
+    // alloc-ok: lifecycle-edge — flight start/retarget only (begin/retarget), never per frame.
+    function driveTo(after) {
+        if (timing !== undefined) {
+            anims = [
+                graph.animate(vx, timingGenerator(after.x, timing)),
+                graph.animate(vy, timingGenerator(after.y, timing)),
+                graph.animate(vw, timingGenerator(after.width, timing)),
+                graph.animate(vh, timingGenerator(after.height, timing)),
+            ];
+            return;
+        }
+        anims = [
+            graph.animate(vx, resolveSpringGenerator(after.x, spring)),
+            graph.animate(vy, resolveSpringGenerator(after.y, spring)),
+            graph.animate(vw, resolveSpringGenerator(after.width, spring)),
+            graph.animate(vh, resolveSpringGenerator(after.height, spring)),
+        ];
+    }
+    // alloc-ok: js-thread — record-building read for the JS-side API (transform/visualRect); the
+    // frame path uses writeVisualInto/settledAgainst.
+    function visual() {
+        return { x: vx.get(), y: vy.get(), width: vw.get(), height: vh.get() };
+    }
+    // Reconcile the internal state to the graph: once the projection springs settle (graph settled) while
+    // measured, the session returns to idle. Every state-dependent entry point reconciles first — the getter
+    // AND the mutators — so post-settle reads and a subsequent retarget agree on the state (the GESTURE review
+    // lesson: a getter-only reconcile leaves the mutators acting on a stale field).
+    function sync() {
+        if (state === 'projecting' && measured && graph.isSettled()) {
+            stopAnims();
+            state = 'idle';
+        }
+    }
+    function failClosed(after) {
+        // A null read: unmeasured ⇒ identity + unsettled, retried next epoch. Never a garbage delta (REQ-LAYOUT-011).
+        stopAnims();
+        measured = false;
+        currentAfter = after;
+        acquireMeasureHandle();
+        state = 'projecting';
+    }
+    return {
+        begin(token, before, after) {
+            void token; // identity binding is the measure tracker's concern (M3); the session takes resolved rects
+            sync();
+            if (before === null || after === null) {
+                failClosed(after);
+                return;
+            }
+            // Fresh projection: jump the visual rect to `before` (velocity 0) and spring to `after`.
+            releaseMeasureHandle();
+            vx.jump(before.x);
+            vy.jump(before.y);
+            vw.jump(before.width);
+            vh.jump(before.height);
+            measured = true;
+            currentAfter = after;
+            driveTo(after);
+            state = 'projecting';
+        },
+        retarget(after) {
+            sync();
+            if (state !== 'projecting' || !measured) {
+                // Nothing in flight to retarget. Fail loud, consistent with the total state machine (never a silent
+                // no-op) — the caller must begin() a measured projection first.
+                throw new Error(`layout: retarget() with no active measured projection (state='${state}', measured=${measured}) — begin() first`);
+            }
+            if (after === null) {
+                failClosed(after);
+                return;
+            }
+            // Continue from the LIVE visual position (+ velocity on spring path) toward the new target —
+            // no jump; the graph re-seeds each channel from live state ⇒ C0/C1 on spring (REQ-LAYOUT-018).
+            currentAfter = after;
+            driveTo(after);
+        },
+        settleAt(after) {
+            // Pin type:false — no multi-frame flight. Jump every channel to the post-layout rect and
+            // drop spring work so settledAgainst/isSettled read true on the same edge (REQ-API-035).
+            releaseMeasureHandle();
+            stopAnims();
+            vx.jump(after.x);
+            vy.jump(after.y);
+            vw.jump(after.width);
+            vh.jump(after.height);
+            measured = true;
+            currentAfter = after;
+            state = 'idle';
+        },
+        transform() {
+            sync();
+            if (!measured || currentAfter === null)
+                return IDENTITY_TRANSFORM;
+            return invert(visual(), currentAfter);
+        },
+        visualRect() {
+            sync();
+            return measured ? visual() : null;
+        },
+        // alloc-ok: js-thread — record-building read for the JS-side API; the frame path uses
+        // settledAgainst's in-place comparison.
+        velocity() {
+            return {
+                x: vx.getVelocity(),
+                y: vy.getVelocity(),
+                width: vw.getVelocity(),
+                height: vh.getVelocity(),
+            };
+        },
+        settledAgainst(target, epsPos, epsVel) {
+            sync();
+            if (!measured)
+                return false;
+            return (Math.abs(vx.get() - target.x) < epsPos &&
+                Math.abs(vy.get() - target.y) < epsPos &&
+                Math.abs(vw.get() - target.width) < epsPos &&
+                Math.abs(vh.get() - target.height) < epsPos &&
+                Math.abs(vx.getVelocity()) < epsVel &&
+                Math.abs(vy.getVelocity()) < epsVel &&
+                Math.abs(vw.getVelocity()) < epsVel &&
+                Math.abs(vh.getVelocity()) < epsVel);
+        },
+        writeVisualInto(out) {
+            sync();
+            if (!measured)
+                return false;
+            out.x = vx.get();
+            out.y = vy.get();
+            out.width = vw.get();
+            out.height = vh.get();
+            return true;
+        },
+        measured: () => measured,
+        isSettled: () => graph.isSettled(),
+        state: () => {
+            sync();
+            return state;
+        },
+        dispose() {
+            stopAnims();
+            releaseMeasureHandle();
+            measured = false;
+            currentAfter = null;
+            state = 'idle';
+        },
+    };
+}