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

package/dist/layout/index.cjs

@@ -0,0 +1,36 @@
+"use strict";
+// SPEC-LAYOUT host-agnostic projection engine barrel (REQ-LAYOUT-001). Grows per milestone: M1 pure
+// projection math (here); compose (M2), measure (M3), session (M4) join as they land. Host-agnostic —
+// no react/react-native/reanimated/Fabric/driver import; relative imports only (REQ-CORE-003).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accountForLayoutScroll = exports.createCommitDetector = exports.createLayoutIdentityRegistry = exports.createProjectionTree = exports.createProjectionSession = exports.projectMeasured = exports.createMeasureTracker = exports.assertCorrectable = exports.correctRadius = exports.counterScale = exports.composeParentRelative = exports.isIdentity = exports.applyTransformToRect = exports.projectAtProgress = exports.invert = exports.IDENTITY_TRANSFORM = exports.EPSILON_VEL = exports.EPSILON_SCALE = exports.EPSILON_POS = exports.toWindowSpaceRect = void 0;
+var types_1 = require("./types.cjs");
+Object.defineProperty(exports, "toWindowSpaceRect", { enumerable: true, get: function () { return types_1.toWindowSpaceRect; } });
+var constants_1 = require("./constants.cjs");
+Object.defineProperty(exports, "EPSILON_POS", { enumerable: true, get: function () { return constants_1.EPSILON_POS; } });
+Object.defineProperty(exports, "EPSILON_SCALE", { enumerable: true, get: function () { return constants_1.EPSILON_SCALE; } });
+Object.defineProperty(exports, "EPSILON_VEL", { enumerable: true, get: function () { return constants_1.EPSILON_VEL; } });
+var projection_1 = require("./projection.cjs");
+Object.defineProperty(exports, "IDENTITY_TRANSFORM", { enumerable: true, get: function () { return projection_1.IDENTITY_TRANSFORM; } });
+Object.defineProperty(exports, "invert", { enumerable: true, get: function () { return projection_1.invert; } });
+Object.defineProperty(exports, "projectAtProgress", { enumerable: true, get: function () { return projection_1.projectAtProgress; } });
+Object.defineProperty(exports, "applyTransformToRect", { enumerable: true, get: function () { return projection_1.applyTransformToRect; } });
+Object.defineProperty(exports, "isIdentity", { enumerable: true, get: function () { return projection_1.isIdentity; } });
+var compose_1 = require("./compose.cjs");
+Object.defineProperty(exports, "composeParentRelative", { enumerable: true, get: function () { return compose_1.composeParentRelative; } });
+Object.defineProperty(exports, "counterScale", { enumerable: true, get: function () { return compose_1.counterScale; } });
+Object.defineProperty(exports, "correctRadius", { enumerable: true, get: function () { return compose_1.correctRadius; } });
+Object.defineProperty(exports, "assertCorrectable", { enumerable: true, get: function () { return compose_1.assertCorrectable; } });
+var measure_1 = require("./measure.cjs");
+Object.defineProperty(exports, "createMeasureTracker", { enumerable: true, get: function () { return measure_1.createMeasureTracker; } });
+Object.defineProperty(exports, "projectMeasured", { enumerable: true, get: function () { return measure_1.projectMeasured; } });
+var session_1 = require("./session.cjs");
+Object.defineProperty(exports, "createProjectionSession", { enumerable: true, get: function () { return session_1.createProjectionSession; } });
+var tree_1 = require("./tree.cjs");
+Object.defineProperty(exports, "createProjectionTree", { enumerable: true, get: function () { return tree_1.createProjectionTree; } });
+var identity_1 = require("./identity.cjs");
+Object.defineProperty(exports, "createLayoutIdentityRegistry", { enumerable: true, get: function () { return identity_1.createLayoutIdentityRegistry; } });
+var commitDetector_1 = require("./commitDetector.cjs");
+Object.defineProperty(exports, "createCommitDetector", { enumerable: true, get: function () { return commitDetector_1.createCommitDetector; } });
+var scroll_1 = require("./scroll.cjs");
+Object.defineProperty(exports, "accountForLayoutScroll", { enumerable: true, get: function () { return scroll_1.accountForLayoutScroll; } });

package/dist/layout/index.d.cts

@@ -0,0 +1,18 @@
+export type { Rect, Transform, LayoutIdToken, WindowSpaceRect } from "./types.cjs";
+export { toWindowSpaceRect } from "./types.cjs";
+export { EPSILON_POS, EPSILON_SCALE, EPSILON_VEL } from "./constants.cjs";
+export { IDENTITY_TRANSFORM, invert, projectAtProgress, applyTransformToRect, isIdentity, } from "./projection.cjs";
+export type { CorrectedRadius } from "./compose.cjs";
+export { composeParentRelative, counterScale, correctRadius, assertCorrectable } from "./compose.cjs";
+export type { MeasureState, MeasureAdapter, Measurement, MeasureTracker } from "./measure.cjs";
+export { createMeasureTracker, projectMeasured } from "./measure.cjs";
+export type { ProjectionSession, ProjectionSessionOptions, ProjectionSessionState, RectVelocity, } from "./session.cjs";
+export { createProjectionSession } from "./session.cjs";
+export type { ProjectionNodeOutput, ProjectionStaleNodeCode, ProjectionStaleNodeReport, ProjectionTree, ProjectionTreeNode, ProjectionTreeOptions, } from "./tree.cjs";
+export { createProjectionTree } from "./tree.cjs";
+export type { IdentityEnterResult, IdentityHolderHandle, IdentityRead, LayoutIdentityFlightOptions, LayoutIdentityRegistry, LayoutIdentityRegistryOptions, LayoutIdentityRole, } from "./identity.cjs";
+export { createLayoutIdentityRegistry } from "./identity.cjs";
+export type { CommitDetection, CommitDetector } from "./commitDetector.cjs";
+export { createCommitDetector } from "./commitDetector.cjs";
+export type { LayoutScrollOffset } from "./scroll.cjs";
+export { accountForLayoutScroll } from "./scroll.cjs";

package/dist/layout/index.d.ts

@@ -0,0 +1,18 @@
+export type { Rect, Transform, LayoutIdToken, WindowSpaceRect } from "./types.js";
+export { toWindowSpaceRect } from "./types.js";
+export { EPSILON_POS, EPSILON_SCALE, EPSILON_VEL } from "./constants.js";
+export { IDENTITY_TRANSFORM, invert, projectAtProgress, applyTransformToRect, isIdentity, } from "./projection.js";
+export type { CorrectedRadius } from "./compose.js";
+export { composeParentRelative, counterScale, correctRadius, assertCorrectable } from "./compose.js";
+export type { MeasureState, MeasureAdapter, Measurement, MeasureTracker } from "./measure.js";
+export { createMeasureTracker, projectMeasured } from "./measure.js";
+export type { ProjectionSession, ProjectionSessionOptions, ProjectionSessionState, RectVelocity, } from "./session.js";
+export { createProjectionSession } from "./session.js";
+export type { ProjectionNodeOutput, ProjectionStaleNodeCode, ProjectionStaleNodeReport, ProjectionTree, ProjectionTreeNode, ProjectionTreeOptions, } from "./tree.js";
+export { createProjectionTree } from "./tree.js";
+export type { IdentityEnterResult, IdentityHolderHandle, IdentityRead, LayoutIdentityFlightOptions, LayoutIdentityRegistry, LayoutIdentityRegistryOptions, LayoutIdentityRole, } from "./identity.js";
+export { createLayoutIdentityRegistry } from "./identity.js";
+export type { CommitDetection, CommitDetector } from "./commitDetector.js";
+export { createCommitDetector } from "./commitDetector.js";
+export type { LayoutScrollOffset } from "./scroll.js";
+export { accountForLayoutScroll } from "./scroll.js";

package/dist/layout/index.js

@@ -0,0 +1,13 @@
+// SPEC-LAYOUT host-agnostic projection engine barrel (REQ-LAYOUT-001). Grows per milestone: M1 pure
+// projection math (here); compose (M2), measure (M3), session (M4) join as they land. Host-agnostic —
+// no react/react-native/reanimated/Fabric/driver import; relative imports only (REQ-CORE-003).
+export { toWindowSpaceRect } from "./types.js";
+export { EPSILON_POS, EPSILON_SCALE, EPSILON_VEL } from "./constants.js";
+export { IDENTITY_TRANSFORM, invert, projectAtProgress, applyTransformToRect, isIdentity, } from "./projection.js";
+export { composeParentRelative, counterScale, correctRadius, assertCorrectable } from "./compose.js";
+export { createMeasureTracker, projectMeasured } from "./measure.js";
+export { createProjectionSession } from "./session.js";
+export { createProjectionTree } from "./tree.js";
+export { createLayoutIdentityRegistry } from "./identity.js";
+export { createCommitDetector } from "./commitDetector.js";
+export { accountForLayoutScroll } from "./scroll.js";

package/dist/layout/measure.cjs

@@ -0,0 +1,81 @@
+"use strict";
+// SPEC-LAYOUT §2/§4a — the measurement lifecycle + fail-closed contract (REQ-LAYOUT-010/011/016/017/019).
+// `null` is a first-class state, never an error to swallow and never a value to assume: an unmeasured read
+// yields an identity transform + unsettled and is retried next epoch. A read fires only after the attached-
+// and-laid-out signal; a view is measured at most once per epoch and the result is cached (the per-frame
+// projection recomputes from the cache, never re-measures); identity is re-validated against a stable token
+// before applying, failing closed on a recycled/unmounted tag. Host-agnostic: the measurement primitive is
+// an injected adapter (a fake host at M1, Fabric measure at M2); `core` never imports a host measure API.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMeasureTracker = createMeasureTracker;
+exports.projectMeasured = projectMeasured;
+const projection_1 = require("./projection.cjs");
+function createMeasureTracker(token) {
+    let state = 'unattached';
+    let epoch = Number.NaN; // no epoch opened yet; the first beginEpoch always invalidates
+    let attemptedThisEpoch = false; // the adapter was read this epoch (once-per-epoch guard, incl. a null read)
+    let cachedRect = null;
+    let measured = false;
+    function current() {
+        return { state, measured, settled: measured, rect: cachedRect };
+    }
+    function resetMeasurement() {
+        measured = false;
+        cachedRect = null;
+        if (state === 'measured')
+            state = 'attached';
+    }
+    return {
+        token,
+        attach() {
+            if (state === 'unattached')
+                state = 'attached';
+        },
+        beginEpoch(e) {
+            // Object.is so re-opening the same epoch is a no-op but the initial NaN epoch always invalidates.
+            if (!Object.is(e, epoch)) {
+                epoch = e;
+                attemptedThisEpoch = false;
+                resetMeasurement();
+            }
+        },
+        measure(adapter) {
+            // Never read before the attached-and-laid-out signal (REQ-LAYOUT-010).
+            if (state === 'unattached')
+                return current();
+            // Once-per-epoch: the adapter is read at most once; the per-frame path reads the cache (REQ-LAYOUT-017).
+            if (attemptedThisEpoch)
+                return current();
+            attemptedThisEpoch = true;
+            const rect = adapter.measure(token);
+            if (rect === null) {
+                // Fail-closed: a null read stays unmeasured/identity and is retried next epoch — never a garbage
+                // delta, never swallowed (REQ-LAYOUT-011). The null branch is explicit.
+                resetMeasurement();
+                return current();
+            }
+            measured = true;
+            cachedRect = rect;
+            state = 'measured';
+            return current();
+        },
+        validate(liveToken) {
+            if (liveToken === token)
+                return true;
+            // Stale identity (Fabric recycled the tag / the view unmounted): the cached rect no longer describes the
+            // live view. Fail closed and re-enter the measure loop rather than applying a stale delta (REQ-LAYOUT-016).
+            resetMeasurement();
+            return false;
+        },
+        current,
+    };
+}
+/**
+ * The fail-closed projection bridge (REQ-LAYOUT-011): if EITHER the before or after read is null (unmeasured),
+ * emit an identity transform — no motion, no garbage delta — else the real FLIP projection at `progress`.
+ */
+function projectMeasured(before, after, progress) {
+    if (before === null || after === null)
+        return projection_1.IDENTITY_TRANSFORM;
+    return (0, projection_1.projectAtProgress)(before, after, progress);
+}

package/dist/layout/measure.d.cts

@@ -0,0 +1,43 @@
+import type { LayoutIdToken, Rect, Transform } from "./types.cjs";
+export type MeasureState = 'unattached' | 'attached' | 'measured';
+/**
+ * The host measurement primitive, injected. Returns the element's current rect, or `null` when it cannot be
+ * measured (unattached / off-screen). A fake adapter at M1; the Fabric `measure` adapter at M2.
+ */
+export interface MeasureAdapter {
+    measure(token: LayoutIdToken): Rect | null;
+}
+/** The resolved measurement of one element for the current epoch. */
+export interface Measurement {
+    readonly state: MeasureState;
+    /** A non-null read landed this epoch. */
+    readonly measured: boolean;
+    /** Measurement-availability = settle: an unmeasured element is unsettled (REQ-LAYOUT-019). */
+    readonly settled: boolean;
+    /** The cached measured rect, or `null` while unmeasured (fail-closed, never a garbage delta). */
+    readonly rect: Rect | null;
+}
+/**
+ * A per-element measurement tracker bound to a stable identity token (REQ-LAYOUT-016). Enforces read-after-
+ * attach (REQ-LAYOUT-010), measure-once-per-epoch caching (REQ-LAYOUT-017), and null-fails-closed
+ * (REQ-LAYOUT-011). Stateful; not thread-shared.
+ */
+export interface MeasureTracker {
+    readonly token: LayoutIdToken;
+    /** The attached-and-laid-out signal; enables reads (REQ-LAYOUT-010). */
+    attach(): void;
+    /** Open a layout epoch; a new epoch invalidates the cache and re-opens measurement (REQ-LAYOUT-017). */
+    beginEpoch(epoch: number): void;
+    /** Measure at most once per epoch via the adapter, caching the result. Null fails closed (REQ-LAYOUT-011). */
+    measure(adapter: MeasureAdapter): Measurement;
+    /** Re-validate the live identity token before applying; a mismatch fails closed (REQ-LAYOUT-016). */
+    validate(liveToken: LayoutIdToken): boolean;
+    /** The current cached measurement without re-reading. */
+    current(): Measurement;
+}
+export declare function createMeasureTracker(token: LayoutIdToken): MeasureTracker;
+/**
+ * The fail-closed projection bridge (REQ-LAYOUT-011): if EITHER the before or after read is null (unmeasured),
+ * emit an identity transform — no motion, no garbage delta — else the real FLIP projection at `progress`.
+ */
+export declare function projectMeasured(before: Rect | null, after: Rect | null, progress: number): Transform;

package/dist/layout/measure.d.ts

@@ -0,0 +1,43 @@
+import type { LayoutIdToken, Rect, Transform } from "./types.js";
+export type MeasureState = 'unattached' | 'attached' | 'measured';
+/**
+ * The host measurement primitive, injected. Returns the element's current rect, or `null` when it cannot be
+ * measured (unattached / off-screen). A fake adapter at M1; the Fabric `measure` adapter at M2.
+ */
+export interface MeasureAdapter {
+    measure(token: LayoutIdToken): Rect | null;
+}
+/** The resolved measurement of one element for the current epoch. */
+export interface Measurement {
+    readonly state: MeasureState;
+    /** A non-null read landed this epoch. */
+    readonly measured: boolean;
+    /** Measurement-availability = settle: an unmeasured element is unsettled (REQ-LAYOUT-019). */
+    readonly settled: boolean;
+    /** The cached measured rect, or `null` while unmeasured (fail-closed, never a garbage delta). */
+    readonly rect: Rect | null;
+}
+/**
+ * A per-element measurement tracker bound to a stable identity token (REQ-LAYOUT-016). Enforces read-after-
+ * attach (REQ-LAYOUT-010), measure-once-per-epoch caching (REQ-LAYOUT-017), and null-fails-closed
+ * (REQ-LAYOUT-011). Stateful; not thread-shared.
+ */
+export interface MeasureTracker {
+    readonly token: LayoutIdToken;
+    /** The attached-and-laid-out signal; enables reads (REQ-LAYOUT-010). */
+    attach(): void;
+    /** Open a layout epoch; a new epoch invalidates the cache and re-opens measurement (REQ-LAYOUT-017). */
+    beginEpoch(epoch: number): void;
+    /** Measure at most once per epoch via the adapter, caching the result. Null fails closed (REQ-LAYOUT-011). */
+    measure(adapter: MeasureAdapter): Measurement;
+    /** Re-validate the live identity token before applying; a mismatch fails closed (REQ-LAYOUT-016). */
+    validate(liveToken: LayoutIdToken): boolean;
+    /** The current cached measurement without re-reading. */
+    current(): Measurement;
+}
+export declare function createMeasureTracker(token: LayoutIdToken): MeasureTracker;
+/**
+ * The fail-closed projection bridge (REQ-LAYOUT-011): if EITHER the before or after read is null (unmeasured),
+ * emit an identity transform — no motion, no garbage delta — else the real FLIP projection at `progress`.
+ */
+export declare function projectMeasured(before: Rect | null, after: Rect | null, progress: number): Transform;

package/dist/layout/measure.js

@@ -0,0 +1,78 @@
+// SPEC-LAYOUT §2/§4a — the measurement lifecycle + fail-closed contract (REQ-LAYOUT-010/011/016/017/019).
+// `null` is a first-class state, never an error to swallow and never a value to assume: an unmeasured read
+// yields an identity transform + unsettled and is retried next epoch. A read fires only after the attached-
+// and-laid-out signal; a view is measured at most once per epoch and the result is cached (the per-frame
+// projection recomputes from the cache, never re-measures); identity is re-validated against a stable token
+// before applying, failing closed on a recycled/unmounted tag. Host-agnostic: the measurement primitive is
+// an injected adapter (a fake host at M1, Fabric measure at M2); `core` never imports a host measure API.
+import { IDENTITY_TRANSFORM, projectAtProgress } from "./projection.js";
+export function createMeasureTracker(token) {
+    let state = 'unattached';
+    let epoch = Number.NaN; // no epoch opened yet; the first beginEpoch always invalidates
+    let attemptedThisEpoch = false; // the adapter was read this epoch (once-per-epoch guard, incl. a null read)
+    let cachedRect = null;
+    let measured = false;
+    function current() {
+        return { state, measured, settled: measured, rect: cachedRect };
+    }
+    function resetMeasurement() {
+        measured = false;
+        cachedRect = null;
+        if (state === 'measured')
+            state = 'attached';
+    }
+    return {
+        token,
+        attach() {
+            if (state === 'unattached')
+                state = 'attached';
+        },
+        beginEpoch(e) {
+            // Object.is so re-opening the same epoch is a no-op but the initial NaN epoch always invalidates.
+            if (!Object.is(e, epoch)) {
+                epoch = e;
+                attemptedThisEpoch = false;
+                resetMeasurement();
+            }
+        },
+        measure(adapter) {
+            // Never read before the attached-and-laid-out signal (REQ-LAYOUT-010).
+            if (state === 'unattached')
+                return current();
+            // Once-per-epoch: the adapter is read at most once; the per-frame path reads the cache (REQ-LAYOUT-017).
+            if (attemptedThisEpoch)
+                return current();
+            attemptedThisEpoch = true;
+            const rect = adapter.measure(token);
+            if (rect === null) {
+                // Fail-closed: a null read stays unmeasured/identity and is retried next epoch — never a garbage
+                // delta, never swallowed (REQ-LAYOUT-011). The null branch is explicit.
+                resetMeasurement();
+                return current();
+            }
+            measured = true;
+            cachedRect = rect;
+            state = 'measured';
+            return current();
+        },
+        validate(liveToken) {
+            if (liveToken === token)
+                return true;
+            // Stale identity (Fabric recycled the tag / the view unmounted): the cached rect no longer describes the
+            // live view. Fail closed and re-enter the measure loop rather than applying a stale delta (REQ-LAYOUT-016).
+            resetMeasurement();
+            return false;
+        },
+        current,
+    };
+}
+/**
+ * The fail-closed projection bridge (REQ-LAYOUT-011): if EITHER the before or after read is null (unmeasured),
+ * emit an identity transform — no motion, no garbage delta — else the real FLIP projection at `progress`.
+ */
+export function projectMeasured(before, after, progress) {
+  'worklet';
+    if (before === null || after === null)
+        return IDENTITY_TRANSFORM;
+    return projectAtProgress(before, after, progress);
+}

package/dist/layout/projection.cjs

@@ -0,0 +1,99 @@
+"use strict";
+// @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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_TRANSFORM = void 0;
+exports.invert = invert;
+exports.projectAtProgress = projectAtProgress;
+exports.applyTransformToRect = applyTransformToRect;
+exports.isIdentity = isIdentity;
+const constants_1 = require("./constants.cjs");
+/** The no-op correction: element sits exactly on its host layout. */
+exports.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) {
+    return from + (to - from) * progress;
+}
+function assertMeasurable(rect) {
+    // 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.
+function invert(before, after) {
+    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).
+function projectAtProgress(before, after, progress) {
+    const from = invert(before, after);
+    return {
+        translateX: lerp(from.translateX, exports.IDENTITY_TRANSFORM.translateX, progress),
+        translateY: lerp(from.translateY, exports.IDENTITY_TRANSFORM.translateY, progress),
+        scaleX: lerp(from.scaleX, exports.IDENTITY_TRANSFORM.scaleX, progress),
+        scaleY: lerp(from.scaleY, exports.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.
+function applyTransformToRect(t, rect) {
+    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). */
+function isIdentity(t, epsPos = constants_1.EPSILON_POS, epsScale = constants_1.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/layout/projection.d.cts

@@ -0,0 +1,23 @@
+import type { Rect, Transform } from "./types.cjs";
+/** The no-op correction: element sits exactly on its host layout. */
+export declare const IDENTITY_TRANSFORM: Transform;
+/**
+ * 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.
+ */
+export declare function invert(before: Rect, after: Rect): Transform;
+/**
+ * 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.
+ */
+export declare function projectAtProgress(before: Rect, after: Rect, progress: number): Transform;
+/**
+ * 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.
+ */
+export declare function applyTransformToRect(t: Transform, rect: Rect): Rect;
+/** Whether a transform is within the settle epsilons of identity (translate ≤ pos eps, scale ≤ scale eps). */
+export declare function isIdentity(t: Transform, epsPos?: number, epsScale?: number): boolean;

package/dist/layout/projection.d.ts

@@ -0,0 +1,23 @@
+import type { Rect, Transform } from "./types.js";
+/** The no-op correction: element sits exactly on its host layout. */
+export declare const IDENTITY_TRANSFORM: Transform;
+/**
+ * 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.
+ */
+export declare function invert(before: Rect, after: Rect): Transform;
+/**
+ * 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.
+ */
+export declare function projectAtProgress(before: Rect, after: Rect, progress: number): Transform;
+/**
+ * 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.
+ */
+export declare function applyTransformToRect(t: Transform, rect: Rect): Rect;
+/** Whether a transform is within the settle epsilons of identity (translate ≤ pos eps, scale ≤ scale eps). */
+export declare function isIdentity(t: Transform, epsPos?: number, epsScale?: number): boolean;

package/dist/layout/projection.js

@@ -0,0 +1,97 @@
+// @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/layout/scroll.cjs

@@ -0,0 +1,27 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accountForLayoutScroll = accountForLayoutScroll;
+/**
+ * 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.
+ */
+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/scroll.d.cts

@@ -0,0 +1,13 @@
+import type { Rect } from "./types.cjs";
+/** One layoutScroll root's scroll offset (px). Pin Point shape. */
+export interface LayoutScrollOffset {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * 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 declare function accountForLayoutScroll(rect: Rect, offsets: readonly LayoutScrollOffset[]): Rect;

package/dist/layout/scroll.d.ts

@@ -0,0 +1,13 @@
+import type { Rect } from "./types.js";
+/** One layoutScroll root's scroll offset (px). Pin Point shape. */
+export interface LayoutScrollOffset {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * 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 declare function accountForLayoutScroll(rect: Rect, offsets: readonly LayoutScrollOffset[]): Rect;