semiotic 3.7.5 → 3.8.1

package/dist/components/charts/shared/diagnoseConfig.d.ts

@@ -1,16 +1,11 @@
 import type { Datum } from "./datumTypes";
-export interface Diagnosis {
-    severity: "error" | "warning";
-    code: string;
-    message: string;
-    fix: string;
-}
-export interface DiagnosisResult {
-    ok: boolean;
-    diagnoses: Diagnosis[];
-}
-/** WCAG contrast ratio between two hex colors. Exported for reuse by the
- *  accessibility audit (auditAccessibility.ts) — single source of truth for the
- *  contrast math. Returns null if either color isn't a parseable hex. */
-export declare function contrastRatio(hex1: string, hex2: string): number | null;
+import type { DiagnosisResult } from "./diagnoseTypes";
+export { contrastRatio } from "./colorContrast";
+export type { Diagnosis, DiagnosisResult } from "./diagnoseTypes";
+/**
+ * Run anti-pattern diagnostics on a Semiotic chart configuration.
+ *
+ * Returns actionable diagnoses with severity, code, message, and fix instruction.
+ * Runs validateProps internally — validation errors are included as diagnoses.
+ */
 export declare function diagnoseConfig(componentName: string, props: Datum): DiagnosisResult;

package/dist/components/charts/shared/diagnoseMisleadingChecks.d.ts

@@ -0,0 +1,9 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+export declare function checkInvertedAxis(_component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkDualAxisUnlabeled(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkCherryPickedWindow(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkPartToWholeNegative(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkNonPassingCurve(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkExtremeAspectRatio(component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkPieTooManySlices(component: string, props: Datum, out: Diagnosis[]): void;

package/dist/components/charts/shared/diagnosePhysicsChecks.d.ts

@@ -0,0 +1,3 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+export declare function checkPhysicsConfig(component: string, props: Datum, out: Diagnosis[]): void;

package/dist/components/charts/shared/diagnoseTypes.d.ts

@@ -0,0 +1,10 @@
+export interface Diagnosis {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    fix: string;
+}
+export interface DiagnosisResult {
+    ok: boolean;
+    diagnoses: Diagnosis[];
+}

package/dist/components/charts/shared/formatUtils.d.ts

@@ -58,7 +58,7 @@ export declare function formatAxis(type?: "number" | "date" | "percent" | "curre
  * )
  * ```
  */
-export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
+export declare function createTooltip(fields: string[], formatters?: Record<string, (value: string | number | Date) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
 /**
  * Formats large numbers with K/M/B suffixes
  *
@@ -85,7 +85,7 @@ export declare function formatLargeNumber(value: number, decimals?: number): str
  *
  * Used as the default axis tickFormat when no explicit format is provided.
  */
-export declare function smartTickFormat(value: any): string;
+export declare function smartTickFormat(value: string | number | Date | null | undefined): string;
 type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "years";
 /**
  * Creates a hierarchical time axis formatter.
@@ -112,7 +112,7 @@ type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "ye
  * <LineChart data={ts} xFormat={adaptiveTimeTicks("minutes")} />
  * ```
  */
-export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: any, index?: number, allTicks?: number[]) => string;
+export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: string | number | Date, index?: number, allTicks?: number[]) => string;
 /**
  * Truncates text to specified length with ellipsis
  *

package/dist/components/charts/shared/hatchFill.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Declarative hatch-fill descriptor — a single value that renders as a
+ * diagonal-line pattern on BOTH rendering backends.
+ *
+ * The library historically had two disjoint hatch primitives: a canvas
+ * `createHatchPattern` (→ `CanvasPattern`) and an SVG `<pattern>` builder
+ * (`hatchFill` recipe / `createSVGHatchPattern`). A caller had to know
+ * which medium they were painting into and hand-produce the right thing —
+ * which is why a `CanvasPattern` returned from a `pieceStyle` silently
+ * collapses to a solid color in SSR (`svgFill` drops non-string fills).
+ *
+ * `HatchFill` closes that gap: it is a plain, serializable descriptor that
+ * can be set directly as `style.fill`. The canvas renderer resolves it to a
+ * `CanvasPattern` (`resolveHatchCanvasPattern`); the SVG serializer resolves
+ * it to a `<pattern>` def + `url(#id)` (`hatchPatternDef` / `hatchFillId`).
+ * One declaration, both mediums — so a bar hatched via a style rule looks
+ * identical whether it is drawn to canvas in the browser or serialized to
+ * SVG on the server.
+ *
+ * @example
+ * ```tsx
+ * <BarChart
+ *   styleRules={[
+ *     { when: { gt: 10 }, style: { fill: { type: "hatch", background: "#ffd166", stroke: "#e0a92a" } } },
+ *   ]}
+ * />
+ * ```
+ */
+import * as React from "react";
+/**
+ * A declarative diagonal-hatch fill. Assign it anywhere a `style.fill`
+ * is accepted (`pieceStyle`, `styleRules`, annotation region `fill`).
+ * Backend-agnostic: resolved to a `CanvasPattern` for canvas and an SVG
+ * `<pattern>` for SSR / the SVG overlay.
+ */
+export interface HatchFill {
+    /** Discriminator — marks this fill as a hatch descriptor. */
+    type: "hatch";
+    /** Tile background color painted under the lines. @default "transparent" */
+    background?: string;
+    /** Color of the diagonal lines. @default "#000" */
+    stroke?: string;
+    /** Width of the diagonal lines in px. @default 1.5 */
+    lineWidth?: number;
+    /** Spacing between lines in px. @default 6 */
+    spacing?: number;
+    /** Angle of the lines in degrees (0 = horizontal, 45 = diagonal). @default 45 */
+    angle?: number;
+    /** Opacity applied to the hatch lines (SVG `<line>` stroke opacity). @default 1 */
+    lineOpacity?: number;
+}
+/** Type guard — is a resolved `style.fill` a `HatchFill` descriptor? */
+export declare function isHatchFill(fill: unknown): fill is HatchFill;
+/**
+ * Stable, content-derived key for a hatch descriptor. Used to cache canvas
+ * patterns and to mint deterministic SVG `<pattern>` ids so identical
+ * descriptors dedupe rather than proliferate.
+ */
+export declare function hatchFillKey(h: HatchFill): string;
+/** Deterministic, SVG-id-safe identifier for a hatch descriptor. */
+export declare function hatchFillId(prefix: string, h: HatchFill): string;
+/**
+ * Resolve a `HatchFill` descriptor to a `CanvasPattern` for the given
+ * context. Cached by descriptor content + DPR. Returns `null` only when
+ * the environment can't create a pattern (SSR/test) — callers fall back
+ * to the descriptor's `background` color.
+ */
+export declare function resolveHatchCanvasPattern(h: HatchFill, ctx: CanvasRenderingContext2D): CanvasPattern | null;
+/**
+ * Render a `HatchFill` descriptor as an SVG `<pattern>` element.
+ * Place the returned element inside `<defs>` (or anywhere valid) and set
+ * `fill="url(#id)"` on the target shape. Mirrors the canvas tile exactly:
+ * parallel lines rotated by `angle` so the two backends read identically.
+ */
+export declare function hatchPatternDef(h: HatchFill, id: string): React.ReactElement;
+/**
+ * Resolve a `style.fill` for an SVG shape. Returns the paint string to use
+ * plus, when the fill is a `HatchFill`, the `<pattern>` def to inject.
+ *
+ * @param fill    the raw `style.fill` (string color, `HatchFill`, or `CanvasPattern`)
+ * @param idBase  prefix for the generated pattern id (should be node-unique-ish)
+ * @param fallback solid color used when `fill` is null/undefined or a raw CanvasPattern
+ */
+export declare function resolveSvgFill(fill: string | HatchFill | CanvasPattern | null | undefined, idBase: string, fallback?: string): {
+    fill: string;
+    def?: React.ReactElement;
+};

package/dist/components/charts/shared/hooks.d.ts

@@ -1,14 +1,26 @@
 import { createLegend } from "./legendUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
 import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
 import type { Datum } from "./datumTypes";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
+import type { ResponsiveRule } from "./responsiveRules";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "./semanticInteractions";
 /**
  * Default fill color used when no colorBy is specified
  */
 export declare const DEFAULT_COLOR = "#007bff";
+export declare const MOBILE_INTERACTION_TARGET_SIZE = 44;
+export declare const MOBILE_INTERACTION_MIN_HIT_RADIUS = 24;
+export declare const MOBILE_INTERACTION_DEFAULTS: ResolvedMobileInteractionConfig;
+export declare const DISABLED_MOBILE_INTERACTION: ResolvedMobileInteractionConfig;
+export declare function resolveMobileInteraction(input: MobileInteractionProp | undefined, context?: {
+    mode?: ChartMode;
+    width?: number;
+    mobileSemantics?: MobileVisualizationContract;
+}): ResolvedMobileInteractionConfig;
 /**
  * Returns the theme's categorical palette, or undefined if no ThemeProvider or
  * the palette is empty. Safe to call outside a ThemeProvider (returns undefined).
@@ -30,18 +42,18 @@ export declare function useThemeDiverging(): string | undefined;
  * Priority: color prop > theme categorical > colorScheme > DEFAULT_COLOR.
  * When a palette is available, cycles through colors by category name.
  */
-export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
+export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | Record<string, string> | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
 /**
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
  */
-export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
+export declare function resolveAccessor<T = string | number | boolean | Date | Datum | null | undefined>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
 /**
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or data is empty (push API mode).
  * Supports both string and function accessors for colorBy.
  */
-export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: Datum, i?: number) => string | number) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -64,7 +76,7 @@ export declare function useSortedData(data: Array<Datum>, sort: boolean | "asc"
  * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
  *   (stream frames wrap the raw datum in { data, time, value, x, y }).
  */
-export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData: _unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData: _unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, mobileInteraction, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -72,17 +84,18 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     onObservation?: OnObservationCallback;
     chartType?: string;
     chartId?: string;
-    onClick?: (datum: any, event: {
+    onClick?: (datum: Datum, event: {
         x: number;
         y: number;
     }) => void;
     hoverHighlight?: HoverHighlightMode;
     colorByField?: string;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
-    customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    customHoverBehavior: SemanticHoverBehavior;
+    customClickBehavior: SemanticClickBehavior;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
     crosshairSourceId: string;
 };
@@ -160,9 +173,16 @@ interface ChartModeInput {
     categoryLabel?: string;
     valueLabel?: string;
     /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
-    linkedHover?: any;
+    linkedHover?: LinkedHoverProp;
+    /** Optional mobile interaction policy surfaced through useChartMode for custom wrappers. */
+    mobileInteraction?: MobileInteractionProp;
+    /** Optional mobile semantic contract surfaced through useChartMode for custom wrappers. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Semantic responsive transformations resolved before mode defaults. */
+    responsiveRules?: ResponsiveRule[];
 }
-interface ChartModeResult {
+/** Result of {@link useChartMode} — exported so declaration emit can name it. */
+export interface ChartModeResult {
     width: number;
     height: number;
     showAxes: boolean;
@@ -186,6 +206,10 @@ interface ChartModeResult {
     };
     /** True when mode is context or sparkline — the "hide interactive chrome" union. */
     compactMode: boolean;
+    /** Resolved touch-first behavior for mobile-capable wrappers. */
+    mobileInteraction: ResolvedMobileInteractionConfig;
+    /** Mobile semantic contract after matching responsive rules are applied. */
+    mobileSemantics: MobileVisualizationContract | undefined;
 }
 /**
  * Resolve chart display mode into concrete prop defaults.

package/dist/components/charts/shared/knownChartComponents.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AUTO-GENERATED from chartSpecs.ts by scripts/regenerate-schema.ts.
+ * Do not edit by hand; run `npm run docs:chart-specs:schema`.
+ *
+ * This compact registry is intentionally separate from validation metadata:
+ * config serialization only needs chart-name membership.
+ */
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare function isKnownChartComponent(componentName: string): boolean;

package/dist/components/charts/shared/leastSquaresRegression.d.ts

@@ -0,0 +1,16 @@
+export type RegressionPoint = [number, number];
+export interface LeastSquaresResult {
+    points: RegressionPoint[];
+    /**
+     * Linear: `[slope, intercept]`. Polynomial: highest power first, matching
+     * the historical `regression` package result consumed by annotations.
+     */
+    equation: number[];
+}
+/** Fit a two-parameter least-squares line with two-decimal output rounding. */
+export declare function linearRegression(data: ReadonlyArray<readonly [number, number | null]>): LeastSquaresResult;
+/**
+ * Fit an order-N polynomial using normal equations. Coefficients and predicted
+ * points use the former dependency's two-decimal rounding and equation order.
+ */
+export declare function polynomialRegression(data: ReadonlyArray<readonly [number, number | null]>, order?: number): LeastSquaresResult;

package/dist/components/charts/shared/mergeShapeStyle.d.ts

@@ -27,7 +27,8 @@ export interface PrimitiveStyleOverrides {
     strokeWidth?: number;
     opacity?: number;
 }
-type StyleFnArg = (...args: any[]) => Datum;
+type StyleArgument = Datum | string | number | boolean | Date | null | undefined;
+type StyleFn<TArgs extends StyleArgument[]> = (...args: TArgs) => Datum;
 /** Returns true when at least one override key has a non-undefined value. */
 export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides): boolean;
 /**
@@ -39,5 +40,5 @@ export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides
  * keeps the memoization-stable identity path hot for the common case
  * where a designer has set nothing.
  */
-export declare function mergeShapeStyle<F extends StyleFnArg>(styleFn: F | undefined, overrides: PrimitiveStyleOverrides): F;
+export declare function mergeShapeStyle<TArgs extends StyleArgument[] = []>(styleFn: StyleFn<TArgs> | undefined, overrides: PrimitiveStyleOverrides): StyleFn<TArgs>;
 export {};

package/dist/components/charts/shared/motionEncoding.d.ts

@@ -0,0 +1,145 @@
+import type { Datum } from "./datumTypes";
+import { type LifecycleBand, type LifecycleBandThresholds } from "../../realtime/lifecycleBands";
+/** Explicit literal wrapper for channels whose values could be field names. */
+export interface MotionEncodingConstant<TValue> {
+    constant: TValue;
+}
+/** A motion channel can read a field, calculate a value, or use a constant. */
+export type MotionEncodingAccessor<TDatum, TValue> = keyof TDatum | ((datum: TDatum, index: number) => TValue) | MotionEncodingConstant<TValue>;
+/** The clock that gives an arrival or age value meaning. */
+export type MotionTimeBasis = "event" | "ingest" | "simulation" | "presentation" | "buffer-index";
+/** Motion helpers do not convert units; related values must use the same unit. */
+export type MotionTimeUnit = "milliseconds" | "seconds" | "frames" | "index";
+/** Coordinate system in which placement or velocity values are expressed. */
+export type MotionCoordinateSpace = "data" | "world" | "screen";
+export interface MotionTimeEncoding<TDatum> {
+    /** Time at which the datum enters the represented system. */
+    arrival?: MotionEncodingAccessor<TDatum, number>;
+    basis?: MotionTimeBasis;
+    unit?: MotionTimeUnit;
+}
+export interface MotionPlacementEncoding<TDatum> {
+    x?: MotionEncodingAccessor<TDatum, number>;
+    y?: MotionEncodingAccessor<TDatum, number>;
+    lane?: MotionEncodingAccessor<TDatum, string | number>;
+    space?: MotionCoordinateSpace;
+}
+export interface MotionKinematicsEncoding<TDatum> {
+    velocityX?: MotionEncodingAccessor<TDatum, number>;
+    velocityY?: MotionEncodingAccessor<TDatum, number>;
+    space?: MotionCoordinateSpace;
+}
+export interface MotionProcessEncoding<TDatum> {
+    group?: MotionEncodingAccessor<TDatum, string | number>;
+    stage?: MotionEncodingAccessor<TDatum, string | number>;
+    target?: MotionEncodingAccessor<TDatum, string | number>;
+    work?: MotionEncodingAccessor<TDatum, number>;
+}
+export interface MotionAccessibleEncoding<TDatum> {
+    description?: MotionEncodingAccessor<TDatum, string>;
+    group?: MotionEncodingAccessor<TDatum, string>;
+    label?: MotionEncodingAccessor<TDatum, string>;
+}
+/** Runtime-neutral motion channels shared by streaming and physics adapters. */
+export interface MotionEncoding<TDatum extends Datum = Datum> {
+    id: MotionEncodingAccessor<TDatum, string | number>;
+    time?: MotionTimeEncoding<TDatum>;
+    placement?: MotionPlacementEncoding<TDatum>;
+    kinematics?: MotionKinematicsEncoding<TDatum>;
+    process?: MotionProcessEncoding<TDatum>;
+    evidence?: Record<string, MotionEncodingAccessor<TDatum, unknown>>;
+    accessible?: MotionAccessibleEncoding<TDatum>;
+}
+export interface ResolvedMotionEncodingRow<TDatum extends Datum = Datum> {
+    id: string;
+    datum: TDatum;
+    time: {
+        arrival?: number;
+        basis?: MotionTimeBasis;
+        unit?: MotionTimeUnit;
+    };
+    placement: {
+        x?: number;
+        y?: number;
+        lane?: string | number;
+        space?: MotionCoordinateSpace;
+    };
+    kinematics: {
+        velocityX?: number;
+        velocityY?: number;
+        space?: MotionCoordinateSpace;
+    };
+    process: {
+        group?: string | number;
+        stage?: string | number;
+        target?: string | number;
+        work?: number;
+    };
+    evidence: Record<string, unknown>;
+    accessible: {
+        description?: string;
+        group?: string;
+        label: string;
+    };
+}
+export interface MotionEncodingCompilation<TDatum extends Datum = Datum> {
+    rows: ResolvedMotionEncodingRow<TDatum>[];
+    byId: Map<string, ResolvedMotionEncodingRow<TDatum>>;
+}
+export interface CompileMotionEncodingOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    encoding: MotionEncoding<TDatum>;
+}
+/** Resolve one encoding accessor without attaching it to a specific runtime. */
+export declare function resolveMotionAccessor<TDatum, TValue>(accessor: MotionEncodingAccessor<TDatum, TValue> | undefined, datum: TDatum, index: number): TValue | undefined;
+/** Resolve runtime-neutral motion channels once while preserving source data. */
+export declare function compileMotionEncoding<TDatum extends Datum = Datum>(options: CompileMotionEncodingOptions<TDatum>): MotionEncodingCompilation<TDatum>;
+export interface ResolveMotionAgeOptions {
+    now: number;
+    arrival: number;
+    /** Uses the same unit as now and arrival. */
+    ttl: number;
+    thresholds?: LifecycleBandThresholds;
+}
+export interface ResolvedMotionAge {
+    age: number;
+    /** Unbounded age / ttl ratio. Negative and invalid ages resolve to zero. */
+    progress: number;
+    lifecycle: LifecycleBand;
+}
+/**
+ * Derive age, its unbounded ttl progress, and its named lifecycle band from
+ * values on a common clock — the one-call helper for authoring custom
+ * age-based encodings (see the Motion Encodings guide, which drives an "age +
+ * lifecycle" table from it). For band-only or ramp-only needs, reach for
+ * `bandFromAge` / `opacityFromAge` directly.
+ */
+export declare function resolveMotionAge(options: ResolveMotionAgeOptions): ResolvedMotionAge;
+export type MotionAgeOpacityType = "linear" | "exponential" | "step";
+export interface MotionAgeOpacityOptions {
+    /** Age where zero is newest. */
+    age: number;
+    /** Oldest meaningful age in the same unit. */
+    extent: number;
+    type: MotionAgeOpacityType;
+    halfLife?: number;
+    threshold?: number;
+    minOpacity?: number;
+}
+/** Map an age to opacity without assuming wall, simulation, or index time. */
+export declare function opacityFromAge(options: MotionAgeOpacityOptions): number;
+export interface MotionPoint {
+    x: number;
+    y: number;
+}
+export interface ResolvedMotionVector {
+    velocityX: number;
+    velocityY: number;
+    speed: number;
+    /** atan2 angle in radians in the supplied coordinate space. */
+    direction: number;
+}
+/** Resolve cartesian velocity into speed and direction. */
+export declare function resolveMotionVector(velocityX: number, velocityY: number): ResolvedMotionVector;
+/** Derive velocity per elapsed unit between two positions. */
+export declare function deriveMotionVector(previous: MotionPoint, current: MotionPoint, elapsed: number): ResolvedMotionVector;

package/dist/components/charts/shared/responsiveRules.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Responsive visualization rule grammar.
+ *
+ * This is deliberately chart-semantic, not CSS. A rule says "when this chart
+ * slot is narrow, transform the chart props this way" so agents, recipes,
+ * audits, and future HOC runtime wiring can reason about the mobile variant
+ * without executing a renderer.
+ */
+export type ResponsiveOrientation = "portrait" | "landscape";
+export interface ResponsiveRuleCondition {
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minAspectRatio?: number;
+    maxAspectRatio?: number;
+    orientation?: ResponsiveOrientation;
+}
+export interface ResponsiveRuleContext {
+    width: number;
+    height?: number;
+}
+export interface ResponsiveRule<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    id?: string;
+    description?: string;
+    /**
+     * Viewport/container condition. All supplied predicates must match.
+     */
+    when: ResponsiveRuleCondition;
+    /**
+     * Shallow prop transform to apply when the condition matches. Nested
+     * `margin`, `frameProps`, `mobileSemantics`, `style`, and `className` are
+     * merged by `resolveResponsiveRules`; other keys replace the base value.
+     */
+    transform: Partial<TProps> & Record<string, unknown>;
+    /**
+     * Higher priority applies later and wins on conflicts. Defaults to source
+     * order when omitted.
+     */
+    priority?: number;
+}
+export interface ResponsiveRuleMatch<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    rule: ResponsiveRule<TProps>;
+    index: number;
+}
+export interface ResponsiveRuleResult<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    props: TProps;
+    matches: ResponsiveRuleMatch<TProps>[];
+}
+export declare function responsiveRuleMatches(rule: ResponsiveRule, context: ResponsiveRuleContext): boolean;
+/**
+ * Resolve matching responsive rules into a transformed prop object. Pure and
+ * SSR-safe. Runtime HOCs can call this with measured container dimensions;
+ * agents and audits can call it with target phone widths.
+ */
+export declare function resolveResponsiveRules<TProps extends Record<string, unknown>>(props: TProps, context: ResponsiveRuleContext, rules?: ReadonlyArray<ResponsiveRule<TProps>> | undefined): ResponsiveRuleResult<TProps>;

package/dist/components/charts/shared/semanticInteractions.d.ts

@@ -0,0 +1,42 @@
+import type { Datum } from "./datumTypes";
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+/** Extra context supplied by Stream Frames to their existing behavior hooks. */
+export interface SemanticInteractionContext {
+    type: "focus" | "activate";
+    inputType: ObservationInputType;
+}
+export type SemanticHoverBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export type SemanticClickBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export declare function observationInputType(pointerType?: string): "pointer" | "touch";
+/**
+ * Stream Frame keyboard navigation lives on a focusable chart wrapper. Let
+ * native controls rendered inside that wrapper (notably widget annotations)
+ * handle their own keys before the chart consumes Enter, Space, or arrows.
+ */
+export declare function isInteractiveKeyboardTarget(event: Pick<ReactKeyboardEvent, "target" | "currentTarget">): boolean;
+/**
+ * Emit the legacy hover event and its semantic focus companion when present.
+ * Keeping both makes the semantic vocabulary additive for existing consumers.
+ */
+export declare function emitHoverObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;
+/** Emit the legacy click event and its semantic activation companion. */
+export declare function emitClickObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;

package/dist/components/charts/shared/sparseArray.d.ts

@@ -24,4 +24,4 @@
  * mutation throws in strict mode rather than corrupting later reads.
  */
 export declare const EMPTY_ARRAY: readonly unknown[];
-export declare function filterSparseArray<T>(input: readonly T[] | undefined | null): T[];
+export declare function filterSparseArray<T extends object>(input: readonly (T | null | undefined)[] | undefined | null): T[];

package/dist/components/charts/shared/streamPropsHelpers.d.ts

@@ -1,8 +1,9 @@
 import type { ReactNode } from "react";
 import type { Datum } from "./datumTypes";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "./semanticInteractions";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { HoverData } from "../../realtime/types";
-import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig } from "./types";
+import type { HoverHighlightMode, LinkedHoverProp, SelectionConfig, ResolvedMobileInteractionConfig } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
@@ -65,20 +66,29 @@ export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMe
  *   - `customClickBehavior` mirrors the click-driving subset
  *     (`onObservation`, `onClick`, `linkedHover` for cross-chart
  *     selection lock).
+ *   - `forceHoverBehavior` / `forceClickBehavior` let composed or
+ *     adapter charts (realtime, matrix cells, custom payload mappers)
+ *     keep their chart-specific callback shape while sharing the same
+ *     mobile predicates and touch-radius plumbing.
  *
  * Returning the props as a spreadable object means HOCs that don't
  * need either get an empty merge that adds nothing.
  */
 export declare function buildCustomBehaviorProps(input: {
     linkedHover?: LinkedHoverProp;
+    selection?: SelectionConfig;
     onObservation?: OnObservationCallback;
     onClick?: ((datum: Datum, position: {
         x: number;
         y: number;
     }) => void) | undefined;
+    hoverRadius?: number;
     hoverHighlight?: HoverHighlightMode;
-    customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    forceHoverBehavior?: boolean;
+    forceClickBehavior?: boolean;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
+    customHoverBehavior: SemanticHoverBehavior;
+    customClickBehavior?: SemanticClickBehavior;
     /**
      * Whether `linkedHover` participates in the click predicate. Most
      * XY / ordinal HOCs say yes — `linkedHover` cross-chart selection
@@ -89,8 +99,10 @@ export declare function buildCustomBehaviorProps(input: {
      */
     linkedHoverInClickPredicate?: boolean;
 }): {
-    customHoverBehavior?: (d: Datum | null) => void;
-    customClickBehavior?: (d: Datum | null) => void;
+    customHoverBehavior?: SemanticHoverBehavior;
+    customClickBehavior?: SemanticClickBehavior;
+    annotationObservationCallback?: OnObservationCallback;
+    hoverRadius?: number;
 };
 /**
  * Resolve the `tooltipContent` prop for the frame.