@humanforest/nuxt-layer 0.1.0

package/packages/tokens/src/colourEngine.ts

@@ -0,0 +1,604 @@
+// colourEngine.ts — framework-free colour math: the canonical Forest colour-generation method.
+// All functions exported; consumed by the Forest colour documentation page.
+
+// ---- OKLCH ↔ sRGB (compact port of scales.ts) ----
+export const srgbToLin = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+export const linToSrgb = (c: number) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+export function hexToLin(hex: string): number[] {
+  const c = hex.replace('#', '');
+  return [0, 2, 4].map((i) => srgbToLin(parseInt(c.slice(i, i + 2), 16) / 255));
+}
+export function linToOklab([r, g, b]: number[]): number[] {
+  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 [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+export function oklabToLin([L, a, b]: number[]): number[] {
+  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,
+  ];
+}
+export const inGamut = (rgb: number[]) => rgb.every((v) => v >= -0.001 && v <= 1.001);
+export function oklchToHex(L: number, C: number, H: number): string {
+  const rad = (H * Math.PI) / 180;
+  let lin = oklabToLin([L, C * Math.cos(rad), C * Math.sin(rad)]);
+  if (!inGamut(lin)) {
+    let lo = 0, hi = C;
+    for (let i = 0; i < 24; i++) {
+      const c = (lo + hi) / 2;
+      inGamut(oklabToLin([L, c * Math.cos(rad), c * Math.sin(rad)])) ? (lo = c) : (hi = c);
+    }
+    lin = oklabToLin([L, lo * Math.cos(rad), lo * Math.sin(rad)]);
+  }
+  const to = (v: number) => Math.round(Math.max(0, Math.min(1, linToSrgb(v))) * 255).toString(16).padStart(2, '0');
+  return '#' + to(lin[0]) + to(lin[1]) + to(lin[2]);
+}
+export function hexToOklch(hex: string) {
+  const [L, a, b] = linToOklab(hexToLin(hex));
+  return { L, C: Math.hypot(a, b), H: ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360 };
+}
+// WCAG relative luminance (0–100) from a hex.
+export const lumF = (hex: string) => (([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b)(hexToLin(hex)) * 100;
+export const lum = (hex: string) => Math.round(lumF(hex));
+export const ink = (hex: string) => (lum(hex) < 42 ? '#fff' : '#1c1c1a');
+export const fmtOklch = (L: number, C: number, H: number) => `oklch(${(L * 100).toFixed(1)}% ${C.toFixed(3)} ${(((H % 360) + 360) % 360).toFixed(1)})`;
+export const info = (hex: string) => { const o = hexToOklch(hex); return { hex: hex.toUpperCase(), oklch: fmtOklch(o.L, o.C, o.H), L: Math.round(o.L * 100), C: o.C.toFixed(3), H: Math.round(((o.H % 360) + 360) % 360), lum: lum(hex) }; };
+
+// ---- WCAG contrast ----
+export const contrast = (h1: string, h2: string) => { const a = lumF(h1) / 100, b = lumF(h2) / 100; const hi = Math.max(a, b), lo = Math.min(a, b); return (hi + 0.05) / (lo + 0.05); };
+
+// ---- APCA (Accessible Perceptual Contrast Algorithm, SA98G / apca-w3 verbatim) ----
+// The contrast method explored for WCAG 3. Polarity-aware: distinguishes dark-on-light
+// from light-on-dark and returns a SIGNED lightness contrast Lc (≈ −108…+106).
+// NOTE: this uses its OWN screen luminance Y — a simple ^2.4 transfer with the SA98G
+// coefficients — NOT lumF (which is WCAG's piecewise linearisation with different weights).
+// Lc is a perceptual value, not a ratio; never convert it to an X:1 figure.
+const APCA = {
+  mainTRC: 2.4, sRco: 0.2126729, sGco: 0.7151522, sBco: 0.072175,
+  normBG: 0.56, normTXT: 0.57, revTXT: 0.62, revBG: 0.65,
+  blkThrs: 0.022, blkClmp: 1.414, scale: 1.14, loOffset: 0.027, loClip: 0.1, deltaYmin: 0.0005,
+};
+// sRGB hex → APCA screen luminance Y (simple ^2.4 gamma; distinct from WCAG lumF).
+export function apcaY(hex: string): number {
+  const c = hex.replace('#', '');
+  const r = parseInt(c.slice(0, 2), 16) / 255, g = parseInt(c.slice(2, 4), 16) / 255, b = parseInt(c.slice(4, 6), 16) / 255;
+  return APCA.sRco * r ** APCA.mainTRC + APCA.sGco * g ** APCA.mainTRC + APCA.sBco * b ** APCA.mainTRC;
+}
+// Signed APCA Lc for text colour on background colour.
+// Validated anchors: apcaLc('#000','#fff') ≈ 106.04, apcaLc('#fff','#000') ≈ −107.88, apcaLc('#888','#fff') ≈ 63.06.
+export function apcaLc(textHex: string, bgHex: string): number {
+  let txtY = apcaY(textHex), bgY = apcaY(bgHex);
+  if (isNaN(txtY) || isNaN(bgY) || Math.min(txtY, bgY) < 0 || Math.max(txtY, bgY) > 1.1) return 0;
+  txtY = txtY > APCA.blkThrs ? txtY : txtY + (APCA.blkThrs - txtY) ** APCA.blkClmp;
+  bgY = bgY > APCA.blkThrs ? bgY : bgY + (APCA.blkThrs - bgY) ** APCA.blkClmp;
+  if (Math.abs(bgY - txtY) < APCA.deltaYmin) return 0;
+  let SAPC = 0, out = 0;
+  if (bgY > txtY) { // BoW (dark text on light background) → positive
+    SAPC = (bgY ** APCA.normBG - txtY ** APCA.normTXT) * APCA.scale;
+    out = SAPC < APCA.loClip ? 0 : SAPC - APCA.loOffset;
+  } else { // WoB (light text on dark background) → negative
+    SAPC = (bgY ** APCA.revBG - txtY ** APCA.revTXT) * APCA.scale;
+    out = SAPC > -APCA.loClip ? 0 : SAPC + APCA.loOffset;
+  }
+  return out * 100;
+}
+
+// ---- Perceived lightness (Helmholtz–Kohlrausch via the Fairchild–Pirrotta model) ----
+// Equal OKLab L is NOT equal perceived lightness: saturated blue/red read heavier than
+// their L implies, while warm yellow-greens carry almost none of that extra weight.
+// L** = L* + (2.5 − 0.025·L*)·(0.116·|sin((h−90)/2)| + 0.085)·C*   (CIELAB L*, C*, h).
+// AESTHETIC tonal ordering only — judging which swatch reads lighter, building visually
+// even multi-hue rows. NEVER feed this into a contrast check; those stay luminance-based.
+const D65 = { Xn: 0.95047, Yn: 1.0, Zn: 1.08883 };
+// sRGB hex → CIELAB (D65). Returns L* (0–100), a*, b*, chroma C*, hue h (degrees).
+export function hexToLab(hex: string) {
+  const [r, g, b] = hexToLin(hex); // already linearised sRGB
+  const X = 0.4124564 * r + 0.3575761 * g + 0.1804375 * b;
+  const Y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+  const Z = 0.0193339 * r + 0.119192 * g + 0.9503041 * b;
+  const f = (t: number) => (t > (6 / 29) ** 3 ? Math.cbrt(t) : (1 / 3) * (29 / 6) ** 2 * t + 4 / 29);
+  const fx = f(X / D65.Xn), fy = f(Y / D65.Yn), fz = f(Z / D65.Zn);
+  const L = 116 * fy - 16, a = 500 * (fx - fy), bb = 200 * (fy - fz);
+  let h = (Math.atan2(bb, a) * 180) / Math.PI; if (h < 0) h += 360;
+  return { L, a, b: bb, C: Math.hypot(a, bb), h };
+}
+// Fairchild–Pirrotta perceived lightness in CIELAB L* units (0–100-ish; can exceed 100 for vivid hues).
+export function fairchildPirrotta(hex: string) {
+  const { L, C, h } = hexToLab(hex);
+  const f2 = 2.5 - 0.025 * L;
+  const f1 = 0.116 * Math.abs(Math.sin((((h - 90) * Math.PI) / 180) / 2)) + 0.085;
+  const deltaL = f2 * f1 * C;
+  return { Lstar: L, C, h, deltaL, Lperceived: L + deltaL };
+}
+// Convenience: just the perceived lightness value.
+export const perceivedL = (hex: string) => fairchildPirrotta(hex).Lperceived;
+
+// ---- maxChromaAt ----
+export function maxChromaAt(L: number, H: number) {
+  const rad = (H * Math.PI) / 180, co = Math.cos(rad), si = Math.sin(rad);
+  let lo = 0, hi = 0.4;
+  for (let i = 0; i < 24; i++) { const c = (lo + hi) / 2; inGamut(oklabToLin([L, c * co, c * si])) ? (lo = c) : (hi = c); }
+  return lo;
+}
+export const hueOf = (hex: string) => hexToOklch(hex).H;
+
+// ---- Display-P3 gamut (wider than sRGB; both D65, so a plain linear matrix maps sRGB→P3) ----
+// Lets ramps reach chroma sRGB can't show, emitted as a color(display-p3 …) primary with a hex fallback.
+const sRGBlinToP3lin = ([r, g, b]: number[]): number[] => [
+  0.8224621 * r + 0.177538 * g,
+  0.0331941 * r + 0.9668058 * g,
+  0.0170827 * r + 0.0723974 * g + 0.9105199 * b,
+];
+export const inGamutP3 = (linsrgb: number[]) => sRGBlinToP3lin(linsrgb).every((v) => v >= -0.001 && v <= 1.001);
+export function maxChromaP3(L: number, H: number) {
+  const rad = (H * Math.PI) / 180, co = Math.cos(rad), si = Math.sin(rad);
+  let lo = 0, hi = 0.4;
+  for (let i = 0; i < 24; i++) { const c = (lo + hi) / 2; inGamutP3(oklabToLin([L, c * co, c * si])) ? (lo = c) : (hi = c); }
+  return lo;
+}
+// OKLCH → Display-P3 string, chroma clamped to the P3 cusp. Display-P3 uses the sRGB transfer curve.
+export function oklchToP3(L: number, C: number, H: number): string {
+  const rad = (H * Math.PI) / 180, co = Math.cos(rad), si = Math.sin(rad);
+  let c = C;
+  if (!inGamutP3(oklabToLin([L, c * co, c * si]))) {
+    let lo = 0, hi = C;
+    for (let i = 0; i < 24; i++) { const m = (lo + hi) / 2; inGamutP3(oklabToLin([L, m * co, m * si])) ? (lo = m) : (hi = m); }
+    c = lo;
+  }
+  const enc = (v: number) => Math.max(0, Math.min(1, linToSrgb(v)));
+  const [r, g, b] = sRGBlinToP3lin(oklabToLin([L, c * co, c * si])).map(enc);
+  return `color(display-p3 ${r.toFixed(4)} ${g.toFixed(4)} ${b.toFixed(4)})`;
+}
+
+// ---- Okhsl chroma model (Ottosson): smooth 3-anchor (C0 / Cmid / Cmax) rational interpolation ----
+export function okhslCuspPoint(H: number) { let bL = 0.35, bc = 0; for (let L = 0.35; L <= 0.99; L += 0.006) { const c = maxChromaAt(L, H); if (c > bc) { bc = c; bL = L; } } return { L: bL, C: bc }; }
+export function getSTmid(a: number, b: number) {
+  const S = 0.11516993 + 1 / (7.4477897 + 4.1590124 * b + a * (-2.19557347 + 1.75198401 * b + a * (-2.13704948 - 10.02301043 * b + a * (-4.24894561 + 5.38770819 * b + 4.69891013 * a))));
+  const T = 0.11239642 + 1 / (1.6132032 - 0.68124379 * b + a * (0.40370612 + 0.90148123 * b + a * (-0.27087943 + 0.6122399 * b + a * (0.00299215 - 0.45399568 * b - 0.14661872 * a))));
+  return [S, T];
+}
+export function okhslChroma(L: number, H: number, s: number) {
+  const rad = (H * Math.PI) / 180, a = Math.cos(rad), b = Math.sin(rad);
+  const cusp = okhslCuspPoint(H);
+  const Smax = cusp.C / cusp.L, Tmax = cusp.C / (1 - cusp.L);
+  const Cmax = maxChromaAt(L, H);
+  const k = Cmax / Math.min(L * Smax, (1 - L) * Tmax);
+  const [Smid, Tmid] = getSTmid(a, b);
+  const Ca = L * Smid, Cb = (1 - L) * Tmid;
+  const Cmid = 0.9 * k * Math.sqrt(Math.sqrt(1 / (1 / Ca ** 4 + 1 / Cb ** 4)));
+  const Ca0 = L * 0.4, Cb0 = (1 - L) * 0.8;
+  const C0 = Math.sqrt(1 / (1 / Ca0 ** 2 + 1 / Cb0 ** 2));
+  const mid = 0.8, midInv = 1.25;
+  let C: number;
+  if (s < mid) { const t = midInv * s, k1 = mid * C0, k2 = 1 - k1 / Cmid; C = (t * k1) / (1 - k2 * t); }
+  else { const t = (s - mid) / (1 - mid), k0 = Cmid, k1 = ((1 - mid) * Cmid * Cmid * midInv * midInv) / C0, k2 = 1 - k1 / (Cmax - Cmid); C = k0 + (t * k1) / (1 - k2 * t); }
+  return Math.min(C, Cmax);
+}
+
+// ---- cuspOf ----
+export const cuspOf = (H: number) => { let bL = 0.35, bc = 0; for (let L = 0.35; L <= 0.99; L += 0.006) { const c = maxChromaAt(L, H); if (c > bc) { bc = c; bL = L; } } return { L: bL, C: bc }; };
+
+// ---- ΔEok ----
+export const labOf = (hex: string) => linToOklab(hexToLin(hex));
+export const dEok = (h1: string, h2: string) => { const A = labOf(h1), B = labOf(h2); return Math.round(Math.hypot(A[0] - B[0], A[1] - B[1], A[2] - B[2]) * 100); };
+
+// ---- CIEDE2000 + CVD gate (data-viz palette validation) ----
+// dEok above is fast but less accurate than CIEDE2000 at predicting perceptual difference (OKLab
+// STRESS ~47 vs CIEDE2000 ~29 on COMBVD). Author scales with dEok; GATE shipped data-viz palettes
+// on dE00 / dE00cvd. See COLOUR-DATAVIZ-RESEARCH.md.
+// CIELAB (D65) from linear-sRGB / hex.
+export function linToLab([r, g, b]: number[]): number[] {
+  const X = 0.4124564 * r + 0.3575761 * g + 0.1804375 * b;
+  const Y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+  const Z = 0.0193339 * r + 0.119192 * g + 0.9503041 * b;
+  const f = (t: number) => (t > (6 / 29) ** 3 ? Math.cbrt(t) : t / (3 * (6 / 29) ** 2) + 4 / 29);
+  const fx = f(X / 0.95047), fy = f(Y / 1), fz = f(Z / 1.08883);
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+export const labCie = (hex: string) => linToLab(hexToLin(hex));
+// CIEDE2000. Verified against the canonical Sharma et al. reference vectors (incl. the 1.0000 hue-wrap traps).
+export function ciede2000([L1, a1, b1]: number[], [L2, a2, b2]: number[]): number {
+  const rad = Math.PI / 180, deg = 180 / Math.PI;
+  const C1 = Math.hypot(a1, b1), C2 = Math.hypot(a2, b2), Cb = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cb ** 7 / (Cb ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * a1, a2p = (1 + G) * a2;
+  const C1p = Math.hypot(a1p, b1), C2p = Math.hypot(a2p, b2);
+  const h1p = (Math.atan2(b1, a1p) * deg + 360) % 360, h2p = (Math.atan2(b2, a2p) * deg + 360) % 360;
+  const dLp = L2 - L1, dCp = C2p - C1p;
+  let dhp = 0; if (C1p * C2p !== 0) { dhp = h2p - h1p; if (dhp > 180) dhp -= 360; else if (dhp < -180) dhp += 360; }
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * rad);
+  const Lbp = (L1 + L2) / 2, Cbp = (C1p + C2p) / 2;
+  let hbp: number; if (C1p * C2p === 0) hbp = h1p + h2p; else { hbp = (h1p + h2p) / 2; if (Math.abs(h1p - h2p) > 180) hbp += h1p + h2p < 360 ? 180 : -180; }
+  const T = 1 - 0.17 * Math.cos((hbp - 30) * rad) + 0.24 * Math.cos(2 * hbp * rad) + 0.32 * Math.cos((3 * hbp + 6) * rad) - 0.2 * Math.cos((4 * hbp - 63) * rad);
+  const dTheta = 30 * Math.exp(-(((hbp - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cbp ** 7 / (Cbp ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lbp - 50) ** 2) / Math.sqrt(20 + (Lbp - 50) ** 2);
+  const Sc = 1 + 0.045 * Cbp, Sh = 1 + 0.015 * Cbp * T, Rt = -Math.sin(2 * dTheta * rad) * Rc;
+  return Math.sqrt((dLp / Sl) ** 2 + (dCp / Sc) ** 2 + (dHp / Sh) ** 2 + Rt * (dCp / Sc) * (dHp / Sh));
+}
+export const dE00 = (h1: string, h2: string) => Math.round(ciede2000(labCie(h1), labCie(h2)));
+// CVD simulation — Machado, Oliveira & Fernandes (2009), severity 1.0, applied in linear sRGB.
+export const CVD_TYPES = ['protan', 'deutan', 'tritan'] as const;
+export type CvdType = (typeof CVD_TYPES)[number];
+const CVD_M: Record<CvdType, number[][]> = {
+  protan: [[0.152286, 1.052583, -0.204868], [0.114503, 0.786281, 0.099216], [-0.003882, -0.048116, 1.051998]],
+  deutan: [[0.367322, 0.860646, -0.227968], [0.280085, 0.672501, 0.047413], [-0.01182, 0.04294, 0.968881]],
+  tritan: [[1.255528, -0.076749, -0.178779], [-0.078411, 0.930809, 0.147602], [0.004733, 0.691367, 0.3039]],
+};
+export const simulateCvdLin = (lin: number[], t: CvdType) => CVD_M[t].map((row) => row[0] * lin[0] + row[1] * lin[1] + row[2] * lin[2]);
+export const simulateCvd = (hex: string, t: CvdType) => { const l = simulateCvdLin(hexToLin(hex), t); const to = (v: number) => Math.round(Math.max(0, Math.min(1, linToSrgb(v))) * 255).toString(16).padStart(2, '0'); return '#' + to(l[0]) + to(l[1]) + to(l[2]); };
+// Worst-case ΔE00 across normal + all three dichromacies — the number to gate categorical series on.
+export const dE00cvd = (h1: string, h2: string) => {
+  const norm = ciede2000(labCie(h1), labCie(h2));
+  const worst = CVD_TYPES.reduce((m, t) => Math.min(m, ciede2000(linToLab(simulateCvdLin(hexToLin(h1), t)), linToLab(simulateCvdLin(hexToLin(h2), t)))), norm);
+  return Math.round(worst);
+};
+// Validate a categorical data-viz set: mutual separation (worst-case CVD), distance from brand/
+// semantic anchors, and WCAG 1.4.11 non-text contrast (≥3:1) against each background.
+export interface DataVizGate { minSep: number; minBrand: number; minContrast: number; bgs: string[]; brand: string[]; }
+export function validateDataViz(hexes: string[], g: DataVizGate) {
+  const pairs: { a: string; b: string; dE: number }[] = [];
+  for (let i = 0; i < hexes.length; i++) for (let j = i + 1; j < hexes.length; j++) pairs.push({ a: hexes[i], b: hexes[j], dE: dE00cvd(hexes[i], hexes[j]) });
+  const minMutual = Math.min(...pairs.map((p) => p.dE));
+  const brand = hexes.map((h) => ({ h, dE: Math.min(...g.brand.map((b) => dE00(h, b))) }));
+  const minBrand = Math.min(...brand.map((b) => b.dE));
+  const contrastRows = hexes.map((h) => ({ h, byBg: g.bgs.map((bg) => +contrast(h, bg).toFixed(2)) }));
+  const minContrast = Math.min(...contrastRows.flatMap((r) => r.byBg));
+  return { pass: minMutual >= g.minSep && minBrand >= g.minBrand && minContrast >= g.minContrast, minMutual, minBrand, minContrast, pairs, brand, contrastRows };
+}
+// The safe categorical set — brand-led, 6 series, dual-mode. Regenerated 2026-07-19 by
+// scripts/brandled.ts and promoted here from the docs page; it replaces the old 5-colour set, which
+// was optimised against pure white and had no real dark variant. Search gate + rationale live in the
+// script header. Series 1–3 lead the brand hierarchy (forest → warm → river); 4–6 are engineered for
+// separation. Keys are the series index, not a hue name — two slots share the warm hue arc (differing
+// in tone), so a hue name would mislead, and the set is consumed by position anyway.
+// Validated: worst-case-CVD ΔE00 12.3 light / 16.3 dark; every colour clears WCAG 1.4.11 ≥ 3:1 against
+// all three real surfaces per mode; dark hue-locked to light so a series keeps its identity across a
+// theme toggle. Four constraints beyond separation, each added because an unconstrained run produced
+// something the metric was happy with and the eye was not:
+//   · chroma 0.13–0.20 — a categorical set carries NO ordering, so uneven chroma invents a hierarchy.
+//     Uncapped, series 2 ran nearly twice the chroma of series 1 and shouted.
+//   · no two hues within 42° — ΔE will happily place two blues 6° apart and separate them by lightness.
+//   · brand ΔE ≤ 9 per brand slot — at 15 the warm slot drifted to ochre (ΔE 12) for separation we did
+//     not need.
+//   · brand anchors and the tonal band are PER MODE — 500/L0.50-0.72 light, 400/L0.52-0.82 dark. Dark
+//     was previously anchored to the 500 step, i.e. a light-mode reference on a dark surface, which
+//     pulled the whole dark set too dark: measured against the 400 step it was Δ15 forest / Δ18 warm.
+//     Light's floor is 0.50 (not 0.44) as a design call: at 0.44 slots 4-6 clustered 16 points below
+//     the brand slots and read as a separate family. Lifting them to L50 is free on separation (ΔE 12
+//     either way) but slot 2 pays for the crowding — chroma 0.155 → 0.130, brand drift 5 → 8. That
+//     trade was made deliberately; it is not the search finding a better optimum.
+// Redundant encoding (shape / dash / direct label) remains MANDATORY.
+export const DATAVIZ = {
+  light: { 1: '#009d7c', 2: '#cc7044', 3: '#617de6', 4: '#b0175f', 5: '#8a34ab', 6: '#5b6c00' },
+  dark: { 1: '#029e72', 2: '#d46b01', 3: '#89b0ff', 4: '#ff9cb2', 5: '#a663ac', 6: '#becf68' },
+} as const;
+// Brand pairs — the brand-forward categorical set: three brand hues × two ramp tones = 6 series, keyed
+// family-tone. Maximum brand fidelity, but NOT colour-blind-safe — the soft tones converge under
+// deutan and sit low on contrast, so this set REQUIRES direct labels / a legend (like the vivid sets).
+// Mode flips the ramp window: light takes the deep+mid steps (500/300), dark slides UP (400/200) so a
+// mark stays lighter than the dark surface. Keys name the mode-stable TONE (deep/soft), never the ramp
+// step — the step differs by mode, so a step number would be a lie in the other mode.
+export const DATAVIZ_PAIRS = {
+  light: { 'forest-deep': '#019f6d', 'forest-soft': '#3bd996', 'warm-deep': '#db6300', 'warm-soft': '#feaf59', 'river-deep': '#3588df', 'river-soft': '#81c0ff' },
+  dark: { 'forest-deep': '#0abb7f', 'forest-soft': '#99e9bc', 'warm-deep': '#f48519', 'warm-soft': '#ffd6a6', 'river-deep': '#43a2ff', 'river-soft': '#b2d9ff' },
+} as const;
+// Sequential ramps — ordered low→high. Three flavours:
+//  • Brand single-hue (forest, indigo): light→dark (light = low), on-vibe / quiet. Invert in dark
+//    mode. forest is the brand ramp; see the note below.
+//  • Cartographic multi-hue (moss, magma): ColorBrewer YlGn and matplotlib magma, verbatim. They vary
+//    hue as well as lightness, which separates adjacent steps better than a single hue can.
+//  • Scientific (cividis, viridis): the canonical, peer-reviewed perceptually-uniform colormaps,
+//    verbatim (public domain). Native direction is dark→light (dark = low) — keep it; both work on
+//    light and dark backgrounds. cividis is CVD-optimal (blue→yellow, the channel CVD preserves);
+//    viridis is the perceptually-uniform default. Prefer these for accuracy-first heatmaps.
+//
+// On "brand": `forest` is the brand ramp and the cell components' default. It is built by the recipe
+// indigo uses — a shared lightness ladder, one hue, triangular chroma — at hue 164.8, with the
+// chroma scaled so stop 7 IS forest-700. The brand colour is a stop on the ramp rather than
+// something it approximates. Measured: L-monotonic, ΔE00 steps 5.8–8.7, hue 0.0–0.1° from brand.
+//
+// A `teal` ramp used to sit here and was retired when forest landed. It was built the same way but
+// at hue 188 — a constant 22.8° from forest-700, nearer cyan than Forest green — so it carried the
+// "brand" label without the brand hue. Beside forest it was close enough to be confusable and no
+// longer earned a slot. moss is the other green: not brand-derived (ColorBrewer YlGn) and the least
+// even steps of the set, kept because a multi-hue ramp separates adjacent steps better than a
+// single hue can.
+export const DATAVIZ_SEQUENTIAL = {
+  forest: ['#dcffee', '#bef9de', '#99e8c5', '#69d2a8', '#30b889', '#289c74', '#208361', '#186c4f', '#11563e'],
+  indigo: ['#f3f4fe', '#e6e8fd', '#ced0fc', '#b1b3f8', '#9494e8', '#7b78da', '#6763bb', '#54519b', '#43407b'],
+  // moss — ColorBrewer YlGn (light→dark, light = low). The public match to Spectrum's "Forest" green
+  // sequential, renamed so it doesn't collide with the brand forest family. Inverts in dark mode.
+  moss: ['#ffffe5', '#f7fcb9', '#d9f0a3', '#addd8e', '#78c679', '#41ab5d', '#238443', '#006837', '#004529'],
+  cividis: ['#00204d', '#00336f', '#39486b', '#575d6d', '#707173', '#8a8779', '#a69d75', '#c4b56c', '#e4cf5b', '#ffea46'],
+  viridis: ['#440154', '#482878', '#3e4a89', '#31688e', '#26828e', '#1f9e89', '#35b779', '#6dcd59', '#b4de2c', '#fde725'],
+  // magma — matplotlib's perceptually-uniform colormap (public domain / CC0). Spectrum's "Magma" is this
+  // map. Native direction dark→low like viridis/cividis; keep it. The warm counterpart to viridis.
+  magma: ['#000004', '#1c1044', '#4f127b', '#812581', '#b5367a', '#e65164', '#fb8861', '#fec287', '#fcfdbf'],
+} as const;
+// Diverging ramps (9 stops: low → neutral light centre → high). Centre = a meaningful value (0/mean/
+// median); lightness peaks there. Three distinct axes (NEVER green↔red — the deuteranopia trap, ΔE 8):
+//  • forestWarm  — brand primary↔secondary (forest green ↔ Acer orange). On-brand; endpoints ΔE00 12
+//    worst-case CVD (forest's teal lean keeps it viable) — least CVD-robust of the three, pair w/ labels.
+//  • blueOrange  — river↔warm. The CVD-safe workhorse (endpoints ΔE00 41). Use when CVD is critical.
+//  • purpleGreen — violet↔forest, the classic ColorBrewer-style diverging (ΔE00 27). Distinct flavour.
+// For dark mode, darken the centre stop (a light centre is invisible on the dark-green surface).
+export const DATAVIZ_DIVERGING = {
+  forestWarm: ['#155e42', '#238862', '#38b484', '#69deac', '#f6ece8', '#fab18b', '#dc804f', '#b05925', '#7d3a11'],
+  blueOrange: ['#12518d', '#3377be', '#5b9fe9', '#9dc8f9', '#f6ece8', '#fab18b', '#dc804f', '#b05925', '#7d3a11'],
+  purpleGreen: ['#673682', '#8e5bab', '#b682d5', '#ddaff9', '#e8f1ec', '#69deac', '#38b484', '#238862', '#155e42'],
+  // redBlue — ColorBrewer RdBu (9-class), the canonical CVD-safe diverging Spectrum calls "Red-blue".
+  // Red↔blue avoids the green↔red deuteranopia trap; both ends stay distinct for every CVD type.
+  redBlue: ['#b2182b', '#d6604d', '#f4a582', '#fddbc7', '#f7f7f7', '#d1e5f0', '#92c5de', '#4393c3', '#2166ac'],
+} as const;
+// Vivid categorical sets. 12 hues spaced for maximum colour separation, not for even hue steps; the
+// first SIX are the curated 6. Dual-mode, and every mark clears WCAG 1.4.11 on both surfaces (min
+// 3.09 light / 3.84 dark). Normal-vision distinct (6: ΔE00 ≥23, 12: ≥10) but these are still
+// NOT colour-blind-safe — red/amber/green converge under deuteranopia, and a 12-set is impossible to
+// keep CVD-distinct (true of every system incl. Spectrum). RULE: use ≤6 when you can; 7–12 require
+// direct labels / legend; for colour-blind-critical charts use DATAVIZ (the 6-colour CVD-safe set).
+// Redundant encoding (shape/dash/label) is mandatory regardless. See research §4.
+// Values are Tailwind v4's oklch palette: step 600 in light mode, step 400 in dark. Bespoke hexes
+// used to sit here; they lost WCAG 1.4.11 on both surfaces (3 of the 6 under 3:1) to buy normal-vision
+// separation, which measured as the wrong trade — the Tailwind pick clears 3:1 everywhere (min 3.09
+// light / 3.84 dark), separates BETTER in light (ΔE00 23.6 vs 22.3), and triples worst-case CVD
+// separation (8.7 vs 2.9). Only dark-mode normal-vision headroom drops (27.1 → 20.0), far above
+// threshold. Hues are the max-min-ΔE00 pick over the 15 Tailwind hues that clear the contrast gate;
+// yellow and lime are excluded — they cannot reach 3:1 on the light surface at any usable step.
+// Sequence note: green leads and red sits sixth, so the common 1–3 series case opens on the brand's
+// own hue rather than on an alarm colour — red carries meaning nobody asked for when it arrives first.
+// Slot n and slot n+6 are the same hue family (green/emerald, amber/orange, sky/blue, indigo/purple,
+// pink/fuchsia, red/rose), so a chart that grows past six extends each existing hue instead of
+// introducing six unrelated ones. That alignment is the reason the 12-set separates at ΔE00 9 rather
+// than the 10.8 a free pick reaches — deliberate: the near-neighbours are what make the tail legible
+// as "more of the same series".
+// Green leads rather than emerald even though emerald is the exact brand hue (163°, ΔE00 6.4 to Brand
+// Forest, vs green's 14.2): emerald's lower chroma and its position between green and teal crowd
+// cyan/sky, and emerald↔pink collapse to ΔE00 1.5 under deuteranopia. Leading emerald costs the six
+// half its separation (23.6 → 12.2). The brand hue is still in the set, at slot 7.
+export const DATAVIZ_CATEGORICAL = {
+  names: ['green', 'amber', 'sky', 'indigo', 'pink', 'red', 'emerald', 'orange', 'blue', 'purple', 'fuchsia', 'rose'],
+  light: ['#00a447', '#da7600', '#0084c8', '#4f39f6', '#e30076', '#e40015', '#009669', '#ec5600', '#155dfc', '#9810fa', '#c500da', '#e60044'],
+  dark: ['#05df72', '#fabc00', '#00bbfd', '#7d87ff', '#fb64b6', '#ff6568', '#00d294', '#ff8b1e', '#56a2ff', '#bf7eff', '#ec6dff', '#ff6880'],
+} as const;
+// Convenience: the curated 6 is the first six of the 12.
+export const datavizCategorical = (n: 6 | 12, mode: 'light' | 'dark') => DATAVIZ_CATEGORICAL[mode].slice(0, n);
+
+// ---- Ladder constants ----
+export const BRAND_SHADES = [0, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export const SHADES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+export const TWL: Record<number, number> = { 0: 0.99, 50: 0.97, 100: 0.935, 150: 0.91, 200: 0.87, 300: 0.79, 400: 0.7, 500: 0.62, 600: 0.545, 700: 0.475, 800: 0.405, 900: 0.34, 950: 0.27 };
+// Bright ladder (amber/acid): keep tints light (vivid yellows can't be dark), but converge the mid/dark
+// levels toward the cool ladder so the darks get dark enough to close the warm-hue contrast holes.
+export const TWL_BRIGHT: Record<number, number> = { 0: 0.99, 50: 0.975, 100: 0.95, 150: 0.92, 200: 0.9, 300: 0.83, 400: 0.75, 500: 0.66, 600: 0.57, 700: 0.49, 800: 0.41, 900: 0.34, 950: 0.27 };
+export const BRIGHT = new Set(['amber']); // acid dropped to the normal ladder (Acid Green is L77 = a 300-level lightness)
+// Warm family ladder: re-spaces the 300/400 slots so the wide Peach→Acer pin gap eases instead of kinking.
+export const TWL_WARM: Record<number, number> = { 0: 0.99, 50: 0.97, 100: 0.935, 150: 0.91, 200: 0.87, 300: 0.815, 400: 0.725, 500: 0.62, 600: 0.545, 700: 0.475, 800: 0.405, 900: 0.34, 950: 0.27 };
+export const ladderFor = (fam: string) => (fam === 'warm' ? TWL_WARM : BRIGHT.has(fam) ? TWL_BRIGHT : TWL);
+export const TWFRAC: Record<number, number> = { 0: 0.16, 50: 0.34, 100: 0.62, 200: 0.72, 300: 0.84, 400: 0.9, 500: 0.9, 600: 0.88, 700: 0.84, 800: 0.72, 900: 0.58, 950: 0.44 };
+export const MUTE = 0.8;
+export const nearestOn = (hex: string, ladder: Record<number, number>) => { const L = hexToOklch(hex).L; let b = BRAND_SHADES[0], bd = Infinity; for (const s of BRAND_SHADES) { const d = Math.abs(ladder[s] - L); if (d < bd) { bd = d; b = s; } } return b; };
+export const CMUL: Record<string, Record<number, number>> = {
+  acid: { 0: 0.4, 50: 0.45, 100: 0.5, 200: 0.65, 300: 0.82 },
+  primary: { 400: 1.15, 600: 1.3, 700: 1.4, 800: 1.4, 900: 1.3 },
+};
+export const HWARM: Record<string, number> = { amber: -22, acid: -6 };
+export const SAT: Record<string, number> = { primary: 0.95, maple: 0.9, warm: 0.9, amber: 0.84, acid: 0.82, river: 0.92 };
+
+// ---- Hue torsion: two-sided lean the H(L) spline curves through (pivots at the pin/base hue) ----
+// l = degrees the lighter-than-anchor end leans; d = degrees the darker-than-anchor end leans.
+export const HTORS: Record<string, { l: number; d: number }> = {
+  primary: { l: -4, d: 6 }, // subtle: light tints lean yellow-green (fresh), dark shades lean teal (deep); pivots at Brand Forest
+  amber: { l: 10, d: -22 }, acid: { l: 6, d: -6 }, maple: { l: -6, d: 2 }, river: { l: -4, d: 8 },
+};
+export const TORS_MULT = 1.5; // global hue-torsion strength dial
+export const torsionFor = (fam: string) => { const t = HTORS[fam] ?? { l: 0, d: (HWARM[fam] ?? 0) }; return { l: t.l * TORS_MULT, d: t.d * TORS_MULT }; };
+
+// Per-family per-level fine-tuning for GENERATED families: override lightness (0–1) and/or chroma
+// (OKLab C, clamped to the cusp) at a specific level, without disturbing the shared lightness ladder.
+export const TUNE: Record<string, Record<number, { L?: number; C?: number; H?: number }>> = {};
+
+// ---- buildTW: a simple generate-then-stamp ramp (retained as a comparison/utility) ----
+export function buildTW(H: number, pins: Record<number, string> = {}, ladder: Record<number, number> = TWL, cmul?: Record<number, number>, dHue = 0, sat = 0.9) {
+  const o: Record<number, string> = {};
+  const L5 = ladder[500], Lbot = ladder[950];
+  for (const s of BRAND_SHADES) {
+    const L = ladder[s];
+    const hh = dHue && L < L5 ? H + dHue * ((L5 - L) / (L5 - Lbot || 1)) : H;
+    o[s] = oklchToHex(L, okhslChroma(L, hh, sat) * (cmul?.[s] ?? 1), hh);
+  }
+  for (const [s, hex] of Object.entries(pins)) o[+s] = hex.toLowerCase();
+  return o;
+}
+
+// ---- PCHIP machinery (monotone-cubic C(L) / H(L) splines through anchors) ----
+export function pchipSlopes(xs: number[], ys: number[]) {
+  const n = xs.length, h: number[] = [], d: number[] = [], m: number[] = new Array(n);
+  for (let i = 0; i < n - 1; i++) { h[i] = xs[i + 1] - xs[i]; d[i] = (ys[i + 1] - ys[i]) / h[i]; }
+  m[0] = d[0]; m[n - 1] = d[n - 2];
+  for (let i = 1; i < n - 1; i++) {
+    if (d[i - 1] * d[i] <= 0) m[i] = 0;
+    else { const w1 = 2 * h[i] + h[i - 1], w2 = h[i] + 2 * h[i - 1]; m[i] = (w1 + w2) / (w1 / d[i - 1] + w2 / d[i]); }
+  }
+  return m;
+}
+export function makeSpline(pts: { x: number; y: number }[]) {
+  const s = [...pts].sort((a, b) => a.x - b.x);
+  const xs = s.map((p) => p.x), ys = s.map((p) => p.y), m = pchipSlopes(xs, ys), n = xs.length;
+  return (x: number) => {
+    if (x <= xs[0]) return ys[0];
+    if (x >= xs[n - 1]) return ys[n - 1];
+    let i = 0; while (x > xs[i + 1]) i++;
+    const hh = xs[i + 1] - xs[i], t = (x - xs[i]) / hh, t2 = t * t, t3 = t2 * t;
+    return (2 * t3 - 3 * t2 + 1) * ys[i] + (t3 - 2 * t2 + t) * hh * m[i] + (-2 * t3 + 3 * t2) * ys[i + 1] + (t3 - t2) * hh * m[i + 1];
+  };
+}
+export const normH = (h: number) => ((h % 360) + 360) % 360;
+
+// ---- Pin config ----
+// optional 3rd element = explicit level (override the auto by-lightness placement)
+// Brand naming: maple = red (Error), river = blue (Info); primary keeps its key (brand name "forest", Nuxt UI's primary alias).
+export const PINS: Record<string, [string, string, number?][]> = {
+  // Brand Forest anchors the mid; Dark Forest + Darkest Forest (the brand's deep greens, also the logo's
+  // mark + ink) anchor the dark end — Forest, the primary, owns the system's dark envelope (see FRAC_DARK).
+  primary: [['Brand Forest', '#00845C', 600], ['Dark Forest', '#046C4C', 700], ['Darkest Forest', '#002A24', 950]],
+  maple: [],
+  // warm absorbs the old orange + cream: cream tints, an Acer-orange mid, a bark-brown floor — one ramp.
+  warm: [['Ice Cream', '#FFF9F2', 50], ['Peach Cream', '#FFD6A6', 200], ['Acer Orange', '#DB6300', 500], ['Bark Brown', '#44231C', 950]],
+  amber: [],
+  acid: [['Acid Green', '#B4BD11', 300]], // pinned at 300 on the normal ladder (was 400/bright)
+  river: [],
+};
+export const HUE: Record<string, string> = { primary: '#00845C', maple: '#E5484D', warm: '#DB6300', amber: '#FFC53D', acid: '#B4BD11', river: '#0090FF' };
+export const pinsFor = (fam: string) => Object.fromEntries((PINS[fam] || []).map(([, hex, lvl]) => [lvl ?? nearestOn(hex, ladderFor(fam)), hex]));
+export const scaleMarks: Record<string, string> = {};
+for (const [fam, list] of Object.entries(PINS)) for (const [name, hex, lvl] of list) scaleMarks[`${fam}-${lvl ?? nearestOn(hex, ladderFor(fam))}`] = name;
+
+// ---- Brand naming + the Nuxt UI alias contract ----
+// We own the primitive scales + this alias mapping; Nuxt UI owns the semantic aliases and all component
+// theming. BRAND_NAMES maps each engine family key to its brand colour name (primary's is "forest";
+// maple/river already carry theirs). NUXT_UI_ALIASES maps each Nuxt UI semantic colour to the brand
+// colour it resolves to — the contract realised in app.config `ui.colors` (web), Flutter theme, and Figma.
+export const BRAND_NAMES: Record<string, string> = { primary: 'forest', maple: 'maple', warm: 'warm', amber: 'amber', acid: 'acid', river: 'river', neutral: 'neutral' };
+export const NUXT_UI_ALIASES: Record<string, string> = { primary: 'forest', success: 'forest', error: 'maple', info: 'river', warning: 'amber', secondary: 'warm', neutral: 'neutral' };
+
+// ---- Brand chroma profile: chroma is DERIVED from the pins, not dialed per family ----
+// Two curves, both read straight off the brand pins (PINS):
+//   1. cusp-fraction F(L) — how hard the brand pushes toward the gamut wall at each lightness.
+//      Measured: Brand Forest / Accent / Acer / Acid / Peach all ride ~98–100% of their own cusp;
+//      Bark Brown rides ~45% (the deliberately muted deep end). So F ≈ 1.0 through the mids,
+//      easing to ~0.45 in the darks and tapering at the extreme tints.
+//   2. comfort ceiling K(L) — the brand's absolute chroma envelope (upper hull of pin chroma),
+//      peaking ~0.17 (Acer/Acid). Caps wide-gamut hues (green/lime/blue) so their light tints stay
+//      rich instead of neon — riding 100% of green's fat cusp would otherwise blow past the brand's feel.
+// chroma(L,H) = min( F(L)·cusp(L,H), K(L) ). Generated families (amber, maple, river) inherit the SAME
+// law the pins obey, so they read as siblings of Forest / Acer / Peach rather than independent picks.
+export const FRAC_TINT = 0.5; // cusp-fraction at the extreme light end (lighter than the lightest pin)
+export const FRAC_DARK = 0.4; // extreme-dark anchor (L0.20, below the floor). The DARK RICHNESS is now set
+// by Forest's own dark pins (Dark Forest @700, Darkest Forest @950, both riding ~0.95 of their cusp): they define
+// the shared dark cusp-fraction, so every family's darks stay rich. This anchor only extrapolates below 950.
+export const CHROMA_HEADROOM = 1.0; // multiplier on the comfort ceiling (1 = exact pin envelope)
+function buildBrandChromaProfile() {
+  const allPins = Object.values(PINS).flat() as [string, string, number?][];
+  // 1. cusp-fraction curve: pin chroma as a fraction of its own cusp (drop near-white pins — cusp too small).
+  // Also drop deliberately-muted dark accents (Bark Brown: f≈0.45 at L0.30): authored low on purpose, it
+  // would clash with Forest's rich dark pins (Darkest Forest rides ~0.94) and suppress the system's dark richness.
+  // Bark Brown still pins warm-950 exactly; it just doesn't define the shared envelope — Forest's darks do.
+  const fr: { L: number; f: number }[] = [];
+  for (const [, hex] of allPins) { const o = hexToOklch(hex); const cu = maxChromaAt(o.L, o.H); const f = o.C / cu; if (cu > 0.03 && o.L < 0.95 && !(o.L < 0.35 && f < 0.55)) fr.push({ L: o.L, f }); }
+  fr.sort((a, b) => a.L - b.L);
+  const frM: { L: number; f: number }[] = [];
+  for (const p of fr) { const last = frM[frM.length - 1]; if (last && Math.abs(last.L - p.L) < 0.02) { last.f = (last.f + p.f) / 2; last.L = (last.L + p.L) / 2; } else frM.push({ ...p }); }
+  const fracSpline = makeSpline([{ x: 0.2, y: FRAC_DARK }, ...frM.map((p) => ({ x: p.L, y: p.f })), { x: 0.985, y: FRAC_TINT }]);
+  // 2. comfort ceiling: upper hull of absolute pin chroma over lightness
+  const ca = allPins.map(([, hex]) => hexToOklch(hex)).filter((o) => o.C > 0.02).map((o) => ({ L: o.L, C: o.C })).sort((a, b) => a.L - b.L);
+  const caM: { L: number; C: number }[] = [];
+  for (const p of ca) { const last = caM[caM.length - 1]; if (last && Math.abs(last.L - p.L) < 0.03) last.C = Math.max(last.C, p.C); else caM.push({ ...p }); }
+  const capSpline = makeSpline([{ x: 0.18, y: 0.03 }, ...caM.map((p) => ({ x: p.L, y: p.C })), { x: 0.985, y: 0.015 }]);
+  return { fracSpline, capSpline };
+}
+const BRAND_CHROMA = buildBrandChromaProfile();
+// Derived chroma at a lightness+hue: ride the gamut wall at the brand's fraction, capped at brand comfort.
+export function brandChroma(L: number, H: number, gamut: 'srgb' | 'p3' = 'srgb', headroom = CHROMA_HEADROOM) {
+  const cusp = (gamut === 'p3' ? maxChromaP3 : maxChromaAt)(L, H);
+  return Math.min(BRAND_CHROMA.fracSpline(L) * cusp, BRAND_CHROMA.capSpline(L) * headroom);
+}
+export const cuspFractionAt = (L: number) => BRAND_CHROMA.fracSpline(L); // F(L), for visualisation
+export const chromaComfortAt = (L: number) => BRAND_CHROMA.capSpline(L); // K(L), for visualisation
+
+// ---- buildPCHIP: the canonical ramp builder (pins as exact control points) ----
+// ov = runtime lever overrides (for the tuner tool); omitted → uses the module-level config.
+// torsL/torsD are the FINAL lean degrees (already scaled), matching torsionFor()'s output.
+export type PchipOverrides = { sat?: number; chromaMul?: number; headroom?: number; torsL?: number; torsD?: number; tune?: Record<number, { L?: number; C?: number; H?: number }>; pins?: [string, string, number?][]; hue?: string; ladder?: Record<number, number>; steer?: boolean };
+
+// ---- House-curve steering: the pinned brand anchors (Primary + Warm) define a reference
+// chroma per level; the flexible semantics (maple / river / amber) ride it — clamped to each gamut —
+// so they read as siblings of the brand, distinct only by hue. Success = primary, so the brand green
+// anchors the set; warm is the brand secondary. Acid was dropped from the anchors: it's a rare tertiary
+// (the Lime mock), so it shouldn't shape the semantics. ----
+const HOUSE_ANCHORS = ['primary', 'warm'];
+const STEERED = new Set(['maple', 'river', 'amber']);
+const P3_TO_SRGBLIN = [[1.2249401, -0.2249404, 0], [-0.0420569, 1.0420571, 0], [-0.0196376, -0.0786361, 1.0982735]];
+// decode a built swatch string (hex or color(display-p3 …)) back to OKLCH.
+export function decodeOklch(s: string) {
+  if (s[0] === '#') return hexToOklch(s);
+  const m = s.match(/display-p3\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)/);
+  if (!m) return { L: 0, C: 0, H: 0 };
+  const lin = [srgbToLin(+m[1]), srgbToLin(+m[2]), srgbToLin(+m[3])];
+  const r = P3_TO_SRGBLIN[0][0] * lin[0] + P3_TO_SRGBLIN[0][1] * lin[1] + P3_TO_SRGBLIN[0][2] * lin[2];
+  const g = P3_TO_SRGBLIN[1][0] * lin[0] + P3_TO_SRGBLIN[1][1] * lin[1] + P3_TO_SRGBLIN[1][2] * lin[2];
+  const b = P3_TO_SRGBLIN[2][0] * lin[0] + P3_TO_SRGBLIN[2][1] * lin[1] + P3_TO_SRGBLIN[2][2] * lin[2];
+  const [L, A, B] = linToOklab([r, g, b]);
+  return { L, C: Math.hypot(A, B), H: ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360 };
+}
+const _houseCache: Record<string, Record<number, number>> = {};
+// average chroma per level across the pinned brand anchors (Primary + Warm) — built canonically (NOT steered → no recursion), cached per gamut.
+export function houseChroma(gamut: 'srgb' | 'p3' = 'srgb'): Record<number, number> {
+  if (_houseCache[gamut]) return _houseCache[gamut];
+  const ramps = HOUSE_ANCHORS.map((f) => buildPCHIP(f, gamut));
+  const h: Record<number, number> = {};
+  for (const s of BRAND_SHADES) { const cs = ramps.map((r) => decodeOklch(r[s]).C); h[s] = cs.reduce((a, b) => a + b, 0) / cs.length; }
+  _houseCache[gamut] = h;
+  return h;
+}
+
+export function buildPCHIP(fam: string, gamut: 'srgb' | 'p3' = 'srgb', ov?: PchipOverrides) {
+  const maxC = gamut === 'p3' ? maxChromaP3 : maxChromaAt;
+  const toStr = gamut === 'p3' ? oklchToP3 : oklchToHex;
+  const base = hexToOklch(ov?.hue ?? HUE[fam]);
+  const H0 = normH(base.H);
+  const ladder = ov?.ladder ?? ladderFor(fam);
+  const sat = ov?.sat ?? SAT[fam] ?? 0.9;
+  const tDef = torsionFor(fam);
+  const tors = { l: ov?.torsL ?? tDef.l, d: ov?.torsD ?? tDef.d };
+  const list = ov?.pins ?? PINS[fam] ?? [];
+  // pin anchors = exact brand colours (own L,C,H)
+  const anchors = list.map(([, hex]) => { const o = hexToOklch(hex); return { L: o.L, C: o.C, H: normH(o.H), hex: hex.toLowerCase() }; });
+  // seed base hue colour if no pin sits near its lightness — this is the torsion pivot
+  if (!anchors.some((a) => Math.abs(a.L - base.L) < 0.04)) anchors.push({ L: base.L, C: base.C, H: H0, hex: '' });
+  // synthetic light/dark ends so the spline spans the whole ladder.
+  // Two-sided hue torsion: lighter end leans by tors.l, darker end by tors.d, pivoting at the base/pin hue.
+  if (!anchors.some((a) => a.L > 0.93)) anchors.push({ L: 0.985, C: 0.012, H: H0 + tors.l, hex: '' });
+  if (!anchors.some((a) => a.L < 0.34)) { const Ld = 0.24, hd = H0 + tors.d; anchors.push({ L: Ld, C: Math.min(okhslChroma(Ld, hd, sat), maxC(Ld, hd)), H: hd, hex: '' }); }
+  anchors.sort((a, b) => a.L - b.L);
+  // unwrap hue to dodge 0/360 wrap in the spline
+  for (let i = 1; i < anchors.length; i++) { while (anchors[i].H - anchors[i - 1].H > 180) anchors[i].H -= 360; while (anchors[i].H - anchors[i - 1].H < -180) anchors[i].H += 360; }
+  const hS = makeSpline(anchors.map((a) => ({ x: a.L, y: a.H })));
+  // pin owns its level's L: override the ladder slot lightness with the pin's true L
+  const Lad: Record<number, number> = { ...ladder };
+  const pinHex: Record<number, string> = {};
+  for (const [, hex, lvl] of list) { const o = hexToOklch(hex); const level = lvl ?? nearestOn(hex, ladder); Lad[level] = o.L; pinHex[level] = hex.toLowerCase(); }
+  const o: Record<number, string> = {};
+  const tune = ov?.tune ?? TUNE[fam] ?? {};
+  const cMul = ov?.chromaMul ?? 1; // global chroma dial — scales the derived curve (then gamut-clamped)
+  const headroom = ov?.headroom ?? CHROMA_HEADROOM; // loosen/tighten the brand comfort ceiling
+  // The semantics (maple/river/amber) ride the house curve by default; pass steer:false to opt out
+  const steered = STEERED.has(fam) && ov?.steer !== false && !ov?.pins;
+  const house = steered ? houseChroma(gamut) : null;
+  for (const s of BRAND_SHADES) {
+    const tu = tune[s];
+    const L = s === 0 ? 0.985 : (tu?.L ?? Lad[s]);
+    const hh = tu?.H != null ? tu.H : hS(L);
+    // chroma: steered families take the house curve; brand families ride the cusp-fraction + comfort ceiling. Clamp to gamut.
+    const target = house ? house[s] : brandChroma(L, hh, gamut, headroom);
+    let C = Math.min(target * cMul, maxC(L, hh));
+    if (tu?.C != null) C = Math.min(tu.C, maxC(L, hh));
+    o[s] = toStr(L, C, hh);
+  }
+  // guarantee exact pin (sRGB brand hex; in p3 mode emit its display-p3 form — same in-gamut colour)
+  for (const [lvl, hex] of Object.entries(pinHex)) { const po = hexToOklch(hex); o[+lvl] = gamut === 'p3' ? oklchToP3(po.L, po.C, po.H) : hex; }
+  return o;
+}
+
+// ---- pinsFor / scaleMarks are exported above ----
+// scaleMarks is populated at module load time (top-level loop)