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

package/dist/timing.js

@@ -0,0 +1,201 @@
+'worklet';
+// @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).
+// Runtime-readable named set (validate / keyframeTiming / shippedSurface share this authority).
+export const 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(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.
+export function resolveEasing(ease) {
+    if (typeof ease === 'string') {
+        if (!isNamedEasing(ease)) {
+            throw new Error(`unknown named easing '${ease}' — expected one of ${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).
+export 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.
+export 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/transformTemplate.cjs

@@ -0,0 +1,219 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Bounded transform-template support (T17 packet, specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md):
+// the canonical generated-string builder (pin `motion-dom buildTransform` format and value
+// typing) and the bounded parser that turns a template's RETURN string into the RN transform
+// array. Grammar is exactly the canonical builder's function set; anything off-grammar fails
+// loud naming the offending token — never a silent partial parse (the R13 law). Host-agnostic
+// (REQ-CORE-003): no host imports.
+//
+// alloc-ok: frame — template composition is string-valued by pin design (motion-dom
+// buildTransform allocates the composed string per frame); the parser allocates only the small
+// output entry list, proportional to the entry count.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTransformString = buildTransformString;
+exports.buildTransformTemplateArgs = buildTransformTemplateArgs;
+exports.parseTransformTemplateOutput = parseTransformTemplateOutput;
+// Canonical key order (pin `transformPropOrder` restricted to the shipped transform keys — the
+// same list composeTransform commits, so template and non-template composition agree).
+const TEMPLATE_KEY_ORDER = [
+    'perspective',
+    'x',
+    'y',
+    'scale',
+    'scaleX',
+    'scaleY',
+    'rotate',
+    'rotateX',
+    'rotateY',
+    'skewX',
+    'skewY',
+];
+// Function name in the generated string per key (pin: translateAlias x→translateX, y→translateY).
+const KEY_FUNCTION = {
+    perspective: 'perspective',
+    x: 'translateX',
+    y: 'translateY',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+// Plain-object lookups, never Sets: worklet captures stay in the most conservative shareable
+// shape — records of primitives (the composeTransform.ts law) — so serialization can never be
+// the failure mode on the UI runtime.
+const DEGREE_KEYS = Object.freeze({
+    rotate: 1,
+    rotateX: 1,
+    rotateY: 1,
+    skewX: 1,
+    skewY: 1,
+});
+const LENGTH_KEYS = Object.freeze({ perspective: 1, x: 1, y: 1 });
+// Pin build-transform's default law: `value === (key.startsWith("scale") ? 1 : 0)`.
+const SCALE_KEYS = Object.freeze({ scale: 1, scaleX: 1, scaleY: 1 });
+// The values-map key name per canonical key (pin latestValues naming: transformPerspective).
+const VALUES_MAP_KEY = {
+    perspective: 'transformPerspective',
+    x: 'x',
+    y: 'y',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+function typedValueFor(key, value) {
+    const unit = DEGREE_KEYS[key] === 1 ? 'deg' : LENGTH_KEYS[key] === 1 ? 'px' : '';
+    return `${value}${unit}`;
+}
+function assertFiniteTemplateValue(key, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`transformTemplate values: key '${key}' must be a finite number, got ${String(value)} (T17).`);
+    }
+}
+/**
+ * The canonical generated string (pin `buildTransform`): `${fn}(${valueWithUnit})` joined by
+ * spaces in canonical order. A non-finite value fails loud naming the key.
+ */
+function buildTransformString(values) {
+    let out = '';
+    for (const key of TEMPLATE_KEY_ORDER) {
+        const value = values[key];
+        if (value === undefined)
+            continue;
+        assertFiniteTemplateValue(key, value);
+        out += `${out === '' ? '' : ' '}${KEY_FUNCTION[key]}(${typedValueFor(key, value)})`;
+    }
+    return out;
+}
+/**
+ * The pin's template call args (motion-dom build-transform, verbatim loop): the values map
+ * carries every PRESENT key typed (defaults INCLUDED — `!valueIsDefault || transformTemplate`);
+ * the generated string carries only NON-DEFAULT values in canonical order, so an all-default
+ * transform hands the template '' (pin `transformIsDefault ? "" : transformString`).
+ */
+function buildTransformTemplateArgs(values) {
+    const typed = {};
+    let generated = '';
+    for (const key of TEMPLATE_KEY_ORDER) {
+        const value = values[key];
+        if (value === undefined)
+            continue;
+        assertFiniteTemplateValue(key, value);
+        const typedValue = typedValueFor(key, value);
+        typed[VALUES_MAP_KEY[key]] = typedValue;
+        const isDefault = SCALE_KEYS[key] === 1 ? value === 1 : value === 0;
+        if (!isDefault) {
+            generated += `${generated === '' ? '' : ' '}${KEY_FUNCTION[key]}(${typedValue})`;
+        }
+    }
+    return { values: typed, generated };
+}
+// Per-function unit law: translate* take px|%; scale* are unitless; rotate*/skew* take
+// deg|unitless; perspective takes px|unitless. Anything else is a named refusal.
+const FUNCTION_UNITS = {
+    perspective: ['px', ''],
+    translate: ['px', '%'],
+    translateX: ['px', '%'],
+    translateY: ['px', '%'],
+    scale: [''],
+    scaleX: [''],
+    scaleY: [''],
+    rotate: ['deg', ''],
+    rotateX: ['deg', ''],
+    rotateY: ['deg', ''],
+    skewX: ['deg', ''],
+    skewY: ['deg', ''],
+};
+const ENTRY_NAME = {
+    perspective: 'perspective',
+    translateX: 'translateX',
+    translateY: 'translateY',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+const VALUE_RE = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(px|%|deg)?$/;
+function fail(templateOutput, reason) {
+    throw new Error(`transformTemplate output '${templateOutput}': ${reason} (T17 bounded grammar).`);
+}
+function parseValue(templateOutput, fn, raw) {
+    const m = VALUE_RE.exec(raw.trim());
+    if (m === null) {
+        fail(templateOutput, `unparseable value '${raw}' for ${fn}`);
+    }
+    const [, numeral, rawUnit] = m;
+    const unit = (rawUnit ?? '');
+    const allowed = FUNCTION_UNITS[fn];
+    if (!allowed.includes(unit)) {
+        fail(templateOutput, `unit '${unit || '(none)'}' is not valid for ${fn}`);
+    }
+    // Percent translate entries ride RN's percent-string form. Angle entries commit as RN degree
+    // STRINGS — the shipped composeTransform output shape (RN types the rotate/skew family
+    // string-typed; a bare number is not a valid entry). A unitless angle is degrees by the pin's
+    // getValueAsType law. Everything else commits numeric.
+    if (unit === '%')
+        return `${numeral}%`;
+    if (allowed.includes('deg'))
+        return `${numeral}deg`;
+    return Number(numeral);
+}
+/**
+ * Parse a template's RETURN string into the ordered RN transform array. The grammar is the
+ * canonical builder's function set with px/%/deg/unitless values; `translate` takes 1-2 args
+ * (comma or space separated). Anything else throws naming the offending token.
+ */
+function parseTransformTemplateOutput(templateOutput) {
+    const out = [];
+    let rest = templateOutput.trim();
+    while (rest.length > 0) {
+        const open = rest.indexOf('(');
+        const fn = open === -1 ? rest.trim() : rest.slice(0, open).trim();
+        if (open === -1 || fn === '' || /\s/.test(fn)) {
+            fail(templateOutput, `malformed token '${fn}' — expected fn(args)`);
+        }
+        if (!(fn in FUNCTION_UNITS) && fn !== 'translate') {
+            fail(templateOutput, `transform function '${fn}' is outside the bounded grammar`);
+        }
+        const close = rest.indexOf(')', open);
+        if (close === -1) {
+            fail(templateOutput, `unbalanced parens near '${fn}('`);
+        }
+        const argsRaw = rest.slice(open + 1, close);
+        const args = argsRaw.includes(',')
+            ? argsRaw.split(',').map((a) => a.trim())
+            : argsRaw.trim() === ''
+                ? []
+                : argsRaw.trim().split(/\s+/);
+        if (fn === 'translate') {
+            if (args.length === 0 || args.length > 2) {
+                fail(templateOutput, `translate takes 1 or 2 args, got ${args.length}`);
+            }
+            out.push({ translateX: parseValue(templateOutput, 'translate', args[0]) });
+            if (args.length === 2) {
+                out.push({ translateY: parseValue(templateOutput, 'translate', args[1]) });
+            }
+        }
+        else {
+            if (args.length !== 1) {
+                fail(templateOutput, `${fn} takes exactly 1 arg, got ${args.length}`);
+            }
+            out.push({ [ENTRY_NAME[fn]]: parseValue(templateOutput, fn, args[0]) });
+        }
+        rest = rest.slice(close + 1).trim();
+    }
+    return out;
+}

package/dist/transformTemplate.d.cts

@@ -0,0 +1,29 @@
+export type TransformTemplateValues = Partial<Record<(typeof TEMPLATE_KEY_ORDER)[number], number>>;
+export type TransformPropertyKey = 'transformPerspective' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY' | 'skewX' | 'skewY';
+export type TransformProperties = Partial<Record<TransformPropertyKey, string>>;
+export type TransformTemplate = (transform: TransformProperties, generatedTransform: string) => string;
+declare const TEMPLATE_KEY_ORDER: readonly ["perspective", "x", "y", "scale", "scaleX", "scaleY", "rotate", "rotateX", "rotateY", "skewX", "skewY"];
+/**
+ * The canonical generated string (pin `buildTransform`): `${fn}(${valueWithUnit})` joined by
+ * spaces in canonical order. A non-finite value fails loud naming the key.
+ */
+export declare function buildTransformString(values: TransformTemplateValues): string;
+export type TransformTemplateArgs = {
+    readonly values: TransformProperties;
+    readonly generated: string;
+};
+/**
+ * The pin's template call args (motion-dom build-transform, verbatim loop): the values map
+ * carries every PRESENT key typed (defaults INCLUDED — `!valueIsDefault || transformTemplate`);
+ * the generated string carries only NON-DEFAULT values in canonical order, so an all-default
+ * transform hands the template '' (pin `transformIsDefault ? "" : transformString`).
+ */
+export declare function buildTransformTemplateArgs(values: TransformTemplateValues): TransformTemplateArgs;
+export type TransformEntry = Readonly<Record<string, number | string>>;
+/**
+ * Parse a template's RETURN string into the ordered RN transform array. The grammar is the
+ * canonical builder's function set with px/%/deg/unitless values; `translate` takes 1-2 args
+ * (comma or space separated). Anything else throws naming the offending token.
+ */
+export declare function parseTransformTemplateOutput(templateOutput: string): TransformEntry[];
+export {};

package/dist/transformTemplate.d.ts

@@ -0,0 +1,29 @@
+export type TransformTemplateValues = Partial<Record<(typeof TEMPLATE_KEY_ORDER)[number], number>>;
+export type TransformPropertyKey = 'transformPerspective' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY' | 'skewX' | 'skewY';
+export type TransformProperties = Partial<Record<TransformPropertyKey, string>>;
+export type TransformTemplate = (transform: TransformProperties, generatedTransform: string) => string;
+declare const TEMPLATE_KEY_ORDER: readonly ["perspective", "x", "y", "scale", "scaleX", "scaleY", "rotate", "rotateX", "rotateY", "skewX", "skewY"];
+/**
+ * The canonical generated string (pin `buildTransform`): `${fn}(${valueWithUnit})` joined by
+ * spaces in canonical order. A non-finite value fails loud naming the key.
+ */
+export declare function buildTransformString(values: TransformTemplateValues): string;
+export type TransformTemplateArgs = {
+    readonly values: TransformProperties;
+    readonly generated: string;
+};
+/**
+ * The pin's template call args (motion-dom build-transform, verbatim loop): the values map
+ * carries every PRESENT key typed (defaults INCLUDED — `!valueIsDefault || transformTemplate`);
+ * the generated string carries only NON-DEFAULT values in canonical order, so an all-default
+ * transform hands the template '' (pin `transformIsDefault ? "" : transformString`).
+ */
+export declare function buildTransformTemplateArgs(values: TransformTemplateValues): TransformTemplateArgs;
+export type TransformEntry = Readonly<Record<string, number | string>>;
+/**
+ * Parse a template's RETURN string into the ordered RN transform array. The grammar is the
+ * canonical builder's function set with px/%/deg/unitless values; `translate` takes 1-2 args
+ * (comma or space separated). Anything else throws naming the offending token.
+ */
+export declare function parseTransformTemplateOutput(templateOutput: string): TransformEntry[];
+export {};