semiotic 3.7.5 → 3.8.0

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/hooks.d.ts

@@ -1,14 +1,25 @@
 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";
 /**
  * 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,7 +41,7 @@ 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.
@@ -41,7 +52,7 @@ export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum,
  * 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: any, i?: number) => any) | 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 +75,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[];
@@ -78,6 +89,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     }) => void;
     hoverHighlight?: HoverHighlightMode;
     colorByField?: string;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
@@ -161,8 +173,15 @@ interface ChartModeInput {
     valueLabel?: string;
     /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
     linkedHover?: any;
+    /** 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 +205,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/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/streamPropsHelpers.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { Datum } from "./datumTypes";
 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 +65,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;
+    forceHoverBehavior?: boolean;
+    forceClickBehavior?: boolean;
+    mobileInteraction?: ResolvedMobileInteractionConfig;
     customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    customClickBehavior?: (d: Datum | null) => void;
     /**
      * Whether `linkedHover` participates in the click predicate. Most
      * XY / ordinal HOCs say yes — `linkedHover` cross-chart selection
@@ -91,6 +100,7 @@ export declare function buildCustomBehaviorProps(input: {
 }): {
     customHoverBehavior?: (d: Datum | null) => void;
     customClickBehavior?: (d: Datum | null) => void;
+    hoverRadius?: number;
 };
 /**
  * Resolve the `tooltipContent` prop for the frame.

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

@@ -0,0 +1,7 @@
+import type { Datum } from "./datumTypes";
+export declare function parseDateLikeString(value: string): number;
+export declare function coerceDateLikeValue(value: unknown): number;
+export declare function coerceTemporalStringRows(data: Datum[] | undefined, fieldName: string | undefined): {
+    data: Datum[] | undefined;
+    failed: boolean;
+};

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

@@ -4,6 +4,8 @@ import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 import type { Datum } from "./datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { ResponsiveRule } from "./responsiveRules";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -44,7 +46,7 @@ export type LinkedBrushProp = string | {
  * Chart display mode — controls default chrome, size, and interaction.
  * User-provided props always override mode defaults.
  */
-export type ChartMode = "primary" | "context" | "sparkline";
+export type ChartMode = "primary" | "context" | "sparkline" | "mobile";
 /**
  * Hover highlighting mode.
  * `true` and `"series"` both dim non-hovered series/categories; the string
@@ -52,6 +54,46 @@ export type ChartMode = "primary" | "context" | "sparkline";
  * more explicit per-series mode.
  */
 export type HoverHighlightMode = boolean | "series";
+export type MobileClearSelectionBehavior = "backgroundTap" | "none";
+export type MobileSnapBehavior = "nearestDatum" | "none";
+export type MobileStandardControlKind = "brush" | "zoom" | "legend";
+export type MobileStandardControlsMode = boolean | "all" | MobileStandardControlKind | MobileStandardControlKind[];
+/**
+ * Touch-first interaction policy for phone-sized chart slots.
+ *
+ * This is intentionally shared by built-in charts, custom charts, audits, and
+ * generated/interoperable chart manifests so mobile behavior is not a
+ * second-class per-component escape hatch.
+ */
+export interface MobileInteractionConfig {
+    /** Explicitly enable or disable mobile interaction for an object config. */
+    enabled?: boolean;
+    /** Convert tap/click on a datum into a persistent selection when possible. */
+    tapToSelect?: boolean;
+    /** Convert hover-linked detail into a tap-lockable state on touch devices. */
+    tapToLockTooltip?: boolean;
+    /** Clear the mobile interaction state when the frame reports a background tap. */
+    clearSelection?: MobileClearSelectionBehavior;
+    /** Comfortable touch target in CSS pixels. Defaults to 44 when mobile is active. */
+    targetSize?: number;
+    /** Hit-testing strategy for imprecise touch input. */
+    snap?: MobileSnapBehavior;
+    /** Preferred brush handle size in CSS pixels for mobile brush affordances. */
+    brushHandleSize?: number;
+    /** Signals that a brush/zoom/legend gesture has a standard-control alternative. */
+    standardControls?: MobileStandardControlsMode;
+}
+export type MobileInteractionProp = boolean | MobileInteractionConfig;
+export interface ResolvedMobileInteractionConfig {
+    enabled: boolean;
+    tapToSelect: boolean;
+    tapToLockTooltip: boolean;
+    clearSelection: MobileClearSelectionBehavior;
+    targetSize: number;
+    snap: MobileSnapBehavior;
+    brushHandleSize: number;
+    standardControls: MobileStandardControlsMode;
+}
 /**
  * Base props shared across all chart components
  */
@@ -72,6 +114,12 @@ export interface BaseChartProps {
     responsiveWidth?: boolean;
     /** Auto-match height to parent container (requires parent with explicit height). Default: false */
     responsiveHeight?: boolean;
+    /** Semantic responsive transformations keyed by measured chart slot, not CSS alone. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** CSS class name for the chart container */
     className?: string;
     /** Chart title displayed at the top */

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

@@ -1,7 +1,8 @@
 import type { Datum } from "./datumTypes";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
-import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
@@ -21,7 +22,7 @@ export interface ChartSetupInput {
     /** The color-by accessor (may be an "actual" colorBy derived from stackBy/groupBy/categoryAccessor) */
     colorBy: Accessor<string> | undefined;
     /** Color scheme name or custom array — undefined lets useColorScale consult the theme */
-    colorScheme: string | string[] | undefined;
+    colorScheme: string | string[] | Record<string, string> | undefined;
     /** Legend interaction mode */
     legendInteraction: LegendInteractionMode | undefined;
     /** Legend position override */
@@ -58,6 +59,10 @@ export interface ChartSetupInput {
     }) => void;
     /** Dim non-hovered series on data mark hover */
     hoverHighlight?: HoverHighlightMode;
+    /** Touch-first interaction policy for phone-sized chart slots */
+    mobileInteraction?: MobileInteractionProp;
+    /** Mobile semantic contract for generated/audited/mobile-aware chart behavior */
+    mobileSemantics?: MobileVisualizationContract;
     /** Loading state */
     loading: boolean | undefined;
     /** Custom content rendered in place of the default skeleton while `loading` is true. */
@@ -95,6 +100,8 @@ export interface ChartSetupResult {
     customHoverBehavior: (d: Datum | null) => void;
     /** Custom click behavior callback for the frame */
     customClickBehavior: (d: Datum | null) => void;
+    /** Resolved touch-first policy for chart wrappers and stream-prop helpers */
+    mobileInteraction: ResolvedMobileInteractionConfig;
     /** Legend config (or undefined if no legend) */
     legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
     /** Computed margin with legend-aware adjustments */

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

@@ -1,7 +1,9 @@
 import type { Ref, RefObject, ReactElement, ReactNode } from "react";
 import { useChartMode } from "./hooks";
 import { type ChartSetupResult } from "./useChartSetup";
-import type { ChartMode, SelectionConfig, LinkedHoverProp } from "./types";
+import type { Accessor, ChartMode, SelectionConfig, LinkedHoverProp, MobileInteractionProp } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
+import type { ResponsiveRule } from "./responsiveRules";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import { type PartialMargin, type MarginType } from "../../types/marginType";
 import type { Datum } from "./datumTypes";
@@ -17,7 +19,7 @@ interface ScaffoldOptions {
     /** Ref forwarded by the HOC. The hook binds the imperative handle internally. */
     imperativeRef: Ref<RealtimeFrameHandle> | undefined;
     /** Which `useFrameImperativeHandle` variant to bind. XY/ordinal frames share "xy". */
-    imperativeVariant: "xy" | "network";
+    imperativeVariant: "xy" | "network" | "geo-points";
     /** Margin shorthand or sided form from the HOC's `margin` prop. */
     margin: PartialMargin | undefined;
     width?: number;
@@ -26,6 +28,9 @@ interface ScaffoldOptions {
     enableHover?: boolean;
     showLegend?: boolean;
     title?: string;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
+    responsiveRules?: ResponsiveRule[];
     mode?: ChartMode;
     xLabel?: string;
     yLabel?: string;
@@ -39,7 +44,7 @@ interface ScaffoldResult<TFrameHandle> {
     normalizedMargin: Partial<MarginType> | undefined;
 }
 /**
- * Scaffold shared by all three custom-layout HOCs: imperative-handle
+ * Scaffold shared by all four custom-layout HOCs: imperative-handle
  * binding, chart-mode resolution, margin normalization. Network HOCs
  * stop here; data-shaped HOCs layer `useChartSetup` on top via
  * `useCustomChartSetup`.
@@ -53,15 +58,19 @@ interface DataSetupOptions extends ScaffoldOptions {
     /** Whether the hover callback should unwrap the datum (ordinal/network = true, XY = false). */
     unwrapData: boolean;
     /** Color scheme threaded into useChartSetup's color resolution. */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /** Semantic color accessor for legend, linked-hover series mode, and frame color config. */
+    colorBy?: Accessor<string>;
     /** Pass-through chart-setup inputs. */
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     onObservation?: OnObservationCallback;
-    onClick?: (datum: any, ev: {
+    onClick?: (datum: Datum, ev: {
         x: number;
         y: number;
     }) => void;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
     chartId?: string;
     loading?: boolean;
     loadingContent?: ReactNode | false;

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

@@ -1,6 +1,7 @@
 import type { ReactNode, ReactElement } from "react";
 import type { Datum } from "./datumTypes";
-import type { Accessor, ChartAccessor, SelectionConfig, LinkedHoverProp } from "./types";
+import type { Accessor, ChartAccessor, SelectionConfig, LinkedHoverProp, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin, MarginType } from "../../types/marginType";
 import { useChartSelection, useChartLegendAndMargin } from "./hooks";
@@ -23,7 +24,7 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
     /** Edge target accessor (used by `inferNodesFromEdges`). */
     targetAccessor?: ChartAccessor<TEdge, string>;
     colorBy?: Accessor<string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** `undefined` defaults to "auto" (on when colorBy is set). */
     showLegend?: boolean;
     legendPosition?: LegendPosition;
@@ -35,6 +36,8 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
         x: number;
         y: number;
     }) => void;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
     /** Used by useChartSelection for chart-type-stamped observation events. */
     chartType: string;
     chartId?: string;
@@ -94,6 +97,7 @@ export interface NetworkChartSetupResult {
     legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
     margin: MarginType;
     legendPosition: LegendPosition;
+    mobileInteraction: ResolvedMobileInteractionConfig;
     customHoverBehavior: ReturnType<typeof useChartSelection>["customHoverBehavior"];
     customClickBehavior: ReturnType<typeof useChartSelection>["customClickBehavior"];
     /**

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

@@ -12,7 +12,7 @@ export interface OrdinalPieceStyleOptions {
     /** Theme categorical palette (from useThemeCategorical). */
     themeCategorical: string[] | undefined;
     /** colorScheme prop — array or string scheme name. */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Stable category-index map for default-fill cycling. */
     categoryIndexMap: Map<string, number>;
     /** User-supplied `frameProps.pieceStyle`. Accepts the looser

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

@@ -30,7 +30,7 @@ export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, s
     /** The color-by accessor (may be derived from stackBy/groupBy/categoryAccessor) */
     colorBy: Accessor<string> | undefined;
     /** Color scheme name or custom array — undefined lets useColorScale consult the theme */
-    colorScheme: string | string[] | undefined;
+    colorScheme: string | string[] | Record<string, string> | undefined;
     /** Whether legend is requested */
     showLegend: boolean | undefined;
     /** Legend position */