insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,43 @@
+import type { Color } from "insomni";
+import { type LineCurve, type LineDashStyle } from "../../marks.ts";
+import type { RollingAxis, RollingStatistic, RollingWindow } from "../../stats/rolling-window.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export interface StatRollingChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number>;
+    /** Categorical color channel — runs one rolling fit per group. */
+    color?: Aes<T, unknown>;
+}
+export interface StatRollingOptions<T> {
+    /** Sliding window. See `RollingWindow` — bare number = count, object for explicit unit. */
+    window: RollingWindow;
+    /** Default `"mean"`. */
+    statistic?: RollingStatistic<T>;
+    /** Default `"x"`. */
+    axis?: RollingAxis;
+    /** Rows failing the filter are dropped from every window and the output series. */
+    filter?: (datum: T, index: number) => boolean;
+    /** Line curve. Default `"linear"` — pre-smoothed data rarely needs another smoother. */
+    curve?: LineCurve;
+    /** Override the per-group stroke color. When `color` is set, defaults to the color scale. */
+    stroke?: Color;
+    strokeWidth?: number;
+    dashStyle?: LineDashStyle;
+    /**
+     * When true (default), hovering anywhere along the curve resolves to the
+     * nearest rolling point by x — the cursor reads off "the smoothed value
+     * here." Set false for Euclidean nearest within a small pickRadius.
+     *
+     * Hits always carry the synthetic {@link RollingPoint} (`{ x, y, count,
+     * sourceIndex }`) as `info.datum`, not the underlying source row — so a
+     * tooltip resolver can describe the *line's* value at the cursor (e.g.
+     * "14-day mean: 88.4 kg") rather than misattributing a source row's tooltip
+     * to a position on the smoothed curve. Branch on `info.mark === label` to
+     * format the rolling tooltip distinctly from sibling point/line layers.
+     */
+    nearestX?: boolean;
+    /** Used by the auto-legend and tooltip discrimination. Default `"rolling"`. */
+    label?: string;
+}
+export declare function statRolling<T>(channels: StatRollingChannels<T>, options: StatRollingOptions<T>): Geom<T>;

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

@@ -0,0 +1,217 @@
+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 { statRolling } from "./rolling.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  t: number;
+  v: number;
+}
+
+const data: Row[] = [
+  { t: 0, v: 1 },
+  { t: 1, v: 4 },
+  { t: 2, v: 2 },
+  { t: 3, v: 5 },
+  { t: 4, v: 3 },
+];
+
+function makeCtx<R extends Row>(rows: readonly R[]): CompileContext<R> {
+  const xAes = resolveAes<R, unknown>("t");
+  const yAes = resolveAes<R, unknown>("v");
+  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: 0, y: 0, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+describe("statRolling geom", () => {
+  test("kind + label default", () => {
+    const geom = statRolling<Row>({ x: "t", y: "v" }, { window: 1 });
+    expect(geom.kind).toBe("rolling");
+    expect(geom.label).toBe("rolling");
+  });
+
+  test("compile emits a single line builder for the rolling-mean series", () => {
+    const geom = statRolling<Row>({ x: "t", y: "v" }, { window: 3, statistic: "mean" });
+    const builders = geom.compile(makeCtx(data));
+    expect(builders.length).toBe(1);
+    expect(builders[0]!.length).toBe(data.length);
+  });
+
+  test("empty data → no builders, no hit-test", () => {
+    const geom = statRolling<Row>({ x: "t", y: "v" }, { window: 3 });
+    expect(geom.compile(makeCtx<Row>([]))).toEqual([]);
+    expect(geom.compileHitTest!(makeCtx<Row>([]))).toBeNull();
+  });
+
+  test("hit-test emits one position per rolling point at the curve's predicted y", () => {
+    const geom = statRolling<Row>({ x: "t", y: "v" }, { window: 1 });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.geomKind).toBe("rolling");
+    expect(hits.dataIndex.length).toBe(data.length);
+    // window=1 → identity for mean. Row 0: x=0 → px=0; v=1 maps to range
+    // start (200) because the y-scale's domain bottoms at v=1.
+    expect(hits.positions[0]).toBeCloseTo(0, 3);
+    expect(hits.positions[1]).toBeCloseTo(200, 3);
+    expect(hits.pickAxis).toBe("x");
+  });
+
+  test("hit-test datum is the synthetic rolling point, not the source row", () => {
+    const geom = statRolling<Row>({ x: "t", y: "v" }, { window: 1, statistic: "mean" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    // hit.data is the flat RollingPoint[] array, dataIndex is identity.
+    expect(hits.data.length).toBe(data.length);
+    for (let i = 0; i < hits.dataIndex.length; i++) {
+      expect(hits.dataIndex[i]).toBe(i);
+    }
+    const first = hits.data[0] as unknown as {
+      x: number;
+      y: number;
+      sourceIndex: number;
+      count: number;
+    };
+    expect(first.x).toBe(0);
+    expect(first.y).toBe(1);
+    expect(first.sourceIndex).toBe(0);
+    // Channel aes target the rolling point, so attachSeriesReadout reads the
+    // smoothed value rather than the source row's raw value.
+    expect(hits.channels.x!.fn(first as unknown as Row, 0)).toBe(0);
+    expect(hits.channels.y!.fn(first as unknown as Row, 0)).toBe(1);
+  });
+
+  test("filter excludes rows from both the windowed series and emitted hits", () => {
+    const tagged = data.map((d, i) => ({ ...d, keep: i % 2 === 0 })) as Array<
+      Row & { keep: boolean }
+    >;
+    const geom = statRolling<(typeof tagged)[number]>(
+      { x: "t", y: "v" },
+      { window: 1, filter: (d) => d.keep },
+    );
+    const builders = geom.compile(makeCtx(tagged));
+    // 3 even-index rows: 0, 2, 4.
+    expect(builders[0]!.length).toBe(3);
+    const hits = geom.compileHitTest!(makeCtx(tagged))!;
+    expect(hits.dataIndex.length).toBe(3);
+    // Each rolling hit's `sourceIndex` points back into the original tagged
+    // array — proves the filter's source-row tracking survived even though
+    // the hit's `dataIndex` is now an index into the rolling array itself.
+    const sourceIndices = (hits.data as unknown as readonly { sourceIndex: number }[])
+      .map((p) => p.sourceIndex)
+      .sort((a, b) => a - b);
+    expect(sourceIndices).toEqual([0, 2, 4]);
+  });
+
+  test("caches the rollingWindow output across compile passes for stable inputs", () => {
+    const channels = { x: (d: Row) => d.t, y: (d: Row) => d.v };
+    const options = { window: 3, statistic: "mean" as const };
+    const geom = statRolling<Row>(channels, options);
+    const ctx = makeCtx(data);
+    const b1 = geom.compile(ctx);
+    const b2 = geom.compile(ctx);
+    // Same length is a weak signal — but combined with the cache impl it
+    // verifies the second compile path didn't crash and reused the series.
+    expect(b1.length).toBe(b2.length);
+    // Recomputing with a fresh options object that differs by window value
+    // forces a cache miss; the geom still returns a builder.
+    const geom2 = statRolling<Row>(channels, { window: 5, statistic: "mean" });
+    expect(geom2.compile(ctx).length).toBe(1);
+  });
+
+  test("nearestX: false yields a tight pickRadius for Euclidean hover", () => {
+    const geom = statRolling<Row>(
+      { x: "t", y: "v" },
+      { window: 1, nearestX: false, strokeWidth: 2 },
+    );
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.pickAxis).toBeUndefined();
+    expect(hits.pickRadius).toBeLessThan(20);
+  });
+
+  test("color channel splits the series into one rolling fit per group", () => {
+    interface GRow extends Row {
+      g: string;
+    }
+    const grouped: GRow[] = [
+      { t: 0, v: 1, g: "a" },
+      { t: 1, v: 9, g: "b" },
+      { t: 2, v: 2, g: "a" },
+      { t: 3, v: 8, g: "b" },
+      { t: 4, v: 3, g: "a" },
+      { t: 5, v: 7, g: "b" },
+    ];
+    const geom = statRolling<GRow>(
+      { x: "t", y: "v", color: "g" },
+      { window: 1, statistic: "mean" },
+    );
+    const ctx: CompileContext<GRow> = {
+      data: grouped,
+      scales: {
+        x: buildPositionScale(resolveAes<GRow, unknown>("t"), grouped, [0, 100]),
+        y: buildPositionScale(resolveAes<GRow, unknown>("v"), grouped, [200, 0]),
+      },
+      plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+    const builders = geom.compile(ctx);
+    // Two groups → two line builders, three points each (window=1, identity).
+    expect(builders.length).toBe(2);
+    expect(builders[0]!.length).toBe(3);
+    expect(builders[1]!.length).toBe(3);
+
+    const hits = geom.compileHitTest!(ctx)!;
+    expect(hits.dataIndex.length).toBe(6);
+    expect(hits.seriesKey).toBeDefined();
+    // Each hit's RollingPoint.sourceIndex points back to the matching group
+    // in the original data — proves the per-group filter remap survived.
+    const points = hits.data as unknown as readonly { sourceIndex: number }[];
+    for (let i = 0; i < hits.dataIndex.length; i++) {
+      const sourceIdx = points[i]!.sourceIndex;
+      expect(hits.seriesKey![i]).toBe(grouped[sourceIdx]!.g);
+    }
+  });
+
+  test("color channel: ctx.hidden filters out toggled-off groups", () => {
+    interface GRow extends Row {
+      g: string;
+    }
+    const grouped: GRow[] = [
+      { t: 0, v: 1, g: "a" },
+      { t: 1, v: 9, g: "b" },
+      { t: 2, v: 2, g: "a" },
+      { t: 3, v: 8, g: "b" },
+    ];
+    const geom = statRolling<GRow>({ x: "t", y: "v", color: "g" }, { window: 1 });
+    const ctx: CompileContext<GRow> = {
+      data: grouped,
+      scales: {
+        x: buildPositionScale(resolveAes<GRow, unknown>("t"), grouped, [0, 100]),
+        y: buildPositionScale(resolveAes<GRow, unknown>("v"), grouped, [200, 0]),
+      },
+      plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+      hidden: new Set(["b"]),
+    };
+    const builders = geom.compile(ctx);
+    expect(builders.length).toBe(1);
+    const hits = geom.compileHitTest!(ctx)!;
+    // Only group "a" survives; two points.
+    expect(hits.dataIndex.length).toBe(2);
+    const points = hits.data as unknown as readonly { sourceIndex: number }[];
+    for (let i = 0; i < hits.dataIndex.length; i++) {
+      expect(grouped[points[i]!.sourceIndex]!.g).toBe("a");
+    }
+  });
+});

package/src/grammar/geoms/rolling.ts

@@ -0,0 +1,387 @@
+// ---------------------------------------------------------------------------
+// statRolling geom — sliding-window statistic rendered as a line
+// ---------------------------------------------------------------------------
+// Wraps `rollingWindow` so consumers can drop a rolling-mean / median / quantile
+// curve into a chart with a single `.layer(statRolling(...))` call, instead of
+// pre-computing the series and hand-writing a custom `Geom<T>` to render it.
+//
+// Mirrors the ggplot2 `stat_*` model: stat is a layer, the chart owns recompute
+// on data/scale change, and the consumer never sees the intermediate series.
+//
+// Grouping: when `channels.color` is set, the geom buckets rows by the
+// categorical color value and runs `rollingWindow` once per bucket, emitting
+// one line per group. Mirrors `smooth`'s grouping. Without `color`, behaves
+// as a single global fit.
+//
+// Caching: the geom closes over `data + options` and memoizes the last
+// rollingWindow output against (data ref, window, statistic, axis, filter
+// ref, x ref, y ref, color ref). Stable accessors → cache hits across compile
+// passes. Inline closures → cache misses (and the geom recomputes on every
+// dirty draw), so callers paying the per-frame cost should hoist accessors.
+//
+// Hoist-for-cache-warmth pattern (callers):
+//
+//   // module scope — re-used across renders
+//   const xAccessor = (d: Row) => d.timestamp;
+//   const yAccessor = (d: Row) => d.value;
+//
+//   statRolling(
+//     { x: xAccessor, y: yAccessor },
+//     { window: { value: 14, unit: "domain" }, statistic: "median" },
+//   );
+//
+// Inline `x: (d) => d.timestamp` works but recomputes the rolling series
+// every frame because each render creates a fresh function reference.
+// Same guidance applies to `smooth` once it grows an explicit cache.
+
+import type { Color } from "insomni";
+import { lineMark, type LineCurve, type LineDashStyle } from "../../marks.ts";
+import { rollingWindow, type RollingPoint } from "../../stats/rolling-window.ts";
+import type { RollingAxis, RollingStatistic, RollingWindow } from "../../stats/rolling-window.ts";
+import { groupBy } from "../../stats/index.ts";
+import { haloRing, inlineMark, wrapMark } from "./_mark.ts";
+import { dropNullCategoricalIndices, materialize, resolveAes } from "../aes.ts";
+import type { Aes, ResolvedAes } from "../aes.ts";
+import type { CompileContext, CompiledHitTest, Geom, ResolvedChannelMap } from "./types.ts";
+
+export interface StatRollingChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number>;
+  /** Categorical color channel — runs one rolling fit per group. */
+  color?: Aes<T, unknown>;
+}
+
+export interface StatRollingOptions<T> {
+  /** Sliding window. See `RollingWindow` — bare number = count, object for explicit unit. */
+  window: RollingWindow;
+  /** Default `"mean"`. */
+  statistic?: RollingStatistic<T>;
+  /** Default `"x"`. */
+  axis?: RollingAxis;
+  /** Rows failing the filter are dropped from every window and the output series. */
+  filter?: (datum: T, index: number) => boolean;
+  /** Line curve. Default `"linear"` — pre-smoothed data rarely needs another smoother. */
+  curve?: LineCurve;
+  /** Override the per-group stroke color. When `color` is set, defaults to the color scale. */
+  stroke?: Color;
+  strokeWidth?: number;
+  dashStyle?: LineDashStyle;
+  /**
+   * When true (default), hovering anywhere along the curve resolves to the
+   * nearest rolling point by x — the cursor reads off "the smoothed value
+   * here." Set false for Euclidean nearest within a small pickRadius.
+   *
+   * Hits always carry the synthetic {@link RollingPoint} (`{ x, y, count,
+   * sourceIndex }`) as `info.datum`, not the underlying source row — so a
+   * tooltip resolver can describe the *line's* value at the cursor (e.g.
+   * "14-day mean: 88.4 kg") rather than misattributing a source row's tooltip
+   * to a position on the smoothed curve. Branch on `info.mark === label` to
+   * format the rolling tooltip distinctly from sibling point/line layers.
+   */
+  nearestX?: boolean;
+  /** Used by the auto-legend and tooltip discrimination. Default `"rolling"`. */
+  label?: string;
+}
+
+interface GroupSeries {
+  key: unknown;
+  series: RollingPoint[];
+}
+
+// Cache slot keyed by (window, statistic, axis, filter, x, y, color). Holds
+// the per-group series map and a flat RollingPoint[] array. The flat array's
+// reference is held stable across all `compileHitTest` calls that resolve to
+// the same cell, so the hit-layer's slot-identity check (`s.hit.data ===
+// next.data` — `hit-layer.ts:296`) reuses the existing PointCloudNode
+// instead of tearing it down each redraw.
+interface CacheCell<T> {
+  data: readonly T[];
+  window: RollingWindow;
+  statistic: RollingStatistic<T> | undefined;
+  axis: RollingAxis | undefined;
+  filter: ((d: T, i: number) => boolean) | undefined;
+  x: Aes<T, number | Date>;
+  y: Aes<T, number>;
+  // oxlint-disable-next-line no-redundant-type-constituents -- Aes<T,unknown> expands to include unknown; | undefined is explicit intent for "no color accessor"
+  color: Aes<T, unknown> | undefined;
+  groups: GroupSeries[];
+  rollingData: RollingPoint[];
+  // `rollingData` start offset for each entry in `groups[i]`. Lets
+  // `compileHitTest` translate (group, i-within-group) → stable global
+  // index when emitting hits, even when `ctx.hidden` changes between calls.
+  groupOffsets: number[];
+}
+
+// Module-scope cache keyed on the data array reference. Sits OUTSIDE every
+// Geom instance: consumers that drive Monitor-style settings closures via
+// `mount({ build: () => buildChart() })` recreate `statRolling()` (and
+// every other Geom) on every frame — see `mount.ts:600`. A per-instance
+// cache resets each frame, breaks `hit-layer.ts:296`'s slot-identity fast
+// path, and forces a tear-down+rebuild of every hit slot every frame
+// (synthesizing a spurious `onHoverLeave` that hides the tooltip / drops
+// the halo). The module-scope cache survives Geom re-instantiation: as
+// long as the underlying `data` is reference-stable and the rolling
+// config matches by value, the same `rollingData` array is returned and
+// slot identity holds.
+//
+// One data array can host several rolling configs (different windows on
+// the same series, etc.), so we keep a small array per data. Bounded to
+// avoid pathological growth when a control sweeps continuously.
+const CELLS_PER_DATA_CAP = 8;
+const DATA_CACHE = new WeakMap<readonly unknown[], CacheCell<unknown>[]>();
+
+function windowEqual(a: RollingWindow, b: RollingWindow): boolean {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number") return a === b;
+  if (typeof a === "object" && typeof b === "object") {
+    return a.value === b.value && a.unit === b.unit;
+  }
+  return false;
+}
+
+function cellMatches<T>(
+  cell: CacheCell<T>,
+  data: readonly T[],
+  channels: StatRollingChannels<T>,
+  options: StatRollingOptions<T>,
+): boolean {
+  return (
+    cell.data === data &&
+    cell.x === channels.x &&
+    cell.y === channels.y &&
+    cell.color === channels.color &&
+    cell.filter === options.filter &&
+    cell.axis === options.axis &&
+    cell.statistic === options.statistic &&
+    windowEqual(cell.window, options.window)
+  );
+}
+
+function buildGroups<T>(
+  data: readonly T[],
+  colorAes: ResolvedAes<T, unknown> | undefined,
+): { key: unknown; rows: number[] }[] {
+  const indices = Array.from(data, (_d, i) => i);
+  if (!colorAes) return [{ key: undefined, rows: indices }];
+  // Drop null/undefined categorical rows up front so the rendered group set
+  // stays aligned with the color scale's domain (see aes.ts null policy).
+  const valid = dropNullCategoricalIndices(indices, colorAes, data);
+  const colorValues = materialize(colorAes, data);
+  const groups: { key: unknown; rows: number[] }[] = [];
+  for (const [key, rows] of groupBy(valid, (i) => colorValues[i])) {
+    groups.push({ key, rows });
+  }
+  return groups;
+}
+
+export function statRolling<T>(
+  channels: StatRollingChannels<T>,
+  options: StatRollingOptions<T>,
+): Geom<T> {
+  const computeCache = (data: readonly T[]): CacheCell<T> => {
+    // Consult the module-level WeakMap first so Geom re-instantiation
+    // (closure-driven `build()` callbacks recompose the chart on every
+    // frame) doesn't reset our cache. Match by value on the cache key
+    // fields — accessor identity stays the rule for `x/y/color/filter`,
+    // but the wrapping `options` object is fresh each frame even when
+    // its fields haven't changed.
+    let cells = DATA_CACHE.get(data as readonly unknown[]) as CacheCell<T>[] | undefined;
+    if (cells) {
+      for (let i = 0; i < cells.length; i++) {
+        const candidate = cells[i]!;
+        if (cellMatches(candidate, data, channels, options)) {
+          // MRU bump so eviction targets the truly-cold entries.
+          if (i !== cells.length - 1) {
+            cells.splice(i, 1);
+            cells.push(candidate);
+          }
+          return candidate;
+        }
+      }
+    }
+    const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+    const yAes = resolveAes<T, number>(channels.y);
+    const colorAes = channels.color ? resolveAes<T, unknown>(channels.color) : undefined;
+    const rowGroups = buildGroups(data, colorAes);
+
+    const userFilter = options.filter;
+    const groups: GroupSeries[] = [];
+    for (const group of rowGroups) {
+      const memberSet = colorAes ? new Set(group.rows) : null;
+      const combinedFilter = (datum: T, i: number) => {
+        if (memberSet && !memberSet.has(i)) return false;
+        if (userFilter && !userFilter(datum, i)) return false;
+        return true;
+      };
+      const series = rollingWindow(data, {
+        x: (d, i) => {
+          const v = xAes.fn(d, i);
+          return v instanceof Date ? v : (v as number);
+        },
+        y: (d, i) => yAes.fn(d, i),
+        window: options.window,
+        statistic: options.statistic,
+        filter: combinedFilter,
+        axis: options.axis,
+      });
+      groups.push({ key: group.key, series });
+    }
+
+    // Build the flat rolling-point array + per-group offsets once. Both are
+    // held stable on the cache cell so hover state persists across redraws.
+    let total = 0;
+    const groupOffsets: number[] = Array.from({ length: groups.length });
+    for (let i = 0; i < groups.length; i++) {
+      groupOffsets[i] = total;
+      total += groups[i]!.series.length;
+    }
+    const rollingData: RollingPoint[] = Array.from({ length: total });
+    for (let gi = 0; gi < groups.length; gi++) {
+      const series = groups[gi]!.series;
+      const offset = groupOffsets[gi]!;
+      for (let i = 0; i < series.length; i++) {
+        rollingData[offset + i] = series[i]!;
+      }
+    }
+
+    const fresh: CacheCell<T> = {
+      data,
+      window: options.window,
+      statistic: options.statistic,
+      axis: options.axis,
+      filter: options.filter,
+      x: channels.x,
+      y: channels.y,
+      color: channels.color,
+      groups,
+      rollingData,
+      groupOffsets,
+    };
+    if (!cells) {
+      cells = [];
+      DATA_CACHE.set(data as readonly unknown[], cells as CacheCell<unknown>[]);
+    }
+    cells.push(fresh);
+    if (cells.length > CELLS_PER_DATA_CAP) cells.shift();
+    return fresh;
+  };
+
+  const computeGroups = (data: readonly T[]): GroupSeries[] => computeCache(data).groups;
+
+  return {
+    kind: "rolling",
+    channels,
+    label: options.label ?? "rolling",
+    compile(ctx: CompileContext<T>) {
+      const groups = computeGroups(ctx.data);
+      if (groups.length === 0) return [];
+      const xScale = ctx.scales.x.fn as (v: number) => number;
+      const yScale = ctx.scales.y.fn as (v: number) => number;
+      const colorScale = ctx.scales.color?.fn;
+      const hasColor = channels.color !== undefined;
+      const baseStroke = options.stroke ?? ctx.theme.palettes.categorical(0);
+      const strokeWidth = options.strokeWidth ?? ctx.theme.marks.strokeWidth;
+
+      const builders: ReturnType<typeof wrapMark>[] = [];
+      for (const group of groups) {
+        if (group.series.length === 0) continue;
+        if (hasColor && ctx.hidden && ctx.hidden.has(String(group.key))) continue;
+        const stroke =
+          options.stroke ??
+          (hasColor && colorScale ? (colorScale(group.key) as Color) : baseStroke);
+        const mark = lineMark(group.series, {
+          x: (p) => xScale(p.x),
+          y: (p) => yScale(p.y),
+          stroke,
+          strokeWidth,
+          curve: options.curve ?? "linear",
+          dashStyle: options.dashStyle,
+        });
+        builders.push(wrapMark(mark, ctx.plot.topLeft, group.series.length));
+      }
+
+      // Hover halo at the rolling point under the cursor. `ctx.hovered.x/y`
+      // are absolute element-CSS pixels, already on the smoothed line — the
+      // ring lands exactly on the point the tooltip is describing.
+      if (ctx.hovered && ctx.hovered.geomKind === "rolling") {
+        const cx = ctx.hovered.x;
+        const cy = ctx.hovered.y;
+        if (Number.isFinite(cx) && Number.isFinite(cy)) {
+          const sk = ctx.hovered.seriesKey;
+          const ringColor: Color =
+            sk !== undefined && hasColor && colorScale ? (colorScale(sk) as Color) : baseStroke;
+          const r = Math.max(4, strokeWidth * 1.5 + 2);
+          builders.push(inlineMark((layer) => haloRing(layer, cx, cy, r, ringColor, 2)));
+        }
+      }
+      return builders;
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const cell = computeCache(ctx.data);
+      const groups = cell.groups;
+      if (groups.length === 0) return null;
+      const xScale = ctx.scales.x.fn as (v: number) => number;
+      const yScale = ctx.scales.y.fn as (v: number) => number;
+      const ox = ctx.plot.topLeft.x;
+      const oy = ctx.plot.topLeft.y;
+      const hasColor = channels.color !== undefined;
+      const totalCached = cell.rollingData.length;
+      if (totalCached === 0) return null;
+
+      // Emit one hit per visible rolling point. `dataIndex[i]` is the index
+      // into the *cached* flat `rollingData` (stable reference across redraws
+      // — preserves the hit-layer's slot identity); `positions` are recomputed
+      // each call against the current scale.
+      const positions = new Float32Array(totalCached * 2);
+      const dataIndex = new Int32Array(totalCached);
+      const seriesKey: (string | undefined)[] = Array.from({ length: totalCached });
+      let n = 0;
+      for (let gi = 0; gi < groups.length; gi++) {
+        const group = groups[gi]!;
+        if (hasColor && ctx.hidden && ctx.hidden.has(String(group.key))) continue;
+        const offset = cell.groupOffsets[gi]!;
+        const key = hasColor ? String(group.key) : undefined;
+        for (let i = 0; i < group.series.length; i++) {
+          const p = group.series[i]!;
+          const px = xScale(p.x);
+          const py = yScale(p.y);
+          if (!Number.isFinite(px) || !Number.isFinite(py)) continue;
+          positions[n * 2] = ox + px;
+          positions[n * 2 + 1] = oy + py;
+          dataIndex[n] = offset + i;
+          seriesKey[n] = key;
+          n++;
+        }
+      }
+      if (n === 0) return null;
+
+      // Channel aes target the rolling points, not the source rows. Keeps
+      // `attachSeriesReadout` honest: the readout panel reads `xAes.fn(datum)`
+      // and `yAes.fn(datum)` over `hit.data` — they need to return the
+      // rolling point's smoothed value, not whatever source row happens to
+      // share the index.
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: { kind: "accessor", fn: (p) => (p as RollingPoint).x } as ResolvedAes<T, unknown>,
+        y: { kind: "accessor", fn: (p) => (p as RollingPoint).y } as ResolvedAes<T, unknown>,
+      };
+
+      const strokeWidth = options.strokeWidth ?? ctx.theme.marks.strokeWidth;
+      const nearestX = options.nearestX ?? true;
+      const pickRadius = nearestX
+        ? Math.max(ctx.plot.width, ctx.plot.height)
+        : Math.max(8, strokeWidth * 2 + 4);
+
+      return {
+        geomKind: "rolling",
+        label: options.label ?? "rolling",
+        positions: positions.subarray(0, n * 2),
+        dataIndex: dataIndex.subarray(0, n),
+        seriesKey: hasColor ? seriesKey.slice(0, n) : undefined,
+        pickRadius,
+        pickAxis: nearestX ? "x" : undefined,
+        channels: channelsMap,
+        data: cell.rollingData as readonly unknown[] as readonly T[],
+      };
+    },
+  };
+}

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

@@ -0,0 +1,28 @@
+import type { Color } from "insomni";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export interface RugChannels<T> {
+    x?: Aes<T, number | Date>;
+    y?: Aes<T, number | Date>;
+    /** Categorical color split for the ticks. */
+    color?: Aes<T, unknown>;
+}
+export type RugSide = "x" | "y" | "both";
+export interface RugOptions {
+    /**
+     * Which edges receive ticks. Defaults to whichever channels are wired —
+     * with both `x` and `y`, both edges; otherwise just the matching edge.
+     * Use `"both"` to force both edges (mirrors x onto bottom, y onto left).
+     */
+    side?: RugSide;
+    /** Tick length in pixels. Default `6`. */
+    length?: number;
+    /** Tick stroke width. Default `1`. */
+    strokeWidth?: number;
+    /** Override stroke color (defaults to theme.axis.color). */
+    stroke?: Color;
+    /** Multiplier on the resolved stroke alpha. Default `0.6`. */
+    opacity?: number;
+    label?: string;
+}
+export declare function rug<T>(channels: RugChannels<T>, options?: RugOptions): Geom<T>;