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

package/dist/layout/scroll.js

@@ -0,0 +1,24 @@
+// SPEC-LAYOUT REQ-LAYOUT-022 — pure scroll-offset accounting for layout measurement.
+// Pin removeElementScroll (motion@12.42.2 create-projection-node): a viewport/window-space
+// layout box is recovered into content space by ADDING each layoutScroll ancestor's scroll
+// offset (HTMLProjectionNode measureScroll = instance.scrollLeft/scrollTop container scroll;
+// DocumentProjectionNode is the always-on window root). Host-agnostic pure math: the binding
+// supplies offsets when available; closed RN hosts that are not scroll containers contribute
+// {0,0} this rung (stack+math only — REQ-LAYOUT-022(c)). Worklet-safe: plain number math only.
+/**
+ * Convert a viewport/window-space rect into content-space by adding every layoutScroll
+ * ancestor's offset (pin removeElementScroll). Zero offsets leave the rect unchanged.
+ * Offsets apply in path order (root → leaf); cumulative add is commutative for pure
+ * translation so order is documented, not load-bearing for scalar sums.
+ */
+export function accountForLayoutScroll(rect, offsets) {
+    'worklet';
+    let x = rect.x;
+    let y = rect.y;
+    for (let i = 0; i < offsets.length; i++) {
+        const offset = offsets[i];
+        x += offset.x;
+        y += offset.y;
+    }
+    return { x, y, width: rect.width, height: rect.height };
+}

package/dist/layout/session.cjs

@@ -0,0 +1,207 @@
+"use strict";
+// @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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectionSession = createProjectionSession;
+const transition_1 = require("../transition.cjs");
+const timing_1 = require("../timing.cjs");
+const projection_1 = require("./projection.cjs");
+// 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.
+function createProjectionSession(options) {
+    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, (0, timing_1.timingGenerator)(after.x, timing)),
+                graph.animate(vy, (0, timing_1.timingGenerator)(after.y, timing)),
+                graph.animate(vw, (0, timing_1.timingGenerator)(after.width, timing)),
+                graph.animate(vh, (0, timing_1.timingGenerator)(after.height, timing)),
+            ];
+            return;
+        }
+        anims = [
+            graph.animate(vx, (0, transition_1.resolveSpringGenerator)(after.x, spring)),
+            graph.animate(vy, (0, transition_1.resolveSpringGenerator)(after.y, spring)),
+            graph.animate(vw, (0, transition_1.resolveSpringGenerator)(after.width, spring)),
+            graph.animate(vh, (0, transition_1.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 projection_1.IDENTITY_TRANSFORM;
+            return (0, projection_1.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';
+        },
+    };
+}

package/dist/layout/session.d.cts

@@ -0,0 +1,73 @@
+import { type SpringConfig } from "../transition.cjs";
+import { type TimingConfig } from "../timing.cjs";
+import type { MotionGraph } from "../types.cjs";
+import type { LayoutIdToken, Rect, Transform } from "./types.cjs";
+export type ProjectionSessionState = 'idle' | 'projecting';
+/** The live velocity of the visual rect, per component (px/s) — for retarget C1 assertions + diagnostics. */
+export interface RectVelocity {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A caller-owned rect the hot path writes into — the allocation-free counterpart of `Rect`. */
+export interface MutableRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ProjectionSessionOptions {
+    readonly graph: MotionGraph;
+    readonly spring?: SpringConfig;
+    /**
+     * Optional duration/ease tween flight (family-3 layoutId transition slice).
+     * When set, each visual channel uses `timingGenerator` instead of the layout spring —
+     * catalog residuals author `transition={{ duration: N }}` on layoutId hosts.
+     * Mutually exclusive with relying on `spring` for the same session: timing wins when present.
+     */
+    readonly timing?: TimingConfig;
+}
+export interface ProjectionSession {
+    /** Start a fresh projection from `before` to `after`. A null before/after fails closed (unmeasured). */
+    begin(token: LayoutIdToken, before: Rect | null, after: Rect | null): void;
+    /** A host layout change mid-projection: continue from the live visual position + velocity toward `after`. */
+    retarget(after: Rect | null): void;
+    /**
+     * Instant settle at `after` (pin `type: false` under shouldReduceMotion / skipAnimations):
+     * jump every visual channel to the target, stop springs, idle. Used by layout-identity
+     * force-instant edges so the flight never multi-frames under MotionConfig policy (REQ-API-035).
+     */
+    settleAt(after: Rect): void;
+    /** The transform-only correction to apply this frame; identity while unmeasured or at settle. */
+    transform(): Transform;
+    /** The current visual rect, or null while unmeasured. */
+    visualRect(): Rect | null;
+    /** The live per-component velocity of the visual rect. */
+    velocity(): RectVelocity;
+    /**
+     * Allocation-free settle test — the hot-path counterpart of comparing visualRect()+velocity()
+     * against `target` (REQ-DRIVER-015): measured AND every visual channel within `epsPos` of the
+     * target AND every channel velocity within `epsVel` of rest. False while unmeasured
+     * (fail-closed, REQ-LAYOUT-019).
+     */
+    settledAgainst(target: Rect, epsPos: number, epsVel: number): boolean;
+    /**
+     * Allocation-free visual-rect read: writes the live rect into the caller-owned `out` and
+     * returns true, or returns false while unmeasured (out untouched). The hot-path counterpart of
+     * visualRect() (REQ-DRIVER-015).
+     */
+    writeVisualInto(out: MutableRect): boolean;
+    /** A non-null read has landed for the current projection. */
+    measured(): boolean;
+    isSettled(): boolean;
+    state(): ProjectionSessionState;
+    /**
+     * Close the session out: stop the projection springs, release the waiting-for-measurement
+     * activity, return to idle. For an owner ABANDONING the session (a reverted or degraded
+     * identity pairing, an entry GC) — an unmeasured session parked in fail-closed wait would
+     * otherwise hold the graph's settle ledger open forever (L2 review cycle 3).
+     */
+    dispose(): void;
+}
+export declare function createProjectionSession(options: ProjectionSessionOptions): ProjectionSession;

package/dist/layout/session.d.ts

@@ -0,0 +1,73 @@
+import { type SpringConfig } from "../transition.js";
+import { type TimingConfig } from "../timing.js";
+import type { MotionGraph } from "../types.js";
+import type { LayoutIdToken, Rect, Transform } from "./types.js";
+export type ProjectionSessionState = 'idle' | 'projecting';
+/** The live velocity of the visual rect, per component (px/s) — for retarget C1 assertions + diagnostics. */
+export interface RectVelocity {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A caller-owned rect the hot path writes into — the allocation-free counterpart of `Rect`. */
+export interface MutableRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ProjectionSessionOptions {
+    readonly graph: MotionGraph;
+    readonly spring?: SpringConfig;
+    /**
+     * Optional duration/ease tween flight (family-3 layoutId transition slice).
+     * When set, each visual channel uses `timingGenerator` instead of the layout spring —
+     * catalog residuals author `transition={{ duration: N }}` on layoutId hosts.
+     * Mutually exclusive with relying on `spring` for the same session: timing wins when present.
+     */
+    readonly timing?: TimingConfig;
+}
+export interface ProjectionSession {
+    /** Start a fresh projection from `before` to `after`. A null before/after fails closed (unmeasured). */
+    begin(token: LayoutIdToken, before: Rect | null, after: Rect | null): void;
+    /** A host layout change mid-projection: continue from the live visual position + velocity toward `after`. */
+    retarget(after: Rect | null): void;
+    /**
+     * Instant settle at `after` (pin `type: false` under shouldReduceMotion / skipAnimations):
+     * jump every visual channel to the target, stop springs, idle. Used by layout-identity
+     * force-instant edges so the flight never multi-frames under MotionConfig policy (REQ-API-035).
+     */
+    settleAt(after: Rect): void;
+    /** The transform-only correction to apply this frame; identity while unmeasured or at settle. */
+    transform(): Transform;
+    /** The current visual rect, or null while unmeasured. */
+    visualRect(): Rect | null;
+    /** The live per-component velocity of the visual rect. */
+    velocity(): RectVelocity;
+    /**
+     * Allocation-free settle test — the hot-path counterpart of comparing visualRect()+velocity()
+     * against `target` (REQ-DRIVER-015): measured AND every visual channel within `epsPos` of the
+     * target AND every channel velocity within `epsVel` of rest. False while unmeasured
+     * (fail-closed, REQ-LAYOUT-019).
+     */
+    settledAgainst(target: Rect, epsPos: number, epsVel: number): boolean;
+    /**
+     * Allocation-free visual-rect read: writes the live rect into the caller-owned `out` and
+     * returns true, or returns false while unmeasured (out untouched). The hot-path counterpart of
+     * visualRect() (REQ-DRIVER-015).
+     */
+    writeVisualInto(out: MutableRect): boolean;
+    /** A non-null read has landed for the current projection. */
+    measured(): boolean;
+    isSettled(): boolean;
+    state(): ProjectionSessionState;
+    /**
+     * Close the session out: stop the projection springs, release the waiting-for-measurement
+     * activity, return to idle. For an owner ABANDONING the session (a reverted or degraded
+     * identity pairing, an entry GC) — an unmeasured session parked in fail-closed wait would
+     * otherwise hold the graph's settle ledger open forever (L2 review cycle 3).
+     */
+    dispose(): void;
+}
+export declare function createProjectionSession(options: ProjectionSessionOptions): ProjectionSession;

package/dist/layout/session.js

@@ -0,0 +1,205 @@
+// @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';
+        },
+    };
+}