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

package/dist/spring.cjs

@@ -0,0 +1,128 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Analytic scalar spring solver (SPEC-SPRING REQ-SPRING-001/002/008/010/011). A pure closed-form
+// evaluator — value(t)/velocity(t) computed directly per damping regime, never stepped by Euler/RK.
+// Host-agnostic (REQ-CORE-003): imports nothing from motion/react. Numerics are pinned to
+// motion@12.42.2 (see specs/SPEC-SPRING.md) and proven by golden parity in spring.test.ts.
+//
+// Unit/sign convention (REQ-SPRING-008): time `t` is ms; the undamped angular frequency ω0 is per-ms
+// (rad/ms); internal velocity is px/ms. The public boundary is px/s. The solver seeds internal
+// v0 = −(seed.velocity_px_per_s / 1000) so the position's initial derivative x'(0) equals the true
+// incoming public velocity; returned velocity is internal px/ms × 1000. A sign flip here inverts the
+// first-bounce direction (a conformance failure), so it is asserted by the sign test.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertTwoKeyframes = assertTwoKeyframes;
+exports.springGenerator = springGenerator;
+// REQ-SPRING-013 / REQ-API-005: the scalar spring/inertia generator is two-keyframe ([from, to]). More
+// than two keyframes is a dev-time error — fail loudly, never silently truncate.
+function assertTwoKeyframes(keyframes) {
+    if (keyframes.length > 2) {
+        throw new Error(`Native Motion spring is scalar two-keyframe ([from, to]); got ${keyframes.length} keyframes.`);
+    }
+}
+// Rest thresholds (REQ-SPRING-003), pinned from motion source (springDefaults). The scale switches to
+// the granular values when the move is tiny (REQ-SPRING-011). Owned here — SPEC-SPRING tightens the
+// core seed constants.
+const REST_SPEED = { default: 2, granular: 0.01 };
+const REST_DELTA = { default: 0.5, granular: 0.005 };
+const GRANULAR_SCALE = 5;
+/**
+ * Build a spring `GeneratorFactory` from a target and resolved physics. The seed supplies the origin
+ * (`from`) and the incoming public velocity (`velocity`, px/s); transition-config resolution
+ * (findSpring / visualDuration / defaults) is a separate concern (SPEC-SPRING Milestone 2).
+ */
+// alloc-ok: lifecycle-edge — the factory resolves physics once per animate command; per-frame work
+// is sample() below, which mutates the reused record and allocates nothing.
+function springGenerator(target, physics, settle) {
+    const { stiffness, damping, mass } = physics;
+    const omega0 = Math.sqrt(stiffness / mass) / 1000; // undamped angular freq, rad/ms
+    const z = damping / (2 * Math.sqrt(stiffness * mass)); // damping ratio; regime by strict <1/===1/>1
+    const settleDuration = settle?.settleDuration ?? null;
+    // alloc-ok: lifecycle-edge — generator construction at command/interruption time; the closed
+    // forms and the one reused sample record are built here, never per frame.
+    return (seed) => {
+        const origin = seed.from;
+        const delta = target - origin; // initialDelta
+        const v0 = -(seed.velocity / 1000); // internal initial velocity, px/ms (REQ-SPRING-008)
+        // Rest thresholds by move scale (REQ-SPRING-011); per-context overrides win over the scale default.
+        const granular = Math.abs(delta) < GRANULAR_SCALE;
+        // Pinned zero-as-absent (r15 c6e31fd509a8): Motion 12.42.2 reads these thresholds falsy —
+        // an explicit 0 falls back to the scale defaults, never an unbounded active spring.
+        const restSpeed = settle?.restSpeed || (granular ? REST_SPEED.granular : REST_SPEED.default);
+        const restDelta = settle?.restDelta || (granular ? REST_DELTA.granular : REST_DELTA.default);
+        // Regime-specific closed forms. value(t) → px; velocityPerMs(t) → px/ms (= x'(t)).
+        // Each is a NAMED function (frame-path manifest anonymous-sampler repair): the qualified
+        // symbols are springGenerator.factory.<regime>Value/<regime>Velocity.
+        let value;
+        let velocityPerMs;
+        if (z < 1) {
+            // Underdamped (REQ-SPRING-002).
+            const wd = omega0 * Math.sqrt(1 - z * z); // damped angular freq
+            const a = (v0 + z * omega0 * delta) / wd;
+            const sinCoeff = z * omega0 * a + delta * wd;
+            const cosCoeff = z * omega0 * delta - a * wd;
+            function underdampedValue(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return target - env * (a * Math.sin(wd * t) + delta * Math.cos(wd * t));
+            }
+            function underdampedVelocity(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return env * (sinCoeff * Math.sin(wd * t) + cosCoeff * Math.cos(wd * t));
+            }
+            value = underdampedValue;
+            velocityPerMs = underdampedVelocity;
+        }
+        else if (z === 1) {
+            // Critically damped (REQ-SPRING-002).
+            const c = v0 + omega0 * delta;
+            function criticalValue(t) {
+                return target - Math.exp(-omega0 * t) * (delta + c * t);
+            }
+            function criticalVelocity(t) {
+                return Math.exp(-omega0 * t) * (omega0 * c * t - v0);
+            }
+            value = criticalValue;
+            velocityPerMs = criticalVelocity;
+        }
+        else {
+            // Overdamped — pure-exponential form (REQ-SPRING-010). Both λ < 0 → no overflow, no sinh/cosh
+            // cap; the capped form (Motion #1207) is never used. λslow uses −ω0/(z+√(z²−1)) to avoid
+            // catastrophic cancellation at large z.
+            const root = Math.sqrt(z * z - 1);
+            const wd = omega0 * root;
+            const lambdaSlow = -omega0 / (z + root);
+            const lambdaFast = -omega0 * (z + root);
+            const cSlow = (v0 + z * omega0 * delta + wd * delta) / (2 * wd);
+            const cFast = delta - cSlow;
+            function overdampedValue(t) {
+                return target - (cSlow * Math.exp(lambdaSlow * t) + cFast * Math.exp(lambdaFast * t));
+            }
+            function overdampedVelocity(t) {
+                return -(cSlow * lambdaSlow * Math.exp(lambdaSlow * t) +
+                    cFast * lambdaFast * Math.exp(lambdaFast * t));
+            }
+            value = overdampedValue;
+            velocityPerMs = overdampedVelocity;
+        }
+        // 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: seed.from, velocity: seed.velocity, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const velocity = velocityPerMs(elapsedMs) * 1000; // → px/s (REQ-SPRING-008)
+                // Settle (REQ-SPRING-011): findSpring (duration) springs finish deterministically at
+                // t ≥ settleDuration; physics + visualDuration springs rest by speed AND delta. On done, snap to
+                // target (matches motion's next()), so an interruption re-seeds from an exact endpoint.
+                const done = settleDuration !== null
+                    ? elapsedMs >= settleDuration
+                    : Math.abs(velocity) <= restSpeed && Math.abs(target - current) <= restDelta;
+                out.value = done ? target : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/spring.d.cts

@@ -0,0 +1,18 @@
+import type { GeneratorFactory } from "./types.cjs";
+export interface SpringPhysics {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+export interface SpringSettleOptions {
+    restSpeed?: number;
+    restDelta?: number;
+    settleDuration?: number | null;
+}
+export declare function assertTwoKeyframes(keyframes: readonly unknown[]): void;
+/**
+ * Build a spring `GeneratorFactory` from a target and resolved physics. The seed supplies the origin
+ * (`from`) and the incoming public velocity (`velocity`, px/s); transition-config resolution
+ * (findSpring / visualDuration / defaults) is a separate concern (SPEC-SPRING Milestone 2).
+ */
+export declare function springGenerator(target: number, physics: SpringPhysics, settle?: SpringSettleOptions): GeneratorFactory;

package/dist/spring.d.ts

@@ -0,0 +1,18 @@
+import type { GeneratorFactory } from "./types.js";
+export interface SpringPhysics {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+export interface SpringSettleOptions {
+    restSpeed?: number;
+    restDelta?: number;
+    settleDuration?: number | null;
+}
+export declare function assertTwoKeyframes(keyframes: readonly unknown[]): void;
+/**
+ * Build a spring `GeneratorFactory` from a target and resolved physics. The seed supplies the origin
+ * (`from`) and the incoming public velocity (`velocity`, px/s); transition-config resolution
+ * (findSpring / visualDuration / defaults) is a separate concern (SPEC-SPRING Milestone 2).
+ */
+export declare function springGenerator(target: number, physics: SpringPhysics, settle?: SpringSettleOptions): GeneratorFactory;

package/dist/spring.js

@@ -0,0 +1,125 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Analytic scalar spring solver (SPEC-SPRING REQ-SPRING-001/002/008/010/011). A pure closed-form
+// evaluator — value(t)/velocity(t) computed directly per damping regime, never stepped by Euler/RK.
+// Host-agnostic (REQ-CORE-003): imports nothing from motion/react. Numerics are pinned to
+// motion@12.42.2 (see specs/SPEC-SPRING.md) and proven by golden parity in spring.test.ts.
+//
+// Unit/sign convention (REQ-SPRING-008): time `t` is ms; the undamped angular frequency ω0 is per-ms
+// (rad/ms); internal velocity is px/ms. The public boundary is px/s. The solver seeds internal
+// v0 = −(seed.velocity_px_per_s / 1000) so the position's initial derivative x'(0) equals the true
+// incoming public velocity; returned velocity is internal px/ms × 1000. A sign flip here inverts the
+// first-bounce direction (a conformance failure), so it is asserted by the sign test.
+// REQ-SPRING-013 / REQ-API-005: the scalar spring/inertia generator is two-keyframe ([from, to]). More
+// than two keyframes is a dev-time error — fail loudly, never silently truncate.
+export function assertTwoKeyframes(keyframes) {
+    if (keyframes.length > 2) {
+        throw new Error(`Native Motion spring is scalar two-keyframe ([from, to]); got ${keyframes.length} keyframes.`);
+    }
+}
+// Rest thresholds (REQ-SPRING-003), pinned from motion source (springDefaults). The scale switches to
+// the granular values when the move is tiny (REQ-SPRING-011). Owned here — SPEC-SPRING tightens the
+// core seed constants.
+const REST_SPEED = { default: 2, granular: 0.01 };
+const REST_DELTA = { default: 0.5, granular: 0.005 };
+const GRANULAR_SCALE = 5;
+/**
+ * Build a spring `GeneratorFactory` from a target and resolved physics. The seed supplies the origin
+ * (`from`) and the incoming public velocity (`velocity`, px/s); transition-config resolution
+ * (findSpring / visualDuration / defaults) is a separate concern (SPEC-SPRING Milestone 2).
+ */
+// alloc-ok: lifecycle-edge — the factory resolves physics once per animate command; per-frame work
+// is sample() below, which mutates the reused record and allocates nothing.
+export function springGenerator(target, physics, settle) {
+    const { stiffness, damping, mass } = physics;
+    const omega0 = Math.sqrt(stiffness / mass) / 1000; // undamped angular freq, rad/ms
+    const z = damping / (2 * Math.sqrt(stiffness * mass)); // damping ratio; regime by strict <1/===1/>1
+    const settleDuration = settle?.settleDuration ?? null;
+    // alloc-ok: lifecycle-edge — generator construction at command/interruption time; the closed
+    // forms and the one reused sample record are built here, never per frame.
+    return (seed) => {
+        const origin = seed.from;
+        const delta = target - origin; // initialDelta
+        const v0 = -(seed.velocity / 1000); // internal initial velocity, px/ms (REQ-SPRING-008)
+        // Rest thresholds by move scale (REQ-SPRING-011); per-context overrides win over the scale default.
+        const granular = Math.abs(delta) < GRANULAR_SCALE;
+        // Pinned zero-as-absent (r15 c6e31fd509a8): Motion 12.42.2 reads these thresholds falsy —
+        // an explicit 0 falls back to the scale defaults, never an unbounded active spring.
+        const restSpeed = settle?.restSpeed || (granular ? REST_SPEED.granular : REST_SPEED.default);
+        const restDelta = settle?.restDelta || (granular ? REST_DELTA.granular : REST_DELTA.default);
+        // Regime-specific closed forms. value(t) → px; velocityPerMs(t) → px/ms (= x'(t)).
+        // Each is a NAMED function (frame-path manifest anonymous-sampler repair): the qualified
+        // symbols are springGenerator.factory.<regime>Value/<regime>Velocity.
+        let value;
+        let velocityPerMs;
+        if (z < 1) {
+            // Underdamped (REQ-SPRING-002).
+            const wd = omega0 * Math.sqrt(1 - z * z); // damped angular freq
+            const a = (v0 + z * omega0 * delta) / wd;
+            const sinCoeff = z * omega0 * a + delta * wd;
+            const cosCoeff = z * omega0 * delta - a * wd;
+            function underdampedValue(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return target - env * (a * Math.sin(wd * t) + delta * Math.cos(wd * t));
+            }
+            function underdampedVelocity(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return env * (sinCoeff * Math.sin(wd * t) + cosCoeff * Math.cos(wd * t));
+            }
+            value = underdampedValue;
+            velocityPerMs = underdampedVelocity;
+        }
+        else if (z === 1) {
+            // Critically damped (REQ-SPRING-002).
+            const c = v0 + omega0 * delta;
+            function criticalValue(t) {
+                return target - Math.exp(-omega0 * t) * (delta + c * t);
+            }
+            function criticalVelocity(t) {
+                return Math.exp(-omega0 * t) * (omega0 * c * t - v0);
+            }
+            value = criticalValue;
+            velocityPerMs = criticalVelocity;
+        }
+        else {
+            // Overdamped — pure-exponential form (REQ-SPRING-010). Both λ < 0 → no overflow, no sinh/cosh
+            // cap; the capped form (Motion #1207) is never used. λslow uses −ω0/(z+√(z²−1)) to avoid
+            // catastrophic cancellation at large z.
+            const root = Math.sqrt(z * z - 1);
+            const wd = omega0 * root;
+            const lambdaSlow = -omega0 / (z + root);
+            const lambdaFast = -omega0 * (z + root);
+            const cSlow = (v0 + z * omega0 * delta + wd * delta) / (2 * wd);
+            const cFast = delta - cSlow;
+            function overdampedValue(t) {
+                return target - (cSlow * Math.exp(lambdaSlow * t) + cFast * Math.exp(lambdaFast * t));
+            }
+            function overdampedVelocity(t) {
+                return -(cSlow * lambdaSlow * Math.exp(lambdaSlow * t) +
+                    cFast * lambdaFast * Math.exp(lambdaFast * t));
+            }
+            value = overdampedValue;
+            velocityPerMs = overdampedVelocity;
+        }
+        // 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: seed.from, velocity: seed.velocity, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const velocity = velocityPerMs(elapsedMs) * 1000; // → px/s (REQ-SPRING-008)
+                // Settle (REQ-SPRING-011): findSpring (duration) springs finish deterministically at
+                // t ≥ settleDuration; physics + visualDuration springs rest by speed AND delta. On done, snap to
+                // target (matches motion's next()), so an interruption re-seeds from an exact endpoint.
+                const done = settleDuration !== null
+                    ? elapsedMs >= settleDuration
+                    : Math.abs(velocity) <= restSpeed && Math.abs(target - current) <= restDelta;
+                out.value = done ? target : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/subscriptions.cjs

@@ -0,0 +1,74 @@
+"use strict";
+// Shared subscription registry for motion values: value-change listeners (`subscribe`) and named
+// lifecycle events (`on`). Neither path triggers a host render. Extracted so `MotionValueImpl` and
+// `DerivedValue` share one implementation instead of duplicating it (REQ-VALUE-001/002).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Subscriptions = void 0;
+exports.brandDerivedDependentListener = brandDerivedDependentListener;
+// Derived-dependent branding (REQ-VALUE-015): the MotionValue driver port classifies whether a
+// transported write reached a derived dependent without holding a graph handle. Derived values
+// brand their input subscription so observer presence is queryable without invoking listeners.
+const derivedDependentListeners = new WeakSet();
+/** @internal Brand a change listener as a derived value's input subscription. */
+function brandDerivedDependentListener(listener) {
+    derivedDependentListeners.add(listener);
+    return listener;
+}
+class Subscriptions {
+    #change = new Set();
+    // `on('change')` listeners take the latest value (the pinned payload, r15 a62d87e5f419);
+    // lifecycle listeners take none — one storage, lifecycle emission simply passes nothing.
+    #events = new Map();
+    subscribe(listener) {
+        this.#change.add(listener);
+        return () => {
+            this.#change.delete(listener);
+        };
+    }
+    on(event, listener) {
+        let listeners = this.#events.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.#events.set(event, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    /** Notify change subscribers and any `on('change')` listeners with the current value. */
+    emitChange(value) {
+        for (const listener of this.#change)
+            listener(value);
+        const listeners = this.#events.get('change');
+        if (listeners)
+            for (const listener of listeners)
+                listener(value);
+    }
+    /** Fire a named lifecycle event (e.g. `animationStart`/`animationComplete`). */
+    emit(event) {
+        const listeners = this.#events.get(event);
+        // Lifecycle listeners are payload-free by contract (the overloads above); the stored shape
+        // carries T only for the 'change' set.
+        if (listeners)
+            for (const listener of listeners)
+                listener();
+    }
+    /** @internal Driver-port seam: whether any change observer (`subscribe`/`on('change')`) exists. */
+    hasChangeObservers() {
+        return this.#change.size > 0 || (this.#events.get('change')?.size ?? 0) > 0;
+    }
+    /** @internal Driver-port seam: whether a branded derived dependent is among the change listeners. */
+    hasDerivedDependentObserver() {
+        for (const listener of this.#change) {
+            if (derivedDependentListeners.has(listener))
+                return true;
+        }
+        return false;
+    }
+    clear() {
+        this.#change.clear();
+        this.#events.clear();
+    }
+}
+exports.Subscriptions = Subscriptions;

package/dist/subscriptions.d.cts

@@ -0,0 +1,19 @@
+import type { MotionValueEvent, ValueChangeListener } from "./types.cjs";
+/** @internal Brand a change listener as a derived value's input subscription. */
+export declare function brandDerivedDependentListener<L extends (...args: never[]) => void>(listener: L): L;
+export declare class Subscriptions<T> {
+    #private;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    on(event: MotionValueEvent, listener: (latest: T) => void): () => void;
+    /** Notify change subscribers and any `on('change')` listeners with the current value. */
+    emitChange(value: T): void;
+    /** Fire a named lifecycle event (e.g. `animationStart`/`animationComplete`). */
+    emit(event: Exclude<MotionValueEvent, 'change'>): void;
+    /** @internal Driver-port seam: whether any change observer (`subscribe`/`on('change')`) exists. */
+    hasChangeObservers(): boolean;
+    /** @internal Driver-port seam: whether a branded derived dependent is among the change listeners. */
+    hasDerivedDependentObserver(): boolean;
+    clear(): void;
+}

package/dist/subscriptions.d.ts

@@ -0,0 +1,19 @@
+import type { MotionValueEvent, ValueChangeListener } from "./types.js";
+/** @internal Brand a change listener as a derived value's input subscription. */
+export declare function brandDerivedDependentListener<L extends (...args: never[]) => void>(listener: L): L;
+export declare class Subscriptions<T> {
+    #private;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    on(event: MotionValueEvent, listener: (latest: T) => void): () => void;
+    /** Notify change subscribers and any `on('change')` listeners with the current value. */
+    emitChange(value: T): void;
+    /** Fire a named lifecycle event (e.g. `animationStart`/`animationComplete`). */
+    emit(event: Exclude<MotionValueEvent, 'change'>): void;
+    /** @internal Driver-port seam: whether any change observer (`subscribe`/`on('change')`) exists. */
+    hasChangeObservers(): boolean;
+    /** @internal Driver-port seam: whether a branded derived dependent is among the change listeners. */
+    hasDerivedDependentObserver(): boolean;
+    clear(): void;
+}

package/dist/subscriptions.js

@@ -0,0 +1,69 @@
+// Shared subscription registry for motion values: value-change listeners (`subscribe`) and named
+// lifecycle events (`on`). Neither path triggers a host render. Extracted so `MotionValueImpl` and
+// `DerivedValue` share one implementation instead of duplicating it (REQ-VALUE-001/002).
+// Derived-dependent branding (REQ-VALUE-015): the MotionValue driver port classifies whether a
+// transported write reached a derived dependent without holding a graph handle. Derived values
+// brand their input subscription so observer presence is queryable without invoking listeners.
+const derivedDependentListeners = new WeakSet();
+/** @internal Brand a change listener as a derived value's input subscription. */
+export function brandDerivedDependentListener(listener) {
+    derivedDependentListeners.add(listener);
+    return listener;
+}
+export class Subscriptions {
+    #change = new Set();
+    // `on('change')` listeners take the latest value (the pinned payload, r15 a62d87e5f419);
+    // lifecycle listeners take none — one storage, lifecycle emission simply passes nothing.
+    #events = new Map();
+    subscribe(listener) {
+        this.#change.add(listener);
+        return () => {
+            this.#change.delete(listener);
+        };
+    }
+    on(event, listener) {
+        let listeners = this.#events.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.#events.set(event, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    /** Notify change subscribers and any `on('change')` listeners with the current value. */
+    emitChange(value) {
+        for (const listener of this.#change)
+            listener(value);
+        const listeners = this.#events.get('change');
+        if (listeners)
+            for (const listener of listeners)
+                listener(value);
+    }
+    /** Fire a named lifecycle event (e.g. `animationStart`/`animationComplete`). */
+    emit(event) {
+        const listeners = this.#events.get(event);
+        // Lifecycle listeners are payload-free by contract (the overloads above); the stored shape
+        // carries T only for the 'change' set.
+        if (listeners)
+            for (const listener of listeners)
+                listener();
+    }
+    /** @internal Driver-port seam: whether any change observer (`subscribe`/`on('change')`) exists. */
+    hasChangeObservers() {
+        return this.#change.size > 0 || (this.#events.get('change')?.size ?? 0) > 0;
+    }
+    /** @internal Driver-port seam: whether a branded derived dependent is among the change listeners. */
+    hasDerivedDependentObserver() {
+        for (const listener of this.#change) {
+            if (derivedDependentListeners.has(listener))
+                return true;
+        }
+        return false;
+    }
+    clear() {
+        this.#change.clear();
+        this.#events.clear();
+    }
+}

package/dist/subset/index.cjs

@@ -0,0 +1,23 @@
+"use strict";
+// Public surface of the SPEC-UNIVERSAL-SUBSET subsystem: the frozen universal-subset registry and its
+// entry schema types. Host-agnostic (REQ-SUBSET-010) — the native runtime, the web shim, and the
+// conformance runner all read this one object. Re-exported additively from the core index. The loud-fail
+// resolver (Milestone 2) and the normalizer (Milestone 3) join this surface as they land.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCapability = exports.epsilonFor = exports.resolveTargetCapabilities = exports.resolveCapability = exports.hostCapabilities = exports.UnsupportedCapabilityError = exports.UNIVERSAL_SUBSET = void 0;
+var registry_1 = require("./registry.cjs");
+Object.defineProperty(exports, "UNIVERSAL_SUBSET", { enumerable: true, get: function () { return registry_1.UNIVERSAL_SUBSET; } });
+// Loud-fail capability resolver (REQ-SUBSET-014): the fail-closed subset-membership gate + typed error.
+// The verdict-shaped resolution/normalization forms are CORE-INTERNAL (M3 r8 major
+// 4a5b686f1f5f): the ratified SUBSET public seam enumerates the throwing APIs only —
+// internal consumers import the verdicts from the modules directly.
+var resolve_1 = require("./resolve.cjs");
+Object.defineProperty(exports, "UnsupportedCapabilityError", { enumerable: true, get: function () { return resolve_1.UnsupportedCapabilityError; } });
+Object.defineProperty(exports, "hostCapabilities", { enumerable: true, get: function () { return resolve_1.hostCapabilities; } });
+Object.defineProperty(exports, "resolveCapability", { enumerable: true, get: function () { return resolve_1.resolveCapability; } });
+Object.defineProperty(exports, "resolveTargetCapabilities", { enumerable: true, get: function () { return resolve_1.resolveTargetCapabilities; } });
+// Per-value-type normalizer + epsilon floors (REQ-SUBSET-016): reduces engine-native encodings to one
+// comparable value, delegating to VALUE-TYPES (one parser, one set of floors).
+var normalize_1 = require("./normalize.cjs");
+Object.defineProperty(exports, "epsilonFor", { enumerable: true, get: function () { return normalize_1.epsilonFor; } });
+Object.defineProperty(exports, "normalizeCapability", { enumerable: true, get: function () { return normalize_1.normalizeCapability; } });

package/dist/subset/index.d.cts

@@ -0,0 +1,6 @@
+export { UNIVERSAL_SUBSET } from "./registry.cjs";
+export type { CapabilityClass, CapabilityEntry, ReferenceDisposition, ShippingStatus, Universality, ValueType, WebEnginePath, } from "./registry.cjs";
+export { UnsupportedCapabilityError, hostCapabilities, resolveCapability, resolveTargetCapabilities, } from "./resolve.cjs";
+export type { HostCapabilities, UnsupportedReason } from "./resolve.cjs";
+export { epsilonFor, normalizeCapability } from "./normalize.cjs";
+export type { NormalizedValue } from "./normalize.cjs";

package/dist/subset/index.d.ts

@@ -0,0 +1,6 @@
+export { UNIVERSAL_SUBSET } from "./registry.js";
+export type { CapabilityClass, CapabilityEntry, ReferenceDisposition, ShippingStatus, Universality, ValueType, WebEnginePath, } from "./registry.js";
+export { UnsupportedCapabilityError, hostCapabilities, resolveCapability, resolveTargetCapabilities, } from "./resolve.js";
+export type { HostCapabilities, UnsupportedReason } from "./resolve.js";
+export { epsilonFor, normalizeCapability } from "./normalize.js";
+export type { NormalizedValue } from "./normalize.js";

package/dist/subset/index.js

@@ -0,0 +1,13 @@
+// Public surface of the SPEC-UNIVERSAL-SUBSET subsystem: the frozen universal-subset registry and its
+// entry schema types. Host-agnostic (REQ-SUBSET-010) — the native runtime, the web shim, and the
+// conformance runner all read this one object. Re-exported additively from the core index. The loud-fail
+// resolver (Milestone 2) and the normalizer (Milestone 3) join this surface as they land.
+export { UNIVERSAL_SUBSET } from "./registry.js";
+// Loud-fail capability resolver (REQ-SUBSET-014): the fail-closed subset-membership gate + typed error.
+// The verdict-shaped resolution/normalization forms are CORE-INTERNAL (M3 r8 major
+// 4a5b686f1f5f): the ratified SUBSET public seam enumerates the throwing APIs only —
+// internal consumers import the verdicts from the modules directly.
+export { UnsupportedCapabilityError, hostCapabilities, resolveCapability, resolveTargetCapabilities, } from "./resolve.js";
+// Per-value-type normalizer + epsilon floors (REQ-SUBSET-016): reduces engine-native encodings to one
+// comparable value, delegating to VALUE-TYPES (one parser, one set of floors).
+export { epsilonFor, normalizeCapability } from "./normalize.js";

package/dist/subset/normalize.cjs

@@ -0,0 +1,90 @@
+"use strict";
+// SPEC-UNIVERSAL-SUBSET §3 — the per-value-type normalizer + epsilon floors (REQ-SUBSET-016). Reduces an
+// engine-native encoding (RN unitless dp number, web `px`/`deg`/`rad` string, any color syntax) to ONE
+// comparable value per value type so the cross-engine comparator compares like for like. It DELEGATES to
+// VALUE-TYPES for every parse and for the epsilon floors — there is exactly one parser and one set of
+// floors in the codebase (REQ-SUBSET-016 "adopted verbatim"); this file re-declares neither.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCapabilityVerdict = normalizeCapabilityVerdict;
+exports.normalizeCapability = normalizeCapability;
+exports.epsilonFor = epsilonFor;
+const value_types_1 = require("../value-types/index.cjs");
+const color_1 = require("../value-types/color.cjs");
+const numeric_1 = require("../value-types/numeric.cjs");
+const DEG_PER_RAD = 180 / Math.PI;
+// The units each numeric value type may carry and still reduce to ONE comparable value. `''` is the
+// engine-native unitless encoding (RN dp for length, a bare scalar for unitless, degrees for angle).
+// length is px + dp ONLY — vw/vh/% are viewport-/parent-relative and NOT px-comparable without a layout
+// context (they are excluded from the guaranteed subset, REQ-SUBSET-011/§8); an angle unit on a length
+// (or vice versa) is a category error. Anything outside the set fails loud rather than being silently
+// reduced to a bare number that would make incompatible encodings compare equal (REQ-SUBSET-016).
+const COMPATIBLE_UNITS = {
+    length: new Set(['', 'px']),
+    unitless: new Set(['']),
+    angle: new Set(['', 'deg', 'rad']),
+};
+const refuseNormalize = (message) => ({
+    value: null,
+    refusal: new Error(message),
+});
+function scalarVerdict(kind, engineValue) {
+    if (typeof engineValue === 'number')
+        return { value: engineValue, refusal: null };
+    const parsed = (0, numeric_1.parseNumericVerdict)(engineValue);
+    if (parsed.refusal !== null)
+        return refuseNormalize(parsed.refusal);
+    const { value, unit } = parsed.parsed;
+    if (!COMPATIBLE_UNITS[kind].has(unit)) {
+        const allowed = [...COMPATIBLE_UNITS[kind]].map((u) => u || '<unitless>').join(', ');
+        return refuseNormalize(`Incompatible unit '${unit}' for a ${kind} value ${JSON.stringify(engineValue)}: it cannot be ` +
+            `normalized as ${kind} (compatible units: ${allowed}).`);
+    }
+    return { value: kind === 'angle' && unit === 'rad' ? value * DEG_PER_RAD : value, refusal: null };
+}
+function normalizeCapabilityVerdict(entry, engineValue) {
+    switch (entry.valueType) {
+        case 'length':
+        case 'unitless':
+        case 'angle':
+            return scalarVerdict(entry.valueType, engineValue);
+        case 'rgba': {
+            const parsed = (0, color_1.parseColorVerdict)(String(engineValue));
+            return parsed.refusal !== null
+                ? refuseNormalize(parsed.refusal)
+                : { value: parsed.parsed, refusal: null };
+        }
+        case 'complex':
+        case 'gesture':
+        case 'discrete':
+            // Web-only compositor effects (complex), gestures, and discrete keywords (T23 B — compared
+            // by exact keyword equality, never a normalized scalar) have no cross-engine numeric value to
+            // compare — asking for one is a caller error, not a silent zero. Fail loud (REQ-SUBSET-014 ethos).
+            return refuseNormalize(`Capability '${entry.keys[0]}' (valueType '${entry.valueType}') has no cross-engine ` +
+                `normalized value — it is not a comparable animated scalar/color.`);
+    }
+    return refuseNormalize(`unreachable valueType`);
+}
+function normalizeCapability(entry, engineValue) {
+    const verdict = normalizeCapabilityVerdict(entry, engineValue);
+    if (verdict.refusal !== null)
+        throw verdict.refusal;
+    return verdict.value;
+}
+// The comparison epsilon FLOOR for a value type, imported verbatim from VALUE-TYPES (REQ-SUBSET-016).
+// complex/gesture have no comparison tolerance — requesting one is a loud failure, not a default.
+function epsilonFor(valueType) {
+    switch (valueType) {
+        case 'length':
+            return value_types_1.EPS_LENGTH;
+        case 'unitless':
+            return value_types_1.EPS_UNITLESS;
+        case 'angle':
+            return value_types_1.EPS_ANGLE;
+        case 'rgba':
+            return value_types_1.EPS_COLOR_CHANNEL;
+        case 'complex':
+        case 'gesture':
+        case 'discrete':
+            throw new Error(`valueType '${valueType}' has no comparison epsilon — it is not a cross-engine numeric value.`);
+    }
+}

package/dist/subset/normalize.d.cts

@@ -0,0 +1,10 @@
+import type { RGBA } from "../value-types/color.cjs";
+import type { CapabilityEntry, ValueType } from "./registry.cjs";
+export type NormalizedValue = number | RGBA;
+export interface NormalizeVerdict {
+    readonly value: NormalizedValue | null;
+    readonly refusal: Error | null;
+}
+export declare function normalizeCapabilityVerdict(entry: CapabilityEntry, engineValue: string | number): NormalizeVerdict;
+export declare function normalizeCapability(entry: CapabilityEntry, engineValue: string | number): NormalizedValue;
+export declare function epsilonFor(valueType: ValueType): number;

package/dist/subset/normalize.d.ts

@@ -0,0 +1,10 @@
+import type { RGBA } from "../value-types/color.js";
+import type { CapabilityEntry, ValueType } from "./registry.js";
+export type NormalizedValue = number | RGBA;
+export interface NormalizeVerdict {
+    readonly value: NormalizedValue | null;
+    readonly refusal: Error | null;
+}
+export declare function normalizeCapabilityVerdict(entry: CapabilityEntry, engineValue: string | number): NormalizeVerdict;
+export declare function normalizeCapability(entry: CapabilityEntry, engineValue: string | number): NormalizedValue;
+export declare function epsilonFor(valueType: ValueType): number;