@birdycom/omniacss 0.0.0-stage → 0.11.0

package/src/tokens.mjs

@@ -0,0 +1,377 @@
+// File: packages/core/src/tokens.mjs
+// Semantic theme tokens: one JSON source (tokens/semantic.json) -> theme CSS for the web and resolved exports for
+// non-web targets (desktop apps: Tkinter, Qt, WinUI, ...).
+// Map: palette parsing -> OKLCH math + CSS Color 4 gamut mapping -> resolve per mode -> formats (css | json | dtcg | python)
+// Author: Serge Cools | Framework: OmniaCSS
+//
+// Why: native toolkits know no light-dark(), var() or oklch(). The export resolves every token per mode to a final
+// sRGB hex (gamut mapped like CSS Color 4, not clipped per channel), keeps the source oklch and alpha next to it,
+// and stamps the OmniaCSS version so an app knows which release its colors match.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const coreDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const SEMANTIC_FILE = path.join(coreDir, "tokens/semantic.json");
+export const MODES = ["light", "dark"];
+
+/* ===================================================================
+   PALETTE — --color-<name>-<step>: oklch(...) from oc-colors.css
+   =================================================================== */
+
+/** Map "red-70" -> { l, c, h } (l 0..1). Later declarations win, as in the cascade. */
+export function parsePalette(css) {
+  const palette = new Map();
+  const re = /--color-([a-z0-9-]+):\s*oklch\(\s*([\d.]+)%\s+([\d.]+)\s+([\d.]+)(?:deg)?|--color-([a-z0-9-]+):\s*oklch\(\s*([\d.]+)%\s+([\d.]+)\s+none/g;
+  for (const m of css.matchAll(re)) {
+    if (m[1]) palette.set(m[1], { l: +m[2] / 100, c: +m[3], h: +m[4] });
+    else palette.set(m[5], { l: +m[6] / 100, c: +m[7], h: 0 });
+  }
+  return palette;
+}
+
+/* ===================================================================
+   COLOR MATH — OKLCH <-> OKLab <-> linear sRGB <-> sRGB
+   =================================================================== */
+
+const toLab = ({ l, c, h }) => ({ L: l, a: c * Math.cos((h * Math.PI) / 180), b: c * Math.sin((h * Math.PI) / 180) });
+
+function labToLinear({ L, a, b }) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+function linearToLab([r, g, b]) {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+const gamma = (v) => (Math.abs(v) <= 0.0031308 ? 12.92 * v : Math.sign(v) * (1.055 * Math.abs(v) ** (1 / 2.4) - 0.055));
+const ungamma = (v) => (Math.abs(v) <= 0.04045 ? v / 12.92 : Math.sign(v) * ((Math.abs(v) + 0.055) / 1.055) ** 2.4);
+
+const toSrgb = (lch) => labToLinear(toLab(lch)).map(gamma);
+const srgbToLab = (rgb) => linearToLab(rgb.map(ungamma));
+const inGamut = (rgb, eps = 0.000075) => rgb.every((v) => v >= -eps && v <= 1 + eps);
+const clip = (rgb) => rgb.map((v) => Math.min(1, Math.max(0, v)));
+const deltaEOK = (p, q) => Math.hypot(p.L - q.L, p.a - q.a, p.b - q.b);
+
+/**
+ * CSS Color 4 gamut mapping to sRGB (https://www.w3.org/TR/css-color-4/#binsearch):
+ * lower the OKLCH chroma until the clipped color is within a just-noticeable difference (deltaEOK 0.02).
+ * Keeps lightness and hue, unlike clipping each channel.
+ */
+export function gamutMap(lch) {
+  if (lch.l >= 1) return [1, 1, 1];
+  if (lch.l <= 0) return [0, 0, 0];
+  const origin = toSrgb(lch);
+  if (inGamut(origin)) return clip(origin);
+  const JND = 0.02;
+  const EPS = 0.0001;
+  let current = { ...lch };
+  let clipped = clip(origin);
+  if (deltaEOK(srgbToLab(clipped), toLab(current)) < JND) return clipped;
+  let min = 0;
+  let max = lch.c;
+  let minInGamut = true;
+  while (max - min > EPS) {
+    const chroma = (min + max) / 2;
+    current = { ...current, c: chroma };
+    const rgb = toSrgb(current);
+    if (minInGamut && inGamut(rgb)) { min = chroma; continue; }
+    clipped = clip(rgb);
+    const E = deltaEOK(srgbToLab(clipped), toLab(current));
+    if (E < JND) {
+      if (JND - E < EPS) return clipped;
+      minInGamut = false;
+      min = chroma;
+    } else {
+      max = chroma;
+    }
+  }
+  return clipped;
+}
+
+/** Per-channel clipping (what a naive conversion does) — only used to report the difference. */
+export const clipSrgb = (lch) => clip(toSrgb(lch));
+export const isInSrgb = (lch) => inGamut(toSrgb(lch));
+
+export const toHex = (rgb) => "#" + rgb.map((v) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, "0")).join("");
+const round = (n, d) => Number(n.toFixed(d));
+export const oklchString = ({ l, c, h }) => `oklch(${round(l * 100, 2)}% ${round(c, 4)} ${round(h, 2)})`;
+
+/** Alpha-blend rgb over a background (sRGB, gamma space, as browsers composite). */
+const blend = (rgb, alpha, bg) => rgb.map((v, i) => v * alpha + bg[i] * (1 - alpha));
+
+/* ===================================================================
+   RESOLVE — semantic.json -> final values per mode
+   A color value is a palette name ("frostblue-2"), a token reference ("@foreground"),
+   or { "color": <name or @ref>, "alpha": 0..1 }. Light/dark: { "light": v, "dark": v } or one value for both.
+   =================================================================== */
+
+export async function loadSemantic(file = SEMANTIC_FILE) {
+  return JSON.parse(await fs.readFile(file, "utf8"));
+}
+
+export async function loadPalette(dist = path.join(coreDir, "dist")) {
+  return parsePalette(await fs.readFile(path.join(dist, "oc-colors.css"), "utf8"));
+}
+
+const perMode = (v) => (v && typeof v === "object" && ("light" in v || "dark" in v) ? v : { light: v, dark: v });
+
+/** { name, alpha } for one token in one mode, references followed to a palette color. */
+function resolveColor(tokens, name, mode, seen = []) {
+  if (seen.includes(name)) throw new Error(`token cycle: ${[...seen, name].join(" -> ")}`);
+  const def = tokens[name];
+  if (!def) throw new Error(`unknown token "@${name}"`);
+  let v = perMode(def.value)[mode];
+  let alpha = 1;
+  if (v && typeof v === "object") { alpha = v.alpha ?? 1; v = v.color; }
+  if (typeof v === "string" && v.startsWith("@")) {
+    const inner = resolveColor(tokens, v.slice(1), mode, [...seen, name]);
+    return { ...inner, alpha: inner.alpha * alpha, via: [v.slice(1), ...inner.via] };
+  }
+  return { color: v, alpha, via: [] };
+}
+
+/** Resolve every color token per mode: hex (gamut mapped), oklch source, alpha, palette name. */
+export function resolveTokens(semantic, palette) {
+  const out = {};
+  for (const name of Object.keys(semantic.color)) {
+    out[name] = {};
+    for (const mode of MODES) {
+      const { color, alpha } = resolveColor(semantic.color, name, mode);
+      const lch = palette.get(color);
+      if (!lch) throw new Error(`token "${name}" (${mode}): palette color "${color}" not found in oc-colors.css`);
+      const rgb = gamutMap(lch);
+      const entry = { hex: toHex(rgb), oklch: oklchString(lch), palette: color };
+      if (alpha !== 1) entry.alpha = alpha;
+      if (!isInSrgb(lch)) { entry.gamutMapped = true; entry.clippedHex = toHex(clipSrgb(lch)); }
+      entry._rgb = rgb;
+      out[name][mode] = entry;
+    }
+  }
+  // Transparent tokens also get an opaque hex pre-blended over --oc-background (toolkits without alpha).
+  for (const name of Object.keys(out)) {
+    for (const mode of MODES) {
+      const e = out[name][mode];
+      if (e.alpha !== undefined) e.opaqueHex = toHex(blend(e._rgb, e.alpha, out.background[mode]._rgb));
+    }
+  }
+  for (const t of Object.values(out)) for (const mode of MODES) delete t[mode]._rgb;
+  return out;
+}
+
+/* ===================================================================
+   FORMATS
+   =================================================================== */
+
+const cssColor = (tokens, v) => {
+  let alpha = 1;
+  if (v && typeof v === "object") { alpha = v.alpha ?? 1; v = v.color; }
+  const ref = v.startsWith("@") ? `var(--oc-${v.slice(1)})` : `var(--color-${v})`;
+  return alpha === 1 ? ref : `oklch(from ${ref} l c h / ${alpha})`;
+};
+
+/** oc-theme.css: the semantic tokens as light-dark() custom properties (the web side of the same source). */
+export function toCss(semantic, version) {
+  const lines = [];
+  const pad = (s) => "  " + s;
+  lines.push(`/* File: oc-theme.css — generated from tokens/semantic.json by @birdycom/omniacss ${version}. Do not edit. */`);
+  lines.push("/* Semantic theme tokens: every color is light-dark() of an Omnia palette token (oc-colors.css). */");
+  lines.push("/* Same source as the desktop export: npx omniacss tokens --format json|dtcg|python */");
+  lines.push(":root {");
+  lines.push(pad("color-scheme: light dark;"));
+  let group = null;
+  for (const [name, def] of Object.entries(semantic.color)) {
+    if (def.group !== group) { group = def.group; lines.push("", pad(`/* ${group} */`)); }
+    const v = def.value;
+    const value = v && typeof v === "object" && "light" in v
+      ? (JSON.stringify(v.light) === JSON.stringify(v.dark) ? cssColor(semantic.color, v.light) : `light-dark(${cssColor(semantic.color, v.light)}, ${cssColor(semantic.color, v.dark)})`)
+      : cssColor(semantic.color, v);
+    lines.push(pad(`--oc-${name}: ${value};`));
+  }
+  lines.push("", pad("/* Gradients */"));
+  for (const [name, g] of Object.entries(semantic.gradient || {})) {
+    const stops = g.stops.map((s, i) => `var(--oc-${s.color})${s.at !== undefined && i > 0 && i < g.stops.length - 1 ? ` ${s.at}%` : ""}`);
+    lines.push(pad(`--oc-gradient-${name}: linear-gradient(${g.angle}deg, ${stops.join(", ")});`));
+  }
+  lines.push("", pad("/* Shape, focus, motion, fonts */"));
+  lines.push(pad(`--oc-radius: ${semantic.size.radius.rem}rem;`));
+  lines.push(pad(`--oc-focus-width: ${semantic.size["focus-width"].px}px;`));
+  for (const [name, t] of Object.entries(semantic.transition)) lines.push(pad(`--oc-transition-${name}: ${t.ms}ms ${t.easing};`));
+  for (const [name, f] of Object.entries(semantic.font)) lines.push(pad(`--oc-font-${name}: ${f.css};`));
+  // Shadows: the color is its own light-dark() token, so the shadow follows the color-scheme without media queries.
+  lines.push("", pad("/* Shadows (x y blur spread; color + alpha per mode in --oc-shadow-<name>-color) */"));
+  for (const [name, s] of Object.entries(semantic.shadow)) {
+    const c = (mode) => `oklch(from var(--color-${perMode(s.color)[mode]}) l c h / ${perMode(s.alpha)[mode]})`;
+    lines.push(pad(`--oc-shadow-${name}-color: light-dark(${c("light")}, ${c("dark")});`));
+    lines.push(pad(`--oc-shadow-${name}: ${s.x}px ${s.y}px ${s.blur}px ${s.spread}px var(--oc-shadow-${name}-color);`));
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}
+
+const px = (rem) => rem * 16;
+const pt = (pxv) => round(pxv * 0.75, 2);
+
+/** Everything a non-web app needs, resolved: the data behind json, dtcg and python. */
+export function buildExport(semantic, palette, version) {
+  const colors = resolveTokens(semantic, palette);
+  const shadows = {};
+  for (const [name, s] of Object.entries(semantic.shadow)) {
+    shadows[name] = { x: s.x, y: s.y, blur: s.blur, spread: s.spread };
+    for (const mode of MODES) {
+      const lch = palette.get(perMode(s.color)[mode]);
+      shadows[name][mode] = { hex: toHex(gamutMap(lch)), alpha: perMode(s.alpha)[mode] };
+    }
+  }
+  const gradients = {};
+  for (const [name, g] of Object.entries(semantic.gradient || {})) {
+    gradients[name] = { angle: g.angle };
+    for (const mode of MODES) gradients[name][mode] = g.stops.map((s, i) => ({ hex: colors[s.color][mode].hex, at: s.at ?? (i === 0 ? 0 : 100) }));
+  }
+  const text = Object.fromEntries(Object.entries(semantic.text).map(([k, v]) => [k, { px: v.px, pt: pt(v.px) }]));
+  return {
+    omniacss: version,
+    generated: "npx omniacss tokens",
+    modes: MODES,
+    colors,
+    sizes: {
+      radius: { rem: semantic.size.radius.rem, px: px(semantic.size.radius.rem), pt: pt(px(semantic.size.radius.rem)) },
+      "focus-width": { px: semantic.size["focus-width"].px, pt: pt(semantic.size["focus-width"].px) },
+    },
+    text,
+    fonts: Object.fromEntries(Object.entries(semantic.font).map(([k, f]) => [k, { windows: f.windows, macos: f.macos, linux: f.linux, css: f.css }])),
+    transitions: semantic.transition,
+    shadows,
+    gradients,
+  };
+}
+
+/** JSON: { omniacss, tokens: { background: { light: { hex, oklch }, dark: {…} }, radius: { px }, … } } */
+export function toJson(data) {
+  const tokens = {};
+  for (const [name, t] of Object.entries(data.colors)) tokens[name] = t;
+  for (const [name, s] of Object.entries(data.sizes)) tokens[name] = s;
+  for (const [name, s] of Object.entries(data.text)) tokens[`text-${name}`] = s;
+  for (const [name, f] of Object.entries(data.fonts)) tokens[`font-${name}`] = f;
+  for (const [name, t] of Object.entries(data.transitions)) tokens[`transition-${name}`] = t;
+  for (const [name, s] of Object.entries(data.shadows)) tokens[`shadow-${name}`] = s;
+  for (const [name, g] of Object.entries(data.gradients)) tokens[`gradient-${name}`] = g;
+  return JSON.stringify({ omniacss: data.omniacss, generated: data.generated, modes: data.modes, tokens }, null, 2) + "\n";
+}
+
+const hexToComponents = (hex) => [1, 3, 5].map((i) => round(parseInt(hex.slice(i, i + 2), 16) / 255, 4));
+const dtcgColor = (e) => ({ colorSpace: "srgb", components: hexToComponents(e.hex), alpha: e.alpha ?? 1, hex: e.hex });
+
+/** W3C Design Tokens (DTCG): $value = light mode; dark mode in $extensions["com.birdycom.omniacss"].modes.dark. */
+export function toDtcg(data) {
+  const ext = (extra) => ({ "com.birdycom.omniacss": extra });
+  const color = {};
+  for (const [name, t] of Object.entries(data.colors)) {
+    color[name] = {
+      $type: "color",
+      $value: dtcgColor(t.light),
+      $extensions: ext({ modes: { dark: dtcgColor(t.dark) }, oklch: { light: t.light.oklch, dark: t.dark.oklch }, palette: { light: t.light.palette, dark: t.dark.palette } }),
+    };
+  }
+  const dim = (v) => ({ $type: "dimension", $value: { value: v, unit: "px" } });
+  const out = {
+    $description: `OmniaCSS ${data.omniacss} semantic tokens (generated by npx omniacss tokens --format dtcg)`,
+    $extensions: ext({ version: data.omniacss, modes: data.modes }),
+    color,
+    radius: dim(data.sizes.radius.px),
+    "focus-width": dim(data.sizes["focus-width"].px),
+    text: Object.fromEntries(Object.entries(data.text).map(([k, v]) => [k, dim(v.px)])),
+    font: Object.fromEntries(Object.entries(data.fonts).map(([k, f]) => [k, { $type: "fontFamily", $value: f.windows, $extensions: ext({ macos: f.macos, linux: f.linux, css: f.css }) }])),
+    shadow: Object.fromEntries(Object.entries(data.shadows).map(([k, s]) => [k, {
+      $type: "shadow",
+      $value: { color: dtcgColor(s.light), offsetX: { value: s.x, unit: "px" }, offsetY: { value: s.y, unit: "px" }, blur: { value: s.blur, unit: "px" }, spread: { value: s.spread, unit: "px" } },
+      $extensions: ext({ modes: { dark: { color: dtcgColor(s.dark) } } }),
+    }])),
+  };
+  return JSON.stringify(out, null, 2) + "\n";
+}
+
+const py = (v) => JSON.stringify(v);
+const pyKey = (k) => k.replace(/-/g, "_");
+
+/** Python module: PALETTES = {"light": {...}, "dark": {...}} with plain hex (alpha tokens pre-blended), plus sizes and fonts. */
+export function toPython(data) {
+  const L = [];
+  L.push(`# omnia_tokens.py — OmniaCSS ${data.omniacss} semantic tokens for non-web apps (Tkinter, Qt, ...).`);
+  L.push("# Generated by: npx omniacss tokens --format python  (do not edit; regenerate after an OmniaCSS update)");
+  L.push("# Map: OMNIACSS_VERSION -> PALETTES (hex per mode) -> ALPHA -> OKLCH -> SIZES/TEXT -> FONTS -> SHADOWS -> font()");
+  L.push("#");
+  L.push("# Colors are resolved from light-dark(var(--color-...)) and gamut mapped to sRGB the CSS Color 4 way.");
+  L.push("# Tokens with transparency (see ALPHA) are pre-blended over \"background\" in PALETTES.");
+  L.push("");
+  L.push(`OMNIACSS_VERSION = ${py(data.omniacss)}`);
+  L.push("");
+  L.push("PALETTES = {");
+  for (const mode of data.modes) {
+    L.push(`    ${py(mode)}: {`);
+    for (const [name, t] of Object.entries(data.colors)) L.push(`        ${py(pyKey(name))}: ${py(t[mode].opaqueHex ?? t[mode].hex)},`);
+    L.push("    },");
+  }
+  L.push("}");
+  L.push("");
+  L.push("# Transparent tokens: (hex of the color itself, alpha). PALETTES holds the blended result.");
+  L.push("ALPHA = {");
+  for (const mode of data.modes) {
+    const items = Object.entries(data.colors).filter(([, t]) => t[mode].alpha !== undefined).map(([n, t]) => `${py(pyKey(n))}: (${py(t[mode].hex)}, ${t[mode].alpha})`);
+    L.push(`    ${py(mode)}: {${items.join(", ")}},`);
+  }
+  L.push("}");
+  L.push("");
+  L.push("# Source colors (for wide-gamut renderers).");
+  L.push("OKLCH = {");
+  for (const mode of data.modes) {
+    L.push(`    ${py(mode)}: {`);
+    for (const [name, t] of Object.entries(data.colors)) L.push(`        ${py(pyKey(name))}: ${py(t[mode].oklch)},`);
+    L.push("    },");
+  }
+  L.push("}");
+  L.push("");
+  L.push("# Sizes in px (rem base 16 px); pt = px * 0.75.");
+  L.push(`SIZES = {${Object.entries(data.sizes).map(([k, v]) => `${py(pyKey(k))}: ${v.px}`).join(", ")}}`);
+  L.push(`TEXT = {${Object.entries(data.text).map(([k, v]) => `${py(k)}: ${v.px}`).join(", ")}}`);
+  L.push(`TEXT_PT = {${Object.entries(data.text).map(([k, v]) => `${py(k)}: ${v.pt}`).join(", ")}}`);
+  L.push("");
+  L.push("FONTS = {");
+  for (const [k, f] of Object.entries(data.fonts)) L.push(`    ${py(k)}: {"windows": ${py(f.windows)}, "macos": ${py(f.macos)}, "linux": ${py(f.linux)}},`);
+  L.push("}");
+  L.push("");
+  L.push("# Shadows: x, y, blur, spread in px; color hex + alpha per mode.");
+  L.push("SHADOWS = {");
+  for (const [k, s] of Object.entries(data.shadows)) {
+    L.push(`    ${py(k)}: {"x": ${s.x}, "y": ${s.y}, "blur": ${s.blur}, "spread": ${s.spread}, ` +
+      `"light": (${py(s.light.hex)}, ${s.light.alpha}), "dark": (${py(s.dark.hex)}, ${s.dark.alpha})},`);
+  }
+  L.push("}");
+  L.push("");
+  L.push("");
+  L.push("def font(name=\"sans\", platform=None):");
+  L.push("    \"\"\"Font family for this platform (sys.platform: win32 / darwin / linux).\"\"\"");
+  L.push("    import sys");
+  L.push("    key = {\"win32\": \"windows\", \"darwin\": \"macos\"}.get(platform or sys.platform, \"linux\")");
+  L.push("    return FONTS[name][key]");
+  L.push("");
+  return L.join("\n");
+}
+
+export const FORMATS = { json: toJson, dtcg: toDtcg, python: toPython };
+export const EXTENSIONS = { json: "omnia.tokens.json", dtcg: "omnia.dtcg.json", python: "omnia_tokens.py" };

package/src/variants.mjs

@@ -0,0 +1,278 @@
+// File: packages/core/src/variants.mjs
+// On-demand variants for the OmniaCSS engine: hover:, md:, group-hover:, has-[..]:, aria-*, data-*, dark:, cq-md: …
+// A variant maps a list of "branches" ({ sel, at }) around the utility: `sel` is a selector template where `&` stands
+// for the utility class, `at` the list of wrapping at-rules (outermost first). Most variants keep one branch; dark: makes two.
+// Map: breakpoints -> maps -> parseCandidate -> applyVariant -> resolveVariants
+// Author: Serge Cools | Framework: OmniaCSS
+
+/** Viewport breakpoints (min-width). sm/md/lg match the native responsive utilities (_responsive.scss). */
+export const BREAKPOINTS = { sm: "36rem", md: "50rem", lg: "64rem", xl: "80rem", "2xl": "96rem" };
+
+/** Container-query sizes for cq-<size>: (xs..xl match _containment.scss). */
+export const CONTAINER_SIZES = {
+  "3xs": "16rem", "2xs": "18rem", xs: "20rem", sm: "24rem", md: "28rem", lg: "32rem", xl: "36rem",
+  "2xl": "42rem", "3xl": "48rem", "4xl": "56rem", "5xl": "64rem", "6xl": "72rem", "7xl": "80rem",
+};
+
+const PSEUDO_CLASS = {
+  hover: ":hover", focus: ":focus", "focus-visible": ":focus-visible", "focus-within": ":focus-within", active: ":active",
+  visited: ":visited", target: ":target", disabled: ":disabled", enabled: ":enabled", checked: ":checked", indeterminate: ":indeterminate",
+  default: ":default", required: ":required", optional: ":optional", valid: ":valid", invalid: ":invalid", "user-valid": ":user-valid",
+  "user-invalid": ":user-invalid", "in-range": ":in-range", "out-of-range": ":out-of-range", "read-only": ":read-only",
+  "placeholder-shown": ":placeholder-shown", autofill: ":autofill", empty: ":empty",
+  first: ":first-child", last: ":last-child", only: ":only-child", odd: ":nth-child(odd)", even: ":nth-child(even)",
+  "first-of-type": ":first-of-type", "last-of-type": ":last-of-type", "only-of-type": ":only-of-type",
+  open: ":is([open], :popover-open, :open)", "popover-open": ":popover-open", inert: ":is([inert], [inert] *)",
+};
+const STATE_ORDER = ["visited", "target", "open", "popover-open", "default", "checked", "indeterminate", "placeholder-shown", "autofill", "optional", "required", "valid", "invalid", "user-valid", "user-invalid", "in-range", "out-of-range", "read-only", "empty", "focus-within", "hover", "focus", "focus-visible", "active", "enabled", "disabled", "inert"];
+const STRUCT_ORDER = ["first", "last", "only", "odd", "even", "first-of-type", "last-of-type", "only-of-type"];
+
+const PSEUDO_ELEMENT = {
+  before: "::before", after: "::after", "first-letter": "::first-letter", "first-line": "::first-line", marker: "::marker",
+  placeholder: "::placeholder", backdrop: "::backdrop", file: "::file-selector-button", selection: "::selection", "details-content": "::details-content",
+};
+
+const MEDIA = {
+  print: "print", "motion-safe": "(prefers-reduced-motion: no-preference)", "motion-reduce": "(prefers-reduced-motion: reduce)",
+  portrait: "(orientation: portrait)", landscape: "(orientation: landscape)", "contrast-more": "(prefers-contrast: more)",
+  "contrast-less": "(prefers-contrast: less)", "forced-colors": "(forced-colors: active)", "inverted-colors": "(inverted-colors: inverted)",
+  "pointer-fine": "(pointer: fine)", "pointer-coarse": "(pointer: coarse)", "pointer-none": "(pointer: none)",
+  "any-pointer-fine": "(any-pointer: fine)", "any-pointer-coarse": "(any-pointer: coarse)", "any-pointer-none": "(any-pointer: none)",
+  "hover-capable": "(hover: hover)", noscript: "(scripting: none)", "auto-dark": "(prefers-color-scheme: dark)",
+};
+
+/** Scroll-state container queries (the element must sit inside a `container-scroll-state` ancestor). */
+const SCROLL_STATE = {
+  stuck: "not scroll-state(stuck: none)", "stuck-top": "scroll-state(stuck: top)", "stuck-bottom": "scroll-state(stuck: bottom)",
+  "stuck-left": "scroll-state(stuck: left)", "stuck-right": "scroll-state(stuck: right)",
+  snapped: "not scroll-state(snapped: none)", "snapped-x": "scroll-state(snapped: x)", "snapped-y": "scroll-state(snapped: y)",
+  "scrollable-top": "scroll-state(scrollable: top)", "scrollable-bottom": "scroll-state(scrollable: bottom)",
+  "scrollable-left": "scroll-state(scrollable: left)", "scrollable-right": "scroll-state(scrollable: right)",
+};
+
+const ARIA = ["busy", "checked", "disabled", "expanded", "hidden", "pressed", "readonly", "required", "selected"];
+
+/** Fixed variant names per group (for editor tooling such as the OmniaCSS IntelliSense extension). */
+export const VARIANT_GROUPS = {
+  pseudoClass: Object.keys(PSEUDO_CLASS), pseudoElement: Object.keys(PSEUDO_ELEMENT), media: Object.keys(MEDIA),
+  scrollState: Object.keys(SCROLL_STATE), aria: ARIA, other: ["dark", "rtl", "ltr", "starting", "*", "**"],
+};
+
+const DARK_EXPLICIT = ':where(.dark, [data-theme="dark"], :root:has(.oc-theme-switch input[value="dark"]:checked))';
+const DARK_SYSTEM = ':where(:root:not([data-theme="light"], .light, :has(.oc-theme-switch input[value="light"]:checked)))';
+
+/** Escape a string for use in a class selector. */
+export function esc(s) {
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (/[0-9]/.test(ch) && (i === 0 || (i === 1 && s[0] === "-"))) out += "\\3" + ch + " ";
+    else if (/[A-Za-z0-9_\-¡-￿]/.test(ch)) out += ch;
+    else out += "\\" + ch;
+  }
+  return out;
+}
+
+/** Split on `sep` outside of [] and (). */
+export function splitTop(str, sep = ":") {
+  const out = [];
+  let depth = 0, cur = "";
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === "\\") { cur += ch + (str[++i] ?? ""); continue; }
+    if (ch === "[" || ch === "(") depth++;
+    else if (ch === "]" || ch === ")") depth--;
+    if (ch === sep && depth === 0) { out.push(cur); cur = ""; } else cur += ch;
+  }
+  out.push(cur);
+  return out;
+}
+
+/** `[a_b]` -> `a b` (underscore = space, `\_` stays an underscore). */
+const arbitrary = (s) => {
+  const m = s.match(/^\[([\s\S]+)\]$/);
+  return m ? m[1].replace(/\\_/g, "\u0000").replace(/_/g, " ").replace(/\u0000/g, "_") : null;
+};
+
+const quoteAttr = (s) => {
+  const m = s.match(/^([^=~|^$*]+)([~|^$*]?=)(.*)$/);
+  if (!m) return s;
+  const v = /^["']/.test(m[3]) ? m[3] : `"${m[3]}"`;
+  return `${m[1]}${m[2]}${v}`;
+};
+
+/** Append a simple selector in front of a trailing pseudo-element: `&::after` + `:hover` -> `&:hover::after`. */
+function addSimple(sel, suffix) {
+  const m = sel.match(/^(.*?)(::[a-z-]+)$/s);
+  return m ? m[1] + suffix + m[2] : sel + suffix;
+}
+
+/**
+ * Parse a class token: `md:hover:!bg-x` -> { variants: ["md","hover"], base: "bg-x", important: true }.
+ * Returns null when there is nothing to do (no variants and no `!`).
+ */
+export function parseCandidate(token) {
+  if (token.length > 120) return null;
+  const parts = splitTop(token, ":");
+  let base = parts.pop();
+  if (!base) return null;
+  let important = false;
+  if (base.startsWith("!")) { important = true; base = base.slice(1); }
+  else if (base.endsWith("!")) { important = true; base = base.slice(0, -1); }
+  if (!/^-?[A-Za-z]/.test(base)) return null;
+  if (!parts.length && !important) return null;
+  if (parts.some((p) => !p)) return null;
+  return { token, variants: parts, base, important };
+}
+
+const state = (sel = "&", at = []) => ({ sel, at });
+
+/** Selector pattern of a variant that only changes the element's selector ("&:hover"), or null. */
+function innerPattern(name) {
+  const r = applyVariant(name, [state()]);
+  return r && r.length === 1 && !r[0].at.length ? r[0].sel : null;
+}
+
+const patternOf = (name) => {
+  const a = arbitrary(name);
+  if (a !== null) return a.includes("&") ? a : `&${a}`;
+  return innerPattern(name);
+};
+
+/**
+ * Apply one variant to a list of branches.
+ * @returns {{sel:string, at:string[]}[]|null} null when the variant is unknown
+ */
+export function applyVariant(name, branches) {
+  const mapSel = (fn) => branches.map((b) => ({ ...b, sel: fn(b.sel) }));
+  const wrap = (at) => branches.map((b) => ({ ...b, at: [...b.at, at] }));
+  let m;
+
+  if (Object.hasOwn(PSEUDO_CLASS, name)) return mapSel((s) => addSimple(s, PSEUDO_CLASS[name]));
+  // marker: and selection: also reach the descendants (<ul class="marker:…"> colors the bullets of its <li>s).
+  if (name === "marker" || name === "selection") {
+    return branches.flatMap((b) => [{ ...b, sel: b.sel + PSEUDO_ELEMENT[name] }, { ...b, sel: `${b.sel} *${PSEUDO_ELEMENT[name]}` }]);
+  }
+  if (Object.hasOwn(PSEUDO_ELEMENT, name)) return mapSel((s) => s + PSEUDO_ELEMENT[name]);
+  if (Object.hasOwn(MEDIA, name)) return wrap(`@media ${MEDIA[name]}`);
+  if (Object.hasOwn(SCROLL_STATE, name)) return wrap(`@container ${SCROLL_STATE[name]}`);
+  if (name === "starting") return wrap("@starting-style");
+  if (name === "rtl" || name === "ltr") return mapSel((s) => addSimple(s, `:where(:dir(${name}), [dir="${name}"], [dir="${name}"] *)`));
+  if (name === "dark") {
+    return branches.flatMap((b) => [
+      { sel: `${DARK_EXPLICIT} ${b.sel}`, at: b.at },
+      { sel: `${DARK_SYSTEM} ${b.sel}`, at: [...b.at, "@media (prefers-color-scheme: dark)"] },
+    ]);
+  }
+  if (name === "*") return mapSel((s) => `${s} > *`);
+  if (name === "**") return mapSel((s) => `${s} *`);
+
+  // viewport: sm, max-sm, min-sm, min-[600px], max-[600px]
+  if (Object.hasOwn(BREAKPOINTS, name)) return wrap(`@media (min-width: ${BREAKPOINTS[name]})`);
+  if ((m = name.match(/^(min|max)-(.+)$/))) {
+    const [, kind, rest] = m;
+    const a = arbitrary(rest);
+    const v = a ?? BREAKPOINTS[rest];
+    if (v) return wrap(kind === "min" ? `@media (min-width: ${v})` : `@media (width < ${v})`);
+  }
+  // container queries: cq-md, cq-max-md, cq-[400px], cq-md/name (and the short form @md)
+  if ((m = name.match(/^(?:cq-|@)(?:(min|max)-)?(.+?)(?:\/([\w-]+))?$/))) {
+    const [, kind, size, cname] = m;
+    const a = arbitrary(size);
+    const v = a ?? CONTAINER_SIZES[size];
+    if (v) return wrap(`@container ${cname ? cname + " " : ""}${kind === "max" ? `(width < ${v})` : `(min-width: ${v})`}`);
+  }
+  // supports
+  if ((m = name.match(/^(not-)?supports-(.+)$/))) {
+    const a = arbitrary(m[2]);
+    const cond = a !== null ? (/^[\w-]+\s*:/.test(a) ? `(${a})` : /^[\w-]+$/.test(a) ? `(${a}: inherit)` : a) : `(${m[2]}: inherit)`;
+    return wrap(`@supports ${m[1] ? "not " : ""}${cond}`);
+  }
+  // data-* / aria-*
+  if ((m = name.match(/^data-(.+)$/))) {
+    const a = arbitrary(m[1]);
+    return mapSel((s) => addSimple(s, a !== null ? `[data-${quoteAttr(a)}]` : `[data-${m[1]}]`));
+  }
+  if ((m = name.match(/^aria-(.+)$/))) {
+    const a = arbitrary(m[1]);
+    if (a === null && !ARIA.includes(m[1])) return null;
+    return mapSel((s) => addSimple(s, a !== null ? `[aria-${quoteAttr(a)}]` : `[aria-${m[1]}="true"]`));
+  }
+  // group-* / peer-*  (optionally named: group-hover/card)
+  if ((m = name.match(/^(group|peer)-(.+?)(?:\/([\w-]+))?$/))) {
+    const [, kind, innerName, gname] = m;
+    const pattern = patternOf(innerName);
+    if (!pattern) return null;
+    const marker = `:where(.${kind}${gname ? "\\/" + esc(gname) : ""})`;
+    const rel = pattern.replace(/&/g, marker);
+    return mapSel((s) => addSimple(s, `:is(${rel} ${kind === "group" ? "*" : "~ *"})`));
+  }
+  // has-* / not-* / in-*
+  if ((m = name.match(/^(has|not|in)-(.+)$/))) {
+    const [, kind, innerName] = m;
+    const pattern = patternOf(innerName);
+    if (!pattern && kind === "not") {
+      // not-md, not-print, not-supports-[..]
+      const inner = applyVariant(innerName, [state()]);
+      if (inner && inner.length === 1 && inner[0].at.length === 1) {
+        const at = inner[0].at[0];
+        if (/^@media /.test(at)) { const p = at.slice(7); return wrap(`@media not ${p.startsWith("(") ? "all and " : ""}${p}`); }
+        if (/^@supports not /.test(at)) return wrap(at.replace("@supports not ", "@supports "));
+        if (/^@supports /.test(at)) return wrap(at.replace("@supports ", "@supports not "));
+      }
+      return null;
+    }
+    if (!pattern || !pattern.startsWith("&")) return null;
+    const rest = pattern.slice(1);
+    if (kind === "has") return mapSel((s) => addSimple(s, `:has(${rest})`));
+    if (kind === "not") return mapSel((s) => addSimple(s, `:not(${rest})`));
+    return mapSel((s) => `:where(${rest || "*"}) ${s}`);
+  }
+  if ((m = name.match(/^nth-(last-)?(of-type-)?(.+)$/))) {
+    const a = arbitrary(m[3]);
+    const arg = a ?? (/^\d+$/.test(m[3]) ? m[3] : /^(odd|even)$/.test(m[3]) ? m[3] : null);
+    if (arg === null) return null;
+    return mapSel((s) => addSimple(s, `:nth-${m[1] ? "last-" : ""}${m[2] ? "of-type" : "child"}(${arg})`));
+  }
+  // arbitrary variant: [&>svg]:, [&_p]:, [@media(min-width:900px)]:
+  if ((m = name.match(/^\[([\s\S]+)\]$/))) {
+    const body = arbitrary(name);
+    if (body.startsWith("@")) return wrap(body.replace(/^@(media|supports|container)\s*/, "@$1 "));
+    if (!body.includes("&")) return null;
+    return mapSel((s) => body.replace(/&/g, s));
+  }
+  return null;
+}
+
+/** Apply all variants left to right. Returns branches or null if any variant is unknown. */
+export function resolveVariants(variants) {
+  let branches = [state()];
+  for (const v of variants) {
+    branches = applyVariant(v, branches);
+    if (!branches) return null;
+  }
+  return branches;
+}
+
+/** Cascade rank of a variant list: states < group/peer < attribute < media < dark < screens < containers. */
+export function rankOf(variants) {
+  let rank = 0;
+  for (const v of variants) {
+    let r;
+    if (Object.hasOwn(PSEUDO_ELEMENT, v)) r = 100;
+    else if (STRUCT_ORDER.includes(v)) r = 200 + STRUCT_ORDER.indexOf(v);
+    else if (Object.hasOwn(PSEUDO_CLASS, v)) r = 300 + STATE_ORDER.indexOf(v);
+    else if (/^(group|peer|in)-/.test(v)) r = 400;
+    else if (/^(has|not|aria|data|nth)-|^[*\[]/.test(v)) r = 500;
+    else if (/^(not-)?supports-/.test(v)) r = 600;
+    else if (v === "rtl" || v === "ltr") r = 650;
+    else if (Object.hasOwn(MEDIA, v) || Object.hasOwn(SCROLL_STATE, v)) r = 700;
+    else if (v === "dark") r = 800;
+    else if (v === "starting") r = 900;
+    else if (/^max-/.test(v)) r = 1000 - Object.keys(BREAKPOINTS).indexOf(v.slice(4)) * 10;
+    else if (Object.hasOwn(BREAKPOINTS, v) || /^min-/.test(v)) r = 1100 + Object.keys(BREAKPOINTS).indexOf(v.replace(/^min-/, "")) * 10;
+    else r = 2000;
+    rank += r;
+  }
+  return rank;
+}