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

package/dist/subset/resolve.cjs

@@ -0,0 +1,98 @@
+"use strict";
+// SPEC-UNIVERSAL-SUBSET §3 — the loud-fail capability resolver (REQ-SUBSET-014). A capability present in
+// an animate/initial/exit target or a gesture prop, on a host that does not declare it, raises a typed
+// UnsupportedCapabilityError naming the capability, the active host, and the host(s) that DO support it.
+// It never silently no-ops, drops, or degrades — this is REQ-API-005's fail-closed invariant applied to
+// subset membership, and the primitive SPEC-COMPONENT's validateTarget builds on. Host-agnostic: it reads
+// the frozen registry and a pure host-capability descriptor; it touches no real react-native host.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedCapabilityError = void 0;
+exports.hostCapabilities = hostCapabilities;
+exports.resolveCapabilityVerdict = resolveCapabilityVerdict;
+exports.resolveCapability = resolveCapability;
+exports.resolveTargetCapabilities = resolveTargetCapabilities;
+const registry_1 = require("./registry.cjs");
+class UnsupportedCapabilityError extends Error {
+    capability;
+    hostId;
+    reason;
+    // The host ids that DO support the capability (empty for an unknown key). Named in the message so a
+    // developer sees where the capability is valid.
+    supportedOn;
+    constructor(capability, hostId, reason, supportedOn, message) {
+        super(message);
+        this.name = 'UnsupportedCapabilityError';
+        this.capability = capability;
+        this.hostId = hostId;
+        this.reason = reason;
+        this.supportedOn = supportedOn;
+    }
+}
+exports.UnsupportedCapabilityError = UnsupportedCapabilityError;
+// The host archetypes that support each universality class. Provisional taxonomy for the deterministic
+// interior (native = touch-first, web = pointer/keyboard): pointer-gated capability lives on the web
+// host, web-only on the web host, universal + native-extension on both. The exact per-host / per-input
+// gating granularity is a §8 open decision (flagged), refined at the device milestone.
+function supportedHostsFor(universality) {
+    switch (universality) {
+        case 'universal':
+        case 'native-extension':
+            return ['native', 'web'];
+        case 'web-only':
+        case 'pointer-gated':
+            return ['web'];
+    }
+}
+// Build a host from the universalities its input model supports: it declares every registry key whose
+// universality is in `supported`. Keeps host declarations derived from the single source of truth.
+function hostCapabilities(id, supported) {
+    const supportedSet = new Set(supported);
+    const declares = new Set();
+    for (const entry of registry_1.UNIVERSAL_SUBSET.entries) {
+        if (!supportedSet.has(entry.universality))
+            continue;
+        for (const key of entry.keys)
+            declares.add(key);
+    }
+    return { id, declares };
+}
+function resolveCapabilityVerdict(host, key) {
+    const entry = registry_1.UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        return {
+            entry: null,
+            unsupported: new UnsupportedCapabilityError(key, host.id, 'unknown', [], `Unknown capability '${key}': not in the universal-subset registry ` +
+                `(host '${host.id}').`),
+        };
+    }
+    if (!host.declares.has(key)) {
+        const supportedOn = supportedHostsFor(entry.universality);
+        return {
+            entry: null,
+            unsupported: new UnsupportedCapabilityError(key, host.id, 'off-host', supportedOn, `Capability '${key}' is not supported on host '${host.id}' — ` +
+                `it is ${entry.universality}; supported on: ${supportedOn.join(', ')}.`),
+        };
+    }
+    return { entry, unsupported: null };
+}
+// Resolve a single capability key against a host. Returns the registry entry when the host declares it;
+// throws UnsupportedCapabilityError otherwise. The unknown-key check comes FIRST so the registry stays
+// authoritative even if a malformed host over-declares.
+function resolveCapability(host, key) {
+    const verdict = resolveCapabilityVerdict(host, key);
+    if (verdict.unsupported !== null)
+        throw verdict.unsupported;
+    return verdict.entry;
+}
+// Gate every key of a target object against a host's declared capability set. Fails closed on the FIRST
+// unsupported key (the throw aborts iteration) and returns a fresh key→entry map only when ALL keys
+// resolve — it never partially resolves (REQ-SUBSET-014 / REQ-API-013 fail-closed). Named
+// `resolveTargetCapabilities` (not `resolveTarget`) so SPEC-COMPONENT can own the public
+// `resolveTarget(base, target)` value-merge; this is the SUBSET capability gate, a distinct function.
+function resolveTargetCapabilities(host, target) {
+    const resolved = new Map();
+    for (const key of Object.keys(target)) {
+        resolved.set(key, resolveCapability(host, key));
+    }
+    return resolved;
+}

package/dist/subset/resolve.d.cts

@@ -0,0 +1,24 @@
+import { type CapabilityEntry, type Universality } from "./registry.cjs";
+export interface HostCapabilities {
+    readonly id: string;
+    readonly declares: ReadonlySet<string>;
+}
+export type UnsupportedReason = 'unknown' | 'off-host';
+export declare class UnsupportedCapabilityError extends Error {
+    readonly capability: string;
+    readonly hostId: string;
+    readonly reason: UnsupportedReason;
+    readonly supportedOn: readonly string[];
+    constructor(capability: string, hostId: string, reason: UnsupportedReason, supportedOn: readonly string[], message: string);
+}
+export declare function hostCapabilities(id: string, supported: readonly Universality[]): HostCapabilities;
+export type CapabilityVerdict = {
+    readonly entry: CapabilityEntry;
+    readonly unsupported: null;
+} | {
+    readonly entry: null;
+    readonly unsupported: UnsupportedCapabilityError;
+};
+export declare function resolveCapabilityVerdict(host: HostCapabilities, key: string): CapabilityVerdict;
+export declare function resolveCapability(host: HostCapabilities, key: string): CapabilityEntry;
+export declare function resolveTargetCapabilities(host: HostCapabilities, target: Readonly<Record<string, unknown>>): ReadonlyMap<string, CapabilityEntry>;

package/dist/subset/resolve.d.ts

@@ -0,0 +1,24 @@
+import { type CapabilityEntry, type Universality } from "./registry.js";
+export interface HostCapabilities {
+    readonly id: string;
+    readonly declares: ReadonlySet<string>;
+}
+export type UnsupportedReason = 'unknown' | 'off-host';
+export declare class UnsupportedCapabilityError extends Error {
+    readonly capability: string;
+    readonly hostId: string;
+    readonly reason: UnsupportedReason;
+    readonly supportedOn: readonly string[];
+    constructor(capability: string, hostId: string, reason: UnsupportedReason, supportedOn: readonly string[], message: string);
+}
+export declare function hostCapabilities(id: string, supported: readonly Universality[]): HostCapabilities;
+export type CapabilityVerdict = {
+    readonly entry: CapabilityEntry;
+    readonly unsupported: null;
+} | {
+    readonly entry: null;
+    readonly unsupported: UnsupportedCapabilityError;
+};
+export declare function resolveCapabilityVerdict(host: HostCapabilities, key: string): CapabilityVerdict;
+export declare function resolveCapability(host: HostCapabilities, key: string): CapabilityEntry;
+export declare function resolveTargetCapabilities(host: HostCapabilities, target: Readonly<Record<string, unknown>>): ReadonlyMap<string, CapabilityEntry>;

package/dist/subset/resolve.js

@@ -0,0 +1,90 @@
+// SPEC-UNIVERSAL-SUBSET §3 — the loud-fail capability resolver (REQ-SUBSET-014). A capability present in
+// an animate/initial/exit target or a gesture prop, on a host that does not declare it, raises a typed
+// UnsupportedCapabilityError naming the capability, the active host, and the host(s) that DO support it.
+// It never silently no-ops, drops, or degrades — this is REQ-API-005's fail-closed invariant applied to
+// subset membership, and the primitive SPEC-COMPONENT's validateTarget builds on. Host-agnostic: it reads
+// the frozen registry and a pure host-capability descriptor; it touches no real react-native host.
+import { UNIVERSAL_SUBSET } from "./registry.js";
+export class UnsupportedCapabilityError extends Error {
+    capability;
+    hostId;
+    reason;
+    // The host ids that DO support the capability (empty for an unknown key). Named in the message so a
+    // developer sees where the capability is valid.
+    supportedOn;
+    constructor(capability, hostId, reason, supportedOn, message) {
+        super(message);
+        this.name = 'UnsupportedCapabilityError';
+        this.capability = capability;
+        this.hostId = hostId;
+        this.reason = reason;
+        this.supportedOn = supportedOn;
+    }
+}
+// The host archetypes that support each universality class. Provisional taxonomy for the deterministic
+// interior (native = touch-first, web = pointer/keyboard): pointer-gated capability lives on the web
+// host, web-only on the web host, universal + native-extension on both. The exact per-host / per-input
+// gating granularity is a §8 open decision (flagged), refined at the device milestone.
+function supportedHostsFor(universality) {
+    switch (universality) {
+        case 'universal':
+        case 'native-extension':
+            return ['native', 'web'];
+        case 'web-only':
+        case 'pointer-gated':
+            return ['web'];
+    }
+}
+// Build a host from the universalities its input model supports: it declares every registry key whose
+// universality is in `supported`. Keeps host declarations derived from the single source of truth.
+export function hostCapabilities(id, supported) {
+    const supportedSet = new Set(supported);
+    const declares = new Set();
+    for (const entry of UNIVERSAL_SUBSET.entries) {
+        if (!supportedSet.has(entry.universality))
+            continue;
+        for (const key of entry.keys)
+            declares.add(key);
+    }
+    return { id, declares };
+}
+export function resolveCapabilityVerdict(host, key) {
+    const entry = UNIVERSAL_SUBSET.get(key);
+    if (entry === undefined) {
+        return {
+            entry: null,
+            unsupported: new UnsupportedCapabilityError(key, host.id, 'unknown', [], `Unknown capability '${key}': not in the universal-subset registry ` +
+                `(host '${host.id}').`),
+        };
+    }
+    if (!host.declares.has(key)) {
+        const supportedOn = supportedHostsFor(entry.universality);
+        return {
+            entry: null,
+            unsupported: new UnsupportedCapabilityError(key, host.id, 'off-host', supportedOn, `Capability '${key}' is not supported on host '${host.id}' — ` +
+                `it is ${entry.universality}; supported on: ${supportedOn.join(', ')}.`),
+        };
+    }
+    return { entry, unsupported: null };
+}
+// Resolve a single capability key against a host. Returns the registry entry when the host declares it;
+// throws UnsupportedCapabilityError otherwise. The unknown-key check comes FIRST so the registry stays
+// authoritative even if a malformed host over-declares.
+export function resolveCapability(host, key) {
+    const verdict = resolveCapabilityVerdict(host, key);
+    if (verdict.unsupported !== null)
+        throw verdict.unsupported;
+    return verdict.entry;
+}
+// Gate every key of a target object against a host's declared capability set. Fails closed on the FIRST
+// unsupported key (the throw aborts iteration) and returns a fresh key→entry map only when ALL keys
+// resolve — it never partially resolves (REQ-SUBSET-014 / REQ-API-013 fail-closed). Named
+// `resolveTargetCapabilities` (not `resolveTarget`) so SPEC-COMPONENT can own the public
+// `resolveTarget(base, target)` value-merge; this is the SUBSET capability gate, a distinct function.
+export function resolveTargetCapabilities(host, target) {
+    const resolved = new Map();
+    for (const key of Object.keys(target)) {
+        resolved.set(key, resolveCapability(host, key));
+    }
+    return resolved;
+}

package/dist/timing.cjs

@@ -0,0 +1,206 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Duration+ease timing (tween) generator (SPEC-SPRING REQ-TIMING-001/002). value = mix(origin, target,
+// ease(clamp(0,1,t/duration))); velocity is a 5ms finite difference of that curve; done at t ≥ duration;
+// incoming velocity is ignored. Host-agnostic (REQ-CORE-003): the cubic-bezier evaluator is an exact
+// port of motion-utils' Gaëtan Renaudeau BezierEasing (binary subdivision), NOT imported. Numerics are
+// pinned to motion@12.42.2 and proven by golden parity in timing.test.ts.
+//
+// Worklet safety (hytd3r / Remote Function crash class): NEVER store named-easing evaluators as
+// module-init function values. reverseEasing/mirrorEasing wrappers and cubicBezier returns built at
+// load time lacked __workletHash and crashed when UI-runtime call sites invoked them. All named and
+// cubic evaluation is pure math over number tables; resolveEasing returns thin closures that capture
+// only serializable primitives (name string or control points).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAMED_EASING_KEYS = void 0;
+exports.resolveEasing = resolveEasing;
+exports.isEasingList = isEasingList;
+exports.timingGenerator = timingGenerator;
+// Runtime-readable named set (validate / keyframeTiming / shippedSurface share this authority).
+exports.NAMED_EASING_KEYS = [
+    'linear',
+    'easeIn',
+    'easeOut',
+    'easeInOut',
+    'circIn',
+    'circOut',
+    'circInOut',
+    'backIn',
+    'backOut',
+    'backInOut',
+    'anticipate',
+];
+const DEFAULT_DURATION_MS = 300; // REQ-TIMING-002 (0.3s)
+const DEFAULT_EASE = [0.25, 0.1, 0.35, 1]; // REQ-TIMING-002
+const VELOCITY_SAMPLE_MS = 5;
+// Named cubic-bezier control points (motion-utils/easing/ease + back). Data only — no function values.
+const EASE_IN = [0.42, 0, 1, 1];
+const EASE_OUT = [0, 0, 0.58, 1];
+const EASE_IN_OUT = [0.42, 0, 0.58, 1];
+// motion-utils/easing/back.ts: backOut = cubicBezier(0.33, 1.53, 0.69, 0.99)
+const BACK_OUT = [0.33, 1.53, 0.69, 0.99];
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+const mix = (from, to, p) => from + (to - from) * p;
+const SUBDIVISION_PRECISION = 1e-7;
+const SUBDIVISION_MAX_ITERATIONS = 12;
+// x(t)/y(t) of the bezier given a single control-point pair (exact port of motion-utils calcBezier).
+const calcBezier = (t, a1, a2) => ((1 - 3 * a2 + 3 * a1) * t + (3 * a2 - 6 * a1)) * t * t + 3 * a1 * t;
+/** Pure cubic-bezier sample — no nested function allocation at module init (hytd3r). */
+function evaluateCubic(x1, y1, x2, y2, t) {
+    if (t === 0 || t === 1)
+        return t;
+    // Linear gradient is the identity; also avoids a degenerate subdivision.
+    if (x1 === y1 && x2 === y2)
+        return t;
+    let lower = 0;
+    let upper = 1;
+    let currentT = 0;
+    let currentX = 0;
+    let i = 0;
+    do {
+        currentT = lower + (upper - lower) / 2;
+        currentX = calcBezier(currentT, x1, x2) - t;
+        if (currentX > 0)
+            upper = currentT;
+        else
+            lower = currentT;
+    } while (Math.abs(currentX) > SUBDIVISION_PRECISION && ++i < SUBDIVISION_MAX_ITERATIONS);
+    return calcBezier(currentT, y1, y2);
+}
+// motion-utils/easing/circ.ts — pure forms of reverse/mirror so no function-valued table.
+function evaluateCircIn(p) {
+    return 1 - Math.sin(Math.acos(clamp01(p)));
+}
+function evaluateCircOut(p) {
+    // reverse(circIn): 1 - circIn(1 - p)
+    return 1 - evaluateCircIn(1 - p);
+}
+function evaluateCircInOut(p) {
+    // mirror(circIn)
+    return p <= 0.5 ? evaluateCircIn(2 * p) / 2 : (2 - evaluateCircIn(2 * (1 - p))) / 2;
+}
+function evaluateBackOut(p) {
+    return evaluateCubic(BACK_OUT[0], BACK_OUT[1], BACK_OUT[2], BACK_OUT[3], p);
+}
+function evaluateBackIn(p) {
+    // reverse(backOut)
+    return 1 - evaluateBackOut(1 - p);
+}
+function evaluateBackInOut(p) {
+    // mirror(backIn)
+    return p <= 0.5 ? evaluateBackIn(2 * p) / 2 : (2 - evaluateBackIn(2 * (1 - p))) / 2;
+}
+// motion-utils/easing/anticipate.ts
+function evaluateAnticipate(p) {
+    if (p >= 1)
+        return 1;
+    const doubled = p * 2;
+    return doubled < 1 ? 0.5 * evaluateBackIn(doubled) : 0.5 * (2 - Math.pow(2, -10 * (doubled - 1)));
+}
+const NAMED_EASING_SET = new Set(exports.NAMED_EASING_KEYS);
+function isNamedEasing(value) {
+    return NAMED_EASING_SET.has(value);
+}
+/** Pure named-easing sample — captures no function values (hytd3r Remote Function law). */
+function evaluateNamedEasing(name, p) {
+    switch (name) {
+        case 'linear':
+            return p;
+        case 'easeIn':
+            return evaluateCubic(EASE_IN[0], EASE_IN[1], EASE_IN[2], EASE_IN[3], p);
+        case 'easeOut':
+            return evaluateCubic(EASE_OUT[0], EASE_OUT[1], EASE_OUT[2], EASE_OUT[3], p);
+        case 'easeInOut':
+            return evaluateCubic(EASE_IN_OUT[0], EASE_IN_OUT[1], EASE_IN_OUT[2], EASE_IN_OUT[3], p);
+        case 'circIn':
+            return evaluateCircIn(p);
+        case 'circOut':
+            return evaluateCircOut(p);
+        case 'circInOut':
+            return evaluateCircInOut(p);
+        case 'backIn':
+            return evaluateBackIn(p);
+        case 'backOut':
+            return evaluateBackOut(p);
+        case 'backInOut':
+            return evaluateBackInOut(p);
+        case 'anticipate':
+            return evaluateAnticipate(p);
+        default: {
+            // Exhaustiveness + runtime cast guard (9a4arp): never sample NaN for an unknown name.
+            const _exhaustive = name;
+            throw new Error(`unknown named easing '${String(_exhaustive)}'`);
+        }
+    }
+}
+// alloc-ok: lifecycle-edge — easing resolution at factory time. Exported for the multi-keyframe
+// generator (keyframes.ts, REQ-API-033), which resolves ONE easing per segment through this same
+// exact BezierEasing / Motion-named port — never a second easing vocabulary.
+// Closures capture only primitives (name string or four numbers) so worklet serialization never
+// embeds a JS-thread Remote Function (hytd3r).
+// Fail-closed (9a4arp): unknown named strings throw before any sample can emit NaN. The public
+// validateTransition boundary also refuses them; this is the generator-seam backstop for direct
+// timingGenerator / resolveEasing callers.
+function resolveEasing(ease) {
+    if (typeof ease === 'string') {
+        if (!isNamedEasing(ease)) {
+            throw new Error(`unknown named easing '${ease}' — expected one of ${exports.NAMED_EASING_KEYS.join(', ')} ` +
+                '(REQ-TIMING-001 / REQ-API-033)');
+        }
+        const name = ease;
+        // Named returned closures (frame-path manifest anonymous-sampler repair): the qualified
+        // symbols are resolveEasing.namedEvaluator / resolveEasing.cubicEvaluator.
+        return function namedEvaluator(p) {
+            return evaluateNamedEasing(name, p);
+        };
+    }
+    const x1 = ease[0];
+    const y1 = ease[1];
+    const x2 = ease[2];
+    const y2 = ease[3];
+    return function cubicEvaluator(p) {
+        return evaluateCubic(x1, y1, x2, y2, p);
+    };
+}
+// Disambiguate a PER-SEGMENT easing list (`['easeIn', 'easeOut']`, `[[…],[…]]`) from a SINGLE
+// cubic-bezier easing (`[0.25, 0.1, 0.35, 1]`) — both are arrays. A per-segment list's elements are
+// themselves easings (a named string or a nested bezier array); a single CubicBezier's elements are
+// plain numbers. Mirrors motion-dom's `isEasingArray`. Without this, a single-bezier `ease` on a
+// keyframe array would be mis-read element-by-element as per-segment (REQ-API-033).
+function isEasingList(ease) {
+    return Array.isArray(ease) && typeof ease[0] !== 'number';
+}
+/**
+ * Build a tween `GeneratorFactory` (REQ-API-004). `seed.from` is the origin; the seed's incoming
+ * velocity is intentionally ignored (REQ-TIMING-001). The tween finishes deterministically at
+ * `t ≥ duration`.
+ */
+// alloc-ok: lifecycle-edge — the factory resolves duration/ease once per animate command;
+// per-frame work is sample() below, which mutates the reused record and allocates nothing.
+function timingGenerator(target, config) {
+    const duration = config?.duration ?? DEFAULT_DURATION_MS;
+    const ease = resolveEasing(config?.ease ?? DEFAULT_EASE);
+    // alloc-ok: lifecycle-edge — generator construction at command time; the one reused sample
+    // record is built here, never per frame.
+    return (seed) => {
+        const origin = seed.from;
+        const value = (t) => mix(origin, target, ease(clamp01(t / duration)));
+        // One sample record per generator, mutated and returned every call — motion's own generators
+        // return their reused `state` the same way. Per-frame sampling must not allocate
+        // (REQ-DRIVER-015); callers read the scalars immediately and never retain the record.
+        const out = { value: origin, velocity: 0, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const prevT = Math.max(elapsedMs - VELOCITY_SAMPLE_MS, 0);
+                const dt = elapsedMs - prevT;
+                const velocity = dt ? ((current - value(prevT)) / dt) * 1000 : 0; // px/s (REQ-TIMING-001)
+                const done = elapsedMs >= duration;
+                out.value = done ? target : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/timing.d.cts

@@ -0,0 +1,17 @@
+import type { GeneratorFactory } from "./types.cjs";
+export type CubicBezier = readonly [number, number, number, number];
+export type NamedEasing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'circIn' | 'circOut' | 'circInOut' | 'backIn' | 'backOut' | 'backInOut' | 'anticipate';
+export type Easing = CubicBezier | NamedEasing;
+export declare const NAMED_EASING_KEYS: readonly ["linear", "easeIn", "easeOut", "easeInOut", "circIn", "circOut", "circInOut", "backIn", "backOut", "backInOut", "anticipate"];
+export interface TimingConfig {
+    duration?: number;
+    ease?: Easing;
+}
+export declare function resolveEasing(ease: Easing): (p: number) => number;
+export declare function isEasingList(ease: Easing | readonly Easing[]): ease is readonly Easing[];
+/**
+ * Build a tween `GeneratorFactory` (REQ-API-004). `seed.from` is the origin; the seed's incoming
+ * velocity is intentionally ignored (REQ-TIMING-001). The tween finishes deterministically at
+ * `t ≥ duration`.
+ */
+export declare function timingGenerator(target: number, config?: TimingConfig): GeneratorFactory;

package/dist/timing.d.ts

@@ -0,0 +1,17 @@
+import type { GeneratorFactory } from "./types.js";
+export type CubicBezier = readonly [number, number, number, number];
+export type NamedEasing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'circIn' | 'circOut' | 'circInOut' | 'backIn' | 'backOut' | 'backInOut' | 'anticipate';
+export type Easing = CubicBezier | NamedEasing;
+export declare const NAMED_EASING_KEYS: readonly ["linear", "easeIn", "easeOut", "easeInOut", "circIn", "circOut", "circInOut", "backIn", "backOut", "backInOut", "anticipate"];
+export interface TimingConfig {
+    duration?: number;
+    ease?: Easing;
+}
+export declare function resolveEasing(ease: Easing): (p: number) => number;
+export declare function isEasingList(ease: Easing | readonly Easing[]): ease is readonly Easing[];
+/**
+ * Build a tween `GeneratorFactory` (REQ-API-004). `seed.from` is the origin; the seed's incoming
+ * velocity is intentionally ignored (REQ-TIMING-001). The tween finishes deterministically at
+ * `t ≥ duration`.
+ */
+export declare function timingGenerator(target: number, config?: TimingConfig): GeneratorFactory;