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

package/dist/component/variants.cjs

@@ -0,0 +1,333 @@
+"use strict";
+// SPEC-COMPONENT §2 — REQ-API-032: the variants resolution core (R7). Pure, host-agnostic,
+// deterministic over (definition, dictionary, live state) — the pinned `resolveVariantFromProps`
+// chain including its runtime-only direct function form. Law (a): a local dictionary miss is the pinned
+// NO-OP (the propagation-source shape), never an error. Law (b): animation-time arrays
+// resolve to ORDERED per-label applications, each preserving its own embedded transition.
+// Law (c): initial labels overlay synchronously into one first-paint state, transitions
+// discarded. Law (f): the eager shape + entry validation — outer shapes typed as a unit,
+// per-entry validation through the SAME target/transition boundaries the animate lane
+// rides. The FUNCTION form (T24 B2, dynamic variants) is accepted at the boundary by
+// identity and validated at RESOLUTION, where its result exists.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidVariantError = void 0;
+exports.variantsShapeRefusal = variantsShapeRefusal;
+exports.assertVariantsShape = assertVariantsShape;
+exports.validateVariantEntry = validateVariantEntry;
+exports.validateVariantEntrySnapshot = validateVariantEntrySnapshot;
+exports.resolveVariantDefinition = resolveVariantDefinition;
+exports.resolveVariantDefinitionResult = resolveVariantDefinitionResult;
+exports.flattenVariantApplications = flattenVariantApplications;
+exports.resolveInitialOverlay = resolveInitialOverlay;
+const validate_1 = require("./validate.cjs");
+const keyframeTiming_1 = require("../driver/keyframeTiming.cjs");
+const prepare_1 = require("../driver/prepare.cjs");
+const boundedArray_1 = require("./boundedArray.cjs");
+const transition_1 = require("./transition.cjs");
+// Thrown for malformed variants SHAPES (REQ-API-014's structured pattern): the key names the
+// offending unit ('(variants)' for the outer shape, the label for an entry).
+class InvalidVariantError extends Error {
+    key;
+    value;
+    constructor(key, value, reason, cause) {
+        super(`invalid variants ${key === '(variants)' ? 'prop' : `entry '${key}'`} — ${reason}`, cause !== undefined ? { cause } : undefined);
+        this.name = 'InvalidVariantError';
+        this.key = key;
+        this.value = value;
+    }
+}
+exports.InvalidVariantError = InvalidVariantError;
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+// Hostile-input architecture (M3 r3 majors 1b53e9337aec/13af48a64530): severity gates never
+// CATCH around code that can run foreign traps/getters — any durable "ownership" mark on an
+// error object is forgeable or replayable, and trusting exported classes launders authentic
+// sentinels. Instead every boundary primitive is RETURN-shaped with PHASE-SEPARATED reads:
+// foreign code (prototype probes, getters, enumeration traps) runs UNGUARDED first — its
+// faults propagate untouched by construction — and validation then operates on plain
+// snapshots, so a returned refusal is boundary-made by construction and nothing else is
+// ever classified.
+/**
+ * Law (f), outer shape, RETURN-shaped: the typed refusal, or null when `variants` is a
+ * plain object. The probe itself may throw on hostile values (a getPrototypeOf trap, a
+ * revoked proxy) — those faults propagate untouched; only the RETURNED refusal is input
+ * refusal.
+ */
+function variantsShapeRefusal(value) {
+    if (isPlainObject(value))
+        return null;
+    return new InvalidVariantError('(variants)', value, 'the dictionary must be a plain object of label → target entries (REQ-API-032 law f; ' +
+        'a malformed shape fails loud, never coerces to the empty dictionary)');
+}
+/**
+ * Law (f), outer shape: `variants` must be a plain object — null, arrays, and
+ * prototype-carrying objects refuse AS A UNIT (typed), never coerce to an empty dictionary.
+ */
+function assertVariantsShape(value) {
+    const refusal = variantsShapeRefusal(value);
+    if (refusal !== null)
+        throw refusal;
+}
+/**
+ * Law (f), per entry: an entry must be a plain object whose members validate through the
+ * SAME boundaries the animate lane rides — core validateTarget for the target members and
+ * the REQ-API-031 transition law for the embedded transition — or a RESOLVER (T24 B2),
+ * accepted uninvoked and validated at resolution.
+ */
+function validateVariantEntry(label, entry, host, opts) {
+    const { refusal } = validateVariantEntrySnapshot(label, entry, host, opts);
+    if (refusal !== null)
+        throw refusal;
+}
+/**
+ * Law (f), per entry, RETURN-shaped + SNAPSHOT-accepting (M3 r3 majors 13af48a64530 +
+ * 5cb2381e272c; hardened r4 majors 4db96de50131 + 93bab4ecf757): the READ phase runs first
+ * and UNGUARDED — the entry's getters and every level of a transition's enumeration traps
+ * fire here, so their faults (including authentic same-class sentinels) propagate
+ * untouched. Validation then runs on DEEP-plain snapshots, and the SNAPSHOT is what the
+ * caller accepts: a stateful proxy cannot show the validators one value and the engine
+ * another (one read, one truth). Residual bound, stated honestly: hostile LEAF objects
+ * (non-array, non-plain) stay by reference and are refused by the validators' trap-free
+ * type checks — they are never enumerated inside the trusted region.
+ */
+function validateVariantEntrySnapshot(label, entry, host, opts) {
+    if (typeof entry === 'function') {
+        // T24 B2: the dynamic form is ACCEPTED at the boundary, by identity and UNINVOKED — its
+        // keys do not exist until resolution, so entry validation applies to its RESULT at the
+        // resolution seam (resolveVariantDefinition), never here.
+        return { refusal: null, entry: entry };
+    }
+    if (!isPlainObject(entry)) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label} must be a plain target entry (REQ-API-032 law f)`),
+            entry: null,
+        };
+    }
+    // READ phase — every getter and enumeration trap fires HERE, outside any try.
+    const { transition: rawTransition, ...rawTarget } = entry;
+    // Materialize each ARRAY member ONCE, before validation (R8, review major 18): a shallow snapshot let
+    // the validators read a member's elements and the accepted clone read them AGAIN, so a hostile
+    // accessor-backed array (100 then null) could pass validation yet land the unvalidated null in the
+    // snapshot. The bounded capture reads each own index exactly once; the frozen copy is the SINGLE truth both the
+    // validators and the accepted entry see. Non-array members pass through unchanged. The accumulator is
+    // NULL-PROTOTYPE (review major 24): a SCALAR own '__proto__' member assigned onto an ordinary object
+    // is a silent no-op setter (the key vanishes yet the snapshot stays plain and passes the shape gate) —
+    // a null-prototype object makes it an own data property so the capability gate refuses it, loudly.
+    const targetSnapshot = Object.create(null);
+    for (const [key, member] of Object.entries(rawTarget)) {
+        if (!Array.isArray(member)) {
+            targetSnapshot[key] = member;
+            continue;
+        }
+        const captured = (0, boundedArray_1.captureBoundedArray)(member);
+        if (captured.kind !== 'captured') {
+            return {
+                refusal: new InvalidVariantError(label, (0, boundedArray_1.capturedArrayDescription)(captured), `variants.${label} keyframe arrays must have a safe length between 0 and 100000 (REQ-API-033)`),
+                entry: null,
+            };
+        }
+        targetSnapshot[key] = captured.values;
+    }
+    let transitionSnapshot;
+    if (rawTransition === undefined) {
+        transitionSnapshot = undefined;
+    }
+    else if (isPlainObject(rawTransition)) {
+        // Reuse the value-preserving transition capture used by every raw/supplying boundary. It keeps
+        // symbols, unknown strings, and non-enumerable known fields for validateTransitionRefusal while
+        // deeply snapshotting only legal timing arrays.
+        transitionSnapshot = (0, prepare_1.captureTransition)(rawTransition);
+    }
+    else {
+        // A non-plain transition cannot be faithfully snapshotted — spreading a Date/Map/array
+        // yields the EMPTY object, silently laundering the malformed shape into a valid empty
+        // transition (M3 r4 major 4db96de50131). The refusal is constructed HERE, return-shaped,
+        // mirroring validateTransition's own shape law verbatim (message + category parity);
+        // the value is never probed again.
+        const shapeCause = new validate_1.InvalidTransitionError(opts?.componentId, '(transition)', rawTransition, '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 {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${shapeCause.message}`, shapeCause),
+            entry: null,
+        };
+    }
+    // RETURN-shaped validators, NO catch (M3 r6 major 30a9c21bf960): a returned refusal is
+    // validator-made by construction; anything THROWN — including an authentic same-class
+    // sentinel from a polluted dependency (Set.prototype.has) — propagates untouched because
+    // nothing here catches it.
+    const transitionRefusal = (0, validate_1.validateTransitionRefusal)(transitionSnapshot, opts);
+    if (transitionRefusal === null && transitionSnapshot !== undefined) {
+        // Family-2: web pin consumes `ease`; rewrite catalog `easings` on the accepted snapshot so
+        // every supplier (variant embed, element, MotionConfig) hands the same normalized shape.
+        transitionSnapshot = (0, transition_1.normalizeTransitionEaseAlias)(transitionSnapshot);
+    }
+    if (transitionRefusal !== null) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${transitionRefusal.message}`, transitionRefusal),
+            entry: null,
+        };
+    }
+    const targetRefusal = (0, validate_1.validateTargetRefusal)(targetSnapshot, host, opts);
+    if (targetRefusal !== null) {
+        return {
+            refusal: new InvalidVariantError(label, entry, `variants.${label}: ${targetRefusal.message}`, targetRefusal),
+            entry: null,
+        };
+    }
+    for (const [key, value] of Object.entries(targetSnapshot)) {
+        const effectiveTransition = transitionSnapshot === undefined
+            ? undefined
+            : (0, transition_1.resolveTransitionForKey)(transitionSnapshot, key);
+        const timingRefusal = (0, keyframeTiming_1.keyframeTransitionRefusal)(opts?.componentId, key, value, effectiveTransition);
+        if (timingRefusal !== null) {
+            return {
+                refusal: new InvalidVariantError(label, entry, `variants.${label}: ${timingRefusal.message}`, timingRefusal),
+                entry: null,
+            };
+        }
+    }
+    // The accepted ENTRY is null-prototype too (M3 r6 major 5d48ad691b96): absent must MEAN
+    // absent — a consumer reading `.transition` off an Object.prototype-backed entry would
+    // see a polluted inherited value when none is own.
+    const acceptedEntry = Object.create(null);
+    for (const [key, member] of Object.entries(targetSnapshot)) {
+        // `targetSnapshot` array members are ALREADY the read-once frozen copies the validators saw, so the
+        // accepted entry references that single truth directly — no second read of the caller's array
+        // (reviews major 91f7a2c43bd0 immutability + major 18 one-read). Keyframe elements are scalars.
+        acceptedEntry[key] = member;
+    }
+    if (transitionSnapshot !== undefined) {
+        acceptedEntry['transition'] = transitionSnapshot;
+    }
+    return { refusal: null, entry: acceptedEntry };
+}
+/** Split one entry into its application (the bare target + its own transition). */
+function applicationOf(entry) {
+    const { transition, ...target } = entry;
+    return { target: target, transition };
+}
+/**
+ * Laws (a)/(b): resolve a label or label array to the ORDERED application list. A local
+ * miss contributes nothing (the pinned no-op); each hit preserves its own transition.
+ */
+function resolveVariantDefinition(definition, dictionary, context) {
+    const result = resolveVariantDefinitionResult(definition, dictionary, context);
+    if (result.refusal !== null)
+        throw result.refusal;
+    return result.applications;
+}
+/**
+ * Internal severity seam: boundary-made validation failures are returned, while value-state reads
+ * and user resolver invocations remain outside every catch and preserve their exact thrown value.
+ */
+function resolveVariantDefinitionResult(definition, dictionary, context) {
+    if (typeof definition === 'function') {
+        const invocation = invokeResolver('(definition)', definition, context);
+        if (invocation.refusal !== null)
+            return { applications: [], refusal: invocation.refusal };
+        const produced = invocation.value;
+        if (typeof produced !== 'string') {
+            const resolution = resolveProducedTarget('(definition)', produced, context);
+            return resolution.refusal === null
+                ? { applications: [resolution.application], refusal: null }
+                : { applications: [], refusal: resolution.refusal };
+        }
+        return resolveSingleLabel(produced, dictionary, context);
+    }
+    const labels = typeof definition === 'string' ? [definition] : definition;
+    const applications = [];
+    for (const label of labels) {
+        const resolution = resolveSingleLabel(label, dictionary, context);
+        if (resolution.refusal !== null)
+            return { applications: [], refusal: resolution.refusal };
+        applications.push(...resolution.applications);
+    }
+    return { applications, refusal: null };
+}
+function resolutionContextRefusal(label, context) {
+    return context === undefined
+        ? new InvalidVariantError(label, undefined, `variants.${label} is a RESOLVER but the resolution site supplied no ` +
+            'resolution context — the site is not wired for dynamic variants (T24 B2)')
+        : null;
+}
+// Each call performs its own pin-shaped `getValueState` read. The invocation is deliberately
+// unguarded: user faults preserve identity and host severity routes only our typed refusals.
+function invokeResolver(label, entry, context) {
+    const refusal = resolutionContextRefusal(label, context);
+    if (refusal !== null)
+        return { refusal };
+    const wired = context;
+    const { current, velocity } = wired.readValueState();
+    return { value: entry(wired.custom, current, velocity), refusal: null };
+}
+function resolveProducedTarget(label, produced, context) {
+    const contextRefusal = resolutionContextRefusal(label, context);
+    if (contextRefusal !== null)
+        return { refusal: contextRefusal };
+    const wired = context;
+    if (typeof produced === 'function') {
+        return {
+            refusal: new InvalidVariantError(label, produced, `variants.${label}: the resolver returned another resolver — a dictionary resolver ` +
+                'must return a target object exactly once (the pin two-step bound)'),
+        };
+    }
+    const { refusal, entry: accepted } = validateVariantEntrySnapshot(label, produced, wired.host, wired.componentId === undefined ? undefined : { componentId: wired.componentId });
+    if (refusal !== null)
+        return { refusal };
+    return { application: applicationOf(accepted), refusal: null };
+}
+function resolveSingleLabel(label, dictionary, context) {
+    // OWN properties only (M1 review major 1): prototype-chain names are local misses.
+    if (dictionary === undefined || !Object.hasOwn(dictionary, label)) {
+        return { applications: [], refusal: null };
+    }
+    const entry = dictionary[label];
+    if (typeof entry !== 'function') {
+        return { applications: [applicationOf(entry)], refusal: null };
+    }
+    const invocation = invokeResolver(label, entry, context);
+    if (invocation.refusal !== null)
+        return { applications: [], refusal: invocation.refusal };
+    // This is the bounded second function arm. Its result is final and cannot name another label.
+    const resolution = resolveProducedTarget(label, invocation.value, context);
+    return resolution.refusal === null
+        ? { applications: [resolution.application], refusal: null }
+        : { applications: [], refusal: resolution.refusal };
+}
+function flattenVariantApplications(applications) {
+    const target = {};
+    const transitions = {};
+    for (const application of applications) {
+        for (const key of Object.keys(application.target)) {
+            target[key] = application.target[key];
+            if (application.transition === undefined)
+                delete transitions[key];
+            else
+                transitions[key] = application.transition;
+        }
+    }
+    return { target: target, transitions };
+}
+/**
+ * Law (c): the synchronous initial overlay — all labels merge in order into ONE first-paint
+ * state, transitions DISCARDED (REQ-API-010's no-entrance law is untouched).
+ */
+function resolveInitialOverlay(definition, dictionary, context) {
+    const overlay = {};
+    for (const application of resolveVariantDefinition(definition, dictionary, context)) {
+        // T23 B3c: an initial application applies its transitionEnd INSTANTLY (the pin's
+        // nothing-animates arm) — the carrier's sub-values fold into the first-paint state,
+        // winning over the same application's target key; the carrier member itself never
+        // rides the overlay.
+        const { transitionEnd: carrier, ...plain } = application.target;
+        Object.assign(overlay, plain);
+        if (typeof carrier === 'object' && carrier !== null && !Array.isArray(carrier)) {
+            Object.assign(overlay, carrier);
+        }
+    }
+    return overlay;
+}

package/dist/component/variants.d.cts

@@ -0,0 +1,106 @@
+import type { HostCapabilities } from "../subset/index.cjs";
+import type { Target, Transition } from "./types.cjs";
+export type VariantEntry = Target & {
+    readonly transition?: Transition;
+};
+export type VariantResolver = (custom: unknown, current: Readonly<Record<string, unknown>>, velocity: Readonly<Record<string, number>>) => unknown;
+export interface VariantValueState {
+    readonly current: Readonly<Record<string, unknown>>;
+    readonly velocity: Readonly<Record<string, number>>;
+}
+export type VariantsDictionary = Readonly<Record<string, VariantEntry | VariantResolver>>;
+/**
+ * The live inputs a RESOLVER entry is invoked with (pin `getValueState`: the element's
+ * current values and their velocities; `custom` per the pin's exit-vs-props precedence),
+ * plus the validation host its RESULT is validated against. A value-less element's reader
+ * returns empty maps, matching the pin.
+ */
+export interface VariantResolutionContext {
+    readonly custom: unknown;
+    /**
+     * Pin `getValueState` is read at each function arm, not captured when the definition is
+     * discovered. Keeping this lazy also makes static labels a zero-read path.
+     */
+    readonly readValueState: () => VariantValueState;
+    readonly host: HostCapabilities;
+    readonly componentId?: string;
+}
+/** One resolved label's application: the bare target + the label's OWN transition (law b). */
+export interface VariantApplication {
+    readonly target: Target;
+    readonly transition: Transition | undefined;
+}
+export declare class InvalidVariantError extends Error {
+    readonly key: string;
+    readonly value: unknown;
+    constructor(key: string, value: unknown, reason: string, cause?: unknown);
+}
+/**
+ * Law (f), outer shape, RETURN-shaped: the typed refusal, or null when `variants` is a
+ * plain object. The probe itself may throw on hostile values (a getPrototypeOf trap, a
+ * revoked proxy) — those faults propagate untouched; only the RETURNED refusal is input
+ * refusal.
+ */
+export declare function variantsShapeRefusal(value: unknown): InvalidVariantError | null;
+/**
+ * Law (f), outer shape: `variants` must be a plain object — null, arrays, and
+ * prototype-carrying objects refuse AS A UNIT (typed), never coerce to an empty dictionary.
+ */
+export declare function assertVariantsShape(value: unknown): asserts value is VariantsDictionary;
+/**
+ * Law (f), per entry: an entry must be a plain object whose members validate through the
+ * SAME boundaries the animate lane rides — core validateTarget for the target members and
+ * the REQ-API-031 transition law for the embedded transition — or a RESOLVER (T24 B2),
+ * accepted uninvoked and validated at resolution.
+ */
+export declare function validateVariantEntry(label: string, entry: unknown, host: HostCapabilities, opts?: {
+    readonly componentId?: string;
+}): void;
+/**
+ * Law (f), per entry, RETURN-shaped + SNAPSHOT-accepting (M3 r3 majors 13af48a64530 +
+ * 5cb2381e272c; hardened r4 majors 4db96de50131 + 93bab4ecf757): the READ phase runs first
+ * and UNGUARDED — the entry's getters and every level of a transition's enumeration traps
+ * fire here, so their faults (including authentic same-class sentinels) propagate
+ * untouched. Validation then runs on DEEP-plain snapshots, and the SNAPSHOT is what the
+ * caller accepts: a stateful proxy cannot show the validators one value and the engine
+ * another (one read, one truth). Residual bound, stated honestly: hostile LEAF objects
+ * (non-array, non-plain) stay by reference and are refused by the validators' trap-free
+ * type checks — they are never enumerated inside the trusted region.
+ */
+export declare function validateVariantEntrySnapshot(label: string, entry: unknown, host: HostCapabilities, opts?: {
+    readonly componentId?: string;
+}): {
+    readonly refusal: InvalidVariantError | null;
+    readonly entry: VariantEntry | VariantResolver | null;
+};
+/**
+ * Laws (a)/(b): resolve a label or label array to the ORDERED application list. A local
+ * miss contributes nothing (the pinned no-op); each hit preserves its own transition.
+ */
+export declare function resolveVariantDefinition(definition: string | readonly string[] | VariantResolver, dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): readonly VariantApplication[];
+/**
+ * Internal severity seam: boundary-made validation failures are returned, while value-state reads
+ * and user resolver invocations remain outside every catch and preserve their exact thrown value.
+ */
+export declare function resolveVariantDefinitionResult(definition: string | readonly string[] | VariantResolver, dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): {
+    readonly applications: readonly VariantApplication[];
+    readonly refusal: InvalidVariantError | null;
+};
+/**
+ * The per-key projection of an ordered application list — law (b) for LAYER consumers
+ * (gesture-state layers hold one flattened target): each key carries the value AND the
+ * transition of the application that LAST named it. A transition-less winner clears an
+ * earlier attribution so the key falls back exactly as executing that label alone would
+ * (the R6-F1 chain: layer transition, else element transition).
+ */
+export interface FlattenedVariantApplications {
+    readonly target: Target;
+    /** Attribution holds ONLY labeled transitions — absence (not undefined) means fallback. */
+    readonly transitions: Readonly<Record<string, Transition>>;
+}
+export declare function flattenVariantApplications(applications: readonly VariantApplication[]): FlattenedVariantApplications;
+/**
+ * Law (c): the synchronous initial overlay — all labels merge in order into ONE first-paint
+ * state, transitions DISCARDED (REQ-API-010's no-entrance law is untouched).
+ */
+export declare function resolveInitialOverlay(definition: string | readonly string[], dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): Target;

package/dist/component/variants.d.ts

@@ -0,0 +1,106 @@
+import type { HostCapabilities } from "../subset/index.js";
+import type { Target, Transition } from "./types.js";
+export type VariantEntry = Target & {
+    readonly transition?: Transition;
+};
+export type VariantResolver = (custom: unknown, current: Readonly<Record<string, unknown>>, velocity: Readonly<Record<string, number>>) => unknown;
+export interface VariantValueState {
+    readonly current: Readonly<Record<string, unknown>>;
+    readonly velocity: Readonly<Record<string, number>>;
+}
+export type VariantsDictionary = Readonly<Record<string, VariantEntry | VariantResolver>>;
+/**
+ * The live inputs a RESOLVER entry is invoked with (pin `getValueState`: the element's
+ * current values and their velocities; `custom` per the pin's exit-vs-props precedence),
+ * plus the validation host its RESULT is validated against. A value-less element's reader
+ * returns empty maps, matching the pin.
+ */
+export interface VariantResolutionContext {
+    readonly custom: unknown;
+    /**
+     * Pin `getValueState` is read at each function arm, not captured when the definition is
+     * discovered. Keeping this lazy also makes static labels a zero-read path.
+     */
+    readonly readValueState: () => VariantValueState;
+    readonly host: HostCapabilities;
+    readonly componentId?: string;
+}
+/** One resolved label's application: the bare target + the label's OWN transition (law b). */
+export interface VariantApplication {
+    readonly target: Target;
+    readonly transition: Transition | undefined;
+}
+export declare class InvalidVariantError extends Error {
+    readonly key: string;
+    readonly value: unknown;
+    constructor(key: string, value: unknown, reason: string, cause?: unknown);
+}
+/**
+ * Law (f), outer shape, RETURN-shaped: the typed refusal, or null when `variants` is a
+ * plain object. The probe itself may throw on hostile values (a getPrototypeOf trap, a
+ * revoked proxy) — those faults propagate untouched; only the RETURNED refusal is input
+ * refusal.
+ */
+export declare function variantsShapeRefusal(value: unknown): InvalidVariantError | null;
+/**
+ * Law (f), outer shape: `variants` must be a plain object — null, arrays, and
+ * prototype-carrying objects refuse AS A UNIT (typed), never coerce to an empty dictionary.
+ */
+export declare function assertVariantsShape(value: unknown): asserts value is VariantsDictionary;
+/**
+ * Law (f), per entry: an entry must be a plain object whose members validate through the
+ * SAME boundaries the animate lane rides — core validateTarget for the target members and
+ * the REQ-API-031 transition law for the embedded transition — or a RESOLVER (T24 B2),
+ * accepted uninvoked and validated at resolution.
+ */
+export declare function validateVariantEntry(label: string, entry: unknown, host: HostCapabilities, opts?: {
+    readonly componentId?: string;
+}): void;
+/**
+ * Law (f), per entry, RETURN-shaped + SNAPSHOT-accepting (M3 r3 majors 13af48a64530 +
+ * 5cb2381e272c; hardened r4 majors 4db96de50131 + 93bab4ecf757): the READ phase runs first
+ * and UNGUARDED — the entry's getters and every level of a transition's enumeration traps
+ * fire here, so their faults (including authentic same-class sentinels) propagate
+ * untouched. Validation then runs on DEEP-plain snapshots, and the SNAPSHOT is what the
+ * caller accepts: a stateful proxy cannot show the validators one value and the engine
+ * another (one read, one truth). Residual bound, stated honestly: hostile LEAF objects
+ * (non-array, non-plain) stay by reference and are refused by the validators' trap-free
+ * type checks — they are never enumerated inside the trusted region.
+ */
+export declare function validateVariantEntrySnapshot(label: string, entry: unknown, host: HostCapabilities, opts?: {
+    readonly componentId?: string;
+}): {
+    readonly refusal: InvalidVariantError | null;
+    readonly entry: VariantEntry | VariantResolver | null;
+};
+/**
+ * Laws (a)/(b): resolve a label or label array to the ORDERED application list. A local
+ * miss contributes nothing (the pinned no-op); each hit preserves its own transition.
+ */
+export declare function resolveVariantDefinition(definition: string | readonly string[] | VariantResolver, dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): readonly VariantApplication[];
+/**
+ * Internal severity seam: boundary-made validation failures are returned, while value-state reads
+ * and user resolver invocations remain outside every catch and preserve their exact thrown value.
+ */
+export declare function resolveVariantDefinitionResult(definition: string | readonly string[] | VariantResolver, dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): {
+    readonly applications: readonly VariantApplication[];
+    readonly refusal: InvalidVariantError | null;
+};
+/**
+ * The per-key projection of an ordered application list — law (b) for LAYER consumers
+ * (gesture-state layers hold one flattened target): each key carries the value AND the
+ * transition of the application that LAST named it. A transition-less winner clears an
+ * earlier attribution so the key falls back exactly as executing that label alone would
+ * (the R6-F1 chain: layer transition, else element transition).
+ */
+export interface FlattenedVariantApplications {
+    readonly target: Target;
+    /** Attribution holds ONLY labeled transitions — absence (not undefined) means fallback. */
+    readonly transitions: Readonly<Record<string, Transition>>;
+}
+export declare function flattenVariantApplications(applications: readonly VariantApplication[]): FlattenedVariantApplications;
+/**
+ * Law (c): the synchronous initial overlay — all labels merge in order into ONE first-paint
+ * state, transitions DISCARDED (REQ-API-010's no-entrance law is untouched).
+ */
+export declare function resolveInitialOverlay(definition: string | readonly string[], dictionary: VariantsDictionary | undefined, context?: VariantResolutionContext): Target;