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

package/dist/component/validate.cjs

@@ -0,0 +1,1015 @@
+"use strict";
+// SPEC-COMPONENT §2 — validateTarget (REQ-API-013/014/016): the eager, exhaustive, fail-closed runtime
+// validator for a declarative animation target. It is the fail-loud backstop the compile-time Target type
+// (REQ-API-015) cannot be — it accepts an untyped, dynamically-shaped input and rejects, with a
+// descriptive error, any property that is unknown, off-host, wrong-typed, or reserved-but-unimplemented.
+// An invalid target NEVER partially applies: the first offending property aborts the whole target
+// (fail-closed). It composes the SUBSET resolver (membership/off-host authority) and normalizer (value
+// validity) — it does not fork a second membership list or a second parser. Host-agnostic (REQ-CORE-003).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidTransitionError = exports.InvalidTargetError = void 0;
+exports.targetShapeRefusal = targetShapeRefusal;
+exports.assertTargetShape = assertTargetShape;
+exports.validateTargetRefusal = validateTargetRefusal;
+exports.validateTarget = validateTarget;
+exports.validateTargetSnapshot = validateTargetSnapshot;
+exports.validateTransitionRefusal = validateTransitionRefusal;
+exports.transitionShapeRefusal = transitionShapeRefusal;
+exports.validateTransition = validateTransition;
+const resolve_1 = require("../subset/resolve.cjs");
+const normalize_1 = require("../subset/normalize.cjs");
+const discrete_1 = require("../value-types/discrete.cjs");
+const mix_1 = require("../value-types/mix.cjs");
+const constants_1 = require("../config/constants.cjs");
+const measure_resolve_1 = require("../value-types/measure-resolve.cjs");
+const motion_arc_1 = require("../motion-arc.cjs");
+const types_1 = require("./types.cjs");
+const transition_1 = require("./transition.cjs");
+const repeat_1 = require("../repeat.cjs");
+const transition_2 = require("../transition.cjs");
+const timing_1 = require("../timing.cjs");
+const boundedArray_1 = require("./boundedArray.cjs");
+// Thrown when a declarative target property is not a valid animatable value for the host. Structured
+// fields let tooling locate the offending prop; the message names the component, key, received value, and
+// reason (REQ-API-014). The originating SUBSET error (if any) is preserved via `cause` — this class only
+// ADDS the component/target context, it never swallows a failure.
+class InvalidTargetError extends Error {
+    key;
+    value;
+    componentId;
+    constructor(componentId, key, value, reason, cause) {
+        super(`${componentLabel(componentId)}: invalid animation target property '${key}' = ${renderValue(value)} — ${reason}`, cause !== undefined ? { cause } : undefined);
+        this.name = 'InvalidTargetError';
+        this.key = key;
+        this.value = value;
+        this.componentId = componentId;
+    }
+}
+exports.InvalidTargetError = InvalidTargetError;
+function componentLabel(componentId) {
+    // Public hosts supply their own complete identity (`<Text>`, `<Motion.Text>`, …). Wrapping
+    // that in a View-specific label corrupts the diagnostic and breaks REQ-API-014 ownership.
+    return componentId ?? '<Motion.View>';
+}
+// A compact, readable rendering of the received value for the error message — a quoted string, a bare
+// scalar, or a type tag for non-primitives (so an object does not print as an opaque `[object Object]`
+// without context).
+function renderValue(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null)
+        return String(value);
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return `an array (length ${value.length})`;
+    return `a ${typeof value} value`;
+}
+// The developer-facing name of a value type, for the "expected …" clause of a wrong-shape message.
+function describeValueType(valueType) {
+    switch (valueType) {
+        case 'length':
+            // R13 value-breadth (REQ-VALUETYPE-013): measure-resolved %/auto/simple calc join number|px.
+            return 'length (a number of dp, a px string, or a measure-resolved %/auto/simple calc)';
+        case 'unitless':
+            return 'unitless numeric';
+        case 'angle':
+            return 'angle (a number of degrees, or a deg/rad string)';
+        case 'rgba':
+            return 'color';
+        case 'complex':
+            return 'complex';
+        case 'discrete':
+            return 'discrete keyword (a CSS keyword string like none/flex/hidden/visible)';
+        case 'gesture':
+            return 'gesture';
+    }
+}
+// Validate one property's value against its capability entry (REQ-API-013). Numeric/color value types are
+// checked by the SUBSET normalizer — the single value validator, which parses the value as its type and
+// throws loudly on anything unparseable or unit-incompatible. complex/gesture value types are reserved in
+// the registry but their animation is not implemented, so they fail loud as "not yet supported"
+// (REQ-API-016) rather than silently no-op.
+// RETURN-shaped (M3 r6 major 30a9c21bf960; completed M3 r7 majors 32946c21f150 +
+// 22c76ce970f3): the validator's OWN refusals return and BOTH dependency gates
+// (capability resolution, value normalization) are verdict-shaped all the way down — no
+// catch exists anywhere on this path, so a returned refusal is validator-made by
+// construction and anything THROWN is a fault that keeps its exact identity.
+function validateValueRefusal(componentId, key, entry, value) {
+    // A keyframe ARRAY target (REQ-API-033, R8): the value interpolates THROUGH the elements. Validate
+    // the array shape + every element as this key's single value-type (the array is one value-type), then
+    // fall through to the scalar checks for a non-array value.
+    if (Array.isArray(value)) {
+        return validateKeyframeArrayRefusal(componentId, key, entry, value);
+    }
+    switch (entry.valueType) {
+        case 'length':
+        case 'unitless':
+        case 'angle':
+        case 'rgba': {
+            if (typeof value !== 'number' && typeof value !== 'string') {
+                return new InvalidTargetError(componentId, key, value, `expected a ${describeValueType(entry.valueType)} value (number or string), received ${renderValue(value)}`);
+            }
+            // The key-aware executable matrix runs BEFORE normalization (review fe5d455ffde7): a
+            // length string — px included — executes only on the positional keys, and auto only for
+            // width/height. A px-normalizable string on a non-positional key must not slip through
+            // the normalizer's direct acceptance, and a context-requiring form must not ride the
+            // parse rescue key-blind.
+            if (entry.valueType === 'length' && typeof value === 'string') {
+                const executableRefusal = (0, measure_resolve_1.executableLengthValueRefusal)(key, value);
+                if (executableRefusal !== null) {
+                    return new InvalidTargetError(componentId, key, value, executableRefusal, new Error(executableRefusal));
+                }
+            }
+            {
+                // Reuse the SUBSET normalizer as the authoritative value gate (parses + enforces unit
+                // compatibility + rejects malformed colors), VERDICT-shaped (M3 r7 major 22c76ce970f3):
+                // its returned refusal enriches with the target/component context (REQ-API-014) — the
+                // normalizer's message is preserved verbatim in the reason and as `cause` — while a
+                // THROW from a polluted parse dependency propagates untouched (no catch exists here).
+                const verdict = (0, normalize_1.normalizeCapabilityVerdict)(entry, value);
+                if (verdict.refusal !== null) {
+                    // R13 value-breadth (REQ-VALUETYPE-013): length may be measure-resolved (%/auto/simple
+                    // calc). Those forms are not px-normalizable without layout context — accept when
+                    // parseLengthTargetVerdict succeeds (the key-aware matrix already refused what it
+                    // must not execute, above); unsupported calc remainder stays loud.
+                    if (entry.valueType === 'length') {
+                        const lengthVerdict = (0, measure_resolve_1.parseLengthTargetVerdict)(value);
+                        if (lengthVerdict.refusal === null)
+                            return null;
+                        return new InvalidTargetError(componentId, key, value, `not a valid ${describeValueType(entry.valueType)} value (${lengthVerdict.refusal})`, new Error(lengthVerdict.refusal));
+                    }
+                    return new InvalidTargetError(componentId, key, value, `not a valid ${describeValueType(entry.valueType)} value (${verdict.refusal.message})`, verdict.refusal);
+                }
+            }
+            return null;
+        }
+        case 'discrete': {
+            // T23 B2b: a single keyword string of the discrete FAMILY. isDiscreteKeyword pre-guards the
+            // parse (a letters-only string can never throw in parseValue); the family verdict refuses
+            // keywords other families own ('auto', named colors). WHICH mix law a pair takes — the
+            // mixVisibility step or the zero-slot target constant (REQ-VALUETYPE-015) — is a mix-time
+            // question over TWO values, answered at the engines' pair boundaries and not by this
+            // single-value gate. No discrete pair is refused on account of its endpoints' visibility.
+            if (typeof value !== 'string' ||
+                !(0, discrete_1.isDiscreteKeyword)(value) ||
+                (0, mix_1.parseValue)(value).kind !== 'discrete') {
+                return new InvalidTargetError(componentId, key, value, `expected a ${describeValueType(entry.valueType)} value, received ${renderValue(value)}`);
+            }
+            return null;
+        }
+        case 'complex':
+        case 'gesture':
+            return new InvalidTargetError(componentId, key, value, `not yet supported — '${key}' is reserved in the universal-subset registry (valueType '${entry.valueType}') but its animation is not yet implemented (REQ-API-016)`);
+    }
+    return null;
+}
+// Validate a keyframe ARRAY target (REQ-API-033, R8): length ≥2, and every element a valid value of the
+// key's single value-type — the array is ONE value-type, so each element reuses `validateValueRefusal`
+// (no forked parser). A `null` FIRST element is legal (from-current seed, R8-F2); a null anywhere else,
+// too-few keyframes, or a mixed/incompatible element FAILS LOUD naming the offending index. RETURN-shaped
+// like its caller — the whole array is the reported value; the per-element refusal rides as `cause`.
+function validateKeyframeArrayRefusal(componentId, key, entry, arr) {
+    if (arr.length < 2) {
+        return new InvalidTargetError(componentId, key, arr, `a keyframe array must have at least two keyframes (received length ${arr.length}) — REQ-API-033`);
+    }
+    for (let i = 0; i < arr.length; i++) {
+        const element = arr[i];
+        if (element === null) {
+            // R8-F2: only the FIRST keyframe may be null (seed from the element's current value).
+            if (i === 0)
+                continue;
+            return new InvalidTargetError(componentId, key, arr, `keyframe at index ${i} is null — only the FIRST keyframe may be null (from-current seed, R8-F2)`);
+        }
+        // Each keyframe is a SCALAR of the key's single value-type — a nested array is not a keyframe.
+        // Guard BEFORE delegating to the (array-aware) value validator, else a nested array recurses
+        // straight back into this function and slips through, reaching web Motion or the numeric generator
+        // as a malformed input (review 2026-07-18 major 7b423a46e6a1).
+        if (Array.isArray(element)) {
+            return new InvalidTargetError(componentId, key, arr, `keyframe at index ${i} is a nested array — each keyframe must be a single ${describeValueType(entry.valueType)} value, not an array (REQ-API-033)`);
+        }
+        const elementRefusal = validateValueRefusal(componentId, key, entry, element);
+        if (elementRefusal !== null) {
+            return new InvalidTargetError(componentId, key, arr, `keyframe at index ${i} (${renderValue(element)}) is not a valid ${describeValueType(entry.valueType)} value for '${key}' — a keyframe array is a single value-type (REQ-API-033)`, elementRefusal);
+        }
+    }
+    return null;
+}
+// The target's SHAPE is part of the runtime contract (REQ-API-013, review round 9): before any
+// per-property validation, the target itself must be a plain object. Without this gate,
+// Object.keys silently coerced numbers/booleans to the empty target and raw-TypeErrored on null —
+// either no failure at all, or an unnamed one at the wrong altitude. Exported so the severity
+// lanes (native gate, web shim) can refuse a malformed target AS A UNIT under the production
+// report-and-refuse posture.
+function targetShapeRefusal(target, opts) {
+    if (typeof target === 'object' && target !== null && !Array.isArray(target)) {
+        // PLAIN means plain (review round 10 major 33): a Date/Map/Set/class instance carries no
+        // own enumerable target keys, so the per-key loop below would validate it CLEAN as the
+        // empty target — silent acceptance of a malformed input. Only object literals qualify:
+        // prototype Object.prototype (literals, {...spreads}) or null (Object.create(null)).
+        const proto = Object.getPrototypeOf(target);
+        if (proto === Object.prototype || proto === null)
+            return null;
+    }
+    return new InvalidTargetError(opts?.componentId, '(target)', target, 'a declarative target must be a plain object of animatable properties ' +
+        '(REQ-API-013 — a malformed shape fails loud, never coerces to the empty target)');
+}
+function assertTargetShape(target, opts) {
+    const refusal = targetShapeRefusal(target, opts);
+    if (refusal !== null)
+        throw refusal;
+}
+// Eagerly + exhaustively validate every property of a declarative target against a host (REQ-API-013).
+// Fails CLOSED on the FIRST offending property — the throw aborts iteration so an invalid target never
+// partially applies. Accepts a loose, untyped input (dynamically-shaped objects, JS callers) — this is the
+// runtime authority the compile-time `Target` type (REQ-API-015) delegates units/ranges/dynamic shapes to.
+function validateTargetRefusal(target, host, opts) {
+    // This is a root public boundary too, not merely the refusal-only half of a supplying
+    // gate. Delegate to the one-read snapshot authority so hostile keyframe arrays cannot
+    // grow or change between validation steps.
+    return validateTargetSnapshot(target, host, opts).refusal;
+}
+function validateTarget(target, host, opts) {
+    const refusal = validateTargetRefusal(target, host, opts);
+    if (refusal !== null)
+        throw refusal;
+}
+// Validate a target AND return the materialized one-read snapshot a FORWARDING caller must hand on
+// (R8, review major 23). A boundary that validates a target and then forwards it to a second reader
+// (motion/react on the web leg, or resolveTarget) must forward THIS snapshot, never the caller's raw
+// dictionary: an accessor-backed array member (a getter returning a different value per read) passes
+// validation on its first read yet forwards an UNVALIDATED second read downstream. Each ARRAY member
+// is materialized from one bounded length + one read per own index and frozen BEFORE the value
+// gate runs, so the validators and the forwarded target read the SAME single truth — the target
+// counterpart of validateVariantEntrySnapshot. Non-array members pass through; scalars are already
+// immutable. Refusal-only callers keep validateTargetRefusal (no forward ⇒ no second read).
+function validateTargetSnapshot(target, host, opts) {
+    const shapeRefusal = targetShapeRefusal(target, opts);
+    if (shapeRefusal !== null)
+        return { refusal: shapeRefusal, target: null };
+    // READ phase — materialize every array member ONCE, before the value gate reads any element. The
+    // accumulator is NULL-PROTOTYPE (review major 24): an own enumerable '__proto__' target key assigned
+    // onto an ordinary object invokes the legacy prototype setter and vanishes BEFORE the capability gate
+    // runs — a silent empty snapshot with no refusal (G-INV-8 no-silent-failure). On a null-prototype
+    // object the assignment creates an own data property, so '__proto__' survives to be refused loudly.
+    const snapshot = Object.create(null);
+    for (const key of Object.keys(target)) {
+        const member = target[key];
+        if (!Array.isArray(member)) {
+            snapshot[key] = member;
+            continue;
+        }
+        const captured = (0, boundedArray_1.captureBoundedArray)(member);
+        if (captured.kind !== 'captured') {
+            return {
+                refusal: new InvalidTargetError(opts?.componentId, key, (0, boundedArray_1.capturedArrayDescription)(captured), `keyframe arrays must have a safe length between 0 and 100000 (REQ-API-033)`),
+                target: null,
+            };
+        }
+        snapshot[key] = captured.values;
+    }
+    const componentId = opts?.componentId;
+    for (const key of Object.keys(snapshot)) {
+        if (key === 'transitionEnd') {
+            // T23 B3 (pin visual-element-target.ts:38-46/159-168): a target-LEVEL sub-target whose
+            // values JUMP (apply instantly, never animate) after the target's animations settle.
+            // Validate each entry as a SINGLE value of its capability — keyframe arrays and a nested
+            // transitionEnd are meaningless for a jump and refuse loud. The snapshot KEEPS the
+            // sub-target: forwarding boundaries (the web leg) hand it to motion/react, which executes
+            // it natively; the native boundary destructures it into the settle-jump lane.
+            const sub = snapshot[key];
+            if (typeof sub !== 'object' || sub === null || Array.isArray(sub)) {
+                return {
+                    refusal: new InvalidTargetError(componentId, key, sub, 'transitionEnd must be a plain object of target keys to JUMP to at settle (T23 B3)'),
+                    target: null,
+                };
+            }
+            for (const subKey of Object.keys(sub)) {
+                const subValue = sub[subKey];
+                if (subKey === 'transitionEnd') {
+                    return {
+                        refusal: new InvalidTargetError(componentId, 'transitionEnd.transitionEnd', subValue, 'transitionEnd does not nest (T23 B3)'),
+                        target: null,
+                    };
+                }
+                if (Array.isArray(subValue)) {
+                    return {
+                        refusal: new InvalidTargetError(componentId, `transitionEnd.${subKey}`, subValue, 'transitionEnd values JUMP at settle — a keyframe array cannot jump (T23 B3)'),
+                        target: null,
+                    };
+                }
+                const { entry: subEntry, unsupported: subUnsupported } = (0, resolve_1.resolveCapabilityVerdict)(host, subKey);
+                if (subUnsupported !== null) {
+                    return {
+                        refusal: new InvalidTargetError(componentId, `transitionEnd.${subKey}`, subValue, subUnsupported.reason === 'unknown'
+                            ? 'not a recognized universal-subset property'
+                            : `not supported on host '${host.id}' — it is available on: ${subUnsupported.supportedOn.join(', ')}`, subUnsupported),
+                        target: null,
+                    };
+                }
+                const subRefusal = validateValueRefusal(componentId, subKey, subEntry, subValue);
+                if (subRefusal !== null) {
+                    // Re-key to the full PATH: a supplying boundary (variants) surfaces this message
+                    // verbatim, and the bare sub-key would read as the ANIMATED member. The value law
+                    // itself ran key-aware above (the executable matrix needs the real key).
+                    return {
+                        refusal: new InvalidTargetError(componentId, `transitionEnd.${subKey}`, subValue, `refused as a settle-jump value — ${subRefusal.message}`, subRefusal),
+                        target: null,
+                    };
+                }
+            }
+            continue;
+        }
+        const { entry, unsupported } = (0, resolve_1.resolveCapabilityVerdict)(host, key);
+        if (unsupported !== null) {
+            const reason = unsupported.reason === 'unknown'
+                ? `not a recognized universal-subset property`
+                : `not supported on host '${host.id}' — it is available on: ${unsupported.supportedOn.join(', ')}`;
+            return {
+                refusal: new InvalidTargetError(componentId, key, snapshot[key], reason, unsupported),
+                target: null,
+            };
+        }
+        const valueRefusal = validateValueRefusal(componentId, key, entry, snapshot[key]);
+        if (valueRefusal !== null)
+            return { refusal: valueRefusal, target: null };
+    }
+    return { refusal: null, target: snapshot };
+}
+// Thrown when a transition config is malformed (G-INV-8: unsupported or malformed gesture/animation
+// config fails loudly — never a silent no-op). Mirrors InvalidTargetError's structured shape so
+// tooling can locate the offending option the same way.
+class InvalidTransitionError extends Error {
+    key;
+    value;
+    componentId;
+    constructor(componentId, key, value, reason) {
+        super(`${componentLabel(componentId)}: invalid transition option '${key}' = ${renderValue(value)} — ${reason}`);
+        this.name = 'InvalidTransitionError';
+        this.key = key;
+        this.value = value;
+        this.componentId = componentId;
+    }
+}
+exports.InvalidTransitionError = InvalidTransitionError;
+const TRANSITION_NUMBER_OPTIONS = new Set([
+    'duration',
+    'delay',
+    'stiffness',
+    'damping',
+    'mass',
+    'bounce',
+    'visualDuration',
+    'velocity',
+    // U7c (REQ-SPRING-014): the authored settle thresholds — finite numbers, no range floor here;
+    // a negative value's never-settling spring is caught by the derived-config probe instead.
+    'restDelta',
+    'restSpeed',
+]);
+const NAMED_EASINGS = new Set(timing_1.NAMED_EASING_KEYS);
+// A SINGLE easing: a named curve, or ONE 4-point cubic-bezier array. The 4-number bezier is one easing,
+// NEVER four segment easings (REQ-API-033 — `isEasingList` disambiguates it from a per-segment list).
+function isValidSingleEasing(value) {
+    if (typeof value === 'string')
+        return NAMED_EASINGS.has(value);
+    if (!Array.isArray(value) || value.length !== 4)
+        return false;
+    for (let index = 0; index < 4; index++) {
+        // Array.prototype.every skips holes. Missing cubic-bezier coordinates are invalid input, never
+        // implicit defaults — preserve the exact fail-closed timing shape at every boundary.
+        if (!Object.hasOwn(value, index))
+            return false;
+        const point = value[index];
+        if (typeof point !== 'number' || !Number.isFinite(point))
+            return false;
+    }
+    return true;
+}
+function everyPresent(value, predicate) {
+    for (let index = 0; index < value.length; index++) {
+        // Array.prototype.every skips holes, which previously allowed a sparse offsets/easing list to
+        // reach the generator and activate its fallback behavior.
+        if (!Object.hasOwn(value, index) || !predicate(value[index]))
+            return false;
+    }
+    return true;
+}
+function firstMissingArrayIndex(value) {
+    for (let index = 0; index < value.length; index++) {
+        if (!Object.hasOwn(value, index))
+            return index;
+    }
+    return null;
+}
+const TRANSITION_MAP_KEYS = new Set(['default', 'layout', ...types_1.TARGET_PROPERTY_KEYS]);
+// T21 (REQ-API-053): the tree-lane family — legal on a root bag, refused inside per-value map
+// entries (a consumer bag feeds ONE value's generator; orchestration schedules the TREE).
+const ORCHESTRATION_KEY_SET = new Set(types_1.ORCHESTRATION_OPTION_KEYS);
+function isTransitionMapKey(key) {
+    return TRANSITION_MAP_KEYS.has(key);
+}
+function validateTransitionMapEntryRefusal(componentId, mapKey, value, rootFlat) {
+    if (value === undefined)
+        return null;
+    const options = componentId === undefined ? undefined : { componentId };
+    const shapeRefusal = transitionShapeRefusal(value, options);
+    if (shapeRefusal !== null)
+        return shapeRefusal;
+    const record = value;
+    const flat = Object.create(null);
+    let inherits = false;
+    for (const key of Reflect.ownKeys(record)) {
+        const member = record[key];
+        if (typeof key !== 'string') {
+            return new InvalidTransitionError(componentId, mapKey, value, 'a nested transition bag permits only recognized string option keys (REQ-API-051)');
+        }
+        if (key === 'inherit') {
+            if (member !== undefined && typeof member !== 'boolean') {
+                return new InvalidTransitionError(componentId, mapKey + '.inherit', member, 'nested transition inherit must be a boolean (REQ-API-051)');
+            }
+            inherits = member === true;
+            continue;
+        }
+        if (ORCHESTRATION_KEY_SET.has(key)) {
+            return new InvalidTransitionError(componentId, mapKey + '.' + key, member, 'orchestration options live on the tree-level transition bag (element, variant, or ' +
+                'MotionConfig default), never a per-value map entry (REQ-API-053)');
+        }
+        if (key === 'path') {
+            return new InvalidTransitionError(componentId, mapKey + '.path', member, mapKey === 'layout'
+                ? 'transition.layout.path is deferred (REQ-API-059 F3) — property-lane arc() only'
+                : 'path lives on the element transition bag, never a per-value map entry (REQ-API-059)');
+        }
+        if (isTransitionMapKey(key)) {
+            return new InvalidTransitionError(componentId, mapKey + '.' + key, member, 'nested transition maps do not recurse (REQ-API-051)');
+        }
+        flat[key] = member;
+    }
+    if (!inherits) {
+        // A replacing child is validated as its own flat bag. Root fields only join a selected child
+        // when the authored branch opts into `inherit: true`, matching the pinned getValueTransition path.
+        return validateTransitionRefusal(flat, options);
+    }
+    const merged = Object.create(null);
+    for (const key of Reflect.ownKeys(rootFlat))
+        merged[key] = rootFlat[key];
+    for (const key of Reflect.ownKeys(flat))
+        merged[key] = flat[key];
+    return validateTransitionRefusal(merged, options);
+}
+/**
+ * Eagerly validate a transition config (REQ-API-001 vocabulary, G-INV-8 fail-loud). The runtime
+ * authority the compile-time Transition type cannot be: it accepts an untyped input (a
+ * dynamically-shaped gesture-state member, a JS caller) and rejects, with a typed error, any shape
+ * that is not a plain object of known, well-typed transition options. `undefined` is valid absence.
+ */
+function validateTransitionRefusal(transition, opts) {
+    if (transition === undefined)
+        return null;
+    const componentId = opts?.componentId;
+    const shapeRefusal = transitionShapeRefusal(transition, opts);
+    if (shapeRefusal !== null)
+        return shapeRefusal;
+    // `transitionShapeRefusal` above establishes the record shape. Keep the local cast after that
+    // boundary so every option read below belongs to the immutable validation truth.
+    const transitionRecord = transition;
+    // Transition shape is closed over ALL own keys, not just enumerable strings. An authored
+    // non-enumerable `times` still controls trajectory timing, while a symbol can never name a
+    // public option. Capture these keys exactly once into the immutable validation truth.
+    const snapshot = Object.create(null);
+    for (const key of Reflect.ownKeys(transitionRecord)) {
+        const rawValue = transitionRecord[key];
+        if (typeof key !== 'string') {
+            return new InvalidTransitionError(componentId, String(key), rawValue, 'a transition permits only recognized string option keys (G-INV-8)');
+        }
+        if ((key === 'times' || key === 'ease' || key === 'easings' || key === 'easing') &&
+            Array.isArray(rawValue)) {
+            const capture = (0, boundedArray_1.captureBoundedArray)(rawValue);
+            if (capture.kind !== 'captured') {
+                return new InvalidTransitionError(componentId, key, (0, boundedArray_1.capturedArrayDescription)(capture), `${key} must have a safe bounded array length (REQ-API-033)`);
+            }
+            const captured = [];
+            captured.length = capture.values.length;
+            for (let index = 0; index < capture.values.length; index++) {
+                if (!Object.hasOwn(capture.values, index))
+                    continue;
+                const member = capture.values[index];
+                if (!Array.isArray(member)) {
+                    captured[index] = member;
+                    continue;
+                }
+                const nestedCapture = (0, boundedArray_1.captureBoundedCubicBezier)(member);
+                if (nestedCapture.kind !== 'captured') {
+                    return new InvalidTransitionError(componentId, key, (0, boundedArray_1.capturedArrayDescription)(nestedCapture), `${key} contains an easing that is not a four-point cubic-bezier tuple (REQ-API-033)`);
+                }
+                captured[index] = nestedCapture.values;
+            }
+            snapshot[key] = Object.freeze(captured);
+            continue;
+        }
+        snapshot[key] = rawValue;
+    }
+    for (const key of Reflect.ownKeys(snapshot)) {
+        // Symbols returned above before snapshotting; this narrows the closed schema for TypeScript.
+        if (typeof key !== 'string')
+            continue;
+        const value = snapshot[key];
+        if (value === undefined)
+            continue; // an explicitly-undefined option reads as absent
+        if (isTransitionMapKey(key)) {
+            const rootFlat = Object.create(null);
+            for (const rootKey of Reflect.ownKeys(snapshot)) {
+                if (typeof rootKey === 'string' && rootKey !== 'inherit' && !isTransitionMapKey(rootKey)) {
+                    rootFlat[rootKey] = snapshot[rootKey];
+                }
+            }
+            const mapRefusal = validateTransitionMapEntryRefusal(componentId, key, value, rootFlat);
+            if (mapRefusal !== null)
+                return mapRefusal;
+            continue;
+        }
+        if (!types_1.TRANSITION_OPTION_KEYS.includes(key)) {
+            return new InvalidTransitionError(componentId, key, value, `not a recognized transition option (known: ${types_1.TRANSITION_OPTION_KEYS.join(', ')})`);
+        }
+        if (key === 'type') {
+            // U7a: `false` is the authored instant lane (the pin's makeAnimationInstant — the
+            // generator is skipped and the final keyframe commits next frame, delay honored).
+            if (value !== 'spring' && value !== 'tween' && value !== false) {
+                return new InvalidTransitionError(componentId, key, value, "the guaranteed-subset transition types are 'spring', 'tween', and false");
+            }
+            continue;
+        }
+        if (key === 'ease' || key === 'easings' || key === 'easing') {
+            // R8 M2-B (REQ-API-033 law d): `ease`/`easings`/`easing` is a SINGLE easing (named curve or one 4-point
+            // cubic-bezier) OR — for a keyframe-array target — a PER-SEGMENT list of those. `isEasingList`
+            // distinguishes the two: a 4-number bezier is ONE easing (first element numeric), a list's
+            // elements are themselves easings. Shape-valid lists may have any count: the generator indexes
+            // available members, uses linear for missing members, and ignores extras (pin parity).
+            const isList = (0, timing_1.isEasingList)(value);
+            const missingIndex = Array.isArray(value) ? firstMissingArrayIndex(value) : null;
+            if (missingIndex !== null) {
+                return new InvalidTransitionError(componentId, key, value, `ease is missing index ${missingIndex}; sparse timing arrays are invalid (REQ-API-033)`);
+            }
+            const validCurve = isList
+                ? everyPresent(value, isValidSingleEasing)
+                : isValidSingleEasing(value);
+            if (!validCurve) {
+                return new InvalidTransitionError(componentId, key, value, 'ease must be a Motion-named curve (linear, easeIn/Out/InOut, circ*, back*, anticipate), a 4-point ' +
+                    'cubic-bezier array, or a per-segment list of those for a keyframe array (REQ-API-033)');
+            }
+            continue;
+        }
+        if (key === 'times') {
+            // R8 M2-B (REQ-API-033 law d): custom keyframe OFFSETS — finite numbers in [0, 1]. A count
+            // mismatch is shape-valid and makes the generator use even offsets, matching the pin.
+            const missingIndex = Array.isArray(value) ? firstMissingArrayIndex(value) : null;
+            if (missingIndex !== null) {
+                return new InvalidTransitionError(componentId, key, value, `times is missing index ${missingIndex}; sparse timing arrays are invalid (REQ-API-033)`);
+            }
+            const validTimes = Array.isArray(value) &&
+                everyPresent(value, (offset) => typeof offset === 'number' && Number.isFinite(offset) && offset >= 0 && offset <= 1);
+            if (!validTimes) {
+                return new InvalidTransitionError(componentId, key, value, 'times must be an array of finite offsets in [0, 1] (REQ-API-033)');
+            }
+            continue;
+        }
+        if (key === 'repeat') {
+            // The ONE option that may be non-finite: `Infinity` is the pinned endless spelling, so this
+            // key is deliberately outside TRANSITION_NUMBER_OPTIONS' finite check (REQ-API-049).
+            if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+                return new InvalidTransitionError(componentId, key, value, "'repeat' must be a non-negative number of ADDITIONAL plays, or Infinity for endless");
+            }
+            // H2 (REQ-API-049): a FRACTIONAL repeat is accepted and executed. It used to be refused
+            // because the pin runs the partial play and then SNAPS to its final keyframe at finish — its
+            // rule tests `repeat % 2 === 1`, which selects only the odd integers, so no fraction takes
+            // the first-keyframe branch. The fold now reproduces that commit (REQ-TIMING-003,
+            // `repeatGenerator`'s `finalValue`), so no validation refusal stands in for it. The negative
+            // / NaN / non-number branch above is a different question and is unchanged.
+            continue;
+        }
+        if (key === 'repeatType') {
+            if (value !== 'loop' && value !== 'reverse' && value !== 'mirror') {
+                return new InvalidTransitionError(componentId, key, value, "'repeatType' is one of 'loop', 'reverse', or 'mirror'");
+            }
+            continue;
+        }
+        if (key === 'repeatDelay') {
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                return new InvalidTransitionError(componentId, key, value, "'repeatDelay' must be a finite, non-negative number of seconds");
+            }
+            if (!Number.isFinite(value * 1000)) {
+                return new InvalidTransitionError(componentId, key, value, 'the seconds→ms crossing overflows to a non-finite repeatDelay (G-INV-8)');
+            }
+            // The same horizon `delay` and `duration` are bound to. Without it a repeatDelay that is
+            // finite after ×1000 but past any reachable time drives `resolvedDuration` so high that
+            // `totalDuration` overflows to Infinity — and a FINITE repeat then never completes, silently
+            // acquiring the endless repeat's never-settles semantics the author did not ask for.
+            if (value * 1000 > constants_1.SETTLE_HORIZON_MS) {
+                return new InvalidTransitionError(componentId, key, value, 'the dead time between plays exceeds the settle horizon (2**53 ms) — a repeat that ' +
+                    'can never reach its next iteration is not executable (G-INV-8)');
+            }
+            continue;
+        }
+        // T21 (REQ-API-053): the orchestration family. `when` is the closed vocabulary — the pinned
+        // runtime treats ANY other truthy value as children-first, a silent misauthoring this engine
+        // refuses. delayChildren mirrors the shipped `delay` sign law (negative = elapsed-time
+        // offset), so it has NO sign floor — only finite-or-function.
+        if (key === 'when') {
+            if (value !== false && value !== 'beforeChildren' && value !== 'afterChildren') {
+                return new InvalidTransitionError(componentId, key, value, "'when' is false, 'beforeChildren', or 'afterChildren' (REQ-API-053)");
+            }
+            continue;
+        }
+        if (key === 'delayChildren') {
+            const validDelayChildren = typeof value === 'function' || (typeof value === 'number' && Number.isFinite(value));
+            if (!validDelayChildren) {
+                return new InvalidTransitionError(componentId, key, value, "'delayChildren' is a finite number of seconds (negative = elapsed-time offset, the " +
+                    'shipped delay law) or a stagger()-shaped function (index, total) => seconds ' +
+                    '(REQ-API-053)');
+            }
+            continue;
+        }
+        if (key === 'staggerChildren') {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return new InvalidTransitionError(componentId, key, value, "'staggerChildren' must be a finite number of seconds per index step (REQ-API-053)");
+            }
+            continue;
+        }
+        if (key === 'staggerDirection') {
+            if (value !== 1 && value !== -1) {
+                return new InvalidTransitionError(componentId, key, value, "'staggerDirection' is 1 (first→last) or -1 (last→first) (REQ-API-053)");
+            }
+            continue;
+        }
+        if (key === 'path') {
+            if (!(0, motion_arc_1.isNativeArcPath)(value)) {
+                return new InvalidTransitionError(componentId, key, value, 'transition.path must be the value returned by arc() (REQ-API-059)');
+            }
+            continue;
+        }
+        if (TRANSITION_NUMBER_OPTIONS.has(key)) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return new InvalidTransitionError(componentId, key, value, `'${key}' must be a finite number`);
+            }
+            // Executable ranges (G-INV-8): the reference-driver probes are the law's evidence —
+            // mass/stiffness 0 and visualDuration 0 emit NaN, damping 0 never settles; duration 0
+            // and delay 0 execute exactly (kept valid, motion-idiomatic); bounce is the [0, 1]
+            // shape contract. A config the driver cannot execute must refuse HERE, never reach it.
+            if ((key === 'stiffness' || key === 'damping' || key === 'mass' || key === 'visualDuration') &&
+                value <= 0) {
+                return new InvalidTransitionError(componentId, key, value, `'${key}' must be positive — a zero/negative value is not executable (the spring ` +
+                    'resolution emits non-finite or never-settling output; G-INV-8)');
+            }
+            // `delay` deliberately has NO sign floor (r6 major 1a8d6f29c44e): pinned Motion
+            // implements a negative delay as an elapsed-time offset (start mid-trajectory), and
+            // this repo pins that behavior (layoutProp.test.ts negative-delay coverage).
+            if (key === 'duration' && value < 0) {
+                return new InvalidTransitionError(componentId, key, value, `'${key}' cannot be negative`);
+            }
+            if (key === 'bounce' && (value < 0 || value > 1)) {
+                return new InvalidTransitionError(componentId, key, value, "'bounce' is the [0, 1] shape parameter (0 = no bounce, 1 = extremely bouncy)");
+            }
+        }
+    }
+    // T18-a (REQ-API-049): `repeatType`/`repeatDelay` only mean something to a fold that runs. With
+    // `repeat` absent or 0 the fold is inert, so they would ride along as silent no-ops — the same
+    // law that refuses `delay` on a lane which cannot execute it (G-INV-8).
+    const repeatCount = snapshot['repeat'];
+    const foldRuns = typeof repeatCount === 'number' && repeatCount > 0;
+    if (!foldRuns) {
+        for (const companion of ['repeatType', 'repeatDelay']) {
+            if (snapshot[companion] !== undefined) {
+                return new InvalidTransitionError(componentId, companion, snapshot[companion], `'${companion}' has no effect without a positive 'repeat' — an option this transition ` +
+                    'would silently ignore is refused (G-INV-8)');
+            }
+        }
+    }
+    // T21 (REQ-API-053): the repeat family's inert-companion law, applied to the stagger axis.
+    // `staggerDirection` steers a numeric stagger that must EXIST and be nonzero; a function
+    // `delayChildren` (stagger()) displaces the numeric axis entirely in the pinned runtime, so
+    // pairing it with either numeric option is dual stagger authorship (G-INV-8 — the
+    // ease-alias-pair precedent).
+    const delayChildrenValue = snapshot['delayChildren'];
+    if (typeof delayChildrenValue === 'function') {
+        for (const displaced of ['staggerChildren', 'staggerDirection']) {
+            if (snapshot[displaced] !== undefined) {
+                return new InvalidTransitionError(componentId, displaced, snapshot[displaced], `a function 'delayChildren' (stagger()) displaces '${displaced}' in the pinned ` +
+                    'runtime — authoring both is dual stagger authorship; keep exactly one ' +
+                    '(REQ-API-053)');
+            }
+        }
+    }
+    else if (snapshot['staggerDirection'] !== undefined) {
+        const staggerChildrenValue = snapshot['staggerChildren'];
+        if (typeof staggerChildrenValue !== 'number' || staggerChildrenValue === 0) {
+            return new InvalidTransitionError(componentId, 'staggerDirection', snapshot['staggerDirection'], "'staggerDirection' steers 'staggerChildren'; without a nonzero staggerChildren it is " +
+                'a silent no-op this engine refuses (REQ-API-053)');
+        }
+    }
+    // Family-2 / T20: ease, easings, and easing are exclusive aliases (G-INV-8).
+    const easeAliasKeys = ['ease', 'easings', 'easing'].filter((key) => snapshot[key] !== undefined);
+    if (easeAliasKeys.length > 1) {
+        const extra = easeAliasKeys.includes('easing') ? 'easing' : 'easings';
+        return new InvalidTransitionError(componentId, extra, snapshot[extra], `${extra} is an alias of ease — author exactly one of ease, easings, easing (REQ-API-052)`);
+    }
+    return probeDerivedConfigRefusal(snapshot, componentId);
+}
+/**
+ * Shape-only preflight for transition snapshot boundaries. This must run before a null-prototype
+ * snapshot can normalize a Date, class instance, or inherited-only record into an empty object.
+ */
+function transitionShapeRefusal(transition, opts) {
+    if (transition === undefined)
+        return null;
+    const componentId = opts?.componentId;
+    const proto = typeof transition === 'object' && transition !== null
+        ? Object.getPrototypeOf(transition)
+        : undefined;
+    if (typeof transition !== 'object' ||
+        transition === null ||
+        Array.isArray(transition) ||
+        (proto !== Object.prototype && proto !== null)) {
+        return new InvalidTransitionError(componentId, '(transition)', transition, 'a transition must be a plain object of transition options (G-INV-8 — a malformed config ' +
+            'fails loud, never coerces to the default transition)');
+    }
+    return null;
+}
+function validateTransition(transition, opts) {
+    const refusal = validateTransitionRefusal(transition, opts);
+    if (refusal !== null)
+        throw refusal;
+}
+// Sample instants for the derived-config probe: the numeric failure modes are exponential
+// (exp/cos overflow grows with t), so a spread of early-to-late instants catches what a
+// single endpoint sample cannot.
+const PROBE_SAMPLE_INSTANTS_MS = [0, 1, 16, 250, 1000];
+const SPRING_PROBE_OPTIONS = ['stiffness', 'damping', 'mass', 'bounce', 'visualDuration'];
+// The settle law's horizon (r8 3a929cbff062; refined through r13 minor 1d6f4b8a2e90):
+// single-sourced in config/constants and shared verbatim with stepProp's freeze-settle —
+// every accepted trajectory (spring AND tween) must be DONE by it.
+const PROBE_SETTLE_HORIZON_MS = constants_1.SETTLE_HORIZON_MS;
+// Motion's default tween duration when a transition names none.
+const DEFAULT_TWEEN_DURATION_MS = 300;
+/**
+ * Probe the DERIVED spring for `transition`; returns the failure reason or null. Runs the
+ * SAME conversion seams the engine runs (r7 major c814532d1b66): finite samples at a spread
+ * of instants AND bounded settle (r8 major 3a929cbff062 — a permanently-active config is not
+ * executable even when every sample is finite).
+ */
+// alloc-ok: lifecycle-edge — boundary validation constructs one probe generator per config.
+function springProbeFailure(transition, settleHorizonMs = PROBE_SETTLE_HORIZON_MS) {
+    const spring = (0, transition_1.toSpringConfig)(transition);
+    const resolved = (0, transition_2.resolveSpring)(spring);
+    if (resolved.calculatedDuration !== null && !Number.isFinite(resolved.calculatedDuration)) {
+        return 'the derived spring has a non-finite settle duration';
+    }
+    const generator = (0, transition_2.resolveSpringGenerator)(1, spring)({ from: 0, velocity: spring.velocity ?? 0 });
+    for (const at of PROBE_SAMPLE_INSTANTS_MS) {
+        const sample = generator.sample(at);
+        if (!Number.isFinite(sample.value) || !Number.isFinite(sample.velocity)) {
+            return `the derived spring emits a non-finite sample at ${at}ms`;
+        }
+    }
+    const settleAt = resolved.calculatedDuration !== null
+        ? Math.min(resolved.calculatedDuration + 1, settleHorizonMs)
+        : settleHorizonMs;
+    const settled = generator.sample(settleAt);
+    if (!Number.isFinite(settled.value) || settled.done !== true) {
+        return ('the derived spring is not done by the settle horizon (2**53 ms — the shared bound ' +
+            "stepProp's freeze-settle also lands on) — a practically-never-settling config is " +
+            'not executable');
+    }
+    return null;
+}
+/**
+ * The DERIVED-config executability law (r7 major c814532d1b66, G-INV-8): per-option
+ * sign/finiteness cannot see what the converters and generators DERIVE. On a probe failure
+ * the error LOCALIZES the offense (r8 minor 0c88b6d4e219): each present option re-probes
+ * alone and the first solo failure names itself; a pure interaction names every participant.
+ */
+// alloc-ok: lifecycle-edge — boundary validation constructs probe generators per config.
+function probeDerivedConfigRefusal(transition, componentId) {
+    const springRelevant = transition.type === 'spring' ||
+        SPRING_PROBE_OPTIONS.some((option) => transition[option] !== undefined);
+    // Family-2 / T20: every ease alias must enter the derived probe under the authored key.
+    const easeField = (0, transition_1.effectiveTransitionEase)(transition);
+    const easeKey = transition.ease !== undefined ? 'ease' : transition.easings !== undefined ? 'easings' : 'easing';
+    const tweenRelevant = transition.type === 'tween' || transition.duration !== undefined || easeField !== undefined;
+    // The seconds→ms crossing must stay finite for BOTH duration-family options (r8 major
+    // c723a65f4e8b: an Infinity delay holds a layout transition forever; -Infinity seeds an
+    // infinite elapsed clock).
+    for (const option of ['duration', 'delay']) {
+        const value = transition[option];
+        if (value !== undefined && !Number.isFinite(value * 1000)) {
+            return new InvalidTransitionError(componentId, option, value, `the seconds→ms crossing overflows to a non-finite ${option} (G-INV-8)`);
+        }
+    }
+    // A POSITIVE delay is a wall-clock hold phase (r14 major f3a91c7d5e62): the layout lane
+    // waits until delayUntil before any stepping begins, so freeze-settle cannot bound it —
+    // the hold itself must fit the settle horizon. Negative delay seeds elapsed instead (no
+    // hold; the no-rewind freeze-settle covers any seed).
+    if (transition.delay !== undefined && transition.delay * 1000 > constants_1.SETTLE_HORIZON_MS) {
+        return new InvalidTransitionError(componentId, 'delay', transition.delay, 'the hold phase exceeds the settle horizon (2**53 ms) — a practically-never-starting ' +
+            'config is not executable (G-INV-8)');
+    }
+    if (springRelevant) {
+        const positiveDelayMs = transition.delay !== undefined && transition.delay > 0 ? transition.delay * 1000 : 0;
+        const failure = springProbeFailure(transition, PROBE_SETTLE_HORIZON_MS - positiveDelayMs);
+        if (failure !== null) {
+            // A delayed spring must finish in the time remaining after its hold phase. Distinguish that
+            // combined failure from an intrinsically non-settling spring so the boundary names delay and
+            // does not let stepProp freeze a mid-flight sample at the shared horizon (review major n4wse8).
+            if (positiveDelayMs > 0 && springProbeFailure(transition, PROBE_SETTLE_HORIZON_MS) === null) {
+                return new InvalidTransitionError(componentId, 'delay', transition.delay, 'the positive delay plus the spring exceeds the settle horizon (2**53 ms) — ' +
+                    'the animation cannot complete before the shared freeze-settle bound (G-INV-8)');
+            }
+            // U7c (REQ-SPRING-014): restDelta/restSpeed join the localization list (NOT
+            // SPRING_PROBE_OPTIONS — a tween carrying them must never trigger the spring probe; the
+            // pin ignores them outside the spring generator). A negative threshold's never-settling
+            // spring names itself here.
+            const present = [
+                ...SPRING_PROBE_OPTIONS,
+                'velocity',
+                'restDelta',
+                'restSpeed',
+            ].filter((option) => transition[option] !== undefined);
+            for (const option of present) {
+                const solo = { type: 'spring', [option]: transition[option] };
+                if (springProbeFailure(solo) !== null) {
+                    return new InvalidTransitionError(componentId, option, transition[option], `${failure} (G-INV-8)`);
+                }
+            }
+            // No option fails alone: the INTERACTION is the offense — name every participant.
+            const participants = present
+                .map((option) => `${option} = ${String(transition[option])}`)
+                .join(', ');
+            return new InvalidTransitionError(componentId, '(transition)', Object.fromEntries(present.map((option) => [option, transition[option]])), `${failure}; the interaction of ${participants} is the offense (G-INV-8)`);
+        }
+    }
+    if (tweenRelevant) {
+        const durationMs = transition.duration !== undefined ? transition.duration * 1000 : DEFAULT_TWEEN_DURATION_MS;
+        // The settle law binds tweens too (r13 major 7f1c9e2a4b60): stepProp's freeze-settle
+        // lands on the shared horizon, so a tween still mid-flight there would commit a
+        // mid-flight sample as its terminal value — refuse it at the boundary instead.
+        if (durationMs > constants_1.SETTLE_HORIZON_MS) {
+            return new InvalidTransitionError(componentId, 'duration', transition.duration, 'the derived tween is not done by the settle horizon (2**53 ms) — a ' +
+                'practically-never-settling config is not executable (G-INV-8)');
+        }
+        const positiveDelayMs = transition.delay !== undefined && transition.delay > 0 ? transition.delay * 1000 : 0;
+        if (positiveDelayMs > constants_1.SETTLE_HORIZON_MS - durationMs) {
+            return new InvalidTransitionError(componentId, 'delay', transition.delay, 'the positive delay plus the tween exceeds the settle horizon (2**53 ms) — ' +
+                'the animation cannot complete before the shared freeze-settle bound (G-INV-8)');
+        }
+        // Per-segment ease lists never enter the scalar tween path (`toTimingConfig` drops them).
+        // Probe each segment curve directly so finite-but-non-executable cubics fail loud (i73cik).
+        if (easeField !== undefined && (0, timing_1.isEasingList)(easeField)) {
+            for (const segment of easeField) {
+                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 new InvalidTransitionError(componentId, easeKey, easeField, `the derived per-segment ${easeKey} emits a non-finite sample at progress ${progress} — this ` +
+                            'config is not executable (G-INV-8)');
+                    }
+                }
+            }
+        }
+        else {
+            const timing = (0, transition_1.toTimingConfig)(transition);
+            const generator = (0, timing_1.timingGenerator)(1, timing)({ from: 0, velocity: 0 });
+            for (const fraction of [0, 0.25, 0.5, 0.75, 1]) {
+                const sample = generator.sample(durationMs * fraction);
+                if (!Number.isFinite(sample.value)) {
+                    return new InvalidTransitionError(componentId, easeKey, easeField, `the derived tween emits a non-finite sample at ${fraction} of the duration — this ` +
+                        'config is not executable (G-INV-8)');
+                }
+            }
+        }
+    }
+    // T18-a L3, moved here from the driver (fix-up review MAJOR). The fold's two degenerate bases —
+    // a zero-length play, and a base still moving past the pin's 20s measuring window — were refused
+    // only inside `buildRepeatedGenerator`, i.e. at animate time. That is too late for two reasons:
+    // the failure arrives as a bare driver-lane Error rather than a typed InvalidTransitionError
+    // naming the property, and the parity classifier (which asks THIS function whether a config is
+    // executable) certified those configs as shipped surface while the runtime refused them. Both
+    // are decidable from the authored transition, so they are decided here. The driver keeps its own
+    // check as the defence-in-depth backstop for command shapes that never pass through validation.
+    //
+    // transition-default-selection F5 (packet §2): the zero-length arm is RETIRED. Its only producer
+    // was an authored `duration: 0`, and the pin handles that bag without any fold
+    // (`makeAnimationInstant`, motion-dom@12.42.2 motion-value.ts:89-98): without a repeatDelay it
+    // INSTANTS — type-independently — so the whole repeat arm is skipped by the gate below; with a
+    // repeatDelay the pin totals the delay gaps around zero-length plays and the fold executes.
+    // What was a recorded approximation (refuse-loud) is amended under the fidelity presumption; the
+    // fold's own `repeatIterationRefusal` remains the backstop for the shape that still cannot run
+    // (zero-length plays with nothing separating them — unreachable from an authored bag, which
+    // instants instead).
+    if (transition.repeat !== undefined &&
+        transition.repeat > 0 &&
+        !(0, transition_1.isDurationZeroInstantTransition)(transition)) {
+        // This function sees a TRANSITION and no TARGET, and the drivers' measurement lane depends on
+        // both — a keyframe-array target is played by the keyframes generator unless the transition
+        // explicitly asked for a spring. So the same transition can legitimately measure zero (refused)
+        // against an array target and non-zero (executed) against a numeric one, and NO answer computed
+        // from the transition alone is right for both.
+        //
+        // That is the same shape as the never-settling arm, and it takes the same resolution: validation
+        // refuses only what is refused for EVERY target shape, and the driver — which holds the target —
+        // owns the rest. Four review rounds were spent re-deriving a lane rule instead; the rule now
+        // lives once in core (`iterationMeasurementLane`) and is evaluated here for both shapes.
+        const iterationByLane = (targetIsNumeric) => {
+            switch ((0, repeat_1.iterationMeasurementLane)(targetIsNumeric, transition.type === 'spring', 
+            // REQ-TIMING-006 + F6: an untyped timing-lane bag (duration-only OR ease-only) rides the
+            // timing lane, same as the drivers.
+            transition.type === 'tween' || (0, transition_1.isTimingLaneTransition)(transition))) {
+                case 'keyframes':
+                    return (0, transition_1.toKeyframesConfig)(transition).duration ?? null;
+                case 'timing':
+                    return (0, transition_1.toTimingConfig)(transition).duration ?? null;
+                case 'spring':
+                    return (0, transition_2.resolveSpring)((0, transition_1.toSpringConfig)(transition)).calculatedDuration;
+            }
+        };
+        // `null` is "only the driver's scan can measure this", never "zero" — so a lane that cannot be
+        // measured here can never contribute to a refusal.
+        const numericLaneMs = iterationByLane(true);
+        const arrayLaneMs = iterationByLane(false);
+        // F5: a lane measuring ZERO is exactly an authored `duration: 0` (the spring lane clamps to a
+        // live 10ms rather than resolving zero). The instant gate above already routed the
+        // no-repeatDelay form out of this arm; the repeatDelay form reaches here and EXECUTES — the
+        // pin totals the delay gaps around the zero-length plays — so there is no zero-length refusal
+        // left for validation to own.
+        // `duration`, `delay` and `repeatDelay` are each bound to the settle horizon; `repeat` is the
+        // MULTIPLIER that produces `totalDuration` and was not (review MAJOR). A FINITE repeat past the
+        // horizon never completes — `onAnimationComplete` never fires, `whenSettled()` never resolves,
+        // and `stepProp`'s precision freeze commits a value short of the target. An ENDLESS repeat is
+        // exempt: never settling is its design, not an overflow.
+        if (Number.isFinite(transition.repeat)) {
+            // The floor must be the SHORTEST iteration this transition could possibly run — across BOTH
+            // target shapes, since the lane changes with the target — or it refuses animations that would
+            // have completed. Per lane:
+            //
+            //   measured here (`timing`/`keyframes` duration, or a DURATION-resolved spring's
+            //     `calculatedDuration`)  exact and distance-independent, so use it. A duration-resolved
+            //     spring can be well under a scan step (`duration: 0.01` resolves to 10ms), which is why
+            //     flooring it at the scan step over-refused (review MINOR).
+            //   scan-measured (a PHYSICS or `visualDuration` spring, both of which resolve
+            //     `calculatedDuration === null`)  the length depends on the distance, which this function
+            //     cannot see. The scan reports a multiple of its step, so among iterations that EXECUTE at
+            //     all one step is the shortest that exists.
+            //   absent duration on a `timing`/`keyframes` lane  both generators default to 300ms.
+            //
+            // The floor is therefore sound in the never-over-refuse direction, and deliberately partial in
+            // the other: a scan-measured spring whose real iteration is far longer than one step can still
+            // carry a repeat count that overflows the horizon and be accepted here. The driver is where
+            // that becomes observable, and it is the same reason the never-settles arm lives there.
+            // A lane measuring ZERO is an authored `duration: 0` (the spring lane clamps to a live 10ms,
+            // never zero). Post-F5 that bag EXECUTES: without a repeatDelay it instants (the gate above
+            // keeps it out of this arm entirely); with one the pin totals the delay gaps around
+            // zero-length plays, so 0 IS the exact, distance-independent floor. Adopting it is no longer
+            // the round-5 MAJOR — that bug adopted a zero floor for a clamped 10ms spring lane and so
+            // zeroed a REAL total; here the zero-length plays genuinely total only their repeatDelay
+            // gaps, and the horizon check stays live on the delay term.
+            const laneFloorMs = (laneMs, targetIsNumeric) => {
+                if (laneMs !== null && laneMs > 0)
+                    return laneMs;
+                if (laneMs === 0)
+                    return 0;
+                // `null` = this lane is scan-measured, or carries no authored duration.
+                return (0, repeat_1.iterationMeasurementLane)(targetIsNumeric, transition.type === 'spring', transition.type === 'tween' || (0, transition_1.isTimingLaneTransition)(transition)) === 'spring'
+                    ? repeat_1.ITERATION_SCAN_STEP_MS
+                    : DEFAULT_TWEEN_DURATION_MS;
+            };
+            const executableLaneFloorsMs = [
+                laneFloorMs(numericLaneMs, true),
+                laneFloorMs(arrayLaneMs, false),
+            ].filter((laneMs) => laneMs !== null);
+            // `laneFloorMs` is total (every lane yields a floor), so an empty list is unreachable; the
+            // assert stays rather than a default because the obvious default is `0`, and adopting `0`
+            // blindly is precisely the round-5 MAJOR — it zeroes the fold total and switches the horizon
+            // check off. The zero floor is lawful ONLY through the F5 duration-zero lane above; a silent
+            // fallback here would reconstitute that bug the moment either arm's condition drifted.
+            if (executableLaneFloorsMs.length === 0) {
+                throw new Error('native-motion internal invariant: the settle-horizon arm reached a fold with no ' +
+                    'executable lane. Refusing to ' +
+                    'default the iteration to 0 — that would disable the horizon check (G-INV-8).');
+            }
+            const iterationDurationMs = Math.min(...executableLaneFloorsMs);
+            const { totalDurationMs } = (0, repeat_1.repeatFoldGeometry)({
+                repeat: transition.repeat,
+                repeatDelayMs: transition.repeatDelay !== undefined ? transition.repeatDelay * 1000 : 0,
+                iterationDurationMs,
+            });
+            if (totalDurationMs > constants_1.SETTLE_HORIZON_MS) {
+                return new InvalidTransitionError(componentId, 'repeat', transition.repeat, 'the repeated animation cannot finish before the settle horizon (2**53 ms) — a finite ' +
+                    "repeat that never completes silently acquires the endless repeat's never-settles " +
+                    'semantics, which is not what `repeat` asked for. Use `repeat: Infinity` if the ' +
+                    'animation is meant to run forever (G-INV-8)');
+            }
+            const positiveDelayMs = transition.delay !== undefined && transition.delay > 0 ? transition.delay * 1000 : 0;
+            if (positiveDelayMs > constants_1.SETTLE_HORIZON_MS - totalDurationMs) {
+                return new InvalidTransitionError(componentId, 'delay', transition.delay, 'the positive delay plus the repeated animation exceeds the settle horizon (2**53 ms) — ' +
+                    'a finite repeat cannot complete before the shared freeze-settle bound (G-INV-8)');
+            }
+        }
+    }
+    return null;
+}