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

package/dist/component/index.cjs

@@ -0,0 +1,57 @@
+"use strict";
+// Public surface of the SPEC-COMPONENT subsystem: the declarative Motion.View API contract. Host-agnostic
+// (REQ-CORE-003) — the native runtime, the web shim, and the conformance runner all consume this one
+// module. Re-exported additively from the core index. The end-state types land first (Milestone 1); the
+// loud-fail `validateTarget` (Milestone 2) and the partial-overlay `resolveTarget` (Milestone 3) join this
+// surface as they land.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTarget = exports.resolveStartValue = exports.hostBaseValue = exports.DiscreteHostBaseError = exports.variantsShapeRefusal = exports.validateVariantEntrySnapshot = exports.validateVariantEntry = exports.resolveVariantDefinition = exports.resolveInitialOverlay = exports.InvalidVariantError = exports.flattenVariantApplications = exports.assertVariantsShape = exports.validateTransitionRefusal = exports.validateTransition = exports.validateTargetSnapshot = exports.validateTargetRefusal = exports.validateTarget = exports.targetShapeRefusal = exports.InvalidTransitionError = exports.InvalidTargetError = exports.assertTargetShape = exports.toRepeatFoldOptions = exports.toKeyframesConfig = exports.toTimingConfig = exports.toSpringConfig = exports.toDelayMs = exports.stagger = exports.resolveOrchestrationEpisode = exports.resolveChildOrchestrationDelay = exports.TRANSITION_OPTION_KEYS = exports.TARGET_PROPERTY_KEYS = exports.ORCHESTRATION_OPTION_KEYS = void 0;
+var types_1 = require("./types.cjs");
+Object.defineProperty(exports, "ORCHESTRATION_OPTION_KEYS", { enumerable: true, get: function () { return types_1.ORCHESTRATION_OPTION_KEYS; } });
+Object.defineProperty(exports, "TARGET_PROPERTY_KEYS", { enumerable: true, get: function () { return types_1.TARGET_PROPERTY_KEYS; } });
+Object.defineProperty(exports, "TRANSITION_OPTION_KEYS", { enumerable: true, get: function () { return types_1.TRANSITION_OPTION_KEYS; } });
+// T21 (REQ-API-053): variant orchestration — the public stagger() helper the catalog imports,
+// plus the tree-lane per-child delay resolver the native controller and web shim consume.
+var orchestration_1 = require("./orchestration.cjs");
+Object.defineProperty(exports, "resolveChildOrchestrationDelay", { enumerable: true, get: function () { return orchestration_1.resolveChildOrchestrationDelay; } });
+Object.defineProperty(exports, "resolveOrchestrationEpisode", { enumerable: true, get: function () { return orchestration_1.resolveOrchestrationEpisode; } });
+Object.defineProperty(exports, "stagger", { enumerable: true, get: function () { return orchestration_1.stagger; } });
+// Transition unit boundary (REQ-API-001): convert the public seconds-based Transition to the internal
+// millisecond SPRING/TIMING resolver configs. The single seconds↔ms crossing — no internal unit leaks.
+// Family-2 host helpers (effectiveTransitionEase / normalizeTransitionEaseAlias) are NOT public —
+// they ride `internal-driver` (implementation seam; 00i0nt public-surface).
+var transition_1 = require("./transition.cjs");
+Object.defineProperty(exports, "toDelayMs", { enumerable: true, get: function () { return transition_1.toDelayMs; } });
+Object.defineProperty(exports, "toSpringConfig", { enumerable: true, get: function () { return transition_1.toSpringConfig; } });
+Object.defineProperty(exports, "toTimingConfig", { enumerable: true, get: function () { return transition_1.toTimingConfig; } });
+Object.defineProperty(exports, "toKeyframesConfig", { enumerable: true, get: function () { return transition_1.toKeyframesConfig; } });
+Object.defineProperty(exports, "toRepeatFoldOptions", { enumerable: true, get: function () { return transition_1.toRepeatFoldOptions; } });
+// Loud-fail runtime validator (REQ-API-013/014/016): the fail-closed backstop for what the Target type
+// cannot catch (units, ranges, untyped callers), with descriptive component-scoped errors.
+var validate_1 = require("./validate.cjs");
+Object.defineProperty(exports, "assertTargetShape", { enumerable: true, get: function () { return validate_1.assertTargetShape; } });
+Object.defineProperty(exports, "InvalidTargetError", { enumerable: true, get: function () { return validate_1.InvalidTargetError; } });
+Object.defineProperty(exports, "InvalidTransitionError", { enumerable: true, get: function () { return validate_1.InvalidTransitionError; } });
+Object.defineProperty(exports, "targetShapeRefusal", { enumerable: true, get: function () { return validate_1.targetShapeRefusal; } });
+Object.defineProperty(exports, "validateTarget", { enumerable: true, get: function () { return validate_1.validateTarget; } });
+Object.defineProperty(exports, "validateTargetRefusal", { enumerable: true, get: function () { return validate_1.validateTargetRefusal; } });
+Object.defineProperty(exports, "validateTargetSnapshot", { enumerable: true, get: function () { return validate_1.validateTargetSnapshot; } });
+Object.defineProperty(exports, "validateTransition", { enumerable: true, get: function () { return validate_1.validateTransition; } });
+Object.defineProperty(exports, "validateTransitionRefusal", { enumerable: true, get: function () { return validate_1.validateTransitionRefusal; } });
+var variants_1 = require("./variants.cjs");
+Object.defineProperty(exports, "assertVariantsShape", { enumerable: true, get: function () { return variants_1.assertVariantsShape; } });
+Object.defineProperty(exports, "flattenVariantApplications", { enumerable: true, get: function () { return variants_1.flattenVariantApplications; } });
+Object.defineProperty(exports, "InvalidVariantError", { enumerable: true, get: function () { return variants_1.InvalidVariantError; } });
+Object.defineProperty(exports, "resolveInitialOverlay", { enumerable: true, get: function () { return variants_1.resolveInitialOverlay; } });
+Object.defineProperty(exports, "resolveVariantDefinition", { enumerable: true, get: function () { return variants_1.resolveVariantDefinition; } });
+Object.defineProperty(exports, "validateVariantEntry", { enumerable: true, get: function () { return variants_1.validateVariantEntry; } });
+Object.defineProperty(exports, "validateVariantEntrySnapshot", { enumerable: true, get: function () { return variants_1.validateVariantEntrySnapshot; } });
+Object.defineProperty(exports, "variantsShapeRefusal", { enumerable: true, get: function () { return variants_1.variantsShapeRefusal; } });
+// Pure target-merge + base-resolution (REQ-API-002/010/011/012/017): resolveTarget overlays a partial
+// target onto the live value set (hold, never reset); resolveStartValue/hostBaseValue resolve a first-seen
+// property's starting value from the resolved style, else the documented host base. Deterministic seam.
+var resolve_1 = require("./resolve.cjs");
+Object.defineProperty(exports, "DiscreteHostBaseError", { enumerable: true, get: function () { return resolve_1.DiscreteHostBaseError; } });
+Object.defineProperty(exports, "hostBaseValue", { enumerable: true, get: function () { return resolve_1.hostBaseValue; } });
+Object.defineProperty(exports, "resolveStartValue", { enumerable: true, get: function () { return resolve_1.resolveStartValue; } });
+Object.defineProperty(exports, "resolveTarget", { enumerable: true, get: function () { return resolve_1.resolveTarget; } });

package/dist/component/index.d.cts

@@ -0,0 +1,12 @@
+export type { MotionTargetProps, Target, TargetPropertyKey, Transition, TransitionMapKey, TransitionOptionBag, TransitionType, VariantLabels, } from "./types.cjs";
+export { ORCHESTRATION_OPTION_KEYS, TARGET_PROPERTY_KEYS, TRANSITION_OPTION_KEYS } from "./types.cjs";
+export { resolveChildOrchestrationDelay, resolveOrchestrationEpisode, stagger, } from "./orchestration.cjs";
+export type { ChildOrchestrationInput, DynamicDelay, OrchestrationEpisode, OrchestrationEpisodeInput, StaggerEase, StaggerOptions, StaggerOrigin, } from "./orchestration.cjs";
+export { toDelayMs, toSpringConfig, toTimingConfig, toKeyframesConfig, toRepeatFoldOptions, } from "./transition.cjs";
+export type { RepeatFoldOptions } from "./transition.cjs";
+export { assertTargetShape, InvalidTargetError, InvalidTransitionError, targetShapeRefusal, validateTarget, validateTargetRefusal, validateTargetSnapshot, validateTransition, validateTransitionRefusal, } from "./validate.cjs";
+export { assertVariantsShape, flattenVariantApplications, InvalidVariantError, resolveInitialOverlay, resolveVariantDefinition, validateVariantEntry, validateVariantEntrySnapshot, variantsShapeRefusal, } from "./variants.cjs";
+export type { FlattenedVariantApplications, VariantApplication, VariantEntry, VariantResolutionContext, VariantResolver, VariantsDictionary, } from "./variants.cjs";
+export type { ValidateTargetOptions } from "./validate.cjs";
+export { DiscreteHostBaseError, hostBaseValue, resolveStartValue, resolveTarget } from "./resolve.cjs";
+export type { ResolvedTargetValue, ResolvedValue, StartResolution } from "./resolve.cjs";

package/dist/component/index.d.ts

@@ -0,0 +1,12 @@
+export type { MotionTargetProps, Target, TargetPropertyKey, Transition, TransitionMapKey, TransitionOptionBag, TransitionType, VariantLabels, } from "./types.js";
+export { ORCHESTRATION_OPTION_KEYS, TARGET_PROPERTY_KEYS, TRANSITION_OPTION_KEYS } from "./types.js";
+export { resolveChildOrchestrationDelay, resolveOrchestrationEpisode, stagger, } from "./orchestration.js";
+export type { ChildOrchestrationInput, DynamicDelay, OrchestrationEpisode, OrchestrationEpisodeInput, StaggerEase, StaggerOptions, StaggerOrigin, } from "./orchestration.js";
+export { toDelayMs, toSpringConfig, toTimingConfig, toKeyframesConfig, toRepeatFoldOptions, } from "./transition.js";
+export type { RepeatFoldOptions } from "./transition.js";
+export { assertTargetShape, InvalidTargetError, InvalidTransitionError, targetShapeRefusal, validateTarget, validateTargetRefusal, validateTargetSnapshot, validateTransition, validateTransitionRefusal, } from "./validate.js";
+export { assertVariantsShape, flattenVariantApplications, InvalidVariantError, resolveInitialOverlay, resolveVariantDefinition, validateVariantEntry, validateVariantEntrySnapshot, variantsShapeRefusal, } from "./variants.js";
+export type { FlattenedVariantApplications, VariantApplication, VariantEntry, VariantResolutionContext, VariantResolver, VariantsDictionary, } from "./variants.js";
+export type { ValidateTargetOptions } from "./validate.js";
+export { DiscreteHostBaseError, hostBaseValue, resolveStartValue, resolveTarget } from "./resolve.js";
+export type { ResolvedTargetValue, ResolvedValue, StartResolution } from "./resolve.js";

package/dist/component/index.js

@@ -0,0 +1,22 @@
+// Public surface of the SPEC-COMPONENT subsystem: the declarative Motion.View API contract. Host-agnostic
+// (REQ-CORE-003) — the native runtime, the web shim, and the conformance runner all consume this one
+// module. Re-exported additively from the core index. The end-state types land first (Milestone 1); the
+// loud-fail `validateTarget` (Milestone 2) and the partial-overlay `resolveTarget` (Milestone 3) join this
+// surface as they land.
+export { ORCHESTRATION_OPTION_KEYS, TARGET_PROPERTY_KEYS, TRANSITION_OPTION_KEYS } from "./types.js";
+// T21 (REQ-API-053): variant orchestration — the public stagger() helper the catalog imports,
+// plus the tree-lane per-child delay resolver the native controller and web shim consume.
+export { resolveChildOrchestrationDelay, resolveOrchestrationEpisode, stagger, } from "./orchestration.js";
+// Transition unit boundary (REQ-API-001): convert the public seconds-based Transition to the internal
+// millisecond SPRING/TIMING resolver configs. The single seconds↔ms crossing — no internal unit leaks.
+// Family-2 host helpers (effectiveTransitionEase / normalizeTransitionEaseAlias) are NOT public —
+// they ride `internal-driver` (implementation seam; 00i0nt public-surface).
+export { toDelayMs, toSpringConfig, toTimingConfig, toKeyframesConfig, toRepeatFoldOptions, } from "./transition.js";
+// Loud-fail runtime validator (REQ-API-013/014/016): the fail-closed backstop for what the Target type
+// cannot catch (units, ranges, untyped callers), with descriptive component-scoped errors.
+export { assertTargetShape, InvalidTargetError, InvalidTransitionError, targetShapeRefusal, validateTarget, validateTargetRefusal, validateTargetSnapshot, validateTransition, validateTransitionRefusal, } from "./validate.js";
+export { assertVariantsShape, flattenVariantApplications, InvalidVariantError, resolveInitialOverlay, resolveVariantDefinition, validateVariantEntry, validateVariantEntrySnapshot, variantsShapeRefusal, } from "./variants.js";
+// Pure target-merge + base-resolution (REQ-API-002/010/011/012/017): resolveTarget overlays a partial
+// target onto the live value set (hold, never reset); resolveStartValue/hostBaseValue resolve a first-seen
+// property's starting value from the resolved style, else the documented host base. Deterministic seam.
+export { DiscreteHostBaseError, hostBaseValue, resolveStartValue, resolveTarget } from "./resolve.js";

package/dist/component/orchestration.cjs

@@ -0,0 +1,129 @@
+"use strict";
+// SPEC-COMPONENT §2 — variant orchestration math (REQ-API-053, T21). The pure tree-lane layer
+// under `delayChildren` / `staggerChildren` / `staggerDirection`: `stagger()` (the public
+// authoring helper the catalog imports from the package root) and the per-child delay resolver
+// replicating the pinned composition (motion-dom@12.42.2 `visual-element-variant.ts:92-103` +
+// `calc-child-stagger.ts` + `utils/stagger.ts`), golden-pinned per sample in
+// `orchestration.test.ts`. Host-agnostic (REQ-CORE-003) — relative imports only. Orchestration
+// never crosses to the UI runtime: this runs on the JS thread at start-scheduling time, so plain
+// function values (a `stagger()` result) are legal here — and ONLY here (the transition
+// converters strip the family, so no function ever reaches a driver or a worklet crossing).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stagger = stagger;
+exports.resolveChildOrchestrationDelay = resolveChildOrchestrationDelay;
+exports.resolveOrchestrationEpisode = resolveOrchestrationEpisode;
+const timing_1 = require("../timing.cjs");
+const validate_1 = require("./validate.cjs");
+// The pin's getOriginIndex (utils/stagger.ts): 'first' → 0, 'last' → total − 1,
+// 'center' → (total − 1) / 2. A numeric origin is used as-is by the caller.
+function staggerOriginIndex(from, total) {
+    if (from === 'first')
+        return 0;
+    const lastIndex = total - 1;
+    return from === 'last' ? lastIndex : lastIndex / 2;
+}
+/**
+ * The public stagger() helper (REQ-API-053) — pin-verbatim math: delay = duration × |origin − i|,
+ * optionally warped by `ease` over maxDelay = total × duration, plus `startDelay`. Seconds, like
+ * every public time. Malformed inputs fail loud at FACTORY time (G-INV-8) — the pin silently
+ * emits NaN delays instead, a misauthoring this engine refuses.
+ */
+function stagger(duration = 0.1, options = {}) {
+    if (typeof duration !== 'number' || !Number.isFinite(duration)) {
+        throw new Error(`stagger: duration must be a finite number of seconds, got ${String(duration)} (REQ-API-053)`);
+    }
+    const { startDelay = 0, from = 0, ease } = options;
+    if (typeof startDelay !== 'number' || !Number.isFinite(startDelay)) {
+        throw new Error(`stagger: startDelay must be a finite number of seconds, got ${String(startDelay)} (REQ-API-053)`);
+    }
+    const validOrigin = from === 'first' ||
+        from === 'last' ||
+        from === 'center' ||
+        (typeof from === 'number' && Number.isFinite(from));
+    if (!validOrigin) {
+        throw new Error(`stagger: from must be 'first', 'last', 'center', or a finite index, got ${String(from)} (REQ-API-053)`);
+    }
+    // Resolve the easing EAGERLY so an unknown named curve or malformed bezier throws at the
+    // authoring site, not on the first child start. resolveEasing owns that refusal.
+    const easingFunction = ease === undefined ? undefined : typeof ease === 'function' ? ease : (0, timing_1.resolveEasing)(ease);
+    return (index, total) => {
+        const fromIndex = typeof from === 'number' ? from : staggerOriginIndex(from, total);
+        const distance = Math.abs(fromIndex - index);
+        let delay = duration * distance;
+        if (easingFunction !== undefined) {
+            const maxDelay = total * duration;
+            delay = easingFunction(delay / maxDelay) * maxDelay;
+        }
+        return startDelay + delay;
+    };
+}
+/**
+ * Per-child start delay, exactly the pinned composition (visual-element-variant.ts:92-103):
+ * forwarded + (function delayChildren ? 0 : numeric delayChildren) + stagger term, where a
+ * FUNCTION delayChildren displaces staggerChildren/staggerDirection entirely and the numeric
+ * term is index × staggerChildren (direction 1) or (total − 1) × staggerChildren − index ×
+ * staggerChildren (direction −1). Operation order is preserved for float-exact golden parity.
+ */
+function resolveChildOrchestrationDelay(input) {
+    const { forwardedDelay, delayChildren, staggerChildren = 0, staggerDirection = 1, index, total, } = input;
+    if (!Number.isInteger(index) ||
+        !Number.isInteger(total) ||
+        total < 1 ||
+        index < 0 ||
+        index >= total) {
+        // Callers derive (index, total) from the live child registry; an out-of-range pair is the
+        // registry's bookkeeping broken — fail loud, never emit a silently-wrong delay.
+        throw new Error(`resolveChildOrchestrationDelay: index ${String(index)} outside [0, ${String(total)}) — ` +
+            'the variant child registry is inconsistent (internal invariant, REQ-API-053)');
+    }
+    const delayIsFunction = typeof delayChildren === 'function';
+    const staggerTerm = delayIsFunction
+        ? executeDynamicDelay(delayChildren, index, total)
+        : staggerDirection === 1
+            ? index * staggerChildren
+            : (total - 1) * staggerChildren - index * staggerChildren;
+    return forwardedDelay + (delayIsFunction ? 0 : (delayChildren ?? 0)) + staggerTerm;
+}
+// The DynamicDelay EXECUTION boundary (review r1 major 6): validate admits arbitrary functions,
+// so the call itself is where user input can misbehave. Both failure shapes surface as the same
+// typed class the validation boundary throws, so the host severity seam catches them under the
+// one policy (development throws; production reports and refuses the property). The pin emits
+// NaN delays here; this engine refuses (G-INV-8).
+function executeDynamicDelay(delayChildren, index, total) {
+    let result;
+    try {
+        result = delayChildren(index, total);
+    }
+    catch (error) {
+        throw new validate_1.InvalidTransitionError(undefined, 'delayChildren', delayChildren, `the dynamic delay callback threw at (index ${String(index)}, total ${String(total)}): ` +
+            `${String(error)} (REQ-API-053)`);
+    }
+    if (typeof result !== 'number' || !Number.isFinite(result)) {
+        throw new validate_1.InvalidTransitionError(undefined, 'delayChildren', result, `the dynamic delay callback must return finite seconds, got ${String(result)} at ` +
+            `(index ${String(index)}, total ${String(total)}) (REQ-API-053)`);
+    }
+    return result;
+}
+/**
+ * Resolve a parent's tree-level transition bag into the episode its direct children compose
+ * against (pin: visual-element-variant.ts:71-103). Two laws beyond extraction: what forwards
+ * to children is `nodeStartDelay` — the delay THIS node's own start was computed with (its
+ * orchestration-computed delay from its own parent; 0 at a controlling root) — never the
+ * bag's authored `delay`, which rides only the node's own values (F4); and a truthy `when`
+ * SEQUENCES own-values vs children with the sequenced branch passing `delay: 0` to
+ * `animateChildren` (the no-arg call), while `delayChildren`/stagger apply in both branches.
+ */
+function resolveOrchestrationEpisode(bag, nodeStartDelay = 0) {
+    if (!Number.isFinite(nodeStartDelay)) {
+        throw new Error(`resolveOrchestrationEpisode: nodeStartDelay must be finite seconds, got ${String(nodeStartDelay)} ` +
+            '— the caller cascades its own computed start delay (internal invariant, REQ-API-053)');
+    }
+    const when = bag.when ?? false;
+    return {
+        forwardedDelay: when === false ? nodeStartDelay : 0,
+        delayChildren: bag.delayChildren,
+        staggerChildren: bag.staggerChildren,
+        staggerDirection: bag.staggerDirection,
+        when,
+    };
+}

package/dist/component/orchestration.d.cts

@@ -0,0 +1,66 @@
+import { type Easing } from "../timing.cjs";
+export type StaggerOrigin = 'first' | 'last' | 'center' | number;
+/** (index, total) → seconds. The public `delayChildren` function form — what `stagger()` returns. */
+export type DynamicDelay = (index: number, total: number) => number;
+export type StaggerEase = Easing | ((progress: number) => number);
+export interface StaggerOptions {
+    readonly startDelay?: number;
+    readonly from?: StaggerOrigin;
+    readonly ease?: StaggerEase;
+}
+/**
+ * The public stagger() helper (REQ-API-053) — pin-verbatim math: delay = duration × |origin − i|,
+ * optionally warped by `ease` over maxDelay = total × duration, plus `startDelay`. Seconds, like
+ * every public time. Malformed inputs fail loud at FACTORY time (G-INV-8) — the pin silently
+ * emits NaN delays instead, a misauthoring this engine refuses.
+ */
+export declare function stagger(duration?: number, options?: StaggerOptions): DynamicDelay;
+export interface ChildOrchestrationInput {
+    /** The pin's `animateChildren` forwarded delay: `options.delay` on the parallel branch, 0 on a `when`-sequenced branch. */
+    readonly forwardedDelay: number;
+    readonly delayChildren?: number | DynamicDelay | undefined;
+    readonly staggerChildren?: number | undefined;
+    readonly staggerDirection?: number | undefined;
+    /** Position among the parent's DIRECT variant children in tree order (native authority: mount registration order — packet L3). */
+    readonly index: number;
+    readonly total: number;
+}
+/**
+ * Per-child start delay, exactly the pinned composition (visual-element-variant.ts:92-103):
+ * forwarded + (function delayChildren ? 0 : numeric delayChildren) + stagger term, where a
+ * FUNCTION delayChildren displaces staggerChildren/staggerDirection entirely and the numeric
+ * term is index × staggerChildren (direction 1) or (total − 1) × staggerChildren − index ×
+ * staggerChildren (direction −1). Operation order is preserved for float-exact golden parity.
+ */
+export declare function resolveChildOrchestrationDelay(input: ChildOrchestrationInput): number;
+/**
+ * One orchestration EPISODE as the parent's direct children consume it (T21, REQ-API-053): the
+ * four tree-lane options plus the delay the parent forwards. Built per label edge from the
+ * parent's RESOLVED variant transition by `resolveOrchestrationEpisode`.
+ */
+export interface OrchestrationEpisode {
+    /** What `animateChildren` receives as `delay`: the node's CASCADED start delay in the
+     * parallel branch (the pin forwards `options.delay` — the delay this node's own start was
+     * computed with, NOT its authored transition `delay`), 0 when `when` sequences (the pin's
+     * no-arg `getChildAnimations()` call — packet law 3; corrected by F4). */
+    readonly forwardedDelay: number;
+    readonly delayChildren?: number | DynamicDelay | undefined;
+    readonly staggerChildren?: number | undefined;
+    readonly staggerDirection?: number | undefined;
+    /** Normalized: absent authoring reads as `false` (parallel). */
+    readonly when: false | 'beforeChildren' | 'afterChildren';
+}
+/** The orchestration-relevant slice of a resolved tree-level transition bag. The authored
+ * `delay` is deliberately NOT here — it rides the node's OWN values only (the pin's
+ * getValueTransition), never the children (F4). */
+export type OrchestrationEpisodeInput = Pick<import('./types').TransitionOptionBag, 'when' | 'delayChildren' | 'staggerChildren' | 'staggerDirection'>;
+/**
+ * Resolve a parent's tree-level transition bag into the episode its direct children compose
+ * against (pin: visual-element-variant.ts:71-103). Two laws beyond extraction: what forwards
+ * to children is `nodeStartDelay` — the delay THIS node's own start was computed with (its
+ * orchestration-computed delay from its own parent; 0 at a controlling root) — never the
+ * bag's authored `delay`, which rides only the node's own values (F4); and a truthy `when`
+ * SEQUENCES own-values vs children with the sequenced branch passing `delay: 0` to
+ * `animateChildren` (the no-arg call), while `delayChildren`/stagger apply in both branches.
+ */
+export declare function resolveOrchestrationEpisode(bag: OrchestrationEpisodeInput, nodeStartDelay?: number): OrchestrationEpisode;

package/dist/component/orchestration.d.ts

@@ -0,0 +1,66 @@
+import { type Easing } from "../timing.js";
+export type StaggerOrigin = 'first' | 'last' | 'center' | number;
+/** (index, total) → seconds. The public `delayChildren` function form — what `stagger()` returns. */
+export type DynamicDelay = (index: number, total: number) => number;
+export type StaggerEase = Easing | ((progress: number) => number);
+export interface StaggerOptions {
+    readonly startDelay?: number;
+    readonly from?: StaggerOrigin;
+    readonly ease?: StaggerEase;
+}
+/**
+ * The public stagger() helper (REQ-API-053) — pin-verbatim math: delay = duration × |origin − i|,
+ * optionally warped by `ease` over maxDelay = total × duration, plus `startDelay`. Seconds, like
+ * every public time. Malformed inputs fail loud at FACTORY time (G-INV-8) — the pin silently
+ * emits NaN delays instead, a misauthoring this engine refuses.
+ */
+export declare function stagger(duration?: number, options?: StaggerOptions): DynamicDelay;
+export interface ChildOrchestrationInput {
+    /** The pin's `animateChildren` forwarded delay: `options.delay` on the parallel branch, 0 on a `when`-sequenced branch. */
+    readonly forwardedDelay: number;
+    readonly delayChildren?: number | DynamicDelay | undefined;
+    readonly staggerChildren?: number | undefined;
+    readonly staggerDirection?: number | undefined;
+    /** Position among the parent's DIRECT variant children in tree order (native authority: mount registration order — packet L3). */
+    readonly index: number;
+    readonly total: number;
+}
+/**
+ * Per-child start delay, exactly the pinned composition (visual-element-variant.ts:92-103):
+ * forwarded + (function delayChildren ? 0 : numeric delayChildren) + stagger term, where a
+ * FUNCTION delayChildren displaces staggerChildren/staggerDirection entirely and the numeric
+ * term is index × staggerChildren (direction 1) or (total − 1) × staggerChildren − index ×
+ * staggerChildren (direction −1). Operation order is preserved for float-exact golden parity.
+ */
+export declare function resolveChildOrchestrationDelay(input: ChildOrchestrationInput): number;
+/**
+ * One orchestration EPISODE as the parent's direct children consume it (T21, REQ-API-053): the
+ * four tree-lane options plus the delay the parent forwards. Built per label edge from the
+ * parent's RESOLVED variant transition by `resolveOrchestrationEpisode`.
+ */
+export interface OrchestrationEpisode {
+    /** What `animateChildren` receives as `delay`: the node's CASCADED start delay in the
+     * parallel branch (the pin forwards `options.delay` — the delay this node's own start was
+     * computed with, NOT its authored transition `delay`), 0 when `when` sequences (the pin's
+     * no-arg `getChildAnimations()` call — packet law 3; corrected by F4). */
+    readonly forwardedDelay: number;
+    readonly delayChildren?: number | DynamicDelay | undefined;
+    readonly staggerChildren?: number | undefined;
+    readonly staggerDirection?: number | undefined;
+    /** Normalized: absent authoring reads as `false` (parallel). */
+    readonly when: false | 'beforeChildren' | 'afterChildren';
+}
+/** The orchestration-relevant slice of a resolved tree-level transition bag. The authored
+ * `delay` is deliberately NOT here — it rides the node's OWN values only (the pin's
+ * getValueTransition), never the children (F4). */
+export type OrchestrationEpisodeInput = Pick<import('./types').TransitionOptionBag, 'when' | 'delayChildren' | 'staggerChildren' | 'staggerDirection'>;
+/**
+ * Resolve a parent's tree-level transition bag into the episode its direct children compose
+ * against (pin: visual-element-variant.ts:71-103). Two laws beyond extraction: what forwards
+ * to children is `nodeStartDelay` — the delay THIS node's own start was computed with (its
+ * orchestration-computed delay from its own parent; 0 at a controlling root) — never the
+ * bag's authored `delay`, which rides only the node's own values (F4); and a truthy `when`
+ * SEQUENCES own-values vs children with the sequenced branch passing `delay: 0` to
+ * `animateChildren` (the no-arg call), while `delayChildren`/stagger apply in both branches.
+ */
+export declare function resolveOrchestrationEpisode(bag: OrchestrationEpisodeInput, nodeStartDelay?: number): OrchestrationEpisode;

package/dist/component/orchestration.js

@@ -0,0 +1,124 @@
+// SPEC-COMPONENT §2 — variant orchestration math (REQ-API-053, T21). The pure tree-lane layer
+// under `delayChildren` / `staggerChildren` / `staggerDirection`: `stagger()` (the public
+// authoring helper the catalog imports from the package root) and the per-child delay resolver
+// replicating the pinned composition (motion-dom@12.42.2 `visual-element-variant.ts:92-103` +
+// `calc-child-stagger.ts` + `utils/stagger.ts`), golden-pinned per sample in
+// `orchestration.test.ts`. Host-agnostic (REQ-CORE-003) — relative imports only. Orchestration
+// never crosses to the UI runtime: this runs on the JS thread at start-scheduling time, so plain
+// function values (a `stagger()` result) are legal here — and ONLY here (the transition
+// converters strip the family, so no function ever reaches a driver or a worklet crossing).
+import { resolveEasing } from "../timing.js";
+import { InvalidTransitionError } from "./validate.js";
+// The pin's getOriginIndex (utils/stagger.ts): 'first' → 0, 'last' → total − 1,
+// 'center' → (total − 1) / 2. A numeric origin is used as-is by the caller.
+function staggerOriginIndex(from, total) {
+    if (from === 'first')
+        return 0;
+    const lastIndex = total - 1;
+    return from === 'last' ? lastIndex : lastIndex / 2;
+}
+/**
+ * The public stagger() helper (REQ-API-053) — pin-verbatim math: delay = duration × |origin − i|,
+ * optionally warped by `ease` over maxDelay = total × duration, plus `startDelay`. Seconds, like
+ * every public time. Malformed inputs fail loud at FACTORY time (G-INV-8) — the pin silently
+ * emits NaN delays instead, a misauthoring this engine refuses.
+ */
+export function stagger(duration = 0.1, options = {}) {
+    if (typeof duration !== 'number' || !Number.isFinite(duration)) {
+        throw new Error(`stagger: duration must be a finite number of seconds, got ${String(duration)} (REQ-API-053)`);
+    }
+    const { startDelay = 0, from = 0, ease } = options;
+    if (typeof startDelay !== 'number' || !Number.isFinite(startDelay)) {
+        throw new Error(`stagger: startDelay must be a finite number of seconds, got ${String(startDelay)} (REQ-API-053)`);
+    }
+    const validOrigin = from === 'first' ||
+        from === 'last' ||
+        from === 'center' ||
+        (typeof from === 'number' && Number.isFinite(from));
+    if (!validOrigin) {
+        throw new Error(`stagger: from must be 'first', 'last', 'center', or a finite index, got ${String(from)} (REQ-API-053)`);
+    }
+    // Resolve the easing EAGERLY so an unknown named curve or malformed bezier throws at the
+    // authoring site, not on the first child start. resolveEasing owns that refusal.
+    const easingFunction = ease === undefined ? undefined : typeof ease === 'function' ? ease : resolveEasing(ease);
+    return (index, total) => {
+        const fromIndex = typeof from === 'number' ? from : staggerOriginIndex(from, total);
+        const distance = Math.abs(fromIndex - index);
+        let delay = duration * distance;
+        if (easingFunction !== undefined) {
+            const maxDelay = total * duration;
+            delay = easingFunction(delay / maxDelay) * maxDelay;
+        }
+        return startDelay + delay;
+    };
+}
+/**
+ * Per-child start delay, exactly the pinned composition (visual-element-variant.ts:92-103):
+ * forwarded + (function delayChildren ? 0 : numeric delayChildren) + stagger term, where a
+ * FUNCTION delayChildren displaces staggerChildren/staggerDirection entirely and the numeric
+ * term is index × staggerChildren (direction 1) or (total − 1) × staggerChildren − index ×
+ * staggerChildren (direction −1). Operation order is preserved for float-exact golden parity.
+ */
+export function resolveChildOrchestrationDelay(input) {
+    const { forwardedDelay, delayChildren, staggerChildren = 0, staggerDirection = 1, index, total, } = input;
+    if (!Number.isInteger(index) ||
+        !Number.isInteger(total) ||
+        total < 1 ||
+        index < 0 ||
+        index >= total) {
+        // Callers derive (index, total) from the live child registry; an out-of-range pair is the
+        // registry's bookkeeping broken — fail loud, never emit a silently-wrong delay.
+        throw new Error(`resolveChildOrchestrationDelay: index ${String(index)} outside [0, ${String(total)}) — ` +
+            'the variant child registry is inconsistent (internal invariant, REQ-API-053)');
+    }
+    const delayIsFunction = typeof delayChildren === 'function';
+    const staggerTerm = delayIsFunction
+        ? executeDynamicDelay(delayChildren, index, total)
+        : staggerDirection === 1
+            ? index * staggerChildren
+            : (total - 1) * staggerChildren - index * staggerChildren;
+    return forwardedDelay + (delayIsFunction ? 0 : (delayChildren ?? 0)) + staggerTerm;
+}
+// The DynamicDelay EXECUTION boundary (review r1 major 6): validate admits arbitrary functions,
+// so the call itself is where user input can misbehave. Both failure shapes surface as the same
+// typed class the validation boundary throws, so the host severity seam catches them under the
+// one policy (development throws; production reports and refuses the property). The pin emits
+// NaN delays here; this engine refuses (G-INV-8).
+function executeDynamicDelay(delayChildren, index, total) {
+    let result;
+    try {
+        result = delayChildren(index, total);
+    }
+    catch (error) {
+        throw new InvalidTransitionError(undefined, 'delayChildren', delayChildren, `the dynamic delay callback threw at (index ${String(index)}, total ${String(total)}): ` +
+            `${String(error)} (REQ-API-053)`);
+    }
+    if (typeof result !== 'number' || !Number.isFinite(result)) {
+        throw new InvalidTransitionError(undefined, 'delayChildren', result, `the dynamic delay callback must return finite seconds, got ${String(result)} at ` +
+            `(index ${String(index)}, total ${String(total)}) (REQ-API-053)`);
+    }
+    return result;
+}
+/**
+ * Resolve a parent's tree-level transition bag into the episode its direct children compose
+ * against (pin: visual-element-variant.ts:71-103). Two laws beyond extraction: what forwards
+ * to children is `nodeStartDelay` — the delay THIS node's own start was computed with (its
+ * orchestration-computed delay from its own parent; 0 at a controlling root) — never the
+ * bag's authored `delay`, which rides only the node's own values (F4); and a truthy `when`
+ * SEQUENCES own-values vs children with the sequenced branch passing `delay: 0` to
+ * `animateChildren` (the no-arg call), while `delayChildren`/stagger apply in both branches.
+ */
+export function resolveOrchestrationEpisode(bag, nodeStartDelay = 0) {
+    if (!Number.isFinite(nodeStartDelay)) {
+        throw new Error(`resolveOrchestrationEpisode: nodeStartDelay must be finite seconds, got ${String(nodeStartDelay)} ` +
+            '— the caller cascades its own computed start delay (internal invariant, REQ-API-053)');
+    }
+    const when = bag.when ?? false;
+    return {
+        forwardedDelay: when === false ? nodeStartDelay : 0,
+        delayChildren: bag.delayChildren,
+        staggerChildren: bag.staggerChildren,
+        staggerDirection: bag.staggerDirection,
+        when,
+    };
+}

package/dist/component/resolve.cjs

@@ -0,0 +1,104 @@
+"use strict";
+// SPEC-COMPONENT §2 — the pure target-merge + base-resolution functions (REQ-API-002/010/011/012/017).
+// Two responsibilities, two pure functions on the verifier seam:
+//   • resolveTarget(base, target) — REQ-API-012 overlay: apply a partial target onto the live value set.
+//     Keys in the target retarget; keys absent from the target retain their live value; a target NEVER
+//     resets an unlisted property. There is no "full visual state" the author must restate.
+//   • resolveStartValue / hostBaseValue — REQ-API-011 base resolution: the STARTING value of a property
+//     appearing in a target with no prior live value — the resolved `style` value if present, else the
+//     documented host base. Identical across engines (the base derives from the registry value type, not
+//     from any host), so no engine supplies a divergent implicit default.
+// Both are pure and deterministic: same inputs → same result, independent of clock or host (REQ-API-017).
+// Host-agnostic (REQ-CORE-003) — reads only the SUBSET registry (relative import).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscreteHostBaseError = void 0;
+exports.resolveTarget = resolveTarget;
+exports.resolveStartValue = resolveStartValue;
+exports.hostBaseValue = hostBaseValue;
+const subset_1 = require("../subset/index.cjs");
+const boundedArray_1 = require("./boundedArray.cjs");
+const validate_1 = require("./validate.cjs");
+// Overlay `target` onto the live `base` value set (REQ-API-012). Returns a fresh, complete value set: every
+// key present in either input appears once; a key in `target` takes the target value (retarget), a key only
+// in `base` retains its live value (hold). Never mutates its inputs; never resets a property the target did
+// not mention. A target value may be a keyframe array (ResolvedTargetValue), so the merge is typed to carry it.
+function resolveTarget(base, target) {
+    // Hold every unlisted base key, then overlay the target. A keyframe ARRAY value is CLONED (and frozen)
+    // as it is captured — a resolved snapshot (a presence exit target, a retarget origin) is resolved-once
+    // and held-immutable, so it must not alias a caller-owned array whose later mutation would change it in
+    // place (REQ-API-017; review major c8d4e61a705b). Keyframe elements are scalars, so a shallow clone is a
+    // full copy. A fresh object each call — the inputs stay immutable.
+    const merged = {};
+    for (const key of Object.keys(base))
+        merged[key] = captureValue(key, base[key]);
+    for (const key of Object.keys(target))
+        merged[key] = captureValue(key, target[key]);
+    return merged;
+}
+// Capture a resolved value independently of its caller: a keyframe array is cloned + frozen (so a later
+// source mutation cannot reach the snapshot, and the snapshot itself cannot be mutated downstream); a
+// scalar is already immutable and passes through.
+function captureValue(key, value) {
+    if (!Array.isArray(value))
+        return value;
+    const capture = (0, boundedArray_1.captureBoundedArray)(value);
+    if (capture.kind !== 'captured') {
+        throw new validate_1.InvalidTargetError(undefined, key, (0, boundedArray_1.capturedArrayDescription)(capture), 'keyframe arrays must have a safe bounded length (REQ-API-033)');
+    }
+    if (capture.values.length < 2) {
+        throw new validate_1.InvalidTargetError(undefined, key, capture.values, 'a keyframe array must have at least two keyframes (REQ-API-033)');
+    }
+    for (let index = 0; index < capture.values.length; index++) {
+        if (!Object.hasOwn(capture.values, index)) {
+            throw new validate_1.InvalidTargetError(undefined, key, capture.values, `keyframe array is missing index ${index} (REQ-API-033)`);
+        }
+    }
+    return capture.values;
+}
+// REQ-API-011: the STARTING (from) value of a property that appears in a target with no prior live value.
+// The resolved `style` value if the style prop specifies it, else the documented host base. Pure.
+function resolveStartValue(key, resolution) {
+    const styled = resolution?.style?.[key];
+    return styled !== undefined ? styled : hostBaseValue(key);
+}
+// T23 B2a2: the discrete-start refusal is TYPED so the component boundary can apply the
+// severity law to exactly this case (production report + refuse the key) without message
+// sniffing; unknown/complex host-base refusals stay plain loud errors on every severity.
+class DiscreteHostBaseError extends Error {
+    constructor(key) {
+        super(`no documented host base value for discrete '${key}': the host default diverges across ` +
+            'engines — provide the starting keyword via initial/style/variants.');
+        this.name = 'DiscreteHostBaseError';
+    }
+}
+exports.DiscreteHostBaseError = DiscreteHostBaseError;
+// The documented host base value for a universal property (REQ-API-011) — the value it animates FROM when
+// neither a live value nor a `style` value exists. Derived from the registry value type so it is a SINGLE
+// source of truth and identical across engines (no host parameter, no engine-divergent default): scale and
+// opacity rest at 1; translations, dimensions, spacing, radii, border widths, and angles rest at 0; colors
+// rest at fully-transparent black. complex/gesture capabilities have no scalar base and fail loud, as does
+// an unknown property.
+function hostBaseValue(key) {
+    const entry = subset_1.UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        throw new Error(`no documented host base value for unknown property '${key}': it is not a universal-subset property.`);
+    }
+    switch (entry.valueType) {
+        case 'unitless':
+            // opacity and scale/scaleX/scaleY are the only unitless universal properties; all rest at 1.
+            return 1;
+        case 'length':
+        case 'angle':
+            return 0;
+        case 'rgba':
+            return 'rgba(0, 0, 0, 0)';
+        case 'discrete':
+            // T23 B: the host default for a discrete keyword DIVERGES across engines (web block vs RN
+            // flex for display) — there is no engine-identical documented base, so the start value must
+            // come from `initial`/`style`/a variant, never a silent host default.
+            throw new DiscreteHostBaseError(key);
+        case 'complex':
+        case 'gesture':
+            throw new Error(`no documented host base value for '${key}' (valueType '${entry.valueType}'): it is not an animatable scalar/color property.`);
+    }
+}

package/dist/component/resolve.d.cts

@@ -0,0 +1,11 @@
+export type ResolvedValue = number | string;
+export type ResolvedTargetValue = ResolvedValue | readonly (number | string | null)[];
+export declare function resolveTarget(base: Readonly<Record<string, ResolvedTargetValue>>, target: Readonly<Record<string, ResolvedTargetValue>>): Record<string, ResolvedTargetValue>;
+export interface StartResolution {
+    readonly style?: Readonly<Record<string, ResolvedValue>>;
+}
+export declare function resolveStartValue(key: string, resolution?: StartResolution): ResolvedValue;
+export declare class DiscreteHostBaseError extends Error {
+    constructor(key: string);
+}
+export declare function hostBaseValue(key: string): ResolvedValue;

package/dist/component/resolve.d.ts

@@ -0,0 +1,11 @@
+export type ResolvedValue = number | string;
+export type ResolvedTargetValue = ResolvedValue | readonly (number | string | null)[];
+export declare function resolveTarget(base: Readonly<Record<string, ResolvedTargetValue>>, target: Readonly<Record<string, ResolvedTargetValue>>): Record<string, ResolvedTargetValue>;
+export interface StartResolution {
+    readonly style?: Readonly<Record<string, ResolvedValue>>;
+}
+export declare function resolveStartValue(key: string, resolution?: StartResolution): ResolvedValue;
+export declare class DiscreteHostBaseError extends Error {
+    constructor(key: string);
+}
+export declare function hostBaseValue(key: string): ResolvedValue;