remarque-tokens 0.8.0 → 0.10.0

package/AGENT_RULES.md

@@ -41,6 +41,7 @@ These are not guidelines. Agents must follow them literally.
 - NEVER change a value in `tokens-core.css` (or its tokens' values anywhere) — core tokens are Remarque's identity; changing them means the project has forked the system
 - Site personalization happens ONLY by overriding `tokens-palette.css` tokens (font slots from the approved pairings, colors, accent, `--content-reading` per the measure table) in a stylesheet loaded after the tokens
 - After ANY palette change, run the audit and fix every failure before shipping — `npm run audit` inside this repo; `npx remarque-audit --palette <file> --src <dir>` in a consumer project (the npm script only exists here)
+- A generated palette override (from `npx remarque-theme <light> --dark <dark>`, see REMARQUE.md "Color Providers") is regenerated, never hand-edited — if it needs to change, change the source theme slugs and re-run `remarque-theme`, don't patch the emitted CSS directly
 
 ### Typography
 

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
 
+## 0.10.0 — 2026-07-23
+
+Color-provider Phase 2 groundwork: the upstream dataset now pairs its own
+themes, so the bridge no longer needs to be told what goes with what.
+
+### Changed
+- **`remarque-theme`: `--dark` is now optional.** Dataset 0.2.0 of
+  `@williamzujkowski/oklch-terminal-themes` ships a `counterpart` field
+  (canonical light↔dark pairing, curated for ambiguous families —
+  upstream #128); when the light theme declares one, the bridge uses it.
+  A counterpart slug is validated exactly like a user-supplied `--dark`
+  (index membership before any path resolution). Lights without a
+  counterpart still require `--dark`; nothing is guessed from names.
+- **Corpus test now enumerates pairs from the `counterpart` field**
+  instead of the name-stem heuristic it shipped with — the dataset is
+  authoritative; the heuristic is gone.
+- Dev-pinned dataset bumped `0.1.0` → `0.2.0` (485 → 547 themes; the
+  corpus now includes deriving Remarque's palette from its own upstreamed
+  `remarque-light`/`remarque-dark` terminal themes, upstream #127).
+  `peerDependencies` widened to `>=0.1.0 <0.3.0`.
+
+## 0.9.0 — 2026-07-22
+
+Color-provider bridge release (consensus-ratified 7-0, higher_order panel;
+closes #75 — Phase 1 of the color-provider integration; Phase 2/3 tracked
+in #76).
+
+### Added
+- **`remarque-theme` bin** (#75): `npx remarque-theme <light-slug> --dark
+  <dark-slug> [-o out.css]` derives a full 15-slot palette-tier override
+  from an `@williamzujkowski/oklch-terminal-themes` light+dark pair.
+  Terminal themes carry only `background/foreground/cursor/selection` +
+  16 ANSI slots — most of Remarque's semantic slots don't map directly,
+  and most themes fail the AAA `fg-muted` 7:1 line as authored. The bridge
+  derives instead: hue + chroma come from the theme, lightness is solved
+  per slot by binary search against the exact Enforcement Checklist
+  targets (in-gamut chroma clamping inside the solver, round-then-verify
+  to avoid float rounding pushing a borderline value back out of gamut).
+  Output passes `remarque-audit` **by construction** — the script
+  self-verifies the same contrast + gamut checks in-process before it
+  will emit anything.
+- **Security hardening** (#75, panel security review): both slugs are
+  validated against the package's own `index.json` *before* any path is
+  built from them (the actual guard against path traversal, not the slug
+  regex, which is defense-in-depth); every OKLCH triplet read from theme
+  JSON is validated as finite numbers before use; CSS is never built by
+  string-interpolating raw JSON — every emitted number has passed through
+  our own rounding + validation. Light/dark polarity (`isDark`) is
+  enforced against the requested slugs.
+- **`scripts/test-theme.mjs`** (#75): a corpus property test enumerating
+  every light+dark pair in the installed `oklch-terminal-themes` package
+  by name-stem (47 pairs at the pinned 0.1.0 dataset) — every pair must
+  derive AND pass the real `audit.mjs`, not a sample. Also covers unknown
+  slugs, polarity mismatches, traversal-looking slugs, and that the
+  output declares only palette-tier custom properties. Wired into CI
+  alongside `test-audit.mjs`/`test-drift.mjs`.
+- **`@williamzujkowski/oklch-terminal-themes`** pinned exact at `0.1.0` in
+  `devDependencies`, and listed as an optional `^0.1.0` peerDependency —
+  consumers who want `remarque-theme` install it themselves; it is never
+  required to use the rest of the package.
+- REMARQUE.md: new "Color Providers" section positioning the palette tier
+  as theme-suppliable, with `oklch-terminal-themes` as the reference
+  provider and the pairing contract stated explicitly (`--dark` is
+  required; upstream pairing metadata tracked in
+  `oklch-terminal-themes#128`). AGENT_RULES.md: a rule against hand-editing
+  a generated palette — regenerate it instead.
+
+No core-tier token values changed in this release. `tokens-palette.css`
+(the shipped default palette) is also unchanged — `remarque-theme` is an
+opt-in alternate source for the palette tier, not a replacement for it.
+
 ## 0.8.0 — 2026-07-21
 
 Archetype-vocabulary and AI-agent-packaging release (design review; closes

package/REMARQUE.md

@@ -70,6 +70,24 @@ This makes compliance mechanical: a site that overrides only palette-tier tokens
 
 ---
 
+## Color Providers
+
+The palette tier (all `--color-*` tokens) can be *supplied* rather than hand-authored — Remarque focuses on typography, and a color-provider package can own the personalization surface it already sanctions.
+
+[`@williamzujkowski/oklch-terminal-themes`](https://www.npmjs.com/package/@williamzujkowski/oklch-terminal-themes) is the reference provider: a dataset of terminal color schemes converted to OKLCH. Run it through the bundled bridge:
+
+```
+npx remarque-theme <light-slug> [--dark <dark-slug>] [-o palette-override.css]
+```
+
+Terminal themes carry only `background/foreground/cursor/selection` + 16 ANSI slots — a few of Remarque's 15 semantic slots map directly, and most themes fail the AAA `fg-muted` 7:1 line as authored. So `remarque-theme` *derives* rather than maps: **hue and chroma carry the theme's personality; lightness is solved per slot** (binary search against the same contrast targets as the Enforcement Checklist below, with in-gamut chroma clamping) so the output passes `remarque-audit` by construction. The accent hue comes from the theme's cursor color if it's chromatic, otherwise the most saturated classic ANSI color, and is kept consistent between the light and dark half of a pair.
+
+The audit remains the gate regardless of provenance — `remarque-theme` self-verifies its own output against the same checks before it will emit anything, but a site that hand-edits a generated palette (or points at a provider with pathological input colors) still runs through `remarque-audit` in CI like any other palette.
+
+**Pairing contract:** dataset 0.2.0+ carries a `counterpart` field linking each paired theme to its canonical opposite-polarity variant ([`oklch-terminal-themes#128`](https://github.com/williamzujkowski/oklch-terminal-themes/issues/128)), and `--dark` defaults to it — `npx remarque-theme rose-pine-dawn` alone derives the rosé-pine pair. For a light theme without a counterpart (or an older dataset), `--dark <slug>` remains required; nothing is ever guessed from names. `remarque-theme` also rejects a light slug that isn't tagged `isDark: false` and a dark slug that isn't tagged `isDark: true`.
+
+---
+
 ## Font Slots
 
 Remarque uses a three-slot font system. Each slot has a strict role, and each slot accepts a small set of approved faces — swap the face, keep the role.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "engines": {
     "node": ">=18"
   },
@@ -23,12 +23,24 @@
   "main": "tokens.css",
   "bin": {
     "remarque-audit": "scripts/audit.mjs",
-    "remarque-drift": "scripts/drift-check.mjs"
+    "remarque-drift": "scripts/drift-check.mjs",
+    "remarque-theme": "scripts/theme.mjs"
   },
   "scripts": {
     "audit": "node scripts/audit.mjs",
     "drift": "node scripts/drift-check.mjs"
   },
+  "devDependencies": {
+    "@williamzujkowski/oklch-terminal-themes": "0.2.0"
+  },
+  "peerDependencies": {
+    "@williamzujkowski/oklch-terminal-themes": ">=0.1.0 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@williamzujkowski/oklch-terminal-themes": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": "./tokens.css",
     "./tokens": "./tokens.css",
@@ -59,6 +71,7 @@
     "fonts/",
     "scripts/audit.mjs",
     "scripts/drift-check.mjs",
+    "scripts/theme.mjs",
     "tailwind.config.js",
     "REMARQUE.md",
     "AGENT_RULES.md",

package/scripts/theme.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/*
+ * remarque-theme — derive a Remarque palette-tier override from an
+ * @williamzujkowski/oklch-terminal-themes light+dark pair.
+ *
+ *   node scripts/theme.mjs <light-slug> --dark <dark-slug> [-o out.css]
+ *   npx remarque-theme <light-slug> --dark <dark-slug> [-o out.css]
+ *
+ * Terminal themes carry only background/foreground/cursor/selection + 16
+ * ANSI slots — most of Remarque's 15 semantic slots don't map directly,
+ * and most themes fail the AAA fg-muted 7:1 line as authored. So this
+ * DERIVES rather than maps: hue + chroma come from the theme (its
+ * personality), lightness is solved per slot to hit the exact ratio
+ * targets from REMARQUE.md's Enforcement Checklist (binary search over
+ * L, with in-gamut chroma clamping inside the solver). Output passes
+ * remarque-audit BY CONSTRUCTION — this script self-verifies the same
+ * pairings before it will emit anything.
+ *
+ * Security (non-negotiable, per the panel security review on #75):
+ *   - Both slugs are checked against the package's own index.json BEFORE
+ *     any path is built from them — an unknown slug never reaches a
+ *     require.resolve() or fs call. This is the actual guard against
+ *     path traversal; the slug regex below is defense-in-depth, not the
+ *     primary control.
+ *   - Every OKLCH triplet read from theme JSON is validated as finite
+ *     numbers (l in [0,1], c >= 0, h in [0,360)) before it touches any
+ *     math. Malformed/hostile theme JSON fails loudly, never silently.
+ *   - CSS is never built by string-interpolating raw JSON. Every number
+ *     emitted has passed through our own rounding + validation first.
+ */
+
+import { createRequire } from 'node:module';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const PKG_SPEC = '@williamzujkowski/oklch-terminal-themes';
+const HERE = dirname(fileURLToPath(import.meta.url));
+let OWN_VERSION = 'unknown';
+try {
+  OWN_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
+} catch { /* provenance is best-effort */ }
+
+const USAGE = `usage: remarque-theme <light-slug> [--dark <dark-slug>] [-o out.css]
+
+  <light-slug>     slug of a theme with isDark=false in ${PKG_SPEC}
+  --dark <slug>    slug of a theme with isDark=true; defaults to the light
+                    theme's "counterpart" from the dataset (0.2.0+) when it
+                    has one, and is required when it doesn't
+  -o, --output     write the derived palette here instead of stdout`;
+
+function die(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+/* ── CLI args ─────────────────────────────────────────────────────── */
+
+const argv = process.argv.slice(2);
+let darkSlug, outFile;
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--dark') darkSlug = argv[++i];
+  else if (a === '-o' || a === '--output') outFile = argv[++i];
+  else if (a === '-h' || a === '--help') { console.log(USAGE); process.exit(0); }
+  else positional.push(a);
+}
+const lightSlug = positional[0];
+if (!lightSlug) die(USAGE);
+
+/* ── Resolve @williamzujkowski/oklch-terminal-themes ─────────────────
+ * Tried from the consumer's cwd first (a project that installs the
+ * themes package at its own top level), then from this script's own
+ * location (covers hoisting layouts where only remarque-tokens itself
+ * declares the peerDependency). First resolvable wins. */
+
+function tryResolveFrom(base) {
+  try {
+    const req = createRequire(base);
+    const indexPath = req.resolve(`${PKG_SPEC}/index.json`);
+    return { req, indexPath };
+  } catch {
+    return null;
+  }
+}
+
+const resolved =
+  tryResolveFrom(pathToFileURL(join(process.cwd(), 'package.json')).href) ||
+  tryResolveFrom(import.meta.url);
+
+if (!resolved) {
+  die(
+    `${PKG_SPEC} is not installed (checked from the current project and from remarque-tokens itself).\n\n` +
+    `Install it and retry:\n  npm install ${PKG_SPEC}@0.1.0\n`
+  );
+}
+
+const index = JSON.parse(readFileSync(resolved.indexPath, 'utf8'));
+const bySlug = new Map((index.themes || []).map((t) => [t.slug, t]));
+
+// Package root sits two directories above data/index.json; read its
+// package.json for the provenance header directly via fs (not through
+// "exports" — the package does not publish that subpath).
+const themesPkgRoot = dirname(dirname(resolved.indexPath));
+let themesVersion = 'unknown';
+try {
+  themesVersion = JSON.parse(readFileSync(join(themesPkgRoot, 'package.json'), 'utf8')).version;
+} catch { /* provenance is best-effort */ }
+
+/* ── Slug validation — the actual security boundary ──────────────────
+ * A slug is only ever used to build a require specifier AFTER it has
+ * been matched, byte-for-byte, against an entry in the package's own
+ * index. Nothing user-supplied reaches require.resolve()/fs otherwise. */
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function requireSlug(slug, label) {
+  if (typeof slug !== 'string' || !SLUG_RE.test(slug) || !bySlug.has(slug)) {
+    die(`${label} slug "${slug}" is not a known theme in ${PKG_SPEC} (see its index.json for valid slugs)`);
+  }
+  return bySlug.get(slug);
+}
+
+const lightMeta = requireSlug(lightSlug, 'light');
+/* --dark defaults to the dataset's counterpart field (0.2.0+). The value
+ * still goes through requireSlug like a user-supplied one — a dataset
+ * entry is not trusted further than the CLI arg it replaces. */
+if (!darkSlug) {
+  darkSlug = lightMeta.counterpart;
+  if (!darkSlug) {
+    die(
+      `"${lightSlug}" has no counterpart in the installed ${PKG_SPEC} dataset — ` +
+      `pass --dark <slug> explicitly (or upgrade the dataset; pairing metadata landed in 0.2.0)`
+    );
+  }
+}
+const darkMeta = requireSlug(darkSlug, 'dark');
+if (lightMeta.isDark !== false) die(`light slug "${lightSlug}" has isDark=${lightMeta.isDark}, expected false`);
+if (darkMeta.isDark !== true) die(`dark slug "${darkSlug}" has isDark=${darkMeta.isDark}, expected true`);
+
+function loadTheme(slug) {
+  // Safe: slug has already been matched against the package's index above.
+  const path = resolved.req.resolve(`${PKG_SPEC}/themes/${slug}.json`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+const themeLight = loadTheme(lightSlug);
+const themeDark = loadTheme(darkSlug);
+
+/* ── Numeric validation ───────────────────────────────────────────── */
+
+const isNum = (x) => typeof x === 'number' && Number.isFinite(x);
+
+function validateOklch(o, where) {
+  if (!o || !isNum(o.l) || o.l < 0 || o.l > 1) die(`${where}: invalid or missing OKLCH l (${o && o.l})`);
+  if (!isNum(o.c) || o.c < 0) die(`${where}: invalid or missing OKLCH c (${o && o.c})`);
+  if (!isNum(o.h) || o.h < 0 || o.h >= 360) die(`${where}: invalid or missing OKLCH h (${o && o.h})`);
+  return [o.l, o.c, o.h];
+}
+
+function slotLch(theme, slot, label) {
+  const entry = theme.colors && theme.colors[slot];
+  if (!entry || !entry.oklch) die(`${label}: missing colors.${slot}.oklch`);
+  return validateOklch(entry.oklch, `${label} colors.${slot}`);
+}
+
+/* ── OKLCH → sRGB → WCAG luminance (same Ottosson matrices as audit.mjs) */
+
+function oklchToLinearSrgb(L, C, H) {
+  const h = (H * Math.PI) / 180;
+  const a = C * Math.cos(h), b = C * Math.sin(h);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 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.7076147010 * s,
+  ];
+}
+const inGamut = (rgb) => rgb.every((x) => x >= -0.0005 && x <= 1.0005);
+const clip = (x) => Math.min(1, Math.max(0, x));
+const luminance = (rgb) => {
+  const [r, g, b] = rgb.map(clip);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+function ratio(c1, c2) {
+  const l1 = luminance(oklchToLinearSrgb(...c1));
+  const l2 = luminance(oklchToLinearSrgb(...c2));
+  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+const r3 = (x) => +x.toFixed(3);
+const r1 = (x) => +x.toFixed(1);
+
+/* Largest chroma <= C that stays in sRGB gamut at (L, H).
+ * Round-then-verify (fixes the spike's bug, see #75): stepping in
+ * unrounded space and only rounding the final answer can round a
+ * borderline-in-gamut value back OUT of gamut (float rounding is not
+ * gamut-aware). So after the coarse search we round, then keep backing
+ * off in already-rounded steps until the ROUNDED value itself verifies. */
+function fitChroma(L, C, H) {
+  let c = Math.max(0, C);
+  while (c > 0 && !inGamut(oklchToLinearSrgb(L, c, H))) c -= 0.001;
+  c = Math.max(0, c);
+  let rounded = r3(c);
+  while (rounded > 0 && !inGamut(oklchToLinearSrgb(L, rounded, H))) rounded = r3(rounded - 0.001);
+  return Math.max(0, rounded);
+}
+
+/* Solve lightness so [L, C', H] hits >= target ratio against bg.
+ * dir 'darker': text on a light bg — find the MAX L that still passes
+ * (stays closest to the theme's own feel). dir 'lighter': text on a
+ * dark bg — find the MIN L. Chroma is clamped in-gamut INSIDE the
+ * solver at every candidate L, and the final [L, C, H] is rounded, then
+ * re-verified against the real (non-margin) target — nudging L further
+ * in the safe direction if rounding cost just enough ratio to fail. */
+function solveLOnce(C, H, bg, target, dir) {
+  const searchTarget = target * 1.03; // margin over the audit threshold
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const c = fitChroma(mid, C, H);
+    const passes = ratio([mid, c, H], bg) >= searchTarget;
+    if (dir === 'darker') { if (passes) lo = mid; else hi = mid; }
+    else { if (passes) hi = mid; else lo = mid; }
+  }
+  let L = r3(dir === 'darker' ? lo : hi);
+  let c = fitChroma(L, C, H);
+  let guard = 0;
+  while (ratio([L, c, H], bg) < target && guard < 100) {
+    const next = dir === 'darker' ? r3(L - 0.001) : r3(L + 0.001);
+    if (next < 0 || next > 1 || next === L) break;
+    L = next;
+    c = fitChroma(L, C, H);
+    guard++;
+  }
+  const ok = ratio([L, c, H], bg) >= target;
+  return { L, C: c, H: r1(H), ok };
+}
+
+function solveL(C, H, bg, target, dir) {
+  let r = solveLOnce(C, H, bg, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  // Chroma-collapse fallback: retry as a neutral if the chromatic
+  // solve can't reach the target ratio at any lightness.
+  r = solveLOnce(0, H, bg, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  die(
+    `internal error: cannot solve lightness for a ${target}:1 target ` +
+    `(hue ${H.toFixed(1)}, direction ${dir}) even with chroma collapsed to 0 — pathological theme colors`
+  );
+}
+
+/* Accent hue: cursor if it's chromatic, else the most-chromatic classic ANSI. */
+function accentHue(theme, label) {
+  const cursor = theme.colors && theme.colors.cursor && theme.colors.cursor.oklch;
+  if (cursor) {
+    const [, c, h] = validateOklch(cursor, `${label} colors.cursor`);
+    if (c >= 0.05) return { h, c, from: 'cursor' };
+  }
+  const names = ['blue', 'purple', 'red', 'green', 'cyan', 'yellow'];
+  const cands = [];
+  for (const name of names) {
+    const o = theme.colors && theme.colors[name] && theme.colors[name].oklch;
+    if (!o) continue;
+    const [, c, h] = validateOklch(o, `${label} colors.${name}`);
+    cands.push({ name, c, h });
+  }
+  if (!cands.length) die(`${label}: no classic ANSI colors available to derive an accent hue`);
+  cands.sort((a, b) => b.c - a.c);
+  return { h: cands[0].h, c: cands[0].c, from: cands[0].name };
+}
+
+function fmt(triple) {
+  const [L, C, H] = triple;
+  if (!isNum(L) || !isNum(C) || !isNum(H)) die('internal error: attempted to emit a non-finite color component');
+  return `oklch(${L} ${C} ${H})`;
+}
+
+/* ── LIGHT derivation ─────────────────────────────────────────────── */
+
+function deriveLight(t) {
+  const [bgL0, bgC0, bgH0] = slotLch(t, 'background', 'light');
+  const bgH = r1(bgH0);
+  const bgL = r3(Math.max(bgL0, 0.93));
+  const bgC = fitChroma(bgL, Math.min(bgC0, 0.02), bgH);
+  const bg = [bgL, bgC, bgH];
+  const surface = [r3(bgL - 0.01), bgC, bgH];
+  const [, fgC0, fgH] = slotLch(t, 'foreground', 'light');
+  const fgC = Math.min(fgC0, 0.03);
+  const fg = solveL(fgC, fgH, surface, 10, 'darker');
+  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'darker');
+  const muted = solveL(Math.min(fgC0, 0.02), fgH, surface, 4.5, 'darker');
+  const borderBold = solveL(0.01, bgH, bg, 3.0, 'darker');
+  const ac = accentHue(t, 'light');
+  const acC = Math.min(ac.c, 0.14);
+  const accent = solveL(acC, ac.h, bg, 4.5, 'darker');
+  const accentHover = [r3(accent[0] - 0.08), fitChroma(r3(accent[0] - 0.08), acC * 0.8, ac.h), r1(ac.h)];
+  const raw = {
+    'color-bg': bg,
+    'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
+    'color-fg': fg,
+    'color-fg-muted': fgMuted,
+    'color-muted': muted,
+    'color-border': [r3(bg[0] - 0.095), bg[1], bg[2]],
+    'color-border-bold': borderBold,
+    'color-surface': surface,
+    'color-accent': accent,
+    'color-accent-hover': accentHover,
+    'color-accent-subtle': [0.95, fitChroma(0.95, 0.02, ac.h), r1(ac.h)],
+    'color-selection-bg': [0.92, fitChroma(0.92, 0.04, ac.h), r1(ac.h)],
+    'color-selection-fg': { ref: 'color-fg' },
+    'color-code-bg': [r3(bg[0] - 0.03), bg[1], bg[2]],
+    'color-code-fg': { ref: 'color-fg' },
+  };
+  const tokens = {};
+  for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
+  return { accentFrom: ac.from, accentH: ac.h, raw, tokens };
+}
+
+/* ── DARK derivation ──────────────────────────────────────────────── */
+
+function deriveDark(t, accentHueLight) {
+  const [bgL0, bgC0, bgH0] = slotLch(t, 'background', 'dark');
+  const bgH = r1(bgH0);
+  const bgL = r3(Math.min(Math.max(bgL0, 0.14), 0.22));
+  const bgC = fitChroma(bgL, Math.min(bgC0, 0.03), bgH);
+  const bg = [bgL, bgC, bgH];
+  const surface = [r3(bg[0] + 0.03), bgC, bgH];
+  const [, fgC0, fgH] = slotLch(t, 'foreground', 'dark');
+  const fgC = Math.min(fgC0, 0.02);
+  const fg = solveL(fgC, fgH, surface, 10, 'lighter');
+  const fgMuted = solveL(fgC, fgH, bg, 7.0, 'lighter');
+  const muted = solveL(fgC, fgH, surface, 4.5, 'lighter');
+  const borderBold = solveL(0.01, bgH, bg, 3.0, 'lighter');
+  const ac = accentHue(t, 'dark');
+  const h = accentHueLight ?? ac.h; // keep hue consistent across the pair
+  const acC = Math.min(ac.c, 0.12);
+  const accent = solveL(acC, h, bg, 4.5, 'lighter');
+  const accentHover = [r3(accent[0] + 0.07), fitChroma(r3(accent[0] + 0.07), acC, h), r1(h)];
+  const selBg = [r3(bg[0] + 0.14), fitChroma(r3(bg[0] + 0.14), 0.06, h), r1(h)];
+  const selFg = solveL(0.005, fgH, selBg, 4.5, 'lighter');
+  const codeBg = [r3(bg[0] + 0.04), bgC, bgH];
+  const codeFg = solveL(0.005, fgH, codeBg, 7, 'lighter');
+  const raw = {
+    'color-bg': bg,
+    'color-bg-subtle': surface,
+    'color-fg': fg,
+    'color-fg-muted': fgMuted,
+    'color-muted': muted,
+    'color-border': [r3(bg[0] + 0.09), bg[1], bg[2]],
+    'color-border-bold': borderBold,
+    'color-surface': surface,
+    'color-accent': accent,
+    'color-accent-hover': accentHover,
+    'color-accent-subtle': [r3(bg[0] + 0.06), fitChroma(r3(bg[0] + 0.06), 0.04, h), r1(h)],
+    'color-selection-bg': selBg,
+    'color-selection-fg': selFg,
+    'color-code-bg': codeBg,
+    'color-code-fg': codeFg,
+  };
+  const tokens = {};
+  for (const [name, v] of Object.entries(raw)) tokens[name] = fmt(v);
+  tokens['weight-display'] = '500';
+  return { raw, tokens };
+}
+
+const light = deriveLight(themeLight);
+const dark = deriveDark(themeDark, light.accentH);
+
+/* ── Self-verify — the same pairings + gamut rule as scripts/audit.mjs,
+ * run in-process against the raw [L,C,H] triples (mirrored here rather
+ * than reparsing the CSS we're about to emit). This should be
+ * impossible to fail; a failure means a bug in the derivation above,
+ * not a bad input theme, so it errors as an internal error. */
+
+const CHECKS = [
+  ['color-fg', 'color-bg', 4.5, 'primary text'],
+  ['color-fg', 'color-surface', 4.5, 'primary text on surface'],
+  ['color-fg-muted', 'color-bg', 7.0, 'secondary text (spec AAA line)'],
+  ['color-muted', 'color-bg', 4.5, 'tertiary text'],
+  ['color-muted', 'color-surface', 4.5, 'tertiary text on surface'],
+  ['color-accent', 'color-bg', 4.5, 'links'],
+  ['color-accent-hover', 'color-bg', 4.5, 'link hover'],
+  ['color-code-fg', 'color-code-bg', 4.5, 'code text'],
+  ['color-border-bold', 'color-bg', 3.0, 'functional borders (WCAG 1.4.11)'],
+  ['color-selection-fg', 'color-selection-bg', 4.5, 'selected text'],
+];
+
+function resolveRaw(raw, name, seen = new Set()) {
+  if (seen.has(name)) die(`internal error: circular var() chain at --${name}`);
+  seen.add(name);
+  const v = raw[name];
+  if (v === undefined) die(`internal error: --${name} was never derived`);
+  return v.ref ? resolveRaw(raw, v.ref, seen) : v;
+}
+
+function selfVerify(themeName, raw) {
+  for (const [name, v] of Object.entries(raw)) {
+    const triple = v.ref ? resolveRaw(raw, name) : v;
+    if (!inGamut(oklchToLinearSrgb(...triple))) {
+      die(`internal error: derived --${name} (${themeName}) oklch(${triple.join(' ')}) is outside sRGB gamut`);
+    }
+  }
+  for (const [fgName, bgName, min, label] of CHECKS) {
+    const fg = resolveRaw(raw, fgName);
+    const bg = resolveRaw(raw, bgName);
+    const r = ratio(fg, bg);
+    if (r < min) {
+      die(`internal error: derived --${fgName}/--${bgName} (${themeName}) = ${r.toFixed(2)}:1 < ${min}:1 (${label}) — this should be impossible; the derivation has a bug`);
+    }
+  }
+}
+selfVerify('light', light.raw);
+selfVerify('dark', dark.raw);
+
+/* ── Emit ─────────────────────────────────────────────────────────── */
+
+const decls = (tokens, indent = '  ') => Object.entries(tokens).map(([k, v]) => `${indent}--${k}: ${v};`).join('\n');
+
+const css = `/*
+ * Generated by remarque-theme (remarque-tokens ${OWN_VERSION}) — DO NOT HAND-EDIT.
+ * Regenerate instead: npx remarque-theme ${lightSlug} --dark ${darkSlug}
+ *
+ * Source themes (${PKG_SPEC}@${themesVersion}):
+ *   light = "${lightSlug}"   dark = "${darkSlug}"
+ *   accent hue derived from: ${light.accentFrom} (H=${light.accentH.toFixed(1)})
+ *
+ * Palette tier only (--color-*, --weight-display) — see REMARQUE.md
+ * "Token Tiers" / "Color Providers". Self-verified against the same
+ * contrast + gamut checks as remarque-audit before being emitted.
+ */
+
+:root {
+${decls(light.tokens)}
+  --weight-display: 400;
+}
+
+[data-theme="dark"] {
+${decls(dark.tokens)}
+}
+`;
+
+if (outFile) {
+  writeFileSync(outFile, css);
+  console.error(`remarque-theme: wrote ${outFile}`);
+} else {
+  process.stdout.write(css);
+}

package/tokens.json

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.8.0",
+      "version": "0.10.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"