nudge-ui 0.2.0

package/dist/css/value-semantics/colorSemantics.js

@@ -0,0 +1,526 @@
+import { extractVarCalls, splitTopLevel, splitTopLevelWhitespace, topLevelSlashIndex } from "./cssSyntax.js";
+const MIX_PERCENTAGE_OR_TOKEN = /^(?:\d+\.?\d*|\.\d+)%$|^var\([\s\S]+\)$/i;
+const COLOR_FUNCTIONS_WITH_ALPHA_SYNTAX = new Set(["rgb", "hsl", "hwb", "lab", "lch", "oklab", "oklch", "color"]);
+const COLOR_FUNCTION_NAMES = new Set([
+    ...COLOR_FUNCTIONS_WITH_ALPHA_SYNTAX,
+    "rgba",
+    "hsla",
+]);
+// CSS named colors are valid color values even though they do not have an
+// explicit alpha syntax. Opacity edits represent them with color-mix(), while
+// full opacity preserves the authored keyword.
+const NAMED_COLOR_KEYWORDS = new Set([
+    "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black",
+    "blanchedalmond", "blue", "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse",
+    "chocolate", "coral", "cornflowerblue", "cornsilk", "crimson", "cyan", "darkblue", "darkcyan",
+    "darkgoldenrod", "darkgray", "darkgrey", "darkgreen", "darkkhaki", "darkmagenta", "darkolivegreen",
+    "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen", "darkslateblue",
+    "darkslategray", "darkslategrey", "darkturquoise", "darkviolet", "deeppink", "deepskyblue",
+    "dimgray", "dimgrey", "dodgerblue", "firebrick", "floralwhite", "forestgreen", "fuchsia",
+    "gainsboro", "ghostwhite", "gold", "goldenrod", "gray", "grey", "green", "greenyellow",
+    "honeydew", "hotpink", "indianred", "indigo", "ivory", "khaki", "lavender", "lavenderblush",
+    "lawngreen", "lemonchiffon", "lightblue", "lightcoral", "lightcyan", "lightgoldenrodyellow",
+    "lightgray", "lightgrey", "lightgreen", "lightpink", "lightsalmon", "lightseagreen", "lightskyblue",
+    "lightslategray", "lightslategrey", "lightsteelblue", "lightyellow", "lime", "limegreen", "linen",
+    "magenta", "maroon", "mediumaquamarine", "mediumblue", "mediumorchid", "mediumpurple",
+    "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise", "mediumvioletred",
+    "midnightblue", "mintcream", "mistyrose", "moccasin", "navajowhite", "navy", "oldlace", "olive",
+    "olivedrab", "orange", "orangered", "orchid", "palegoldenrod", "palegreen", "paleturquoise",
+    "palevioletred", "papayawhip", "peachpuff", "peru", "pink", "plum", "powderblue", "purple",
+    "rebeccapurple", "red", "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown", "seagreen",
+    "seashell", "sienna", "silver", "skyblue", "slateblue", "slategray", "slategrey", "snow",
+    "springgreen", "steelblue", "tan", "teal", "thistle", "tomato", "turquoise", "violet", "wheat",
+    "white", "whitesmoke", "yellow", "yellowgreen",
+]);
+const CSS_NUMBER = /^[+-]?(?:(?:\d+\.?\d*)|(?:\.\d+))(?:e[+-]?\d+)?$/i;
+function formatOpacityPercent(value) {
+    return `${String(Number(value.toFixed(4)))}%`;
+}
+function parseOpacityPercent(value, clamp = true) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const isPercent = trimmed.endsWith("%");
+    const numericText = isPercent ? trimmed.slice(0, -1).trim() : trimmed;
+    if (!CSS_NUMBER.test(numericText))
+        return null;
+    const numeric = Number(numericText);
+    if (!Number.isFinite(numeric))
+        return null;
+    const percent = isPercent ? numeric : numeric * 100;
+    return clamp ? Math.max(0, Math.min(100, percent)) : percent;
+}
+/**
+ * Normalizes an authored opacity to a clamped percent string. Accepts `%`
+ * and `0..1` forms; returns null when the input is not a parseable opacity.
+ */
+export function normalizeOpacityPercent(value) {
+    const percent = parseOpacityPercent(value);
+    return percent === null ? null : formatOpacityPercent(percent);
+}
+function parseColorMixItem(value) {
+    const parts = splitTopLevelWhitespace(value.trim());
+    if (parts.length > 1 && MIX_PERCENTAGE_OR_TOKEN.test(parts.at(-1))) {
+        return { color: parts.slice(0, -1).join(" "), percentage: parts.at(-1) };
+    }
+    if (parts.length > 1 && MIX_PERCENTAGE_OR_TOKEN.test(parts[0])) {
+        return { color: parts.slice(1).join(" "), percentage: parts[0] };
+    }
+    return { color: value.trim(), percentage: null };
+}
+function isExactVarFunction(value) {
+    if (!/^var\(/i.test(value))
+        return false;
+    let depth = 0;
+    let quote = null;
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (quote) {
+            if (char === quote && value[index - 1] !== "\\")
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === "(")
+            depth++;
+        else if (char === ")") {
+            depth--;
+            if (depth === 0)
+                return index === value.length - 1;
+        }
+    }
+    return false;
+}
+function resolveOpacityPercentage(authoredValue, ctx, clamp = true) {
+    const trimmed = authoredValue.trim();
+    const exactVar = isExactVarFunction(trimmed);
+    const tokenResult = exactVar ? ctx.resolveTokenReference?.(trimmed) ?? null : null;
+    const localName = exactVar ? extractVarCalls(trimmed)[0]?.name : undefined;
+    const localValue = localName ? ctx.localAliases?.get(localName) : undefined;
+    const fallback = exactVar ? extractVarCalls(trimmed)[0]?.fallback : undefined;
+    const resolved = localValue
+        ?? (tokenResult?.resolvedValue && !/^var\(/i.test(tokenResult.resolvedValue)
+            ? tokenResult.resolvedValue
+            : fallback ?? trimmed);
+    const percent = parseOpacityPercent(resolved, clamp);
+    if (percent === null)
+        return null;
+    const token = tokenResult?.tokens.find((candidate) => candidate.name === tokenResult.tokenName)
+        ?? tokenResult?.tokens[0];
+    return {
+        percent,
+        component: {
+            value: formatOpacityPercent(percent),
+            authoredValue: trimmed,
+            tokenName: tokenResult?.tokenName ?? null,
+            token,
+        },
+    };
+}
+function resolveOpacityComponent(authoredValue, ctx) {
+    return resolveOpacityPercentage(authoredValue, ctx)?.component ?? null;
+}
+/**
+ * Derives the alpha component of a `color-mix(...)` whose second argument
+ * reconciles a color against `transparent`. The component is the color item's
+ * percentage, or the 100−p mirror of the transparent item's percentage when
+ * only that one is authored.
+ */
+function resolveColorMixOpacity(value, ctx) {
+    const open = value.indexOf("(");
+    const close = value.lastIndexOf(")");
+    if (open < 0 || close <= open)
+        return undefined;
+    const parts = splitTopLevel(value.slice(open + 1, close), ",");
+    if (parts.length !== 3 || !/^\s*in\s+/i.test(parts[0]))
+        return undefined;
+    const items = parts.slice(1).map(parseColorMixItem);
+    const transparentIndex = items.findIndex((item) => item.color.toLowerCase() === "transparent");
+    if (transparentIndex < 0 || items.filter((item) => item.color.toLowerCase() === "transparent").length !== 1)
+        return undefined;
+    const colorIndex = transparentIndex === 0 ? 1 : 0;
+    const colorItem = items[colorIndex];
+    const transparentItem = items[transparentIndex];
+    const colorPercentage = colorItem.percentage
+        ? resolveOpacityPercentage(colorItem.percentage, ctx, false)
+        : null;
+    const transparentPercentage = transparentItem.percentage
+        ? resolveOpacityPercentage(transparentItem.percentage, ctx, false)
+        : null;
+    if ((colorItem.percentage && !colorPercentage) || (transparentItem.percentage && !transparentPercentage))
+        return undefined;
+    let colorWeight = colorPercentage?.percent;
+    let transparentWeight = transparentPercentage?.percent;
+    if (colorWeight === undefined && transparentWeight === undefined) {
+        colorWeight = 50;
+        transparentWeight = 50;
+    }
+    else if (colorWeight === undefined) {
+        if (transparentWeight < 0 || transparentWeight > 100)
+            return undefined;
+        colorWeight = 100 - transparentWeight;
+    }
+    else if (transparentWeight === undefined) {
+        if (colorWeight < 0 || colorWeight > 100)
+            return undefined;
+        transparentWeight = 100 - colorWeight;
+    }
+    const resolvedColorWeight = colorWeight;
+    const resolvedTransparentWeight = transparentWeight;
+    if (resolvedColorWeight === undefined || resolvedTransparentWeight === undefined)
+        return undefined;
+    if (resolvedColorWeight < 0 || resolvedTransparentWeight < 0)
+        return undefined;
+    const total = resolvedColorWeight + resolvedTransparentWeight;
+    if (total <= 0)
+        return undefined;
+    const effectivePercent = total < 100 ? resolvedColorWeight : (resolvedColorWeight / total) * 100;
+    const attribution = colorPercentage?.component ?? transparentPercentage?.component;
+    return {
+        value: formatOpacityPercent(effectivePercent),
+        authoredValue: attribution?.authoredValue ?? "50%",
+        tokenName: attribution?.tokenName ?? null,
+        token: attribution?.token,
+        source: "color-mix",
+    };
+}
+/**
+ * Interprets the alpha component of one authored color value. Returns a
+ * `ColorOpacity` when the value carries a recognized alpha channel (hex,
+ * rgb/hsl, or color-mix against transparent), and undefined otherwise.
+ */
+export function interpretColorOpacity(value, ctx) {
+    const trimmed = value.trim();
+    const hex = /^#([\da-f]{4}|[\da-f]{8})$/i.exec(trimmed);
+    if (hex) {
+        const raw = hex[1];
+        const alpha = raw.length === 4 ? raw.slice(-1) : raw.slice(-2);
+        const max = raw.length === 4 ? 15 : 255;
+        return {
+            value: formatOpacityPercent((Number.parseInt(alpha, 16) / max) * 100),
+            authoredValue: alpha,
+            source: "hex",
+            tokenName: null,
+        };
+    }
+    const colorFunction = /^(rgba?|hsla?)\(([\s\S]*)\)$/i.exec(trimmed);
+    if (colorFunction) {
+        const body = colorFunction[2];
+        const commaParts = splitTopLevel(body, ",");
+        const alpha = commaParts.length >= 4
+            ? commaParts[3]
+            : (() => {
+                const slash = topLevelSlashIndex(body);
+                return slash >= 0 ? body.slice(slash + 1).trim() : null;
+            })();
+        if (alpha) {
+            const component = resolveOpacityComponent(alpha, ctx);
+            if (component) {
+                return { ...component, source: colorFunction[1].toLowerCase().startsWith("rgb") ? "rgb" : "hsl" };
+            }
+        }
+    }
+    if (/^color-mix\(/i.test(trimmed))
+        return resolveColorMixOpacity(trimmed, ctx);
+    return undefined;
+}
+/** Returns whether a color value carries its own alpha channel. */
+export function colorValueHasEmbeddedAlpha(value) {
+    const trimmed = value.trim();
+    if (/^transparent$/i.test(trimmed))
+        return true;
+    if (/^#(?:[\da-f]{4}|[\da-f]{8})$/i.test(trimmed))
+        return true;
+    const colorFunction = /^([a-z-]+)\(([\s\S]*)\)$/i.exec(trimmed);
+    if (!colorFunction)
+        return false;
+    const name = colorFunction[1].toLowerCase();
+    const body = colorFunction[2];
+    if (name === "rgba" || name === "hsla")
+        return true;
+    if (COLOR_FUNCTIONS_WITH_ALPHA_SYNTAX.has(name)) {
+        if (topLevelSlashIndex(body) >= 0)
+            return true;
+        if ((name === "rgb" || name === "hsl") && splitTopLevel(body, ",").length >= 4)
+            return true;
+    }
+    if (name !== "color-mix")
+        return false;
+    const parts = splitTopLevel(body, ",");
+    return parts.length === 3 && parts.slice(1).some((part) => {
+        const item = parseColorMixItem(part);
+        return item.color.toLowerCase() === "transparent" || colorValueHasEmbeddedAlpha(item.color);
+    });
+}
+/** Interprets UI-relevant color shape through the value-semantics seam. */
+export function interpretColorValue(value, ctx) {
+    const trimmed = value.trim();
+    return {
+        opacity: interpretColorOpacity(trimmed, ctx),
+        facts: {
+            hasEmbeddedAlpha: colorValueHasEmbeddedAlpha(trimmed),
+            isExpression: /^color-mix\(/i.test(trimmed),
+            opacityEditable: applyColorOpacity(trimmed, "50%").ok,
+        },
+    };
+}
+function replaceFunctionOpacity(value, opacity) {
+    const open = value.indexOf("(");
+    const close = value.lastIndexOf(")");
+    if (open < 0 || close <= open)
+        return null;
+    const body = value.slice(open + 1, close);
+    const commaParts = splitTopLevel(body, ",");
+    if (commaParts.length >= 4) {
+        return `${value.slice(0, open + 1)}${commaParts.slice(0, 3).map((part) => part.trim()).join(", ")}, ${opacity}${value.slice(close)}`;
+    }
+    const slash = topLevelSlashIndex(body);
+    if (slash < 0)
+        return null;
+    return `${value.slice(0, open + 1)}${body.slice(0, slash).trim()} / ${opacity}${value.slice(close)}`;
+}
+function isOpaqueRgbOrHslFunction(value) {
+    const match = /^(?:rgba?|hsla?)\(([\s\S]*)\)$/i.exec(value);
+    if (!match)
+        return false;
+    const body = match[1];
+    if (topLevelSlashIndex(body) >= 0)
+        return false;
+    const commaParts = splitTopLevel(body, ",");
+    return commaParts.length === 3
+        || (commaParts.length === 1 && splitTopLevelWhitespace(body).length === 3);
+}
+function replaceColorMixItemPercentage(item, opacity) {
+    const parts = splitTopLevelWhitespace(item.trim());
+    if (parts.length > 1 && MIX_PERCENTAGE_OR_TOKEN.test(parts.at(-1))) {
+        return [...parts.slice(0, -1), opacity].join(" ");
+    }
+    if (parts.length > 1 && MIX_PERCENTAGE_OR_TOKEN.test(parts[0])) {
+        return [opacity, ...parts.slice(1)].join(" ");
+    }
+    return `${item.trim()} ${opacity}`;
+}
+function replaceColorMixOpacity(value, opacity) {
+    const open = value.indexOf("(");
+    const close = value.lastIndexOf(")");
+    if (open < 0 || close <= open)
+        return null;
+    const parts = splitTopLevel(value.slice(open + 1, close), ",");
+    if (parts.length !== 3 || !/^\s*in\s+/i.test(parts[0]))
+        return null;
+    const items = parts.slice(1).map(parseColorMixItem);
+    const transparentIndex = items.findIndex((item) => item.color.toLowerCase() === "transparent");
+    if (transparentIndex < 0 || items.filter((item) => item.color.toLowerCase() === "transparent").length !== 1)
+        return null;
+    const colorIndex = transparentIndex === 0 ? 1 : 0;
+    const updated = [...parts];
+    const colorItem = items[colorIndex];
+    const transparentItem = items[transparentIndex];
+    if (colorItem.percentage && transparentItem.percentage) {
+        const percent = parseOpacityPercent(opacity);
+        if (percent === null)
+            return null;
+        updated[colorIndex + 1] = replaceColorMixItemPercentage(parts[colorIndex + 1], formatOpacityPercent(percent));
+        updated[transparentIndex + 1] = replaceColorMixItemPercentage(parts[transparentIndex + 1], formatOpacityPercent(100 - percent));
+    }
+    else if (colorItem.percentage) {
+        updated[colorIndex + 1] = replaceColorMixItemPercentage(parts[colorIndex + 1], opacity);
+    }
+    else if (transparentItem.percentage) {
+        const percent = parseOpacityPercent(opacity);
+        if (percent === null)
+            return null;
+        updated[transparentIndex + 1] = replaceColorMixItemPercentage(parts[transparentIndex + 1], formatOpacityPercent(100 - percent));
+    }
+    else {
+        updated[colorIndex + 1] = `${parts[colorIndex + 1].trim()} ${opacity}`;
+    }
+    return `${value.slice(0, open + 1)}${updated.join(", ")}${value.slice(close)}`;
+}
+/**
+ * Rewrites the alpha of a supported color expression to a normalized opacity
+ * percent. Hex alpha channels are rewritten digit-for-digit, rgb/hsl slash or
+ * comma alpha is replaced, `color-mix(... transparent)` reconciles its
+ * percentage (or its 100−p mirror), and a bare `var()` wraps into
+ * `color-mix(in srgb, var(...) <pct>, transparent)` — unwrapping back to the
+ * plain `var()` when the opacity reaches 100%. Unsupported value shapes and
+ * unparseable opacities return an explicit `ok: false`.
+ */
+export function applyColorOpacity(value, opacity) {
+    const normalized = normalizeOpacityPercent(opacity);
+    if (normalized === null)
+        return { ok: false, reason: "invalid-opacity" };
+    const trimmed = value.trim();
+    if (/^var\(\s*--[\w-]+(?:\s*,[\s\S]*)?\s*\)$/i.test(trimmed)) {
+        return normalized === "100%"
+            ? { ok: true, value: trimmed }
+            : { ok: true, value: `color-mix(in srgb, ${trimmed} ${normalized}, transparent)` };
+    }
+    const hex = /^#([\da-f]{4}|[\da-f]{8})$/i.exec(trimmed);
+    if (hex) {
+        const raw = hex[1];
+        const max = raw.length === 4 ? 15 : 255;
+        const digits = raw.length === 4 ? 1 : 2;
+        const alpha = Math.round((parseOpacityPercent(normalized) / 100) * max).toString(16).padStart(digits, "0");
+        return { ok: true, value: `${trimmed.slice(0, -digits)}${alpha}` };
+    }
+    if (/^#(?:[\da-f]{3}|[\da-f]{6})$/i.test(trimmed)) {
+        return normalized === "100%"
+            ? { ok: true, value: trimmed }
+            : { ok: true, value: `color-mix(in srgb, ${trimmed} ${normalized}, transparent)` };
+    }
+    const functionName = /^(\w[\w-]*)\(/i.exec(trimmed)?.[1]?.toLowerCase();
+    if (functionName && COLOR_FUNCTION_NAMES.has(functionName)) {
+        const open = trimmed.indexOf("(");
+        if (open < 0 || !trimmed.endsWith(")") || !trimmed.slice(open + 1, -1).trim()) {
+            return { ok: false, reason: "unsupported" };
+        }
+        const next = replaceFunctionOpacity(trimmed, normalized);
+        if (next)
+            return { ok: true, value: next };
+        if (functionName === "rgb" || functionName === "rgba" || functionName === "hsl" || functionName === "hsla") {
+            if (!isOpaqueRgbOrHslFunction(trimmed))
+                return { ok: false, reason: "unsupported" };
+        }
+        return normalized === "100%"
+            ? { ok: true, value: trimmed }
+            : { ok: true, value: `color-mix(in srgb, ${trimmed} ${normalized}, transparent)` };
+    }
+    if (NAMED_COLOR_KEYWORDS.has(trimmed.toLowerCase())) {
+        return normalized === "100%"
+            ? { ok: true, value: trimmed }
+            : { ok: true, value: `color-mix(in srgb, ${trimmed} ${normalized}, transparent)` };
+    }
+    if (/^color-mix\(/i.test(trimmed)) {
+        const next = replaceColorMixOpacity(trimmed, normalized);
+        return next ? { ok: true, value: next } : { ok: false, reason: "unsupported" };
+    }
+    return { ok: false, reason: "unsupported" };
+}
+function tokenReferenceName(entry) {
+    const name = entry.cssName ?? entry.name;
+    return name.startsWith("--") ? name : null;
+}
+function rgbTuple(value) {
+    const trimmed = value.trim();
+    const hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(trimmed);
+    if (hex) {
+        const raw = hex[1];
+        const expanded = raw.length === 3 ? raw.split("").map((part) => part + part).join("") : raw;
+        // SAFETY: hex length was validated and expanded to six hex digits before parsing RGB channels.
+        const rgb = [0, 2, 4].map((offset) => Number.parseInt(expanded.slice(offset, offset + 2), 16));
+        return [rgb[0], rgb[1], rgb[2]];
+    }
+    const match = /^rgba?\(([\s\S]*)\)$/i.exec(trimmed);
+    if (!match)
+        return null;
+    const body = match[1];
+    const commaParts = splitTopLevel(body, ",");
+    if (commaParts.length > 1 && commaParts.length !== 3 && commaParts.length !== 4)
+        return null;
+    const channelParts = commaParts.length >= 3
+        ? commaParts.slice(0, 3)
+        : splitTopLevelWhitespace(body.slice(0, Math.max(0, topLevelSlashIndex(body) < 0 ? body.length : topLevelSlashIndex(body))));
+    if (channelParts.length !== 3)
+        return null;
+    const channels = channelParts.map((part) => CSS_NUMBER.test(part.trim()) ? Number(part.trim()) : Number.NaN);
+    if (channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255))
+        return null;
+    // SAFETY: channel count and finite 0-255 range were validated before rounding to an RGB tuple.
+    const rounded = channels.map((channel) => Math.round(channel));
+    return [rounded[0], rounded[1], rounded[2]];
+}
+function sameRgb(left, right) {
+    return Boolean(left && right && left.every((channel, index) => channel === right[index]));
+}
+function replaceRgbChannels(value, oldValue, nextValue) {
+    const match = /^(rgba?)\(([\s\S]*)\)$/i.exec(value.trim());
+    const oldRgb = rgbTuple(oldValue);
+    const nextRgb = rgbTuple(nextValue);
+    if (!match || !sameRgb(rgbTuple(value), oldRgb) || !nextRgb)
+        return null;
+    const body = match[2];
+    const commaParts = splitTopLevel(body, ",");
+    if (commaParts.length >= 3) {
+        const alpha = commaParts.length === 4 ? `, ${commaParts[3].trim()}` : "";
+        return `${match[1]}(${nextRgb.join(", ")}${alpha})`;
+    }
+    const slash = topLevelSlashIndex(body);
+    const alpha = slash >= 0 ? ` / ${body.slice(slash + 1).trim()}` : "";
+    return `${match[1]}(${nextRgb.join(" ")}${alpha})`;
+}
+function replaceColorMixItemColor(item, color) {
+    const parsed = parseColorMixItem(item);
+    if (!parsed.percentage)
+        return color;
+    const parts = splitTopLevelWhitespace(item.trim());
+    return MIX_PERCENTAGE_OR_TOKEN.test(parts[0])
+        ? `${parsed.percentage} ${color}`
+        : `${color} ${parsed.percentage}`;
+}
+function replaceColorMixColor(value, oldValue, nextColor) {
+    const open = value.indexOf("(");
+    const close = value.lastIndexOf(")");
+    if (open < 0 || close <= open)
+        return null;
+    const parts = splitTopLevel(value.slice(open + 1, close), ",");
+    if (parts.length !== 3 || !/^\s*in\s+/i.test(parts[0]))
+        return null;
+    const items = parts.slice(1).map(parseColorMixItem);
+    const colorIndexes = items.flatMap((item, index) => item.color.toLowerCase() === "transparent" ? [] : [index]);
+    if (colorIndexes.length !== 1)
+        return null;
+    const colorIndex = colorIndexes[0];
+    if (!sameRgb(rgbTuple(items[colorIndex].color), rgbTuple(oldValue)) && items[colorIndex].color.trim().toLowerCase() !== oldValue.trim().toLowerCase())
+        return null;
+    const updated = [...parts];
+    updated[colorIndex + 1] = replaceColorMixItemColor(parts[colorIndex + 1], nextColor);
+    return `${value.slice(0, open + 1)}${updated.join(", ")}${value.slice(close)}`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Replaces only the color token in a separable color expression. Keeping this
+ * separate from a plain token swap preserves authored alpha modifiers, for
+ * example Tailwind's `color-mix(... var(--color-red-500) 10%, transparent)`
+ * keeps its `10%` when the color token changes.
+ */
+export function applyColorTokenReplacement(value, oldToken, newToken) {
+    const nextName = tokenReferenceName(newToken);
+    if (nextName) {
+        for (const oldName of [oldToken.cssName, oldToken.name].filter((name) => Boolean(name))) {
+            const reference = new RegExp(`var\\(\\s*${escapeRegExp(oldName)}(?=\\s*(?:,|\\)))`, "i");
+            if (reference.test(value)) {
+                return {
+                    ok: true,
+                    value: value.replace(new RegExp(`var\\(\\s*${escapeRegExp(oldName)}(?=\\s*(?:,|\\)))`, "gi"), `var(${nextName}`),
+                };
+            }
+        }
+    }
+    const oldValue = oldToken.cssValue?.trim() || oldToken.value.trim();
+    const nextValue = newToken.cssValue?.trim() || newToken.value.trim();
+    if (!oldValue || !nextValue)
+        return { ok: false, reason: "unsupported" };
+    const replacement = nextName ? `var(${nextName})` : nextValue;
+    if (value.trim().toLowerCase() === oldValue.toLowerCase())
+        return { ok: true, value: replacement };
+    if (sameRgb(rgbTuple(value), rgbTuple(oldValue)) && !/[/,]/.test(value))
+        return { ok: true, value: replacement };
+    const rgbReplacement = replaceRgbChannels(value, oldValue, nextValue);
+    if (rgbReplacement)
+        return { ok: true, value: rgbReplacement };
+    const mixReplacement = replaceColorMixColor(value, oldValue, replacement);
+    if (mixReplacement)
+        return { ok: true, value: mixReplacement };
+    return { ok: false, reason: "unsupported" };
+}
+/** The public meaning-preserving edit operation for supported value edits. */
+export function applyValueEdit(request) {
+    if (request.kind === "color-opacity") {
+        return applyColorOpacity(request.authored, request.opacity);
+    }
+    return applyColorTokenReplacement(request.authored, request.currentToken, request.nextToken);
+}

package/dist/css/value-semantics/cssSyntax.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Low-level, browser-safe CSS value splitting helpers shared by the
+ * value-semantics Modules (plan slice 3.4). These are internal parsing seams,
+ * not public Interface: they split structure, they do not interpret meaning.
+ */
+/**
+ * Balanced `var()` scanning. Handles nested parentheses and takes the first
+ * top-level comma as the fallback separator.
+ */
+export declare function extractVarCalls(value: string): Array<{
+    name: string;
+    fallback?: string;
+}>;
+/** Index of the first top-level `/` in a value, or -1 when none exists. */
+export declare function topLevelSlashIndex(value: string): number;
+/** Splits CSS values at top-level combinators or an optional delimiter. */
+export declare function splitTopLevel(s: string, sep?: string): string[];
+/** Splits a value at top-level whitespace, honoring quotes and nesting. */
+export declare function splitTopLevelWhitespace(value: string): string[];

package/dist/css/value-semantics/cssSyntax.js

@@ -0,0 +1,111 @@
+/**
+ * Low-level, browser-safe CSS value splitting helpers shared by the
+ * value-semantics Modules (plan slice 3.4). These are internal parsing seams,
+ * not public Interface: they split structure, they do not interpret meaning.
+ */
+/**
+ * Balanced `var()` scanning. Handles nested parentheses and takes the first
+ * top-level comma as the fallback separator.
+ */
+export function extractVarCalls(value) {
+    const calls = [];
+    let i = 0;
+    while (i < value.length) {
+        const start = value.indexOf("var(", i);
+        if (start < 0)
+            break;
+        let depth = 1;
+        let j = start + 4;
+        let comma = -1;
+        while (j < value.length && depth > 0) {
+            const char = value[j];
+            if (char === "(")
+                depth++;
+            else if (char === ")")
+                depth--;
+            else if (char === "," && depth === 1 && comma < 0)
+                comma = j;
+            j++;
+        }
+        const body = value.slice(start + 4, Math.max(start + 4, j - 1)).trim();
+        const name = (body.slice(0, comma < 0 ? body.length : comma - start - 4).trim().match(/^--[\w-]+/) ?? [])[0];
+        if (name) {
+            const fallback = comma >= 0 ? value.slice(comma + 1, Math.max(comma + 1, j - 1)).trim() : undefined;
+            calls.push({ name, fallback });
+        }
+        i = Math.max(j, start + 4);
+    }
+    return calls;
+}
+/** Index of the first top-level `/` in a value, or -1 when none exists. */
+export function topLevelSlashIndex(value) {
+    let depth = 0;
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (char === "(")
+            depth++;
+        else if (char === ")")
+            depth = Math.max(0, depth - 1);
+        else if (char === "/" && depth === 0)
+            return index;
+    }
+    return -1;
+}
+/** Splits CSS values at top-level combinators or an optional delimiter. */
+export function splitTopLevel(s, sep) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === "(")
+            depth++;
+        else if (s[i] === ")")
+            depth--;
+        else if (depth === 0 && sep && s[i] === sep) {
+            parts.push(s.slice(start, i));
+            start = i + 1;
+        }
+        else if (depth === 0 && !sep && (s[i] === " " || s[i] === ">" || s[i] === "+" || s[i] === "~")) {
+            // Only split on combinators that have non-space around them.
+            if (i > start)
+                parts.push(s.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    const last = s.slice(start).trim();
+    if (last)
+        parts.push(last);
+    return parts;
+}
+/** Splits a value at top-level whitespace, honoring quotes and nesting. */
+export function splitTopLevelWhitespace(value) {
+    const parts = [];
+    let depth = 0;
+    let quote = null;
+    let start = 0;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (quote) {
+            if (char === quote && value[i - 1] !== "\\")
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === "(" || char === "[") {
+            depth++;
+        }
+        else if (char === ")" || char === "]") {
+            depth = Math.max(0, depth - 1);
+        }
+        else if (depth === 0 && /\s/.test(char ?? "")) {
+            if (i > start)
+                parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    if (start < value.length)
+        parts.push(value.slice(start));
+    return parts;
+}