insomni-plot 0.1.0-alpha.0

package/src/grammar/accessibility.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vite-plus/test";
+import { apcaContrast, contrastRatio, cssHex } from "insomni";
+import {
+  DEFAULT_ACCESSIBILITY,
+  layerEqualizeTarget,
+  resolveTextColor,
+  _resetAccessibilityWarnings,
+  type Accessibility,
+} from "./accessibility.ts";
+import { themeDefault, type Theme } from "./theme.ts";
+
+function themeWith(overrides: Partial<Accessibility>): Theme {
+  return {
+    ...themeDefault,
+    accessibility: { ...DEFAULT_ACCESSIBILITY, ...overrides },
+  };
+}
+
+// A handful of bg colors spanning the dark/light spectrum so equalize is
+// exercised across both APCA polarities.
+const CELL_FILLS = [
+  cssHex("#1a2540"), // dark blue
+  cssHex("#3b3654"), // dark purple
+  cssHex("#2d6e8a"), // teal
+  cssHex("#4ea84e"), // green
+  cssHex("#c8d83b"), // chartreuse
+  cssHex("#f0e060"), // yellow
+];
+
+describe("resolveTextColor — APCA equalize", () => {
+  it("normalizes |Lc| close to target across light and dark backgrounds", () => {
+    _resetAccessibilityWarnings();
+    const theme = themeWith({
+      metric: "apca",
+      equalize: true,
+      apcaTarget: 75,
+      themeBias: 0, // disable bias to isolate the equalize math
+    });
+    const fg = cssHex("#ffffff");
+
+    const lcs = CELL_FILLS.map((bg) => {
+      const out = resolveTextColor(fg, bg, theme, {
+        fontSizePx: 14,
+        site: "tile-label",
+        markLabel: true,
+      });
+      return Math.abs(apcaContrast(out, bg));
+    });
+
+    // For cells whose luminance allows reaching the bumped target (82.5),
+    // the result lands within ±2 Lc. Mid-luminance cells (green, etc.)
+    // can't reach 82.5 with grayscale-only L shifts — equalize picks the
+    // best achievable in that case. The spread is still tighter than what
+    // WCAG equalize would produce; see the next test.
+    for (const lc of lcs) {
+      // Below 50 would mean genuinely unreadable; above ~85 means
+      // the polarity bump is overshooting.
+      expect(lc).toBeGreaterThan(50);
+      expect(lc).toBeLessThan(85);
+    }
+  });
+
+  it("APCA equalize produces tighter perceptual uniformity than WCAG equalize", () => {
+    _resetAccessibilityWarnings();
+    const fg = cssHex("#ffffff");
+
+    const wcagTheme = themeWith({
+      metric: "wcag",
+      equalize: true,
+      wcagLevel: 7,
+      themeBias: 0,
+    });
+    const apcaTheme = themeWith({
+      metric: "apca",
+      equalize: true,
+      apcaTarget: 75,
+      themeBias: 0,
+    });
+
+    // Measure each result's |Lc| — the perceptual-weight proxy. APCA
+    // equalize should produce a tighter spread of |Lc| than WCAG equalize.
+    const measure = (theme: Theme): number[] =>
+      CELL_FILLS.map((bg) => {
+        const out = resolveTextColor(fg, bg, theme, {
+          fontSizePx: 14,
+          site: "tile-label",
+          markLabel: true,
+        });
+        return Math.abs(apcaContrast(out, bg));
+      });
+
+    const wcagLcs = measure(wcagTheme);
+    const apcaLcs = measure(apcaTheme);
+
+    const spread = (xs: number[]) => Math.max(...xs) - Math.min(...xs);
+    expect(spread(apcaLcs)).toBeLessThan(spread(wcagLcs));
+  });
+
+  it("equalize does not modify chrome (markLabel=false) text", () => {
+    _resetAccessibilityWarnings();
+    const theme = themeWith({ metric: "apca", equalize: true, apcaTarget: 75 });
+    const fg = themeDefault.text.color;
+    const bg = themeDefault.background;
+
+    const out = resolveTextColor(fg, bg, theme, {
+      fontSizePx: 14,
+      site: "axis-label",
+      // markLabel omitted → false; this is chrome
+    });
+    // Chrome already has good contrast on the panel; resolver should
+    // pass it through unmodified.
+    expect(out).toEqual(fg);
+  });
+});
+
+describe("layerEqualizeTarget", () => {
+  it("returns the worst cell's max-achievable |Lc|", () => {
+    const theme = themeWith({ metric: "apca", equalize: true, themeBias: 0 });
+    const target = layerEqualizeTarget(theme, CELL_FILLS);
+    // Mid-luminance green (#4ea84e) caps |Lc| around 61 — should be the floor.
+    expect(target).not.toBeNull();
+    expect(target!).toBeGreaterThan(50);
+    expect(target!).toBeLessThan(75);
+  });
+
+  it("returns null when equalize is off", () => {
+    const theme = themeWith({ metric: "apca", equalize: false });
+    expect(layerEqualizeTarget(theme, CELL_FILLS)).toBeNull();
+  });
+
+  it("returns null when accessibility is disabled", () => {
+    const theme = themeWith({ enabled: false });
+    expect(layerEqualizeTarget(theme, CELL_FILLS)).toBeNull();
+  });
+});
+
+describe("resolveTextColor — equalize with layer-floor override", () => {
+  it("pulls every cell to the same |Lc| — even cells that could be louder", () => {
+    _resetAccessibilityWarnings();
+    const theme = themeWith({ metric: "apca", equalize: true, themeBias: 0 });
+    const fg = cssHex("#ffffff");
+    const target = layerEqualizeTarget(theme, CELL_FILLS)!;
+
+    const lcs = CELL_FILLS.map((bg) => {
+      const out = resolveTextColor(fg, bg, theme, {
+        fontSizePx: 14,
+        site: "tile-label",
+        markLabel: true,
+        targetOverride: target,
+      });
+      return Math.abs(apcaContrast(out, bg));
+    });
+
+    // Tight spread — within a couple Lc of the layer floor.
+    const spread = Math.max(...lcs) - Math.min(...lcs);
+    expect(spread).toBeLessThan(4);
+    // And visibly *less* than a dark cell would naturally produce.
+    expect(Math.max(...lcs)).toBeLessThan(80);
+  });
+});
+
+describe("resolveTextColor — fix-failing only", () => {
+  it("APCA fix raises low-contrast labels above target |Lc|", () => {
+    _resetAccessibilityWarnings();
+    const theme = themeWith({
+      metric: "apca",
+      equalize: false,
+      apcaTarget: 60,
+      themeBias: 0,
+    });
+    // Mid-gray text on a similarly toned background — fails badly.
+    const fg = cssHex("#888888");
+    const bg = cssHex("#999999");
+    const out = resolveTextColor(fg, bg, theme, {
+      fontSizePx: 14,
+      site: "tile-label",
+      markLabel: true,
+    });
+    expect(Math.abs(apcaContrast(out, bg))).toBeGreaterThanOrEqual(59.5);
+  });
+
+  it("WCAG metric still works (backwards compat)", () => {
+    _resetAccessibilityWarnings();
+    const theme = themeWith({
+      metric: "wcag",
+      equalize: false,
+      wcagLevel: 4.5,
+      themeBias: 0,
+    });
+    const fg = cssHex("#888888");
+    const bg = cssHex("#999999");
+    const out = resolveTextColor(fg, bg, theme, {
+      fontSizePx: 14,
+      site: "tile-label",
+      markLabel: true,
+    });
+    expect(contrastRatio(out, bg)).toBeGreaterThanOrEqual(4.5);
+  });
+});

package/src/grammar/accessibility.ts

@@ -0,0 +1,443 @@
+// ---------------------------------------------------------------------------
+// Text-readability resolution
+// ---------------------------------------------------------------------------
+// Bridges chart text-draw sites to insomni's contrast primitives. Each draw
+// site passes the foreground it wants and a *known* background; this module
+// returns the color that should actually be used (auto-fixed when needed)
+// and warns when contrast falls short and the user has opted out of fixes.
+//
+// Two metrics are supported:
+//   • APCA — perceptual, polarity-aware (default). Equalizing on |Lc| makes
+//     labels feel like the same weight regardless of cell color.
+//   • WCAG 2.1 ratio — kept for backwards compat; equalizing on ratio is
+//     visually unequal across polarities, which is why we changed defaults.
+//
+// Outline / shadow modes are accepted but currently fall back to auto-color
+// because the SDF text path can't render them yet — see
+// dev_docs/2026-04-30-text-accessibility.md for the gap list.
+
+import {
+  apcaContrast,
+  apcaFontLookup,
+  BLACK,
+  colorAtApca,
+  colorAtContrast,
+  contrastRatio,
+  findAccessibleColor,
+  findApcaColor,
+  lerpInSpace,
+  srgbToOklab,
+  wcagMinContrast,
+  WHITE,
+  type BlendSpace,
+  type Color,
+} from "insomni";
+import type { Theme } from "./theme.ts";
+
+// Alpha-composite `fg` over `bg`. Both metrics measure the rendered pixel,
+// not the unmixed fg, so we composite first.
+function compositeOver(fg: Color, bg: Color): Color {
+  if (fg.a >= 1) return fg;
+  const a = fg.a;
+  return {
+    r: fg.r * a + bg.r * (1 - a),
+    g: fg.g * a + bg.g * (1 - a),
+    b: fg.b * a + bg.b * (1 - a),
+    a: 1,
+  };
+}
+
+// Perceptual distance in OKLab — finding the "nearest" accent should feel
+// nearest *to the eye*, not in the warped sRGB cube. Squared distance is
+// fine since we only compare candidates against each other.
+function oklabDist2(a: Color, b: Color): number {
+  const A = srgbToOklab(a);
+  const B = srgbToOklab(b);
+  const dL = A.L - B.L;
+  const da = A.a - B.a;
+  const db = A.b - B.b;
+  return dL * dL + da * da + db * db;
+}
+
+// Default accent palette derived from the active theme — the colors the
+// reader is *already* seeing in the chart's chrome plus a few palette
+// samples. Cached per-theme since it's stable for a chart's lifetime.
+const _accentCache = new WeakMap<Theme, Color[]>();
+function defaultAccents(theme: Theme): readonly Color[] {
+  const cached = _accentCache.get(theme);
+  if (cached) return cached;
+  const out: Color[] = [
+    theme.text.color,
+    theme.title.color,
+    theme.subtitle.color,
+    theme.axis.labelColor,
+    theme.axis.titleColor,
+    theme.legend.labelColor,
+  ];
+  const cat = theme.palettes.categorical;
+  const N = Math.min(cat.colors.length, 8);
+  for (let i = 0; i < N; i++) out.push(cat.colors[i]!);
+  _accentCache.set(theme, out);
+  return out;
+}
+
+export type AccessibilityMode = "auto-color" | "outline" | "shadow" | "none";
+export type ContrastMetric = "wcag" | "apca";
+
+export interface Accessibility {
+  /**
+   * Master switch. When `false`, `resolveTextColor` never alters colors —
+   * but if `warn` is also true it logs the failing site once per session so
+   * authors can see what would have been fixed.
+   */
+  enabled: boolean;
+  /**
+   * Which contrast metric to enforce.
+   *
+   * `"apca"` (default) uses APCA Lc — perceptually uniform and
+   * polarity-aware, so equalizing produces labels that read with the same
+   * weight whether they sit on a dark or a light cell.
+   *
+   * `"wcag"` uses the WCAG 2.1 ratio formula. Kept for backwards
+   * compatibility; equalizing on WCAG ratio looks visually unbalanced
+   * across polarities.
+   */
+  metric: ContrastMetric;
+  /**
+   * WCAG-mode target. `"AA"` = 4.5:1 normal / 3:1 large; `"AAA"` = 7:1 / 4.5:1.
+   * A raw number sets an absolute minimum ratio (1–21) applied to all text
+   * regardless of size. Ignored when `metric === "apca"`.
+   */
+  wcagLevel: "AA" | "AAA" | number;
+  /**
+   * APCA-mode target |Lc|. `"auto"` (default) looks up the recommended
+   * minimum from APCA's font/weight table for each site (typical body text
+   * lands around Lc 75–90). A raw number applies a single |Lc| floor to
+   * every site. Ignored when `metric === "wcag"`.
+   */
+  apcaTarget: number | "auto";
+  /**
+   * How to fix low-contrast text. `auto-color` nudges the color toward an
+   * accessible shade preserving hue/saturation. `outline` / `shadow` are
+   * reserved API hooks — both currently degrade to `auto-color` since the
+   * SDF text pipeline doesn't render text effects yet. `none` leaves text
+   * untouched (and warns when `warn` is on).
+   */
+  mode: AccessibilityMode;
+  /** Whether to console.warn on contrast failures the system isn't fixing. */
+  warn: boolean;
+  /**
+   * When true, every *mark* label (geom-rendered, sitting on a data-driven
+   * fill) is normalized to *exactly* the target contrast — not just `>=`.
+   * Equalizing prevents cells with high contrast from visually outweighing
+   * neighbors. Hue and saturation are preserved; only lightness shifts.
+   *
+   * Chrome text (titles, axis, legend) skips this — those sit on the
+   * panel background and equalizing them just dims legible chrome.
+   */
+  equalize: boolean;
+  /**
+   * How strongly the auto-fixer pulls toward colors already in the theme.
+   * `0` keeps the original hue/sat untouched. `1` snaps to the nearest
+   * passing theme accent. Intermediate values blend in `blendSpace`,
+   * keeping the label feeling "of the same family" as the chart's palette.
+   *
+   * The pull is only applied when at least one accent independently meets
+   * the contrast target — biasing toward an unreadable accent would defeat
+   * the fix. When `equalize` is on, the L-channel is re-fit after the blend
+   * so the final contrast still lands at the target.
+   */
+  themeBias: number;
+  /**
+   * Optional explicit accent palette for the bias. When unset, the
+   * resolver derives accents from the active theme (text/title/legend
+   * colors plus a sample of the categorical palette).
+   */
+  accents?: readonly Color[];
+  /**
+   * Color space used for the theme-bias blend. Defaults to `"oklch"` —
+   * perceptually uniform with hue preserved along the blend.
+   */
+  blendSpace: BlendSpace;
+}
+
+export const DEFAULT_ACCESSIBILITY: Accessibility = {
+  enabled: true,
+  metric: "apca",
+  wcagLevel: 7,
+  apcaTarget: "auto",
+  mode: "auto-color",
+  warn: true,
+  equalize: true,
+  themeBias: 0.5,
+  blendSpace: "oklch",
+};
+
+/**
+ * Stub for SDF text effects. Setting these on the theme today has no visual
+ * effect — the renderer will pick them up once outline/shadow are wired into
+ * the text pipeline. Kept on the public API so call sites and themes can
+ * declare intent now without a follow-up breaking change.
+ */
+export interface TextEffects {
+  outline?: { color: Color; width: number };
+  shadow?: { color: Color; blur?: number; dx?: number; dy?: number };
+}
+
+// ---------------------------------------------------------------------------
+// Once-per-session warnings — keyed by (site, fg, bg, metric value bucket)
+// so a single repeating draw call doesn't spam the console every frame.
+
+const _warnedKeys = new Set<string>();
+const _warnedEffectModes = new Set<AccessibilityMode>();
+
+function colorKey(c: Color): string {
+  const q = (v: number) => Math.round(v * 255);
+  return `${q(c.r)},${q(c.g)},${q(c.b)},${c.a.toFixed(2)}`;
+}
+
+function warnOnce(
+  site: string,
+  fg: Color,
+  bg: Color,
+  formattedMessage: string,
+  bucketKey: string,
+  enabledHint: boolean,
+): void {
+  const key = `${site}|${colorKey(fg)}|${colorKey(bg)}|${bucketKey}`;
+  if (_warnedKeys.has(key)) return;
+  _warnedKeys.add(key);
+  const suffix = enabledHint
+    ? ""
+    : " (theme.accessibility.enabled is false; set mode to 'auto-color' to auto-fix)";
+  console.warn(`[plot] Low text contrast at ${site}: ${formattedMessage}.${suffix}`);
+}
+
+function warnEffectModeOnce(mode: AccessibilityMode): void {
+  if (_warnedEffectModes.has(mode)) return;
+  _warnedEffectModes.add(mode);
+  console.warn(
+    `[plot] accessibility.mode='${mode}' is not yet implemented (SDF text outline/shadow ` +
+      `pending). Falling back to 'auto-color' for now.`,
+  );
+}
+
+/** Test helper — clears the dedupe cache so repeat warnings fire again. */
+export function _resetAccessibilityWarnings(): void {
+  _warnedKeys.clear();
+  _warnedEffectModes.clear();
+}
+
+/**
+ * Compute a layer-wide equalize target — the largest |contrast| the worst
+ * cell in `backgrounds` can achieve from a black or white label. Used by
+ * geoms that want every label normalized to the same readable level even
+ * if that means muting high-contrast cells.
+ *
+ * Returns `null` when the metric/policy doesn't equalize (so callers can
+ * skip the pre-pass cheaply).
+ */
+export function layerEqualizeTarget(theme: Theme, backgrounds: readonly Color[]): number | null {
+  const a = theme.accessibility ?? DEFAULT_ACCESSIBILITY;
+  if (!a.enabled || !a.equalize || a.mode === "none") return null;
+  if (backgrounds.length === 0) return null;
+  const engine = a.metric === "apca" ? apcaEngine : wcagEngine;
+  let floor = Infinity;
+  for (const bg of backgrounds) {
+    // Each cell's reachable max is bounded by the more contrasting of
+    // black / white. (Hue/sat-preserving search can't beat the extremes.)
+    const reach = Math.max(engine.measure(BLACK, bg), engine.measure(WHITE, bg));
+    if (reach < floor) floor = reach;
+  }
+  return Number.isFinite(floor) ? floor : null;
+}
+
+// ---------------------------------------------------------------------------
+// Contrast engine — abstracts WCAG vs APCA so the resolver logic stays
+// metric-agnostic. `value` is the metric reading: WCAG ratio or |APCA Lc|.
+// `target` is the threshold. Both are non-negative scalars; the engine
+// internally tracks polarity for APCA.
+
+interface ContrastEngine {
+  /** Magnitude of the metric (WCAG ratio, or |Lc| for APCA). */
+  measure(fg: Color, bg: Color): number;
+  /** Target magnitude for this draw site (font-size lookup or fixed). */
+  target(opts: ResolveTextColorOptions, a: Accessibility): number;
+  /** Find the nearest passing color (preserves hue/sat). */
+  findFix(fg: Color, bg: Color, target: number): Color;
+  /** Find the color whose magnitude lands *at* `target` (preserves hue/sat). */
+  findExact(fg: Color, bg: Color, target: number): Color;
+  /** Format the failure for warn-once messages. */
+  formatFailure(value: number, target: number): { message: string; bucket: string };
+}
+
+const wcagEngine: ContrastEngine = {
+  measure: (fg, bg) => contrastRatio(fg, bg),
+  target: (opts, a) =>
+    wcagMinContrast({
+      fontSizePx: opts.fontSizePx,
+      bold: opts.bold,
+      level: a.wcagLevel,
+    }),
+  findFix: (fg, bg, t) => findAccessibleColor(fg, bg, t),
+  findExact: (fg, bg, t) => colorAtContrast(fg, bg, t),
+  formatFailure: (value, target) => ({
+    message: `${value.toFixed(2)}:1 (need ${target.toFixed(1)}:1)`,
+    bucket: value.toFixed(1),
+  }),
+};
+
+// APCA polarity asymmetry: light-on-dark needs slightly more |Lc| than
+// dark-on-light to feel equally readable. Per Somers' guidance, the reverse
+// polarity recommendation runs ~10% higher.
+const APCA_REVERSE_BIAS = 1.1;
+
+const apcaEngine: ContrastEngine = {
+  measure: (fg, bg) => Math.abs(apcaContrast(fg, bg)),
+  target: (opts, a) => {
+    const base =
+      a.apcaTarget === "auto"
+        ? apcaFontLookup(opts.fontSizePx, opts.bold ? 700 : 400)
+        : a.apcaTarget;
+    // Polarity-aware bump — when fg ends up lighter than bg (dark mode
+    // direction), require ~10% more |Lc| for equal perceived weight.
+    const yFg = relativeApcaLuminance(opts);
+    return yFg.reverse ? base * APCA_REVERSE_BIAS : base;
+  },
+  findFix: (fg, bg, t) => findApcaColor(fg, bg, t),
+  findExact: (fg, bg, t) => colorAtApca(fg, bg, t),
+  formatFailure: (value, target) => ({
+    message: `Lc ${value.toFixed(0)} (need ${target.toFixed(0)})`,
+    bucket: value.toFixed(0),
+  }),
+};
+
+// Polarity hint passthrough — the APCA engine's `target` doesn't have direct
+// access to (fg, bg) at lookup time, so we stash the inferred polarity on
+// the options object. Filled in by `resolveTextColor` before dispatch.
+function relativeApcaLuminance(opts: ResolveTextColorOptions): { reverse: boolean } {
+  return { reverse: opts._apcaReverse === true };
+}
+
+// ---------------------------------------------------------------------------
+
+export interface ResolveTextColorOptions {
+  /** Font size in CSS pixels. */
+  fontSizePx: number;
+  /** Treat the text as bold (affects WCAG large-text and APCA weight lookup). */
+  bold?: boolean;
+  /**
+   * Short label identifying the draw site (e.g. `"axis-label"`,
+   * `"tile-label"`). Used to namespace dedupe keys for warnings.
+   */
+  site: string;
+  /**
+   * Whether this site sits on a *data-driven* background (mark fills,
+   * heatmap cells) versus chrome on the panel background. `equalize`
+   * normalization applies only to mark sites — chrome text always sits on
+   * the same panel background, so equalizing it would just lower legible
+   * titles/axis/legend text down toward the contrast floor for no gain.
+   * Default `false`.
+   */
+  markLabel?: boolean;
+  /**
+   * Override the engine-computed target. When set, the resolver uses this
+   * value instead of the font/level lookup. Used by geoms that need to
+   * coordinate a layer-wide equalize floor (e.g. tile pulls every label
+   * down to the worst cell's max-achievable contrast so the layer reads
+   * uniformly, instead of saturating each label at its own per-cell max).
+   */
+  targetOverride?: number;
+  /** @internal — APCA polarity, computed inside the resolver. */
+  _apcaReverse?: boolean;
+}
+
+/**
+ * Resolve the actual color that should be drawn for a piece of text given
+ * the requested foreground, the known background, and the chart's
+ * accessibility policy. Pure — does not draw anything.
+ */
+export function resolveTextColor(
+  fg: Color,
+  bg: Color,
+  theme: Theme,
+  opts: ResolveTextColorOptions,
+): Color {
+  const a = theme.accessibility ?? DEFAULT_ACCESSIBILITY;
+  const engine = a.metric === "apca" ? apcaEngine : wcagEngine;
+
+  const fgEffective = compositeOver(fg, bg);
+
+  // For APCA: infer polarity (sign of Lc) so the target lookup can apply
+  // the asymmetric reverse-polarity bump.
+  const optsResolved: ResolveTextColorOptions =
+    a.metric === "apca" ? { ...opts, _apcaReverse: apcaContrast(fgEffective, bg) < 0 } : opts;
+
+  const target = optsResolved.targetOverride ?? engine.target(optsResolved, a);
+  const value = engine.measure(fgEffective, bg);
+  const passes = value >= target;
+
+  const computeFix = (): Color =>
+    a.equalize
+      ? engine.findExact(fgEffective, bg, target)
+      : engine.findFix(fgEffective, bg, target);
+
+  // Equalize: every mark label normalizes (even ones already above the
+  // threshold). Chrome sites skip this branch.
+  if (a.enabled && a.equalize && a.mode !== "none" && opts.markLabel) {
+    if (a.mode === "outline" || a.mode === "shadow") warnEffectModeOnce(a.mode);
+    return applyThemeBias(computeFix(), bg, target, a, theme, engine);
+  }
+
+  if (passes) return fg;
+
+  if (!a.enabled || a.mode === "none") {
+    if (a.warn) {
+      const { message, bucket } = engine.formatFailure(value, target);
+      warnOnce(opts.site, fg, bg, message, bucket, a.enabled);
+    }
+    return fg;
+  }
+
+  if (a.mode === "outline" || a.mode === "shadow") {
+    warnEffectModeOnce(a.mode);
+  }
+  return applyThemeBias(computeFix(), bg, target, a, theme, engine);
+}
+
+// Pull the candidate toward the nearest theme accent that *also* meets the
+// contrast target. When `equalize` is on, re-fit lightness after the blend
+// so the final contrast lands at the target.
+function applyThemeBias(
+  candidate: Color,
+  bg: Color,
+  target: number,
+  a: Accessibility,
+  theme: Theme,
+  engine: ContrastEngine,
+): Color {
+  if (a.themeBias <= 0) return candidate;
+  const accents = a.accents ?? defaultAccents(theme);
+  if (accents.length === 0) return candidate;
+
+  // Only consider accents that independently pass the target.
+  let best: Color | null = null;
+  let bestDist = Infinity;
+  for (const accent of accents) {
+    if (engine.measure(accent, bg) < target) continue;
+    const d = oklabDist2(candidate, accent);
+    if (d < bestDist) {
+      bestDist = d;
+      best = accent;
+    }
+  }
+  if (!best) return candidate;
+
+  const blended = lerpInSpace(candidate, best, a.themeBias, a.blendSpace);
+  if (a.equalize) return engine.findExact(blended, bg, target);
+  // Non-equalize path: the blend can usually only move the metric
+  // monotonically between two passing colors, but float rounding occasionally
+  // nudges it a hair below — clamp back up if so.
+  if (engine.measure(blended, bg) >= target) return blended;
+  return engine.findFix(blended, bg, target);
+}

package/src/grammar/aes.d.ts

@@ -0,0 +1,35 @@
+export type ColumnKeys<T, V> = {
+    [K in keyof T]-?: T[K] extends V ? K : never;
+}[keyof T];
+export type Accessor<T, V> = (datum: T, index: number) => V;
+export type Aes<T, V> = ColumnKeys<T, V> | Accessor<T, V> | V;
+export type Row = Record<string, unknown>;
+export interface ResolvedAes<T, V> {
+    readonly kind: "column" | "accessor" | "constant";
+    readonly column?: keyof T & string;
+    readonly fn: Accessor<T, V>;
+}
+/**
+ * Normalize an `Aes<T, V>` to a `(d, i) => V` accessor plus metadata. The
+ * `kind` and `column` fields let consumers (auto-scale inference, legends,
+ * tooltip labels) introspect the original mapping.
+ */
+export declare function resolveAes<T, V>(aes: Aes<T, V> | undefined, fallback?: V): ResolvedAes<T, V>;
+/**
+ * Materialize an aesthetic to a flat array. Used when the chart needs the
+ * full column for domain inference.
+ */
+export declare function materialize<T, V>(aes: ResolvedAes<T, V>, data: readonly T[]): V[];
+/**
+ * Return the subset of `indices` whose row produces a non-null categorical
+ * value under `aes`. Used by geoms that group by a categorical channel; keeps
+ * the drop-row policy in one place.
+ */
+export declare function dropNullCategoricalIndices<T>(indices: readonly number[], aes: ResolvedAes<T, unknown>, data: readonly T[]): number[];
+/**
+ * Best-effort guess of a channel's data type. Used to pick a default scale
+ * type when no override is supplied. Null / undefined values are skipped
+ * (see "Null / undefined policy" above).
+ */
+export type ChannelDataType = "number" | "date" | "string" | "boolean" | "unknown";
+export declare function inferDataType(values: readonly unknown[]): ChannelDataType;