semiotic 3.8.2 → 3.8.4

package/dist/components/charts/physics/GaltonBoardChart.d.ts

@@ -3,7 +3,7 @@ import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
 import type { ChartMode } from "../shared/types";
 export interface GaltonBoardReferenceLine {
     value: number;
@@ -42,6 +42,11 @@ export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omi
     styleRules?: StyleRule[];
     referenceLines?: GaltonBoardReferenceLine | GaltonBoardReferenceLine[];
     seed?: number;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     showProjection?: boolean;
     tooltip?: TooltipProp;
     paused?: boolean;

package/dist/components/charts/physics/gauntletChartProps.d.ts

@@ -7,7 +7,7 @@ import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineSto
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { PhysicsProcessBodyGroup } from "./physicsProcessPrimitives";
-import type { PhysicsHocFrameProps, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
+import type { PhysicsHocFrameProps, PhysicsRerunMS, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
 import type { GauntletEvent, GauntletGate, GauntletLayout, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyDefinition } from "./gauntletTypes";
 export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
     data?: TDatum[];
@@ -43,6 +43,12 @@ export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<B
         positiveProperties: Map<string, GauntletPropertyDefinition>;
     }) => string;
     paused?: boolean;
+    /**
+     * Replay the full compound simulation this many milliseconds after it
+     * settles. Omit or pass `null` for a single run; `0` replays on the next
+     * timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     projectPlacement?: (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout) => Partial<GauntletProjectPlacement>;
     showChrome?: boolean;
     /**

package/dist/components/charts/physics/gauntletChrome.d.ts

@@ -12,9 +12,10 @@ export declare function defaultGauntletTooltipContent(hover: PhysicsHoverData):
 export declare function drawGauntletBody(ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style): void;
 export declare function resolveCanvasColor(ctx: CanvasRenderingContext2D, value: Style[keyof Style] | undefined, fallback: string): string;
 export declare function drawTethers(ctx: CanvasRenderingContext2D, bodies: PhysicsBodyState[]): void;
-export declare function GauntletChrome({ layout, states }: {
+export declare function GauntletChrome({ layout, states, compact }: {
     layout: GauntletLayout;
     states: readonly GauntletProjectState[];
+    compact?: boolean;
 }): React.JSX.Element;
 export declare function gauntletSemanticItem(body: PhysicsBodyState): false | {
     label: string;

package/dist/components/charts/physics/gauntletPhysics.d.ts

@@ -10,7 +10,7 @@ export { CORE_KIND, POSITIVE_KIND, NEGATIVE_KIND } from "./gauntletTypes";
 export type { GauntletAccessors, GauntletBodyDatum, GauntletCoreBodyFn, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectPlacementFn, GauntletProjectState, GauntletPropertyDefinition, GauntletPropertyForceContext, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions, GauntletViabilityFn } from "./gauntletTypes";
 export declare const DEFAULT_WIDTH = 900;
 export declare const DEFAULT_HEIGHT = 520;
-export declare function gauntletWallColliders(layout: Pick<GauntletLayout, "width" | "floorY">): NonNullable<PhysicsPipelineConfig["colliders"]>;
+export declare function gauntletWallColliders(layout: Pick<GauntletLayout, "width" | "floorY"> & Partial<Pick<GauntletLayout, "height">>): NonNullable<PhysicsPipelineConfig["colliders"]>;
 export declare function readAccessor<TDatum extends Datum, TValue>(datum: TDatum, index: number, accessor: ChartAccessor<TDatum, TValue> | undefined, fallback: TValue): TValue;
 export declare function propertyLabel(property: GauntletPropertyDefinition | undefined): string;
 export declare function projectCoreId(projectId: string): string;
@@ -23,19 +23,34 @@ export declare const GAUNTLET_WALL: {
     readonly rightInset: 30;
     readonly thickness: 8;
 };
+type GauntletWallLayout = Pick<GauntletLayout, "width" | "floorY"> & Partial<Pick<GauntletLayout, "height">>;
+/** Scale the authored gauntlet corridor into context and sparkline boxes. */
+export declare function resolveGauntletWall(layout: GauntletWallLayout): {
+    readonly left: 28;
+    readonly top: 76;
+    readonly rightInset: 30;
+    readonly thickness: 8;
+} | {
+    left: number;
+    top: number;
+    rightInset: number;
+    thickness: number;
+};
+/** Scale default body/orbit geometry while preserving authored full-size values. */
+export declare function gauntletSpatialScale(layout: GauntletWallLayout): number;
 /**
  * Keep body centers inside the playable gauntlet corridor so satellite
  * property particles never spawn or settle outside the left/right walls
  * (the "stuck on the left" regression for Homes on Main Street).
  */
-export declare function clampGauntletPoint(x: number, y: number, radius: number, layout: Pick<GauntletLayout, "width" | "floorY">): {
+export declare function clampGauntletPoint(x: number, y: number, radius: number, layout: GauntletWallLayout): {
     x: number;
     y: number;
 };
 export declare function buildLayout(size: [number, number], gates: readonly GauntletGate[] | undefined, crashOffset: number): GauntletLayout;
 export declare function defaultPlacement(layout: GauntletLayout): Required<GauntletProjectPlacement>;
 export declare function resolvePlacement<TDatum extends Datum>(project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, projectPlacement: GauntletProjectPlacementFn<TDatum> | undefined): Required<GauntletProjectPlacement>;
-export declare function featureSlot(ids: readonly string[], id: string): {
+export declare function featureSlot(ids: readonly string[], id: string, spatialScale?: number): {
     angle: number;
     index: number;
     radius: number;
@@ -68,4 +83,4 @@ export declare function buildGauntletPhysics<TDatum extends Datum = Datum>(optio
     initialSpawns: PhysicsQueuedSpawn[];
     layout: GauntletLayout;
 };
-export declare function buildNegativeSpawn<TDatum extends Datum>(project: GauntletProjectState<TDatum>, property: GauntletPropertyDefinition, index: number, x: number, y: number, layout: Pick<GauntletLayout, "width" | "floorY">, spawnAt?: number): PhysicsQueuedSpawn;
+export declare function buildNegativeSpawn<TDatum extends Datum>(project: GauntletProjectState<TDatum>, property: GauntletPropertyDefinition, index: number, x: number, y: number, layout: GauntletWallLayout, spawnAt?: number): PhysicsQueuedSpawn;

package/dist/components/charts/physics/gauntletRuntime.d.ts

@@ -34,7 +34,10 @@ export declare function spawnBodiesForGauntletEffect<TDatum extends Datum>(optio
         color?: string;
         durationMs?: number;
         radius?: number;
+        scale?: number;
     }) => unknown;
+    /** Uniform pop-burst scale (see StreamPhysicsPopOptions.scale). */
+    popScale?: number;
 }): void;
 export declare function projectRouteTarget<TDatum extends Datum>(elapsed: number, project: GauntletProjectState<TDatum>, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>, events: readonly GauntletEvent[], gateById: Map<string, GauntletLayout["gates"][number]>, terminalBehavior: "outcome" | "hold-last"): {
     x: number;

package/dist/components/charts/physics/physicsHocUtils.d.ts

@@ -21,6 +21,18 @@ export type PhysicsSharedChartProps = {
 };
 /** Galton / pile sampling mode (orthogonal to ChartMode display modes). */
 export type PhysicsSimulationMode = "sample" | "mechanical";
+/** Delay between a settled physics run and a fresh seeded replay. */
+export type PhysicsRerunMS = number | null;
+/**
+ * Add an optional settle -> delay -> remount loop to a physics HOC.
+ *
+ * Remounting is intentional: it replays the chart's deterministic seed,
+ * initial bodies, and spawn pacing instead of trying to reverse a live store.
+ */
+export declare function usePhysicsRerun(config: StreamPhysicsFrameProps["config"], rerunMS: PhysicsRerunMS | undefined, paused: boolean | undefined, onRerun?: () => void): {
+    config: StreamPhysicsFrameProps["config"];
+    rerunKey: number;
+};
 /**
  * Split ChartMode (`primary`/`context`/`sparkline`/`mobile`) from the
  * Galton/pile `sample`/`mechanical` simulation mode. Accepts legacy

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -9,6 +9,8 @@ import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
 import type { ResponsiveRule } from "../shared/responsiveRules";
+import type { LegendValue } from "../../types/legendTypes";
+import type { PartialMargin } from "../../types/marginType";
 export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
@@ -28,12 +30,7 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Chart height (alternative to size) */
     height?: number;
     /** Chart margins */
-    margin?: {
-        top?: number;
-        right?: number;
-        bottom?: number;
-        left?: number;
-    };
+    margin?: PartialMargin;
     /** CSS class name */
     className?: string;
     onObservation?: OnObservationCallback;
@@ -151,6 +148,8 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     emphasis?: "primary" | "secondary";
     /** Show a legend */
     showLegend?: boolean;
+    /** Additional legend content. Categorical groups follow the inferred category legend. */
+    legend?: LegendValue;
     /** Legend position */
     legendPosition?: LegendPosition;
     /** Legend interaction mode */

package/dist/components/charts/realtime/temporalHistogramConfig.d.ts

@@ -0,0 +1,11 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+/** Resolve the reversed value domain used by downward temporal histograms. */
+export declare function resolveDownwardHistogramExtent<TDatum extends Datum>({ data, valueAccessor, timeAccessor, binSize, valueExtent, extentPadding, }: {
+    data: readonly TDatum[] | undefined;
+    valueAccessor: ChartAccessor<TDatum, number> | undefined;
+    timeAccessor: ChartAccessor<TDatum, number> | undefined;
+    binSize: number;
+    valueExtent: [number, number] | undefined;
+    extentPadding: number | undefined;
+}): [number, number] | undefined;

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

@@ -0,0 +1,15 @@
+import type { Datum } from "./datumTypes";
+export interface PrepareAreaSeriesDataOptions<TDatum extends Datum = Datum> {
+    /** Original prop value; null/undefined means the chart has no bounded data. */
+    data: unknown;
+    /** Sparse-filtered rows used by the chart setup pipeline. */
+    safeData: TDatum[];
+    areaBy?: string | ((datum: TDatum) => unknown);
+    lineDataAccessor: string;
+}
+/**
+ * Normalize AreaChart's two public data shapes into frame-ready point rows.
+ * Kept independent of React so the HOC and synchronous server renderer use
+ * exactly the same grouping/flattening semantics.
+ */
+export declare function prepareAreaSeriesData<TDatum extends Datum = Datum>({ data, safeData, areaBy, lineDataAccessor, }: PrepareAreaSeriesDataOptions<TDatum>): TDatum[];

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

@@ -0,0 +1,75 @@
+import type { ChartMode, LinkedHoverProp, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { MobileVisualizationContract } from "./auditMobileVisualization";
+import type { ResponsiveRule } from "./responsiveRules";
+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;
+/** Runtime guard for public prop bags where `mode` may be chart-specific. */
+export declare function isChartMode(value: unknown): value is ChartMode;
+export interface ChartModeInput {
+    width?: number;
+    height?: number;
+    showAxes?: boolean;
+    showGrid?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    showLabels?: boolean;
+    showCategoryTicks?: boolean;
+    orientation?: string;
+    title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    xLabel?: string;
+    yLabel?: string;
+    categoryLabel?: string;
+    valueLabel?: string;
+    linkedHover?: LinkedHoverProp;
+    mobileInteraction?: MobileInteractionProp;
+    mobileSemantics?: MobileVisualizationContract;
+    responsiveRules?: ResponsiveRule[];
+}
+export interface ChartModeResult {
+    /** Effective mode after responsive rules have been applied. */
+    mode: ChartMode;
+    width: number;
+    height: number;
+    showAxes: boolean;
+    showGrid: boolean;
+    enableHover: boolean;
+    showLegend: boolean | undefined;
+    showLabels: boolean | undefined;
+    title: string | undefined;
+    description: string | undefined;
+    summary: string | undefined;
+    accessibleTable: boolean | undefined;
+    xLabel: string | undefined;
+    yLabel: string | undefined;
+    categoryLabel: string | undefined;
+    valueLabel: string | undefined;
+    marginDefaults: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    compactMode: boolean;
+    mobileInteraction: ResolvedMobileInteractionConfig;
+    mobileSemantics: MobileVisualizationContract | undefined;
+}
+export declare function resolveChartMode(mode: ChartMode | undefined, userProps: ChartModeInput, primaryDefaults?: {
+    width?: number;
+    height?: number;
+}): ChartModeResult;
+/**
+ * Axis-free charts keep their established 10px regular-mode inset while
+ * adopting the shared context/sparkline margins. Reading `resolved` here is
+ * important: responsive rules may have changed the effective chart mode.
+ */
+export declare function resolveAxisFreeMarginDefaults(resolved: Pick<ChartModeResult, "compactMode" | "marginDefaults">): ChartModeResult["marginDefaults"];

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

@@ -32,7 +32,7 @@
  *     schema.json (and MCP responses) but are dropped from validationMap
  *     (which only reads `type` and `enum`).
  */
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function" | "null";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "physics" | "value";
 /**
@@ -157,7 +157,7 @@ export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
 export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
 export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
 export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
-export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline", "mobile"];
 /**
  * Compose a chart's full prop set (bags + ownProps) in deterministic order.
  * ownProps wins on key collision so a chart can override a shared default.

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

@@ -7,6 +7,14 @@ export declare const COLOR_SCHEMES: Record<string, readonly string[] | ((t: numb
  * Default colors for charts
  */
 export declare const DEFAULT_COLORS: readonly string[];
+/** Uniform mark color when no categorical encoding or theme is active. */
+export declare const DEFAULT_COLOR = "#007bff";
+/**
+ * Resolve a categorical palette with one precedence contract for React HOCs,
+ * streaming/custom layouts, and server rendering. Explicit settings always
+ * win; the ambient theme is the default, not an override.
+ */
+export declare function resolveCategoricalPalette(colorScheme: string | string[] | Record<string, string> | undefined, themeCategorical: readonly string[] | undefined, fallback?: readonly string[]): readonly string[];
 /**
  * Pastel palette for depth-based hierarchy coloring (Treemap, CirclePack, TreeDiagram).
  * Index corresponds to hierarchy depth, wraps via modulo.

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

@@ -0,0 +1,3 @@
+import type { Style } from "../../stream/types";
+/** Shared background-land style for geo charts that layer marks over areas. */
+export declare const GEO_BACKGROUND_AREA_STYLE: Style;

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

@@ -12,6 +12,7 @@
  * />
  * ```
  */
+import type { HatchFill } from "./hatchFill";
 export interface HatchPatternOptions {
     /** Background color of the pattern tile */
     background?: string;
@@ -27,9 +28,13 @@ export interface HatchPatternOptions {
 /**
  * Create a repeating diagonal-line hatch pattern for canvas fills.
  *
- * Must be called in a browser environment (needs canvas). Returns null
- * in server/test environments where canvas is unavailable.
+ * In a browser (canvas available) returns a `CanvasPattern`. In server/test
+ * environments — where canvas is unavailable — returns the equivalent
+ * serializable {@link HatchFill} descriptor instead of `null`, so the same
+ * `pieceStyle`/`nodeStyle` renders a hatch through the SVG path rather than
+ * collapsing to the solid fallback. Use {@link isHatchFill} to distinguish the
+ * two forms; both are valid as a `style.fill`.
  */
 export declare function createHatchPattern(options?: HatchPatternOptions, 
 /** Optional target canvas to create the pattern on (for correct DPR scaling) */
-targetCtx?: CanvasRenderingContext2D): CanvasPattern | null;
+targetCtx?: CanvasRenderingContext2D): CanvasPattern | HatchFill | null;

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

@@ -1,26 +1,15 @@
-import { createLegend } from "./legendUtils";
+export { DEFAULT_COLOR } from "./colorUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
+import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, ResolvedMobileInteractionConfig } from "./types";
 import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
+import type { LegendValue } from "../../types/legendTypes";
 import type { Datum } from "./datumTypes";
-import type { MobileVisualizationContract } from "./auditMobileVisualization";
-import type { ResponsiveRule } from "./responsiveRules";
+import type { ChartModeInput, ChartModeResult } from "./chartMode";
+export { DISABLED_MOBILE_INTERACTION, MOBILE_INTERACTION_DEFAULTS, MOBILE_INTERACTION_MIN_HIT_RADIUS, MOBILE_INTERACTION_TARGET_SIZE, isChartMode, resolveChartMode, resolveMobileInteraction, } from "./chartMode";
+export type { ChartModeInput, ChartModeResult } from "./chartMode";
 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).
@@ -113,7 +102,7 @@ export declare function getCrosshairProps(linkedHover: unknown, crosshairSourceI
  * expansion pattern that every chart with color encoding repeats.
  */
 export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, }: {
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, }: {
     data: Array<Datum>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
@@ -122,8 +111,10 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
     userMargin: PartialMargin | undefined;
     defaults?: MarginType;
     categories?: string[];
+    /** Caller legend composed after the chart's inferred categorical groups. */
+    additionalLegend?: LegendValue;
 }): {
-    legend: ReturnType<typeof createLegend> | undefined;
+    legend: LegendValue | undefined;
     margin: MarginType;
     legendPosition: LegendPosition;
 };
@@ -153,67 +144,10 @@ export interface LegendInteractionState {
  * - "isolate": click toggles category visibility; click all to reset
  */
 export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;
-interface ChartModeInput {
-    width?: number;
-    height?: number;
-    showAxes?: boolean;
-    showGrid?: boolean;
-    enableHover?: boolean;
-    showLegend?: boolean;
-    showLabels?: boolean;
-    showCategoryTicks?: boolean;
-    /** "vertical" | "horizontal" — used to shrink the category-axis margin when showCategoryTicks is false */
-    orientation?: string;
-    title?: string;
-    description?: string;
-    summary?: string;
-    accessibleTable?: boolean;
-    xLabel?: string;
-    yLabel?: string;
-    categoryLabel?: string;
-    valueLabel?: string;
-    /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
-    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[];
-}
-/** Result of {@link useChartMode} — exported so declaration emit can name it. */
-export interface ChartModeResult {
-    width: number;
-    height: number;
-    showAxes: boolean;
-    showGrid: boolean;
-    enableHover: boolean;
-    showLegend: boolean | undefined;
-    showLabels: boolean | undefined;
-    title: string | undefined;
-    description: string | undefined;
-    summary: string | undefined;
-    accessibleTable: boolean | undefined;
-    xLabel: string | undefined;
-    yLabel: string | undefined;
-    categoryLabel: string | undefined;
-    valueLabel: string | undefined;
-    marginDefaults: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-    };
-    /** 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.
- * User-provided values always override mode defaults.
+ * React-facing alias for {@link resolveChartMode}. Mode resolution is kept
+ * pure so non-React renderers (notably semiotic/server) consume the exact same
+ * defaults and responsive-rule contract as chart HOCs.
  */
 export declare function useChartMode(mode: ChartMode | undefined, userProps: ChartModeInput, primaryDefaults?: {
     width?: number;
@@ -227,4 +161,3 @@ export declare function resolveAnimateConfig(animate: boolean | {
     duration?: number;
     easing?: "linear" | "ease-out";
 } | undefined): TransitionConfig | undefined;
-export {};

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

@@ -0,0 +1,55 @@
+/**
+ * Pure LineChart series-feature prep for the SSR / renderChart path.
+ *
+ * Mirrors the client HOC orchestration of:
+ *   - `useSeriesFeatures` (forecast / anomaly via `buildForecast`)
+ *   - gapStrategy (break / interpolate / zero)
+ *   - directLabel endpoint annotations
+ *   - segment-aware lineStyle (createSegmentLineStyle)
+ *
+ * Client uses lazy dynamic import + React state for these; SSR can call
+ * the pure statisticalOverlays entry points synchronously.
+ */
+import type { Datum } from "./datumTypes";
+import { type AnomalyConfig, type ForecastConfig } from "./statisticalOverlays";
+export interface LineSeriesSsrInput {
+    data: unknown;
+    xAccessor?: string | ((d: Datum) => unknown);
+    yAccessor?: string | ((d: Datum) => unknown);
+    lineBy?: string | ((d: Datum) => unknown);
+    colorBy?: string | ((d: Datum) => unknown);
+    colorScheme?: unknown;
+    color?: string;
+    forecast?: ForecastConfig;
+    anomaly?: AnomalyConfig;
+    gapStrategy?: "break" | "interpolate" | "zero";
+    directLabel?: boolean | {
+        position?: "start" | "end";
+        fontSize?: number;
+    };
+    /** Existing annotations to merge with statistical + direct-label ones. */
+    annotations?: Datum[];
+    themeCategorical?: string[];
+    /** Base lineStyle from buildLineStyle — wrapped with segment styling when forecast is set. */
+    baseLineStyle?: (d: Datum, group?: string) => Datum;
+}
+export interface LineSeriesSsrResult {
+    data: Datum[];
+    xAccessor: string | ((d: Datum) => unknown);
+    yAccessor: string | ((d: Datum) => unknown);
+    groupAccessor: string | ((d: Datum) => unknown) | undefined;
+    colorAccessor: string | ((d: Datum) => unknown) | undefined;
+    annotations: Datum[];
+    lineStyle?: (d: Datum, group?: string) => Datum;
+    yExtent?: [number, number];
+    /** Extra right/left margin for direct labels. */
+    marginExtra?: {
+        left?: number;
+        right?: number;
+    };
+}
+/**
+ * Prepare LineChart props for static SSR: forecast/anomaly data + annotations,
+ * gap handling, direct labels, segment lineStyle.
+ */
+export declare function prepareLineSeriesForSsr(input: LineSeriesSsrInput): LineSeriesSsrResult;

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

@@ -43,7 +43,7 @@ export type LinkedBrushProp = string | {
     yField?: string;
 };
 /**
- * Chart display mode — controls default chrome, size, and interaction.
+ * Chart display mode — controls default decoration, size, and interaction.
  * User-provided props always override mode defaults.
  */
 export type ChartMode = "primary" | "context" | "sparkline" | "mobile";
@@ -98,7 +98,7 @@ export interface ResolvedMobileInteractionConfig {
  * Base props shared across all chart components
  */
 export interface BaseChartProps {
-    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    /** Display mode: "primary" (full decoration), "context" (compact), "sparkline" (inline), or "mobile" (touch-first) */
     mode?: ChartMode;
     /** Chart width in pixels. Default: 600 */
     width?: number;

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

@@ -7,6 +7,7 @@ import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { ReactElement, ReactNode } from "react";
+import type { LegendValue } from "../../types/legendTypes";
 /**
  * Input parameters for useChartSetup.
  *
@@ -43,6 +44,8 @@ export interface ChartSetupInput {
     chartId: string | undefined;
     /** Show legend override */
     showLegend: boolean | undefined;
+    /** Caller legend appended to inferred categorical legend groups. */
+    legend?: LegendValue;
     /** User-provided margin */
     userMargin: PartialMargin | undefined;
     /** Mode-resolved margin defaults */

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

@@ -8,6 +8,7 @@ import type { OnObservationCallback } from "../../store/ObservationStore";
 import { type PartialMargin, type MarginType } from "../../types/marginType";
 import type { Datum } from "./datumTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendValue } from "../../types/legendTypes";
 /**
  * Margin shorthand → sided form. The Stream*Frame margin props only
  * accept the sided object form, so HOCs that expose the user-friendly
@@ -64,6 +65,8 @@ interface DataSetupOptions extends ScaffoldOptions {
     colorScheme?: string | string[] | Record<string, string>;
     /** Semantic color accessor for legend, linked-hover series mode, and frame color config. */
     colorBy?: Accessor<string>;
+    /** Caller legend appended to the inferred colorBy legend. */
+    legend?: LegendValue;
     /** Pass-through chart-setup inputs. */
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;

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

@@ -1,8 +1,9 @@
 import type { Datum } from "./datumTypes";
 import type { Accessor, ChartAccessor } from "./types";
 import type { SelectionHookResult, SelectionStyleConfig } from "./selectionUtils";
-import { type StyleRule, type StyleRuleContext } from "./styleRules";
-export interface XYLineStyleOptions {
+import type { XYLineBaseStyleOptions } from "./xyLineStyle";
+import type { StyleRule, StyleRuleContext } from "./styleRules";
+export interface XYLineStyleOptions extends XYLineBaseStyleOptions {
     /**
      * Base stroke width. The top-level `strokeWidth` override below
      * wins via `mergeShapeStyle` when both are supplied.

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

@@ -5,7 +5,7 @@ export interface ValidationResult {
     valid: boolean;
     errors: string[];
 }
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function" | "null";
 export interface PropDef {
     type: PropType | PropType[];
     enum?: readonly string[];

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

@@ -0,0 +1,21 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import { type StyleRule, type StyleRuleContext } from "./styleRules";
+/** Pure portion of the LineChart style contract, shared by CSR and SSR. */
+export interface XYLineBaseStyleOptions {
+    lineWidth?: number;
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    colorScale?: (value: string) => string;
+    color?: string;
+    resolveStroke?: (datum: Datum, group?: string) => string;
+    fillArea?: boolean | string[];
+    areaOpacity?: number;
+    styleRules?: ReadonlyArray<StyleRule>;
+    ruleContext?: (datum: Datum, group?: string) => StyleRuleContext;
+}
+/**
+ * Build the deterministic data-to-style callback used before primitive and
+ * selection overlays. Keeping this free of React lets renderChart() apply the
+ * same default/color/fill/rule precedence as the client HOC.
+ */
+export declare function buildXYLineBaseStyle(options: XYLineBaseStyleOptions): (datum: Datum, group?: string) => Datum;