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

package/dist/driver/keyframeTiming.js

@@ -0,0 +1,124 @@
+// 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.
+import { InvalidTargetError, InvalidTransitionError } from "../component/validate.js";
+import { NAMED_EASING_KEYS, resolveEasing } from "../timing.js";
+import { springKeyframeCountRefusal } from "../transition.js";
+function isPresentArrayIndex(value, index) {
+    return Object.hasOwn(value, index);
+}
+function invalidTiming(componentId, key, value, reason) {
+    return new InvalidTransitionError(componentId, key, value, reason);
+}
+const NAMED_EASING_SET = new Set(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';
+}
+export 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. */
+export function keyframeTransitionRefusal(componentId, key, value, transition) {
+    if (Array.isArray(value) && transition?.type === 'spring') {
+        const springRefusal = 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. */
+export function initialTargetRefusal(componentId, key, value) {
+    if (!Array.isArray(value))
+        return null;
+    return new 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.
+export 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 = 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/keyframeTimingConfig.cjs

@@ -0,0 +1,24 @@
+"use strict";
+// The target-count-dependent part of the pinned keyframes generator, isolated as a pure dual-runtime
+// seam. Core's reference generator and native's UI-runtime generator both call these functions, so a
+// shape-valid authored list cannot take different fallback paths on JS and UI.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyframeOffsetAt = keyframeOffsetAt;
+exports.keyframeSegmentEase = keyframeSegmentEase;
+/** Motion uses authored offsets only when there is exactly one per keyframe; otherwise offsets are even. */
+function keyframeOffsetAt(times, index, keyframeCount) {
+    if (times !== undefined && times.length === keyframeCount) {
+        const authored = times[index];
+        if (authored !== undefined)
+            return authored;
+    }
+    return index / (keyframeCount - 1);
+}
+/** Motion indexes an easing list by segment, using linear for a missing entry and ignoring extras. */
+function keyframeSegmentEase(ease, segmentIndex) {
+    if (ease === undefined)
+        return 'easeInOut';
+    if (Array.isArray(ease) && typeof ease[0] !== 'number')
+        return ease[segmentIndex] ?? 'linear';
+    return ease;
+}

package/dist/driver/keyframeTimingConfig.d.cts

@@ -0,0 +1,5 @@
+import type { Easing } from "../timing.cjs";
+/** Motion uses authored offsets only when there is exactly one per keyframe; otherwise offsets are even. */
+export declare function keyframeOffsetAt(times: readonly number[] | undefined, index: number, keyframeCount: number): number;
+/** Motion indexes an easing list by segment, using linear for a missing entry and ignoring extras. */
+export declare function keyframeSegmentEase(ease: Easing | readonly Easing[] | undefined, segmentIndex: number): Easing;

package/dist/driver/keyframeTimingConfig.d.ts

@@ -0,0 +1,5 @@
+import type { Easing } from "../timing.js";
+/** Motion uses authored offsets only when there is exactly one per keyframe; otherwise offsets are even. */
+export declare function keyframeOffsetAt(times: readonly number[] | undefined, index: number, keyframeCount: number): number;
+/** Motion indexes an easing list by segment, using linear for a missing entry and ignoring extras. */
+export declare function keyframeSegmentEase(ease: Easing | readonly Easing[] | undefined, segmentIndex: number): Easing;

package/dist/driver/keyframeTimingConfig.js

@@ -0,0 +1,22 @@
+// The target-count-dependent part of the pinned keyframes generator, isolated as a pure dual-runtime
+// seam. Core's reference generator and native's UI-runtime generator both call these functions, so a
+// shape-valid authored list cannot take different fallback paths on JS and UI.
+/** Motion uses authored offsets only when there is exactly one per keyframe; otherwise offsets are even. */
+export function keyframeOffsetAt(times, index, keyframeCount) {
+  'worklet';
+    if (times !== undefined && times.length === keyframeCount) {
+        const authored = times[index];
+        if (authored !== undefined)
+            return authored;
+    }
+    return index / (keyframeCount - 1);
+}
+/** Motion indexes an easing list by segment, using linear for a missing entry and ignoring extras. */
+export function keyframeSegmentEase(ease, segmentIndex) {
+  'worklet';
+    if (ease === undefined)
+        return 'easeInOut';
+    if (Array.isArray(ease) && typeof ease[0] !== 'number')
+        return ease[segmentIndex] ?? 'linear';
+    return ease;
+}

package/dist/driver/prepare.cjs

@@ -0,0 +1,459 @@
+"use strict";
+// REQ-DRIVER-030 — the one raw DriverCommand → immutable PreparedDriverCommand boundary. Concrete
+// backends receive only the prepared protocol, so caller accessors, mutation, optional velocity, and
+// per-property transition fallback semantics are settled exactly once before backend dispatch.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureTransition = captureTransition;
+exports.prepareDriverCommand = prepareDriverCommand;
+exports.adaptPreparedDriver = adaptPreparedDriver;
+const keyframeTiming_1 = require("./keyframeTiming.cjs");
+const boundedArray_1 = require("../component/boundedArray.cjs");
+const validate_1 = require("../component/validate.cjs");
+const types_1 = require("../component/types.cjs");
+// `PropTransition` additionally carries controller-resolved DefaultTransition springs. `restSpeed`
+// is internal-only (never an authored public Transition option) but must survive preparation so both
+// drivers retain the pinned default's settle threshold.
+function captureTarget(to) {
+    if (typeof to === 'number')
+        return to;
+    // Read the caller's cardinality exactly once, then copy that many indexed values. Array iteration
+    // may re-read a stateful proxy's `length` between elements; this boundary must capture one target
+    // truth before validation and dispatch.
+    const capture = (0, boundedArray_1.captureBoundedArray)(to);
+    if (capture.kind !== 'captured') {
+        throw new validate_1.InvalidTargetError(undefined, 'to', (0, boundedArray_1.capturedArrayDescription)(capture), 'driver keyframe targets must have a safe array length (REQ-API-033)');
+    }
+    return capture.values;
+}
+// Capture the one nested level the legal timing schema admits: an outer `ease` list may contain a
+// 4-number cubic-bezier tuple. Generic recursive cloning was unsafe — a malformed cyclic/deeper array
+// overflowed before it reached the typed validator. Sparse slots deliberately stay sparse; validation
+// names the missing index rather than letting Array.prototype.every skip it. A deeper array remains an
+// opaque malformed member and is rejected by the bounded timing predicate before any backend runs it.
+function captureTimingArray(value, nested = false) {
+    const capture = nested ? (0, boundedArray_1.captureBoundedCubicBezier)(value) : (0, boundedArray_1.captureBoundedArray)(value);
+    if (capture.kind !== 'captured')
+        return (0, boundedArray_1.capturedArrayDescription)(capture);
+    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 element = capture.values[index];
+        captured[index] =
+            !nested && Array.isArray(element) ? captureTimingArray(element, true) : element;
+    }
+    return Object.freeze(captured);
+}
+const TRANSITION_MAP_KEYS = new Set(['default', 'layout', ...types_1.TARGET_PROPERTY_KEYS]);
+function transitionMapRefusal(transition) {
+    if (typeof transition !== 'object' || transition === null || Array.isArray(transition))
+        return null;
+    for (const key of Reflect.ownKeys(transition)) {
+        if (typeof key === 'string' && TRANSITION_MAP_KEYS.has(key)) {
+            return new validate_1.InvalidTransitionError(undefined, key, transition[key], 'a raw DriverCommand must carry a flat transition selected by the component boundary; ' +
+                'transition maps are not executable at the backend protocol (REQ-DRIVER-033)');
+        }
+    }
+    return null;
+}
+function isTransitionMapKey(key) {
+    return TRANSITION_MAP_KEYS.has(key);
+}
+function targetTransitionsShapeRefusal(value, targets) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return new validate_1.InvalidTransitionError(undefined, 'targetTransitions', value, 'retarget targetTransitions must be a plain object keyed by retarget targets (REQ-DRIVER-030)');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return new validate_1.InvalidTransitionError(undefined, 'targetTransitions', value, 'retarget targetTransitions must be a plain object keyed by retarget targets (REQ-DRIVER-030)');
+    }
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string') {
+            return new validate_1.InvalidTransitionError(undefined, String(key), undefined, 'retarget targetTransitions may only contain string retarget target keys (REQ-DRIVER-030)');
+        }
+        if (!Object.hasOwn(targets, key)) {
+            return new validate_1.InvalidTransitionError(undefined, key, undefined, 'retarget targetTransitions may only override a key present in targets (REQ-DRIVER-030)');
+        }
+    }
+    return null;
+}
+// Capture exactly one legal nested transition-bag level. A nested map entry is retained as an opaque
+// value so the validator can refuse recursive maps; recursively cloning malformed input here would
+// turn a fail-closed schema error into an unbounded/cyclic capture walk.
+function captureNestedTransitionBag(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const source = value;
+    const captured = Object.create(null);
+    for (const key of Reflect.ownKeys(source)) {
+        const member = source[key];
+        const capturedMember = typeof key === 'string' &&
+            (key === 'times' || key === 'ease' || key === 'easings' || key === 'easing') &&
+            Array.isArray(member)
+            ? captureTimingArray(member)
+            : member;
+        Object.defineProperty(captured, key, {
+            value: capturedMember,
+            enumerable: Object.getOwnPropertyDescriptor(source, key)?.enumerable ?? true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return Object.freeze(captured);
+}
+// Capture a transition independently of its caller. Every own field (including non-enumerable fields and
+// symbols) is read once and preserved; capture is deliberately NOT the schema/severity authority. Its
+// callers validate this immutable truth, so an unknown authored option is refused by the established
+// typed boundary instead of escaping before production can report it. Arrays are DEEP-cloned and frozen because
+// generator/contending state may retain them after command() returns (including a per-segment ease list's
+// nested cubic-bezier arrays, R8 M2-B). A null-prototype accumulator preserves an own `__proto__` field
+// instead of invoking the legacy setter.
+function captureTransition(transition) {
+    if (typeof transition !== 'object' || transition === null || Array.isArray(transition))
+        return transition;
+    const captured = Object.create(null);
+    for (const key of Reflect.ownKeys(transition)) {
+        const value = transition[key];
+        const capturedValue = typeof key === 'string' &&
+            (key === 'times' || key === 'ease' || key === 'easings' || key === 'easing') &&
+            Array.isArray(value)
+            ? captureTimingArray(value)
+            : typeof key === 'string' && isTransitionMapKey(key)
+                ? captureNestedTransitionBag(value)
+                : value;
+        Object.defineProperty(captured, key, {
+            value: capturedValue,
+            enumerable: Object.getOwnPropertyDescriptor(transition, key)?.enumerable ?? true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return Object.freeze(captured);
+}
+// A command-level transition is ALWAYS authored. Only a per-property transition can be the controller's
+// count-aware DefaultTransition, because defaults differ by property/keyframe count. Keep those two raw
+// slots distinct at this boundary instead of inferring provenance from a field such as `restSpeed`.
+function internalPropTransitionRefusal(transition) {
+    if (typeof transition !== 'object' || transition === null || Array.isArray(transition)) {
+        return (0, validate_1.validateTransitionRefusal)(transition);
+    }
+    const value = transition;
+    const type = value['type'];
+    const hasRestSpeed = Object.hasOwn(value, 'restSpeed');
+    // R16 (REQ-GESTURE-023): the internal inertia transition — the gesture free-drag release's
+    // two-phase generator descriptor. Command-layer only; validated field-by-field here, then
+    // passed through unchanged (both drivers construct the SAME generator physics, no skew).
+    if (type === 'inertia') {
+        const allowed = new Set([
+            'type',
+            'power',
+            'timeConstant',
+            'bounceStiffness',
+            'bounceDamping',
+            'restDelta',
+            'restSpeed',
+            'min',
+            'max',
+        ]);
+        for (const key of Reflect.ownKeys(value)) {
+            if (!allowed.has(key)) {
+                return new validate_1.InvalidTransitionError(undefined, typeof key === 'string' ? key : String(key), value[key], 'not a recognized internal inertia transition option (REQ-DRIVER-030, R16)');
+            }
+        }
+        for (const key of [
+            'power',
+            'timeConstant',
+            'bounceStiffness',
+            'bounceDamping',
+            'restDelta',
+            'restSpeed',
+        ]) {
+            const field = value[key];
+            if (!Object.hasOwn(value, key) ||
+                typeof field !== 'number' ||
+                !Number.isFinite(field) ||
+                field <= 0) {
+                return new validate_1.InvalidTransitionError(undefined, key, field, `an internal inertia transition requires an own finite ${key} greater than zero (REQ-DRIVER-030, R16)`);
+            }
+        }
+        // Bounds follow the drag-constraints sentinel law: open sides are ±Infinity of the correct
+        // polarity; wrong-polarity infinities and min > max are refused (G-INV-8).
+        const min = value['min'];
+        const max = value['max'];
+        if (min !== undefined && (typeof min !== 'number' || Number.isNaN(min) || min === Infinity)) {
+            return new validate_1.InvalidTransitionError(undefined, 'min', min, 'an internal inertia transition min must be a number or -Infinity (REQ-DRIVER-030, R16)');
+        }
+        if (max !== undefined && (typeof max !== 'number' || Number.isNaN(max) || max === -Infinity)) {
+            return new validate_1.InvalidTransitionError(undefined, 'max', max, 'an internal inertia transition max must be a number or +Infinity (REQ-DRIVER-030, R16)');
+        }
+        if (min !== undefined && max !== undefined && min > max) {
+            return new validate_1.InvalidTransitionError(undefined, 'min', min, 'an internal inertia transition requires min <= max (REQ-DRIVER-030, R16)');
+        }
+        return null;
+    }
+    if (type !== 'keyframes' && !hasRestSpeed)
+        return (0, validate_1.validateTransitionRefusal)(transition);
+    if (type !== 'keyframes') {
+        // U7c (REQ-SPRING-014): restSpeed/restDelta are AUTHORED vocabulary now, so restSpeed
+        // presence can no longer discriminate the controller's internal spring default from an
+        // authored spring — the shapes genuinely overlap, and Motion fidelity gives the authored
+        // reading precedence (a legal authored per-prop spring must never refuse as a "malformed
+        // internal default"). Validate as authored first; only when that fails does the STRICT
+        // internal shape law below get its say, so a malformed controller default still fails loud
+        // instead of riding along.
+        const authoredRefusal = (0, validate_1.validateTransitionRefusal)(transition);
+        if (authoredRefusal === null)
+            return null;
+        const internalRefusal = internalSpringDefaultRefusal(value);
+        return internalRefusal ?? authoredRefusal;
+    }
+    const allowed = new Set([
+        'type',
+        'duration',
+        'ease',
+        'delay',
+        'repeat',
+        'repeatType',
+        'repeatDelay',
+    ]);
+    for (const key of Reflect.ownKeys(value)) {
+        if (!allowed.has(key)) {
+            return new validate_1.InvalidTransitionError(undefined, typeof key === 'string' ? key : String(key), value[key], 'not a recognized internal driver transition option (REQ-DRIVER-030)');
+        }
+    }
+    const duration = value['duration'];
+    if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0) {
+        return new validate_1.InvalidTransitionError(undefined, 'duration', duration, 'an internal keyframes default requires a finite duration greater than zero (REQ-DRIVER-030)');
+    }
+    if (value['ease'] !== undefined && !isInternalKeyframesEase(value['ease'])) {
+        return new validate_1.InvalidTransitionError(undefined, 'ease', value['ease'], 'an internal keyframes default permits only one finite four-number cubic-bezier ease tuple (REQ-DRIVER-030)');
+    }
+    const authored = Object.create(null);
+    authored['type'] = 'tween';
+    authored['duration'] = duration;
+    if (value['ease'] !== undefined)
+        authored['ease'] = value['ease'];
+    for (const key of ['delay', 'repeat', 'repeatType', 'repeatDelay']) {
+        if (value[key] !== undefined)
+            authored[key] = value[key];
+    }
+    return (0, validate_1.validateTransitionRefusal)(authored);
+}
+// The STRICT internal spring-default shape (r16): the controller's count-aware
+// `getDefaultTransition` output carries exactly this vocabulary, every physics field present and
+// positive. Reached only when the authored reading already failed (U7c — see above), so this is
+// the fail-loud backstop for malformed controller output, never a gate on authored input.
+function internalSpringDefaultRefusal(value) {
+    const allowed = new Set([
+        'type',
+        'stiffness',
+        'damping',
+        'restSpeed',
+        'delay',
+        'repeat',
+        'repeatType',
+        'repeatDelay',
+    ]);
+    for (const key of Reflect.ownKeys(value)) {
+        if (!allowed.has(key)) {
+            return new validate_1.InvalidTransitionError(undefined, typeof key === 'string' ? key : String(key), value[key], 'not a recognized internal driver transition option (REQ-DRIVER-030)');
+        }
+    }
+    if (value['type'] !== 'spring') {
+        return new validate_1.InvalidTransitionError(undefined, 'restSpeed', value['restSpeed'], 'restSpeed is internal-only and valid only on an internal spring transition (REQ-DRIVER-030)');
+    }
+    for (const key of ['stiffness', 'damping', 'restSpeed']) {
+        const field = value[key];
+        if (!Object.hasOwn(value, key) ||
+            typeof field !== 'number' ||
+            !Number.isFinite(field) ||
+            field <= 0) {
+            return new validate_1.InvalidTransitionError(undefined, key, field, `an internal spring default requires an own finite ${key} greater than zero (REQ-DRIVER-030)`);
+        }
+    }
+    const authored = {
+        type: 'spring',
+        stiffness: value['stiffness'],
+        damping: value['damping'],
+    };
+    for (const key of ['delay', 'repeat', 'repeatType', 'repeatDelay']) {
+        if (value[key] !== undefined)
+            authored[key] = value[key];
+    }
+    return (0, validate_1.validateTransitionRefusal)(authored);
+}
+function isInternalKeyframesEase(value) {
+    if (!Array.isArray(value) || value.length !== 4)
+        return false;
+    for (let index = 0; index < 4; index++) {
+        if (!Object.hasOwn(value, index) ||
+            typeof value[index] !== 'number' ||
+            !Number.isFinite(value[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+function validatePreparedPropTransition(transition) {
+    // The raw/prepared seam admits controller defaults in addition to the closed authored Transition
+    // vocabulary ONLY in a PropTarget slot. Supplying and command boundaries call the authored validator.
+    const refusal = internalPropTransitionRefusal(transition);
+    if (refusal !== null)
+        throw refusal;
+    return transition;
+}
+function captureAndValidatePropTransition(transition) {
+    const shapeRefusal = (0, validate_1.transitionShapeRefusal)(transition);
+    if (shapeRefusal !== null)
+        throw shapeRefusal;
+    const captured = captureTransition(transition);
+    const mapRefusal = transitionMapRefusal(captured);
+    if (mapRefusal !== null)
+        throw mapRefusal;
+    return validatePreparedPropTransition(captured);
+}
+function captureAndValidateCommandTransition(transition) {
+    // Component slots admit `undefined` as an omitted transition, but the raw Driver command protocol
+    // has no defaulting authority: every start/retarget must carry its authored fallback before a target
+    // can be prepared or either backend can schedule. Keep requiredness here, ahead of capture, because
+    // generic validation intentionally treats undefined as legal absence for component consumers.
+    if (transition === undefined) {
+        throw new validate_1.InvalidTransitionError(undefined, 'transition', transition, 'a DriverCommand start or retarget requires an authored transition (REQ-DRIVER-030)');
+    }
+    const shapeRefusal = (0, validate_1.transitionShapeRefusal)(transition);
+    if (shapeRefusal !== null)
+        throw shapeRefusal;
+    const captured = captureTransition(transition);
+    const refusal = (0, validate_1.validateTransitionRefusal)(captured);
+    if (refusal !== null)
+        throw refusal;
+    const mapRefusal = transitionMapRefusal(captured);
+    if (mapRefusal !== null)
+        throw mapRefusal;
+    return captured;
+}
+function prepareStart(command) {
+    // Command transition first preserves the established defensive capture convention when one hostile
+    // object occupies both command and per-prop slots. The order is not public semantics; both backends
+    // observe only the resulting snapshot.
+    const commandTransition = captureAndValidateCommandTransition(command.transition);
+    const rawTargets = command.targets;
+    const releasesGesture = command.releasesGesture === true;
+    const targets = Object.create(null);
+    for (const key of Object.keys(rawTargets)) {
+        const rawTarget = rawTargets[key];
+        // One canonical read per field. Do not destructure/re-read inside either backend.
+        const to = rawTarget.to;
+        const from = rawTarget.from;
+        const velocity = rawTarget.velocity;
+        const transition = rawTarget.transition;
+        const preparedTransition = transition === undefined ? commandTransition : captureAndValidatePropTransition(transition);
+        const capturedTo = captureTarget(to);
+        const timingRefusal = (0, keyframeTiming_1.keyframeTimingRefusal)(undefined, key, capturedTo, preparedTransition);
+        if (timingRefusal !== null)
+            throw timingRefusal;
+        targets[key] = Object.freeze({
+            to: capturedTo,
+            from,
+            velocity: velocity ?? 0,
+            transition: preparedTransition,
+        });
+    }
+    const path = command.path === undefined
+        ? undefined
+        : Object.freeze({
+            fromX: command.path.fromX,
+            fromY: command.path.fromY,
+            toX: command.path.toX,
+            toY: command.path.toY,
+            peak: command.path.peak,
+            signedStrength: command.path.signedStrength,
+            rotationScale: command.path.rotationScale,
+            transition: captureAndValidatePropTransition(command.path.transition),
+        });
+    return Object.freeze({
+        kind: 'start',
+        targets: Object.freeze(targets),
+        releasesGesture,
+        ...(path === undefined ? {} : { path }),
+    });
+}
+function prepareRetarget(command) {
+    const transition = captureAndValidateCommandTransition(command.transition);
+    const rawTargets = command.targets;
+    const rawTargetTransitions = command.targetTransitions;
+    const targetTransitionsRefusal = targetTransitionsShapeRefusal(rawTargetTransitions, rawTargets);
+    if (targetTransitionsRefusal !== null)
+        throw targetTransitionsRefusal;
+    const targets = Object.create(null);
+    const targetTransitions = Object.create(null);
+    for (const key of Object.keys(rawTargets)) {
+        const target = rawTargets[key];
+        const hasRawTargetTransition = rawTargetTransitions !== undefined && Object.hasOwn(rawTargetTransitions, key);
+        const rawTargetTransition = hasRawTargetTransition ? rawTargetTransitions[key] : undefined;
+        if (hasRawTargetTransition && rawTargetTransition === undefined) {
+            throw new validate_1.InvalidTransitionError(undefined, key, undefined, 'retarget targetTransitions entries must contain a transition (REQ-DRIVER-030)');
+        }
+        let targetTransition;
+        if (!hasRawTargetTransition) {
+            targetTransition = transition;
+        }
+        else {
+            // The undefined case was rejected immediately above; this assertion records that
+            // runtime proof for the narrowed prepared boundary.
+            targetTransition = captureAndValidatePropTransition(rawTargetTransition);
+        }
+        const timingRefusal = (0, keyframeTiming_1.keyframeTimingRefusal)(undefined, key, target, targetTransition);
+        if (timingRefusal !== null)
+            throw timingRefusal;
+        targets[key] = target;
+        if (hasRawTargetTransition) {
+            targetTransitions[key] = targetTransition;
+        }
+    }
+    return Object.freeze({
+        kind: 'retarget',
+        targets: Object.freeze(targets),
+        transition,
+        ...(Object.keys(targetTransitions).length === 0
+            ? {}
+            : { targetTransitions: Object.freeze(targetTransitions) }),
+    });
+}
+const PREPARED_STOP = Object.freeze({ kind: 'stop' });
+function prepareDriverCommand(command) {
+    switch (command.kind) {
+        case 'start':
+            return prepareStart(command);
+        case 'retarget':
+            return prepareRetarget(command);
+        case 'stop':
+            return PREPARED_STOP;
+    }
+}
+// Preserve the small public Driver surface while making the raw→prepared transition structural: a
+// concrete backend implements PreparedDriver and therefore cannot accidentally inspect PropTarget.
+function adaptPreparedDriver(backend, assertCommandable) {
+    return {
+        register: (initial) => backend.register(initial),
+        command: (handle, command) => {
+            // Preserve each backend's lifecycle/handle failure precedence: an invalid destination fails
+            // before any hostile caller getter can run, just as it did before the shared adapter existed.
+            assertCommandable(handle);
+            backend.command(handle, prepareDriverCommand(command));
+        },
+        step: (elapsedMs) => backend.step(elapsedMs),
+        committed: (handle) => backend.committed(handle),
+        setActive: (handle, active) => backend.setActive(handle, active),
+        isActive: (handle) => backend.isActive(handle),
+        write: (handle, values, velocities) => backend.write(handle, values, velocities),
+        liveFor: (handle, key) => backend.liveFor(handle, key),
+    };
+}

package/dist/driver/prepare.d.cts

@@ -0,0 +1,4 @@
+import type { Driver, DriverCommand, PreparedDriver, PreparedDriverCommand, PropTransition } from "./types.cjs";
+export declare function captureTransition<T extends PropTransition>(transition: T): T;
+export declare function prepareDriverCommand(command: DriverCommand): PreparedDriverCommand;
+export declare function adaptPreparedDriver(backend: PreparedDriver, assertCommandable: (handle: Parameters<Driver['command']>[0]) => void): Driver;

package/dist/driver/prepare.d.ts

@@ -0,0 +1,4 @@
+import type { Driver, DriverCommand, PreparedDriver, PreparedDriverCommand, PropTransition } from "./types.js";
+export declare function captureTransition<T extends PropTransition>(transition: T): T;
+export declare function prepareDriverCommand(command: DriverCommand): PreparedDriverCommand;
+export declare function adaptPreparedDriver(backend: PreparedDriver, assertCommandable: (handle: Parameters<Driver['command']>[0]) => void): Driver;