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

package/dist/value-types/measure-resolve.js

@@ -0,0 +1,313 @@
+// REQ-VALUETYPE-013/014 — positional length measure-resolve (R13 value-breadth).
+// Pure recognition + arithmetic against a host-supplied layout context. No DOM, no RN.
+// Pin: motion-dom DOMKeyframesResolver measure path; catalog Animation-between-value-types,
+// height-auto*, Shared-layout-continuity* calc(100vw - 100px).
+//
+// Law: calc is first-class — never silent complex tokenization of interior numbers.
+import { parseNumeric, parseNumericVerdict } from "./numeric.js";
+const POSITIONAL_LENGTH_AXIS_SET = new Set([
+    'width',
+    'height',
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'x',
+    'y',
+]);
+/** The positional keys whose length STRINGS any engine may measure-resolve (REQ-VALUETYPE-013). */
+export const POSITIONAL_LENGTH_AXES = Object.freeze([
+    'width',
+    'height',
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'x',
+    'y',
+]);
+/** Runtime membership of the positional length axis set (cross-engine, one authority). */
+export function isPositionalLengthAxis(key) {
+    return POSITIONAL_LENGTH_AXIS_SET.has(key);
+}
+/**
+ * The ONE key-aware executable value matrix (review fe5d455ffde7 / 91d41675d511): a
+ * measure-resolved length string (scalar, or any keyframe element — a null FIRST element is the
+ * legal from-current marker) executes only on the positional keys, and `auto` only for
+ * width/height (the intrinsic content measure; the positional-auto remainder stays loud).
+ * Returns the named refusal, or null when the value rides another lane (number, non-string) or
+ * is executable. Used by every supplying boundary: core target validation (web + native), the
+ * variants dictionary gate, the gesture-state gate, and the style-base gate.
+ */
+export function executableLengthValueRefusal(key, value) {
+    if (typeof value === 'number')
+        return null;
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            const element = value[index];
+            if (element === null && index === 0)
+                continue;
+            const refusal = executableLengthValueRefusal(key, element);
+            if (refusal !== null)
+                return refusal;
+        }
+        return null;
+    }
+    if (typeof value !== 'string')
+        return null;
+    if (!isLengthTarget(value))
+        return null; // not a length string — the value-type lane owns it
+    if (!isPositionalLengthAxis(key)) {
+        return (`measure-resolved length strings (%/auto/simple calc/px) execute only on the positional ` +
+            `keys (${POSITIONAL_LENGTH_AXES.join(', ')}); '${key}' drives explicit numbers ` +
+            `(REQ-VALUETYPE-013)`);
+    }
+    if (isAuto(value) && key !== 'width' && key !== 'height') {
+        return (`not yet supported — positional 'auto' on '${key}' cannot measure-resolve ` +
+            '(REQ-VALUETYPE-013; auto resolves for width/height only, the intrinsic content measure)');
+    }
+    return null;
+}
+const CALC_OUTER_RE = /^calc\(\s*(.+)\s*\)$/i;
+// Pin-exercised simple binary forms only: term (op) term, each term a number/unit or nested not allowed.
+const SIMPLE_CALC_BODY_RE = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?(?:px|%|vw|vh)?)\s*([+-])\s*([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?(?:px|%|vw|vh)?)$/i;
+export function isAuto(raw) {
+    return raw.trim().toLowerCase() === 'auto';
+}
+/**
+ * Calc prefix detection (REQ-VALUETYPE-013): match `calc(` regardless of trailing `)`.
+ * Malformed/unclosed calc must NOT fall through to complex partial tokenization — parse
+ * routes it to a named refusal.
+ */
+export function isCalc(raw) {
+    return /^calc\s*\(/i.test(raw.trim());
+}
+export class MeasureResolveContextError extends Error {
+    reason;
+    axis;
+    constructor(message, reason, axis) {
+        super(message);
+        this.name = 'MeasureResolveContextError';
+        this.reason = reason;
+        this.axis = axis;
+    }
+}
+/** Layout/inset axes: % of parent. Transform x/y: % of the element box (pin unit-conversion). */
+function percentReferenceSize(axis, ctx) {
+    if (axis === 'x')
+        return { size: ctx.autoWidth, label: 'element width (transform %)' };
+    if (axis === 'y')
+        return { size: ctx.autoHeight, label: 'element height (transform %)' };
+    if (axis === 'width' || axis === 'left' || axis === 'right') {
+        return { size: ctx.parentWidth, label: 'parent width' };
+    }
+    return { size: ctx.parentHeight, label: 'parent height' };
+}
+// The supported auto matrix is DIMENSIONS only (review e2b1b9c7013b): width/height auto is the
+// intrinsic content measure (the shipped height-auto capability). Positional auto
+// (left/right/top/bottom/x/y) is NOT Motion-faithful as an element-box size — motion-dom reads
+// computed left/top, bounding-box right/bottom, and the current transform translation — so it
+// stays loud with the named "not yet supported" format, never a silently unrelated endpoint.
+// The reason is typed ('unsupported-axis-auto'): it must never read as a deferrable
+// missing-element-measure (hosts would park the key behind onLayout instead of refusing it).
+function autoRefusal(axis) {
+    if (axis === 'width' || axis === 'height')
+        return null;
+    return new MeasureResolveContextError(`not yet supported — positional 'auto' on '${axis}' cannot measure-resolve ` +
+        '(REQ-VALUETYPE-013; auto resolves for width/height only, the intrinsic content measure; ' +
+        'positional left/right/top/bottom/x/y auto is the unsupported remainder)', 'unsupported-axis-auto', axis);
+}
+function autoSize(axis, ctx) {
+    return axis === 'width' ? ctx.autoWidth : ctx.autoHeight;
+}
+// Inputs and context components are validated finite, but the ARITHMETIC can still overflow
+// (review 46e1c8fd339a): calc(1e308px + 1e308px), 1e308% of a large parent, or a cancellation
+// to NaN (Infinity − Infinity) would otherwise reach driver invariants as a raw Infinity/NaN.
+// The resolved result is boundary-checked through the same typed channel — never deferred.
+function assertFiniteResolved(value, axis) {
+    if (!Number.isFinite(value)) {
+        throw new MeasureResolveContextError(`measure-resolve on '${axis}' produced a non-finite result (${value}); finite inputs ` +
+            'overflowed the driver lane, which requires finite px (REQ-VALUETYPE-013)', 'non-finite-result', axis);
+    }
+    return value;
+}
+export function parseLengthTargetVerdict(raw) {
+    if (typeof raw === 'number') {
+        if (!Number.isFinite(raw)) {
+            return { parsed: null, refusal: `Cannot parse non-finite length target: ${raw}` };
+        }
+        return { parsed: { kind: 'px', value: raw }, refusal: null };
+    }
+    const s = raw.trim();
+    if (s.length === 0)
+        return { parsed: null, refusal: `Cannot parse empty length target` };
+    if (isAuto(s))
+        return { parsed: { kind: 'auto' }, refusal: null };
+    if (isCalc(s))
+        return parseSimpleCalcVerdict(s);
+    const verdict = parseNumericVerdict(s);
+    if (verdict.refusal !== null) {
+        return { parsed: null, refusal: verdict.refusal };
+    }
+    const { value, unit } = verdict.parsed;
+    if (unit === '' || unit === 'px')
+        return { parsed: { kind: 'px', value }, refusal: null };
+    if (unit === '%')
+        return { parsed: { kind: 'percent', value }, refusal: null };
+    if (unit === 'vw')
+        return { parsed: { kind: 'vw', value }, refusal: null };
+    if (unit === 'vh')
+        return { parsed: { kind: 'vh', value }, refusal: null };
+    return {
+        parsed: null,
+        refusal: `not yet supported — length unit "${unit}" in ${JSON.stringify(raw)} cannot measure-resolve ` +
+            `(REQ-VALUETYPE-013; supported: number/px/%/vw/vh/auto/simple calc)`,
+    };
+}
+/** Parse a single length term used inside simple calc or as a standalone target. */
+export function parseLengthTarget(raw) {
+    const verdict = parseLengthTargetVerdict(raw);
+    if (verdict.refusal !== null)
+        throw new Error(verdict.refusal);
+    return verdict.parsed;
+}
+/**
+ * Total predicate: whether `raw` is a measure-resolved length form (no throw).
+ * Drivers use this at recognition boundaries — never bare try/catch over parseLengthTarget
+ * (unexpected faults must not be classified as “not a length”).
+ */
+export function isLengthTarget(raw) {
+    return parseLengthTargetVerdict(raw).refusal === null;
+}
+/** Verdict-shaped simple calc — no catch: unexpected faults from RegExp/String propagate. */
+function parseSimpleCalcVerdict(raw) {
+    const s = raw.trim();
+    const outer = CALC_OUTER_RE.exec(s);
+    if (outer === null) {
+        return {
+            parsed: null,
+            refusal: `not yet supported — malformed calc ${JSON.stringify(raw)} (REQ-VALUETYPE-013)`,
+        };
+    }
+    const body = outer[1].trim();
+    // Nested parens / var() / multi-ops → loud incomplete (never partial complex).
+    if (body.includes('(') || /var\s*\(/i.test(body) || body.includes('*') || body.includes('/')) {
+        return {
+            parsed: null,
+            refusal: `not yet supported — calc form ${JSON.stringify(raw)} is outside the pin simple binary set ` +
+                `(REQ-VALUETYPE-013(d))`,
+        };
+    }
+    const m = SIMPLE_CALC_BODY_RE.exec(body);
+    if (m === null) {
+        return {
+            parsed: null,
+            refusal: `not yet supported — calc form ${JSON.stringify(raw)} is outside the pin simple binary set ` +
+                `(REQ-VALUETYPE-013(d))`,
+        };
+    }
+    const leftVerdict = parseLengthTargetVerdict(m[1]);
+    if (leftVerdict.refusal !== null)
+        return leftVerdict;
+    const rightVerdict = parseLengthTargetVerdict(m[3]);
+    if (rightVerdict.refusal !== null)
+        return rightVerdict;
+    const left = leftVerdict.parsed;
+    const right = rightVerdict.parsed;
+    const op = m[2];
+    if (left.kind === 'calc' ||
+        right.kind === 'calc' ||
+        left.kind === 'auto' ||
+        right.kind === 'auto') {
+        return {
+            parsed: null,
+            refusal: `not yet supported — nested/auto inside calc ${JSON.stringify(raw)} (REQ-VALUETYPE-013(d))`,
+        };
+    }
+    return { parsed: { kind: 'calc', raw: s, left, op, right }, refusal: null };
+}
+function resolveParsed(parsed, axis, ctx) {
+    switch (parsed.kind) {
+        case 'px':
+            return parsed.value;
+        case 'percent': {
+            const { size, label } = percentReferenceSize(axis, ctx);
+            if (size === undefined || !Number.isFinite(size)) {
+                const reason = axis === 'x' || axis === 'y' ? 'missing-element-measure' : 'missing-parent';
+                throw new MeasureResolveContextError(`Cannot measure-resolve percent length on ${axis}: ${label} missing from layout context ` +
+                    `(REQ-VALUETYPE-013)`, reason, axis);
+            }
+            return assertFiniteResolved((parsed.value / 100) * size, axis);
+        }
+        case 'vw': {
+            if (ctx.viewportWidth === undefined || !Number.isFinite(ctx.viewportWidth)) {
+                throw new MeasureResolveContextError(`Cannot measure-resolve vw length: viewportWidth missing from layout context (REQ-VALUETYPE-013)`, 'missing-viewport', axis);
+            }
+            return assertFiniteResolved((parsed.value / 100) * ctx.viewportWidth, axis);
+        }
+        case 'vh': {
+            if (ctx.viewportHeight === undefined || !Number.isFinite(ctx.viewportHeight)) {
+                throw new MeasureResolveContextError(`Cannot measure-resolve vh length: viewportHeight missing from layout context (REQ-VALUETYPE-013)`, 'missing-viewport', axis);
+            }
+            return assertFiniteResolved((parsed.value / 100) * ctx.viewportHeight, axis);
+        }
+        case 'auto': {
+            const refusal = autoRefusal(axis);
+            if (refusal !== null)
+                throw refusal;
+            const size = autoSize(axis, ctx);
+            if (size === undefined || !Number.isFinite(size)) {
+                throw new MeasureResolveContextError(`Cannot measure-resolve auto on ${axis}: auto measure missing from layout context (REQ-VALUETYPE-013)`, 'missing-element-measure', axis);
+            }
+            return size;
+        }
+        case 'calc': {
+            const l = resolveParsed(parsed.left, axis, ctx);
+            const r = resolveParsed(parsed.right, axis, ctx);
+            return assertFiniteResolved(parsed.op === '+' ? l + r : l - r, axis);
+        }
+    }
+}
+/**
+ * Resolve a length target to px using host layout context (Motion measure-then-mix law).
+ * Pure: all geometry arrives in `ctx`.
+ */
+export function resolveLengthToPx(raw, axis, ctx) {
+    return resolveParsed(parseLengthTarget(raw), axis, ctx);
+}
+function familyOf(parsed) {
+    if (parsed.kind === 'px')
+        return 'px';
+    if (parsed.kind === 'calc')
+        return 'calc';
+    return parsed.kind;
+}
+/**
+ * Motion needsMeasurement — the pin's family decision (review ae0a42832d85): the SAME relative
+ * unit family returns WITHOUT a measure (%→%, vw→vw, vh→vh interpolate on the unit lane — on
+ * native, measured-endpoint animation per the recorded divergence, never a unit-string
+ * generator). auto and calc always measure; mixed families measure.
+ */
+export function needsLengthMeasureResolve(from, to) {
+    const a = parseLengthTarget(from);
+    const b = parseLengthTarget(to);
+    if (a.kind === 'auto' || b.kind === 'auto')
+        return true;
+    if (a.kind === 'calc' || b.kind === 'calc')
+        return true;
+    // Same relative unit family → the pin returns immediately (no measure).
+    if (a.kind === 'percent' && b.kind === 'percent')
+        return false;
+    if (a.kind === 'vw' && b.kind === 'vw')
+        return false;
+    if (a.kind === 'vh' && b.kind === 'vh')
+        return false;
+    if (a.kind === 'percent' || b.kind === 'percent')
+        return true;
+    if (a.kind === 'vw' || b.kind === 'vw' || a.kind === 'vh' || b.kind === 'vh')
+        return true;
+    // both px-family
+    return familyOf(a) !== familyOf(b);
+}
+// Re-export parseNumeric for callers that only need the numeric path after resolve.
+export { parseNumeric };

package/dist/value-types/mix.cjs

@@ -0,0 +1,90 @@
+"use strict";
+// The unified mix() seam (SPEC-VALUE-TYPES §3, REQ-VALUETYPE-003/009/012). One family dispatcher over the
+// numeric/color/complex value types: `parseValue` decomposes a raw string into a tagged TYPED value,
+// `mix` interpolates two typed values of the same family, `transformValue` projects a typed value back to
+// its committed string/number. Host-agnostic (REQ-VALUETYPE-011).
+//
+// The typed value — NOT a string — is the canonical carrier (REQ-VALUETYPE-012): the native driver writes
+// it to shared values directly; string recomposition is one deterministic projection for the web commit
+// path / conformance. Holding the DECOMPOSED typed value across retargets is lossless where a
+// string round-trip would drift (REQ-VALUETYPE-009 keep-current). `progress` is always a normalized [0,1]
+// fraction here; SPRING divides its internal [0,100] progress by 100 before this seam — the sole handoff
+// (REQ-VALUETYPE-003).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseValue = parseValue;
+exports.mix = mix;
+exports.transformValue = transformValue;
+const color_1 = require("./color.cjs");
+const complex_1 = require("./complex.cjs");
+const discrete_1 = require("./discrete.cjs");
+const measure_resolve_1 = require("./measure-resolve.cjs");
+const numeric_1 = require("./numeric.cjs");
+// Decompose a raw string into a tagged typed value. Detection order:
+// auto → calc → numeric → single-color → discrete keyword → complex.
+// auto/calc BEFORE complex is load-bearing (REQ-VALUETYPE-013): calc(50% + 100px) must never
+// partial-tokenizeize as complex slots. Discrete AFTER color so named colors keep their family,
+// BEFORE complex so single keywords (display/visibility values) parse instead of throwing the
+// zero-token complex refusal (T23 B — parseComplex keeps that throw for every other shape).
+// An implicit base and an explicit target both flow through
+// this identical parser (REQ-VALUETYPE-009).
+function parseValue(raw) {
+    if ((0, measure_resolve_1.isAuto)(raw))
+        return { kind: 'auto' };
+    if ((0, measure_resolve_1.isCalc)(raw)) {
+        // parseLengthTarget enforces pin simple-binary set; unsupported remainder throws loud.
+        const parsed = (0, measure_resolve_1.parseLengthTarget)(raw);
+        if (parsed.kind !== 'calc') {
+            throw new Error(`Internal: isCalc but parseLengthTarget kind is ${parsed.kind}`);
+        }
+        return { kind: 'calc', value: parsed };
+    }
+    if ((0, numeric_1.isNumeric)(raw))
+        return { kind: 'numeric', value: (0, numeric_1.parseNumeric)(raw) };
+    if ((0, color_1.isColor)(raw))
+        return { kind: 'color', value: (0, color_1.parseColor)(raw) };
+    if ((0, discrete_1.isDiscreteKeyword)(raw))
+        return { kind: 'discrete', value: raw };
+    return { kind: 'complex', value: (0, complex_1.parseComplex)(raw) };
+}
+// Interpolate two typed values of the SAME family. A cross-family pair is a loud failure (REQ-VALUETYPE-008
+// — no silent coercion). Output is a typed value (REQ-VALUETYPE-012).
+// auto/calc never mix here — resolve to px first (REQ-VALUETYPE-013(b)).
+function mix(from, to, progress) {
+    if (from.kind === 'auto' || to.kind === 'auto' || from.kind === 'calc' || to.kind === 'calc') {
+        throw new Error(`Cannot mix unresolved ${from.kind === 'auto' || from.kind === 'calc' ? from.kind : to.kind} ` +
+            `length — measure-resolve to px before mix (REQ-VALUETYPE-013)`);
+    }
+    if (from.kind === 'numeric' && to.kind === 'numeric') {
+        return { kind: 'numeric', value: (0, numeric_1.mixNumeric)(from.value, to.value, progress) };
+    }
+    if (from.kind === 'color' && to.kind === 'color') {
+        return { kind: 'color', value: (0, color_1.mixColor)(from.value, to.value, progress) };
+    }
+    if (from.kind === 'complex' && to.kind === 'complex') {
+        return { kind: 'complex', value: (0, complex_1.mixComplex)(from.value, to.value, progress) };
+    }
+    if (from.kind === 'discrete' && to.kind === 'discrete') {
+        // The pin's TWO discrete paths (REQ-VALUETYPE-015): the mixVisibility step when an endpoint
+        // is invisible and its counterpart has zero values, else the zero-slot TARGET constant.
+        return { kind: 'discrete', value: (0, discrete_1.mixDiscrete)(from.value, to.value, progress) };
+    }
+    throw new Error(`Cannot mix value families: origin is "${from.kind}", target is "${to.kind}"`);
+}
+// Project a typed value to its committed form (REQ-VALUETYPE-012). A plain number stays a number
+// (identity); everything else is a string. This is the ONLY place a typed value becomes a string.
+function transformValue(v) {
+    switch (v.kind) {
+        case 'numeric':
+            return (0, numeric_1.transformNumeric)(v.value);
+        case 'color':
+            return (0, color_1.transformColor)(v.value);
+        case 'complex':
+            return (0, complex_1.transformComplex)(v.value);
+        case 'auto':
+            return 'auto';
+        case 'calc':
+            return v.value.raw;
+        case 'discrete':
+            return (0, discrete_1.transformDiscrete)(v.value);
+    }
+}

package/dist/value-types/mix.d.cts

@@ -0,0 +1,27 @@
+import { type RGBA } from "./color.cjs";
+import { type ComplexValue } from "./complex.cjs";
+import { type ParsedLengthTarget } from "./measure-resolve.cjs";
+import { type NumericValue } from "./numeric.cjs";
+export type TypedValue = {
+    readonly kind: 'numeric';
+    readonly value: NumericValue;
+} | {
+    readonly kind: 'color';
+    readonly value: RGBA;
+} | {
+    readonly kind: 'complex';
+    readonly value: ComplexValue;
+} | {
+    readonly kind: 'auto';
+} | {
+    readonly kind: 'calc';
+    readonly value: Extract<ParsedLengthTarget, {
+        kind: 'calc';
+    }>;
+} | {
+    readonly kind: 'discrete';
+    readonly value: string;
+};
+export declare function parseValue(raw: string): TypedValue;
+export declare function mix(from: TypedValue, to: TypedValue, progress: number): TypedValue;
+export declare function transformValue(v: TypedValue): string | number;

package/dist/value-types/mix.d.ts

@@ -0,0 +1,27 @@
+import { type RGBA } from "./color.js";
+import { type ComplexValue } from "./complex.js";
+import { type ParsedLengthTarget } from "./measure-resolve.js";
+import { type NumericValue } from "./numeric.js";
+export type TypedValue = {
+    readonly kind: 'numeric';
+    readonly value: NumericValue;
+} | {
+    readonly kind: 'color';
+    readonly value: RGBA;
+} | {
+    readonly kind: 'complex';
+    readonly value: ComplexValue;
+} | {
+    readonly kind: 'auto';
+} | {
+    readonly kind: 'calc';
+    readonly value: Extract<ParsedLengthTarget, {
+        kind: 'calc';
+    }>;
+} | {
+    readonly kind: 'discrete';
+    readonly value: string;
+};
+export declare function parseValue(raw: string): TypedValue;
+export declare function mix(from: TypedValue, to: TypedValue, progress: number): TypedValue;
+export declare function transformValue(v: TypedValue): string | number;

package/dist/value-types/mix.js

@@ -0,0 +1,85 @@
+// The unified mix() seam (SPEC-VALUE-TYPES §3, REQ-VALUETYPE-003/009/012). One family dispatcher over the
+// numeric/color/complex value types: `parseValue` decomposes a raw string into a tagged TYPED value,
+// `mix` interpolates two typed values of the same family, `transformValue` projects a typed value back to
+// its committed string/number. Host-agnostic (REQ-VALUETYPE-011).
+//
+// The typed value — NOT a string — is the canonical carrier (REQ-VALUETYPE-012): the native driver writes
+// it to shared values directly; string recomposition is one deterministic projection for the web commit
+// path / conformance. Holding the DECOMPOSED typed value across retargets is lossless where a
+// string round-trip would drift (REQ-VALUETYPE-009 keep-current). `progress` is always a normalized [0,1]
+// fraction here; SPRING divides its internal [0,100] progress by 100 before this seam — the sole handoff
+// (REQ-VALUETYPE-003).
+import { isColor, mixColor, parseColor, transformColor } from "./color.js";
+import { mixComplex, parseComplex, transformComplex } from "./complex.js";
+import { isDiscreteKeyword, mixDiscrete, transformDiscrete } from "./discrete.js";
+import { isAuto, isCalc, parseLengthTarget } from "./measure-resolve.js";
+import { isNumeric, mixNumeric, parseNumeric, transformNumeric } from "./numeric.js";
+// Decompose a raw string into a tagged typed value. Detection order:
+// auto → calc → numeric → single-color → discrete keyword → complex.
+// auto/calc BEFORE complex is load-bearing (REQ-VALUETYPE-013): calc(50% + 100px) must never
+// partial-tokenizeize as complex slots. Discrete AFTER color so named colors keep their family,
+// BEFORE complex so single keywords (display/visibility values) parse instead of throwing the
+// zero-token complex refusal (T23 B — parseComplex keeps that throw for every other shape).
+// An implicit base and an explicit target both flow through
+// this identical parser (REQ-VALUETYPE-009).
+export function parseValue(raw) {
+    if (isAuto(raw))
+        return { kind: 'auto' };
+    if (isCalc(raw)) {
+        // parseLengthTarget enforces pin simple-binary set; unsupported remainder throws loud.
+        const parsed = parseLengthTarget(raw);
+        if (parsed.kind !== 'calc') {
+            throw new Error(`Internal: isCalc but parseLengthTarget kind is ${parsed.kind}`);
+        }
+        return { kind: 'calc', value: parsed };
+    }
+    if (isNumeric(raw))
+        return { kind: 'numeric', value: parseNumeric(raw) };
+    if (isColor(raw))
+        return { kind: 'color', value: parseColor(raw) };
+    if (isDiscreteKeyword(raw))
+        return { kind: 'discrete', value: raw };
+    return { kind: 'complex', value: parseComplex(raw) };
+}
+// Interpolate two typed values of the SAME family. A cross-family pair is a loud failure (REQ-VALUETYPE-008
+// — no silent coercion). Output is a typed value (REQ-VALUETYPE-012).
+// auto/calc never mix here — resolve to px first (REQ-VALUETYPE-013(b)).
+export function mix(from, to, progress) {
+    if (from.kind === 'auto' || to.kind === 'auto' || from.kind === 'calc' || to.kind === 'calc') {
+        throw new Error(`Cannot mix unresolved ${from.kind === 'auto' || from.kind === 'calc' ? from.kind : to.kind} ` +
+            `length — measure-resolve to px before mix (REQ-VALUETYPE-013)`);
+    }
+    if (from.kind === 'numeric' && to.kind === 'numeric') {
+        return { kind: 'numeric', value: mixNumeric(from.value, to.value, progress) };
+    }
+    if (from.kind === 'color' && to.kind === 'color') {
+        return { kind: 'color', value: mixColor(from.value, to.value, progress) };
+    }
+    if (from.kind === 'complex' && to.kind === 'complex') {
+        return { kind: 'complex', value: mixComplex(from.value, to.value, progress) };
+    }
+    if (from.kind === 'discrete' && to.kind === 'discrete') {
+        // The pin's TWO discrete paths (REQ-VALUETYPE-015): the mixVisibility step when an endpoint
+        // is invisible and its counterpart has zero values, else the zero-slot TARGET constant.
+        return { kind: 'discrete', value: mixDiscrete(from.value, to.value, progress) };
+    }
+    throw new Error(`Cannot mix value families: origin is "${from.kind}", target is "${to.kind}"`);
+}
+// Project a typed value to its committed form (REQ-VALUETYPE-012). A plain number stays a number
+// (identity); everything else is a string. This is the ONLY place a typed value becomes a string.
+export function transformValue(v) {
+    switch (v.kind) {
+        case 'numeric':
+            return transformNumeric(v.value);
+        case 'color':
+            return transformColor(v.value);
+        case 'complex':
+            return transformComplex(v.value);
+        case 'auto':
+            return 'auto';
+        case 'calc':
+            return v.value.raw;
+        case 'discrete':
+            return transformDiscrete(v.value);
+    }
+}

package/dist/value-types/named-colors.cjs

@@ -0,0 +1,61 @@
+"use strict";
+// CSS Color Module Level 4 named colors → canonical RGBA (REQ-VALUETYPE-005). Authored from the CSS
+// spec, NOT motion-dom (which has no named-color table — `color.parse("red")` returns garbage; on web it
+// delegates named colors to the DOM) and NOT the DOM/react-native, so the SAME raw string resolves to the
+// SAME RGBA on both engines with no host in the loop. `transparent` is the CSS keyword for rgba(0,0,0,0).
+// This is a curated common subset (the 16 CSS Level-2 keywords + `transparent` + frequent extended
+// keywords); full-L4 completeness is the vetoable open decision (SPEC-VALUE-TYPES §8). Keys are lowercase;
+// the lookup lowercases its input.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAMED_COLORS = void 0;
+const opaque = (red, green, blue) => ({ red, green, blue, alpha: 1 });
+exports.NAMED_COLORS = {
+    transparent: { red: 0, green: 0, blue: 0, alpha: 0 },
+    // CSS Level 2 (basic) keywords
+    black: opaque(0, 0, 0),
+    silver: opaque(192, 192, 192),
+    gray: opaque(128, 128, 128),
+    white: opaque(255, 255, 255),
+    maroon: opaque(128, 0, 0),
+    red: opaque(255, 0, 0),
+    purple: opaque(128, 0, 128),
+    fuchsia: opaque(255, 0, 255),
+    green: opaque(0, 128, 0),
+    lime: opaque(0, 255, 0),
+    olive: opaque(128, 128, 0),
+    yellow: opaque(255, 255, 0),
+    navy: opaque(0, 0, 128),
+    blue: opaque(0, 0, 255),
+    teal: opaque(0, 128, 128),
+    aqua: opaque(0, 255, 255),
+    // Frequent extended keywords + spelling aliases
+    cyan: opaque(0, 255, 255), // alias of aqua
+    magenta: opaque(255, 0, 255), // alias of fuchsia
+    grey: opaque(128, 128, 128), // alias of gray
+    orange: opaque(255, 165, 0),
+    pink: opaque(255, 192, 203),
+    brown: opaque(165, 42, 42),
+    gold: opaque(255, 215, 0),
+    indigo: opaque(75, 0, 130),
+    violet: opaque(238, 130, 238),
+    darkgray: opaque(169, 169, 169),
+    darkgrey: opaque(169, 169, 169),
+    lightgray: opaque(211, 211, 211),
+    lightgrey: opaque(211, 211, 211),
+    dimgray: opaque(105, 105, 105),
+    slategray: opaque(112, 128, 144),
+    whitesmoke: opaque(245, 245, 245),
+    lightblue: opaque(173, 216, 230),
+    darkblue: opaque(0, 0, 139),
+    lightgreen: opaque(144, 238, 144),
+    darkgreen: opaque(0, 100, 0),
+    coral: opaque(255, 127, 80),
+    salmon: opaque(250, 128, 114),
+    tomato: opaque(255, 99, 71),
+    crimson: opaque(220, 20, 60),
+    skyblue: opaque(135, 206, 235),
+    steelblue: opaque(70, 130, 180),
+    turquoise: opaque(64, 224, 208),
+    beige: opaque(245, 245, 220),
+    ivory: opaque(255, 255, 240),
+};

package/dist/value-types/named-colors.d.cts

@@ -0,0 +1,2 @@
+import type { RGBA } from "./color.cjs";
+export declare const NAMED_COLORS: Readonly<Record<string, RGBA>>;

package/dist/value-types/named-colors.d.ts

@@ -0,0 +1,2 @@
+import type { RGBA } from "./color.js";
+export declare const NAMED_COLORS: Readonly<Record<string, RGBA>>;