@stigmer/theme 3.1.4 → 3.1.5

package/src/contract/__tests__/resolve.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { parseThemeCss } from "../parse.js";
+import { presetLightLeaksIntoDark, resolveTokens } from "../resolve.js";
+
+const DEFAULTS = parseThemeCss(`
+:root {
+  --stgm-background: light-default;
+  --stgm-foreground: light-default;
+  --stgm-primary: light-default;
+}
+[data-stgm-color-mode="dark"] {
+  --stgm-background: dark-default;
+  --stgm-primary: dark-default;
+}
+`);
+
+const PRESET = parseThemeCss(`
+.stgm-theme-x {
+  --stgm-background: light-preset;
+  --stgm-primary: light-preset;
+}
+[data-stgm-color-mode="dark"] .stgm-theme-x,
+.stgm-theme-x[data-stgm-color-mode="dark"] {
+  --stgm-background: dark-preset;
+}
+`);
+
+describe("resolveTokens", () => {
+  it("light mode without preset uses :root values", () => {
+    const resolved = resolveTokens(DEFAULTS, undefined, "light");
+    expect(resolved.get("--stgm-background")).toMatchObject({
+      value: "light-default",
+      source: "default-light",
+    });
+  });
+
+  it("dark mode without preset overlays the dark block, falling back to light", () => {
+    const resolved = resolveTokens(DEFAULTS, undefined, "dark");
+    expect(resolved.get("--stgm-background")?.value).toBe("dark-default");
+    // --stgm-foreground has no dark declaration: inherits the light value.
+    expect(resolved.get("--stgm-foreground")).toMatchObject({
+      value: "light-default",
+      source: "default-light",
+    });
+  });
+
+  it("light mode with preset prefers preset-light over defaults", () => {
+    const resolved = resolveTokens(DEFAULTS, PRESET, "light");
+    expect(resolved.get("--stgm-background")?.value).toBe("light-preset");
+    expect(resolved.get("--stgm-foreground")?.value).toBe("light-default");
+  });
+
+  it("dark mode with preset resolves preset-dark ?? preset-light ?? default-dark ?? default-light", () => {
+    const resolved = resolveTokens(DEFAULTS, PRESET, "dark");
+    // Defined in the preset dark block: preset-dark wins.
+    expect(resolved.get("--stgm-background")).toMatchObject({
+      value: "dark-preset",
+      source: "preset-dark",
+    });
+    // Defined in preset light only: the preset-light value leaks into dark
+    // (higher cascade priority than the default dark block).
+    expect(resolved.get("--stgm-primary")).toMatchObject({
+      value: "light-preset",
+      source: "preset-light",
+    });
+    // Untouched by the preset: default dark... which doesn't exist for
+    // foreground, so default light.
+    expect(resolved.get("--stgm-foreground")?.value).toBe("light-default");
+  });
+});
+
+describe("presetLightLeaksIntoDark", () => {
+  it("flags tokens the preset defines light-only while defaults have a dark value", () => {
+    expect(presetLightLeaksIntoDark(DEFAULTS, PRESET)).toEqual(["--stgm-primary"]);
+  });
+
+  it("does not flag tokens with no default dark value (nothing to leak over)", () => {
+    const preset = parseThemeCss(`
+.stgm-theme-y {
+  --stgm-foreground: light-preset;
+}
+`);
+    expect(presetLightLeaksIntoDark(DEFAULTS, preset)).toEqual([]);
+  });
+});

package/src/contract/audit.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseThemeCss, type ThemeFileTokens } from "./parse.js";
+import {
+  presetLightLeaksIntoDark,
+  resolveTokens,
+  type ColorMode,
+} from "./resolve.js";
+import { contrastRatio, lightnessDelta } from "./color.js";
+import {
+  CONTRAST_PAIRS,
+  SURFACE_PAIRS,
+  SUPPORTING_TEXT_MIN_RATIO,
+  SURFACE_MIN_DELTA_L,
+  TEXT_MIN_RATIO,
+  type ContrastPair,
+} from "./pairs.js";
+
+/**
+ * Contrast-audit runner: evaluates the declared pair contract against every
+ * preset × color mode, resolving tokens through the real cascade.
+ *
+ * Consumed by the vitest suite (assertions) and by
+ * `scripts/contrast-report.ts` (the full human-readable matrix).
+ */
+
+const SRC_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const PRESET_IDS = [
+  "default",
+  "corporate",
+  "startup",
+  "friendly",
+  "fintech",
+  "monochrome",
+] as const;
+
+export type PresetId = (typeof PRESET_IDS)[number];
+export const COLOR_MODES: readonly ColorMode[] = ["light", "dark"];
+
+export interface PairResult {
+  readonly pair: ContrastPair;
+  readonly preset: PresetId;
+  readonly mode: ColorMode;
+  /** WCAG ratio for text pairs; OKLCH lightness delta for surface pairs. */
+  readonly measured: number;
+  readonly threshold: number;
+  readonly passes: boolean;
+  /** False when the pair is measured in this mode but not gated (report-only). */
+  readonly enforced: boolean;
+  readonly foregroundValue: string;
+  readonly backgroundValue: string;
+}
+
+export interface PresetLeak {
+  readonly preset: PresetId;
+  readonly tokens: readonly string[];
+}
+
+export interface AuditReport {
+  readonly results: readonly PairResult[];
+  /** Preset tokens whose light value leaks into dark mode (cascade defect). */
+  readonly leaks: readonly PresetLeak[];
+}
+
+function loadDefaults(): ThemeFileTokens {
+  return parseThemeCss(readFileSync(join(SRC_DIR, "tokens.css"), "utf-8"));
+}
+
+function loadPreset(id: PresetId): ThemeFileTokens | undefined {
+  if (id === "default") return undefined;
+  return parseThemeCss(
+    readFileSync(join(SRC_DIR, "presets", `${id}.css`), "utf-8"),
+  );
+}
+
+function thresholdFor(pair: ContrastPair): number {
+  switch (pair.kind) {
+    case "text":
+      return TEXT_MIN_RATIO;
+    case "supporting":
+      return SUPPORTING_TEXT_MIN_RATIO;
+    case "surface":
+      return SURFACE_MIN_DELTA_L;
+  }
+}
+
+/** Evaluate the full declared contract. */
+export function runContrastAudit(): AuditReport {
+  const defaults = loadDefaults();
+  const results: PairResult[] = [];
+  const leaks: PresetLeak[] = [];
+
+  for (const preset of PRESET_IDS) {
+    const presetTokens = loadPreset(preset);
+    if (presetTokens) {
+      const leaked = presetLightLeaksIntoDark(defaults, presetTokens);
+      if (leaked.length > 0) leaks.push({ preset, tokens: leaked });
+    }
+
+    for (const mode of COLOR_MODES) {
+      const resolved = resolveTokens(defaults, presetTokens, mode);
+      for (const pair of [...CONTRAST_PAIRS, ...SURFACE_PAIRS]) {
+        const foreground = resolved.get(pair.foreground);
+        const background = resolved.get(pair.background);
+        if (!foreground || !background) {
+          throw new Error(
+            `Contract pair references unknown token: ${pair.foreground} / ${pair.background}`,
+          );
+        }
+        const threshold = thresholdFor(pair);
+        const measured =
+          pair.kind === "surface"
+            ? lightnessDelta(foreground.value, background.value)
+            : contrastRatio(foreground.value, background.value);
+        results.push({
+          pair,
+          preset,
+          mode,
+          measured,
+          threshold,
+          passes: measured >= threshold,
+          enforced: pair.enforcedModes?.includes(mode) ?? true,
+          foregroundValue: foreground.value,
+          backgroundValue: background.value,
+        });
+      }
+    }
+  }
+
+  return { results, leaks };
+}
+
+/** Stable identity for a result, used by the exemption list and reporting. */
+export function resultId(result: PairResult): string {
+  return `${result.preset}/${result.mode}: ${result.pair.foreground} on ${result.pair.background}`;
+}

package/src/contract/color.ts

@@ -0,0 +1,79 @@
+import { converter, parse, wcagContrast, type Rgb } from "culori";
+
+/**
+ * Color math for the token contrast audit, backed by culori.
+ *
+ * All comparisons happen on *composited* colors: a translucent token (e.g.
+ * the dark-mode `--stgm-border: oklch(1 0 0 / 14%)`) is first blended over
+ * its surface the way a browser paints it, so the audit measures what the
+ * user actually sees.
+ */
+
+const toRgb = converter("rgb");
+const toOklch = converter("oklch");
+
+/** Parse a CSS color token value; throws on non-color values. */
+export function parseColor(value: string): Rgb {
+  const parsed = parse(value);
+  if (!parsed) {
+    throw new Error(`Not a parseable CSS color: "${value}"`);
+  }
+  return toRgb(parsed);
+}
+
+/** True when the token value is a color (vs. a length, shadow, font, ...). */
+export function isColorValue(value: string): boolean {
+  return parse(value) !== undefined;
+}
+
+/**
+ * Composite a possibly-translucent foreground over an opaque backdrop
+ * (simple source-over in sRGB, matching browser compositing).
+ */
+export function compositeOver(foreground: Rgb, backdrop: Rgb): Rgb {
+  const alpha = foreground.alpha ?? 1;
+  if (alpha >= 1) return foreground;
+  return {
+    mode: "rgb",
+    r: foreground.r * alpha + backdrop.r * (1 - alpha),
+    g: foreground.g * alpha + backdrop.g * (1 - alpha),
+    b: foreground.b * alpha + backdrop.b * (1 - alpha),
+    alpha: 1,
+  };
+}
+
+/**
+ * WCAG 2.1 contrast ratio between two token values.
+ *
+ * A translucent *background* (e.g. the dark-mode `--stgm-border`) must be
+ * composited over the surface it actually paints on — pass that surface as
+ * `backdropValue`. The foreground is then composited over the resolved
+ * background. Omitting `backdropValue` for a translucent background is a
+ * caller error and throws, so no pair silently measures against nothing.
+ */
+export function contrastRatio(
+  foregroundValue: string,
+  backgroundValue: string,
+  backdropValue?: string,
+): number {
+  const rawBackground = parseColor(backgroundValue);
+  if ((rawBackground.alpha ?? 1) < 1 && backdropValue === undefined) {
+    throw new Error(
+      `Background "${backgroundValue}" is translucent — pass the surface it renders over as backdropValue`,
+    );
+  }
+  const background = backdropValue
+    ? compositeOver(rawBackground, parseColor(backdropValue))
+    : rawBackground;
+  const foreground = compositeOver(parseColor(foregroundValue), background);
+  return wcagContrast(foreground, background);
+}
+
+/**
+ * Perceptual lightness difference (OKLCH L, 0..1) between two opaque token
+ * values. Used for surface-separation checks where WCAG has no defined
+ * threshold.
+ */
+export function lightnessDelta(valueA: string, valueB: string): number {
+  return Math.abs(toOklch(parseColor(valueA)).l - toOklch(parseColor(valueB)).l);
+}

package/src/contract/pairs.ts

@@ -0,0 +1,169 @@
+/**
+ * The declared contrast contract: which token pairs must remain readable,
+ * and at what threshold.
+ *
+ * Every pair is grounded in a real rendering in `@stigmer/react` (the
+ * `usage` field cites it). The audit resolves both tokens through the real
+ * cascade for every preset × color mode and measures the WCAG 2.1 ratio —
+ * this file is the single place where a new "text X renders on surface Y"
+ * relationship gets registered.
+ *
+ * Thresholds:
+ * - `text` pairs use WCAG 2.1 AA for normal-size text (4.5:1). SDK chrome
+ *   text is predominantly `text-xs`/`text-sm`, so the large-text relaxation
+ *   never applies.
+ * - `supporting` pairs are deliberately de-emphasized tokens (the `-subtle`
+ *   / `-faint` foreground variants). They are held to the AA large-text /
+ *   non-text floor (3:1) — below that, "de-emphasized" becomes "invisible".
+ * - `surface` pairs have no WCAG-defined threshold. They are measured as
+ *   OKLCH lightness delta and asserted against SURFACE_MIN_DELTA_L.
+ */
+
+export const TEXT_MIN_RATIO = 4.5;
+export const SUPPORTING_TEXT_MIN_RATIO = 3.0;
+
+/**
+ * Minimum OKLCH lightness separation for adjacent surfaces that carry no
+ * border (e.g. the user message bubble on the thread background). OKLCH L
+ * is perceptually uniform, so one number works for both modes; 0.045 keeps
+ * the current light-mode card/page relationship comfortably legal while
+ * flagging fills that melt into the page.
+ */
+export const SURFACE_MIN_DELTA_L = 0.045;
+
+export type PairKind = "text" | "supporting" | "surface";
+
+export interface ContrastPair {
+  /** Foreground token (text or fill being read). */
+  readonly foreground: string;
+  /** Background token it renders on. */
+  readonly background: string;
+  readonly kind: PairKind;
+  /** Where in the SDK this pair is actually rendered. */
+  readonly usage: string;
+  /**
+   * Modes the threshold is enforced in (measured and reported in all modes
+   * regardless). Surface pairs enforce dark only: in light mode, ambient
+   * light and shadows carry small fill deltas, while dark-mode display
+   * flare compresses them — the failure mode reported in issue #187.
+   */
+  readonly enforcedModes?: readonly ("light" | "dark")[];
+}
+
+const pair = (
+  foreground: string,
+  background: string,
+  kind: PairKind,
+  usage: string,
+  enforcedModes?: readonly ("light" | "dark")[],
+): ContrastPair => ({
+  foreground,
+  background,
+  kind,
+  usage,
+  ...(enforcedModes !== undefined && { enforcedModes }),
+});
+
+const STATUSES = [
+  "ready",
+  "running",
+  "pending",
+  "degraded",
+  "failed",
+  "disabled",
+  "draft",
+] as const;
+
+const SYNTAX = [
+  "keyword",
+  "property",
+  "string",
+  "number",
+  "bool",
+  "atom",
+  "meta",
+  "tag",
+] as const;
+
+export const CONTRAST_PAIRS: readonly ContrastPair[] = [
+  // ── Core text on core surfaces ──────────────────────────────────────
+  pair("--stgm-foreground", "--stgm-background", "text", "body text everywhere"),
+  pair("--stgm-card-foreground", "--stgm-card", "text", "card bodies (ApprovalCard, TodoCard, plan cards)"),
+  pair("--stgm-popover-foreground", "--stgm-popover", "text", "dropdowns, dialogs, menus"),
+  pair("--stgm-primary-foreground", "--stgm-primary", "text", "primary buttons (composer send, approval Approve)"),
+  pair("--stgm-secondary-foreground", "--stgm-secondary", "text", "secondary buttons"),
+  pair("--stgm-accent-foreground", "--stgm-accent", "text", "hovered menu items, selected rows"),
+  pair("--stgm-muted-foreground", "--stgm-muted", "text", "supporting text in muted panels (ExecutionErrorNotice interrupted state)"),
+  pair("--stgm-muted-foreground", "--stgm-background", "text", "Thinking indicator, timestamps, captions (SetupProgress, ThinkingMessage)"),
+  pair("--stgm-muted-foreground", "--stgm-card", "text", "supporting text inside cards"),
+  pair("--stgm-foreground", "--stgm-muted-subtle", "text", "user message bubble text (MessageEntry HumanMessage), markdown table headers"),
+  pair("--stgm-muted-foreground", "--stgm-muted-subtle", "text", "secondary affordances inside the user bubble"),
+
+  // ── Semantic text ───────────────────────────────────────────────────
+  pair("--stgm-destructive-foreground", "--stgm-destructive", "text", "destructive buttons (approval Deny)"),
+  pair("--stgm-destructive", "--stgm-destructive-subtle", "text", "error notices (ExecutionErrorNotice failure state)"),
+  pair("--stgm-destructive", "--stgm-background", "text", "inline error text (FailedUserMessage)"),
+  pair("--stgm-success-foreground", "--stgm-success", "text", "success badges"),
+  pair("--stgm-warning-foreground", "--stgm-warning", "text", "warning badges"),
+  pair("--stgm-info-foreground", "--stgm-info", "text", "info badges"),
+
+  // ── Sidebar context ─────────────────────────────────────────────────
+  pair("--stgm-sidebar-foreground", "--stgm-sidebar", "text", "sidebar navigation labels"),
+  pair("--stgm-sidebar-muted-foreground", "--stgm-sidebar", "text", "sidebar section headers, secondary labels"),
+  pair("--stgm-sidebar-primary-foreground", "--stgm-sidebar-primary", "text", "sidebar primary actions"),
+  pair("--stgm-sidebar-accent-foreground", "--stgm-sidebar-accent", "text", "sidebar active/hovered items"),
+
+  // ── Status badges (StatusBadge: status text on its subtle fill) ─────
+  ...STATUSES.map((status) =>
+    pair(
+      `--stgm-status-${status}`,
+      `--stgm-status-${status}-subtle`,
+      "text",
+      `StatusBadge "${status}" pill`,
+    ),
+  ),
+  ...STATUSES.map((status) =>
+    pair(
+      `--stgm-status-${status}-foreground`,
+      `--stgm-status-${status}`,
+      "text",
+      `solid "${status}" status fill with foreground text`,
+    ),
+  ),
+
+  // ── Diff viewer ─────────────────────────────────────────────────────
+  pair("--stgm-diff-added-fg", "--stgm-diff-added-bg", "text", "diff added lines"),
+  pair("--stgm-diff-removed-fg", "--stgm-diff-removed-bg", "text", "diff removed lines"),
+  pair("--stgm-diff-hunk-header-fg", "--stgm-diff-hunk-header-bg", "text", "diff hunk headers"),
+
+  // ── Syntax highlighting (code blocks render on bg-muted) ────────────
+  ...SYNTAX.map((token) =>
+    pair(
+      `--stgm-syntax-${token}`,
+      "--stgm-muted",
+      "text",
+      `highlighted code "${token}" tokens (markdown-components pre)`,
+    ),
+  ),
+  // Comments are deliberately de-emphasized but must stay readable.
+  pair("--stgm-syntax-comment", "--stgm-muted", "supporting", "highlighted code comments"),
+
+  // ── Deliberately de-emphasized text (readability floor, not AA) ─────
+  pair("--stgm-muted-foreground-subtle", "--stgm-background", "supporting", "tertiary captions"),
+  pair("--stgm-muted-foreground-faint", "--stgm-background", "supporting", "faintest hints (placeholder-level text)"),
+];
+
+/**
+ * Adjacent-surface pairs: fills that must visibly separate from the surface
+ * behind them *without* a border — only genuinely borderless fills belong
+ * here. Cards, popovers, and buttons separate via border + shadow, so their
+ * fill delta is intentionally not part of the contract.
+ *
+ * Enforced in dark mode only (see ContrastPair.enforcedModes): the light
+ * values ship far below the threshold by design and read fine under ambient
+ * light; the dark values are where fills melt into the page (issue #187).
+ */
+export const SURFACE_PAIRS: readonly ContrastPair[] = [
+  pair("--stgm-muted-subtle", "--stgm-background", "surface", "user message bubble on thread background (borderless)", ["dark"]),
+  pair("--stgm-muted", "--stgm-background", "surface", "code blocks, muted panels on the page (borderless)", ["dark"]),
+];

package/src/contract/parse.ts

@@ -0,0 +1,131 @@
+/**
+ * Parser for the `--stgm-*` token contract in this package's CSS files.
+ *
+ * The theme CSS is machine-formatted (one declaration per line, flat
+ * top-level blocks, no nesting), so a deliberate line-oriented parser is
+ * sufficient and keeps this package dependency-free. It understands the two
+ * kinds of files we ship:
+ *
+ * - `tokens.css` — defaults: `:root { light }` +
+ *   `[data-stgm-color-mode="dark"] { dark }`
+ * - `presets/*.css` — overrides: `.stgm-theme-<id> { light }` +
+ *   `[data-stgm-color-mode="dark"] .stgm-theme-<id>, ... { dark }`
+ *
+ * A block is classified `dark` when its selector mentions
+ * `data-stgm-color-mode="dark"`, otherwise `light` — the same rule for both
+ * file kinds.
+ *
+ * The parser also captures documentation structure used by the token-docs
+ * generator:
+ *
+ * - `@group` comments (`/* @group Core colors — ... *\/`) start a named
+ *   group; every following declaration belongs to it until the next header.
+ * - A plain comment line immediately preceding a declaration is that
+ *   token's purpose description.
+ */
+
+/** One `--stgm-*` custom property declaration with its documentation. */
+export interface TokenDeclaration {
+  /** Full custom property name, e.g. `--stgm-background`. */
+  readonly name: string;
+  /** Raw CSS value, e.g. `oklch(0.98 0 0)`. */
+  readonly value: string;
+  /** Purpose description from the comment line preceding the declaration. */
+  readonly description?: string;
+  /** Group name from the most recent `@group` header, e.g. `Core colors`. */
+  readonly group?: string;
+}
+
+/** All `--stgm-*` declarations of one CSS file, split by color mode. */
+export interface ThemeFileTokens {
+  readonly light: ReadonlyMap<string, TokenDeclaration>;
+  readonly dark: ReadonlyMap<string, TokenDeclaration>;
+}
+
+const TOKEN_DECLARATION = /^(--stgm-[\w-]+)\s*:\s*(.+?);\s*$/;
+const GROUP_HEADER = /^\/\*\s*@group\s+(.+?)\s*(?:\*\/)?$/;
+
+/**
+ * Parse a theme CSS file into light/dark token maps.
+ *
+ * Later blocks of the same mode overwrite earlier ones, mirroring CSS
+ * source-order behavior for equal-specificity selectors.
+ */
+export function parseThemeCss(css: string): ThemeFileTokens {
+  const light = new Map<string, TokenDeclaration>();
+  const dark = new Map<string, TokenDeclaration>();
+
+  let insideBlock = false;
+  let blockIsDark = false;
+  let selectorBuffer = "";
+  let currentGroup: string | undefined;
+  let pendingDescription: string | undefined;
+  let insideMultilineComment = false;
+
+  for (const rawLine of css.split("\n")) {
+    const line = rawLine.trim();
+
+    if (insideMultilineComment) {
+      if (line.includes("*/")) insideMultilineComment = false;
+      continue;
+    }
+
+    if (!insideBlock) {
+      // Accumulate selector text until the opening brace; a selector list
+      // (the preset dark dual selector) can span multiple lines.
+      if (line.length === 0) continue;
+      if (line.startsWith("/*")) {
+        if (!line.includes("*/")) insideMultilineComment = true;
+        continue;
+      }
+      selectorBuffer += ` ${line}`;
+      if (selectorBuffer.includes("{")) {
+        blockIsDark = selectorBuffer.includes('data-stgm-color-mode="dark"');
+        insideBlock = true;
+        selectorBuffer = "";
+        currentGroup = undefined;
+        pendingDescription = undefined;
+      }
+      continue;
+    }
+
+    if (line.startsWith("}")) {
+      insideBlock = false;
+      continue;
+    }
+
+    const groupMatch = GROUP_HEADER.exec(line);
+    if (groupMatch) {
+      currentGroup = groupMatch[1];
+      if (!line.includes("*/")) insideMultilineComment = true;
+      pendingDescription = undefined;
+      continue;
+    }
+
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) {
+        insideMultilineComment = true;
+        pendingDescription = undefined;
+        continue;
+      }
+      pendingDescription = line.replace(/^\/\*\s*/, "").replace(/\s*\*\/$/, "");
+      continue;
+    }
+
+    const declMatch = TOKEN_DECLARATION.exec(line);
+    if (declMatch) {
+      const declaration: TokenDeclaration = {
+        name: declMatch[1],
+        value: declMatch[2],
+        ...(pendingDescription !== undefined && { description: pendingDescription }),
+        ...(currentGroup !== undefined && { group: currentGroup }),
+      };
+      (blockIsDark ? dark : light).set(declaration.name, declaration);
+    }
+    // Any non-comment line (declaration or otherwise) consumes the pending
+    // description — a comment only documents the line directly beneath it.
+    pendingDescription = undefined;
+  }
+
+  return { light, dark };
+}