insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/connected-scatter.d.ts

@@ -0,0 +1,27 @@
+import type { Aes } from "../aes.ts";
+import { type LineOptions } from "./line.ts";
+import { type PointOptions } from "./point.ts";
+import type { Geom } from "./types.ts";
+export interface ConnectedScatterChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number | Date>;
+    color?: Aes<T, unknown>;
+    order: Aes<T, number | Date>;
+    size?: Aes<T, number>;
+    shape?: Aes<T, unknown>;
+    alpha?: Aes<T, number>;
+}
+export interface ConnectedScatterOptions {
+    /** Line-layer options. */
+    line?: LineOptions;
+    /** Point-layer options. Pass `false` to render only the connecting path. */
+    point?: PointOptions | false;
+}
+/**
+ * Grammar helper for the common "connected scatterplot" recipe:
+ * a path ordered by a third variable, optionally topped with points.
+ *
+ * Returns plain geoms so callers still compose with `.layer(text(...))`,
+ * `.annotate(...)`, facets, transitions, and the normal interaction stack.
+ */
+export declare function connectedScatter<T>(channels: ConnectedScatterChannels<T>, options?: ConnectedScatterOptions): readonly Geom<T>[];

package/src/grammar/geoms/connected-scatter.test.ts

@@ -0,0 +1,157 @@
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { connectedScatter } from "./connected-scatter.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+  series: string;
+  order: number;
+}
+
+const data: Row[] = [
+  { x: 0, y: 0, series: "a", order: 1 },
+  { x: 5, y: 10, series: "a", order: 2 },
+  { x: 10, y: 20, series: "a", order: 3 },
+];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("y");
+  const xScale = buildPositionScale(xAes, rows, [0, 100]);
+  const yScale = buildPositionScale(yAes, rows, [200, 0]);
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: 50, y: 30, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+/** Collect the polylines and circles emitted across a geom's compiled builders. */
+function captureShapes(
+  geom: { compile: (ctx: CompileContext<Row>) => readonly { addTo: (l: never) => void }[] },
+  ctx: CompileContext<Row>,
+): { polylines: Array<{ x: number; y: number }[]>; circles: Array<{ cx: number; cy: number }> } {
+  const polylines: Array<{ x: number; y: number }[]> = [];
+  const circles: Array<{ cx: number; cy: number }> = [];
+  const layer = {
+    pushPolyline({ points }: { points: Array<{ x: number; y: number }> }) {
+      polylines.push(points);
+    },
+    pushCircle(shape: { cx: number; cy: number }) {
+      circles.push(shape);
+    },
+  };
+  for (const builder of geom.compile(ctx)) builder.addTo(layer as never);
+  return { polylines, circles };
+}
+
+describe("connectedScatter geom — factory composition", () => {
+  test("default returns a line geom followed by a point geom", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    expect(geoms).toHaveLength(2);
+    expect(geoms[0]!.kind).toBe("line");
+    expect(geoms[1]!.kind).toBe("point");
+  });
+
+  test("point: false renders only the connecting path", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" }, { point: false });
+    expect(geoms).toHaveLength(1);
+    expect(geoms[0]!.kind).toBe("line");
+  });
+
+  test("threads x/y channels into both layers", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    for (const g of geoms) {
+      expect(g.channels.x).toBe("x");
+      expect(g.channels.y).toBe("y");
+    }
+  });
+
+  test("color channel propagates to both line and point", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order", color: "series" });
+    expect(geoms[0]!.channels.color).toBe("series");
+    expect(geoms[1]!.channels.color).toBe("series");
+  });
+
+  test("size/shape/alpha channels go only to the point layer", () => {
+    const geoms = connectedScatter<Row>({
+      x: "x",
+      y: "y",
+      order: "order",
+      size: "y",
+      shape: "series",
+      alpha: "y",
+    });
+    const pointGeom = geoms[1]!;
+    expect(pointGeom.channels.size).toBe("y");
+    expect(pointGeom.channels.shape).toBe("series");
+    expect(pointGeom.channels.alpha).toBe("y");
+    // The line layer carries none of these point-only channels.
+    expect(geoms[0]!.channels.size).toBeUndefined();
+    expect(geoms[0]!.channels.shape).toBeUndefined();
+    expect(geoms[0]!.channels.alpha).toBeUndefined();
+  });
+});
+
+describe("connectedScatter geom — compile output", () => {
+  test("line layer draws one ordered polyline through the scaled vertices", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    const ctx = makeCtx(data);
+    const { polylines } = captureShapes(geoms[0]!, ctx);
+    expect(polylines).toHaveLength(1);
+    // x: 0,5,10 over domain [0,10] → range [0,100] → 0,50,100; +plot.x(50).
+    expect(polylines[0]!.map((p) => p.x)).toEqual([50, 100, 150]);
+    // y: 0,10,20 over domain [0,20] → range [200,0] → 200,100,0; +plot.y(30).
+    expect(polylines[0]!.map((p) => p.y)).toEqual([230, 130, 30]);
+  });
+
+  test("ordering aesthetic sorts the path even when rows arrive unordered", () => {
+    const shuffled: Row[] = [
+      { x: 10, y: 20, series: "a", order: 3 },
+      { x: 0, y: 0, series: "a", order: 1 },
+      { x: 5, y: 10, series: "a", order: 2 },
+    ];
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    const { polylines } = captureShapes(geoms[0]!, makeCtx(shuffled));
+    expect(polylines).toHaveLength(1);
+    expect(polylines[0]!.map((p) => p.x)).toEqual([50, 100, 150]);
+  });
+
+  test("point layer emits one circle per datum at the scaled anchor", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    const { circles } = captureShapes(geoms[1]!, makeCtx(data));
+    expect(circles).toHaveLength(3);
+    expect(circles.map((c) => c.cx)).toEqual([50, 100, 150]);
+    expect(circles.map((c) => c.cy)).toEqual([230, 130, 30]);
+  });
+});
+
+describe("connectedScatter geom — edge cases", () => {
+  test("empty data: both layers compile to no drawn shapes", () => {
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    const ctx = makeCtx([]);
+    const line = captureShapes(geoms[0]!, ctx);
+    const points = captureShapes(geoms[1]!, ctx);
+    expect(line.polylines).toHaveLength(0);
+    expect(points.circles).toHaveLength(0);
+  });
+
+  test("single point: no polyline (one vertex), one circle", () => {
+    const single: Row[] = [{ x: 5, y: 10, series: "a", order: 1 }];
+    const geoms = connectedScatter<Row>({ x: "x", y: "y", order: "order" });
+    const ctx = makeCtx(single);
+    const line = captureShapes(geoms[0]!, ctx);
+    const points = captureShapes(geoms[1]!, ctx);
+    expect(line.polylines).toHaveLength(0);
+    expect(points.circles).toHaveLength(1);
+  });
+});

package/src/grammar/geoms/connected-scatter.ts

@@ -0,0 +1,63 @@
+import type { Aes } from "../aes.ts";
+import { line, type LineOptions } from "./line.ts";
+import { point, type PointOptions } from "./point.ts";
+import type { Geom } from "./types.ts";
+
+export interface ConnectedScatterChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+  color?: Aes<T, unknown>;
+  order: Aes<T, number | Date>;
+  size?: Aes<T, number>;
+  shape?: Aes<T, unknown>;
+  alpha?: Aes<T, number>;
+}
+
+export interface ConnectedScatterOptions {
+  /** Line-layer options. */
+  line?: LineOptions;
+  /** Point-layer options. Pass `false` to render only the connecting path. */
+  point?: PointOptions | false;
+}
+
+/**
+ * Grammar helper for the common "connected scatterplot" recipe:
+ * a path ordered by a third variable, optionally topped with points.
+ *
+ * Returns plain geoms so callers still compose with `.layer(text(...))`,
+ * `.annotate(...)`, facets, transitions, and the normal interaction stack.
+ */
+export function connectedScatter<T>(
+  channels: ConnectedScatterChannels<T>,
+  options: ConnectedScatterOptions = {},
+): readonly Geom<T>[] {
+  const out: Geom<T>[] = [
+    line(
+      {
+        x: channels.x,
+        y: channels.y,
+        color: channels.color,
+        order: channels.order,
+      },
+      options.line,
+    ),
+  ];
+
+  if (options.point !== false) {
+    out.push(
+      point(
+        {
+          x: channels.x,
+          y: channels.y,
+          color: channels.color,
+          size: channels.size,
+          shape: channels.shape,
+          alpha: channels.alpha,
+        },
+        options.point,
+      ),
+    );
+  }
+
+  return out;
+}

package/src/grammar/geoms/emphasis.d.ts

@@ -0,0 +1,76 @@
+/** Per-geom ordinal capacity / band width. See module header. */
+export declare const EMPHASIS_GEOM_STRIDE: number;
+/**
+ * Geom kinds whose hover dim-others treatment rides the core's ANIMATED GPU
+ * emphasis uniform (P5-T3): they tag each mark instance with a stable emphasis
+ * key at compile time (see {@link emphasisContext}), and the mount drives
+ * `renderer.setEmphasis({ focusedKey, dimAlpha, t })` from the hover signal —
+ * zero marks recompile per hover frame. A chart containing ANY of these (with
+ * hover enabled) pins its marks layer to `cache:"never"` (a bake would freeze
+ * the no-op emphasis; live marks let the uniform dim them — see the mount's
+ * `marksCacheHint`).
+ *
+ * `boxplot` / `violin` / `ridgeline` / `rug` joined this set once the core's
+ * emphasis dim reached `pushPolygon` (polygon-fill keys) — they tag a whole
+ * logical entity (box / violin / ridge row / tick) with ONE key so it dims as a
+ * unit. The remaining hover-INERT geoms are the `nearestX` curve geoms
+ * (`rolling`, `area`, whose compile-time halo updates only on a full frame) and
+ * `point` (its focus halo rides the overlay decorator). bar/histogram/tile/line
+ * ALSO carry overlay focus-halo decorators — dim + halo coexist: the dim is the
+ * global uniform, the halo is a `cache:"never"` overlay shape left at key 0
+ * (exempt) so it stays full-strength.
+ */
+export declare const GPU_DIM_GEOM_KINDS: ReadonlySet<string>;
+/**
+ * Largest geom index whose key band stays inside u32. `geomEmphasisBase(gi)` is
+ * `(gi+1) * 2^20`; `emphasisKeyFor` adds up to `(2^20 - 1) + 1 = 2^20`. So the
+ * max key for geom `gi` is `(gi+2) * 2^20`. The u32 ceiling is `2^32 - 1`, i.e.
+ * `4096 * 2^20`, so we need `(gi+2) * 2^20 <= 4096 * 2^20`, i.e. `gi <= 4094`.
+ * At `gi = 4094` the max key is exactly `4096 * 2^20 = 2^32`, which overflows
+ * u32 → wraps to 0 (the silent EXEMPT sentinel — a non-dimming hole). So the
+ * last SAFE geom index is `4093` and `gi >= 4094` is rejected by
+ * {@link geomEmphasisBase}.
+ */
+export declare const EMPHASIS_MAX_GEOM_INDEX = 4093;
+/**
+ * Disjoint emphasis-key band base for the geom at `geomIndex` in the chart's
+ * layer list (the pipeline's `gi`). `geomIndex + 1` so geom 0 starts at one
+ * full stride (key 0 stays the opt-out sentinel for axis / grid / overlay).
+ */
+export declare function geomEmphasisBase(geomIndex: number): number;
+/**
+ * Emphasis key for the `ordinal`-th participating instance of a geom whose band
+ * starts at `base`. `ordinal + 1` keeps the band's first instance off key 0.
+ * `ordinal` is taken mod the stride so a runaway count can never spill into the
+ * next geom's band (soundness floor — see module header).
+ */
+export declare function emphasisKeyFor(base: number, ordinal: number): number;
+/**
+ * A geom's hover-dim emphasis-key resolver, captured at compile time so the
+ * mount can map an active {@link HoveredHit} to the namespaced key it tagged
+ * its focused instance(s) with — WITHOUT recompiling. `geomKind` + `data`
+ * identity match the resolver to the hit (the same keys that route a hit to its
+ * geom, mirroring {@link GeomHoverDecorator}). `resolve` returns the focused
+ * key, or `null` when this hit focuses nothing in the geom (the mount then
+ * leaves emphasis settled). The geom computes the SAME ordinal it used to tag.
+ */
+export interface EmphasisResolver {
+    readonly geomKind: import("./types.ts").GeomKind;
+    readonly data: readonly unknown[];
+    resolve(hit: import("./types.ts").HoveredHit): number | null;
+}
+/**
+ * Build the per-frame emphasis context a dim-participating geom uses to tag and
+ * resolve. Returns `null` when emphasis is off (`emphasisBase` absent, e.g.
+ * SSR/SVG, or `theme.interactions.hover.enabled === false`) so callers cheaply
+ * skip all tagging. `ordinalOf` maps a hit (or an instance's identity) to the
+ * geom's ordinal — by default the hit's `dataIndex`, which every single-series
+ * dim geom (bar-single/histogram/boxplot/violin/tile/ridgeline/rug) already
+ * uses as its compile index. Multi-series geoms pass a custom `ordinalOf`.
+ */
+export declare function emphasisContext<T>(ctx: import("./types.ts").CompileContext<T>, kind: import("./types.ts").GeomKind, ordinalOf?: (hit: import("./types.ts").HoveredHit) => number | null): {
+    /** Namespaced key for the instance at `ordinal`. Tag marks with this. */
+    keyFor(ordinal: number): number;
+    /** Resolver to register so the mount can map a hit → focused key. */
+    resolver(): EmphasisResolver;
+} | null;

package/src/grammar/geoms/emphasis.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import {
+  EMPHASIS_GEOM_STRIDE,
+  EMPHASIS_MAX_GEOM_INDEX,
+  GPU_DIM_GEOM_KINDS,
+  emphasisContext,
+  emphasisKeyFor,
+  geomEmphasisBase,
+} from "./emphasis.ts";
+import { themeDefault } from "../theme.ts";
+import type { CompileContext, HoveredHit } from "./types.ts";
+
+describe("emphasis-key namespacing (P5-T3)", () => {
+  test("geom bands are disjoint full strides; geom 0 starts at one stride", () => {
+    expect(geomEmphasisBase(0)).toBe(EMPHASIS_GEOM_STRIDE);
+    expect(geomEmphasisBase(1)).toBe(2 * EMPHASIS_GEOM_STRIDE);
+    expect(geomEmphasisBase(2)).toBe(3 * EMPHASIS_GEOM_STRIDE);
+  });
+
+  test("keyFor offsets ordinal+1 so ordinal 0 never collides with the sentinel 0", () => {
+    const base = geomEmphasisBase(0);
+    expect(emphasisKeyFor(base, 0)).toBe(base + 1);
+    expect(emphasisKeyFor(base, 5)).toBe(base + 6);
+    // No geom's key is ever 0 (the EXEMPT/opt-out sentinel).
+    expect(emphasisKeyFor(geomEmphasisBase(0), 0)).toBeGreaterThan(0);
+  });
+
+  test("two distinct geoms never share a key for the same ordinal", () => {
+    const a = emphasisKeyFor(geomEmphasisBase(0), 3);
+    const b = emphasisKeyFor(geomEmphasisBase(1), 3);
+    expect(a).not.toBe(b);
+  });
+
+  test("ordinal at/over the stride wraps (stays inside the geom's band)", () => {
+    const base = geomEmphasisBase(0);
+    // ordinal === stride wraps to ordinal 0's key (mod), never spilling into geom 1.
+    expect(emphasisKeyFor(base, EMPHASIS_GEOM_STRIDE)).toBe(emphasisKeyFor(base, 0));
+    expect(emphasisKeyFor(base, EMPHASIS_GEOM_STRIDE)).toBeLessThan(geomEmphasisBase(1));
+  });
+
+  // Fix E — the key-band ceiling. At gi=4094 the MAX key reaches exactly 2^32 and
+  // wraps to 0 (the silent EXEMPT sentinel). So the last SAFE index is 4093.
+  test("the last safe geom index keeps its max key inside u32", () => {
+    expect(EMPHASIS_MAX_GEOM_INDEX).toBe(4093);
+    const base = geomEmphasisBase(EMPHASIS_MAX_GEOM_INDEX);
+    const maxKey = emphasisKeyFor(base, EMPHASIS_GEOM_STRIDE - 1);
+    // The largest key for the last safe geom is < 2^32 (no wrap).
+    expect(maxKey).toBeLessThan(2 ** 32);
+  });
+
+  test("geomEmphasisBase throws past the ceiling (would overflow u32 → exempt-0 hole)", () => {
+    expect(() => geomEmphasisBase(EMPHASIS_MAX_GEOM_INDEX)).not.toThrow();
+    expect(() => geomEmphasisBase(EMPHASIS_MAX_GEOM_INDEX + 1)).toThrow(RangeError);
+    expect(() => geomEmphasisBase(10000)).toThrow(/ceiling/);
+  });
+});
+
+describe("GPU_DIM_GEOM_KINDS (P5-T3 — single source of truth)", () => {
+  test("includes the four polygon-fill geoms plus the original four", () => {
+    expect([...GPU_DIM_GEOM_KINDS].sort()).toEqual(
+      ["bar", "boxplot", "histogram", "line", "ridgeline", "rug", "tile", "violin"].sort(),
+    );
+  });
+
+  test("excludes the deliberately hover-inert geoms (point / area / rolling)", () => {
+    expect(GPU_DIM_GEOM_KINDS.has("point")).toBe(false);
+    expect(GPU_DIM_GEOM_KINDS.has("area")).toBe(false);
+    expect(GPU_DIM_GEOM_KINDS.has("rolling")).toBe(false);
+  });
+});
+
+describe("emphasisContext", () => {
+  function ctx(over: Partial<CompileContext<unknown>> = {}): CompileContext<unknown> {
+    return {
+      data: [{}, {}, {}],
+      scales: {} as never,
+      plot: {} as never,
+      theme: themeDefault,
+      atlas: undefined,
+      emphasisBase: geomEmphasisBase(0),
+      ...over,
+    };
+  }
+  const hit = (dataIndex: number): HoveredHit => ({
+    geomKind: "bar",
+    dataIndex,
+    data: ctx().data,
+    x: 0,
+    y: 0,
+  });
+
+  test("returns null when emphasisBase is absent (SSR/SVG)", () => {
+    expect(emphasisContext(ctx({ emphasisBase: undefined }), "bar")).toBeNull();
+  });
+
+  test("returns null when hover emphasis is disabled in the theme", () => {
+    const theme = {
+      ...themeDefault,
+      interactions: {
+        ...themeDefault.interactions,
+        hover: { ...themeDefault.interactions.hover, enabled: false },
+      },
+    };
+    expect(emphasisContext(ctx({ theme }), "bar")).toBeNull();
+  });
+
+  test("keyFor uses the geom's band; default ordinalOf = hit.dataIndex", () => {
+    const data = [{}, {}, {}];
+    const c = ctx({ data });
+    const emph = emphasisContext(c, "bar")!;
+    const base = geomEmphasisBase(0);
+    expect(emph.keyFor(2)).toBe(emphasisKeyFor(base, 2));
+    const res = emph.resolver();
+    expect(res.geomKind).toBe("bar");
+    expect(res.data).toBe(data);
+    expect(res.resolve({ geomKind: "bar", dataIndex: 1, data, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(base, 1),
+    );
+  });
+
+  test("resolver rejects hits from a different geom kind or data array", () => {
+    const data = [{}, {}];
+    const emph = emphasisContext(ctx({ data }), "bar")!;
+    const res = emph.resolver();
+    expect(res.resolve({ geomKind: "tile", dataIndex: 0, data, x: 0, y: 0 })).toBeNull();
+    expect(res.resolve({ geomKind: "bar", dataIndex: 0, data: [{}], x: 0, y: 0 })).toBeNull();
+  });
+
+  test("custom ordinalOf returning null → resolver returns null (focuses nothing)", () => {
+    const data = [{}, {}];
+    const emph = emphasisContext(ctx({ data }), "bar", () => null)!;
+    expect(emph.resolver().resolve(hit(0))).toBeNull();
+  });
+});

package/src/grammar/geoms/emphasis.ts

@@ -0,0 +1,162 @@
+// ---------------------------------------------------------------------------
+// Emphasis-key namespacing (P5-T3 — animated GPU hover dim)
+// ---------------------------------------------------------------------------
+// Dim-participating geoms (bar / histogram / boxplot / violin / tile /
+// ridgeline / rug / line) tag each mark instance with a STABLE per-instance
+// emphasis key at compile time (hover-independent). The core renderer writes
+// that key into the instance's `lane4`; `renderer.setEmphasis({ focusedKey,
+// dimAlpha, t })` then dims — on the transparent/OIT path only — every TAGGED
+// instance whose key differs from `focusedKey`, animated by `t` 0→1. Zero marks
+// recompile per hover frame (the old "snap" rebake is gone).
+//
+// KEY NAMESPACING (the whole-frame budget). Keys are GLOBAL per frame across
+// every layer (one emphasis uniform), so two geoms must never collide. Each
+// geom gets a disjoint BASE band; the geom adds `ordinal + 1` within its band.
+//
+//   base(geomIndex) = (geomIndex + 1) * EMPHASIS_GEOM_STRIDE
+//   key(base, ordinal) = base + (ordinal mod EMPHASIS_GEOM_STRIDE) + 1
+//
+// The `+ 1` keeps key 0 reserved as the EXEMPT/opt-out sentinel (core contract:
+// a key-0 instance never dims). `geomIndex + 1` keeps geom 0 off the sentinel
+// band too. With a u32 emphasis key:
+//
+//   • EMPHASIS_GEOM_STRIDE = 2^20 → up to 1,048,575 distinct ordinals per geom
+//     (more than enough for per-row / per-segment marks; a chart with a million
+//     visible marks is already past the SDF instance budget).
+//   • geom band index up to 4093 (inclusive) per chart — the max key for geom
+//     `gi` is `(gi+2) * 2^20`, which must stay <= u32 max `2^32 - 1 < 4096*2^20`,
+//     so `gi <= 4094` keeps the BASE in range but `gi = 4094` makes the max KEY
+//     exactly `2^32` (wraps to 0, the silent EXEMPT sentinel). Hence the last
+//     SAFE index is 4093; `geomEmphasisBase` throws on `gi >= 4094` (which no
+//     real chart reaches). See `EMPHASIS_MAX_GEOM_INDEX`.
+//
+// An ordinal at or beyond the stride wraps (mod), trading a (cosmetic) dim
+// collision for never escaping the geom's band — soundness over fidelity at a
+// scale no real chart reaches. `ordinal` is whatever index the geom reports as
+// the hit's `dataIndex` (per row for bars/tiles/box/violin/ridgeline, the flat
+// cell counter for histogram) — so tagging and hit-resolution share one source.
+
+/** Per-geom ordinal capacity / band width. See module header. */
+export const EMPHASIS_GEOM_STRIDE = 2 ** 20;
+
+/**
+ * Geom kinds whose hover dim-others treatment rides the core's ANIMATED GPU
+ * emphasis uniform (P5-T3): they tag each mark instance with a stable emphasis
+ * key at compile time (see {@link emphasisContext}), and the mount drives
+ * `renderer.setEmphasis({ focusedKey, dimAlpha, t })` from the hover signal —
+ * zero marks recompile per hover frame. A chart containing ANY of these (with
+ * hover enabled) pins its marks layer to `cache:"never"` (a bake would freeze
+ * the no-op emphasis; live marks let the uniform dim them — see the mount's
+ * `marksCacheHint`).
+ *
+ * `boxplot` / `violin` / `ridgeline` / `rug` joined this set once the core's
+ * emphasis dim reached `pushPolygon` (polygon-fill keys) — they tag a whole
+ * logical entity (box / violin / ridge row / tick) with ONE key so it dims as a
+ * unit. The remaining hover-INERT geoms are the `nearestX` curve geoms
+ * (`rolling`, `area`, whose compile-time halo updates only on a full frame) and
+ * `point` (its focus halo rides the overlay decorator). bar/histogram/tile/line
+ * ALSO carry overlay focus-halo decorators — dim + halo coexist: the dim is the
+ * global uniform, the halo is a `cache:"never"` overlay shape left at key 0
+ * (exempt) so it stays full-strength.
+ */
+export const GPU_DIM_GEOM_KINDS: ReadonlySet<string> = new Set([
+  "bar",
+  "histogram",
+  "tile",
+  "line",
+  "boxplot",
+  "violin",
+  "ridgeline",
+  "rug",
+]);
+
+/**
+ * Largest geom index whose key band stays inside u32. `geomEmphasisBase(gi)` is
+ * `(gi+1) * 2^20`; `emphasisKeyFor` adds up to `(2^20 - 1) + 1 = 2^20`. So the
+ * max key for geom `gi` is `(gi+2) * 2^20`. The u32 ceiling is `2^32 - 1`, i.e.
+ * `4096 * 2^20`, so we need `(gi+2) * 2^20 <= 4096 * 2^20`, i.e. `gi <= 4094`.
+ * At `gi = 4094` the max key is exactly `4096 * 2^20 = 2^32`, which overflows
+ * u32 → wraps to 0 (the silent EXEMPT sentinel — a non-dimming hole). So the
+ * last SAFE geom index is `4093` and `gi >= 4094` is rejected by
+ * {@link geomEmphasisBase}.
+ */
+export const EMPHASIS_MAX_GEOM_INDEX = 4093;
+
+/**
+ * Disjoint emphasis-key band base for the geom at `geomIndex` in the chart's
+ * layer list (the pipeline's `gi`). `geomIndex + 1` so geom 0 starts at one
+ * full stride (key 0 stays the opt-out sentinel for axis / grid / overlay).
+ */
+export function geomEmphasisBase(geomIndex: number): number {
+  // Defensive guard: at `geomIndex >= 4094` the max emphasis KEY reaches/exceeds
+  // 2^32 and wraps to 0 (the EXEMPT sentinel) — a silent non-dimming hole. No
+  // real chart has 4094 geoms; reject it loudly rather than emit corrupt keys.
+  if (geomIndex >= EMPHASIS_MAX_GEOM_INDEX + 1) {
+    throw new RangeError(
+      `geomEmphasisBase: geomIndex ${geomIndex} exceeds the emphasis key-band ceiling ` +
+        `(${EMPHASIS_MAX_GEOM_INDEX}); keys would overflow u32 and wrap to the exempt sentinel.`,
+    );
+  }
+  return (geomIndex + 1) * EMPHASIS_GEOM_STRIDE;
+}
+
+/**
+ * Emphasis key for the `ordinal`-th participating instance of a geom whose band
+ * starts at `base`. `ordinal + 1` keeps the band's first instance off key 0.
+ * `ordinal` is taken mod the stride so a runaway count can never spill into the
+ * next geom's band (soundness floor — see module header).
+ */
+export function emphasisKeyFor(base: number, ordinal: number): number {
+  return base + (ordinal % EMPHASIS_GEOM_STRIDE) + 1;
+}
+
+/**
+ * A geom's hover-dim emphasis-key resolver, captured at compile time so the
+ * mount can map an active {@link HoveredHit} to the namespaced key it tagged
+ * its focused instance(s) with — WITHOUT recompiling. `geomKind` + `data`
+ * identity match the resolver to the hit (the same keys that route a hit to its
+ * geom, mirroring {@link GeomHoverDecorator}). `resolve` returns the focused
+ * key, or `null` when this hit focuses nothing in the geom (the mount then
+ * leaves emphasis settled). The geom computes the SAME ordinal it used to tag.
+ */
+export interface EmphasisResolver {
+  readonly geomKind: import("./types.ts").GeomKind;
+  readonly data: readonly unknown[];
+  resolve(hit: import("./types.ts").HoveredHit): number | null;
+}
+
+/**
+ * Build the per-frame emphasis context a dim-participating geom uses to tag and
+ * resolve. Returns `null` when emphasis is off (`emphasisBase` absent, e.g.
+ * SSR/SVG, or `theme.interactions.hover.enabled === false`) so callers cheaply
+ * skip all tagging. `ordinalOf` maps a hit (or an instance's identity) to the
+ * geom's ordinal — by default the hit's `dataIndex`, which every single-series
+ * dim geom (bar-single/histogram/boxplot/violin/tile/ridgeline/rug) already
+ * uses as its compile index. Multi-series geoms pass a custom `ordinalOf`.
+ */
+export function emphasisContext<T>(
+  ctx: import("./types.ts").CompileContext<T>,
+  kind: import("./types.ts").GeomKind,
+  ordinalOf: (hit: import("./types.ts").HoveredHit) => number | null = (hit) => hit.dataIndex,
+): {
+  /** Namespaced key for the instance at `ordinal`. Tag marks with this. */
+  keyFor(ordinal: number): number;
+  /** Resolver to register so the mount can map a hit → focused key. */
+  resolver(): EmphasisResolver;
+} | null {
+  const base = ctx.emphasisBase;
+  if (base === undefined || !ctx.theme.interactions.hover.enabled) return null;
+  const data = ctx.data as readonly unknown[];
+  return {
+    keyFor: (ordinal) => emphasisKeyFor(base, ordinal),
+    resolver: () => ({
+      geomKind: kind,
+      data,
+      resolve(hit) {
+        if (hit.geomKind !== kind || hit.data !== data) return null;
+        const ordinal = ordinalOf(hit);
+        return ordinal === null ? null : emphasisKeyFor(base, ordinal);
+      },
+    }),
+  };
+}