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

package/dist/driver/prepare.js

@@ -0,0 +1,454 @@
+// 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.
+import { keyframeTimingRefusal } from "./keyframeTiming.js";
+import { captureBoundedArray, captureBoundedCubicBezier, capturedArrayDescription, } from "../component/boundedArray.js";
+import { InvalidTargetError, InvalidTransitionError, transitionShapeRefusal, validateTransitionRefusal, } from "../component/validate.js";
+import { TARGET_PROPERTY_KEYS } from "../component/types.js";
+// `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 = captureBoundedArray(to);
+    if (capture.kind !== 'captured') {
+        throw new InvalidTargetError(undefined, 'to', 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 ? captureBoundedCubicBezier(value) : captureBoundedArray(value);
+    if (capture.kind !== 'captured')
+        return 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', ...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 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 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 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 InvalidTransitionError(undefined, String(key), undefined, 'retarget targetTransitions may only contain string retarget target keys (REQ-DRIVER-030)');
+        }
+        if (!Object.hasOwn(targets, key)) {
+            return new 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.
+export 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 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 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 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 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 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 InvalidTransitionError(undefined, 'min', min, 'an internal inertia transition requires min <= max (REQ-DRIVER-030, R16)');
+        }
+        return null;
+    }
+    if (type !== 'keyframes' && !hasRestSpeed)
+        return 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 = 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 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 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 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 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 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 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 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 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 = 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 InvalidTransitionError(undefined, 'transition', transition, 'a DriverCommand start or retarget requires an authored transition (REQ-DRIVER-030)');
+    }
+    const shapeRefusal = transitionShapeRefusal(transition);
+    if (shapeRefusal !== null)
+        throw shapeRefusal;
+    const captured = captureTransition(transition);
+    const refusal = 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 = 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 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 = 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' });
+export 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.
+export 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),
+    };
+}