@fundar/data-chart-telling 1.17.0 → 1.18.0

package/dist/markers/hover/HoverMarker.svelte

@@ -1,283 +1,25 @@
 <script lang="ts">
 	import { usePlot } from '../../layout/plot/usePlot';
-	import DotMarker from '../dot/DotMarker.svelte';
-	import TextMarker from '../text/TextMarker.svelte';
-	import RuleMarker from '../rule/RuleMarker.svelte';
-	import BarMarker from '../bar/BarMarker.svelte';
-	import { getConfiguration } from '../../configuration/config.svelte';
-	import { NumberFormat } from '../../utils/NumberFormat';
-	import { BandNudge } from '../utils/BandNudge';
-	import type { BandSlice } from '../../types/layout/hover';
-	import type { HoverMarkerConfig } from '../../types/markers/common';
+	import { PointPixel } from '../utils/PointPixel';
 	import type { HoverDisplayPoint } from '../../types/layout/hover';
 
 	/**
-	 * In-SVG hover highlight, rendered *inside* a `<Plot>`. Because it positions
-	 * itself through the host plot's scales, it places the same coordinate
-	 * correctly in every facet - that is what makes cross-facet sync work without
-	 * any pixel math. Draws optional x/y crosshair rules plus a dot + value label
-	 * for each matched point.
-	 *
-	 * Takes the raw `marker` config plus the couple of things it can't know on
-	 * its own - `activePoint` (the specific matched point actually under the
-	 * cursor, for the crosshair position; see `controller.svelte.ts`'s own doc
-	 * comment) and whether the active hover strategy implies a crosshair on
-	 * each axis by default - the same "component owns its own rendering"
-	 * pattern `BarMarker`/`RuleMarker` follow. `activePoint`/
-	 * `impliesCrosshairX`/`impliesCrosshairY` are all optional and default to
-	 * "no crosshair".
-	 *
-	 * `areaX`/`areaY` are a separate, always-explicit opt-in (no implied
-	 * default) for a thickened area highlight in place of the thin crosshair -
-	 * see `HoverMarkerConfig`'s own doc comment. Rendered via `BarMarker`'s
-	 * `role: 'highlight'`, so it renders nothing on an axis without a band
-	 * scale (e.g. a line/scatter plot's continuous axis).
+	 * Where the hover is, rendered *inside* a `<Plot>`: it reports the pixel position of the point under the pointer,
+	 * through the host plot's scales, so a synced plot's tooltip can sit on it. It draws nothing itself - the
+	 * `hover` marker's `back` and `front` markers are drawn by `GeometryLayout`, as every other marker.
 	 */
 	interface Props {
-		data?: HoverDisplayPoint[];
-		/** Narrowed to just the fields this component reads - `HoverMarkerConfig` also carries routing/scoping fields (`series`/`scope`/`strategy`/`sync`) it has no use for. */
-		marker: Pick<
-			HoverMarkerConfig,
-			| 'ruleX'
-			| 'ruleY'
-			| 'areaX'
-			| 'areaY'
-			| 'showLabels'
-			| 'format'
-			| 'rule'
-			| 'area'
-			| 'dot'
-			| 'text'
-			| 'decimals'
-			| 'prefix'
-			| 'suffix'
-			| 'signDisplay'
-		>;
 		activePoint?: HoverDisplayPoint | null;
-		impliesCrosshairX?: boolean;
-		impliesCrosshairY?: boolean;
-		/** Reports `activePoint`'s real pixel position within this facet's own box, or `null` when nothing's matched. */
+		/** Reports `activePoint`'s pixel position within this facet's own box, or `null` when nothing's matched. */
 		onActivePointPixel?: (pos: { x: number; y: number } | null) => void;
 	}
 
-	let {
-		data = [],
-		marker,
-		activePoint = null,
-		impliesCrosshairX = false,
-		impliesCrosshairY = false,
-		onActivePointPixel
-	}: Props = $props();
-
-	const cfg = $derived(getConfiguration());
+	let { activePoint = null, onActivePointPixel }: Props = $props();
 	const plot = usePlot().svelteplot;
 
-	/** Scaled pixel position of `value`, centered within its band for a band scale. */
-	function scaledPixel(
-		scale: { type?: string; fn?: (v: never) => unknown } | undefined,
-		value: unknown
-	): number | null {
-		if (!scale?.fn || value == null) return null;
-		const raw = Number(scale.fn(value as never));
-		if (!Number.isFinite(raw)) return null;
-		if (scale.type === 'band') {
-			const bandwidth = (scale.fn as { bandwidth?: () => number }).bandwidth?.() ?? 0;
-			return raw + bandwidth / 2;
-		}
-		return raw;
-	}
-
-	const nudgeOf = (point: { areaInset?: BandSlice } | null | undefined) =>
-		BandNudge.of(plot.scales, point?.areaInset);
-
-	const activePixel = $derived.by((): { x: number; y: number } | null => {
-		if (!activePoint) return null;
-		const x = scaledPixel(plot.scales.x, activePoint.x);
-		const y = scaledPixel(plot.scales.y, activePoint.y);
-		if (x == null || y == null) return null;
-		const nudge = nudgeOf(activePoint);
-		return { x: x + nudge.dx, y: y + nudge.dy };
-	});
+	const activePixel = $derived(activePoint ? PointPixel.of(plot.scales, activePoint) : null);
 
 	$effect(() => {
 		onActivePointPixel?.(activePixel);
 	});
-
-	const showCrosshairX = $derived(
-		marker.ruleX !== false && (impliesCrosshairX || marker.ruleX === true)
-	);
-	const showCrosshairY = $derived(
-		marker.ruleY !== false && (impliesCrosshairY || marker.ruleY === true)
-	);
-	const ruleX = $derived(showCrosshairX ? (activePoint?.x ?? null) : null);
-	const ruleY = $derived(showCrosshairY ? (activePoint?.y ?? null) : null);
-	// areaX/areaY have no implied default - always off unless explicitly set.
-	const areaX = $derived(marker.areaX === true ? (activePoint?.x ?? null) : null);
-	const areaY = $derived(marker.areaY === true ? (activePoint?.y ?? null) : null);
-	/**
-	 * The part of the band an area covers: the active point's own slice (a grouped bar's series), or the whole
-	 * band while the hover matches more than one point in that category, as its dots do.
-	 */
-	const areaInsetOf = (axis: 'x' | 'y'): BandSlice | undefined => {
-		const at = activePoint?.[axis];
-		const key = (value: unknown) => (value instanceof Date ? +value : value);
-		const shared = data.filter((point) => key(point[axis]) === key(at)).length > 1;
-		return shared ? undefined : activePoint?.areaInset;
-	};
-	const areaInsetX = $derived(areaX != null ? areaInsetOf('x') : undefined);
-	const areaInsetY = $derived(areaY != null ? areaInsetOf('y') : undefined);
-	const showLabels = $derived(marker.showLabels ?? true);
-	const format = $derived(marker.format);
-	/** The hovered value as the marker's display fields ask; `undefined` while nothing does, so the plot's own label stays. */
-	const numberOf = $derived(NumberFormat.maybe(NumberFormat.displayOf(marker), cfg));
-	const number = $derived(numberOf ?? NumberFormat.of(undefined, cfg));
-	const labelOf = (d: HoverDisplayPoint): string => {
-		if (format) return format(d, number);
-		const value = Number(d.label);
-		return numberOf && d.label !== undefined && d.label !== '' && Number.isFinite(value)
-			? numberOf(value)
-			: (d.label ?? '');
-	};
-	const ruleStyle = $derived(marker.rule);
-	const areaStyle = $derived({ ...cfg.hover.area, ...marker.area });
-	const dotStyle = $derived(marker.dot);
-	const fontStyle = $derived(marker.text);
-
-	/** Explicit style wins; otherwise fall back to the point's own resolved color. */
-	const resolveColor = (explicit: string | undefined, point: HoverDisplayPoint) =>
-		explicit ?? point.color;
-
-	// Horizontal gap between the dot's edge and an 'outside'-anchored label -
-	// scales with the dot's own resolved radius so the label clears it.
-	const dotRadius = $derived(dotStyle?.dotRadius ?? cfg.hover.dot.dotRadius ?? 5);
-
-	/**
-	 * Resolves `text.textAnchor: 'outside'` into a per-point anchor +
-	 * offset, mirroring the value-label `'outside'` anchor's own left/right
-	 * split (see pyramid/bar's own `ValueAnchor` handling): a positive `x`
-	 * anchors `'start'` and nudges right, a negative `x` anchors `'end'` and
-	 * nudges left - so a diverging mark's label sits on the side of the dot
-	 * away from zero, on whichever side that dot itself landed. Only
-	 * meaningful when the point's `x` is numeric (e.g. pyramid's magnitude
-	 * axis); anything else falls through to the plain `text` style unchanged.
-	 *
-	 * Also overrides `cfg.hover.font`'s default `dy: -18` (meant for a label
-	 * floating *above* the dot) back to vertically centered, and clears the
-	 * dot's own radius horizontally instead of the flat default nudge, so the
-	 * label doesn't collide with the dot it's labeling.
-	 */
-	function resolveFontStyle(point: HoverDisplayPoint) {
-		if (fontStyle?.textAnchor !== 'outside' || typeof point.x !== 'number') {
-			return { ...cfg.hover.font, ...fontStyle, fill: resolveColor(fontStyle?.fill, point) };
-		}
-		const outward = point.x >= 0;
-		const gap = dotRadius + 5;
-		return {
-			...cfg.hover.font,
-			...fontStyle,
-			fill: resolveColor(fontStyle?.fill, point),
-			textAnchor: outward ? ('start' as const) : ('end' as const),
-			lineAnchor: fontStyle?.lineAnchor ?? ('middle' as const),
-			dx: fontStyle?.dx ?? (outward ? gap : -gap),
-			dy: fontStyle?.dy ?? 0
-		};
-	}
 </script>
-
-{#if areaX != null}
-	<BarMarker
-		marker={{
-			type: 'bar',
-			role: 'highlight',
-			isHorizontal: false,
-			data: [],
-			category: areaX,
-			styles: {
-				...areaStyle,
-				insetLeft: areaInsetX?.start,
-				insetRight: areaInsetX?.end
-			}
-		}}
-	/>
-{/if}
-
-{#if areaY != null}
-	<BarMarker
-		marker={{
-			type: 'bar',
-			role: 'highlight',
-			isHorizontal: true,
-			data: [],
-			category: areaY,
-			styles: {
-				...areaStyle,
-				insetTop: areaInsetY?.start,
-				insetBottom: areaInsetY?.end
-			}
-		}}
-	/>
-{/if}
-
-{#if ruleX != null}
-	<g transform="translate({nudgeOf(activePoint).dx}, {nudgeOf(activePoint).dy})">
-		<RuleMarker
-			marker={{
-				type: 'rule',
-				axis: 'x',
-				value: ruleX,
-				styles: { ...cfg.hover.rule, ...ruleStyle }
-			}}
-		/>
-	</g>
-{/if}
-
-{#if ruleY != null}
-	<g transform="translate({nudgeOf(activePoint).dx}, {nudgeOf(activePoint).dy})">
-		<RuleMarker
-			marker={{
-				type: 'rule',
-				axis: 'y',
-				value: ruleY,
-				styles: { ...cfg.hover.rule, ...ruleStyle }
-			}}
-		/>
-	</g>
-{/if}
-
-{#if data.length > 0}
-	{#each data as point (`${point.series ?? ''}_${point.x}_${point.y}`)}
-		<!-- A grouped bar's point sits in its series' slice of the band (`areaInset`), not at the band's middle. -->
-		<g transform="translate({nudgeOf(point).dx}, {nudgeOf(point).dy})">
-			<DotMarker
-				marker={{
-					type: 'dot',
-					data: [point],
-					x: (d) => d.x,
-					y: (d) => d.y,
-					styles: {
-						...cfg.hover.dot,
-						...dotStyle,
-						dotFill: resolveColor(dotStyle?.dotFill, point),
-						dotStroke: resolveColor(dotStyle?.dotStroke, point)
-					}
-				}}
-			/>
-		</g>
-	{/each}
-	{#if showLabels}
-		{#each data as point (`${point.series ?? ''}_${point.x}_${point.y}`)}
-			<g transform="translate({nudgeOf(point).dx}, {nudgeOf(point).dy})">
-				<TextMarker
-					marker={{
-						type: 'text',
-						data: [point],
-						x: (d: HoverDisplayPoint) => d.x,
-						y: (d: HoverDisplayPoint) => d.y,
-						text: labelOf,
-						styles: resolveFontStyle(point)
-					}}
-				/>
-			</g>
-		{/each}
-	{/if}
-{/if}

package/dist/markers/hover/HoverMarker.svelte.d.ts

@@ -1,35 +1,12 @@
-import type { HoverMarkerConfig } from '../../types/markers/common';
 import type { HoverDisplayPoint } from '../../types/layout/hover';
 /**
- * In-SVG hover highlight, rendered *inside* a `<Plot>`. Because it positions
- * itself through the host plot's scales, it places the same coordinate
- * correctly in every facet - that is what makes cross-facet sync work without
- * any pixel math. Draws optional x/y crosshair rules plus a dot + value label
- * for each matched point.
- *
- * Takes the raw `marker` config plus the couple of things it can't know on
- * its own - `activePoint` (the specific matched point actually under the
- * cursor, for the crosshair position; see `controller.svelte.ts`'s own doc
- * comment) and whether the active hover strategy implies a crosshair on
- * each axis by default - the same "component owns its own rendering"
- * pattern `BarMarker`/`RuleMarker` follow. `activePoint`/
- * `impliesCrosshairX`/`impliesCrosshairY` are all optional and default to
- * "no crosshair".
- *
- * `areaX`/`areaY` are a separate, always-explicit opt-in (no implied
- * default) for a thickened area highlight in place of the thin crosshair -
- * see `HoverMarkerConfig`'s own doc comment. Rendered via `BarMarker`'s
- * `role: 'highlight'`, so it renders nothing on an axis without a band
- * scale (e.g. a line/scatter plot's continuous axis).
+ * Where the hover is, rendered *inside* a `<Plot>`: it reports the pixel position of the point under the pointer,
+ * through the host plot's scales, so a synced plot's tooltip can sit on it. It draws nothing itself - the
+ * `hover` marker's `back` and `front` markers are drawn by `GeometryLayout`, as every other marker.
  */
 interface Props {
-    data?: HoverDisplayPoint[];
-    /** Narrowed to just the fields this component reads - `HoverMarkerConfig` also carries routing/scoping fields (`series`/`scope`/`strategy`/`sync`) it has no use for. */
-    marker: Pick<HoverMarkerConfig, 'ruleX' | 'ruleY' | 'areaX' | 'areaY' | 'showLabels' | 'format' | 'rule' | 'area' | 'dot' | 'text' | 'decimals' | 'prefix' | 'suffix' | 'signDisplay'>;
     activePoint?: HoverDisplayPoint | null;
-    impliesCrosshairX?: boolean;
-    impliesCrosshairY?: boolean;
-    /** Reports `activePoint`'s real pixel position within this facet's own box, or `null` when nothing's matched. */
+    /** Reports `activePoint`'s pixel position within this facet's own box, or `null` when nothing's matched. */
     onActivePointPixel?: (pos: {
         x: number;
         y: number;

package/dist/markers/utils/PointPixel.d.ts

@@ -0,0 +1,37 @@
+import type { BandSlice } from '../../types/layout/hover';
+type Scale = {
+    type?: string;
+    fn?: (value: never) => unknown;
+} | undefined;
+/** Where a point is drawn, in pixels of its plot: its `x` and `y` through the plot's scales. */
+export declare class PointPixel {
+    #private;
+    /**
+     * `point`'s pixel position - the middle of its band on a band scale, of its slice when it has one (a grouped
+     * bar's series) - or `null` when a scale cannot place it.
+     */
+    static of(scales: {
+        x?: Scale;
+        y?: Scale;
+    }, point: {
+        x: unknown;
+        y: unknown;
+        areaInset?: BandSlice;
+    }): {
+        x: number;
+        y: number;
+    } | null;
+    /** The index of the one of `points` nearest `cursor`, or `-1` when none can be placed. */
+    static nearest(scales: {
+        x?: Scale;
+        y?: Scale;
+    }, points: readonly {
+        x: unknown;
+        y: unknown;
+        areaInset?: BandSlice;
+    }[], cursor: {
+        x: number;
+        y: number;
+    }): number;
+}
+export {};

package/dist/markers/utils/PointPixel.js

@@ -0,0 +1,44 @@
+import { BandNudge } from './BandNudge';
+/** Where a point is drawn, in pixels of its plot: its `x` and `y` through the plot's scales. */
+export class PointPixel {
+    /**
+     * `point`'s pixel position - the middle of its band on a band scale, of its slice when it has one (a grouped
+     * bar's series) - or `null` when a scale cannot place it.
+     */
+    static of(scales, point) {
+        const x = PointPixel.#along(scales.x, point.x);
+        const y = PointPixel.#along(scales.y, point.y);
+        if (x == null || y == null)
+            return null;
+        const nudge = BandNudge.of(scales, point.areaInset);
+        return { x: x + nudge.dx, y: y + nudge.dy };
+    }
+    /** The index of the one of `points` nearest `cursor`, or `-1` when none can be placed. */
+    static nearest(scales, points, cursor) {
+        let best = -1;
+        let bestDistance = Infinity;
+        points.forEach((point, index) => {
+            const pixel = PointPixel.of(scales, point);
+            if (!pixel)
+                return;
+            const distance = Math.hypot(pixel.x - cursor.x, pixel.y - cursor.y);
+            if (distance < bestDistance) {
+                best = index;
+                bestDistance = distance;
+            }
+        });
+        return best;
+    }
+    /** `value`'s pixel along one scale, in the middle of its band on a band scale. */
+    static #along(scale, value) {
+        if (!scale?.fn || value == null)
+            return null;
+        const raw = Number(scale.fn(value));
+        if (!Number.isFinite(raw))
+            return null;
+        if (scale.type !== 'band')
+            return raw;
+        const bandwidth = scale.fn.bandwidth?.() ?? 0;
+        return raw + bandwidth / 2;
+    }
+}

package/dist/phases/Pipeline.d.ts

@@ -1,4 +1,4 @@
-import type { AxisPlotState, AxisPlotCtx, AxisPlotKind, AxisPlotDefaults, DataRunState, HoverStageOptions, PhaseStage, PlotPhase } from '../types/phases';
+import type { AxisPlotState, AxisPlotEnv, AxisPlotKind, AxisPlotDefaults, DataRunState, HoverStageOptions, PhaseStage, PlotPhase } from '../types/phases';
 import type { PlotStylesConfig } from '../types/configuration/styling';
 import type { FacetConfig } from '../types/layout/facet';
 import type { LegendState } from '../layout/legend/LegendState.svelte';
@@ -55,7 +55,7 @@ export type PipelineOptions<TState> = {
  * Stages declared out of phase order still run in it - with a warning, once,
  * since the declared order would otherwise read as the one that runs.
  */
-export declare class Pipeline<TState, TCtx = unknown> {
+export declare class Pipeline<TState, TEnv = unknown> {
     #private;
     /**
      * The phases that work on the plot's rows - everything before its scales,
@@ -65,25 +65,25 @@ export declare class Pipeline<TState, TCtx = unknown> {
     static readonly DATA_PHASES: readonly PlotPhase[];
     /** Every {@link PlotPhase}, in the order they run: the data phases, then each panel's own. */
     static readonly ORDER: readonly PlotPhase[];
-    readonly stages: readonly PhaseStage<TState, TCtx>[];
-    constructor(stages: PhaseStage<TState, TCtx>[], options?: PipelineOptions<TState>);
+    readonly stages: readonly PhaseStage<TState, TEnv>[];
+    constructor(stages: PhaseStage<TState, TEnv>[], options?: PipelineOptions<TState>);
     /**
      * An axis-based plot kind's pipeline: the shared stages, each set up with
      * the kind's own options - its marks and value labels among them - started
      * from a core's props. Built once per kind object.
      */
-    static ofAxisKind<TState extends AxisPlotState<any, any, any, any>, TCtx extends AxisPlotCtx>(kind: AxisPlotKind<TState, TCtx> & Pick<AxisPlotDefaults<any, any>, 'timeline'>): Pipeline<TState, TCtx>;
+    static ofAxisKind<TState extends AxisPlotState<any, any, any, any>, TEnv extends AxisPlotEnv>(kind: AxisPlotKind<TState, TEnv> & Pick<AxisPlotDefaults<any, any>, 'timeline'>): Pipeline<TState, TEnv>;
     /** A plot's pipeline from what its kind gives: its axis-kind defaults, or a pipeline of its own. */
     static of(defaults: AxisPlotDefaults<any, any> | Pipeline<any, any>): Pipeline<any, any>;
     /** The stage of `phase`, if the pipeline has one. */
-    stage(phase: PlotPhase): PhaseStage<TState, TCtx> | undefined;
+    stage(phase: PlotPhase): PhaseStage<TState, TEnv> | undefined;
     /**
      * A core's run: every stage over the state its `input` (an axis core's
      * props) seeds - or, given `panelState` (one facet panel's part of
      * {@link runData}), only the stages after the data phases, over that state
      * with the input's own props (its box, margins and scales) on top.
      */
-    run: (input: unknown, ctx: TCtx, panelState?: object) => TState;
+    run: (input: unknown, env: TEnv, panelState?: object) => TState;
     /** Whether the pipeline has data phases to run once over every facet panel ({@link runData}). */
     get facets(): boolean;
     /**

package/dist/phases/Pipeline.js

@@ -2,6 +2,7 @@ import { FacetPhase } from './facet/FacetPhase';
 import { DataPhase } from './data/DataPhase';
 import { MappingPhase } from './mapping/MappingPhase';
 import { TransformsPhase } from './transforms/TransformsPhase';
+import { ContextPhase } from './context/ContextPhase';
 import { StatisticsPhase } from './statistics/StatisticsPhase';
 import { ScalesPhase } from './scales/ScalesPhase';
 import { SharedScalesPhase } from './sharedScales/SharedScalesPhase';
@@ -33,6 +34,7 @@ export class Pipeline {
         'data',
         'mapping',
         'transforms',
+        'context',
         'statistics',
         'sharedScales'
     ];
@@ -79,6 +81,7 @@ export class Pipeline {
             new DataPhase(kind.data),
             new MappingPhase(kind.mapping),
             new TransformsPhase(kind.transforms, kind.data?.segments?.connect),
+            new ContextPhase(kind.context),
             new StatisticsPhase(kind.statistics),
             new SharedScalesPhase(kind.sharedScales, scales),
             scales,
@@ -112,12 +115,12 @@ export class Pipeline {
      * {@link runData}), only the stages after the data phases, over that state
      * with the input's own props (its box, margins and scales) on top.
      */
-    run = (input, ctx, panelState) => {
+    run = (input, env, panelState) => {
         const seed = this.#seed(input);
         if (!panelState)
-            return Pipeline.#through(this.stages, seed, ctx);
+            return Pipeline.#through(this.stages, seed, env);
         this.#panel ??= this.stages.filter((stage) => !Pipeline.DATA_PHASES.includes(stage.phase));
-        return Pipeline.#through(this.#panel, { ...panelState, ...seed }, ctx);
+        return Pipeline.#through(this.#panel, { ...panelState, ...seed }, env);
     };
     /** Whether the pipeline has data phases to run once over every facet panel ({@link runData}). */
     get facets() {
@@ -131,7 +134,7 @@ export class Pipeline {
     runData(props, rows, facet, legendInteraction, cfg) {
         this.#data ??= this.stages.filter((stage) => Pipeline.DATA_PHASES.includes(stage.phase));
         const seed = { ...this.#seed(props, rows), facet };
-        return Pipeline.#through(this.#data, seed, Pipeline.#ctxFor(cfg, legendInteraction));
+        return Pipeline.#through(this.#data, seed, Pipeline.#envFor(cfg, legendInteraction));
     }
     /**
      * The plot's hover strategy when neither its `tooltip` nor a hover marker
@@ -143,7 +146,7 @@ export class Pipeline {
         if (fixed !== undefined)
             return fixed;
         const upToData = this.stages.filter((s) => s.phase === 'data');
-        const state = Pipeline.#through(upToData, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        const state = Pipeline.#through(upToData, this.#seed(props), Pipeline.#envFor(cfg, null));
         return HoverSettings.strategyOf(state.axes);
     }
     /** The plot's default `timeline.filterMode`. */
@@ -162,7 +165,7 @@ export class Pipeline {
             return undefined;
         const upToMapping = this.stages.filter((s) => s.phase === 'data' || s.phase === 'mapping');
         // Without a legend: the channels read the same whatever it turns off.
-        const state = Pipeline.#through(upToMapping, this.#seed(props), Pipeline.#ctxFor(cfg, null));
+        const state = Pipeline.#through(upToMapping, this.#seed(props), Pipeline.#envFor(cfg, null));
         const channel = (ref) => {
             const name = ref === 'value' || ref === 'category' ? state.axes?.[ref] : ref;
             if (name === undefined)
@@ -186,11 +189,11 @@ export class Pipeline {
         return this.#options.seed ? this.#options.seed(input, rows) : input;
     }
     /** `stages` over `state`, in order. */
-    static #through(stages, state, ctx) {
-        return stages.reduce((acc, stage) => stage.run(acc, ctx), state);
+    static #through(stages, state, env) {
+        return stages.reduce((acc, stage) => stage.run(acc, env), state);
     }
     /** The context a plot-level run reads, outside any core: the configuration and the legend. */
-    static #ctxFor(cfg, legendInteraction) {
+    static #envFor(cfg, legendInteraction) {
         const interaction = new PlotInteraction(() => cfg, { legend: legendInteraction });
         return { cfg, interaction };
     }

package/dist/phases/context/ContextPhase.d.ts

@@ -0,0 +1,22 @@
+import type { ContextStageOptions } from '../../types/phases/context/phase';
+import type { PhaseStage, ProcessedData } from '../../types/phases';
+import type { PlotAxes } from '../data/PlotAxes';
+import type { Series } from '../../types/plots/data/common';
+/** What the "context" phase reads. */
+type ContextStageState = {
+    processedData?: ProcessedData;
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+};
+/**
+ * The "context" phase every axis-based plot shares: right after the transforms, it works out once what the plot
+ * knows of each processed row - the shared {@link RowContext}, with what the kind adds - and keeps it on the row,
+ * for the tooltip, the hover, the value labels and the author's own markers to read.
+ */
+export declare class ContextPhase<TState extends ContextStageState, TEnv = unknown> implements PhaseStage<TState, TEnv> {
+    #private;
+    readonly phase: "context";
+    constructor(kind?: ContextStageOptions<TState, TEnv>);
+    run: (state: TState, env: TEnv) => TState;
+}
+export {};

package/dist/phases/context/ContextPhase.js

@@ -0,0 +1,23 @@
+import { RowContext } from './RowContext';
+/**
+ * The "context" phase every axis-based plot shares: right after the transforms, it works out once what the plot
+ * knows of each processed row - the shared {@link RowContext}, with what the kind adds - and keeps it on the row,
+ * for the tooltip, the hover, the value labels and the author's own markers to read.
+ */
+export class ContextPhase {
+    phase = 'context';
+    #kind;
+    constructor(kind) {
+        this.#kind = kind;
+    }
+    run = (state, env) => {
+        const rows = state.processedData?.data;
+        if (!rows?.length)
+            return state;
+        const shared = RowContext.shared(state);
+        const own = this.#kind?.(state, env);
+        for (const row of rows)
+            RowContext.tag(row, { ...shared(row), ...own?.(row) });
+        return state;
+    };
+}

package/dist/phases/context/RowContext.d.ts

@@ -0,0 +1,35 @@
+import { PlotAxes } from '../data/PlotAxes';
+import type { PlotRowContext } from '../../types/layout/context';
+import type { Series } from '../../types/plots/data/common';
+import type { ProcessedData, ProcessedRow } from '../../types/phases';
+/** What the shared context is worked out from. */
+type ContextSource = {
+    processedData?: ProcessedData;
+    resolvedSeries?: Series<any>[];
+    axes?: PlotAxes;
+};
+/**
+ * The context of the rows a plot draws ({@link PlotRowContext}): worked out once per row by the "context" phase,
+ * kept on the row itself, and read back from it - or from any copy of it - with {@link of}.
+ */
+export declare class RowContext {
+    #private;
+    /**
+     * What the plot knows of `row`: its series, where it sits, the value it shows and whatever its kind works out
+     * for it, with the row itself. A row no plot drew reads as its series alone.
+     */
+    static of<TContext extends PlotRowContext = PlotRowContext>(row: unknown): TContext;
+    /** Keeps `context` on `row`, for {@link of} to read back. */
+    static tag(row: ProcessedRow, context: PlotRowContext): void;
+    /** Whether `row` carries a context already. */
+    static has(row: unknown): boolean;
+    /** A reader of the rows of `state`: the context each carries, else the shared one, for a row no phase tagged. */
+    static reader(state: ContextSource): (row: ProcessedRow) => PlotRowContext;
+    /**
+     * The context every plot gives a processed row: its series; its `x` and `y` - each its series' own value
+     * (a stacked row's own, not the running total), else where the transforms put it (a density's estimate, a
+     * bin's centre); and its value on the plot's value axis, when that is a number.
+     */
+    static shared(state: ContextSource): (row: ProcessedRow) => PlotRowContext;
+}
+export {};