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

package/dist/keyframes.cjs

@@ -0,0 +1,191 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// The multi-keyframe timing generator (REQ-API-033, R8). Interpolates THROUGH a keyframe array over
+// `duration`: even `defaultOffset` unless `times`, one `easeInOut` per SEGMENT unless an `ease`
+// array, `keyframes[0]` seeds — or the element's CURRENT value when the first keyframe is `null`
+// (R8-F2). Semantics pinned to motion@12.42.2's generators/keyframes.ts; the cubic-bezier easing is
+// timing.ts's exact BezierEasing port (never a second vocabulary). The reused sample record and the
+// bounded segment scan allocate nothing per frame.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyframesGenerator = keyframesGenerator;
+const validate_1 = require("./component/validate.cjs");
+const timing_1 = require("./timing.cjs");
+const keyframeTiming_1 = require("./driver/keyframeTiming.cjs");
+const keyframeTimingConfig_1 = require("./driver/keyframeTimingConfig.cjs");
+const boundedArray_1 = require("./component/boundedArray.cjs");
+const DEFAULT_DURATION_MS = 300; // REQ-TIMING-002 (0.3s), motion's keyframes default
+const VELOCITY_SAMPLE_MS = 5;
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+const mix = (from, to, p) => from + (to - from) * p;
+function captureArray(value, invalid, nested = false) {
+    const capture = nested ? (0, boundedArray_1.captureBoundedCubicBezier)(value) : (0, boundedArray_1.captureBoundedArray)(value);
+    if (capture.kind === 'not-array')
+        throw invalid((0, boundedArray_1.capturedArrayDescription)(capture), 'must be a real array');
+    if (capture.kind === 'invalid-length') {
+        throw invalid((0, boundedArray_1.capturedArrayDescription)(capture), nested
+            ? 'must be a four-point cubic-bezier tuple (REQ-API-033)'
+            : `must have a safe array length between 0 and ${boundedArray_1.MAX_CAPTURED_ARRAY_LENGTH} (REQ-API-033)`);
+    }
+    const length = capture.values.length;
+    const captured = [];
+    captured.length = length;
+    for (let index = 0; index < length; index++) {
+        if (!Object.hasOwn(capture.values, index))
+            continue;
+        const member = capture.values[index];
+        captured[index] =
+            !nested && Array.isArray(member) ? captureArray(member, invalid, true) : member;
+    }
+    return Object.freeze(captured);
+}
+function captureKeyframes(keyframes) {
+    const captured = captureArray(keyframes, (value, reason) => new validate_1.InvalidTargetError(undefined, 'keyframes', value, `${reason} (REQ-API-033)`));
+    if (captured.length < 2) {
+        throw new validate_1.InvalidTargetError(undefined, 'keyframes', captured, 'a keyframe array must have at least two keyframes (REQ-API-033)');
+    }
+    for (let index = 0; index < captured.length; index++) {
+        if (!Object.hasOwn(captured, index)) {
+            throw new validate_1.InvalidTargetError(undefined, 'keyframes', captured, `keyframe array is missing index ${index}; sparse keyframe arrays are invalid (REQ-API-033)`);
+        }
+        const value = captured[index];
+        if (value === null && index === 0)
+            continue;
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new validate_1.InvalidTargetError(undefined, 'keyframes', captured, `keyframe at index ${index} must be a finite number${index === 0 ? ' or null' : ''} (REQ-API-033)`);
+        }
+    }
+    return captured;
+}
+function captureConfig(config) {
+    if (config === undefined)
+        return undefined;
+    // This exported generator is a raw public boundary, not merely a downstream helper. Prove the
+    // outer record BEFORE reading a field so null/array/prototype-bearing values become the typed
+    // transition refusal instead of a host TypeError (R8 review r9). Getter faults deliberately
+    // remain unguarded: caller faults retain their identity rather than being laundered as schema
+    // errors.
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+        throw new validate_1.InvalidTransitionError(undefined, 'config', config, 'keyframesGenerator config must be a plain object (REQ-API-033)');
+    }
+    const prototype = Object.getPrototypeOf(config);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new validate_1.InvalidTransitionError(undefined, 'config', config, 'keyframesGenerator config must not carry a prototype (REQ-API-033)');
+    }
+    for (const key of Reflect.ownKeys(config)) {
+        if (key !== 'duration' && key !== 'times' && key !== 'ease') {
+            throw new validate_1.InvalidTransitionError(undefined, typeof key === 'string' ? key : String(key), config, 'keyframesGenerator config permits only own duration, times, and ease fields (REQ-API-033)');
+        }
+    }
+    const duration = Object.hasOwn(config, 'duration') ? config.duration : undefined;
+    const times = Object.hasOwn(config, 'times') ? config.times : undefined;
+    const ease = Object.hasOwn(config, 'ease') ? config.ease : undefined;
+    if (duration !== undefined &&
+        (typeof duration !== 'number' || !Number.isFinite(duration) || duration < 0)) {
+        throw new validate_1.InvalidTransitionError(undefined, 'duration', duration, 'keyframesGenerator duration must be a finite non-negative number of milliseconds (REQ-API-033)');
+    }
+    if (times !== undefined && !Array.isArray(times)) {
+        throw new validate_1.InvalidTransitionError(undefined, 'times', times, 'times must be a real array of offsets (REQ-API-033 law d)');
+    }
+    return Object.freeze({
+        ...(duration === undefined ? {} : { duration }),
+        ...(times === undefined
+            ? {}
+            : {
+                times: captureArray(times, (value, reason) => new validate_1.InvalidTransitionError(undefined, 'times', value, `${reason}; times must be real offsets (REQ-API-033 law d)`)),
+            }),
+        ...(ease === undefined
+            ? {}
+            : {
+                ease: Array.isArray(ease)
+                    ? captureArray(ease, (value, reason) => new validate_1.InvalidTransitionError(undefined, 'ease', value, `${reason}; ease must be a real easing list (REQ-API-033 law d)`))
+                    : ease,
+            }),
+    });
+}
+/**
+ * Build a multi-keyframe tween `GeneratorFactory` (REQ-API-033). The array length is ≥2 and the
+ * `times`/`ease` shapes are enforced at the validation boundary (validate.ts); this generator
+ * assumes a valid config and is pure per frame.
+ */
+// alloc-ok: lifecycle-edge — the factory resolves offsets + per-segment easers once per animate
+// command; per-frame work is sample() below, which mutates the reused record and allocates nothing.
+function keyframesGenerator(keyframes, config) {
+    const capturedKeyframes = captureKeyframes(keyframes);
+    const capturedConfig = captureConfig(config);
+    const n = capturedKeyframes.length;
+    const refusal = (0, keyframeTiming_1.keyframeConfigRefusal)(capturedKeyframes, capturedConfig);
+    if (refusal !== null)
+        throw refusal;
+    const duration = capturedConfig?.duration ?? DEFAULT_DURATION_MS;
+    // Motion uses authored offsets only when their count matches the keyframes; every other shape-valid
+    // count (including zero) falls back to defaultOffset. Resolve through the shared UI-safe seam.
+    const times = capturedKeyframes.map((_value, index) => (0, keyframeTimingConfig_1.keyframeOffsetAt)(capturedConfig?.times, index, n) * duration);
+    // A list maps available easings by segment; Motion's interpolate uses linear (`noop`) for a missing
+    // member and ignores extras. An absent list still receives the generator's easeInOut default.
+    const segmentEasers = [];
+    for (let i = 0; i < n - 1; i++) {
+        segmentEasers.push((0, timing_1.resolveEasing)((0, keyframeTimingConfig_1.keyframeSegmentEase)(capturedConfig?.ease, i)));
+    }
+    return (seed) => {
+        // null-first (R8-F2): the first keyframe reads the element's current value.
+        // alloc-ok: lifecycle-edge — one values/segments build per generator construction.
+        const values = capturedKeyframes.map((value) => (value === null ? seed.from : value));
+        // Precompute well-typed segments once. The ≥2-length + `times`/`ease` shape laws are enforced at
+        // the validation boundary (validate.ts); the undefined-guard keeps this generator TOTAL and
+        // type-safe under noUncheckedIndexedAccess (it is never hit for valid input) — no per-frame
+        // array indexing, no non-null assertions.
+        const segments = [];
+        for (let i = 0; i < values.length - 1; i++) {
+            const from = values[i];
+            const to = values[i + 1];
+            const start = times[i];
+            const end = times[i + 1];
+            const ease = segmentEasers[i];
+            if (from === undefined ||
+                to === undefined ||
+                start === undefined ||
+                end === undefined ||
+                ease === undefined)
+                continue;
+            segments.push({ start, end, from, to, ease });
+        }
+        const firstSeg = segments[0];
+        const lastSeg = segments[segments.length - 1];
+        const first = firstSeg ? firstSeg.from : seed.from;
+        const last = lastSeg ? lastSeg.to : first;
+        const firstTime = firstSeg ? firstSeg.start : 0;
+        const lastTime = lastSeg ? lastSeg.end : 0;
+        const value = (t) => {
+            if (t <= firstTime)
+                return first;
+            if (t >= lastTime)
+                return last;
+            // bounded segment scan — no iterator alloc, no indexed access after the guard-narrow.
+            for (let i = 0; i < segments.length; i++) {
+                const seg = segments[i];
+                if (seg === undefined)
+                    break;
+                if (t <= seg.end) {
+                    const span = seg.end - seg.start;
+                    const localP = span > 0 ? (t - seg.start) / span : 1;
+                    return mix(seg.from, seg.to, seg.ease(clamp01(localP)));
+                }
+            }
+            return last;
+        };
+        const out = { value: first, velocity: 0, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const prevT = Math.max(elapsedMs - VELOCITY_SAMPLE_MS, 0);
+                const dt = elapsedMs - prevT;
+                const velocity = dt ? ((current - value(prevT)) / dt) * 1000 : 0; // px/s (REQ-TIMING-001)
+                const done = elapsedMs >= duration;
+                out.value = done ? last : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/keyframes.d.cts

@@ -0,0 +1,13 @@
+import { type Easing } from "./timing.cjs";
+import type { GeneratorFactory } from "./types.cjs";
+export interface KeyframesConfig {
+    duration?: number;
+    times?: readonly number[];
+    ease?: Easing | readonly Easing[];
+}
+/**
+ * Build a multi-keyframe tween `GeneratorFactory` (REQ-API-033). The array length is ≥2 and the
+ * `times`/`ease` shapes are enforced at the validation boundary (validate.ts); this generator
+ * assumes a valid config and is pure per frame.
+ */
+export declare function keyframesGenerator(keyframes: readonly (number | null)[], config?: KeyframesConfig): GeneratorFactory;

package/dist/keyframes.d.ts

@@ -0,0 +1,13 @@
+import { type Easing } from "./timing.js";
+import type { GeneratorFactory } from "./types.js";
+export interface KeyframesConfig {
+    duration?: number;
+    times?: readonly number[];
+    ease?: Easing | readonly Easing[];
+}
+/**
+ * Build a multi-keyframe tween `GeneratorFactory` (REQ-API-033). The array length is ≥2 and the
+ * `times`/`ease` shapes are enforced at the validation boundary (validate.ts); this generator
+ * assumes a valid config and is pure per frame.
+ */
+export declare function keyframesGenerator(keyframes: readonly (number | null)[], config?: KeyframesConfig): GeneratorFactory;

package/dist/keyframes.js

@@ -0,0 +1,188 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// The multi-keyframe timing generator (REQ-API-033, R8). Interpolates THROUGH a keyframe array over
+// `duration`: even `defaultOffset` unless `times`, one `easeInOut` per SEGMENT unless an `ease`
+// array, `keyframes[0]` seeds — or the element's CURRENT value when the first keyframe is `null`
+// (R8-F2). Semantics pinned to motion@12.42.2's generators/keyframes.ts; the cubic-bezier easing is
+// timing.ts's exact BezierEasing port (never a second vocabulary). The reused sample record and the
+// bounded segment scan allocate nothing per frame.
+import { InvalidTargetError, InvalidTransitionError } from "./component/validate.js";
+import { resolveEasing } from "./timing.js";
+import { keyframeConfigRefusal } from "./driver/keyframeTiming.js";
+import { keyframeOffsetAt, keyframeSegmentEase } from "./driver/keyframeTimingConfig.js";
+import { captureBoundedArray, captureBoundedCubicBezier, capturedArrayDescription, MAX_CAPTURED_ARRAY_LENGTH, } from "./component/boundedArray.js";
+const DEFAULT_DURATION_MS = 300; // REQ-TIMING-002 (0.3s), motion's keyframes default
+const VELOCITY_SAMPLE_MS = 5;
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+const mix = (from, to, p) => from + (to - from) * p;
+function captureArray(value, invalid, nested = false) {
+    const capture = nested ? captureBoundedCubicBezier(value) : captureBoundedArray(value);
+    if (capture.kind === 'not-array')
+        throw invalid(capturedArrayDescription(capture), 'must be a real array');
+    if (capture.kind === 'invalid-length') {
+        throw invalid(capturedArrayDescription(capture), nested
+            ? 'must be a four-point cubic-bezier tuple (REQ-API-033)'
+            : `must have a safe array length between 0 and ${MAX_CAPTURED_ARRAY_LENGTH} (REQ-API-033)`);
+    }
+    const length = capture.values.length;
+    const captured = [];
+    captured.length = length;
+    for (let index = 0; index < length; index++) {
+        if (!Object.hasOwn(capture.values, index))
+            continue;
+        const member = capture.values[index];
+        captured[index] =
+            !nested && Array.isArray(member) ? captureArray(member, invalid, true) : member;
+    }
+    return Object.freeze(captured);
+}
+function captureKeyframes(keyframes) {
+    const captured = captureArray(keyframes, (value, reason) => new InvalidTargetError(undefined, 'keyframes', value, `${reason} (REQ-API-033)`));
+    if (captured.length < 2) {
+        throw new InvalidTargetError(undefined, 'keyframes', captured, 'a keyframe array must have at least two keyframes (REQ-API-033)');
+    }
+    for (let index = 0; index < captured.length; index++) {
+        if (!Object.hasOwn(captured, index)) {
+            throw new InvalidTargetError(undefined, 'keyframes', captured, `keyframe array is missing index ${index}; sparse keyframe arrays are invalid (REQ-API-033)`);
+        }
+        const value = captured[index];
+        if (value === null && index === 0)
+            continue;
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new InvalidTargetError(undefined, 'keyframes', captured, `keyframe at index ${index} must be a finite number${index === 0 ? ' or null' : ''} (REQ-API-033)`);
+        }
+    }
+    return captured;
+}
+function captureConfig(config) {
+    if (config === undefined)
+        return undefined;
+    // This exported generator is a raw public boundary, not merely a downstream helper. Prove the
+    // outer record BEFORE reading a field so null/array/prototype-bearing values become the typed
+    // transition refusal instead of a host TypeError (R8 review r9). Getter faults deliberately
+    // remain unguarded: caller faults retain their identity rather than being laundered as schema
+    // errors.
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+        throw new InvalidTransitionError(undefined, 'config', config, 'keyframesGenerator config must be a plain object (REQ-API-033)');
+    }
+    const prototype = Object.getPrototypeOf(config);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new InvalidTransitionError(undefined, 'config', config, 'keyframesGenerator config must not carry a prototype (REQ-API-033)');
+    }
+    for (const key of Reflect.ownKeys(config)) {
+        if (key !== 'duration' && key !== 'times' && key !== 'ease') {
+            throw new InvalidTransitionError(undefined, typeof key === 'string' ? key : String(key), config, 'keyframesGenerator config permits only own duration, times, and ease fields (REQ-API-033)');
+        }
+    }
+    const duration = Object.hasOwn(config, 'duration') ? config.duration : undefined;
+    const times = Object.hasOwn(config, 'times') ? config.times : undefined;
+    const ease = Object.hasOwn(config, 'ease') ? config.ease : undefined;
+    if (duration !== undefined &&
+        (typeof duration !== 'number' || !Number.isFinite(duration) || duration < 0)) {
+        throw new InvalidTransitionError(undefined, 'duration', duration, 'keyframesGenerator duration must be a finite non-negative number of milliseconds (REQ-API-033)');
+    }
+    if (times !== undefined && !Array.isArray(times)) {
+        throw new InvalidTransitionError(undefined, 'times', times, 'times must be a real array of offsets (REQ-API-033 law d)');
+    }
+    return Object.freeze({
+        ...(duration === undefined ? {} : { duration }),
+        ...(times === undefined
+            ? {}
+            : {
+                times: captureArray(times, (value, reason) => new InvalidTransitionError(undefined, 'times', value, `${reason}; times must be real offsets (REQ-API-033 law d)`)),
+            }),
+        ...(ease === undefined
+            ? {}
+            : {
+                ease: Array.isArray(ease)
+                    ? captureArray(ease, (value, reason) => new InvalidTransitionError(undefined, 'ease', value, `${reason}; ease must be a real easing list (REQ-API-033 law d)`))
+                    : ease,
+            }),
+    });
+}
+/**
+ * Build a multi-keyframe tween `GeneratorFactory` (REQ-API-033). The array length is ≥2 and the
+ * `times`/`ease` shapes are enforced at the validation boundary (validate.ts); this generator
+ * assumes a valid config and is pure per frame.
+ */
+// alloc-ok: lifecycle-edge — the factory resolves offsets + per-segment easers once per animate
+// command; per-frame work is sample() below, which mutates the reused record and allocates nothing.
+export function keyframesGenerator(keyframes, config) {
+    const capturedKeyframes = captureKeyframes(keyframes);
+    const capturedConfig = captureConfig(config);
+    const n = capturedKeyframes.length;
+    const refusal = keyframeConfigRefusal(capturedKeyframes, capturedConfig);
+    if (refusal !== null)
+        throw refusal;
+    const duration = capturedConfig?.duration ?? DEFAULT_DURATION_MS;
+    // Motion uses authored offsets only when their count matches the keyframes; every other shape-valid
+    // count (including zero) falls back to defaultOffset. Resolve through the shared UI-safe seam.
+    const times = capturedKeyframes.map((_value, index) => keyframeOffsetAt(capturedConfig?.times, index, n) * duration);
+    // A list maps available easings by segment; Motion's interpolate uses linear (`noop`) for a missing
+    // member and ignores extras. An absent list still receives the generator's easeInOut default.
+    const segmentEasers = [];
+    for (let i = 0; i < n - 1; i++) {
+        segmentEasers.push(resolveEasing(keyframeSegmentEase(capturedConfig?.ease, i)));
+    }
+    return (seed) => {
+        // null-first (R8-F2): the first keyframe reads the element's current value.
+        // alloc-ok: lifecycle-edge — one values/segments build per generator construction.
+        const values = capturedKeyframes.map((value) => (value === null ? seed.from : value));
+        // Precompute well-typed segments once. The ≥2-length + `times`/`ease` shape laws are enforced at
+        // the validation boundary (validate.ts); the undefined-guard keeps this generator TOTAL and
+        // type-safe under noUncheckedIndexedAccess (it is never hit for valid input) — no per-frame
+        // array indexing, no non-null assertions.
+        const segments = [];
+        for (let i = 0; i < values.length - 1; i++) {
+            const from = values[i];
+            const to = values[i + 1];
+            const start = times[i];
+            const end = times[i + 1];
+            const ease = segmentEasers[i];
+            if (from === undefined ||
+                to === undefined ||
+                start === undefined ||
+                end === undefined ||
+                ease === undefined)
+                continue;
+            segments.push({ start, end, from, to, ease });
+        }
+        const firstSeg = segments[0];
+        const lastSeg = segments[segments.length - 1];
+        const first = firstSeg ? firstSeg.from : seed.from;
+        const last = lastSeg ? lastSeg.to : first;
+        const firstTime = firstSeg ? firstSeg.start : 0;
+        const lastTime = lastSeg ? lastSeg.end : 0;
+        const value = (t) => {
+            if (t <= firstTime)
+                return first;
+            if (t >= lastTime)
+                return last;
+            // bounded segment scan — no iterator alloc, no indexed access after the guard-narrow.
+            for (let i = 0; i < segments.length; i++) {
+                const seg = segments[i];
+                if (seg === undefined)
+                    break;
+                if (t <= seg.end) {
+                    const span = seg.end - seg.start;
+                    const localP = span > 0 ? (t - seg.start) / span : 1;
+                    return mix(seg.from, seg.to, seg.ease(clamp01(localP)));
+                }
+            }
+            return last;
+        };
+        const out = { value: first, velocity: 0, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const prevT = Math.max(elapsedMs - VELOCITY_SAMPLE_MS, 0);
+                const dt = elapsedMs - prevT;
+                const velocity = dt ? ((current - value(prevT)) / dt) * 1000 : 0; // px/s (REQ-TIMING-001)
+                const done = elapsedMs >= duration;
+                out.value = done ? last : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/layout/commitDetector.cjs

@@ -0,0 +1,67 @@
+"use strict";
+// Commit detection for the L3 no-flash correction (specs/L3-BUILD-PACKET.md §Order 1): dedupe a
+// per-frame stream of measured layout rects into COMMIT events. The UI-thread frame step feeds
+// the committed layout it measures each frame; the detector answers "did the host commit a NEW
+// layout this frame?" so the caller can apply the FLIP inversion in the same frame — before
+// paint. Host-agnostic and pure: the caller owns WHERE rects come from (the spike must feed
+// transform-free layout values — a measure that reflected the correction transform would feed
+// the projection back into measurement, which is forbidden by the standing law).
+//
+// Fail-closed lifecycle (REQ-LAYOUT-011 posture): a null read is 'unmeasured' — never an event,
+// never a fabricated previous rect; the FIRST non-null rect is 'initial' (nothing to correct
+// from); only a rect that DIFFERS from the last committed one is a 'commit' carrying
+// {previous, next}. Equality is exact: two commits that produce identical layout values are the
+// same layout — the detector never invents a zero-delta commit.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommitDetector = createCommitDetector;
+function rectsEqual(a, b) {
+    'worklet';
+    return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+function isFiniteRect(rect) {
+    'worklet';
+    return (Number.isFinite(rect.x) &&
+        Number.isFinite(rect.y) &&
+        Number.isFinite(rect.width) &&
+        Number.isFinite(rect.height));
+}
+function createCommitDetector(options) {
+    'worklet';
+    let committed = null;
+    let refusalReported = false;
+    return {
+        feed(rect) {
+            'worklet';
+            if (rect === null)
+                return { kind: 'unmeasured' };
+            if (!isFiniteRect(rect)) {
+                if (options?.onRefusal === undefined) {
+                    // ui-throw-ok: JS-side public-API loud path (seal r8, F1) — reachable only when the
+                    // detector was constructed WITHOUT a refusal reporter, which the UI-runtime wiring
+                    // never does (it injects the deferred reporter, per the options contract above); a
+                    // bare public construction is a JS consumer, where fail-loud beats a silent swallow.
+                    throw new Error(`layout commit detector: refused a malformed rect (${JSON.stringify(rect)}) — ` +
+                        'non-finite fields never become a commit (L3 packet; M2.5 §semantics 6 posture). ' +
+                        'No refusal reporter installed — the bare public API fails loud (seal r8, F1).');
+                }
+                if (!refusalReported) {
+                    refusalReported = true;
+                    options.onRefusal(`layout commit detector: refused a malformed rect (${JSON.stringify(rect)}) — ` +
+                        'non-finite fields never become a commit (L3 packet; M2.5 §semantics 6 posture).');
+                }
+                // The refusal itself: no commit is recorded — the detector keeps the last valid state.
+                return committed === null ? { kind: 'unmeasured' } : { kind: 'unchanged', rect: committed };
+            }
+            if (committed === null) {
+                committed = rect;
+                return { kind: 'initial', rect };
+            }
+            if (rectsEqual(committed, rect))
+                return { kind: 'unchanged', rect };
+            const previous = committed;
+            committed = rect;
+            return { kind: 'commit', previous, next: rect };
+        },
+        committed: () => committed,
+    };
+}

package/dist/layout/commitDetector.d.cts

@@ -0,0 +1,21 @@
+import type { Rect } from "./types.cjs";
+export type CommitDetection = {
+    readonly kind: 'unmeasured';
+} | {
+    readonly kind: 'initial';
+    readonly rect: Rect;
+} | {
+    readonly kind: 'unchanged';
+    readonly rect: Rect;
+} | {
+    readonly kind: 'commit';
+    readonly previous: Rect;
+    readonly next: Rect;
+};
+export interface CommitDetector {
+    feed(rect: Rect | null): CommitDetection;
+    committed(): Rect | null;
+}
+export declare function createCommitDetector(options?: {
+    readonly onRefusal?: (detail: string) => void;
+}): CommitDetector;

package/dist/layout/commitDetector.d.ts

@@ -0,0 +1,21 @@
+import type { Rect } from "./types.js";
+export type CommitDetection = {
+    readonly kind: 'unmeasured';
+} | {
+    readonly kind: 'initial';
+    readonly rect: Rect;
+} | {
+    readonly kind: 'unchanged';
+    readonly rect: Rect;
+} | {
+    readonly kind: 'commit';
+    readonly previous: Rect;
+    readonly next: Rect;
+};
+export interface CommitDetector {
+    feed(rect: Rect | null): CommitDetection;
+    committed(): Rect | null;
+}
+export declare function createCommitDetector(options?: {
+    readonly onRefusal?: (detail: string) => void;
+}): CommitDetector;

package/dist/layout/commitDetector.js

@@ -0,0 +1,64 @@
+// Commit detection for the L3 no-flash correction (specs/L3-BUILD-PACKET.md §Order 1): dedupe a
+// per-frame stream of measured layout rects into COMMIT events. The UI-thread frame step feeds
+// the committed layout it measures each frame; the detector answers "did the host commit a NEW
+// layout this frame?" so the caller can apply the FLIP inversion in the same frame — before
+// paint. Host-agnostic and pure: the caller owns WHERE rects come from (the spike must feed
+// transform-free layout values — a measure that reflected the correction transform would feed
+// the projection back into measurement, which is forbidden by the standing law).
+//
+// Fail-closed lifecycle (REQ-LAYOUT-011 posture): a null read is 'unmeasured' — never an event,
+// never a fabricated previous rect; the FIRST non-null rect is 'initial' (nothing to correct
+// from); only a rect that DIFFERS from the last committed one is a 'commit' carrying
+// {previous, next}. Equality is exact: two commits that produce identical layout values are the
+// same layout — the detector never invents a zero-delta commit.
+function rectsEqual(a, b) {
+    'worklet';
+    return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+function isFiniteRect(rect) {
+    'worklet';
+    return (Number.isFinite(rect.x) &&
+        Number.isFinite(rect.y) &&
+        Number.isFinite(rect.width) &&
+        Number.isFinite(rect.height));
+}
+export function createCommitDetector(options) {
+    'worklet';
+    let committed = null;
+    let refusalReported = false;
+    return {
+        feed(rect) {
+            'worklet';
+            if (rect === null)
+                return { kind: 'unmeasured' };
+            if (!isFiniteRect(rect)) {
+                if (options?.onRefusal === undefined) {
+                    // ui-throw-ok: JS-side public-API loud path (seal r8, F1) — reachable only when the
+                    // detector was constructed WITHOUT a refusal reporter, which the UI-runtime wiring
+                    // never does (it injects the deferred reporter, per the options contract above); a
+                    // bare public construction is a JS consumer, where fail-loud beats a silent swallow.
+                    throw new Error(`layout commit detector: refused a malformed rect (${JSON.stringify(rect)}) — ` +
+                        'non-finite fields never become a commit (L3 packet; M2.5 §semantics 6 posture). ' +
+                        'No refusal reporter installed — the bare public API fails loud (seal r8, F1).');
+                }
+                if (!refusalReported) {
+                    refusalReported = true;
+                    options.onRefusal(`layout commit detector: refused a malformed rect (${JSON.stringify(rect)}) — ` +
+                        'non-finite fields never become a commit (L3 packet; M2.5 §semantics 6 posture).');
+                }
+                // The refusal itself: no commit is recorded — the detector keeps the last valid state.
+                return committed === null ? { kind: 'unmeasured' } : { kind: 'unchanged', rect: committed };
+            }
+            if (committed === null) {
+                committed = rect;
+                return { kind: 'initial', rect };
+            }
+            if (rectsEqual(committed, rect))
+                return { kind: 'unchanged', rect };
+            const previous = committed;
+            committed = rect;
+            return { kind: 'commit', previous, next: rect };
+        },
+        committed: () => committed,
+    };
+}

package/dist/layout/compose.cjs

@@ -0,0 +1,67 @@
+"use strict";
+// SPEC-LAYOUT §2/§4a — parent-relative composition + distortion correction (REQ-LAYOUT-012/013). A nested
+// child is positioned relative to the animating ancestor's projection frame, so it composes coherently and
+// is never left behind at its pre-animation viewport origin. A child carrying layout identity under a scaled
+// parent gets a counter-scale to keep its intrinsic size, and border-radius is corrected under non-unit
+// scale. A property that cannot be corrected under a scaled layout fails loud (REQ-LAYOUT-013 → REQ-API-005/
+// 006). Pure; consumes the frozen SUBSET registry (existence check) but owns no second property registry.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeParentRelative = composeParentRelative;
+exports.counterScale = counterScale;
+exports.correctRadius = correctRadius;
+exports.assertCorrectable = assertCorrectable;
+const subset_1 = require("../subset/index.cjs");
+const projection_1 = require("./projection.cjs");
+/**
+ * The viewport rect of a child at progress `p`, positioned parent-relative (REQ-LAYOUT-012). `childLocal` is
+ * the child's rect in the parent's LOCAL space (relative to the parent's top-left, in the after frame). The
+ * child rides the parent's projection: its origin and size scale with the parent's current visual frame, so
+ * its fractional position within the parent is invariant across progress and it is never stranded at its
+ * host-absolute origin while the parent is displaced.
+ */
+function composeParentRelative(parentBefore, parentAfter, childLocal, progress) {
+    const tp = (0, projection_1.projectAtProgress)(parentBefore, parentAfter, progress);
+    const parentVisual = (0, projection_1.applyTransformToRect)(tp, parentAfter);
+    return {
+        x: parentVisual.x + childLocal.x * tp.scaleX,
+        y: parentVisual.y + childLocal.y * tp.scaleY,
+        width: childLocal.width * tp.scaleX,
+        height: childLocal.height * tp.scaleY,
+    };
+}
+function assertNonZeroScale(scaleX, scaleY) {
+    if (!Number.isFinite(scaleX) || !Number.isFinite(scaleY) || scaleX === 0 || scaleY === 0) {
+        throw new Error(`layout: cannot counter-correct under a zero/non-finite scale (scaleX=${scaleX}, scaleY=${scaleY}) — divide-by-zero guard (REQ-LAYOUT-011)`);
+    }
+}
+/**
+ * The counter-scale a child carrying layout identity applies to cancel its parent's scale, so it keeps its
+ * intrinsic size under a scaled layout (REQ-LAYOUT-013). `parent.scaleX × counterScale.scaleX == 1`.
+ */
+function counterScale(parent) {
+    assertNonZeroScale(parent.scaleX, parent.scaleY);
+    return { translateX: 0, translateY: 0, scaleX: 1 / parent.scaleX, scaleY: 1 / parent.scaleY };
+}
+/**
+ * Correct a border-radius under a non-unit scale (REQ-LAYOUT-013): dividing by the axis scale so the applied
+ * scale reproduces the intended visual radius. Anisotropic scale yields distinct x/y radii.
+ */
+function correctRadius(radius, scaleX, scaleY) {
+    assertNonZeroScale(scaleX, scaleY);
+    return { x: radius / scaleX, y: radius / scaleY };
+}
+// LAYOUT's proposed set of properties that are corrected under a scaled layout. This is the subsystem's
+// CONTRIBUTION to the universal subset (REQ-LAYOUT-013), pending SUBSET ratification (§7) — NOT a second
+// registry. Size is handled structurally by counterScale; borderRadius by correctRadius.
+const LAYOUT_CORRECTABLE = new Set(['borderRadius']);
+/**
+ * Assert a property can be corrected under a scaled layout, else fail loud (REQ-LAYOUT-013 → REQ-API-005/006)
+ * rather than rendering a distorted result. Consults the frozen registry only to sharpen the message
+ * (known style prop vs typo); the correctable set is LAYOUT's own contribution, pending ratification.
+ */
+function assertCorrectable(property) {
+    if (LAYOUT_CORRECTABLE.has(property))
+        return;
+    const known = subset_1.UNIVERSAL_SUBSET.has(property);
+    throw new Error(`layout: '${property}' is ${known ? 'a known style property but is not' : 'not a known style property and is not'} correctable under a scaled layout at M1 — the correctable set is {borderRadius} (size via counter-scale), LAYOUT's proposed contribution to the universal subset (§7, pending SUBSET ratification). Fails loud rather than rendering distorted (REQ-LAYOUT-013).`);
+}