@transtyle/core 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@transtyle/core",
+  "version": "0.1.0-alpha.0",
+  "description": "Transtyle core: compilation pipeline (load, normalize, derive, resolve, emit, report).",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@transtyle/ir": "0.1.0-alpha.0"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transtyle/transtyle.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/transtyle/transtyle#readme",
+  "bugs": "https://github.com/transtyle/transtyle/issues",
+  "license": "MIT"
+}

package/src/checks.js

@@ -0,0 +1,74 @@
+/** Built-in accessibility/consistency checks (docs/specs/validation-and-coverage.md). */
+
+import { contrastRatio } from './color.js';
+
+const S = 'semantic.color.';
+
+/**
+ * The foreground/background pairs the compiler contrast-checks. Shared with
+ * `transtyle diff`'s contrast-regression flag (diff.js) so "which pairs count"
+ * has exactly one definition — a pair added here is checked in both places.
+ */
+export const CONTRAST_PAIRS = [
+  ['text.base', 'elevation.0.surface'],
+  ['text.base', 'elevation.1.surface'],
+  ['text.muted', 'elevation.0.surface'],
+  ['text.muted', 'elevation.1.surface'],
+];
+
+/** Minimum ratio for the configured standard (normal text). */
+export function contrastThreshold(config) {
+  return config?.check?.contrast?.standard === 'wcag21-aaa' ? 7 : 4.5;
+}
+
+/** The pair's ratio in one resolved mode map, or null if either slot is absent. */
+export function pairRatio(map, fg, bg) {
+  const f = map.get(S + fg)?.value;
+  const b = map.get(S + bg)?.value;
+  if (!f || !b) return null;
+  return contrastRatio(f, b);
+}
+
+export function runChecks(normalized, config, diagnostics) {
+  const min = contrastThreshold(config);
+  const standard = config?.check?.contrast?.standard ?? 'wcag21-aa';
+  for (const mode of normalized.modeValues) {
+    const map = normalized.modes[mode];
+    for (const [fg, bg] of CONTRAST_PAIRS) {
+      const ratio = pairRatio(map, fg, bg);
+      if (ratio === null) continue;
+      if (ratio < min) {
+        // AL5: on a design system with no dark-mode values authored, the
+        // light values simply carry over — so a light-on-light pair is
+        // flagged in dark mode and the warning looks like a mystery about
+        // colors the user never wrote. When this mode's pair is byte-identical
+        // to the default mode's, that carry-over IS the reason, and saying so
+        // is the difference between an actionable warning and noise the user
+        // learns to ignore.
+        //
+        // `derivation.autoDark` is NOT consulted here (or anywhere in the
+        // pipeline): it's specced (derivation.md) but not implemented, so the
+        // hint below must not suggest it as a working remedy — "opt into
+        // autoDark" used to be here and was accurate-sounding but false.
+        const defaultMap = normalized.modes[normalized.defaultMode];
+        const carried =
+          mode === normalized.defaultMode
+            ? []
+            : [fg, bg].filter(
+                (p) =>
+                  JSON.stringify(map.get(`${S}${p}`)?.value) ===
+                  JSON.stringify(defaultMap?.get(`${S}${p}`)?.value),
+              );
+        diagnostics.warn(
+          'TST2101',
+          `${fg} vs ${bg} is ${ratio.toFixed(1)}:1 in ${mode} mode (< ${min}:1 ${standard})`,
+          carried.length
+            ? {
+                hint: `${carried.join(' and ')} ${carried.length > 1 ? 'are' : 'is'} unchanged from ${normalized.defaultMode} mode — nothing authors a ${mode} value, so ${carried.length > 1 ? 'they' : 'it'} carried over. Author the ${mode} value.`,
+              }
+            : {},
+        );
+      }
+    }
+  }
+}

package/src/color.js

@@ -0,0 +1,272 @@
+/**
+ * Minimal OKLCH color engine (zero deps).
+ * Internal canonical form: { l, c, h, alpha } — docs/architecture/ir.md#values.
+ */
+
+import { NAMED_COLORS } from './css-colors.js';
+
+const OKLCH_RE = /^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+%?))?\s*\)$/i;
+const FUNC_RE = /^(rgba?|hsla?)\(\s*([^)]*)\s*\)$/i;
+
+/**
+ * Parse any color syntax a real stylesheet is likely to contain
+ * (docs/architecture/ir.md#values): `oklch()`, `#hex` (3/4/6/8 digits),
+ * `rgb()`/`rgba()`, `hsl()`/`hsla()`, the CSS named colors, and `transparent`.
+ * Both the modern space-separated (`rgb(255 0 0 / 50%)`) and legacy comma
+ * (`rgba(255, 0, 0, .5)`) forms are accepted. Everything canonicalizes to OKLCH.
+ */
+export function parseColor(str) {
+  if (typeof str !== 'string') throw new Error(`Not a color string: ${JSON.stringify(str)}`);
+  const s = str.trim();
+
+  const m = OKLCH_RE.exec(s);
+  if (m) {
+    const num = (v) => (v.endsWith('%') ? parseFloat(v) / 100 : parseFloat(v));
+    return { l: num(m[1]), c: parseFloat(m[2]), h: parseFloat(m[3]), alpha: m[4] ? num(m[4]) : 1 };
+  }
+
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(s)) {
+    const { alpha, ...rgb } = hexToSrgb(s);
+    return srgbToOklch(rgb, alpha);
+  }
+
+  const fn = FUNC_RE.exec(s);
+  if (fn) {
+    const kind = fn[1].toLowerCase();
+    const { parts, alpha } = splitComponents(fn[2]);
+    if (parts.length < 3) throw new Error(`Malformed ${kind}() color: ${s}`);
+    const a = parseAlpha(alpha);
+    if (kind.startsWith('rgb')) {
+      const ch = (v) => (v === 'none' ? 0 : v.endsWith('%') ? parseFloat(v) / 100 : parseFloat(v) / 255);
+      const rgb = { r: ch(parts[0]), g: ch(parts[1]), b: ch(parts[2]) };
+      if (Object.values(rgb).some(Number.isNaN)) throw new Error(`Malformed ${kind}() color: ${s}`);
+      return srgbToOklch(rgb, a);
+    }
+    const h = parseHue(parts[0]);
+    const pct = (v) => (v === 'none' ? 0 : parseFloat(v) / 100);
+    const sat = pct(parts[1]), lig = pct(parts[2]);
+    if ([h, sat, lig].some(Number.isNaN)) throw new Error(`Malformed ${kind}() color: ${s}`);
+    return srgbToOklch(hslToSrgb(h, sat, lig), a);
+  }
+
+  const lower = s.toLowerCase();
+  if (lower === 'transparent') return { l: 0, c: 0, h: 0, alpha: 0 };
+  if (NAMED_COLORS[lower]) {
+    const { alpha, ...rgb } = hexToSrgb(NAMED_COLORS[lower]);
+    return srgbToOklch(rgb, alpha);
+  }
+
+  throw new Error(`Unsupported color syntax: ${s} (expected oklch(), #hex, rgb(), hsl(), or a CSS named color)`);
+}
+
+/** Split a function body into 3 components + optional alpha, modern or legacy form. */
+function splitComponents(inner) {
+  const body = inner.trim();
+  const slash = body.indexOf('/');
+  if (slash !== -1) {
+    return { parts: body.slice(0, slash).trim().split(/\s+/), alpha: body.slice(slash + 1).trim() };
+  }
+  if (body.includes(',')) {
+    const all = body.split(',').map((p) => p.trim());
+    return { parts: all.slice(0, 3), alpha: all[3] };
+  }
+  return { parts: body.split(/\s+/), alpha: undefined };
+}
+
+const parseAlpha = (v) => {
+  if (v === undefined || v === '' || v === 'none') return 1;
+  const n = v.endsWith('%') ? parseFloat(v) / 100 : parseFloat(v);
+  return Number.isNaN(n) ? 1 : Math.min(1, Math.max(0, n));
+};
+
+/** CSS <angle> → degrees (deg/rad/grad/turn, or unitless = deg). */
+function parseHue(v) {
+  const m = /^(-?[\d.]+)(deg|rad|grad|turn)?$/i.exec(v.trim());
+  if (!m) return NaN;
+  const n = parseFloat(m[1]);
+  switch ((m[2] ?? 'deg').toLowerCase()) {
+    case 'rad': return (n * 180) / Math.PI;
+    case 'grad': return n * 0.9;
+    case 'turn': return n * 360;
+    default: return n;
+  }
+}
+
+function hslToSrgb(hDeg, s, l) {
+  const h = ((hDeg % 360) + 360) % 360;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  const [r, g, b] =
+    h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x]
+    : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  return { r: r + m, g: g + m, b: b + m };
+}
+
+export function formatColor({ l, c, h, alpha = 1 }) {
+  const r3 = (n) => Math.round(n * 1000) / 1000;
+  const L = Math.min(1, Math.max(0, r3(l)));
+  let C = Math.max(0, r3(c));
+  let H = Math.round(h * 10) / 10;
+  if (C < 0.002) { C = 0; H = 0; } // achromatic: drop meaningless hue
+  const a = alpha < 1 ? ` / ${r3(alpha)}` : '';
+  return `oklch(${L} ${C} ${H}${a})`;
+}
+
+/** Mix a toward b by t (0 = a, 1 = b), in OKLCH with shortest-path hue. */
+export function mix(a, b, t) {
+  // Cartesian OKLab interpolation (derivation.md, pinned by exercise F21).
+  // Polar hue lerp passes through unrelated hues at moderate ratios (an amber
+  // border tint on a blue-cast surface must not travel through cyan).
+  const lerp = (x, y) => x + (y - x) * t;
+  const rad = Math.PI / 180;
+  const A = lerp(a.c * Math.cos(a.h * rad), b.c * Math.cos(b.h * rad));
+  const B = lerp(a.c * Math.sin(a.h * rad), b.c * Math.sin(b.h * rad));
+  const c = Math.sqrt(A * A + B * B);
+  const h = c < 1e-9 ? 0 : (Math.atan2(B, A) / rad + 360) % 360;
+  return { l: lerp(a.l, b.l), c, h, alpha: lerp(a.alpha ?? 1, b.alpha ?? 1) };
+}
+
+// ---- OKLab <-> linear sRGB (Björn Ottosson's matrices) ----
+
+function oklchToLinearSrgb({ l, c, h }) {
+  const hr = (h * Math.PI) / 180;
+  const a = c * Math.cos(hr);
+  const b = c * Math.sin(hr);
+  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 {
+    r: 4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+    g: -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+    b: -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+  };
+}
+
+/** #rgb / #rgba / #rrggbb / #rrggbbaa → sRGB (+ alpha). */
+function hexToSrgb(hex) {
+  let s = hex.slice(1);
+  if (s.length === 3 || s.length === 4) s = s.split('').map((ch) => ch + ch).join('');
+  const n = parseInt(s.slice(0, 6), 16);
+  const alpha = s.length === 8 ? parseInt(s.slice(6, 8), 16) / 255 : 1;
+  return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255, alpha };
+}
+
+function srgbToLinear(v) {
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+}
+
+function srgbToOklch({ r, g, b }, alpha = 1) {
+  const lr = srgbToLinear(r), lg = srgbToLinear(g), lb = srgbToLinear(b);
+  const l_ = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m_ = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s_ = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const A = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+  const c = Math.hypot(A, B);
+  const h = ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;
+  return { l: L, c, h, alpha };
+}
+
+const linearToSrgb = (v) => (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055);
+
+const inSrgbGamut = ({ r, g, b }) => r >= -0.0005 && r <= 1.0005 && g >= -0.0005 && g <= 1.0005 && b >= -0.0005 && b <= 1.0005;
+
+/**
+ * Reduce chroma at a fixed lightness/hue until the color lands inside the
+ * sRGB gamut (binary search; ~20 steps is well under float precision).
+ * Keeps `l` and `h` exactly as given — only `c` moves — because rules like
+ * F20 (contrast-anchor) pick `l`/`h` for a reason (contrast, brand hue) and
+ * should not have those silently perturbed by channel-clipping downstream.
+ * A no-op when the color is already in gamut.
+ */
+export function clampChromaToGamut({ l, c, h, alpha = 1 }) {
+  if (c <= 0 || inSrgbGamut(oklchToLinearSrgb({ l, c, h }))) return { l, c, h, alpha };
+  let lo = 0, hi = c;
+  for (let i = 0; i < 20; i++) {
+    const mid = (lo + hi) / 2;
+    if (inSrgbGamut(oklchToLinearSrgb({ l, c: mid, h }))) lo = mid;
+    else hi = mid;
+  }
+  return { l, c: lo, h, alpha };
+}
+
+/**
+ * OKLCH → gamma-encoded sRGB. `clamped` is true when the color was outside the
+ * sRGB gamut and had to be clamped (coverage class: approximated).
+ */
+export function oklchToSrgb(color) {
+  const lin = oklchToLinearSrgb(color);
+  let clamped = false;
+  const enc = (v) => {
+    if (v < -0.005 || v > 1.005) clamped = true;
+    return linearToSrgb(Math.min(1, Math.max(0, v)));
+  };
+  return { r: enc(lin.r), g: enc(lin.g), b: enc(lin.b), clamped };
+}
+
+/**
+ * Format as an HSL channel triplet ("221 83% 53%") — the shadcn tailwind-v3
+ * convention (wrapped by components as hsl(var(--x))).
+ */
+export function formatHslTriplet(color) {
+  // Near-achromatic: drop the meaningless hue/saturation before conversion,
+  // otherwise rounding noise yields absurd triplets like "180 100% 99.9%".
+  const input = color.c < 0.002 ? { ...color, c: 0 } : color;
+  const { r, g, b, clamped } = oklchToSrgb(input);
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  let h = 0, s = 0;
+  if (d > 1e-6) {
+    s = d / (1 - Math.abs(2 * l - 1));
+    if (max === r) h = ((g - b) / d) % 6;
+    else if (max === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h = (h * 60 + 360) % 360;
+  }
+  const r1 = (n) => Math.round(n * 10) / 10;
+  return { text: `${r1(h)} ${r1(s * 100)}% ${r1(l * 100)}%`, clamped };
+}
+
+/**
+ * Format as #rrggbb hex (canvas-friendly: ECharts). `clamped` mirrors oklchToSrgb.
+ *
+ * Round-trip note (measured exhaustively, guarded by scripts/check-color.mjs):
+ * `formatHex(parseColor(hex))` returns the input for all but 1580 of the
+ * 16,777,216 sRGB values (0.0094%), which come back ±1/255. Those all sit in the
+ * near-black range, where sRGB's transfer curve is steepest relative to an 8-bit
+ * step; it is inherent to canonicalizing through OKLCH in float64. Determinism is
+ * unaffected — the same input always yields the same output.
+ */
+export function formatHex(color) {
+  const input = color.c < 0.002 ? { ...color, c: 0 } : color;
+  const { r, g, b, clamped } = oklchToSrgb(input);
+  const h2 = (v) => Math.round(v * 255).toString(16).padStart(2, '0');
+  return { text: `#${h2(r)}${h2(g)}${h2(b)}`, clamped };
+}
+
+/** WCAG 2.1 relative luminance (via linear sRGB, gamut-clamped). */
+export function relativeLuminance(color) {
+  const { r, g, b } = oklchToLinearSrgb(color);
+  const cl = (v) => Math.min(1, Math.max(0, v));
+  return 0.2126 * cl(r) + 0.7152 * cl(g) + 0.0722 * cl(b);
+}
+
+/** WCAG 2.1 contrast ratio between two colors (order-independent). */
+export function contrastRatio(a, b) {
+  const ya = relativeLuminance(a), yb = relativeLuminance(b);
+  const [hi, lo] = ya >= yb ? [ya, yb] : [yb, ya];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Pick the candidate with the highest contrast against bg. Returns { color, ratio, index }. */
+export function contrastPick(bg, candidates) {
+  let best = null;
+  candidates.forEach((cand, index) => {
+    const ratio = contrastRatio(bg, cand);
+    if (!best || ratio > best.ratio) best = { color: cand, ratio, index };
+  });
+  return best;
+}

package/src/css-colors.js

@@ -0,0 +1,46 @@
+/**
+ * The CSS Color Module Level 4 named colors (plus `transparent`), as sRGB hex.
+ *
+ * Kept as data in its own module so color.js stays readable. Real products use
+ * these verbatim — the P4 hostile-adoption experiment hit a hard stop on
+ * Miniflux's literal `red` and `purple` (docs/findings/hostile-adoption.md).
+ */
+export const NAMED_COLORS = {
+  aliceblue: '#f0f8ff', antiquewhite: '#faebd7', aqua: '#00ffff', aquamarine: '#7fffd4',
+  azure: '#f0ffff', beige: '#f5f5dc', bisque: '#ffe4c4', black: '#000000',
+  blanchedalmond: '#ffebcd', blue: '#0000ff', blueviolet: '#8a2be2', brown: '#a52a2a',
+  burlywood: '#deb887', cadetblue: '#5f9ea0', chartreuse: '#7fff00', chocolate: '#d2691e',
+  coral: '#ff7f50', cornflowerblue: '#6495ed', cornsilk: '#fff8dc', crimson: '#dc143c',
+  cyan: '#00ffff', darkblue: '#00008b', darkcyan: '#008b8b', darkgoldenrod: '#b8860b',
+  darkgray: '#a9a9a9', darkgreen: '#006400', darkgrey: '#a9a9a9', darkkhaki: '#bdb76b',
+  darkmagenta: '#8b008b', darkolivegreen: '#556b2f', darkorange: '#ff8c00', darkorchid: '#9932cc',
+  darkred: '#8b0000', darksalmon: '#e9967a', darkseagreen: '#8fbc8f', darkslateblue: '#483d8b',
+  darkslategray: '#2f4f4f', darkslategrey: '#2f4f4f', darkturquoise: '#00ced1', darkviolet: '#9400d3',
+  deeppink: '#ff1493', deepskyblue: '#00bfff', dimgray: '#696969', dimgrey: '#696969',
+  dodgerblue: '#1e90ff', firebrick: '#b22222', floralwhite: '#fffaf0', forestgreen: '#228b22',
+  fuchsia: '#ff00ff', gainsboro: '#dcdcdc', ghostwhite: '#f8f8ff', gold: '#ffd700',
+  goldenrod: '#daa520', gray: '#808080', green: '#008000', greenyellow: '#adff2f',
+  grey: '#808080', honeydew: '#f0fff0', hotpink: '#ff69b4', indianred: '#cd5c5c',
+  indigo: '#4b0082', ivory: '#fffff0', khaki: '#f0e68c', lavender: '#e6e6fa',
+  lavenderblush: '#fff0f5', lawngreen: '#7cfc00', lemonchiffon: '#fffacd', lightblue: '#add8e6',
+  lightcoral: '#f08080', lightcyan: '#e0ffff', lightgoldenrodyellow: '#fafad2', lightgray: '#d3d3d3',
+  lightgreen: '#90ee90', lightgrey: '#d3d3d3', lightpink: '#ffb6c1', lightsalmon: '#ffa07a',
+  lightseagreen: '#20b2aa', lightskyblue: '#87cefa', lightslategray: '#778899', lightslategrey: '#778899',
+  lightsteelblue: '#b0c4de', lightyellow: '#ffffe0', lime: '#00ff00', limegreen: '#32cd32',
+  linen: '#faf0e6', magenta: '#ff00ff', maroon: '#800000', mediumaquamarine: '#66cdaa',
+  mediumblue: '#0000cd', mediumorchid: '#ba55d3', mediumpurple: '#9370db', mediumseagreen: '#3cb371',
+  mediumslateblue: '#7b68ee', mediumspringgreen: '#00fa9a', mediumturquoise: '#48d1cc', mediumvioletred: '#c71585',
+  midnightblue: '#191970', mintcream: '#f5fffa', mistyrose: '#ffe4e1', moccasin: '#ffe4b5',
+  navajowhite: '#ffdead', navy: '#000080', oldlace: '#fdf5e6', olive: '#808000',
+  olivedrab: '#6b8e23', orange: '#ffa500', orangered: '#ff4500', orchid: '#da70d6',
+  palegoldenrod: '#eee8aa', palegreen: '#98fb98', paleturquoise: '#afeeee', palevioletred: '#db7093',
+  papayawhip: '#ffefd5', peachpuff: '#ffdab9', peru: '#cd853f', pink: '#ffc0cb',
+  plum: '#dda0dd', powderblue: '#b0e0e6', purple: '#800080', rebeccapurple: '#663399',
+  red: '#ff0000', rosybrown: '#bc8f8f', royalblue: '#4169e1', saddlebrown: '#8b4513',
+  salmon: '#fa8072', sandybrown: '#f4a460', seagreen: '#2e8b57', seashell: '#fff5ee',
+  sienna: '#a0522d', silver: '#c0c0c0', skyblue: '#87ceeb', slateblue: '#6a5acd',
+  slategray: '#708090', slategrey: '#708090', snow: '#fffafa', springgreen: '#00ff7f',
+  steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080', thistle: '#d8bfd8',
+  tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee', wheat: '#f5deb3',
+  white: '#ffffff', whitesmoke: '#f5f5f5', yellow: '#ffff00', yellowgreen: '#9acd32',
+};