insomni-plot 0.1.0-alpha.0

package/src/grammar/pipeline.d.ts

@@ -0,0 +1,158 @@
+import type { Color, Frame, GlyphAtlas, Layer, Padding } from "insomni";
+import { type AxisOptions } from "../axis.ts";
+import { type AnnotationSpec } from "./annotations.ts";
+import { type FacetSpec } from "./facet.ts";
+import { type PointSwatchSpec } from "../legend.ts";
+import type { AxesSpec, AxisSpec, LegendMergeChannel, LegendSpec, TitleSpec } from "./chart.ts";
+import { type Coord } from "./coord.ts";
+import type { GrammarTransitions } from "./interactions/transitions.ts";
+import type { Geom, ScaleBundle } from "./geoms/index.ts";
+import { type Signal } from "insomni/reactivity";
+import { type AlphaScaleOptions, type BorderStyleScaleOptions, type ColorScaleOptions, type OverlayGlyphScaleOptions, type PositionScaleOptions, type ShapeScaleOptions, type SizeScaleOptions } from "./scales.ts";
+import { type Theme } from "./theme.ts";
+export interface ChartConfig<T> {
+    data: readonly T[] | Signal<readonly T[]>;
+    width: number | undefined;
+    height: number | undefined;
+    background: Color | undefined;
+    padding: Padding;
+    framePadding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    device: GPUDevice | undefined;
+    externalAtlas: GlyphAtlas | undefined;
+    theme: Theme;
+    layers: readonly Geom<T>[];
+    axes: AxesSpec;
+    titles: TitleSpec;
+    legend: LegendSpec;
+    scaleOverrides: {
+        x?: PositionScaleOptions;
+        y?: PositionScaleOptions;
+        color?: ColorScaleOptions<unknown>;
+        size?: SizeScaleOptions;
+        alpha?: AlphaScaleOptions;
+        shape?: ShapeScaleOptions;
+        borderStyle?: BorderStyleScaleOptions;
+        overlayGlyph?: OverlayGlyphScaleOptions;
+    };
+    annotations: readonly AnnotationSpec[];
+    facet?: FacetSpec<T>;
+    /**
+     * Coordinate system. Defaults to `coordCartesian()`. Threaded into
+     * `CompileContext.coord` and used to dispatch axis rendering.
+     */
+    coord: Coord;
+}
+export interface PipelineOutput<T = unknown> {
+    scales: ScaleBundle;
+    /** Hit-test contributions from any geom that implements `compileHitTest`. */
+    hitTests: import("./geoms/types.ts").CompiledHitTest<T>[];
+    /**
+     * Hover-focus decorators from geoms that implement `hoverDecoration` (point).
+     * The mount draws these into the overlay layer on hover — a cheap path that
+     * avoids recompiling the baked marks. Empty for geoms whose hover treatment
+     * is global (dim-others), which the mount handles via a marks re-bake.
+     * Faceted charts collect one decorator per (panel, geom), each closing over
+     * its panel's rows (P6-T3).
+     */
+    hoverDecorators: import("./geoms/types.ts").GeomHoverDecorator[];
+    /**
+     * Emphasis-key resolvers from dim-participating geoms (P5-T3). The mount maps
+     * an active hover hit to the geom's namespaced focused key and drives the
+     * core's animated GPU dim. Empty for charts with no dim geom. Faceted charts
+     * collect one resolver per (panel, geom) with a disjoint per-panel key band
+     * (P6-T3), so hovering one panel never dims another.
+     */
+    emphasisResolvers: import("./geoms/emphasis.ts").EmphasisResolver[];
+    /**
+     * Inset chart frame after outer padding — the area available to axes, slots,
+     * and the plot panel. Used to clip the hud layer so overlay marks (e.g. tip
+     * labels) don't bleed into the outer padding region.
+     */
+    outerFrame: Frame;
+    /**
+     * Plot drawing region in absolute element-CSS pixels (top-left of the plot
+     * frame, matching `Frame.topLeft`). For faceted charts this is the union
+     * of all panel frames — wide enough to enclose every panel — used by the
+     * crosshair to clip its guide line to the marks region.
+     */
+    plotFrame: Frame;
+    /**
+     * Position-scale range insets in CSS px (`framePadding` + per-geom
+     * `prepareRange` reservations). The position scales' pixel range is
+     * `[reserve.left, plotFrame.width - reserve.right]` (X) and
+     * `[plotFrame.height - reserve.bottom, reserve.top]` (Y). The mount feeds
+     * this into the data viewport via `setFrame(plotFrame, reserve)` so
+     * `dataToScreen` matches where marks render.
+     */
+    reserve: {
+        readonly left: number;
+        readonly right: number;
+        readonly top: number;
+        readonly bottom: number;
+    };
+    /**
+     * Per-panel plot frames for faceted charts (one entry per panel, in render
+     * order). Empty / undefined for non-faceted charts. Used by the crosshair
+     * to clip its guide line to the active panel rather than the chart-wide
+     * union frame. Coordinates match `plotFrame` (absolute element-CSS px).
+     */
+    panelFrames?: readonly Frame[];
+    /** Categorical legend builder and its placed origin (absolute CSS px). */
+    legend?: {
+        builder: import("../legend.ts").LegendBuilder;
+        origin: {
+            x: number;
+            y: number;
+        };
+    };
+}
+export declare function currentData<T>(data: readonly T[] | Signal<readonly T[]>): readonly T[];
+/**
+ * Optional tail bundle for {@link runPipeline}. Required core args
+ * (`config`, `data`, layers, `atlas`) stay positional; everything that varies
+ * per-frame lives here so call sites don't drift when fields are added.
+ */
+export interface RunPipelineOptions<T> {
+    hovered?: import("./geoms/types.ts").HoveredHit | null;
+    selected?: readonly import("./geoms/types.ts").HoveredHit[];
+    hidden?: ReadonlySet<string>;
+    legendDimAlpha?: number;
+    transitions?: GrammarTransitions;
+    transitionKey?: (datum: T, index: number) => string;
+}
+export declare function runPipeline<T>(config: ChartConfig<T>, data: readonly T[], axisLayer: Layer, marksLayer: Layer, hudLayer: Layer, atlas: GlyphAtlas | undefined, options?: RunPipelineOptions<T>): PipelineOutput<T>;
+/**
+ * Extract the existing scale's domain into a `PositionScaleOptions` that pins
+ * a new scale to the same input range — used to keep faceted panels aligned
+ * under `scales: "fixed"`.
+ *
+ * Exported for unit testing — not part of the public grammar surface.
+ */
+export declare function shareDomain(scale: ScaleBundle["x"]): PositionScaleOptions;
+/** @internal Exported for unit tests only. */
+export declare function makeAxisOptions(spec: AxisSpec | undefined, theme: Theme, atlas: GlyphAtlas | undefined): AxisOptions<unknown>;
+type LegendChannelScales = Omit<ScaleBundle, "x" | "y">;
+/**
+ * Build one point-style swatch for a merged legend entry. Resolves each
+ * listed channel's scale at `value` and composes the result into a single
+ * `PointSwatchSpec`. Channels listed in `mergeSet` but lacking an active
+ * scale are silently skipped — the merge declaration is the consumer's
+ * assertion that the channels exist *if* they're configured.
+ */
+export declare function composeMergedPointSwatch(value: unknown, color: Color, scales: LegendChannelScales, mergeSet: ReadonlySet<LegendMergeChannel>, theme: Theme): PointSwatchSpec;
+/**
+ * Detect which non-color channels share the color scale's categorical domain,
+ * so the legend can fold them into one row per entry without the consumer
+ * spelling out `merge: [...]`. A channel auto-merges when its scale exists AND
+ * its `.domain` is structurally equal to the color domain. `size` is numeric
+ * and never auto-merges; opt in via `legendSpec.merge` if you want it.
+ *
+ * Exported for testing.
+ */
+export declare function autoMergeChannels(colorDomain: readonly unknown[], scales: LegendChannelScales): LegendMergeChannel[];
+export {};

package/src/grammar/pipeline.test.ts

@@ -0,0 +1,463 @@
+// @vitest-environment jsdom
+import { createLayer } from "insomni";
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveAes } from "./aes.ts";
+import { plot } from "./chart.ts";
+import { coordPolar } from "./coord.ts";
+import { EMPHASIS_GEOM_STRIDE } from "./geoms/emphasis.ts";
+import type { ChannelSpec, CompileContext, Geom, HoveredHit } from "./geoms/types.ts";
+import { runPipeline, shareDomain, type ChartConfig } from "./pipeline.ts";
+import { buildPositionScale } from "./scales.ts";
+
+interface Row {
+  x: number;
+  y: number;
+}
+
+const data: Row[] = [
+  { x: 1, y: 2 },
+  { x: 2, y: 4 },
+];
+
+function recordingGeom(received: { ctx: CompileContext<Row> | null }): Geom<Row> {
+  const channels: ChannelSpec<Row> = { x: "x" as unknown, y: "y" as unknown };
+  return {
+    kind: "point",
+    channels,
+    compile(ctx) {
+      received.ctx = ctx;
+      return [];
+    },
+  };
+}
+
+interface ChartWithConfig {
+  __config__: ChartConfig<Row>;
+}
+
+function configFromChart<T extends ChartWithConfig>(chart: T): ChartConfig<Row> {
+  return chart.__config__;
+}
+
+describe("runPipeline — hovered context", () => {
+  it("threads `hovered: null` into compile context by default", () => {
+    const received: { ctx: CompileContext<Row> | null } = { ctx: null };
+    const chart = plot({ data, width: 400, height: 300 }).layer(recordingGeom(received));
+    const config = configFromChart(chart as unknown as ChartWithConfig);
+    const a = createLayer({ space: "ui" });
+    const m = createLayer({ space: "ui" });
+    const h = createLayer({ space: "ui" });
+    runPipeline(config, data, a, m, h, undefined);
+    expect(received.ctx).not.toBeNull();
+    expect(received.ctx!.hovered).toBeNull();
+  });
+
+  it("forwards a HoveredHit value into compile context", () => {
+    const received: { ctx: CompileContext<Row> | null } = { ctx: null };
+    const chart = plot({ data, width: 400, height: 300 }).layer(recordingGeom(received));
+    const config = configFromChart(chart as unknown as ChartWithConfig);
+    const a = createLayer({ space: "ui" });
+    const m = createLayer({ space: "ui" });
+    const h = createLayer({ space: "ui" });
+    const hovered: HoveredHit = {
+      geomKind: "point",
+      dataIndex: 1,
+      data,
+      x: 100,
+      y: 200,
+    };
+    runPipeline(config, data, a, m, h, undefined, { hovered });
+    expect(received.ctx?.hovered).toBe(hovered);
+    expect(received.ctx?.hovered?.dataIndex).toBe(1);
+  });
+});
+
+describe("runPipeline — emphasis (P5-T3)", () => {
+  it("threads a disjoint emphasisBase per geom (geomEmphasisBase(gi))", () => {
+    const r0: { ctx: CompileContext<Row> | null } = { ctx: null };
+    const r1: { ctx: CompileContext<Row> | null } = { ctx: null };
+    const chart = plot({ data, width: 400, height: 300 })
+      .layer(recordingGeom(r0))
+      .layer(recordingGeom(r1));
+    const config = configFromChart(chart as unknown as ChartWithConfig);
+    runPipeline(
+      config,
+      data,
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      undefined,
+    );
+    // Bands are disjoint and ascend with geom index.
+    expect(r0.ctx!.emphasisBase).toBeGreaterThan(0);
+    expect(r1.ctx!.emphasisBase).toBeGreaterThan(r0.ctx!.emphasisBase!);
+  });
+
+  it("collects emphasisResolvers from geoms that implement emphasisResolution", () => {
+    const resolverGeom: Geom<Row> = {
+      kind: "bar",
+      channels: { x: "x" as unknown, y: "y" as unknown },
+      compile: () => [],
+      emphasisResolution: (ctx) => ({
+        geomKind: "bar",
+        data: ctx.data,
+        resolve: () => (ctx.emphasisBase ?? 0) + 1,
+      }),
+    };
+    const chart = plot({ data, width: 400, height: 300 }).layer(resolverGeom);
+    const config = configFromChart(chart as unknown as ChartWithConfig);
+    const out = runPipeline(
+      config,
+      data,
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      undefined,
+    );
+    expect(out.emphasisResolvers).toHaveLength(1);
+    expect(out.emphasisResolvers[0]!.geomKind).toBe("bar");
+  });
+
+  it("emphasisResolvers is empty for a chart with no dim geom", () => {
+    const r: { ctx: CompileContext<Row> | null } = { ctx: null };
+    const chart = plot({ data, width: 400, height: 300 }).layer(recordingGeom(r));
+    const config = configFromChart(chart as unknown as ChartWithConfig);
+    const out = runPipeline(
+      config,
+      data,
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      createLayer({ space: "ui" }),
+      undefined,
+    );
+    expect(out.emphasisResolvers).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Faceted emphasis parity (P6-T3)
+// ---------------------------------------------------------------------------
+
+interface FacetRow {
+  panel: string;
+  x: number;
+  y: number;
+}
+
+// Two panels (a / b), two rows each, so the facet path runs >1 panel.
+const facetData: FacetRow[] = [
+  { panel: "a", x: 1, y: 2 },
+  { panel: "a", x: 2, y: 4 },
+  { panel: "b", x: 3, y: 6 },
+  { panel: "b", x: 4, y: 8 },
+];
+
+interface FacetConfigChart {
+  __config__: ChartConfig<FacetRow>;
+}
+
+function facetConfig<T extends FacetConfigChart>(chart: T): ChartConfig<FacetRow> {
+  return chart.__config__;
+}
+
+/**
+ * A dim-participating ("bar") geom that mirrors the real emphasis contract: it
+ * tags via `emphasisBase` (recording each compile ctx so tests can read the
+ * per-panel band) and exposes a resolver + decorator that close over the ctx's
+ * (panel-sliced) data. The resolver returns `base + dataIndex + 1`, matching the
+ * `emphasisKeyFor` convention, so panel bands are observable through it.
+ */
+function facetBarGeom(seen: { ctxs: CompileContext<FacetRow>[] }): Geom<FacetRow> {
+  return {
+    kind: "bar",
+    channels: { x: "x" as unknown, y: "y" as unknown },
+    compile(ctx) {
+      seen.ctxs.push(ctx);
+      return [];
+    },
+    emphasisResolution: (ctx) => ({
+      geomKind: "bar",
+      data: ctx.data,
+      resolve: (hit) =>
+        hit.geomKind === "bar" && hit.data === ctx.data
+          ? (ctx.emphasisBase ?? 0) + hit.dataIndex + 1
+          : null,
+    }),
+    hoverDecoration: (ctx) => ({
+      geomKind: "bar",
+      data: ctx.data,
+      decorate: () => {},
+    }),
+  };
+}
+
+// Stub atlas (measureText only) so the faceted strip's `pushText` succeeds in
+// jsdom. Mirrors `makeFakeTextAtlas` in axis.test.ts.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function fakeAtlas(): any {
+  return {
+    measureText(text: string, opts: { fontSize?: number }) {
+      const fs = opts.fontSize ?? 12;
+      return { width: text.length * fs * 0.6, height: fs };
+    },
+  };
+}
+
+function runFacetPipeline(
+  config: ChartConfig<FacetRow>,
+  data: readonly FacetRow[],
+  options?: Parameters<typeof runPipeline<FacetRow>>[6],
+) {
+  const atlas = fakeAtlas();
+  const axisLayer = createLayer({ space: "ui", atlas });
+  const marksLayer = createLayer({ space: "ui", atlas });
+  const hudLayer = createLayer({ space: "ui", atlas });
+  // The facet strip + axes call `pushText` (glyph shaping needs real atlas
+  // metrics we don't stub); we exercise emphasis collection, not text layout, so
+  // no-op the text path. Mirrors axis.test.ts's recording-layer trick.
+  for (const l of [axisLayer, hudLayer]) {
+    (l as unknown as { pushText: () => void }).pushText = () => {};
+  }
+  return runPipeline(config, data, axisLayer, marksLayer, hudLayer, atlas, options);
+}
+
+describe("runPipeline — faceted emphasis (P6-T3)", () => {
+  it("threads a disjoint emphasisBase per panel (no cross-panel collision)", () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2 });
+    runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    // One compile per panel (single geom × 2 panels).
+    expect(seen.ctxs).toHaveLength(2);
+    const baseA = seen.ctxs[0]!.emphasisBase;
+    const baseB = seen.ctxs[1]!.emphasisBase;
+    expect(baseA).toBeGreaterThan(0);
+    expect(baseB).toBeGreaterThan(0);
+    // effectiveGi = panelIndex * geomCount(1) + gi(0) → panelIndex.
+    expect(baseA).toBe(1 * EMPHASIS_GEOM_STRIDE); // geomEmphasisBase(0)
+    expect(baseB).toBe(2 * EMPHASIS_GEOM_STRIDE); // geomEmphasisBase(1)
+    // The two panels never share a band → a key from panel A can't land in B.
+    expect(baseA).not.toBe(baseB);
+  });
+
+  it("collects one emphasisResolver per panel; a panel-B hit resolves into B's band", () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2 });
+    const out = runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(out.emphasisResolvers).toHaveLength(2);
+
+    // Mirror the mount's `focusedKeyFor`: match a hit to its resolver via
+    // (geomKind, data identity). Faceted hits carry the panel's sliced rows.
+    const panelARows = seen.ctxs[0]!.data;
+    const panelBRows = seen.ctxs[1]!.data;
+    expect(panelARows).not.toBe(panelBRows);
+
+    function resolve(hit: HoveredHit): number {
+      for (const r of out.emphasisResolvers) {
+        if (r.geomKind === hit.geomKind && r.data === hit.data) return r.resolve(hit) ?? 0;
+      }
+      return 0;
+    }
+
+    const hitA: HoveredHit = { geomKind: "bar", dataIndex: 0, data: panelARows, x: 0, y: 0 };
+    const hitB: HoveredHit = { geomKind: "bar", dataIndex: 0, data: panelBRows, x: 0, y: 0 };
+    const keyA = resolve(hitA);
+    const keyB = resolve(hitB);
+
+    // Same ordinal, different panels → keys differ and land in their own bands.
+    expect(keyA).toBe(1 * EMPHASIS_GEOM_STRIDE + 1);
+    expect(keyB).toBe(2 * EMPHASIS_GEOM_STRIDE + 1);
+    expect(keyA).not.toBe(keyB);
+  });
+
+  it("collects one hoverDecorator per panel (focus-halo path)", () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2 });
+    const out = runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(out.hoverDecorators).toHaveLength(2);
+    // Each decorator closes over a distinct panel's rows.
+    const datas = out.hoverDecorators.map((d) => d.data);
+    expect(datas[0]).not.toBe(datas[1]);
+  });
+
+  it("hands each panel a distinct, frame-pinned coord (deferred-closure safe)", () => {
+    // Under polar facets, a geom's hoverDecoration closure captures `ctx.coord`
+    // and runs at hover time — after the facet loop has bound the SHARED coord
+    // to the last panel's frame. If every panel's ctx held that one shared
+    // instance, panel A's halo would project against panel B's centre. The
+    // pipeline now wraps the shared coord per panel (`frameBoundCoord`) so each
+    // ctx carries an independent, frame-pinned coord.
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .coord(coordPolar({ angleChannel: "x" }))
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2 });
+    runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(seen.ctxs).toHaveLength(2);
+    const coordA = seen.ctxs[0]!.coord!;
+    const coordB = seen.ctxs[1]!.coord!;
+    // Distinct instances — neither is the other, so a later panel's bind cannot
+    // poison an earlier panel's captured projection.
+    expect(coordA).not.toBe(coordB);
+    expect(coordA.kind).toBe("polar");
+
+    // Panel-stability under interleaving: projecting through A, then B, then A
+    // again yields A's SAME result both times (each call re-pins to its own
+    // frame). With a single shared coord, the B call would leave the coord bound
+    // to B's frame and corrupt A's second projection whenever the frames differ.
+    const p = { x: 30, y: 40 };
+    const a1 = coordA.project(p);
+    coordB.project(p);
+    const a2 = coordA.project(p);
+    expect(a2).toEqual(a1);
+  });
+
+  it("trips the existing key-band ceiling guard when panels × geoms overflows u32", () => {
+    // effectiveGi = panelIndex * geomCount + gi. With 4 geom layers per panel
+    // the guard (effectiveGi >= EMPHASIS_MAX_GEOM_INDEX + 1 = 4094) trips at
+    // panelIndex 1023, gi 2 (1023*4 + 2 = 4094) — so only ~1024 panels need to
+    // compile before the throw, not ~4094 (avoids flaking near vitest's 5s
+    // default under full-file scheduling). 1024 panels × 4 geoms reaches a max
+    // effectiveGi of 1023*4 + 3 = 4095 ≥ 4094, guaranteeing the overflow.
+    const geomCount = 4;
+    const panelCount = 1024; // max effectiveGi 1023*4 + 3 = 4095 ≥ 4094 → throws
+    const manyPanels: FacetRow[] = Array.from({ length: panelCount }, (_, i) => ({
+      panel: `p${i}`,
+      x: i,
+      y: i,
+    }));
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    let chart = plot({ data: manyPanels, width: 4000, height: 3000 });
+    for (let g = 0; g < geomCount; g++) chart = chart.layer(facetBarGeom(seen));
+    chart = chart.facet({ by: "panel", ncol: panelCount });
+    const config = facetConfig(chart as unknown as FacetConfigChart);
+    // geomEmphasisBase throws (RangeError) at effectiveGi 4094 — same guard the
+    // non-faceted path relies on, now reached by the faceted flattening.
+    expect(() => runFacetPipeline(config, manyPanels)).toThrow(/ceiling/);
+  }, 30_000); // vitest's 5s default so it never flakes on a busy CI runner. // Belt-and-braces: this builds ~1024 panels; give it generous headroom over
+});
+
+// ---------------------------------------------------------------------------
+// Faceted per-panel scales (ECS back-out regression — D1)
+// ---------------------------------------------------------------------------
+//
+// The ECS integration populated entities against the chart-wide scales while
+// geoms re-resolved against per-panel scales — so every panel rendered at the
+// chart-wide domain (the faceting mis-render P0 bug). With the back-out, geoms
+// read `ctx.scales` directly, and the facet path hands each panel a scale bundle
+// built from its OWN rows under `scales: "free"`. These assert the geom actually
+// receives that per-panel bundle.
+
+function domainOf(scale: { axisScale: unknown }): readonly unknown[] {
+  return (scale.axisScale as { domain: readonly unknown[] }).domain;
+}
+
+describe("runPipeline — faceted per-panel scales (D1 regression)", () => {
+  it('scales:"free" gives each panel a scale bundle built from its own rows', () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2, scales: "free" });
+    runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(seen.ctxs).toHaveLength(2);
+    const xA = domainOf(seen.ctxs[0]!.scales.x);
+    const xB = domainOf(seen.ctxs[1]!.scales.x);
+    const yA = domainOf(seen.ctxs[0]!.scales.y);
+    const yB = domainOf(seen.ctxs[1]!.scales.y);
+
+    // Panel a rows have x ∈ {1,2}, y ∈ {2,4}; panel b rows x ∈ {3,4}, y ∈ {6,8}.
+    // Under free scales the per-panel domains must differ — if every panel saw
+    // the chart-wide domain (the ECS bug) these would be equal.
+    expect(xA).not.toEqual(xB);
+    expect(yA).not.toEqual(yB);
+    // And each panel's max must track its own data, not the chart-wide max.
+    expect(Number(xB[xB.length - 1])).toBeGreaterThan(Number(xA[xA.length - 1]));
+    expect(Number(yB[yB.length - 1])).toBeGreaterThan(Number(yA[yA.length - 1]));
+  });
+
+  it('scales:"fixed" pins every panel to the shared chart-wide domain', () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2, scales: "fixed" });
+    runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(seen.ctxs).toHaveLength(2);
+    // Fixed: panels share the chart-wide domain so axes line up across panels.
+    expect(domainOf(seen.ctxs[0]!.scales.x)).toEqual(domainOf(seen.ctxs[1]!.scales.x));
+    expect(domainOf(seen.ctxs[0]!.scales.y)).toEqual(domainOf(seen.ctxs[1]!.scales.y));
+  });
+
+  it("each panel's geom sees its own sliced rows as ctx.data", () => {
+    const seen: { ctxs: CompileContext<FacetRow>[] } = { ctxs: [] };
+    const chart = plot({ data: facetData, width: 400, height: 300 })
+      .layer(facetBarGeom(seen))
+      .facet({ by: "panel", ncol: 2 });
+    runFacetPipeline(facetConfig(chart as unknown as FacetConfigChart), facetData);
+
+    expect(seen.ctxs).toHaveLength(2);
+    // ctx.data is the panel slice, not the full chart data.
+    expect(seen.ctxs[0]!.data).not.toBe(facetData);
+    expect(seen.ctxs[0]!.data.every((r) => r.panel === "a")).toBe(true);
+    expect(seen.ctxs[1]!.data.every((r) => r.panel === "b")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// shareDomain — faceted `scales: "fixed"` domain pinning
+// ---------------------------------------------------------------------------
+
+describe("shareDomain — scale-type preservation", () => {
+  const aes = resolveAes<Row, unknown>("x");
+
+  it("preserves a log scale type and passes its domain through", () => {
+    const data: Row[] = [
+      { x: 1, y: 0 },
+      { x: 1000, y: 0 },
+    ];
+    const scale = buildPositionScale(aes, data, [0, 300], { type: "log", domain: [1, 1000] });
+    expect(scale.type).toBe("log");
+
+    const shared = shareDomain(scale);
+    // A faceted log axis must stay log under scales:"fixed" — not silently
+    // collapse to linear.
+    expect(shared.type).toBe("log");
+    expect(shared.domain).toEqual([1, 1000]);
+  });
+
+  it("preserves band / time / sqrt and defaults the rest to linear", () => {
+    const catAes = resolveAes<{ c: string }, unknown>("c");
+    const bandScale = buildPositionScale(catAes, [{ c: "a" }, { c: "b" }], [0, 100], {
+      type: "band",
+      domain: ["a", "b"],
+    });
+    expect(shareDomain(bandScale).type).toBe("band");
+
+    const numData: Row[] = [
+      { x: 0, y: 0 },
+      { x: 100, y: 0 },
+    ];
+    const sqrtScale = buildPositionScale(aes, numData, [0, 100], {
+      type: "sqrt",
+      domain: [0, 100],
+    });
+    expect(shareDomain(sqrtScale).type).toBe("sqrt");
+
+    const linScale = buildPositionScale(aes, numData, [0, 100], {
+      type: "linear",
+      domain: [0, 100],
+    });
+    expect(shareDomain(linScale).type).toBe("linear");
+  });
+});