@ggts-sh/svelte 0.43.0

package/dist/interaction/interaction-diagnostics.js

@@ -0,0 +1,173 @@
+/**
+ * Agent-facing interaction diagnostic catalog — frozen codes, messages, and
+ * doc URLs for capability normalization and runtime key/lineage checks.
+ *
+ * Extracted from interaction.ts so pure catalog data is not mixed with event
+ * types and normalizeInteractionConfig.
+ *
+ * Inspect×geom advisories (bar/col x-guide + high-cardinality) are owned by
+ * @ggts-sh/core so the CLI --inspect path reuses the same messages (#1531).
+ */
+import { INSPECT_GEOM_DIAGNOSTIC_CATALOG } from "@ggts-sh/core";
+export const INTERACTION_DIAGNOSTIC_CATALOG = Object.freeze({
+    INTERACTION_INTERVAL_FACET_UNSUPPORTED: {
+        severity: "warning",
+        code: "INTERACTION_INTERVAL_FACET_UNSUPPORTED",
+        message: "Brush zoom currently requires one unfaceted panel.",
+        prop: "zoom",
+        suggestions: [
+            "Remove the facet",
+            "Use faceted interval selection",
+            "Zoom a linked detail view",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-interval-facet-unsupported",
+    },
+    INTERACTION_INVALID_MAX_DISTANCE: {
+        severity: "error",
+        code: "INTERACTION_INVALID_MAX_DISTANCE",
+        message: "inspect.maxDistance must be a finite non-negative CSS-pixel distance.",
+        prop: "inspect.maxDistance",
+        suggestions: ["Use a finite number greater than or equal to zero"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-invalid-max-distance",
+    },
+    INTERACTION_POINT_REQUIRES_KEY: {
+        severity: "warning",
+        code: "INTERACTION_POINT_REQUIRES_KEY",
+        message: "Durable point selection requires resolved row identity.",
+        prop: "identity",
+        suggestions: [
+            "Ordinary charts omit identity — defaults to an id column or row index",
+            'Override with <Inspect identity="id" /> or select={{ type: "point", identity: "id" }}',
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-point-requires-key",
+    },
+    INTERACTION_INTERVAL_PRESET_REQUIRES_KEY: {
+        severity: "warning",
+        code: "INTERACTION_INTERVAL_PRESET_REQUIRES_KEY",
+        message: "Coordinated interval presets (union, cross-panel) require resolved row identity; without it they combine no rows.",
+        prop: "identity",
+        suggestions: [
+            "Ordinary charts omit identity — defaults to an id column or row index",
+            'Override with select={{ type: "interval", identity: "id", … }} or <Inspect identity="id" />',
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-interval-preset-requires-key",
+    },
+    INTERACTION_INVALID_KEY: {
+        severity: "error",
+        code: "INTERACTION_INVALID_KEY",
+        message: "A key accessor returned null, undefined, or a non-PropertyKey value.",
+        prop: "identity",
+        suggestions: ["Return a stable string, number, or symbol for every row"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-invalid-key",
+    },
+    INTERACTION_DUPLICATE_KEY: {
+        severity: "error",
+        code: "INTERACTION_DUPLICATE_KEY",
+        message: "The key accessor returned a duplicate value; durable interaction is disabled for that value.",
+        prop: "identity",
+        suggestions: ["Use a field that uniquely identifies each source row"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-duplicate-key",
+    },
+    INTERACTION_UNSTABLE_KEY: {
+        severity: "error",
+        code: "INTERACTION_UNSTABLE_KEY",
+        message: "The key accessor returned a different value for the same source row.",
+        prop: "identity",
+        suggestions: ["Return an immutable field that uniquely identifies each row"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-unstable-key",
+    },
+    INTERACTION_MISSING_LINEAGE: {
+        severity: "warning",
+        code: "INTERACTION_MISSING_LINEAGE",
+        message: "A synthetic or aggregate mark did not expose source-row lineage.",
+        prop: "layers",
+        suggestions: ["Use a stat that preserves source-row lineage"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-missing-lineage",
+    },
+    INTERACTION_LEGEND_REQUIRES_KEY: {
+        severity: "warning",
+        code: "INTERACTION_LEGEND_REQUIRES_KEY",
+        message: "Legend focus requires resolved row identity so encoded legend values never become identities.",
+        prop: "identity",
+        suggestions: [
+            "Ordinary charts omit identity — defaults to an id column or row index",
+            'Override with <Inspect identity="id" /> or createPlotInteraction({ identity: "id" })',
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-legend-requires-key",
+    },
+    INTERACTION_LEGEND_DISCRETE_ONLY: {
+        severity: "advisory",
+        code: "INTERACTION_LEGEND_DISCRETE_ONLY",
+        message: "Legend focus currently applies to discrete color and fill legends; continuous ramps remain static.",
+        prop: "focus",
+        suggestions: [
+            'Enable focus on a discrete guide: <GuideLegend channel="color" focus />',
+            "Use a discrete color or fill mapping",
+            "Keep the continuous ramp static",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-legend-discrete-only",
+    },
+    INTERACTION_INTERVAL_SCALE_UNSUPPORTED: {
+        severity: "warning",
+        code: "INTERACTION_INTERVAL_SCALE_UNSUPPORTED",
+        message: "Interval domains and brush zoom require continuous linear, log, or time scales.",
+        prop: "scales",
+        suggestions: ["Use a continuous positional scale", "Use point inspection for band data"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-interval-scale-unsupported",
+    },
+    INTERACTION_TOOL_UNAVAILABLE: {
+        severity: "warning",
+        code: "INTERACTION_TOOL_UNAVAILABLE",
+        message: "The requested interaction tool is unavailable for the enabled capabilities.",
+        prop: "tool",
+        suggestions: ["Enable the matching capability", "Choose an available interaction tool"],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-tool-unavailable",
+    },
+    INTERACTION_SCOPE_WITHOUT_CONTROLLER: {
+        severity: "advisory",
+        code: "INTERACTION_SCOPE_WITHOUT_CONTROLLER",
+        message: "interactionScope is ignored without an interaction controller; chart-local scope is derived from key and aes.",
+        prop: "interactionScope",
+        suggestions: [
+            "Pass interaction={createPlotInteraction()} to control this plot",
+            "Remove interactionScope from uncontrolled plots",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-scope-without-controller",
+    },
+    INTERACTION_HANDLER_WITHOUT_CAPABILITY: {
+        severity: "advisory",
+        code: "INTERACTION_HANDLER_WITHOUT_CAPABILITY",
+        // Emitted with `prop` overridden to the concrete handler name and
+        // `actual` naming the capability prop that would enable it.
+        message: "An interaction handler is set but its capability prop is not enabled, so the handler never fires.",
+        prop: "oninspect / onselect / onzoom / onlegendfocus / onlegendfilter",
+        suggestions: [
+            "Enable the matching capability prop (for example select for onselect)",
+            "Remove the unused handler",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-handler-without-capability",
+    },
+    ...INSPECT_GEOM_DIAGNOSTIC_CATALOG,
+    INTERACTION_INSPECT_IDENTITY_DROPPED: {
+        severity: "advisory",
+        code: "INTERACTION_INSPECT_IDENTITY_DROPPED",
+        message: "An <Inspect> child replaced the inspect prop whole (REPLACE), so the prop's `identity` no longer applies; rows fall back to an id column or row index.",
+        prop: "Inspect",
+        suggestions: [
+            "Move identity onto the <Inspect> child",
+            "Drop identity from the inspect prop if the default row identity is intended",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-inspect-identity-dropped",
+    },
+    INTERACTION_DUPLICATE_INSPECT_CAPABILITY: {
+        severity: "advisory",
+        code: "INTERACTION_DUPLICATE_INSPECT_CAPABILITY",
+        message: "Multiple <Inspect> children are registered; only the last one's options apply (REPLACE).",
+        prop: "Inspect",
+        suggestions: [
+            "Keep a single <Inspect> child",
+            "Merge options onto one <Inspect> instead of stacking siblings",
+        ],
+        docUrl: "https://ggts.sh/guide/interaction-reference#interaction-duplicate-inspect-capability",
+    },
+});

package/dist/interaction/interaction-states.svelte.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Interaction controller assembly — owns construction order and sibling-port
+ * wiring for the five interaction controllers (zoom, selection, interval,
+ * surface, inspection).
+ *
+ * Before this module, plot-engine.svelte.ts hand-wired the construction DAG
+ * across ~200 lines, with `let surfaceState!` / `let semanticCandidateProjection!`
+ * late bindings to break the surface ↔ inspection ↔ interval ↔ selection
+ * cycles.
+ *
+ * Why two phases
+ * --------------
+ * On SSR the Svelte compiler evaluates `$derived` eagerly at declaration, so
+ * construction order must be the exact topological order of every derived
+ * read — not just handler-time reads. The full DAG interleaves with host
+ * controllers:
+ *
+ *   zoom → legendFilter → runtime → semanticKeys → selection → interval →
+ *   surface → inspection
+ *
+ * Phase 1 (`createInteractionAssembly`) constructs zoom, the only controller
+ * the legend-filter / runtime chain reads. Phase 2 (`complete`) — called by
+ * the host once the runtime and semantic-key service exist — constructs
+ * selection → interval → surface → inspection and wires all sibling ports
+ * internally:
+ *
+ * - surface is constructed before inspection so the shared interaction
+ *   reducer exists as a concrete instance (inspection no longer closes over
+ *   a later surface binding);
+ * - interval / surface receive sibling controllers as handler-only getters
+ *   over the bundle under construction (event-time reads only — every
+ *   controller documents its construction-time reads as context-only).
+ *
+ * Host-derived enablement (availableTools, pointSelectEnabled, surfaceInter-
+ * active) and host-owned slices (dataIdentityEpoch, consumptionCandidates,
+ * clearAnnouncement) arrive via options; everything shared arrives via the
+ * InteractionContext.
+ */
+import type { InspectionState, InspectionStateOptions } from "../inspection/inspection-state.svelte.js";
+import type { IntervalState, IntervalStateOptions } from "../interval/interval-state.svelte.js";
+import type { SelectionState } from "../selection/selection-state.svelte.js";
+import type { SurfaceState, SurfaceStateOptions } from "../surface/surface-state.svelte.js";
+import type { PlotZoomState, PlotZoomStateOptions } from "../zoom/zoom-state.svelte.js";
+import type { InteractionContext } from "./interaction-context.svelte.js";
+/** The five interaction controllers, keyed by role. */
+type InteractionStates = {
+    readonly zoom: PlotZoomState;
+    readonly selection: SelectionState;
+    readonly interval: IntervalState;
+    readonly surface: SurfaceState;
+    readonly inspection: InspectionState;
+};
+/**
+ * Host-owned slices the assembly cannot derive from the context. Sibling
+ * ports (reducer, emitSelection, commitZoom, inspection/interval/zoom
+ * getters) are wired internally — hosts never see them.
+ */
+type InteractionStatesOptions = {
+    readonly interval: Pick<IntervalStateOptions, "consumptionCandidates">;
+    readonly surface: Pick<SurfaceStateOptions, "toolProp" | "initialTool" | "availableTools" | "pointSelectEnabled" | "surfaceInteractive">;
+    readonly inspection: Omit<InspectionStateOptions, "reducer">;
+};
+/** Phase-1 result: zoom (consumed by the host's legend-filter / runtime
+ * chain) plus the phase-2 completion hook. */
+export type InteractionAssembly = {
+    readonly zoom: PlotZoomState;
+    /**
+     * Phase 2 — call once the runtime and semantic-key service exist (SSR
+     * evaluates deriveds eagerly at construction, so model-reading controllers
+     * must be constructed after the runtime). Constructs selection → interval
+     * → surface → inspection and returns the full bundle.
+     */
+    complete(options: InteractionStatesOptions): InteractionStates;
+};
+/**
+ * Phase 1: construct the zoom controller (model-free at construction) and
+ * return the assembly handle. Call `complete` after the host runtime exists.
+ * Call once during component init (controllers register $derived/$effect in
+ * the calling effect tree).
+ */
+export declare function createInteractionAssembly(context: InteractionContext, options: {
+    readonly zoom: PlotZoomStateOptions;
+}): InteractionAssembly;
+export {};

package/dist/interaction/interaction-states.svelte.js

@@ -0,0 +1,55 @@
+import { createInspectionState } from "../inspection/inspection-state.svelte.js";
+import { createIntervalState } from "../interval/interval-state.svelte.js";
+import { createSelectionState } from "../selection/selection-state.svelte.js";
+import { createSurfaceState } from "../surface/surface-state.svelte.js";
+import { createPlotZoomState } from "../zoom/zoom-state.svelte.js";
+/**
+ * Phase 1: construct the zoom controller (model-free at construction) and
+ * return the assembly handle. Call `complete` after the host runtime exists.
+ * Call once during component init (controllers register $derived/$effect in
+ * the calling effect tree).
+ */
+export function createInteractionAssembly(context, options) {
+    const zoom = createPlotZoomState(context, options.zoom);
+    return {
+        zoom,
+        complete(phase2) {
+            // Sibling ports close over these bindings; assigned in topological
+            // order below and read only at handler time, never during construction.
+            let interval;
+            let inspection;
+            const selection = createSelectionState(context);
+            interval = createIntervalState(context, {
+                consumptionCandidates: phase2.interval.consumptionCandidates,
+                effectiveZoomDomains: () => zoom.effectiveZoomDomains,
+                commitZoom: (domains, source) => {
+                    zoom.commitZoom(domains, source);
+                },
+                inspectionPanel: () => inspection.inspectionPanel,
+                emitSelection: (event) => {
+                    selection.emitSelection(event);
+                },
+            });
+            const surface = createSurfaceState(context, {
+                ...phase2.surface,
+                inspection: () => inspection,
+                interval: () => interval,
+                zoom: () => zoom,
+                emitSelection: (event) => {
+                    selection.emitSelection(event);
+                },
+                togglePointKeys: (keys, source) => {
+                    selection.togglePointKeys(keys, source);
+                },
+            });
+            inspection = createInspectionState(context, {
+                ...phase2.inspection,
+                // Concrete reducer — surface is already constructed, so inspection
+                // no longer closes over a later surface binding (was `let
+                // surfaceState!`).
+                reducer: surface.reducer,
+            });
+            return { zoom, selection, interval, surface, inspection };
+        },
+    };
+}

package/dist/interaction/interaction.d.ts

@@ -0,0 +1,304 @@
+import type { CellValue, PositionTransformName } from "@ggts-sh/core";
+import type { Snippet } from "svelte";
+import type { LegendFilterEvent } from "../legend/filter.js";
+import type { InteractionDiagnostic } from "./interaction-diagnostics.js";
+export { INTERACTION_DIAGNOSTIC_CATALOG } from "./interaction-diagnostics.js";
+export type { InteractionDiagnostic, InteractionDiagnosticCode, } from "./interaction-diagnostics.js";
+export { discreteColorFillDomainSizes, HIGH_CARDINALITY_DISCRETE_THRESHOLD, inspectAxisOnBarColDiagnostics, inspectAxisOnDistributionDiagnostics, inspectHighCardinalityDiagnostics, layerGeomsFromSpecLayers, } from "./inspect-geom-advisories.js";
+export type InteractionSource = "pointer" | "keyboard" | "touch" | "programmatic";
+export type InspectMode = "auto" | "exact" | "x" | "y" | "xy";
+export type TooltipTotal = "auto" | "off" | "top" | "bottom";
+export type ResolvedInspectMode = Exclude<InspectMode, "auto">;
+export type AreaMode = "x" | "y" | "xy";
+export type InteractionTool = "inspect" | "point" | "select-area" | "zoom-area";
+/** Brush tools that need crosshair cursor and touch-action: none on capture. */
+export type AreaInteractionTool = "select-area" | "zoom-area";
+export declare function isAreaTool(tool: InteractionTool): tool is AreaInteractionTool;
+export interface TooltipField {
+    readonly channel: string;
+    readonly field: string;
+    readonly value: CellValue;
+}
+export interface PlotDatum<Row, Key> {
+    readonly key: Key | null;
+    readonly row: Row | null;
+    readonly sourceKeys: ReadonlyArray<Key>;
+    readonly lineageCount: number;
+    readonly layerIndex: number;
+    readonly panelId: string | null;
+    readonly fields: ReadonlyArray<TooltipField>;
+    readonly anchor: Readonly<{
+        x: number;
+        y: number;
+    }>;
+}
+export type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+interface PlotInspectionBase<Row, Key> {
+    readonly type: "inspect";
+    readonly phase: "change";
+    readonly state: "transient" | "pinned";
+    readonly source: InteractionSource;
+    readonly panelId: string | null;
+    /**
+     * Sum of unique series contributions in the composition group (stack/fill),
+     * independent of inspect `mode`. `null` when the group is not additive
+     * (identity/dodge) or has no finite numeric contribution. Exact/xy keep a
+     * single listed member; the total still covers the whole stack.
+     */
+    readonly groupTotal?: number | null;
+    readonly focus: PlotDatum<Row, Key>;
+    readonly members: NonEmptyReadonlyArray<PlotDatum<Row, Key>>;
+}
+export type PlotInspectionChange<Row, Key> = (PlotInspectionBase<Row, Key> & {
+    readonly mode: "exact" | "xy";
+}) | (PlotInspectionBase<Row, Key> & {
+    readonly mode: "x" | "y";
+    readonly axisValue: CellValue;
+    readonly axisLabel: string;
+    /**
+     * Sum of numeric contributions on the value axis for unique series in
+     * the full axis group (y when mode is x, x when mode is y). Used by
+     * the default tooltip Total row; independent of the hover member cap
+     * (#1274 / #1389). Only populated when the group includes a stack/fill
+     * layer — parallel multi-series (identity/dodge lines and points) leave
+     * this `null` so the tooltip does not invent a sum. Multi-layer paints
+     * of the same source series (line+point, col+text) contribute once;
+     * distinct series on other layers (e.g. a trend over a stack) are
+     * included. Also `null` when no member has a finite numeric contribution.
+     */
+    readonly groupTotal: number | null;
+    /**
+     * Unique series-contribution count in the full axis group (all layers,
+     * deduped). Drives the default tooltip "+N more" line when hover rows
+     * were truncated (#1274 / #1389).
+     */
+    readonly groupMemberCount: number;
+});
+export interface PlotInspectionClear {
+    readonly type: "inspect";
+    readonly phase: "clear";
+    readonly source: InteractionSource;
+}
+export type PlotInspection<Row, Key = PropertyKey> = PlotInspectionChange<Row, Key> | PlotInspectionClear;
+export interface IntervalSelection<Key = PropertyKey> {
+    readonly type: "select";
+    readonly phase: "start" | "change" | "end" | "clear";
+    readonly mode: AreaMode;
+    readonly panelId: string | null;
+    readonly domain: Readonly<{
+        x?: readonly [CellValue, CellValue];
+        y?: readonly [CellValue, CellValue];
+    }>;
+    readonly pixels: Readonly<{
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    }>;
+    readonly keys: ReadonlyArray<Key>;
+    readonly lineageCount: number;
+    readonly source: InteractionSource;
+}
+export interface PointSelection<Key = PropertyKey> {
+    readonly type: "select";
+    readonly phase: "end" | "clear";
+    readonly mode: "point";
+    readonly keys: ReadonlyArray<Key>;
+    readonly source: InteractionSource;
+}
+export type PlotSelection<Key = PropertyKey> = IntervalSelection<Key> | PointSelection<Key>;
+export interface ZoomEvent {
+    readonly type: "zoom";
+    readonly phase: "end" | "clear";
+    readonly source: InteractionSource;
+    readonly domains: ReadonlyZoomDomains | null;
+}
+export interface LegendFocusChange<Key = PropertyKey> {
+    readonly type: "legend-focus";
+    readonly phase: "change";
+    readonly state: "transient" | "committed";
+    readonly source: InteractionSource;
+    readonly scale: "color" | "fill" | "size" | "linewidth" | "alpha" | "shape" | "linetype";
+    /** Raw encoded domain value. This is deliberately distinct from row keys. */
+    readonly value: CellValue;
+    readonly label: string;
+    readonly keys: ReadonlyArray<Key>;
+}
+export interface LegendFocusClear {
+    readonly type: "legend-focus";
+    readonly phase: "clear";
+    readonly source: InteractionSource;
+}
+export type LegendFocusEvent<Key = PropertyKey> = LegendFocusChange<Key> | LegendFocusClear;
+export type PlotInteractionEvent<Row, Key = PropertyKey> = PlotInspection<Row, Key> | PlotSelection<Key> | ZoomEvent | LegendFocusEvent<Key> | LegendFilterEvent;
+export interface InspectOptions<Row = Record<string, CellValue>, Key = PropertyKey> {
+    readonly mode?: InspectMode;
+    readonly pin?: boolean;
+    readonly maxDistance?: number;
+    readonly contentMode?: "informational" | "interactive";
+    /**
+     * When true, inspection mutes non-focused marks (sibling bars/cols) via the
+     * interaction mask. Default false — tooltip-only hover avoids full-plot
+     * flicker when the pointer crosses gaps between rect marks (#633).
+     */
+    readonly muteSiblings?: boolean;
+    /**
+     * Where the default tooltip shows a single group total (stack/fill sum
+     * across series at the focused category). Independent of inspect `mode`:
+     * stacked bars can keep `mode="exact"` and still show a Total row.
+     *
+     * - `"auto"` (default): Total at the bottom when the group is additive
+     *   (stack/fill) and has more than one series. Axis-mode (`x`/`y`)
+     *   inspections already do this; exact/xy do not unless opted in.
+     * - `"off"`: never show Total.
+     * - `"top"` / `"bottom"`: force Total when a numeric group total exists.
+     */
+    readonly tooltipTotal?: TooltipTotal;
+    /**
+     * Durable row identity for interaction payloads (pin rebind, selection
+     * keys, legend focus). Preferred over the deprecated GGPlot `key` prop.
+     * Default when omitted: `id` column if present, else row index.
+     */
+    readonly identity?: Key | ((row: Row, index: number) => Key);
+    readonly content?: Snippet<[PlotInspectionChange<Row, Key>]>;
+}
+export interface SelectOptions {
+    readonly type: "point" | "interval";
+    readonly mode?: AreaMode;
+    readonly multiple?: boolean;
+    readonly persistent?: boolean;
+    /** Facet coordination semantics for durable interval selections. */
+    readonly preset?: FacetIntervalPreset;
+    /**
+     * Durable row identity for selection keys (and shared plot interaction).
+     * Preferred over the deprecated GGPlot `key` prop. Not selection semantics —
+     * omitted from the resolved select config.
+     */
+    readonly identity?: PropertyKey | ((row: Record<string, CellValue>, index: number) => PropertyKey);
+}
+export interface ZoomOptions {
+    readonly mode?: AreaMode;
+    readonly trigger?: "brush";
+}
+export type InspectInput<Row = Record<string, CellValue>, Key = PropertyKey> = boolean | InspectOptions<Row, Key>;
+export type SelectInput = false | "point" | "interval" | SelectOptions;
+export type ZoomInput = boolean | ZoomOptions;
+export interface LegendFocusOptions {
+    /** Preview a legend group on pointer hover and DOM focus. */
+    readonly preview?: boolean;
+}
+export type LegendFocusInput = boolean | LegendFocusOptions;
+export interface ResolvedInteractionConfig<Row = Record<string, CellValue>, Key = PropertyKey> {
+    readonly interactive: boolean;
+    readonly inspect: Readonly<Required<Omit<InspectOptions<Row, Key>, "content" | "identity">> & Pick<InspectOptions<Row, Key>, "content">> | null;
+    /** Select config without `identity` (identity is resolved separately for row keys). */
+    readonly select: Readonly<Required<Omit<SelectOptions, "identity">>> | null;
+    readonly zoom: Readonly<Required<ZoomOptions>> | null;
+    readonly legendFocus: Readonly<Required<LegendFocusOptions>> | null;
+    readonly initialTool: InteractionTool;
+    readonly availableTools: ReadonlyArray<InteractionTool>;
+    readonly diagnostics: ReadonlyArray<InteractionDiagnostic>;
+}
+export interface InteractionConfigInput<Row = Record<string, CellValue>, Key = PropertyKey> {
+    readonly inspect?: InspectInput<Row, Key>;
+    readonly select?: SelectInput;
+    readonly zoom?: ZoomInput;
+    readonly legendFocus?: LegendFocusInput;
+    readonly tool?: InteractionTool;
+}
+export { normalizeInteractionConfig } from "./normalize-interaction-config.js";
+export interface ReadonlyZoomDomains {
+    readonly x?: readonly [number, number];
+    readonly y?: readonly [number, number];
+}
+/** Semantic namespaces used when one controller coordinates unlike views.
+ * Key state crosses charts only through `keys`; data-space zoom crosses one
+ * positional channel only when that channel's scope also matches. */
+export interface PlotInteractionScope {
+    readonly keys: string;
+    readonly x?: string;
+    readonly y?: string;
+    /** Namespace for semantic facet intervals. Defaults to `keys` when omitted. */
+    readonly intervals?: string;
+}
+export type PlotInteractionChange = "selection" | "emphasis" | "interval" | "zoom";
+/** How facet interval state is consumed by coordinated panels.
+ *
+ * - independent: only the matching panel consumes its interval
+ * - union: matching rows from every stored panel interval are combined
+ * - cross-panel: the sole origin interval is projected into compatible panels
+ */
+export type FacetIntervalPreset = "independent" | "union" | "cross-panel";
+export type SemanticIntervalAxis = Readonly<{
+    kind: "linear" | "time";
+    /** Pre-stat position transform (default identity). Always identity for
+     *  kind:"time". "log"/"sqrt" semantics live in `transform`, not `kind`. */
+    transform?: PositionTransformName;
+    /** Ascending data-space values; time values are Unix milliseconds. */
+    domain: readonly [number, number];
+}> | Readonly<{
+    kind: "band";
+    /** Ordered, encoded category identities. Labels are presentation-only. */
+    values: ReadonlyArray<string>;
+}>;
+export interface ReadonlyIntervalDomains {
+    readonly x?: SemanticIntervalAxis;
+    readonly y?: SemanticIntervalAxis;
+}
+export interface PlotInteractionInterval<Key extends PropertyKey> {
+    /** Stable structured facet identity, never a panel index. */
+    readonly panelId: string;
+    readonly preset: FacetIntervalPreset;
+    readonly domains: ReadonlyIntervalDomains;
+    /** Stable source-row identities selected by this panel interval. */
+    readonly keys: ReadonlyArray<Key>;
+}
+export interface ScopedInteractionInterval<Key extends PropertyKey> extends PlotInteractionInterval<Key> {
+    readonly scope: string;
+}
+export interface ScopedInteractionKeys<Key extends PropertyKey> {
+    readonly scope: string;
+    readonly keys: ReadonlyArray<Key>;
+}
+export interface ScopedInteractionDomain {
+    readonly scope: string;
+    readonly domain: readonly [number, number];
+}
+/** Controller semantic state. It deliberately excludes rows, renderer
+ * indices, pixel rectangles, candidate ids, models, and DOM references. */
+export interface PlotInteractionSnapshot<Key extends PropertyKey> {
+    readonly revision: number;
+    readonly selections: ReadonlyArray<ScopedInteractionKeys<Key>>;
+    readonly emphases: ReadonlyArray<ScopedInteractionKeys<Key>>;
+    readonly intervals: ReadonlyArray<ScopedInteractionInterval<Key>>;
+    readonly zoom: Readonly<{
+        x: ReadonlyArray<ScopedInteractionDomain>;
+        y: ReadonlyArray<ScopedInteractionDomain>;
+    }>;
+}
+export interface PlotInteractionTransition<Key extends PropertyKey> {
+    readonly revision: number;
+    readonly kind: PlotInteractionChange | "reconcile";
+    readonly changes: ReadonlyArray<PlotInteractionChange>;
+    readonly source: InteractionSource;
+    readonly scope: PlotInteractionScope;
+    readonly snapshot: PlotInteractionSnapshot<Key>;
+}
+/**
+ * @deprecated since 0.1.0 — use IntervalSelection. Kept as a source migration
+ * alias only: https://ggts.sh/guide/upgrading#deprecated-type-aliases
+ */
+export type BrushSelection = IntervalSelection;
+/**
+ * @deprecated since 0.1.0 — use PlotInspectionChange. Kept as a source
+ * migration alias only: https://ggts.sh/guide/upgrading#deprecated-type-aliases
+ */
+export type TooltipContext<Row = Record<string, CellValue>, Key = PropertyKey> = PlotInspectionChange<Row, Key>;
+/**
+ * @deprecated since 0.1.0 — use ReadonlyZoomDomains. Kept as a source
+ * migration alias only: https://ggts.sh/guide/upgrading#deprecated-type-aliases
+ */
+export type ZoomDomains = {
+    x?: [number, number];
+    y?: [number, number];
+};

package/dist/interaction/interaction.js

@@ -0,0 +1,7 @@
+// Diagnostic catalog (codes + frozen messages) lives in interaction-diagnostics.ts.
+export { INTERACTION_DIAGNOSTIC_CATALOG } from "./interaction-diagnostics.js";
+export { discreteColorFillDomainSizes, HIGH_CARDINALITY_DISCRETE_THRESHOLD, inspectAxisOnBarColDiagnostics, inspectAxisOnDistributionDiagnostics, inspectHighCardinalityDiagnostics, layerGeomsFromSpecLayers, } from "./inspect-geom-advisories.js";
+export function isAreaTool(tool) {
+    return tool === "select-area" || tool === "zoom-area";
+}
+export { normalizeInteractionConfig } from "./normalize-interaction-config.js";

package/dist/interaction/normalize-interaction-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize public interaction capability inputs into a resolved config with
+ * diagnostics. Types live in ./interaction.ts; this module is pure logic only.
+ */
+import type { InteractionConfigInput, ResolvedInteractionConfig } from "./interaction.js";
+export declare function normalizeInteractionConfig<Row, Key>(input: InteractionConfigInput<Row, Key>, context?: {
+    faceted?: boolean;
+    hasKey?: boolean;
+}): ResolvedInteractionConfig<Row, Key>;