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

package/dist/value-types/color.cjs

@@ -0,0 +1,220 @@
+"use strict";
+// Color value types (SPEC-VALUE-TYPES §3, REQ-VALUETYPE-005/006). Pure parse (hex/rgb/hsl/named → RGBA),
+// gamma-aware linear-light channel mix, and recompose. Host-agnostic (REQ-VALUETYPE-011): no DOM CSSOM,
+// no react-native processColor, no locale formatting — the named-color table (./named-colors) and the
+// HSL→RGB transform are this subsystem's own, so the same raw string yields the same RGBA on both engines.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseColorVerdict = parseColorVerdict;
+exports.parseColor = parseColor;
+exports.isColor = isColor;
+exports.hslaToRgba = hslaToRgba;
+exports.mixColor = mixColor;
+exports.transformColor = transformColor;
+const named_colors_1 = require("./named-colors.cjs");
+const refuseColor = (message) => ({ colorRefusal: message });
+function isColorRefusal(value) {
+    // OWN-property discriminant (M3 r8 major dbffcd947d13): the `in` operator walks the
+    // prototype chain, so a polluted `Object.prototype.colorRefusal` would turn every VALID
+    // RGBA result into a refusal. hasOwn is pollution-invisible.
+    return typeof value === 'object' && value !== null && Object.hasOwn(value, 'colorRefusal');
+}
+function parseColorVerdict(raw) {
+    const s = raw.trim();
+    const lower = s.toLowerCase();
+    const named = named_colors_1.NAMED_COLORS[lower];
+    if (named !== undefined)
+        return { parsed: named, refusal: null };
+    let outcome = null;
+    if (s.startsWith('#'))
+        outcome = parseHex(s);
+    else if (lower.startsWith('rgb'))
+        outcome = parseRgb(s);
+    else if (lower.startsWith('hsl'))
+        outcome = parseHsl(s);
+    if (outcome === null) {
+        return { parsed: null, refusal: `Cannot parse ${JSON.stringify(raw)} as a color` };
+    }
+    return isColorRefusal(outcome)
+        ? { parsed: null, refusal: outcome.colorRefusal }
+        : { parsed: outcome, refusal: null };
+}
+function parseColor(raw) {
+    const verdict = parseColorVerdict(raw);
+    if (verdict.refusal !== null)
+        throw new Error(verdict.refusal);
+    return verdict.parsed;
+}
+// Family predicate for the dispatcher (mix.ts): is the WHOLE raw string a single color? A named-table
+// hit, a hex ATTEMPT, or a single rgb/hsl function. This recognizes the SHAPE, not validity: a "#"
+// single token (`# ` + alphanumerics, no whitespace) is always a hex attempt, and `parseColor` is the
+// strict validator that throws on a malformed one (wrong length/charset). Recognizing the shape here is
+// what keeps a malformed hex like "#12" a LOUD color failure (REQ-VALUETYPE-008) instead of silently
+// falling through to the complex tokenizer, which would treat "#" as a literal template and mix a bogus
+// number out of it. Mirrors the rgb/hsl branch, which likewise defers channel validity to parseColor.
+function isColor(raw) {
+    const s = raw.trim();
+    if (named_colors_1.NAMED_COLORS[s.toLowerCase()] !== undefined)
+        return true;
+    if (s.startsWith('#'))
+        return /^#[0-9a-z]+$/i.test(s);
+    return /^(?:rgba?|hsla?)\([^)]*\)$/i.test(s);
+}
+// #rgb, #rgba, #rrggbb, #rrggbbaa. Short forms double each nibble (matching CSS + motion).
+function parseHex(s) {
+    const h = s.slice(1);
+    const hex2 = (a, b) => Number.parseInt(a + b, 16);
+    let red;
+    let green;
+    let blue;
+    let alpha255 = 255;
+    if (h.length === 3 || h.length === 4) {
+        red = hex2(h.charAt(0), h.charAt(0));
+        green = hex2(h.charAt(1), h.charAt(1));
+        blue = hex2(h.charAt(2), h.charAt(2));
+        if (h.length === 4)
+            alpha255 = hex2(h.charAt(3), h.charAt(3));
+    }
+    else if (h.length === 6 || h.length === 8) {
+        red = hex2(h.charAt(0), h.charAt(1));
+        green = hex2(h.charAt(2), h.charAt(3));
+        blue = hex2(h.charAt(4), h.charAt(5));
+        if (h.length === 8)
+            alpha255 = hex2(h.charAt(6), h.charAt(7));
+    }
+    else {
+        return refuseColor(`Invalid hex color ${JSON.stringify(s)} (need 3/4/6/8 digits)`);
+    }
+    if (!/^[0-9a-f]+$/i.test(h) || Number.isNaN(red) || Number.isNaN(green) || Number.isNaN(blue)) {
+        return refuseColor(`Invalid hex color ${JSON.stringify(s)}`);
+    }
+    return { red, green, blue, alpha: alpha255 / 255 };
+}
+// Split the "(...)" argument list of an rgb()/rgba()/hsl()/hsla() function into trimmed channel tokens.
+function channels(prefix, s, label) {
+    const m = prefix.exec(s.trim());
+    if (m === null || m[1] === undefined) {
+        return refuseColor(`Invalid ${label} color ${JSON.stringify(s)}`);
+    }
+    const parts = m[1].split(',').map((p) => p.trim());
+    if (parts.length < 3 || parts.length > 4) {
+        return refuseColor(`${label} color needs 3 or 4 channels: ${JSON.stringify(s)}`);
+    }
+    return parts;
+}
+function num(token, s) {
+    const n = token === undefined ? Number.NaN : Number.parseFloat(token);
+    if (Number.isNaN(n)) {
+        return refuseColor(`Invalid color channel ${JSON.stringify(token)} in ${JSON.stringify(s)}`);
+    }
+    return n;
+}
+function parseRgb(s) {
+    const parts = channels(/^rgba?\(([^)]*)\)$/i, s, 'rgb');
+    if (isColorRefusal(parts))
+        return parts;
+    const red = num(parts[0], s);
+    if (isColorRefusal(red))
+        return red;
+    const green = num(parts[1], s);
+    if (isColorRefusal(green))
+        return green;
+    const blue = num(parts[2], s);
+    if (isColorRefusal(blue))
+        return blue;
+    const alpha = parts.length === 4 ? num(parts[3], s) : 1;
+    if (isColorRefusal(alpha))
+        return alpha;
+    return { red, green, blue, alpha };
+}
+function parseHsl(s) {
+    const parts = channels(/^hsla?\(([^)]*)\)$/i, s, 'hsl');
+    if (isColorRefusal(parts))
+        return parts;
+    const hue = num(parts[0], s);
+    if (isColorRefusal(hue))
+        return hue;
+    const saturation = num(parts[1], s);
+    if (isColorRefusal(saturation))
+        return saturation;
+    const lightness = num(parts[2], s);
+    if (isColorRefusal(lightness))
+        return lightness;
+    // parseFloat stops at the trailing "%" on saturation/lightness.
+    const alpha = parts.length === 4 ? num(parts[3], s) : 1;
+    if (isColorRefusal(alpha))
+        return alpha;
+    return hslaToRgba(hue, saturation, lightness, alpha);
+}
+// Standard HSL→RGB (matches motion-dom's hslaToRgba): rgb rounded to integers, alpha passed through.
+// Module-internal by the value-types barrel's own law; `motion-mix.ts` imports it directly for the
+// pin's HSLA-object color arm (REQ-VALUETYPE-016) rather than growing a second conversion.
+function hslaToRgba(hue, saturation, lightness, alpha) {
+    const h = hue / 360;
+    const s = saturation / 100;
+    const l = lightness / 100;
+    let red;
+    let green;
+    let blue;
+    if (s === 0) {
+        red = green = blue = l;
+    }
+    else {
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        red = hueToRgb(p, q, h + 1 / 3);
+        green = hueToRgb(p, q, h);
+        blue = hueToRgb(p, q, h - 1 / 3);
+    }
+    return {
+        red: Math.round(red * 255),
+        green: Math.round(green * 255),
+        blue: Math.round(blue * 255),
+        alpha,
+    };
+}
+function hueToRgb(p, q, tRaw) {
+    let t = tRaw;
+    if (t < 0)
+        t += 1;
+    if (t > 1)
+        t -= 1;
+    if (t < 1 / 6)
+        return p + (q - p) * 6 * t;
+    if (t < 1 / 2)
+        return q;
+    if (t < 2 / 3)
+        return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+}
+// REQ-VALUETYPE-006: linear-light (gamma-aware) channel mix, NOT a naive average. `sqrt` of the
+// squared-channel interpolation — motion's mixLinearColor. Alpha mixes linearly.
+function mixLinearColor(from, to, v) {
+    return Math.sqrt(Math.max(0, v * (to * to - from * from) + from * from));
+}
+function mixColor(from, to, progress) {
+    return {
+        red: mixLinearColor(from.red, to.red, progress),
+        green: mixLinearColor(from.green, to.green, progress),
+        blue: mixLinearColor(from.blue, to.blue, progress),
+        alpha: from.alpha + (to.alpha - from.alpha) * progress,
+    };
+}
+// String projection (REQ-VALUETYPE-006): rgb round→clamp[0,255]; alpha sanitized to Motion's 5-dp rule,
+// formatted byte-identically to motion-dom's `rgba(r, g, b, a)` recompose.
+function clampChannel(v) {
+    return Math.min(255, Math.max(0, Math.round(v)));
+}
+function sanitize(v) {
+    return Math.round(v * 1e5) / 1e5;
+}
+// Alpha is CLAMPED to [0,1] before the 5-dp sanitize, byte-identical to motion-dom's rgba formatter
+// (`sanitize(alpha.transform(a))` where `alpha.transform = clamp(0,1)`; review major 50). A spring
+// color array OVERSHOOTS its progress (>100), so `mixColor` extrapolates alpha past 1 — without the
+// clamp native handed React Native an invalid `rgba(…, 1.396)`, diverging from the pinned oracle. The
+// rgb channels already clamp to [0,255] via `clampChannel`, matching Motion's `clampRgbUnit`.
+function clampAlpha(v) {
+    return Math.min(1, Math.max(0, v));
+}
+function transformColor(c) {
+    return `rgba(${clampChannel(c.red)}, ${clampChannel(c.green)}, ${clampChannel(c.blue)}, ${sanitize(clampAlpha(c.alpha))})`;
+}

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

@@ -0,0 +1,19 @@
+export interface RGBA {
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    readonly alpha: number;
+}
+export type ColorParseVerdict = {
+    readonly parsed: RGBA;
+    readonly refusal: null;
+} | {
+    readonly parsed: null;
+    readonly refusal: string;
+};
+export declare function parseColorVerdict(raw: string): ColorParseVerdict;
+export declare function parseColor(raw: string): RGBA;
+export declare function isColor(raw: string): boolean;
+export declare function hslaToRgba(hue: number, saturation: number, lightness: number, alpha: number): RGBA;
+export declare function mixColor(from: RGBA, to: RGBA, progress: number): RGBA;
+export declare function transformColor(c: RGBA): string;

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

@@ -0,0 +1,19 @@
+export interface RGBA {
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    readonly alpha: number;
+}
+export type ColorParseVerdict = {
+    readonly parsed: RGBA;
+    readonly refusal: null;
+} | {
+    readonly parsed: null;
+    readonly refusal: string;
+};
+export declare function parseColorVerdict(raw: string): ColorParseVerdict;
+export declare function parseColor(raw: string): RGBA;
+export declare function isColor(raw: string): boolean;
+export declare function hslaToRgba(hue: number, saturation: number, lightness: number, alpha: number): RGBA;
+export declare function mixColor(from: RGBA, to: RGBA, progress: number): RGBA;
+export declare function transformColor(c: RGBA): string;

package/dist/value-types/color.js

@@ -0,0 +1,218 @@
+// Color value types (SPEC-VALUE-TYPES §3, REQ-VALUETYPE-005/006). Pure parse (hex/rgb/hsl/named → RGBA),
+// gamma-aware linear-light channel mix, and recompose. Host-agnostic (REQ-VALUETYPE-011): no DOM CSSOM,
+// no react-native processColor, no locale formatting — the named-color table (./named-colors) and the
+// HSL→RGB transform are this subsystem's own, so the same raw string yields the same RGBA on both engines.
+import { NAMED_COLORS } from "./named-colors.js";
+const refuseColor = (message) => ({ colorRefusal: message });
+function isColorRefusal(value) {
+    // OWN-property discriminant (M3 r8 major dbffcd947d13): the `in` operator walks the
+    // prototype chain, so a polluted `Object.prototype.colorRefusal` would turn every VALID
+    // RGBA result into a refusal. hasOwn is pollution-invisible.
+    return typeof value === 'object' && value !== null && Object.hasOwn(value, 'colorRefusal');
+}
+export function parseColorVerdict(raw) {
+    const s = raw.trim();
+    const lower = s.toLowerCase();
+    const named = NAMED_COLORS[lower];
+    if (named !== undefined)
+        return { parsed: named, refusal: null };
+    let outcome = null;
+    if (s.startsWith('#'))
+        outcome = parseHex(s);
+    else if (lower.startsWith('rgb'))
+        outcome = parseRgb(s);
+    else if (lower.startsWith('hsl'))
+        outcome = parseHsl(s);
+    if (outcome === null) {
+        return { parsed: null, refusal: `Cannot parse ${JSON.stringify(raw)} as a color` };
+    }
+    return isColorRefusal(outcome)
+        ? { parsed: null, refusal: outcome.colorRefusal }
+        : { parsed: outcome, refusal: null };
+}
+export function parseColor(raw) {
+    const verdict = parseColorVerdict(raw);
+    if (verdict.refusal !== null)
+        throw new Error(verdict.refusal);
+    return verdict.parsed;
+}
+// Family predicate for the dispatcher (mix.ts): is the WHOLE raw string a single color? A named-table
+// hit, a hex ATTEMPT, or a single rgb/hsl function. This recognizes the SHAPE, not validity: a "#"
+// single token (`# ` + alphanumerics, no whitespace) is always a hex attempt, and `parseColor` is the
+// strict validator that throws on a malformed one (wrong length/charset). Recognizing the shape here is
+// what keeps a malformed hex like "#12" a LOUD color failure (REQ-VALUETYPE-008) instead of silently
+// falling through to the complex tokenizer, which would treat "#" as a literal template and mix a bogus
+// number out of it. Mirrors the rgb/hsl branch, which likewise defers channel validity to parseColor.
+export function isColor(raw) {
+    const s = raw.trim();
+    if (NAMED_COLORS[s.toLowerCase()] !== undefined)
+        return true;
+    if (s.startsWith('#'))
+        return /^#[0-9a-z]+$/i.test(s);
+    return /^(?:rgba?|hsla?)\([^)]*\)$/i.test(s);
+}
+// #rgb, #rgba, #rrggbb, #rrggbbaa. Short forms double each nibble (matching CSS + motion).
+function parseHex(s) {
+    const h = s.slice(1);
+    const hex2 = (a, b) => Number.parseInt(a + b, 16);
+    let red;
+    let green;
+    let blue;
+    let alpha255 = 255;
+    if (h.length === 3 || h.length === 4) {
+        red = hex2(h.charAt(0), h.charAt(0));
+        green = hex2(h.charAt(1), h.charAt(1));
+        blue = hex2(h.charAt(2), h.charAt(2));
+        if (h.length === 4)
+            alpha255 = hex2(h.charAt(3), h.charAt(3));
+    }
+    else if (h.length === 6 || h.length === 8) {
+        red = hex2(h.charAt(0), h.charAt(1));
+        green = hex2(h.charAt(2), h.charAt(3));
+        blue = hex2(h.charAt(4), h.charAt(5));
+        if (h.length === 8)
+            alpha255 = hex2(h.charAt(6), h.charAt(7));
+    }
+    else {
+        return refuseColor(`Invalid hex color ${JSON.stringify(s)} (need 3/4/6/8 digits)`);
+    }
+    if (!/^[0-9a-f]+$/i.test(h) || Number.isNaN(red) || Number.isNaN(green) || Number.isNaN(blue)) {
+        return refuseColor(`Invalid hex color ${JSON.stringify(s)}`);
+    }
+    return { red, green, blue, alpha: alpha255 / 255 };
+}
+// Split the "(...)" argument list of an rgb()/rgba()/hsl()/hsla() function into trimmed channel tokens.
+function channels(prefix, s, label) {
+    const m = prefix.exec(s.trim());
+    if (m === null || m[1] === undefined) {
+        return refuseColor(`Invalid ${label} color ${JSON.stringify(s)}`);
+    }
+    const parts = m[1].split(',').map((p) => p.trim());
+    if (parts.length < 3 || parts.length > 4) {
+        return refuseColor(`${label} color needs 3 or 4 channels: ${JSON.stringify(s)}`);
+    }
+    return parts;
+}
+function num(token, s) {
+    const n = token === undefined ? Number.NaN : Number.parseFloat(token);
+    if (Number.isNaN(n)) {
+        return refuseColor(`Invalid color channel ${JSON.stringify(token)} in ${JSON.stringify(s)}`);
+    }
+    return n;
+}
+function parseRgb(s) {
+    const parts = channels(/^rgba?\(([^)]*)\)$/i, s, 'rgb');
+    if (isColorRefusal(parts))
+        return parts;
+    const red = num(parts[0], s);
+    if (isColorRefusal(red))
+        return red;
+    const green = num(parts[1], s);
+    if (isColorRefusal(green))
+        return green;
+    const blue = num(parts[2], s);
+    if (isColorRefusal(blue))
+        return blue;
+    const alpha = parts.length === 4 ? num(parts[3], s) : 1;
+    if (isColorRefusal(alpha))
+        return alpha;
+    return { red, green, blue, alpha };
+}
+function parseHsl(s) {
+    const parts = channels(/^hsla?\(([^)]*)\)$/i, s, 'hsl');
+    if (isColorRefusal(parts))
+        return parts;
+    const hue = num(parts[0], s);
+    if (isColorRefusal(hue))
+        return hue;
+    const saturation = num(parts[1], s);
+    if (isColorRefusal(saturation))
+        return saturation;
+    const lightness = num(parts[2], s);
+    if (isColorRefusal(lightness))
+        return lightness;
+    // parseFloat stops at the trailing "%" on saturation/lightness.
+    const alpha = parts.length === 4 ? num(parts[3], s) : 1;
+    if (isColorRefusal(alpha))
+        return alpha;
+    return hslaToRgba(hue, saturation, lightness, alpha);
+}
+// Standard HSL→RGB (matches motion-dom's hslaToRgba): rgb rounded to integers, alpha passed through.
+// Module-internal by the value-types barrel's own law; `motion-mix.ts` imports it directly for the
+// pin's HSLA-object color arm (REQ-VALUETYPE-016) rather than growing a second conversion.
+export function hslaToRgba(hue, saturation, lightness, alpha) {
+    const h = hue / 360;
+    const s = saturation / 100;
+    const l = lightness / 100;
+    let red;
+    let green;
+    let blue;
+    if (s === 0) {
+        red = green = blue = l;
+    }
+    else {
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        red = hueToRgb(p, q, h + 1 / 3);
+        green = hueToRgb(p, q, h);
+        blue = hueToRgb(p, q, h - 1 / 3);
+    }
+    return {
+        red: Math.round(red * 255),
+        green: Math.round(green * 255),
+        blue: Math.round(blue * 255),
+        alpha,
+    };
+}
+function hueToRgb(p, q, tRaw) {
+    let t = tRaw;
+    if (t < 0)
+        t += 1;
+    if (t > 1)
+        t -= 1;
+    if (t < 1 / 6)
+        return p + (q - p) * 6 * t;
+    if (t < 1 / 2)
+        return q;
+    if (t < 2 / 3)
+        return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+}
+// REQ-VALUETYPE-006: linear-light (gamma-aware) channel mix, NOT a naive average. `sqrt` of the
+// squared-channel interpolation — motion's mixLinearColor. Alpha mixes linearly.
+function mixLinearColor(from, to, v) {
+  'worklet';
+    return Math.sqrt(Math.max(0, v * (to * to - from * from) + from * from));
+}
+export function mixColor(from, to, progress) {
+  'worklet';
+    return {
+        red: mixLinearColor(from.red, to.red, progress),
+        green: mixLinearColor(from.green, to.green, progress),
+        blue: mixLinearColor(from.blue, to.blue, progress),
+        alpha: from.alpha + (to.alpha - from.alpha) * progress,
+    };
+}
+// String projection (REQ-VALUETYPE-006): rgb round→clamp[0,255]; alpha sanitized to Motion's 5-dp rule,
+// formatted byte-identically to motion-dom's `rgba(r, g, b, a)` recompose.
+function clampChannel(v) {
+  'worklet';
+    return Math.min(255, Math.max(0, Math.round(v)));
+}
+function sanitize(v) {
+  'worklet';
+    return Math.round(v * 1e5) / 1e5;
+}
+// Alpha is CLAMPED to [0,1] before the 5-dp sanitize, byte-identical to motion-dom's rgba formatter
+// (`sanitize(alpha.transform(a))` where `alpha.transform = clamp(0,1)`; review major 50). A spring
+// color array OVERSHOOTS its progress (>100), so `mixColor` extrapolates alpha past 1 — without the
+// clamp native handed React Native an invalid `rgba(…, 1.396)`, diverging from the pinned oracle. The
+// rgb channels already clamp to [0,255] via `clampChannel`, matching Motion's `clampRgbUnit`.
+function clampAlpha(v) {
+  'worklet';
+    return Math.min(1, Math.max(0, v));
+}
+export function transformColor(c) {
+  'worklet';
+    return `rgba(${clampChannel(c.red)}, ${clampChannel(c.green)}, ${clampChannel(c.blue)}, ${sanitize(clampAlpha(c.alpha))})`;
+}

package/dist/value-types/complex.cjs

@@ -0,0 +1,160 @@
+"use strict";
+// Complex/compound value types (SPEC-VALUE-TYPES §3, REQ-VALUETYPE-007/008). Tokenize a compound string
+// (borderRadius, box-shadow, transform lists) into an ordered list of typed slots (number+unit or color)
+// plus the literal separators between them, mix positionally, and recompose using the TARGET's separators.
+// Host-agnostic (REQ-VALUETYPE-011). Native TIGHTENS motion-dom: exact-count shape compatibility (motion
+// allows origin.count >= target.count), a per-slot unit-identity check (motion folds units into its split
+// template and silently re-applies the target's), and a loud throw where motion warns + snaps
+// (mixImmediate). motion carries bare numbers + a unit-bearing split; Native carries number+unit slots +
+// unit-free separators — the recompose STRING is byte-identical either way.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseComplex = parseComplex;
+exports.transformComplex = transformComplex;
+exports.mixComplex = mixComplex;
+const constants_1 = require("./constants.cjs");
+const color_1 = require("./color.cjs");
+const numeric_1 = require("./numeric.cjs");
+// Longest-match-first token recognizers (REQ-VALUETYPE-007). Sticky (`y`) so each is anchored at the
+// cursor. The hex branch grabs the WHOLE `#…` alphanumeric run (not a fixed 3/4/6/8 length) so a
+// malformed hex like `#12` or `#1234567` is captured in full and handed to parseColor, which throws
+// (REQ-VALUETYPE-008) — rather than the old fixed-length regex silently matching the `#123456` prefix and
+// leaving a stray `7` to tokenize as a bogus number. A bare `#` (no alnum after) is caught by an explicit
+// guard in the scan loop.
+const COLOR_TOKEN_RE = /#[0-9a-z]+|(?:rgba?|hsla?)\([^)]*\)/iy;
+const NUMBER_TOKEN_RE = /[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/iy;
+const VAR_TOKEN_RE = /var\(\s*--[^)]*\)/iy;
+// A color-function SIGIL (`rgb(`/`rgba(`/`hsl(`/`hsla(`). Non-sticky, tested against the remaining slice:
+// if a sigil is present but COLOR_TOKEN_RE could not consume a complete function, the function is
+// unclosed/malformed and must fail loud rather than silently tokenizing its interior numbers.
+const COLOR_SIGIL_RE = /^(?:rgba?|hsla?)\(/i;
+function matchStickyAt(re, raw, at) {
+    re.lastIndex = at;
+    const m = re.exec(raw);
+    return m !== null && m.index === at ? m[0] : null;
+}
+// A number token plus an optional trailing KNOWN unit. A non-KNOWN suffix (e.g. `em`) is left in the
+// template, matching motion — REQ-VALUETYPE-004's unit check only governs the units this subsystem owns.
+function matchNumberAt(raw, at) {
+    const numStr = matchStickyAt(NUMBER_TOKEN_RE, raw, at);
+    if (numStr === null)
+        return null;
+    const rest = raw.slice(at + numStr.length);
+    let unit = '';
+    for (const u of constants_1.KNOWN_UNITS) {
+        if (rest.startsWith(u)) {
+            unit = u;
+            break;
+        }
+    }
+    return { value: Number.parseFloat(numStr), unit, length: numStr.length + unit.length };
+}
+function parseComplex(raw) {
+    const slots = [];
+    const template = [];
+    let cursor = 0;
+    let literalStart = 0;
+    while (cursor < raw.length) {
+        // var() is web-only (REQ-VALUETYPE-007): on the native runtime it fails loud at parse, never silently
+        // becomes a literal.
+        if (matchStickyAt(VAR_TOKEN_RE, raw, cursor) !== null) {
+            throw new Error(`CSS variable tokens are web-only and cannot be parsed on the native runtime: ${JSON.stringify(raw)}`);
+        }
+        // color BEFORE number (longest-match-first): rgba(…) wins over the bare `0` at its opening paren.
+        const color = matchStickyAt(COLOR_TOKEN_RE, raw, cursor);
+        if (color !== null) {
+            template.push(raw.slice(literalStart, cursor));
+            slots.push({ kind: 'color', value: (0, color_1.parseColor)(color) });
+            cursor += color.length;
+            literalStart = cursor;
+            continue;
+        }
+        const num = matchNumberAt(raw, cursor);
+        if (num !== null) {
+            template.push(raw.slice(literalStart, cursor));
+            slots.push({ kind: 'number', value: num.value, unit: num.unit });
+            cursor += num.length;
+            literalStart = cursor;
+            continue;
+        }
+        // A color SIGIL the color branch could not accept — a bare/malformed `#`, or an unclosed/malformed
+        // `rgb()`/`hsl()` — is a malformed color, never literal template filler: fail loud (REQ-VALUETYPE-008)
+        // so it can never silently split into a `#`/`rgb(` literal plus bogus downstream numbers. An unknown
+        // keyword WITHOUT a sigil (`solid`, `inset`, `rgbicon`) stays a legitimate literal.
+        if (raw.charAt(cursor) === '#' || COLOR_SIGIL_RE.test(raw.slice(cursor))) {
+            throw new Error(`Malformed color token at index ${cursor} in complex value ${JSON.stringify(raw)}`);
+        }
+        cursor++;
+    }
+    template.push(raw.slice(literalStart));
+    if (slots.length === 0) {
+        throw new Error(`No animatable tokens (number/color) in complex value ${JSON.stringify(raw)}`);
+    }
+    return { slots, template };
+}
+// motion's mixComplex recompose runs each interpolated number through `sanitize` (round to 5 decimals) —
+// note this is a DIVERGENCE from motion's STANDALONE number/unit transform, which is raw (see numeric.ts).
+// Native mirrors motion per-path for byte-parity: raw standalone (transformNumeric), sanitized in complex.
+function sanitize(v) {
+    return Math.round(v * 1e5) / 1e5;
+}
+function transformSlot(slot) {
+    if (slot.kind === 'color')
+        return (0, color_1.transformColor)(slot.value);
+    const v = sanitize(slot.value);
+    return slot.unit === '' ? String(v) : `${v}${slot.unit}`;
+}
+function transformComplex(v) {
+    let out = v.template[0] ?? '';
+    for (let i = 0; i < v.slots.length; i++) {
+        const slot = v.slots[i];
+        if (slot === undefined)
+            continue; // unreachable: i < slots.length
+        out += transformSlot(slot) + (v.template[i + 1] ?? '');
+    }
+    return out;
+}
+function countByKind(v) {
+    let number = 0;
+    let color = 0;
+    for (const s of v.slots) {
+        if (s.kind === 'color')
+            color++;
+        else
+            number++;
+    }
+    return { number, color };
+}
+// Exact-count shape compatibility (REQ-VALUETYPE-007): motion mixes when origin.count >= target.count and
+// snaps the excess; Native requires the counts to match exactly and fails loud otherwise.
+function assertShapeCompatible(from, to) {
+    const cf = countByKind(from);
+    const ct = countByKind(to);
+    if (cf.number !== ct.number || cf.color !== ct.color) {
+        throw new Error(`Complex values are shape-incompatible: origin ${JSON.stringify(transformComplex(from))} has ` +
+            `${cf.number} number(s)/${cf.color} color(s), target ${JSON.stringify(transformComplex(to))} has ` +
+            `${ct.number} number(s)/${ct.color} color(s) — counts must match exactly`);
+    }
+}
+// Positionally mix each slot: numbers via mixNumeric (which enforces the per-slot unit-identity check,
+// REQ-VALUETYPE-004), colors via the gamma-aware mixColor. Recompose with the TARGET's template
+// (REQ-VALUETYPE-007). A same-count but positional type mismatch (number vs color at a slot) is a loud
+// failure (REQ-VALUETYPE-008).
+function mixComplex(from, to, progress) {
+    assertShapeCompatible(from, to);
+    const slots = to.slots.map((toSlot, i) => {
+        const fromSlot = from.slots[i];
+        if (fromSlot === undefined) {
+            throw new Error(`Missing origin slot ${i} for complex mix`); // unreachable after shape check
+        }
+        if (fromSlot.kind === 'number' && toSlot.kind === 'number') {
+            const mixed = (0, numeric_1.mixNumeric)({ value: fromSlot.value, unit: fromSlot.unit }, { value: toSlot.value, unit: toSlot.unit }, progress);
+            return { kind: 'number', value: mixed.value, unit: mixed.unit };
+        }
+        if (fromSlot.kind === 'color' && toSlot.kind === 'color') {
+            return { kind: 'color', value: (0, color_1.mixColor)(fromSlot.value, toSlot.value, progress) };
+        }
+        throw new Error(`Type mismatch at slot ${i}: origin is ${fromSlot.kind}, target is ${toSlot.kind} — ` +
+            `${JSON.stringify(transformComplex(from))} vs ${JSON.stringify(transformComplex(to))}`);
+    });
+    return { slots, template: to.template };
+}

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

@@ -0,0 +1,19 @@
+import { type RGBA } from "./color.cjs";
+interface NumberSlot {
+    readonly kind: 'number';
+    readonly value: number;
+    readonly unit: string;
+}
+interface ColorSlot {
+    readonly kind: 'color';
+    readonly value: RGBA;
+}
+export type Slot = NumberSlot | ColorSlot;
+export interface ComplexValue {
+    readonly slots: readonly Slot[];
+    readonly template: readonly string[];
+}
+export declare function parseComplex(raw: string): ComplexValue;
+export declare function transformComplex(v: ComplexValue): string;
+export declare function mixComplex(from: ComplexValue, to: ComplexValue, progress: number): ComplexValue;
+export {};

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

@@ -0,0 +1,19 @@
+import { type RGBA } from "./color.js";
+interface NumberSlot {
+    readonly kind: 'number';
+    readonly value: number;
+    readonly unit: string;
+}
+interface ColorSlot {
+    readonly kind: 'color';
+    readonly value: RGBA;
+}
+export type Slot = NumberSlot | ColorSlot;
+export interface ComplexValue {
+    readonly slots: readonly Slot[];
+    readonly template: readonly string[];
+}
+export declare function parseComplex(raw: string): ComplexValue;
+export declare function transformComplex(v: ComplexValue): string;
+export declare function mixComplex(from: ComplexValue, to: ComplexValue, progress: number): ComplexValue;
+export {};