insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/tile.ts

@@ -0,0 +1,621 @@
+// ---------------------------------------------------------------------------
+// tile geom — categorical / matrix heatmap (one cell per row)
+// ---------------------------------------------------------------------------
+// Produces one rectangular cell per datum. The `fill` channel feeds the
+// chart-wide color scale, so a continuous palette + automatic color-bar
+// legend just work via the existing pipeline.
+//
+// Two layout modes, picked at compile-time from the active scales:
+//   - band × band  → cell size taken from `bandwidth()` on each axis
+//   - continuous   → cell size inferred from sorted unique values (assumes
+//     a regular grid, like long-format `mtcars` rows or `geom_tile()` data).
+
+import type { Color, Layer } from "insomni";
+import { layerEqualizeTarget, resolveTextColor } from "../accessibility.ts";
+import { valueLabelMark } from "../../annotations.ts";
+import {
+  type BandScale,
+  type ContinuousScale,
+  type AxisScale,
+  type TimeScale,
+} from "../../scales.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { withAlpha } from "../color-utils.ts";
+import { barSwatch } from "../../legend.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomHoverDecorator,
+  HoveredHit,
+  ResolvedChannelMap,
+} from "./types.ts";
+import { defaultMarkFill, resolveCoord, wrapMark } from "./_mark.ts";
+import { emphasisContext } from "./emphasis.ts";
+
+export interface TileChannels<T> {
+  x: Aes<T, string | number | Date>;
+  y: Aes<T, string | number | Date>;
+  /**
+   * Continuous fill — typically a numeric column. Drives the chart's color
+   * scale (legend renders as a continuous color bar). For a per-cell constant
+   * color, pass `options.fill` instead and omit this channel.
+   */
+  fill?: Aes<T, unknown>;
+}
+
+export interface TileNAOptions {
+  /** Fill for missing/non-finite values. When unset, NA cells are skipped. */
+  fill?: Color;
+}
+
+export interface TileOptions<T = unknown> {
+  /**
+   * Constant cell color when no `fill` channel is mapped. Ignored when
+   * `channels.fill` is present (in which case the color scale supplies the
+   * fill).
+   */
+  fill?: Color;
+  /** Horizontal/vertical inset between cells. Default `0`. */
+  padding?: number;
+  /** Per-axis padding override (multi-key form). Wins over `padding`. */
+  paddingX?: number;
+  paddingY?: number;
+  /** Optional border outline per cell. */
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /**
+   * Per-cell text label. Receives the (numeric) fill value when the `fill`
+   * channel is mapped; receives `NaN` otherwise (in which case you'll
+   * typically derive the label from the datum directly).
+   */
+  showValues?: (value: number, datum: T, index: number) => string;
+  labelColor?: Color;
+  labelFontSize?: number;
+  /**
+   * Skip per-cell labels when the projected cell is below this pixel size on
+   * either axis. Labels at small cell sizes are unreadable smudges and the
+   * shaping cost dominates frame time at high cell counts. Default: unset
+   * (every cell labeled). A value around `1.5 * labelFontSize` is a sensible
+   * floor for legibility.
+   */
+  minLabelCellPx?: number;
+  /**
+   * For numeric/time x or y axes only — the implicit cell width/height in
+   * domain units. When omitted, the cell extent is inferred from the
+   * smallest gap between sorted unique values in the data.
+   */
+  cellWidth?: number;
+  cellHeight?: number;
+  /** Missing-value handling. */
+  na?: TileNAOptions;
+  label?: string;
+}
+
+export function tile<T>(channels: TileChannels<T>, options: TileOptions<T> = {}): Geom<T> {
+  return {
+    kind: "tile",
+    channels: { x: channels.x, y: channels.y, color: channels.fill },
+    label: options.label,
+    legendSwatch: (color) => barSwatch({ fill: color, size: 12 }),
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme, atlas } = ctx;
+      const coord = resolveCoord(ctx);
+      if (coord.kind !== "cartesian") {
+        // Per Phase 3b spec: polar tile would emit annular sectors (polygon
+        // walking inner-arc + outer-arc at ~1° step). Deferred to v2; throw
+        // a friendly error so users get a clear signal instead of a silently
+        // mis-projected rectangle quad.
+        throw new Error(
+          `coordPolar() does not support geomTile in v1. Use point/line/text/rule under polar; tile remains Cartesian-only.`,
+        );
+      }
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const fillAes = channels.fill ? resolveAes<T, unknown>(channels.fill) : undefined;
+
+      const padX = options.paddingX ?? options.padding ?? 0;
+      const padY = options.paddingY ?? options.padding ?? 0;
+
+      const xLayout = makeAxisLayout<T>(
+        scales.x.axisScale as AxisScale<unknown>,
+        xAes,
+        data,
+        options.cellWidth,
+      );
+      const yLayout = makeAxisLayout<T>(
+        scales.y.axisScale as AxisScale<unknown>,
+        yAes,
+        data,
+        options.cellHeight,
+      );
+
+      const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+      const colorScaleFn = scales.color?.fn;
+      const naFill = options.na?.fill;
+
+      // Resolve per-cell fill once — the inner loop just reads it.
+      const fillFor =
+        fillAes && colorScaleFn
+          ? (d: T, i: number): Color | null => {
+              const raw = fillAes.fn(d, i);
+              if (!isFiniteValue(raw)) return naFill ?? null;
+              return withAlpha(colorScaleFn(raw), theme.marks.fillAlpha);
+            }
+          : (_d: T, _i: number): Color | null => withAlpha(baseFill, theme.marks.fillAlpha);
+
+      // Hover emphasis — the dim-others treatment now rides the core's GPU
+      // emphasis uniform (P5-T3): tag each cell with a stable per-row key; the
+      // mount fades non-focused cells without a marks recompile. No compile-time
+      // color dim / halo. `dataIndex` in compileHitTest equals the datum index `i`.
+      const emph = emphasisContext(ctx, "tile");
+
+      const builders: ReturnType<typeof wrapMark>[] = [];
+
+      builders.push({
+        length: data.length,
+        addTo: (layer) => {
+          const ox = plot.topLeft.x;
+          const oy = plot.topLeft.y;
+          const stroke = options.stroke;
+          const strokeWidth = options.strokeWidth;
+          const cornerRadius = options.cornerRadius;
+
+          for (let i = 0; i < data.length; i++) {
+            const datum = data[i]!;
+            const xv = xAes.fn(datum, i);
+            const yv = yAes.fn(datum, i);
+            const xRect = xLayout.rect(xv);
+            const yRect = yLayout.rect(yv);
+            if (!xRect || !yRect) continue;
+            const fill = fillFor(datum, i);
+            if (!fill) continue;
+            // Project the cell's top-left corner through the active coord.
+            // Under Cartesian this is the identity; polar (Phase 3) routes
+            // tiles to an annular-sector mark instead and bypasses this path.
+            const projectedCorner = coord.project({
+              x: xRect.start + padX / 2,
+              y: yRect.start + padY / 2,
+            });
+            const rx = ox + projectedCorner.x;
+            const ry = oy + projectedCorner.y;
+            const rw = Math.max(0, xRect.length - padX);
+            const rh = Math.max(0, yRect.length - padY);
+            layer.pushRect({
+              x: rx,
+              y: ry,
+              width: rw,
+              height: rh,
+              fill,
+              stroke,
+              strokeWidth,
+              cornerRadius,
+              emphasisKey: emph?.keyFor(i),
+            });
+          }
+
+          return layer;
+        },
+      });
+
+      // Optional per-cell text labels.
+      if (atlas && options.showValues) {
+        const fmt = options.showValues;
+        const baseLabelColor: Color = options.labelColor ?? theme.text.color;
+        const labelFontSize = options.labelFontSize ?? theme.marks.labelFontSize;
+        // Single pre-pass over data: gather per-cell fills (null where the
+        // cell is empty) so we can derive the equalize target AND skip
+        // re-calling `fillFor` from `labelColorFor` below.
+        //
+        // Equalize: pull every label down to the lowest contrast *any* cell
+        // can support. Without this, equalize saturates at each cell's
+        // individual max — loud cells stay loud, indistinguishable from
+        // "fix failing only".
+        const perCellFill: (Color | null)[] = Array.from({ length: data.length });
+        const cellFills: Color[] = [];
+        for (let i = 0; i < data.length; i++) {
+          const f = fillFor(data[i]!, i);
+          perCellFill[i] = f;
+          if (f) cellFills.push(f);
+        }
+        const equalizeTarget = layerEqualizeTarget(theme, cellFills);
+        // `resolveTextColor` runs APCA contrast math + iterative color search
+        // per call — expensive enough that running it for thousands of cells
+        // with a continuous palette dominates frame time. Cache by quantized
+        // RGB string so visually-equivalent fills reuse the result; with a
+        // continuous palette over thousands of cells the cache typically
+        // collapses to a few hundred unique fills.
+        const labelColorCache = new Map<string, Color>();
+        const labelColorFor = (_d: T, i: number): Color => {
+          const cellFill = perCellFill[i];
+          if (!cellFill) return baseLabelColor;
+          const key = quantizeColorKey(cellFill);
+          const hit = labelColorCache.get(key);
+          if (hit !== undefined) return hit;
+          const resolved = resolveTextColor(baseLabelColor, cellFill, theme, {
+            fontSizePx: labelFontSize,
+            site: "tile-label",
+            markLabel: true,
+            targetOverride: equalizeTarget ?? undefined,
+          });
+          labelColorCache.set(key, resolved);
+          return resolved;
+        };
+        const labelMark = valueLabelMark(data, {
+          x: (d, i) => {
+            const xr = xLayout.rect(xAes.fn(d, i));
+            const yr = yLayout.rect(yAes.fn(d, i));
+            if (!xr || !yr) return 0;
+            return coord.project({
+              x: xr.start + xr.length / 2,
+              y: yr.start + yr.length / 2,
+            }).x;
+          },
+          y: (d, i) => {
+            const xr = xLayout.rect(xAes.fn(d, i));
+            const yr = yLayout.rect(yAes.fn(d, i));
+            if (!xr || !yr) return 0;
+            // Center vertically inside the cell — `valueLabelMark` uses the
+            // y as the text baseline, so subtract half the font for visual
+            // centering.
+            return (
+              coord.project({
+                x: xr.start + xr.length / 2,
+                y: yr.start + yr.length / 2,
+              }).y -
+              labelFontSize / 2
+            );
+          },
+          text: (d, i) => {
+            const raw = fillAes ? fillAes.fn(d, i) : NaN;
+            const numeric = typeof raw === "number" ? raw : NaN;
+            return fmt(numeric, d, i);
+          },
+          color: labelColorFor,
+          fontSize: labelFontSize,
+          align: "center",
+          offset: { x: 0, y: 0 },
+          filter: (d, i) => {
+            const xr = xLayout.rect(xAes.fn(d, i));
+            const yr = yLayout.rect(yAes.fn(d, i));
+            if (xr === null || yr === null) return false;
+            const minPx = options.minLabelCellPx;
+            if (minPx !== undefined && (xr.length < minPx || yr.length < minPx)) {
+              return false;
+            }
+            return true;
+          },
+        });
+        builders.push(wrapMark(labelMark, plot.topLeft, data.length));
+      }
+
+      return builders;
+    },
+    emphasisResolution(ctx) {
+      return emphasisContext(ctx, "tile")?.resolver() ?? null;
+    },
+    hoverDecoration(ctx: CompileContext<T>): GeomHoverDecorator | null {
+      // Focus halo on the hovered cell — recovered from the old snap path's
+      // `paintHalos` outline (deleted in e6d5643). Now an OVERLAY decorator
+      // replayed into the live overlay layer (NO marks recompile). Overlay shapes
+      // leave emphasisKey 0 ⇒ EXEMPT ⇒ the halo stays full-strength while the
+      // other cells dim via the GPU uniform. The hit's `dataIndex` is the datum
+      // index `i`, so we re-project just that cell's rect.
+      const { data, plot } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+      if (coord.kind !== "cartesian") return null;
+      const hoverCfg = ctx.theme.interactions.hover;
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const xLayout = makeAxisLayout<T>(
+        ctx.scales.x.axisScale as AxisScale<unknown>,
+        xAes,
+        data,
+        options.cellWidth,
+      );
+      const yLayout = makeAxisLayout<T>(
+        ctx.scales.y.axisScale as AxisScale<unknown>,
+        yAes,
+        data,
+        options.cellHeight,
+      );
+      const padX = options.paddingX ?? options.padding ?? 0;
+      const padY = options.paddingY ?? options.padding ?? 0;
+      const ringColor: Color = hoverCfg.haloColor ?? ctx.theme.text.color;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+
+      return {
+        geomKind: "tile",
+        data,
+        decorate(hit: HoveredHit, layer: Layer): void {
+          if (!hoverCfg.enabled || hit.data !== data) return;
+          const i = hit.dataIndex;
+          const d = data[i];
+          if (d === undefined) return;
+          const xRect = xLayout.rect(xAes.fn(d, i));
+          const yRect = yLayout.rect(yAes.fn(d, i));
+          if (!xRect || !yRect) return;
+          const corner = coord.project({ x: xRect.start + padX / 2, y: yRect.start + padY / 2 });
+          layer.pushRect({
+            x: ox + corner.x,
+            y: oy + corner.y,
+            width: Math.max(0, xRect.length - padX),
+            height: Math.max(0, yRect.length - padY),
+            cornerRadius: options.cornerRadius,
+            stroke: ringColor,
+            strokeWidth: hoverCfg.haloStrokeWidth,
+          });
+        },
+      };
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const fillAes = channels.fill ? resolveAes<T, unknown>(channels.fill) : undefined;
+      const xLayout = makeAxisLayout<T>(
+        scales.x.axisScale as AxisScale<unknown>,
+        xAes,
+        data,
+        options.cellWidth,
+      );
+      const yLayout = makeAxisLayout<T>(
+        scales.y.axisScale as AxisScale<unknown>,
+        yAes,
+        data,
+        options.cellHeight,
+      );
+
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const positions = new Float32Array(data.length * 2);
+      const rects = new Float32Array(data.length * 4);
+      const dataIndex = new Int32Array(data.length);
+      let n = 0;
+      // Track the smallest cell extent to size pickRadius to one cell.
+      let halfMin = Infinity;
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const xRect = xLayout.rect(xAes.fn(datum, i));
+        const yRect = yLayout.rect(yAes.fn(datum, i));
+        if (!xRect || !yRect) continue;
+        const center = coord.project({
+          x: xRect.start + xRect.length / 2,
+          y: yRect.start + yRect.length / 2,
+        });
+        const corner = coord.project({ x: xRect.start, y: yRect.start });
+        positions[n * 2] = ox + center.x;
+        positions[n * 2 + 1] = oy + center.y;
+        // Whole-cell footprint for region hit testing.
+        rects[n * 4] = ox + corner.x;
+        rects[n * 4 + 1] = oy + corner.y;
+        rects[n * 4 + 2] = xRect.length;
+        rects[n * 4 + 3] = yRect.length;
+        dataIndex[n] = i;
+        n++;
+        const half = Math.min(xRect.length, yRect.length) / 2;
+        if (half < halfMin) halfMin = half;
+      }
+      if (n === 0) return null;
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: xAes,
+        y: yAes,
+        color: fillAes,
+      };
+      return {
+        geomKind: "tile",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex: dataIndex.subarray(0, n),
+        // Half the smallest cell — biased toward not over-claiming neighbors
+        // when cell sizes vary. Euclidean within a cell still always picks.
+        pickRadius: Number.isFinite(halfMin) ? halfMin : 0,
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-axis layout — resolves a value to its cell's pixel `[start, length]`.
+// ---------------------------------------------------------------------------
+
+interface AxisLayout {
+  rect(value: unknown): { start: number; length: number } | null;
+}
+
+function makeAxisLayout<T>(
+  scale: AxisScale<unknown>,
+  aes: { fn: (d: T, i: number) => unknown },
+  data: readonly T[],
+  cellExtent: number | undefined,
+): AxisLayout {
+  if (isBandScale(scale)) {
+    const bw = scale.bandwidth();
+    return {
+      rect: (value) => {
+        const px = scale(String(value) as never);
+        if (!Number.isFinite(px)) return null;
+        return { start: px, length: bw };
+      },
+    };
+  }
+
+  // Continuous / time scale: cell extent in domain units.
+  // Either a user-supplied `cellExtent` or one inferred from the data.
+  const domainExtent = cellExtent ?? inferCellExtent(scale, aes, data);
+  // Pre-resolve to avoid repeated property reads in the hot loop.
+  const continuous = scale as ContinuousScale | TimeScale;
+
+  // Detect regular grids: when the sorted unique values are equally spaced
+  // (e.g. hours 0–23), the data is effectively ordinal and cells should
+  // abut from the domain edge rather than centering on each value. This
+  // gives edge cells their full height flush with the domain boundary.
+  // Irregularly-spaced continuous data falls through to centered layout.
+  const [sortedValues, isRegular] = detectGrid(valuesFromAes(aes, data), domainExtent);
+
+  if (isRegular) {
+    // Abutting-bin layout: cell i occupies [d0 + i*step, d0 + (i+1)*step]
+    // in domain space. The step is computed from the domain span divided
+    // by the number of unique values so all cells fit exactly within the
+    // visible range — no overflow at the edges.
+    const [d0, d1] = (scale as ContinuousScale).domain as [number, number];
+    const count = sortedValues.length;
+    const step = count > 1 ? (d1 - d0) / count : 1;
+    const valueToIndex = new Map(sortedValues.map((v, i) => [v, i]));
+
+    return {
+      rect: (value) => {
+        const nv = isDate(value) ? (value as Date).getTime() : (value as number);
+        if (!Number.isFinite(nv)) return null;
+        const idx = valueToIndex.get(nv);
+        if (idx === undefined) return null;
+        const dataStart = d0 + idx * step;
+        const dataEnd = dataStart + step;
+        let p0: number;
+        let p1: number;
+        if (isDate(value)) {
+          p0 = (continuous as TimeScale)(new Date(dataStart));
+          p1 = (continuous as TimeScale)(new Date(dataEnd));
+        } else {
+          p0 = (continuous as ContinuousScale)(dataStart);
+          p1 = (continuous as ContinuousScale)(dataEnd);
+        }
+        return { start: Math.min(p0, p1), length: Math.abs(p1 - p0) };
+      },
+    };
+  }
+
+  // Centered-cell layout for irregularly-spaced continuous data. Each cell
+  // is centred on its data value and extends half a cell extent in each
+  // direction. Edge cells may overflow the scale range — the layer clip
+  // rect clips to the plot frame, which gives geometrically-honest results
+  // (the cell's domain footprint legitimately extends past the visible
+  // domain). Truncating or shifting edge cells would cause half-sized or
+  // overlapping cells, both worse outcomes.
+  return {
+    rect: (value) => {
+      const half = domainExtent / 2;
+      let p0: number;
+      let p1: number;
+      if (isDate(value)) {
+        p0 = (continuous as TimeScale)(addDate(value as Date, -half));
+        p1 = (continuous as TimeScale)(addDate(value as Date, half));
+      } else {
+        const v = value as number;
+        if (!Number.isFinite(v)) return null;
+        p0 = (continuous as ContinuousScale)(v - half);
+        p1 = (continuous as ContinuousScale)(v + half);
+      }
+      return { start: Math.min(p0, p1), length: Math.abs(p1 - p0) };
+    },
+  };
+}
+
+/**
+ * Collect unique numeric (or epoch-ms Date) values from a channel accessor,
+ * returned as a sorted array. Shared by `detectGrid` and `inferCellExtent`.
+ */
+function valuesFromAes<T>(aes: { fn: (d: T, i: number) => unknown }, data: readonly T[]): number[] {
+  const seen = new Set<number>();
+  for (let i = 0; i < data.length; i++) {
+    const raw = aes.fn(data[i]!, i);
+    const n = isDate(raw) ? raw.getTime() : (raw as number);
+    if (typeof n === "number" && Number.isFinite(n) && !seen.has(n)) {
+      seen.add(n);
+    }
+  }
+  return [...seen].sort((a, b) => a - b);
+}
+
+/**
+ * Check whether a sorted array of values forms a regular arithmetic
+ * progression (equal gaps between every adjacent pair). When true, the
+ * tile data is effectively ordinal (e.g. hours 0–23, months 1–12) and
+ * an abutting-bin layout is safe and correct.
+ *
+ * Returns `[sortedValues, true]` for a regular grid, `[sortedValues, false]`
+ * otherwise. The sorted values are returned to avoid re-scanning.
+ */
+function detectGrid(sorted: number[], step: number): [sorted: number[], isRegular: boolean] {
+  if (sorted.length < 2) return [sorted, false];
+  const eps = Math.abs(step) * 1e-9;
+  for (let i = 1; i < sorted.length; i++) {
+    if (Math.abs(sorted[i]! - sorted[i - 1]! - step) > eps) {
+      return [sorted, false];
+    }
+  }
+  return [sorted, true];
+}
+
+/** Collect unique numeric (or epoch-ms Date) values from a channel accessor. */
+function numericValuesFromAes<T>(
+  aes: { fn: (d: T, i: number) => unknown },
+  data: readonly T[],
+): Set<number> {
+  const vals = new Set<number>();
+  for (let i = 0; i < data.length; i++) {
+    const raw = aes.fn(data[i]!, i);
+    const n = isDate(raw) ? raw.getTime() : (raw as number);
+    if (typeof n === "number" && Number.isFinite(n)) vals.add(n);
+  }
+  return vals;
+}
+
+function inferCellExtent<T>(
+  scale: AxisScale<unknown>,
+  aes: { fn: (d: T, i: number) => unknown },
+  data: readonly T[],
+): number {
+  const vals = numericValuesFromAes(aes, data);
+  if (vals.size < 2) {
+    // Fallback: 1% of the scale's domain extent — single-row datasets.
+    const dom = (scale as ContinuousScale).domain;
+    const span = Math.abs((dom[1] as number) - (dom[0] as number));
+    return span > 0 ? span * 0.01 : 1;
+  }
+  const sorted = [...vals].sort((a, b) => a - b);
+  let minGap = Infinity;
+  for (let i = 1; i < sorted.length; i++) {
+    const g = sorted[i]! - sorted[i - 1]!;
+    if (g > 0 && g < minGap) minGap = g;
+  }
+  return Number.isFinite(minGap) ? minGap : 1;
+}
+
+function addDate(d: Date, deltaMs: number): Date {
+  return new Date(d.getTime() + deltaMs);
+}
+
+function isFiniteValue(v: unknown): boolean {
+  if (typeof v === "number") return Number.isFinite(v);
+  if (isDate(v)) return Number.isFinite(v.getTime());
+  return v !== null && v !== undefined;
+}
+
+function isDate(v: unknown): v is Date {
+  return typeof v === "object" && v !== null && v instanceof Date;
+}
+
+function isBandScale(scale: AxisScale<unknown>): scale is BandScale<unknown> {
+  return "bandwidth" in scale;
+}
+
+// 8-bit-per-channel quantized RGBA — perceptually indistinguishable from full
+// precision for contrast resolution; collapses near-identical palette samples
+// onto a single cache slot.
+function quantizeColorKey(c: Color): string {
+  const r = (c.r * 255 + 0.5) | 0;
+  const g = (c.g * 255 + 0.5) | 0;
+  const b = (c.b * 255 + 0.5) | 0;
+  const a = (c.a * 255 + 0.5) | 0;
+  return `${r},${g},${b},${a}`;
+}