@hadoku/themes 0.0.0-stage → 5.12.15

package/scripts/lib/color.mjs

@@ -0,0 +1,184 @@
+/**
+ * Color math for theme token validation.
+ *
+ * Handles the three value formats that appear in style.css: #rrggbb,
+ * rgba(r, g, b, a), and the CSS keywords black/white. Alpha matters — the
+ * `-bg` and `-hover` tokens are translucent, so contrast has to be computed
+ * against the composited result over a real surface, not the raw value.
+ */
+
+const NAMED = {
+  black: [0, 0, 0, 1],
+  white: [255, 255, 255, 1],
+  transparent: [0, 0, 0, 0]
+}
+
+/**
+ * Parse a CSS color into [r, g, b, a]. Throws on anything unrecognized.
+ * Already-parsed [r,g,b,a] tuples pass straight through, so the output of
+ * flatten() can be fed back in as a backdrop without a round-trip to string.
+ */
+export function parseColor(input) {
+  if (Array.isArray(input)) {
+    const [r, g, b, a = 1] = input
+    return [r, g, b, a]
+  }
+  const value = String(input).trim().toLowerCase()
+
+  if (NAMED[value]) return [...NAMED[value]]
+
+  const hex = value.match(/^#([0-9a-f]{3,8})$/)
+  if (hex) {
+    let h = hex[1]
+    if (h.length === 3 || h.length === 4) {
+      h = h
+        .split('')
+        .map(c => c + c)
+        .join('')
+    }
+    if (h.length !== 6 && h.length !== 8) {
+      throw new Error(`Unsupported hex color: ${input}`)
+    }
+    return [
+      parseInt(h.slice(0, 2), 16),
+      parseInt(h.slice(2, 4), 16),
+      parseInt(h.slice(4, 6), 16),
+      h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1
+    ]
+  }
+
+  const rgb = value.match(/^rgba?\(([^)]+)\)$/)
+  if (rgb) {
+    const parts = rgb[1].split(/[,\s/]+/).filter(Boolean)
+    if (parts.length < 3) throw new Error(`Unsupported rgb color: ${input}`)
+    const channel = p => (p.endsWith('%') ? (parseFloat(p) / 100) * 255 : parseFloat(p))
+    const alpha =
+      parts[3] === undefined
+        ? 1
+        : parts[3].endsWith('%')
+          ? parseFloat(parts[3]) / 100
+          : parseFloat(parts[3])
+    return [channel(parts[0]), channel(parts[1]), channel(parts[2]), alpha]
+  }
+
+  throw new Error(`Cannot parse color: ${input}`)
+}
+
+/** Composite a possibly-translucent foreground over an opaque backdrop. */
+export function flatten(color, backdrop) {
+  const [r, g, b, a] = parseColor(color)
+  if (a >= 1) return [r, g, b, 1]
+  const [br, bg, bb] = parseColor(backdrop)
+  return [r * a + br * (1 - a), g * a + bg * (1 - a), b * a + bb * (1 - a), 1]
+}
+
+/** WCAG 2.2 relative luminance. */
+export function luminance(rgb) {
+  const [r, g, b] = rgb.slice(0, 3).map(v => {
+    const c = v / 255
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/**
+ * WCAG 2.2 contrast ratio between two colors, each flattened over `backdrop`
+ * first so translucent tokens are measured as they actually render.
+ */
+export function contrast(fg, bg, backdrop = '#ffffff') {
+  const f = luminance(flatten(fg, flatten(bg, backdrop)))
+  const b = luminance(flatten(bg, backdrop))
+  const [hi, lo] = f > b ? [f, b] : [b, f]
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+/** Round a ratio the way the docs report it. */
+export const ratio = n => Math.round(n * 100) / 100
+
+export function toHex([r, g, b]) {
+  const c = v =>
+    Math.round(Math.min(255, Math.max(0, v)))
+      .toString(16)
+      .padStart(2, '0')
+  return `#${c(r)}${c(g)}${c(b)}`
+}
+
+/* ---------- OKLCH, for perceptually-even shade derivation ---------- */
+/* THEME_SYSTEM_RULES.md §8: derive variants in OKLCH, not HSL — an HSL
+   lightness shift that is fine for blue is catastrophic for yellow. */
+
+const srgbToLinear = c => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const linearToSrgb = c => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055)
+
+export function rgbToOklch([r, g, b]) {
+  const lr = srgbToLinear(r / 255)
+  const lg = srgbToLinear(g / 255)
+  const lb = srgbToLinear(b / 255)
+
+  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 bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+
+  const C = Math.sqrt(a * a + bb * bb)
+  let H = (Math.atan2(bb, a) * 180) / Math.PI
+  if (H < 0) H += 360
+  return { L, C, H }
+}
+
+export function oklchToRgb({ L, C, H }) {
+  const h = (H * Math.PI) / 180
+  const a = C * Math.cos(h)
+  const b = C * Math.sin(h)
+
+  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
+
+  const lr = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s
+  const lg = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s
+  const lb = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
+
+  return [linearToSrgb(lr) * 255, linearToSrgb(lg) * 255, linearToSrgb(lb) * 255].map(v =>
+    Math.min(255, Math.max(0, v))
+  )
+}
+
+/**
+ * OKLCH → sRGB with the chroma pulled in until the result is inside the sRGB
+ * gamut. Lightness and hue are kept exactly; only chroma gives way. This is
+ * what lets an editor slider move L or H freely without producing a color the
+ * screen cannot show.
+ */
+export function oklchToRgbInGamut({ L, C, H }) {
+  const target = Math.min(1, Math.max(0, L))
+  // Binary-search chroma down until the result round-trips inside sRGB.
+  let lo = 0
+  let hi = Math.max(0, C)
+  let best = oklchToRgb({ L: target, C: 0, H })
+  for (let i = 0; i < 24; i += 1) {
+    const mid = (lo + hi) / 2
+    const candidate = oklchToRgb({ L: target, C: mid, H })
+    const inGamut = candidate.every(v => v >= -0.5 && v <= 255.5)
+    if (inGamut) {
+      best = candidate
+      lo = mid
+    } else {
+      hi = mid
+    }
+  }
+  return best
+}
+
+/**
+ * Shift a color's OKLCH lightness by `delta` (positive = lighter), clamping
+ * chroma so the result stays in sRGB gamut.
+ */
+export function shiftLightness(color, delta) {
+  const [r, g, b, alpha] = parseColor(color)
+  const { L, C, H } = rgbToOklch([r, g, b])
+  return { rgb: oklchToRgbInGamut({ L: L + delta, C, H }), alpha }
+}

package/scripts/lib/contract.d.mts

@@ -0,0 +1,58 @@
+/** Types for contract.mjs — see that file for the behaviour. */
+
+export type RGBA = [number, number, number, number]
+export type ThemeTokens = Record<string, string>
+export type ThemeTokenMap = Record<string, ThemeTokens>
+/** `{ [theme]: { [--color-token]: value } }` */
+export type TokenEdits = Record<string, Record<string, string>>
+
+export interface TokenChange {
+  theme: string
+  token: string
+  from: string
+  to: string
+}
+
+export interface ComfortMetric {
+  id: string
+  label: string
+  value: number
+  ok: boolean
+  target: string
+  display: string
+}
+
+export const THEMES: readonly string[]
+export const FAMILIES: readonly string[]
+export const STRUCTURAL: readonly string[]
+export const AA_TEXT: number
+export const WCAG_PAIR_COUNT: number
+
+export function isDarkTheme(theme: string): boolean
+export function parseThemes(css: string): ThemeTokenMap
+export function checkTheme(theme: string, tokens: ThemeTokens): string[]
+export function checkThemes(themes: ThemeTokenMap): string[]
+export function comfortMetrics(theme: string, tokens: ThemeTokens): ComfortMetric[]
+export function formatColor(rgba: number[]): string
+export function normalizeColor(input: unknown): string
+export function applyTokenEdits(
+  css: string,
+  edits: TokenEdits
+): { css: string; changes: TokenChange[] }
+
+export function parseColor(input: string | number[]): RGBA
+export function flatten(color: string | number[], backdrop: string | number[]): RGBA
+export function contrast(
+  fg: string | number[],
+  bg: string | number[],
+  backdrop?: string | number[]
+): number
+export function luminance(rgb: number[]): number
+export function ratio(n: number): number
+export function toHex(rgb: number[]): string
+export function rgbToOklch(rgb: number[]): { L: number; C: number; H: number }
+export function oklchToRgbInGamut(lch: {
+  L: number
+  C: number
+  H: number
+}): [number, number, number]

package/scripts/lib/contract.mjs

@@ -0,0 +1,348 @@
+/**
+ * The theme contract, as pure functions over style.css TEXT.
+ *
+ * One implementation, three callers:
+ *   - check-contrast.mjs (the CLI gate lint:css runs)
+ *   - the hosted theme editor (@wolffm/task/editor), live as sliders move
+ *   - the task worker's save route, which re-checks before it commits to main
+ *
+ * The editor's verdict is a preview; the worker's is the one that counts. They
+ * agree because they are the same code, not because they were kept in sync.
+ *
+ * No node imports — this module is bundled into a browser page and a
+ * Cloudflare Worker. Exposed as `@wolffm/themes/contract`.
+ */
+
+import { parseColor, flatten, contrast, luminance, ratio, toHex, rgbToOklch } from './color.mjs'
+import { AA_TEXT, SURFACE_STEP, BORDER_STEP, BORDER_LIGHT_STEP } from './derive.mjs'
+import {
+  THEMES,
+  FAMILIES,
+  STRUCTURAL,
+  isDarkTheme,
+  parseThemes,
+  readBlocks,
+  blankComments,
+  themesForSelector
+} from './tokens.mjs'
+
+export { THEMES, FAMILIES, STRUCTURAL, isDarkTheme, parseThemes, AA_TEXT }
+export {
+  parseColor,
+  flatten,
+  contrast,
+  luminance,
+  ratio,
+  toHex,
+  rgbToOklch,
+  oklchToRgbInGamut
+} from './color.mjs'
+
+const VARIANTS = ['', '-dark', '-bg', '-hover']
+
+/** Every app surface a component (and therefore a translucent tint) can sit on. */
+const SURFACES = ['bg', 'bg-card', 'bg-alt']
+
+/**
+ * Every structural and WCAG problem in one theme's tokens, as human-readable
+ * strings. Empty = the theme passes the gate.
+ */
+export function checkTheme(theme, tk) {
+  const problems = []
+  const surface =
+    tk['--color-bg-card'] || tk['--color-bg'] || (isDarkTheme(theme) ? '#000' : '#fff')
+
+  // 1. Structural symmetry — every family carries an identical token set.
+  for (const f of FAMILIES) {
+    for (const v of VARIANTS) {
+      if (!tk[`--color-${f}${v}`]) problems.push(`${theme}: missing --color-${f}${v}`)
+    }
+    for (const on of [`--color-on-${f}`, `--color-on-${f}-bg`]) {
+      if (!tk[on]) problems.push(`${theme}: missing ${on}`)
+    }
+  }
+  for (const s of STRUCTURAL) {
+    if (!tk[`--color-${s}`]) problems.push(`${theme}: missing --color-${s}`)
+  }
+
+  // 2. Contrast contracts. The `-bg` tints are translucent, so the pair is
+  //    checked against every surface the badge could be placed on, not just
+  //    the card — the same badge on `bg-alt` is a different composite.
+  for (const f of FAMILIES) {
+    const opaquePairs = [
+      [`on-${f}`, tk[`--color-on-${f}`], f, tk[`--color-${f}`], 'filled button'],
+      [
+        `on-${f}`,
+        tk[`--color-on-${f}`],
+        `${f}-dark`,
+        tk[`--color-${f}-dark`],
+        'button gradient bottom'
+      ]
+    ]
+    for (const [fgName, fg, bgName, bg, what] of opaquePairs) {
+      if (!fg || !bg) continue
+      const r = contrast(fg, bg, surface)
+      if (r < AA_TEXT) {
+        problems.push(
+          `${theme}: ${what} — ${fgName} on ${bgName} is ${ratio(r)}:1 (needs ${AA_TEXT}:1)`
+        )
+      }
+    }
+
+    const fg = tk[`--color-on-${f}-bg`]
+    const tint = tk[`--color-${f}-bg`]
+    if (fg && tint) {
+      for (const s of SURFACES) {
+        const r = contrast(fg, tint, tk[`--color-${s}`])
+        if (r < AA_TEXT) {
+          problems.push(
+            `${theme}: tint badge on ${s} — on-${f}-bg on ${f}-bg is ${ratio(r)}:1 (needs ${AA_TEXT}:1)`
+          )
+        }
+      }
+    }
+  }
+
+  // 3. Text must be readable on every surface it can land on. `-tertiary` and
+  //    `-muted` are deliberately excluded: they are decorative-only and do not
+  //    clear AA in every theme (documented in THEME_USAGE_GUIDE.md).
+  for (const token of ['text', 'text-secondary']) {
+    for (const s of SURFACES) {
+      const r = contrast(tk[`--color-${token}`], tk[`--color-${s}`], surface)
+      if (r < AA_TEXT) {
+        problems.push(`${theme}: ${token} on ${s} is ${ratio(r)}:1 (needs ${AA_TEXT}:1)`)
+      }
+    }
+  }
+
+  // 4. Surface separation. WCAG says nothing about page vs card, which is how
+  //    the light themes drifted to white-on-white with nobody noticing: every
+  //    pair above passed while the cards were invisible. Floors and their
+  //    measurement are documented beside SURFACE_STEP in derive.mjs.
+  const L = c => rgbToOklch(flatten(c, surface)).L
+  const mode = isDarkTheme(theme) ? 'dark' : 'light'
+  const steps = [
+    ['bg-card', 'bg', SURFACE_STEP],
+    ['border', 'bg-card', BORDER_STEP[mode]],
+    ['border-light', 'bg-card', BORDER_LIGHT_STEP[mode]]
+  ]
+  for (const [a, b, floor] of steps) {
+    const fa = tk[`--color-${a}`]
+    const fb = tk[`--color-${b}`]
+    if (!fa || !fb) continue
+    const d = Math.abs(L(fa) - L(fb))
+    if (d < floor) {
+      problems.push(`${theme}: ${a} vs ${b} is ΔL ${d.toFixed(3)} (needs ${floor} OKLCH)`)
+    }
+  }
+  return problems
+}
+
+/** checkTheme over every shipped theme. */
+export function checkThemes(themes) {
+  return THEMES.flatMap(theme => checkTheme(theme, themes[theme] ?? {}))
+}
+
+/** Number of WCAG pairs checkTheme evaluates across all themes, for reporting. */
+export const WCAG_PAIR_COUNT =
+  THEMES.length * (FAMILIES.length * (2 + SURFACES.length) + 2 * SURFACES.length)
+
+/**
+ * Where each semantic family's hue is EXPECTED to sit, in OKLCH degrees. A
+ * `success` that renders orange is not a contrast failure, but a reader who has
+ * learned "green = done" will misread it — which is a comfort problem the AA
+ * gate cannot see. Ranges are wide on purpose: they catch a family drifting to
+ * another meaning, not a theme choosing its own shade.
+ */
+const SEMANTIC_HUES = {
+  success: [100, 180],
+  warning: [45, 110],
+  danger: [0, 50, 330, 360]
+}
+
+function hueInRange(h, range) {
+  for (let i = 0; i < range.length; i += 2) {
+    if (h >= range[i] && h <= range[i + 1]) return true
+  }
+  return false
+}
+
+/**
+ * Comfort metrics: the things that make a theme tiring to look at while every
+ * AA pair still passes. ADVISORY — they guide the editor's meters and never
+ * block a save; the contract above is the only gate.
+ *
+ * Measured 2026-10-23 when light themes were reported "painful": card-vs-page
+ * separation was 1.03–1.07:1 in 8 of 9 light themes (cards invisible), borders
+ * 1.25–1.55:1, and body text up to 17:1 on near-white.
+ */
+export function comfortMetrics(theme, tk) {
+  const dark = isDarkTheme(theme)
+  const bg = tk['--color-bg']
+  const card = tk['--color-bg-card']
+  const metrics = []
+  const push = (id, label, value, ok, target, display) =>
+    metrics.push({ id, label, value, ok, target, display: display ?? `${ratio(value)}:1` })
+
+  try {
+    const sep = contrast(card, bg, bg)
+    push('surface-separation', 'Card vs page', sep, sep >= 1.1, '≥ 1.10:1')
+
+    const border = contrast(tk['--color-border'], card, bg)
+    push('border-visibility', 'Border vs card', border, border >= 1.6, '≥ 1.60:1')
+
+    const text = contrast(tk['--color-text'], bg, bg)
+    push('text-harshness', 'Text vs page', text, text >= 7 && text <= 15, '7–15:1')
+
+    const lum = luminance(flatten(bg, dark ? '#000' : '#fff'))
+    if (dark) {
+      push('page-depth', 'Page darkness', lum, lum <= 0.02, '≤ 0.020', lum.toFixed(3))
+    } else {
+      push('page-glare', 'Page glare', lum, lum <= 0.9, '≤ 0.900', lum.toFixed(3))
+    }
+
+    for (const [family, range] of Object.entries(SEMANTIC_HUES)) {
+      const [r, g, b] = parseColor(tk[`--color-${family}`])
+      const { H, C } = rgbToOklch([r, g, b])
+      // A near-grey has no meaningful hue; don't flag what nobody can see.
+      const ok = C < 0.03 || hueInRange(H, range)
+      push(
+        `${family}-hue`,
+        `${family} reads as ${family}`,
+        H,
+        ok,
+        `hue ${range.slice(0, 2).join('–')}°`,
+        `${Math.round(H)}°`
+      )
+    }
+  } catch (e) {
+    metrics.push({
+      id: 'unparseable',
+      label: 'Unparseable token',
+      value: 0,
+      ok: false,
+      target: '',
+      display: e instanceof Error ? e.message : String(e)
+    })
+  }
+  return metrics
+}
+
+/**
+ * Serialize [r,g,b,a] the way style.css writes colors: lowercase #rrggbb when
+ * opaque, `rgba(r, g, b, a)` when translucent.
+ */
+export function formatColor([r, g, b, a = 1]) {
+  if (a >= 1) return toHex([r, g, b])
+  const c = v => Math.round(Math.min(255, Math.max(0, v)))
+  const alpha = Math.round(Math.min(1, Math.max(0, a)) * 1000) / 1000
+  return `rgba(${c(r)}, ${c(g)}, ${c(b)}, ${alpha})`
+}
+
+const NUM = String.raw`\d+(?:\.\d+)?%?|\.\d+%?`
+/** #hex, white/black, or rgb()/rgba() of plain numbers — nothing parseFloat could half-read. */
+const STRICT_COLOR = new RegExp(
+  String.raw`^(?:white|black|#[0-9a-f]{3,8}|rgba?\(\s*(?:${NUM})(?:\s*[,\s/]\s*(?:${NUM})){2,3}\s*\))$`,
+  'i'
+)
+
+/**
+ * Parse an untrusted color and re-serialize it. Throws unless every channel
+ * is a finite number in range — parseColor alone does not guarantee that
+ * (`rgba(1;},2,3)` parses to NaN rather than throwing).
+ *
+ * This is what makes a save safe: the text spliced into style.css is always
+ * produced HERE, never copied from the request.
+ */
+export function normalizeColor(input) {
+  if (typeof input !== 'string' || input.length > 64 || !STRICT_COLOR.test(input.trim())) {
+    throw new Error(`Not a color: ${String(input).slice(0, 64)}`)
+  }
+  const rgba = parseColor(input)
+  const ok =
+    rgba.slice(0, 3).every(v => Number.isFinite(v) && v >= 0 && v <= 255) &&
+    Number.isFinite(rgba[3]) &&
+    rgba[3] >= 0 &&
+    rgba[3] <= 1
+  if (!ok) throw new Error(`Color out of range: ${input}`)
+  return formatColor(rgba)
+}
+
+/**
+ * Locate `name`'s value inside a block body. Returns offsets relative to the
+ * body, or null. Scans the comment-blanked body so a commented-out
+ * declaration never matches, while offsets stay valid for the original text.
+ */
+function findValue(body, name) {
+  const scan = blankComments(body)
+  const re = new RegExp(`(^|[\\s;{])${name.replace(/[-]/g, '\\-')}\\s*:`, 'g')
+  let match
+  let last = null
+  while ((match = re.exec(scan)) !== null) {
+    let i = re.lastIndex
+    let depth = 0
+    while (i < scan.length) {
+      const c = scan[i]
+      if (c === '(') depth += 1
+      else if (c === ')') depth -= 1
+      else if (c === ';' && depth === 0) break
+      i += 1
+    }
+    let start = re.lastIndex
+    let end = i
+    while (start < end && /\s/.test(scan[start])) start += 1
+    while (end > start && /\s/.test(scan[end - 1])) end -= 1
+    // Last declaration wins, mirroring the cascade.
+    last = { start, end }
+  }
+  return last
+}
+
+/**
+ * Apply `{ [theme]: { [--color-token]: value } }` to style.css text.
+ *
+ * Returns `{ css, changes }`, where `changes` lists only the tokens whose value
+ * actually moved. Throws on an unknown theme or token, a theme whose block is
+ * shared with another theme (an edit would leak), or an invalid color.
+ * Every byte outside the edited values — comments, CRLF line endings,
+ * ordering — is preserved.
+ */
+export function applyTokenEdits(css, edits) {
+  const blocks = readBlocks(css)
+  const splices = []
+  const changes = []
+
+  for (const [theme, tokens] of Object.entries(edits)) {
+    if (!THEMES.includes(theme)) throw new Error(`Unknown theme: ${theme}`)
+    for (const [name, raw] of Object.entries(tokens)) {
+      if (!/^--color-[a-z0-9-]+$/.test(name)) throw new Error(`Not a color token: ${name}`)
+      const value = normalizeColor(raw)
+
+      let target = null
+      for (const block of blocks) {
+        const names = themesForSelector(block.selector)
+        if (!names.includes(theme)) continue
+        const at = findValue(block.body, name)
+        if (at) target = { block, at, names }
+      }
+      if (!target) throw new Error(`${theme} does not declare ${name}`)
+      if (target.names.length > 1) {
+        throw new Error(
+          `${theme}'s ${name} lives in a block shared with ${target.names.join(', ')} — refusing to edit it from one theme`
+        )
+      }
+      const start = target.block.start + target.at.start
+      const end = target.block.start + target.at.end
+      const from = css.slice(start, end)
+      if (from === value) continue
+      splices.push({ start, end, value })
+      changes.push({ theme, token: name, from, to: value })
+    }
+  }
+
+  let out = css
+  for (const s of splices.sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, s.start) + s.value + out.slice(s.end)
+  }
+  return { css: out, changes }
+}