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

package/dist/component/variants.js

@@ -0,0 +1,321 @@
+// SPEC-COMPONENT §2 — REQ-API-032: the variants resolution core (R7). Pure, host-agnostic,
+// deterministic over (definition, dictionary, live state) — the pinned `resolveVariantFromProps`
+// chain including its runtime-only direct function form. Law (a): a local dictionary miss is the pinned
+// NO-OP (the propagation-source shape), never an error. Law (b): animation-time arrays
+// resolve to ORDERED per-label applications, each preserving its own embedded transition.
+// Law (c): initial labels overlay synchronously into one first-paint state, transitions
+// discarded. Law (f): the eager shape + entry validation — outer shapes typed as a unit,
+// per-entry validation through the SAME target/transition boundaries the animate lane
+// rides. The FUNCTION form (T24 B2, dynamic variants) is accepted at the boundary by
+// identity and validated at RESOLUTION, where its result exists.
+import { InvalidTransitionError, validateTargetRefusal, validateTransitionRefusal, } from "./validate.js";
+import { keyframeTransitionRefusal } from "../driver/keyframeTiming.js";
+import { captureTransition } from "../driver/prepare.js";
+import { captureBoundedArray, capturedArrayDescription } from "./boundedArray.js";
+import { normalizeTransitionEaseAlias, resolveTransitionForKey } from "./transition.js";
+// Thrown for malformed variants SHAPES (REQ-API-014's structured pattern): the key names the
+// offending unit ('(variants)' for the outer shape, the label for an entry).
+export class InvalidVariantError extends Error {
+    key;
+    value;
+    constructor(key, value, reason, cause) {
+        super(`invalid variants ${key === '(variants)' ? 'prop' : `entry '${key}'`} — ${reason}`, cause !== undefined ? { cause } : undefined);
+        this.name = 'InvalidVariantError';
+        this.key = key;
+        this.value = value;
+    }
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+// Hostile-input architecture (M3 r3 majors 1b53e9337aec/13af48a64530): severity gates never
+// CATCH around code that can run foreign traps/getters — any durable "ownership" mark on an
+// error object is forgeable or replayable, and trusting exported classes launders authentic
+// sentinels. Instead every boundary primitive is RETURN-shaped with PHASE-SEPARATED reads:
+// foreign code (prototype probes, getters, enumeration traps) runs UNGUARDED first — its
+// faults propagate untouched by construction — and validation then operates on plain
+// snapshots, so a returned refusal is boundary-made by construction and nothing else is
+// ever classified.
+/**
+ * Law (f), outer shape, RETURN-shaped: the typed refusal, or null when `variants` is a
+ * plain object. The probe itself may throw on hostile values (a getPrototypeOf trap, a
+ * revoked proxy) — those faults propagate untouched; only the RETURNED refusal is input
+ * refusal.
+ */
+export function variantsShapeRefusal(value) {
+    if (isPlainObject(value))
+        return null;
+    return new InvalidVariantError('(variants)', value, 'the dictionary must be a plain object of label → target entries (REQ-API-032 law f; ' +
+        'a malformed shape fails loud, never coerces to the empty dictionary)');
+}
+/**
+ * Law (f), outer shape: `variants` must be a plain object — null, arrays, and
+ * prototype-carrying objects refuse AS A UNIT (typed), never coerce to an empty dictionary.
+ */
+export function assertVariantsShape(value) {
+    const refusal = variantsShapeRefusal(value);
+    if (refusal !== null)
+        throw refusal;
+}
+/**
+ * Law (f), per entry: an entry must be a plain object whose members validate through the
+ * SAME boundaries the animate lane rides — core validateTarget for the target members and
+ * the REQ-API-031 transition law for the embedded transition — or a RESOLVER (T24 B2),
+ * accepted uninvoked and validated at resolution.
+ */
+export function validateVariantEntry(label, entry, host, opts) {
+    const { refusal } = validateVariantEntrySnapshot(label, entry, host, opts);
+    if (refusal !== null)
+        throw refusal;
+}
+/**
+ * Law (f), per entry, RETURN-shaped + SNAPSHOT-accepting (M3 r3 majors 13af48a64530 +
+ * 5cb2381e272c; hardened r4 majors 4db96de50131 + 93bab4ecf757): the READ phase runs first
+ * and UNGUARDED — the entry's getters and every level of a transition's enumeration traps
+ * fire here, so their faults (including authentic same-class sentinels) propagate
+ * untouched. Validation then runs on DEEP-plain snapshots, and the SNAPSHOT is what the
+ * caller accepts: a stateful proxy cannot show the validators one value and the engine
+ * another (one read, one truth). Residual bound, stated honestly: hostile LEAF objects
+ * (non-array, non-plain) stay by reference and are refused by the validators' trap-free
+ * type checks — they are never enumerated inside the trusted region.
+ */
+export function validateVariantEntrySnapshot(label, entry, host, opts) {
+    if (typeof entry === 'function') {
+        // T24 B2: the dynamic form is ACCEPTED at the boundary, by identity and UNINVOKED — its
+        // keys do not exist until resolution, so entry validation applies to its RESULT at the
+        // resolution seam (resolveVariantDefinition), never here.
+        return { refusal: null, entry: entry };
+    }
+    if (!isPlainObject(entry)) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label} must be a plain target entry (REQ-API-032 law f)`),
+            entry: null,
+        };
+    }
+    // READ phase — every getter and enumeration trap fires HERE, outside any try.
+    const { transition: rawTransition, ...rawTarget } = entry;
+    // Materialize each ARRAY member ONCE, before validation (R8, review major 18): a shallow snapshot let
+    // the validators read a member's elements and the accepted clone read them AGAIN, so a hostile
+    // accessor-backed array (100 then null) could pass validation yet land the unvalidated null in the
+    // snapshot. The bounded capture reads each own index exactly once; the frozen copy is the SINGLE truth both the
+    // validators and the accepted entry see. Non-array members pass through unchanged. The accumulator is
+    // NULL-PROTOTYPE (review major 24): a SCALAR own '__proto__' member assigned onto an ordinary object
+    // is a silent no-op setter (the key vanishes yet the snapshot stays plain and passes the shape gate) —
+    // a null-prototype object makes it an own data property so the capability gate refuses it, loudly.
+    const targetSnapshot = Object.create(null);
+    for (const [key, member] of Object.entries(rawTarget)) {
+        if (!Array.isArray(member)) {
+            targetSnapshot[key] = member;
+            continue;
+        }
+        const captured = captureBoundedArray(member);
+        if (captured.kind !== 'captured') {
+            return {
+                refusal: new InvalidVariantError(label, capturedArrayDescription(captured), `variants.${label} keyframe arrays must have a safe length between 0 and 100000 (REQ-API-033)`),
+                entry: null,
+            };
+        }
+        targetSnapshot[key] = captured.values;
+    }
+    let transitionSnapshot;
+    if (rawTransition === undefined) {
+        transitionSnapshot = undefined;
+    }
+    else if (isPlainObject(rawTransition)) {
+        // Reuse the value-preserving transition capture used by every raw/supplying boundary. It keeps
+        // symbols, unknown strings, and non-enumerable known fields for validateTransitionRefusal while
+        // deeply snapshotting only legal timing arrays.
+        transitionSnapshot = captureTransition(rawTransition);
+    }
+    else {
+        // A non-plain transition cannot be faithfully snapshotted — spreading a Date/Map/array
+        // yields the EMPTY object, silently laundering the malformed shape into a valid empty
+        // transition (M3 r4 major 4db96de50131). The refusal is constructed HERE, return-shaped,
+        // mirroring validateTransition's own shape law verbatim (message + category parity);
+        // the value is never probed again.
+        const shapeCause = new InvalidTransitionError(opts?.componentId, '(transition)', rawTransition, 'a transition must be a plain object of transition options (G-INV-8 — a malformed config ' +
+            'fails loud, never coerces to the default transition)');
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${shapeCause.message}`, shapeCause),
+            entry: null,
+        };
+    }
+    // RETURN-shaped validators, NO catch (M3 r6 major 30a9c21bf960): a returned refusal is
+    // validator-made by construction; anything THROWN — including an authentic same-class
+    // sentinel from a polluted dependency (Set.prototype.has) — propagates untouched because
+    // nothing here catches it.
+    const transitionRefusal = validateTransitionRefusal(transitionSnapshot, opts);
+    if (transitionRefusal === null && transitionSnapshot !== undefined) {
+        // Family-2: web pin consumes `ease`; rewrite catalog `easings` on the accepted snapshot so
+        // every supplier (variant embed, element, MotionConfig) hands the same normalized shape.
+        transitionSnapshot = normalizeTransitionEaseAlias(transitionSnapshot);
+    }
+    if (transitionRefusal !== null) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${transitionRefusal.message}`, transitionRefusal),
+            entry: null,
+        };
+    }
+    const targetRefusal = validateTargetRefusal(targetSnapshot, host, opts);
+    if (targetRefusal !== null) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${targetRefusal.message}`, targetRefusal),
+            entry: null,
+        };
+    }
+    for (const [key, value] of Object.entries(targetSnapshot)) {
+        const effectiveTransition = transitionSnapshot === undefined
+            ? undefined
+            : resolveTransitionForKey(transitionSnapshot, key);
+        const timingRefusal = keyframeTransitionRefusal(opts?.componentId, key, value, effectiveTransition);
+        if (timingRefusal !== null) {
+            return {
+                refusal: new InvalidVariantError(label, entry, `variants.${label}: ${timingRefusal.message}`, timingRefusal),
+                entry: null,
+            };
+        }
+    }
+    // The accepted ENTRY is null-prototype too (M3 r6 major 5d48ad691b96): absent must MEAN
+    // absent — a consumer reading `.transition` off an Object.prototype-backed entry would
+    // see a polluted inherited value when none is own.
+    const acceptedEntry = Object.create(null);
+    for (const [key, member] of Object.entries(targetSnapshot)) {
+        // `targetSnapshot` array members are ALREADY the read-once frozen copies the validators saw, so the
+        // accepted entry references that single truth directly — no second read of the caller's array
+        // (reviews major 91f7a2c43bd0 immutability + major 18 one-read). Keyframe elements are scalars.
+        acceptedEntry[key] = member;
+    }
+    if (transitionSnapshot !== undefined) {
+        acceptedEntry['transition'] = transitionSnapshot;
+    }
+    return { refusal: null, entry: acceptedEntry };
+}
+/** Split one entry into its application (the bare target + its own transition). */
+function applicationOf(entry) {
+    const { transition, ...target } = entry;
+    return { target: target, transition };
+}
+/**
+ * Laws (a)/(b): resolve a label or label array to the ORDERED application list. A local
+ * miss contributes nothing (the pinned no-op); each hit preserves its own transition.
+ */
+export function resolveVariantDefinition(definition, dictionary, context) {
+    const result = resolveVariantDefinitionResult(definition, dictionary, context);
+    if (result.refusal !== null)
+        throw result.refusal;
+    return result.applications;
+}
+/**
+ * Internal severity seam: boundary-made validation failures are returned, while value-state reads
+ * and user resolver invocations remain outside every catch and preserve their exact thrown value.
+ */
+export function resolveVariantDefinitionResult(definition, dictionary, context) {
+    if (typeof definition === 'function') {
+        const invocation = invokeResolver('(definition)', definition, context);
+        if (invocation.refusal !== null)
+            return { applications: [], refusal: invocation.refusal };
+        const produced = invocation.value;
+        if (typeof produced !== 'string') {
+            const resolution = resolveProducedTarget('(definition)', produced, context);
+            return resolution.refusal === null
+                ? { applications: [resolution.application], refusal: null }
+                : { applications: [], refusal: resolution.refusal };
+        }
+        return resolveSingleLabel(produced, dictionary, context);
+    }
+    const labels = typeof definition === 'string' ? [definition] : definition;
+    const applications = [];
+    for (const label of labels) {
+        const resolution = resolveSingleLabel(label, dictionary, context);
+        if (resolution.refusal !== null)
+            return { applications: [], refusal: resolution.refusal };
+        applications.push(...resolution.applications);
+    }
+    return { applications, refusal: null };
+}
+function resolutionContextRefusal(label, context) {
+    return context === undefined
+        ? new InvalidVariantError(label, undefined, `variants.${label} is a RESOLVER but the resolution site supplied no ` +
+            'resolution context — the site is not wired for dynamic variants (T24 B2)')
+        : null;
+}
+// Each call performs its own pin-shaped `getValueState` read. The invocation is deliberately
+// unguarded: user faults preserve identity and host severity routes only our typed refusals.
+function invokeResolver(label, entry, context) {
+    const refusal = resolutionContextRefusal(label, context);
+    if (refusal !== null)
+        return { refusal };
+    const wired = context;
+    const { current, velocity } = wired.readValueState();
+    return { value: entry(wired.custom, current, velocity), refusal: null };
+}
+function resolveProducedTarget(label, produced, context) {
+    const contextRefusal = resolutionContextRefusal(label, context);
+    if (contextRefusal !== null)
+        return { refusal: contextRefusal };
+    const wired = context;
+    if (typeof produced === 'function') {
+        return {
+            refusal: new InvalidVariantError(label, produced, `variants.${label}: the resolver returned another resolver — a dictionary resolver ` +
+                'must return a target object exactly once (the pin two-step bound)'),
+        };
+    }
+    const { refusal, entry: accepted } = validateVariantEntrySnapshot(label, produced, wired.host, wired.componentId === undefined ? undefined : { componentId: wired.componentId });
+    if (refusal !== null)
+        return { refusal };
+    return { application: applicationOf(accepted), refusal: null };
+}
+function resolveSingleLabel(label, dictionary, context) {
+    // OWN properties only (M1 review major 1): prototype-chain names are local misses.
+    if (dictionary === undefined || !Object.hasOwn(dictionary, label)) {
+        return { applications: [], refusal: null };
+    }
+    const entry = dictionary[label];
+    if (typeof entry !== 'function') {
+        return { applications: [applicationOf(entry)], refusal: null };
+    }
+    const invocation = invokeResolver(label, entry, context);
+    if (invocation.refusal !== null)
+        return { applications: [], refusal: invocation.refusal };
+    // This is the bounded second function arm. Its result is final and cannot name another label.
+    const resolution = resolveProducedTarget(label, invocation.value, context);
+    return resolution.refusal === null
+        ? { applications: [resolution.application], refusal: null }
+        : { applications: [], refusal: resolution.refusal };
+}
+export function flattenVariantApplications(applications) {
+    const target = {};
+    const transitions = {};
+    for (const application of applications) {
+        for (const key of Object.keys(application.target)) {
+            target[key] = application.target[key];
+            if (application.transition === undefined)
+                delete transitions[key];
+            else
+                transitions[key] = application.transition;
+        }
+    }
+    return { target: target, transitions };
+}
+/**
+ * Law (c): the synchronous initial overlay — all labels merge in order into ONE first-paint
+ * state, transitions DISCARDED (REQ-API-010's no-entrance law is untouched).
+ */
+export function resolveInitialOverlay(definition, dictionary, context) {
+    const overlay = {};
+    for (const application of resolveVariantDefinition(definition, dictionary, context)) {
+        // T23 B3c: an initial application applies its transitionEnd INSTANTLY (the pin's
+        // nothing-animates arm) — the carrier's sub-values fold into the first-paint state,
+        // winning over the same application's target key; the carrier member itself never
+        // rides the overlay.
+        const { transitionEnd: carrier, ...plain } = application.target;
+        Object.assign(overlay, plain);
+        if (typeof carrier === 'object' && carrier !== null && !Array.isArray(carrier)) {
+            Object.assign(overlay, carrier);
+        }
+    }
+    return overlay;
+}

package/dist/config/constants.cjs

@@ -0,0 +1,41 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Pinned motion-graph constants. Adopted from `motion@12.42.2` (see
+// `specs/OPEN-DECISIONS.md` §D resolutions log) and PROVEN equal to that pinned oracle by the M1b
+// conformance suite — these literals are a starting seed, not hand-authored ground truth. Never
+// widen an epsilon here to make a test pass (test-integrity); fix the code or ratify the constant.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETTLE_HORIZON_MS = exports.EPS_SETTLE_FRAME = exports.EPS_TRAJ = exports.EPS_VELOCITY = exports.GRANULAR_THRESHOLD = exports.REST_SPEED = exports.REST_DELTA = exports.DT_CLAMP_MS = exports.MAX_VELOCITY_DELTA_MS = void 0;
+/**
+ * CORE-only velocity staleness window (ms). Governs `MotionValue.getVelocity` and the animation
+ * cold-start velocity seed. It does NOT govern the gesture path — that consumes platform release
+ * velocity (§D/§G). A value sample older than this reads velocity `0`.
+ */
+exports.MAX_VELOCITY_DELTA_MS = 30;
+/**
+ * Per-frame elapsed-time ceiling (ms). Guards the graph against a large jump after backgrounding
+ * (REQ-CLOCK-003). Flagged for human confirmation. ~2.4 frames at 60Hz.
+ */
+exports.DT_CLAMP_MS = 40;
+// Rest thresholds — adopted from Motion; the exact numerics and their conformance pin are owned by
+// SPEC-SPRING. Present here only so CORE has one source; SPRING tightens them.
+exports.REST_DELTA = 0.01;
+exports.REST_SPEED = 2;
+/** Granular rest-threshold discontinuity at `|target − origin| < 5` (Motion). */
+exports.GRANULAR_THRESHOLD = 5;
+// Named epsilons — config, not literals in assertions. Nominal seeds from SPEC-CORE §5; final
+// values ratified with SPEC-SPRING and tightened against the pinned oracle in M1b.
+/** Velocity equality tolerance (units/sec). */
+exports.EPS_VELOCITY = 1;
+/** Trajectory / dt-robustness tolerance (value units). */
+exports.EPS_TRAJ = 0.5;
+/** Settle is exact to the frame. */
+exports.EPS_SETTLE_FRAME = 0;
+/**
+ * The settle law's shared horizon (r12 4f6e2d1b8a70 / r13 minor 1d6f4b8a2e90 — ONE
+ * authority): validateTransition requires every accepted trajectory to be DONE by this
+ * instant (~285 millennia), and stepProp's precision-freeze termination samples the settled
+ * state at max(elapsed, this horizon). The pairing is what guarantees an accepted config
+ * reaches its settled value on every stepping cadence; the two consumers must never diverge.
+ */
+exports.SETTLE_HORIZON_MS = 2 ** 53;

package/dist/config/constants.d.cts

@@ -0,0 +1,29 @@
+/**
+ * CORE-only velocity staleness window (ms). Governs `MotionValue.getVelocity` and the animation
+ * cold-start velocity seed. It does NOT govern the gesture path — that consumes platform release
+ * velocity (§D/§G). A value sample older than this reads velocity `0`.
+ */
+export declare const MAX_VELOCITY_DELTA_MS = 30;
+/**
+ * Per-frame elapsed-time ceiling (ms). Guards the graph against a large jump after backgrounding
+ * (REQ-CLOCK-003). Flagged for human confirmation. ~2.4 frames at 60Hz.
+ */
+export declare const DT_CLAMP_MS = 40;
+export declare const REST_DELTA = 0.01;
+export declare const REST_SPEED = 2;
+/** Granular rest-threshold discontinuity at `|target − origin| < 5` (Motion). */
+export declare const GRANULAR_THRESHOLD = 5;
+/** Velocity equality tolerance (units/sec). */
+export declare const EPS_VELOCITY = 1;
+/** Trajectory / dt-robustness tolerance (value units). */
+export declare const EPS_TRAJ = 0.5;
+/** Settle is exact to the frame. */
+export declare const EPS_SETTLE_FRAME = 0;
+/**
+ * The settle law's shared horizon (r12 4f6e2d1b8a70 / r13 minor 1d6f4b8a2e90 — ONE
+ * authority): validateTransition requires every accepted trajectory to be DONE by this
+ * instant (~285 millennia), and stepProp's precision-freeze termination samples the settled
+ * state at max(elapsed, this horizon). The pairing is what guarantees an accepted config
+ * reaches its settled value on every stepping cadence; the two consumers must never diverge.
+ */
+export declare const SETTLE_HORIZON_MS: number;

package/dist/config/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CORE-only velocity staleness window (ms). Governs `MotionValue.getVelocity` and the animation
+ * cold-start velocity seed. It does NOT govern the gesture path — that consumes platform release
+ * velocity (§D/§G). A value sample older than this reads velocity `0`.
+ */
+export declare const MAX_VELOCITY_DELTA_MS = 30;
+/**
+ * Per-frame elapsed-time ceiling (ms). Guards the graph against a large jump after backgrounding
+ * (REQ-CLOCK-003). Flagged for human confirmation. ~2.4 frames at 60Hz.
+ */
+export declare const DT_CLAMP_MS = 40;
+export declare const REST_DELTA = 0.01;
+export declare const REST_SPEED = 2;
+/** Granular rest-threshold discontinuity at `|target − origin| < 5` (Motion). */
+export declare const GRANULAR_THRESHOLD = 5;
+/** Velocity equality tolerance (units/sec). */
+export declare const EPS_VELOCITY = 1;
+/** Trajectory / dt-robustness tolerance (value units). */
+export declare const EPS_TRAJ = 0.5;
+/** Settle is exact to the frame. */
+export declare const EPS_SETTLE_FRAME = 0;
+/**
+ * The settle law's shared horizon (r12 4f6e2d1b8a70 / r13 minor 1d6f4b8a2e90 — ONE
+ * authority): validateTransition requires every accepted trajectory to be DONE by this
+ * instant (~285 millennia), and stepProp's precision-freeze termination samples the settled
+ * state at max(elapsed, this horizon). The pairing is what guarantees an accepted config
+ * reaches its settled value on every stepping cadence; the two consumers must never diverge.
+ */
+export declare const SETTLE_HORIZON_MS: number;

package/dist/config/constants.js

@@ -0,0 +1,38 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Pinned motion-graph constants. Adopted from `motion@12.42.2` (see
+// `specs/OPEN-DECISIONS.md` §D resolutions log) and PROVEN equal to that pinned oracle by the M1b
+// conformance suite — these literals are a starting seed, not hand-authored ground truth. Never
+// widen an epsilon here to make a test pass (test-integrity); fix the code or ratify the constant.
+/**
+ * CORE-only velocity staleness window (ms). Governs `MotionValue.getVelocity` and the animation
+ * cold-start velocity seed. It does NOT govern the gesture path — that consumes platform release
+ * velocity (§D/§G). A value sample older than this reads velocity `0`.
+ */
+export const MAX_VELOCITY_DELTA_MS = 30;
+/**
+ * Per-frame elapsed-time ceiling (ms). Guards the graph against a large jump after backgrounding
+ * (REQ-CLOCK-003). Flagged for human confirmation. ~2.4 frames at 60Hz.
+ */
+export const DT_CLAMP_MS = 40;
+// Rest thresholds — adopted from Motion; the exact numerics and their conformance pin are owned by
+// SPEC-SPRING. Present here only so CORE has one source; SPRING tightens them.
+export const REST_DELTA = 0.01;
+export const REST_SPEED = 2;
+/** Granular rest-threshold discontinuity at `|target − origin| < 5` (Motion). */
+export const GRANULAR_THRESHOLD = 5;
+// Named epsilons — config, not literals in assertions. Nominal seeds from SPEC-CORE §5; final
+// values ratified with SPEC-SPRING and tightened against the pinned oracle in M1b.
+/** Velocity equality tolerance (units/sec). */
+export const EPS_VELOCITY = 1;
+/** Trajectory / dt-robustness tolerance (value units). */
+export const EPS_TRAJ = 0.5;
+/** Settle is exact to the frame. */
+export const EPS_SETTLE_FRAME = 0;
+/**
+ * The settle law's shared horizon (r12 4f6e2d1b8a70 / r13 minor 1d6f4b8a2e90 — ONE
+ * authority): validateTransition requires every accepted trajectory to be DONE by this
+ * instant (~285 millennia), and stepProp's precision-freeze termination samples the settled
+ * state at max(elapsed, this horizon). The pairing is what guarantees an accepted config
+ * reaches its settled value on every stepping cadence; the two consumers must never diverge.
+ */
+export const SETTLE_HORIZON_MS = 2 ** 53;

package/dist/delay.cjs

@@ -0,0 +1,72 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// T18-b / REQ-TIMING-004 — the delay elapsed-time REBASE. `delay` is not a generator feature in
+// the pinned Motion: it is a pure `t → t − delay` shift applied AROUND the repeat fold
+// (motion-dom@12.42.2 `JSAnimation.tick`: `timeWithoutDelay = currentTime − delay`, clamped at 0,
+// computed BEFORE the fold arithmetic). This module is that shift, so every trajectory — bare
+// generator or fold — delays identically and none of them learns about delay. Host-agnostic
+// (REQ-CORE-003): relative imports only. Numerics are pinned by per-sample goldens in
+// delay.test.ts.
+//
+// The hold is never done, which is what keeps `delay` + `duration: 0` from finishing instantly
+// (the pin's `delayState` law). A NEGATIVE delay is an elapsed-time seed, not an error: the
+// rebase formula is the whole law, so the first sample lands mid-trajectory — including
+// mid-iteration when the magnitude exceeds whole iterations of a fold. There is no sign floor
+// (pinned behavior; validate.ts bounds only a POSITIVE delay to the settle horizon and refuses
+// the non-finite ones).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delayGenerator = delayGenerator;
+/**
+ * Wrap `base` in the delay rebase (REQ-TIMING-004). The returned generator is a `Generator` like
+ * any other — the driver steps it without knowing it delays. Both driver backends call this at
+ * BOTH seams (start and retarget), around whatever the transition resolved to — the fold when the
+ * transition repeats, the bare generator otherwise — and parity between them is held by the
+ * executing floor, `driverParity.differential.test.ts`, not by this call being shared.
+ *
+ * While `t − delayMs < 0` the sample is the FIRST keyframe with velocity 0 and `done: false`
+ * (packet L2): the pin's `delayState` holds `keyframes[0]` and never completes, and our
+ * analytic-velocity contract (REQ-SPRING-009) reads 0 during the hold — so a mid-delay retarget
+ * reseeds from the held value at rest, there being no motion to be continuous WITH. The first
+ * keyframe is captured from `base.sample(0)` at CONSTRUCTION: every core generator is a pure
+ * function of elapsed time, so the zero-sample is the held value by definition.
+ *
+ * After the hold, `done` is the wrapped trajectory's own at `t − delayMs` — the fold reports done
+ * against its `totalDuration` (which excludes delay), so a finite animation settles at
+ * `delay + totalDuration` exactly (packet L4).
+ *
+ * `delayMs === 0` is elided to `base` unchanged: the identity rebase adds no behavior, and the
+ * drivers never produce a negative elapsed where elision would differ (`stepProp` accumulates
+ * non-negative deltas). A NaN elapsed is NOT laundered into the hold: `NaN < delayMs` is false,
+ * so the wrapped generator receives NaN and answers NaN — a broken clock stays loud (the repeat
+ * fold's `Math.max` law, applied here).
+ */
+// alloc-ok: lifecycle-edge — construction captures the first keyframe and builds the ONE reused
+// sample record; sample() below mutates it and allocates nothing (REQ-DRIVER-021).
+function delayGenerator(base, delayMs) {
+    if (delayMs === 0)
+        return base;
+    const firstKeyframe = base.sample(0).value;
+    const out = { value: firstKeyframe, velocity: 0, done: false };
+    return {
+        // A delay is a pure time SHIFT: it moves WHEN a trajectory ends, never WHERE it rests. So the
+        // wrapped trajectory's finish-time commit passes straight through. Dropping it here silently
+        // returned `delay` + a fractional `repeat` to the mid-play landing REQ-TIMING-003 exists to
+        // fix — on both drivers and at both seams, through a combination validation accepts (H2
+        // round-1 review MAJOR 1). Every wrapper of a `Generator` owes this forward.
+        finalValue: base.finalValue,
+        sample(elapsedMs) {
+            const rebasedMs = elapsedMs - delayMs;
+            if (rebasedMs < 0) {
+                out.value = firstKeyframe;
+                out.velocity = 0;
+                out.done = false;
+                return out;
+            }
+            const sample = base.sample(rebasedMs);
+            out.value = sample.value;
+            out.velocity = sample.velocity;
+            out.done = sample.done;
+            return out;
+        },
+    };
+}

package/dist/delay.d.cts

@@ -0,0 +1,26 @@
+import type { Generator } from "./types.cjs";
+/**
+ * Wrap `base` in the delay rebase (REQ-TIMING-004). The returned generator is a `Generator` like
+ * any other — the driver steps it without knowing it delays. Both driver backends call this at
+ * BOTH seams (start and retarget), around whatever the transition resolved to — the fold when the
+ * transition repeats, the bare generator otherwise — and parity between them is held by the
+ * executing floor, `driverParity.differential.test.ts`, not by this call being shared.
+ *
+ * While `t − delayMs < 0` the sample is the FIRST keyframe with velocity 0 and `done: false`
+ * (packet L2): the pin's `delayState` holds `keyframes[0]` and never completes, and our
+ * analytic-velocity contract (REQ-SPRING-009) reads 0 during the hold — so a mid-delay retarget
+ * reseeds from the held value at rest, there being no motion to be continuous WITH. The first
+ * keyframe is captured from `base.sample(0)` at CONSTRUCTION: every core generator is a pure
+ * function of elapsed time, so the zero-sample is the held value by definition.
+ *
+ * After the hold, `done` is the wrapped trajectory's own at `t − delayMs` — the fold reports done
+ * against its `totalDuration` (which excludes delay), so a finite animation settles at
+ * `delay + totalDuration` exactly (packet L4).
+ *
+ * `delayMs === 0` is elided to `base` unchanged: the identity rebase adds no behavior, and the
+ * drivers never produce a negative elapsed where elision would differ (`stepProp` accumulates
+ * non-negative deltas). A NaN elapsed is NOT laundered into the hold: `NaN < delayMs` is false,
+ * so the wrapped generator receives NaN and answers NaN — a broken clock stays loud (the repeat
+ * fold's `Math.max` law, applied here).
+ */
+export declare function delayGenerator(base: Generator, delayMs: number): Generator;

package/dist/delay.d.ts

@@ -0,0 +1,26 @@
+import type { Generator } from "./types.js";
+/**
+ * Wrap `base` in the delay rebase (REQ-TIMING-004). The returned generator is a `Generator` like
+ * any other — the driver steps it without knowing it delays. Both driver backends call this at
+ * BOTH seams (start and retarget), around whatever the transition resolved to — the fold when the
+ * transition repeats, the bare generator otherwise — and parity between them is held by the
+ * executing floor, `driverParity.differential.test.ts`, not by this call being shared.
+ *
+ * While `t − delayMs < 0` the sample is the FIRST keyframe with velocity 0 and `done: false`
+ * (packet L2): the pin's `delayState` holds `keyframes[0]` and never completes, and our
+ * analytic-velocity contract (REQ-SPRING-009) reads 0 during the hold — so a mid-delay retarget
+ * reseeds from the held value at rest, there being no motion to be continuous WITH. The first
+ * keyframe is captured from `base.sample(0)` at CONSTRUCTION: every core generator is a pure
+ * function of elapsed time, so the zero-sample is the held value by definition.
+ *
+ * After the hold, `done` is the wrapped trajectory's own at `t − delayMs` — the fold reports done
+ * against its `totalDuration` (which excludes delay), so a finite animation settles at
+ * `delay + totalDuration` exactly (packet L4).
+ *
+ * `delayMs === 0` is elided to `base` unchanged: the identity rebase adds no behavior, and the
+ * drivers never produce a negative elapsed where elision would differ (`stepProp` accumulates
+ * non-negative deltas). A NaN elapsed is NOT laundered into the hold: `NaN < delayMs` is false,
+ * so the wrapped generator receives NaN and answers NaN — a broken clock stays loud (the repeat
+ * fold's `Math.max` law, applied here).
+ */
+export declare function delayGenerator(base: Generator, delayMs: number): Generator;