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

package/dist/delay.js

@@ -0,0 +1,70 @@
+'worklet';
+// @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).
+/**
+ * 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).
+export 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/derived.cjs

@@ -0,0 +1,143 @@
+"use strict";
+// Derived values (REQ-VALUE-002/013): a read-only MotionValue computed from numeric inputs, off the
+// host render path. Recompute is coalesced to the frame boundary and applied in creation-index
+// (topological) order by the graph, so a derivation-of-derivations observes no intermediate value.
+// The dependency graph is acyclic by construction: inputs must already exist when a derived is
+// created, so a node can only depend on earlier-created nodes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DerivedValue = void 0;
+const collect_reads_1 = require("./collect-reads.cjs");
+const subscriptions_1 = require("./subscriptions.cjs");
+class DerivedValue {
+    creationIndex;
+    #inputs;
+    #compute;
+    #detached = false;
+    #markDirty;
+    #inputUnsubscribers;
+    #subs = new subscriptions_1.Subscriptions();
+    #value;
+    // Construction-edge-sized reusable input buffer (REQ-DRIVER-021, packet §6 ordinary local-JS
+    // repair): recompute fills it by indexed writes — no per-flush map array, closure, or fresh
+    // spread target on the engine bookkeeping path.
+    #inputValues;
+    constructor(creationIndex, inputs, compute, markDirty) {
+        this.creationIndex = creationIndex;
+        this.#inputs = inputs;
+        this.#compute = compute;
+        this.#markDirty = markDirty;
+        this.#inputValues = Array.from({ length: inputs.length });
+        this.#value = this.#recompute();
+        this.#inputUnsubscribers = this.#subscribeInputs();
+    }
+    // One stable named input listener per derived value (manifest node
+    // DerivedValue.markDirtyFromInput) — not a fresh closure per input per (re)subscription.
+    #markDirtyFromInput = () => {
+        this.#markDirty(this);
+    };
+    #subscribeInputs() {
+        // Branded so the driver port can classify a transported write's derived-dirty reach
+        // (REQ-VALUE-015) without a graph handle; the listener itself is unchanged.
+        return this.#inputs.map((input) => input.subscribe((0, subscriptions_1.brandDerivedDependentListener)(this.#markDirtyFromInput)));
+    }
+    /**
+     * Release the input subscriptions WITHOUT destroying the value (REQ-VALUE-002 lifecycle,
+     * review r4): the hook layer detaches on effect cleanup and re-attaches the SAME value on a
+     * StrictMode replay. Subscribers and the last value survive a detach.
+     */
+    detachInputs() {
+        for (const unsubscribe of this.#inputUnsubscribers)
+            unsubscribe();
+        this.#inputUnsubscribers = [];
+        // Cancel any ALREADY-QUEUED recompute (review r5): a set() before the detach must not
+        // apply or notify on the next flush. The dirty-set entry stays; flush() below no-ops it.
+        this.#detached = true;
+    }
+    /** Re-subscribe the inputs and resync from their CURRENT values. Idempotent. */
+    attachInputs() {
+        if (this.#inputUnsubscribers.length > 0)
+            return;
+        this.#detached = false;
+        this.#inputUnsubscribers = this.#subscribeInputs();
+        this.refresh();
+    }
+    /**
+     * Recompute synchronously from the current inputs and notify on change — the render-phase
+     * re-parameterization path (a compute whose captured parameters changed resyncs immediately;
+     * frame-coalesced flushing remains the INPUT-driven path).
+     */
+    refresh() {
+        this.#applyRecomputeFromReusableInputs();
+    }
+    get() {
+        (0, collect_reads_1.reportMotionValueRead)(this);
+        return this.#value;
+    }
+    set(_value) {
+        throw new Error('native-motion-core: cannot set a derived value; it is read-only (REQ-VALUE-002)');
+    }
+    jump(_value) {
+        throw new Error('native-motion-core: cannot jump a derived value; it is read-only (REQ-VALUE-002)');
+    }
+    subscribe(listener) {
+        return this.#subs.subscribe(listener);
+    }
+    // Open decision (SPEC-CORE §8): derived-value velocity parity with Motion's transform values.
+    // Reports 0 until ratified; recorded so it is not a silent choice.
+    getVelocity() {
+        return 0;
+    }
+    on(event, listener) {
+        // Broad implementation signature for delegation only — not a public overload (r16).
+        return this.#subs.on(event, listener);
+    }
+    stop() {
+        // A derived value is not animated directly; nothing to stop.
+    }
+    isAnimating() {
+        // Read-only: inputs animate, the derivation only recomputes — never animated directly (r12).
+        return false;
+    }
+    destroy() {
+        for (const unsubscribe of this.#inputUnsubscribers)
+            unsubscribe();
+        this.#inputUnsubscribers = [];
+        // Teardown cancels queued dirt exactly like detach (r9): a set() that preceded the destroy
+        // must never recompute a destroyed value at the next flush.
+        this.#detached = true;
+        // The pinned full event union (REQ-API-027, r8): teardown announces itself to existing
+        // listeners before subscriptions drop — same law as MotionValueImpl.destroy.
+        this.#subs.emit('destroy');
+        this.#subs.clear();
+    }
+    /**
+     * Recompute from inputs; notify subscribers only if the value actually changed (glitch-free).
+     * A DETACHED node no-ops here: dirt queued before the detach is cancelled, never applied
+     * (review r5). Explicit refresh() bypasses this gate — a deliberate resync is caller intent.
+     */
+    flush() {
+        if (this.#detached)
+            return;
+        this.#applyRecomputeFromReusableInputs();
+    }
+    #applyRecomputeFromReusableInputs() {
+        const next = this.#recompute();
+        if (!Object.is(next, this.#value)) {
+            this.#value = next;
+            this.#subs.emitChange(this.#value);
+        }
+    }
+    // Indexed fill of the construction-sized reusable buffer — the frame-path replacement for
+    // `inputs.map((input) => input.get())` (fresh array + closure per dirty recompute).
+    #readInputsIntoReusableBuffer() {
+        const inputs = this.#inputs;
+        const values = this.#inputValues;
+        for (let i = 0; i < inputs.length; i++)
+            values[i] = inputs[i].get();
+    }
+    #recompute() {
+        this.#readInputsIntoReusableBuffer();
+        return this.#compute(...this.#inputValues);
+    }
+}
+exports.DerivedValue = DerivedValue;

package/dist/derived.d.cts

@@ -0,0 +1,41 @@
+import type { DerivedSource, MotionValue, MotionValueEvent, ValueChangeListener } from "./types.cjs";
+/** A node the graph flushes on the frame boundary. */
+export interface DirtyNode {
+    readonly creationIndex: number;
+    flush(): void;
+}
+export declare class DerivedValue<T> implements MotionValue<T>, DirtyNode {
+    #private;
+    readonly creationIndex: number;
+    constructor(creationIndex: number, inputs: readonly DerivedSource[], compute: (...values: unknown[]) => T, markDirty: (node: DirtyNode) => void);
+    /**
+     * Release the input subscriptions WITHOUT destroying the value (REQ-VALUE-002 lifecycle,
+     * review r4): the hook layer detaches on effect cleanup and re-attaches the SAME value on a
+     * StrictMode replay. Subscribers and the last value survive a detach.
+     */
+    detachInputs(): void;
+    /** Re-subscribe the inputs and resync from their CURRENT values. Idempotent. */
+    attachInputs(): void;
+    /**
+     * Recompute synchronously from the current inputs and notify on change — the render-phase
+     * re-parameterization path (a compute whose captured parameters changed resyncs immediately;
+     * frame-coalesced flushing remains the INPUT-driven path).
+     */
+    refresh(): void;
+    get(): T;
+    set(_value: T): never;
+    jump(_value: T): never;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    getVelocity(): number;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    stop(): void;
+    isAnimating(): boolean;
+    destroy(): void;
+    /**
+     * Recompute from inputs; notify subscribers only if the value actually changed (glitch-free).
+     * A DETACHED node no-ops here: dirt queued before the detach is cancelled, never applied
+     * (review r5). Explicit refresh() bypasses this gate — a deliberate resync is caller intent.
+     */
+    flush(): void;
+}

package/dist/derived.d.ts

@@ -0,0 +1,41 @@
+import type { DerivedSource, MotionValue, MotionValueEvent, ValueChangeListener } from "./types.js";
+/** A node the graph flushes on the frame boundary. */
+export interface DirtyNode {
+    readonly creationIndex: number;
+    flush(): void;
+}
+export declare class DerivedValue<T> implements MotionValue<T>, DirtyNode {
+    #private;
+    readonly creationIndex: number;
+    constructor(creationIndex: number, inputs: readonly DerivedSource[], compute: (...values: unknown[]) => T, markDirty: (node: DirtyNode) => void);
+    /**
+     * Release the input subscriptions WITHOUT destroying the value (REQ-VALUE-002 lifecycle,
+     * review r4): the hook layer detaches on effect cleanup and re-attaches the SAME value on a
+     * StrictMode replay. Subscribers and the last value survive a detach.
+     */
+    detachInputs(): void;
+    /** Re-subscribe the inputs and resync from their CURRENT values. Idempotent. */
+    attachInputs(): void;
+    /**
+     * Recompute synchronously from the current inputs and notify on change — the render-phase
+     * re-parameterization path (a compute whose captured parameters changed resyncs immediately;
+     * frame-coalesced flushing remains the INPUT-driven path).
+     */
+    refresh(): void;
+    get(): T;
+    set(_value: T): never;
+    jump(_value: T): never;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    getVelocity(): number;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    stop(): void;
+    isAnimating(): boolean;
+    destroy(): void;
+    /**
+     * Recompute from inputs; notify subscribers only if the value actually changed (glitch-free).
+     * A DETACHED node no-ops here: dirt queued before the detach is cancelled, never applied
+     * (review r5). Explicit refresh() bypasses this gate — a deliberate resync is caller intent.
+     */
+    flush(): void;
+}

package/dist/derived.js

@@ -0,0 +1,139 @@
+// Derived values (REQ-VALUE-002/013): a read-only MotionValue computed from numeric inputs, off the
+// host render path. Recompute is coalesced to the frame boundary and applied in creation-index
+// (topological) order by the graph, so a derivation-of-derivations observes no intermediate value.
+// The dependency graph is acyclic by construction: inputs must already exist when a derived is
+// created, so a node can only depend on earlier-created nodes.
+import { reportMotionValueRead } from "./collect-reads.js";
+import { brandDerivedDependentListener, Subscriptions } from "./subscriptions.js";
+export class DerivedValue {
+    creationIndex;
+    #inputs;
+    #compute;
+    #detached = false;
+    #markDirty;
+    #inputUnsubscribers;
+    #subs = new Subscriptions();
+    #value;
+    // Construction-edge-sized reusable input buffer (REQ-DRIVER-021, packet §6 ordinary local-JS
+    // repair): recompute fills it by indexed writes — no per-flush map array, closure, or fresh
+    // spread target on the engine bookkeeping path.
+    #inputValues;
+    constructor(creationIndex, inputs, compute, markDirty) {
+        this.creationIndex = creationIndex;
+        this.#inputs = inputs;
+        this.#compute = compute;
+        this.#markDirty = markDirty;
+        this.#inputValues = Array.from({ length: inputs.length });
+        this.#value = this.#recompute();
+        this.#inputUnsubscribers = this.#subscribeInputs();
+    }
+    // One stable named input listener per derived value (manifest node
+    // DerivedValue.markDirtyFromInput) — not a fresh closure per input per (re)subscription.
+    #markDirtyFromInput = () => {
+        this.#markDirty(this);
+    };
+    #subscribeInputs() {
+        // Branded so the driver port can classify a transported write's derived-dirty reach
+        // (REQ-VALUE-015) without a graph handle; the listener itself is unchanged.
+        return this.#inputs.map((input) => input.subscribe(brandDerivedDependentListener(this.#markDirtyFromInput)));
+    }
+    /**
+     * Release the input subscriptions WITHOUT destroying the value (REQ-VALUE-002 lifecycle,
+     * review r4): the hook layer detaches on effect cleanup and re-attaches the SAME value on a
+     * StrictMode replay. Subscribers and the last value survive a detach.
+     */
+    detachInputs() {
+        for (const unsubscribe of this.#inputUnsubscribers)
+            unsubscribe();
+        this.#inputUnsubscribers = [];
+        // Cancel any ALREADY-QUEUED recompute (review r5): a set() before the detach must not
+        // apply or notify on the next flush. The dirty-set entry stays; flush() below no-ops it.
+        this.#detached = true;
+    }
+    /** Re-subscribe the inputs and resync from their CURRENT values. Idempotent. */
+    attachInputs() {
+        if (this.#inputUnsubscribers.length > 0)
+            return;
+        this.#detached = false;
+        this.#inputUnsubscribers = this.#subscribeInputs();
+        this.refresh();
+    }
+    /**
+     * Recompute synchronously from the current inputs and notify on change — the render-phase
+     * re-parameterization path (a compute whose captured parameters changed resyncs immediately;
+     * frame-coalesced flushing remains the INPUT-driven path).
+     */
+    refresh() {
+        this.#applyRecomputeFromReusableInputs();
+    }
+    get() {
+        reportMotionValueRead(this);
+        return this.#value;
+    }
+    set(_value) {
+        throw new Error('native-motion-core: cannot set a derived value; it is read-only (REQ-VALUE-002)');
+    }
+    jump(_value) {
+        throw new Error('native-motion-core: cannot jump a derived value; it is read-only (REQ-VALUE-002)');
+    }
+    subscribe(listener) {
+        return this.#subs.subscribe(listener);
+    }
+    // Open decision (SPEC-CORE §8): derived-value velocity parity with Motion's transform values.
+    // Reports 0 until ratified; recorded so it is not a silent choice.
+    getVelocity() {
+        return 0;
+    }
+    on(event, listener) {
+        // Broad implementation signature for delegation only — not a public overload (r16).
+        return this.#subs.on(event, listener);
+    }
+    stop() {
+        // A derived value is not animated directly; nothing to stop.
+    }
+    isAnimating() {
+        // Read-only: inputs animate, the derivation only recomputes — never animated directly (r12).
+        return false;
+    }
+    destroy() {
+        for (const unsubscribe of this.#inputUnsubscribers)
+            unsubscribe();
+        this.#inputUnsubscribers = [];
+        // Teardown cancels queued dirt exactly like detach (r9): a set() that preceded the destroy
+        // must never recompute a destroyed value at the next flush.
+        this.#detached = true;
+        // The pinned full event union (REQ-API-027, r8): teardown announces itself to existing
+        // listeners before subscriptions drop — same law as MotionValueImpl.destroy.
+        this.#subs.emit('destroy');
+        this.#subs.clear();
+    }
+    /**
+     * Recompute from inputs; notify subscribers only if the value actually changed (glitch-free).
+     * A DETACHED node no-ops here: dirt queued before the detach is cancelled, never applied
+     * (review r5). Explicit refresh() bypasses this gate — a deliberate resync is caller intent.
+     */
+    flush() {
+        if (this.#detached)
+            return;
+        this.#applyRecomputeFromReusableInputs();
+    }
+    #applyRecomputeFromReusableInputs() {
+        const next = this.#recompute();
+        if (!Object.is(next, this.#value)) {
+            this.#value = next;
+            this.#subs.emitChange(this.#value);
+        }
+    }
+    // Indexed fill of the construction-sized reusable buffer — the frame-path replacement for
+    // `inputs.map((input) => input.get())` (fresh array + closure per dirty recompute).
+    #readInputsIntoReusableBuffer() {
+        const inputs = this.#inputs;
+        const values = this.#inputValues;
+        for (let i = 0; i < inputs.length; i++)
+            values[i] = inputs[i].get();
+    }
+    #recompute() {
+        this.#readInputsIntoReusableBuffer();
+        return this.#compute(...this.#inputValues);
+    }
+}

package/dist/driver/index.cjs

@@ -0,0 +1,22 @@
+"use strict";
+// Public surface of the SPEC-NATIVE-DRIVER subsystem: the host-agnostic Driver seam `core` defines and the
+// native/web drivers implement. Host-agnostic (REQ-DRIVER-010) — imports no driver, no host package. The
+// interface + command types land first (Milestone 1); the pure worklet-safe step, the reference driver,
+// and the prop-tier classification join this surface as they land.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tierFor = exports.createReferenceDriver = exports.stepProp = exports.clampElapsed = exports.captureTransition = void 0;
+var prepare_1 = require("./prepare.cjs");
+Object.defineProperty(exports, "captureTransition", { enumerable: true, get: function () { return prepare_1.captureTransition; } });
+// The pure, time-integrated per-frame step (REQ-DRIVER-012/015): the worklet-safe trajectory advance a
+// concrete driver runs each frame. Exposed so the native worklet + web drivers reuse the single step math.
+var step_1 = require("./step.cjs");
+Object.defineProperty(exports, "clampElapsed", { enumerable: true, get: function () { return step_1.clampElapsed; } });
+Object.defineProperty(exports, "stepProp", { enumerable: true, get: function () { return step_1.stepProp; } });
+// The reference in-core Driver (REQ-DRIVER-013/020): the host-agnostic command-protocol + quiesce
+// implementation the fake host + conformance drive; the substrate drivers are its device-bound peers.
+var reference_1 = require("./reference.cjs");
+Object.defineProperty(exports, "createReferenceDriver", { enumerable: true, get: function () { return reference_1.createReferenceDriver; } });
+// Prop-tier classification (REQ-DRIVER-017): routes each animatable prop to its substrate execution path
+// (fast vs commit), registry-derived and fail-loud on an untiered prop.
+var tiers_1 = require("./tiers.cjs");
+Object.defineProperty(exports, "tierFor", { enumerable: true, get: function () { return tiers_1.tierFor; } });

package/dist/driver/index.d.cts

@@ -0,0 +1,7 @@
+export type { Driver, DriverCommand, ElementHandle, LivePropState, PropTarget, PropTargetTo, PropTransition, } from "./types.cjs";
+export { captureTransition } from "./prepare.cjs";
+export { clampElapsed, stepProp } from "./step.cjs";
+export type { PropStep } from "./step.cjs";
+export { createReferenceDriver } from "./reference.cjs";
+export { tierFor } from "./tiers.cjs";
+export type { PropTier } from "./tiers.cjs";

package/dist/driver/index.d.ts

@@ -0,0 +1,7 @@
+export type { Driver, DriverCommand, ElementHandle, LivePropState, PropTarget, PropTargetTo, PropTransition, } from "./types.js";
+export { captureTransition } from "./prepare.js";
+export { clampElapsed, stepProp } from "./step.js";
+export type { PropStep } from "./step.js";
+export { createReferenceDriver } from "./reference.js";
+export { tierFor } from "./tiers.js";
+export type { PropTier } from "./tiers.js";

package/dist/driver/index.js

@@ -0,0 +1,14 @@
+// Public surface of the SPEC-NATIVE-DRIVER subsystem: the host-agnostic Driver seam `core` defines and the
+// native/web drivers implement. Host-agnostic (REQ-DRIVER-010) — imports no driver, no host package. The
+// interface + command types land first (Milestone 1); the pure worklet-safe step, the reference driver,
+// and the prop-tier classification join this surface as they land.
+export { captureTransition } from "./prepare.js";
+// The pure, time-integrated per-frame step (REQ-DRIVER-012/015): the worklet-safe trajectory advance a
+// concrete driver runs each frame. Exposed so the native worklet + web drivers reuse the single step math.
+export { clampElapsed, stepProp } from "./step.js";
+// The reference in-core Driver (REQ-DRIVER-013/020): the host-agnostic command-protocol + quiesce
+// implementation the fake host + conformance drive; the substrate drivers are its device-bound peers.
+export { createReferenceDriver } from "./reference.js";
+// Prop-tier classification (REQ-DRIVER-017): routes each animatable prop to its substrate execution path
+// (fast vs commit), registry-derived and fail-loud on an untiered prop.
+export { tierFor } from "./tiers.js";

package/dist/driver/keyframeTiming.cjs

@@ -0,0 +1,130 @@
+"use strict";
+// The shared target-count-dependent keyframe timing law (REQ-API-033 law d). Component
+// suppliers and raw Driver.command preparation both use this one predicate, so a transition
+// cannot pass one boundary and become inert or fall back at another.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyframeTimingRefusal = keyframeTimingRefusal;
+exports.keyframeTransitionRefusal = keyframeTransitionRefusal;
+exports.initialTargetRefusal = initialTargetRefusal;
+exports.keyframeConfigRefusal = keyframeConfigRefusal;
+const validate_1 = require("../component/validate.cjs");
+const timing_1 = require("../timing.cjs");
+const transition_1 = require("../transition.cjs");
+function isPresentArrayIndex(value, index) {
+    return Object.hasOwn(value, index);
+}
+function invalidTiming(componentId, key, value, reason) {
+    return new validate_1.InvalidTransitionError(componentId, key, value, reason);
+}
+const NAMED_EASING_SET = new Set(timing_1.NAMED_EASING_KEYS);
+function isValidSingleEasing(value) {
+    if (typeof value === 'string')
+        return NAMED_EASING_SET.has(value);
+    if (!Array.isArray(value) || value.length !== 4)
+        return false;
+    for (let index = 0; index < 4; index++) {
+        if (!isPresentArrayIndex(value, index))
+            return false;
+        const point = value[index];
+        if (typeof point !== 'number' || !Number.isFinite(point))
+            return false;
+    }
+    return true;
+}
+function isEasingList(value) {
+    return Array.isArray(value) && typeof value[0] !== 'number';
+}
+function keyframeTimingRefusal(componentId, key, value, transition) {
+    if (transition === undefined)
+        return null;
+    const hasTimes = transition.times !== undefined;
+    // Family-2 / T20: easings and easing are exclusive aliases of ease (validated upstream).
+    const easeField = transition.ease !== undefined
+        ? transition.ease
+        : transition.easings !== undefined
+            ? transition.easings
+            : transition.easing;
+    const easeKey = transition.ease !== undefined ? 'ease' : transition.easings !== undefined ? 'easings' : 'easing';
+    const easeIsList = easeField !== undefined && isEasingList(easeField);
+    if (!hasTimes && !easeIsList)
+        return null;
+    if (hasTimes) {
+        const times = transition.times;
+        if (!Array.isArray(times)) {
+            return invalidTiming(componentId, 'times', times, 'times must be an array of finite offsets in [0, 1] (REQ-API-033 law d)');
+        }
+        for (let index = 0; index < times.length; index++) {
+            if (!isPresentArrayIndex(times, index)) {
+                return invalidTiming(componentId, 'times', times, `times is missing index ${index}; sparse timing arrays are invalid (REQ-API-033 law d)`);
+            }
+            const offset = times[index];
+            if (typeof offset !== 'number' || !Number.isFinite(offset) || offset < 0 || offset > 1) {
+                return invalidTiming(componentId, 'times', times, 'times must contain only finite offsets in [0, 1] (REQ-API-033 law d)');
+            }
+            if (index > 0 && offset < times[index - 1]) {
+                return invalidTiming(componentId, 'times', times, 'times must be nondecreasing so every keyframe segment has a non-negative duration (REQ-API-033 law d)');
+            }
+        }
+    }
+    if (easeIsList) {
+        const easeList = easeField;
+        for (let index = 0; index < easeList.length; index++) {
+            if (!isPresentArrayIndex(easeList, index)) {
+                return invalidTiming(componentId, easeKey, easeList, `${easeKey} is missing index ${index}; sparse timing arrays are invalid (REQ-API-033 law d)`);
+            }
+            if (!isValidSingleEasing(easeList[index])) {
+                return invalidTiming(componentId, easeKey, easeList, `each per-segment ${easeKey} entry must be a named easing or one 4-point cubic-bezier (REQ-API-033 law d)`);
+            }
+        }
+    }
+    if (!Array.isArray(value)) {
+        return invalidTiming(componentId, hasTimes ? 'times' : easeKey, hasTimes ? transition.times : easeField, `${hasTimes ? 'times' : 'a per-segment ease list'} applies only to a KEYFRAME-ARRAY target — ` +
+            `'${key}' is a single value, not a keyframe array (REQ-API-033 law d)`);
+    }
+    if (transition.type === 'spring') {
+        return invalidTiming(componentId, hasTimes ? 'times' : easeKey, hasTimes ? transition.times : easeField, `an explicit spring ignores ${hasTimes ? 'times' : 'a per-segment ease list'} for '${key}'; ` +
+            'keyframe timing is not executable on an explicit spring (REQ-API-033 law d)');
+    }
+    return null;
+}
+/** The complete target/effective-transition keyframe law shared by every supplier. */
+function keyframeTransitionRefusal(componentId, key, value, transition) {
+    if (Array.isArray(value) && transition?.type === 'spring') {
+        const springRefusal = (0, transition_1.springKeyframeCountRefusal)(value.length);
+        if (springRefusal !== null)
+            return springRefusal;
+    }
+    return keyframeTimingRefusal(componentId, key, value, transition);
+}
+/** `initial` is a synchronous scalar first-paint supplier, never a keyframe command. */
+function initialTargetRefusal(componentId, key, value) {
+    if (!Array.isArray(value))
+        return null;
+    return new validate_1.InvalidTargetError(componentId, key, value, `initial.${key} must be a scalar first-paint value; keyframe arrays belong to animation-time suppliers (REQ-API-033)`);
+}
+// `keyframesGenerator` is exported and can therefore be reached without a component/driver supplier.
+// Keep its raw timing configuration on the SAME schema/cross-field authority as those suppliers: a
+// malformed direct call must fail typed before it builds segments. Shape-valid count mismatches are
+// deliberate pin behavior: offsets fall back to even and missing list easings become linear.
+function keyframeConfigRefusal(keyframes, config) {
+    const timing = keyframeTimingRefusal(undefined, 'keyframes', keyframes, config);
+    if (timing !== null)
+        return timing;
+    if (config?.ease === undefined)
+        return null;
+    const easeSegments = isEasingList(config.ease) ? config.ease : [config.ease];
+    for (const segment of easeSegments) {
+        if (!isValidSingleEasing(segment)) {
+            return invalidTiming(undefined, 'ease', config.ease, 'ease must be a named easing or one 4-point cubic-bezier (REQ-API-033 law d)');
+        }
+        // Derived executability (i73cik): finite cubic control points can still sample NaN.
+        const easer = (0, timing_1.resolveEasing)(segment);
+        for (const progress of [0, 0.25, 0.5, 0.75, 1]) {
+            if (!Number.isFinite(easer(progress))) {
+                return invalidTiming(undefined, 'ease', config.ease, `the derived segment ease emits a non-finite sample at progress ${progress} — this ` +
+                    'config is not executable (G-INV-8)');
+            }
+        }
+    }
+    return null;
+}

package/dist/driver/keyframeTiming.d.cts

@@ -0,0 +1,18 @@
+import { InvalidTargetError, InvalidTransitionError } from "../component/validate.cjs";
+type TimingTransition = Readonly<{
+    type?: unknown;
+    times?: unknown;
+    ease?: unknown;
+    easings?: unknown;
+    easing?: unknown;
+}>;
+export declare function keyframeTimingRefusal(componentId: string | undefined, key: string, value: unknown, transition: TimingTransition | undefined): InvalidTransitionError | null;
+/** The complete target/effective-transition keyframe law shared by every supplier. */
+export declare function keyframeTransitionRefusal(componentId: string | undefined, key: string, value: unknown, transition: TimingTransition | undefined): Error | null;
+/** `initial` is a synchronous scalar first-paint supplier, never a keyframe command. */
+export declare function initialTargetRefusal(componentId: string | undefined, key: string, value: unknown): InvalidTargetError | null;
+export declare function keyframeConfigRefusal(keyframes: readonly unknown[], config: Readonly<{
+    times?: unknown;
+    ease?: unknown;
+}> | undefined): InvalidTransitionError | null;
+export {};

package/dist/driver/keyframeTiming.d.ts

@@ -0,0 +1,18 @@
+import { InvalidTargetError, InvalidTransitionError } from "../component/validate.js";
+type TimingTransition = Readonly<{
+    type?: unknown;
+    times?: unknown;
+    ease?: unknown;
+    easings?: unknown;
+    easing?: unknown;
+}>;
+export declare function keyframeTimingRefusal(componentId: string | undefined, key: string, value: unknown, transition: TimingTransition | undefined): InvalidTransitionError | null;
+/** The complete target/effective-transition keyframe law shared by every supplier. */
+export declare function keyframeTransitionRefusal(componentId: string | undefined, key: string, value: unknown, transition: TimingTransition | undefined): Error | null;
+/** `initial` is a synchronous scalar first-paint supplier, never a keyframe command. */
+export declare function initialTargetRefusal(componentId: string | undefined, key: string, value: unknown): InvalidTargetError | null;
+export declare function keyframeConfigRefusal(keyframes: readonly unknown[], config: Readonly<{
+    times?: unknown;
+    ease?: unknown;
+}> | undefined): InvalidTransitionError | null;
+export {};