beadcyte 0.4.0

package/src/web/style-audit.mjs

@@ -0,0 +1,346 @@
+// style-audit.mjs — resolves the token layer without a browser, so the
+// distinctness of encoding colours can be asserted in tests.
+//
+// This exists because a named style can override encoding colours, and a
+// style that quietly lands two states on the same colour is a data bug, not
+// a cosmetic one. The terminal style did exactly that: its green accent
+// pulled `future` to within 0.029 OKLab of `shipped`, making closed and open
+// bars indistinguishable. A test is the only thing that catches that class of
+// mistake before a human squints at a chart.
+//
+// The parser is deliberately narrow. It understands only the shapes our own
+// token files use — `light-dark(a, b)`, `oklch(L% C H)` and one level of
+// `var(--x)` — and throws on anything else rather than guessing, so a token
+// written in a form the audit can't check fails loudly instead of silently
+// escaping the guard.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const DEG = Math.PI / 180;
+
+/** Selector blocks, in source order, so later ones override earlier ones. */
+function parseBlocks(css) {
+  const blocks = [];
+  // Strip comments first; they contain braces and colons.
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const re = /([^{}]+)\{([^{}]*)\}/g;
+  let m;
+  while ((m = re.exec(clean))) {
+    const selector = m[1].trim();
+    const decls = {};
+    for (const line of m[2].split(";")) {
+      const i = line.indexOf(":");
+      if (i < 0) continue;
+      const prop = line.slice(0, i).trim();
+      if (!prop.startsWith("--")) continue;
+      decls[prop] = line.slice(i + 1).trim();
+    }
+    if (Object.keys(decls).length) blocks.push({ selector, decls });
+  }
+  return blocks;
+}
+
+/**
+ * Flatten the blocks that apply to a given style, in cascade order: bare
+ * `:root` first, then the style's own block.
+ */
+function declarationsFor(blocks, style) {
+  const out = {};
+  for (const b of blocks) {
+    // Selector LISTS, not exact strings: the token blocks are shared with
+    // the options menu's style previews ( ":root, [data-preview=default]" ),
+    // and an exact-match check silently stopped collecting the base tokens
+    // the moment that hook was added.
+    const parts = b.selector.split(",").map((x) => x.trim());
+    const isBase = parts.includes(":root");
+    const isStyle =
+      style !== "default" &&
+      parts.some((x) => x.includes(`data-style="${style}"`));
+    if (isBase || isStyle) Object.assign(out, b.decls);
+  }
+  return out;
+}
+
+function splitTopLevel(s) {
+  const parts = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of s) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(cur.trim());
+      cur = "";
+    } else cur += ch;
+  }
+  if (cur.trim()) parts.push(cur.trim());
+  return parts;
+}
+
+/** Resolve a declaration to {L, C, H}. Throws on anything unrecognised. */
+function resolve(value, decls, mode, seen = new Set()) {
+  const v = value.trim();
+
+  const varMatch = v.match(/^var\(\s*(--[a-z0-9-]+)\s*\)$/i);
+  if (varMatch) {
+    const name = varMatch[1];
+    if (seen.has(name)) throw new Error(`var cycle at ${name}`);
+    if (!(name in decls)) throw new Error(`unknown token ${name}`);
+    return resolve(decls[name], decls, mode, new Set([...seen, name]));
+  }
+
+  if (v.startsWith("light-dark(")) {
+    const inner = v.slice("light-dark(".length, v.lastIndexOf(")"));
+    const [light, dark] = splitTopLevel(inner);
+    return resolve(mode === "light" ? light : dark, decls, mode, seen);
+  }
+
+  const ok = v.match(
+    /^oklch\(\s*([\d.]+)%\s+([\d.]+)\s+([\d.]+)\s*\)$/i,
+  );
+  if (ok) {
+    return { L: Number(ok[1]) / 100, C: Number(ok[2]), H: Number(ok[3]) };
+  }
+
+  throw new Error(`style-audit cannot resolve: ${v}`);
+}
+
+/**
+ * Perceptual distance in OKLab. LCH is polar, so hue differences at low
+ * chroma barely matter perceptually — converting to Lab before measuring is
+ * what makes "two greys with different hues" correctly read as close.
+ */
+export function distance(a, b) {
+  const ax = a.C * Math.cos(a.H * DEG);
+  const ay = a.C * Math.sin(a.H * DEG);
+  const bx = b.C * Math.cos(b.H * DEG);
+  const by = b.C * Math.sin(b.H * DEG);
+  return Math.hypot(a.L - b.L, ax - bx, ay - by);
+}
+
+/** OKLCH -> linear sRGB -> gamma-encoded sRGB, for compositing. */
+function oklchToSrgb({ L, C, H }) {
+  const a = C * Math.cos(H * DEG);
+  const b = C * Math.sin(H * DEG);
+  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.291485548 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  const lin = [
+    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,
+  ];
+  return lin.map((v) => {
+    const c = v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(Math.max(v, 0), 1 / 2.4) - 0.055;
+    return Math.min(1, Math.max(0, c));
+  });
+}
+
+function srgbToOklab([r, g, b]) {
+  const lin = [r, g, b].map((c) =>
+    c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4,
+  );
+  const [R, G, B] = lin;
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+/**
+ * What the eye actually receives: the token painted at its fill-opacity over
+ * the plot background, composited in sRGB the way the browser does it.
+ *
+ * Comparing raw tokens is not enough. Bar kinds are drawn from 0.35 to 0.95
+ * opacity over a background the style also recolours, so two kinds can sit
+ * far apart as tokens and converge once blended — which is exactly how
+ * "closed and open are both almost the same green" survived a fix that only
+ * separated the tokens.
+ */
+export function composite(fg, bg, alpha) {
+  const f = oklchToSrgb(fg);
+  const b = oklchToSrgb(bg);
+  return srgbToOklab(f.map((c, i) => c * alpha + b[i] * (1 - alpha)));
+}
+
+/** Distance between two already-Oklab colours. */
+export function labDistance(a, b) {
+  return Math.hypot(a.L - b.L, a.a - b.a, a.b - b.b);
+}
+
+// ── colour-vision deficiency ──────────────────────────────────────────────
+//
+// Machado, Oliveira & Fernandes (2009), severity 1.0: the three dichromacies
+// as linear-sRGB matrices. The audit's OKLab floor measures what full colour
+// vision receives; these measure what a dichromat does, and a pair told apart
+// by hue alone at one lightness passes the first and collapses under the
+// second — which is exactly how the default palette shipped with in-progress
+// and future 0.3 apart for a deuteranope (bp-67g.26).
+const CVD_MATRICES = {
+  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 CVD_KINDS = Object.freeze(Object.keys(CVD_MATRICES));
+
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const linearToSrgb = (v) =>
+  Math.min(1, Math.max(0, v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(Math.max(v, 0), 1 / 2.4) - 0.055));
+
+/** What a dichromat of the given kind sees for an sRGB colour, as sRGB. */
+export function simulateCvd(srgb, kind) {
+  const m = CVD_MATRICES[kind];
+  if (!m) throw new Error(`unknown CVD kind ${kind}`);
+  const lin = srgb.map(srgbToLinear);
+  return [0, 1, 2].map((i) => linearToSrgb(m[i * 3] * lin[0] + m[i * 3 + 1] * lin[1] + m[i * 3 + 2] * lin[2]));
+}
+
+/** A token painted at alpha over a background, as the sRGB the eye receives. */
+export function paintedSrgb(fg, bg, alpha) {
+  const f = oklchToSrgb(fg);
+  const b = oklchToSrgb(bg);
+  return f.map((c, i) => c * alpha + b[i] * (1 - alpha));
+}
+
+/** Separation of two sRGB colours under a simulated deficiency: deltaE in OKLab x100. */
+export function cvdDistanceSrgb(a, b, kind) {
+  return labDistance(srgbToOklab(simulateCvd(a, kind)), srgbToOklab(simulateCvd(b, kind))) * 100;
+}
+
+/** The same for two OKLCH tokens. */
+export function cvdDistance(a, b, kind) {
+  return cvdDistanceSrgb(oklchToSrgb(a), oklchToSrgb(b), kind);
+}
+
+/**
+ * Reads the .bar.kind-* rules straight out of the Gantt component, so the
+ * audit measures the opacities the chart actually uses. A hand-copied table
+ * would silently drift from the stylesheet, and a guard that tests stale
+ * numbers is worse than no guard.
+ */
+export function readBarKinds(vuePath) {
+  const src = readFileSync(vuePath, "utf8");
+  const re =
+    /\.bar\.kind-([A-Za-z]+)\s*\{[^}]*?fill:\s*var\((--[a-z0-9-]+)\)[^}]*?\}/g;
+  const kinds = [];
+  let m;
+  while ((m = re.exec(src))) {
+    const [block, name, token] = [m[0], m[1], m[2]];
+    const alphaMatch = block.match(/fill-opacity:\s*([\d.]+)/);
+    // Bars inherit .bar's own fill-opacity when their rule omits one.
+    const base = src.match(/\.beads-gantt \.bar\s*\{[^}]*?fill-opacity:\s*([\d.]+)/);
+    kinds.push({
+      name,
+      token,
+      alpha: Number(alphaMatch ? alphaMatch[1] : base ? base[1] : 1),
+      // A kind drawn through the hatch mask is told apart by TEXTURE, not
+      // hue (bp-6cg's wait segments): the painted-distance checks compare
+      // only unhatched kinds, and a separate check holds hatched kinds to
+      // the texture contract.
+      hatched: /mask:\s*url\(#beads-gantt-synthetic-mask\)/.test(block),
+    });
+  }
+  if (!kinds.length) throw new Error("no .bar.kind-* rules found — parser stale");
+  return kinds;
+}
+
+/**
+ * How a synthetic-assignee bar is drawn, read from the component the way
+ * readBarKinds is: the `.bar.synthetic` rule's declarations, plus the hatch
+ * geometry and bar height the template's mask is built from.
+ *
+ * Two things could quietly defeat the hatch (bp-67g.49). A `fill` or
+ * `fill-opacity` on `.bar.synthetic` would make synthetic a colour state the
+ * painted-kinds check never sees, because readBarKinds reads only the
+ * `.bar.kind-*` rules. And stripes finer than the bar is tall stop being
+ * stripes: at a pitch the eye cannot resolve, a hatched bar is a paler bar —
+ * the third opacity level the texture exists to avoid.
+ */
+export function readSyntheticTreatment(vuePath) {
+  const src = readFileSync(vuePath, "utf8");
+  const rule = src.match(/\.beads-gantt \.bar\.synthetic\s*\{([^}]*)\}/);
+  if (!rule) throw new Error("no .bar.synthetic rule found — parser stale");
+  const declarations = {};
+  for (const line of rule[1].split(";")) {
+    const i = line.indexOf(":");
+    if (i < 0) continue;
+    declarations[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  const num = (re, what) => {
+    const m = src.match(re);
+    if (!m) throw new Error(`${what} not found in ${vuePath} — parser stale`);
+    return Number(m[1]);
+  };
+  const rowH = num(/const ROW_H = (\d+);/, "ROW_H");
+  const barInset = num(/const BAR_H = ROW_H - (\d+);/, "BAR_H");
+  return {
+    declarations,
+    pitch: num(/const HATCH_PITCH = (\d+(?:\.\d+)?);/, "HATCH_PITCH"),
+    stripe: num(/const HATCH_STRIPE = (\d+(?:\.\d+)?);/, "HATCH_STRIPE"),
+    barHeight: rowH - barInset,
+  };
+}
+
+/**
+ * The stylesheets the app actually loads, in load order, read out of main.ts
+ * rather than listed by hand. A style declared in a file the audit does not
+ * read is invisible to every check in the suite while the suite stays green;
+ * deriving the list from the import graph closes that hole (bp-jak).
+ */
+export function readStyleSheets(mainTsPath) {
+  const src = readFileSync(mainTsPath, "utf8");
+  const dir = dirname(mainTsPath);
+  const re = /^import\s+"(\.\/[^"]+\.css)";/gm;
+  const out = [];
+  let m;
+  while ((m = re.exec(src))) out.push(join(dir, m[1]));
+  if (!out.length) throw new Error(`no css imports found in ${mainTsPath} — parser stale`);
+  return out;
+}
+
+/**
+ * The colour token each variant of a chip component paints its text with,
+ * read from the component the way readBarKinds reads bar fills: every rule
+ * whose selector matches `selectorRe` and declares `color: var(--c-…)`.
+ * Returns [{ variant, token }] in source order, so an audit group can be
+ * built from what the chip renders rather than from a list that drifts.
+ */
+export function readChipInks(vuePath, selectorRe) {
+  const src = readFileSync(vuePath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+  const out = [];
+  const re = new RegExp(`(${selectorRe.source})\\s*\\{([^}]*)\\}`, "g");
+  let m;
+  while ((m = re.exec(src))) {
+    const color = m[m.length - 1].match(/(?:^|;)\s*color:\s*var\((--[a-z0-9-]+)\)/);
+    if (color) out.push({ variant: m[1].trim(), token: color[1] });
+  }
+  if (!out.length) throw new Error(`no chip ink rules matched in ${vuePath} — parser stale`);
+  return out;
+}
+
+export function loadTokens(paths) {
+  const blocks = paths.flatMap((p) => parseBlocks(readFileSync(p, "utf8")));
+  return {
+    /** Resolved value of one token under a style + mode. */
+    get(token, style, mode) {
+      const decls = declarationsFor(blocks, style);
+      if (!(token in decls)) throw new Error(`unknown token ${token}`);
+      return resolve(decls[token], decls, mode);
+    },
+    styles() {
+      const found = new Set(["default"]);
+      for (const b of blocks) {
+        const m = b.selector.match(/data-style="([a-z0-9-]+)"/i);
+        if (m) found.add(m[1]);
+      }
+      return [...found];
+    },
+  };
+}

package/src/web/styles-alt.css

@@ -0,0 +1,111 @@
+/* styles-alt.css — alternate palette families.
+ *
+ * Loaded AFTER tokens.css so `:root[data-style=...]` reliably beats bare
+ * `:root` — a pseudo-class plus an attribute out-specifies a pseudo-class
+ * alone, but only wins the tie if it comes later.
+ *
+ * Each family redefines the same tokens every component already reads, so a
+ * whole-app reskin costs no per-component changes. Each supplies its own
+ * light-dark() pair, so every family respects the light/dark toggle
+ * independently rather than being dark-only.
+ *
+ * These two are beadcyte's own alternatives; the ports of other editors'
+ * palettes live in styles-ported.css. They also prove the layer is real: if
+ * the switcher only ever showed the default, nothing would catch it being
+ * accidentally coupled to the default's values.
+ *
+ * A style MAY restyle the chart's encoding colours, but only by declaring
+ * the whole set deliberately — never by side effect. That distinction is the
+ * whole lesson of the terminal bug: it overrode --c-accent alone, which
+ * `future` happened to alias, pulling future to within 0.029 OKLab of
+ * shipped and making closed and open bars indistinguishable.
+ *
+ * style-audit.test.mjs enforces it: every pair of colours inside an encoding
+ * group must stay at least MIN_DISTINCT apart in every style and mode. A
+ * style that collapses two states fails the suite instead of shipping.
+ *
+ * Each block also matches [data-preview="<name>"], so the options menu can
+ * render a swatch in a family's colours while a different family is active.
+ * Custom properties inherit, so declaring them on the swatch container is
+ * enough — and sharing the selector means a preview can never drift from
+ * the style it claims to show.
+ */
+
+:root[data-style="synthwave"],
+[data-preview="synthwave"] {
+  /* Encoding set, declared in full. Neon hues, still mutually separated:
+     teal done, violet in flight, hot pink ahead, muted mauve for closed
+     without a ship, and a red today rule that reads as a rule and not as
+     another bar. */
+  --c-shipped: light-dark(oklch(54.6% 0.094 190.0), oklch(79.9% 0.138 190.0));
+  --c-in-progress: light-dark(oklch(44.6% 0.200 275.0), oklch(70.0% 0.158 275.0));
+  --c-future: light-dark(oklch(61.2% 0.240 343.0), oklch(61.7% 0.250 343.0));
+  --c-backlog: light-dark(oklch(61.2% 0.240 343.0), oklch(61.7% 0.250 343.0));
+  --c-closed-noship: light-dark(oklch(37.5% 0.045 310.0), oklch(70.9% 0.045 310.0));
+  /* Yellow: distinct from teal shipped, violet review and pink future,
+     and reads as a live cursor rather than an error. */
+  --c-today: light-dark(oklch(62.0% 0.128 95.0), oklch(84.9% 0.174 95.0));
+
+  --c-bg: light-dark(oklch(96% 0.020 305), oklch(15.5% 0.062 296));
+  --c-panel: light-dark(oklch(92.5% 0.034 305), oklch(20.5% 0.070 300));
+  --c-panel-2: light-dark(oklch(88.5% 0.046 305), oklch(25.0% 0.082 298));
+  --c-border: light-dark(oklch(83% 0.055 305), oklch(33.5% 0.105 306));
+  --c-border-strong: light-dark(oklch(70% 0.085 305), oklch(45.0% 0.140 306));
+  --c-text: light-dark(oklch(28% 0.090 305), oklch(95% 0.031 304));
+  --c-dim: light-dark(oklch(48% 0.070 305), oklch(72% 0.110 311));
+  --c-dim-bright: light-dark(oklch(38% 0.080 305), oklch(85% 0.070 308));
+
+  /* Economics phases, in the family's own hues. Still mutually separated —
+     style-audit.test.mjs checks these per style, same as the bar kinds. */
+  --c-phase-worked: light-dark(oklch(46.5% 0.082 190.0), oklch(78.4% 0.136 190.0));
+  --c-phase-review: light-dark(oklch(54.2% 0.200 275.0), oklch(69.9% 0.158 275.0));
+  --c-phase-waiting: light-dark(oklch(66.0% 0.240 343.0), oklch(68.9% 0.250 343.0));
+  --c-phase-other: light-dark(oklch(74.0% 0.030 310.0), oklch(45.0% 0.060 310.0));
+
+  --c-accent: light-dark(oklch(52% 0.240 343), oklch(68.4% 0.270 343));
+  --c-epic: light-dark(oklch(55% 0.220 320), oklch(72% 0.230 320));
+}
+
+:root[data-style="terminal"],
+[data-preview="terminal"] {
+  /* Encoding set, declared in full. A phosphor palette, but green alone
+     cannot carry five states, so the hues fan out: green done, amber in
+     flight, cyan ahead, dim green-grey for closed without a ship, red rule
+     for today. */
+  --c-shipped: light-dark(oklch(36.0% 0.118 145.0), oklch(89.5% 0.190 145.0));
+  --c-in-progress: light-dark(oklch(60.0% 0.124 80.0), oklch(78.3% 0.150 80.0));
+  --c-future: light-dark(oklch(43.4% 0.074 200.0), oklch(76.0% 0.120 200.0));
+  --c-backlog: light-dark(oklch(43.4% 0.074 200.0), oklch(76.0% 0.120 200.0));
+  --c-closed-noship: light-dark(oklch(57.9% 0.030 150.0), oklch(63.8% 0.035 150.0));
+  /* Magenta: the one hue a phosphor palette of green, amber and cyan
+     leaves free, so the now-rule never reads as another bar. */
+  --c-today: light-dark(oklch(52.0% 0.228 340.0), oklch(66.5% 0.260 340.0));
+
+  --c-bg: light-dark(oklch(97% 0.012 135), oklch(14% 0.028 150));
+  --c-panel: light-dark(oklch(94% 0.020 135), oklch(18% 0.036 150));
+  --c-panel-2: light-dark(oklch(90% 0.028 135), oklch(22% 0.044 150));
+  --c-border: light-dark(oklch(84% 0.040 135), oklch(30% 0.058 150));
+  --c-border-strong: light-dark(oklch(72% 0.060 135), oklch(42% 0.080 150));
+  --c-text: light-dark(oklch(30% 0.090 145), oklch(90% 0.130 145));
+  --c-dim: light-dark(oklch(50% 0.080 145), oklch(65% 0.100 145));
+  --c-dim-bright: light-dark(oklch(40% 0.090 145), oklch(78% 0.120 145));
+
+  /* Economics phases in phosphor. Waiting is ~95% of a typical bar, so it
+     carries the family's identity: dim idle green, not the amber the default
+     uses — otherwise the whole bar looks unthemed however the two thin
+     segments beside it are coloured. Worked is the bright active green and
+     review the amber accent a real terminal would use for attention. */
+  --c-phase-waiting: light-dark(oklch(66.0% 0.110 150.0), oklch(52.1% 0.110 150.0));
+  --c-phase-worked: light-dark(oklch(48.0% 0.152 145.0), oklch(88.0% 0.200 145.0));
+  --c-phase-review: light-dark(oklch(62.1% 0.130 80.0), oklch(79.9% 0.150 80.0));
+  --c-phase-other: light-dark(oklch(74.0% 0.020 150.0), oklch(40.0% 0.040 150.0));
+
+  --c-accent: light-dark(oklch(48% 0.150 145), oklch(78% 0.180 145));
+  /* Cyan-teal, held clear of the dim inks it shares the label column and the
+     type chips with; the previous teal sat under the audit floor against
+     them in both modes (bp-jak). */
+  --c-epic: light-dark(oklch(35.0% 0.060 200.0), oklch(80.5% 0.140 182.0));
+
+  --font-body: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas,
+    monospace;
+}