semiotic 3.8.1 → 3.8.3

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/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/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;

package/dist/components/charts/xy/LineChart.d.ts

@@ -7,6 +7,7 @@ import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types"
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import { type StyleRule } from "../shared/styleRules";
 import type { AnomalyConfig, ForecastConfig } from "../shared/statisticalOverlays";
+import type { LegendValue } from "../../types/legendTypes";
 /**
  * LineChart component props
  */
@@ -153,6 +154,8 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * @default "right"
      */
     legendPosition?: "right" | "left" | "top" | "bottom";
+    /** Additional legend content. Categorical groups follow the inferred series legend. */
+    legend?: LegendValue;
     /**
      * Tooltip configuration
      */

package/dist/components/legendLayout.d.ts

@@ -0,0 +1,31 @@
+import type { LegendLayout } from "./types/legendTypes";
+export declare const DEFAULT_LEGEND_SWATCH_SIZE = 16;
+export declare const DEFAULT_LEGEND_LABEL_GAP = 6;
+export declare const DEFAULT_LEGEND_ITEM_GAP = 10;
+export declare const DEFAULT_LEGEND_ROW_HEIGHT = 22;
+export interface LegendMetrics {
+    swatchSize: number;
+    labelGap: number;
+    itemGap: number;
+    rowHeight: number;
+    align: "start" | "center" | "end";
+    maxWidth?: number;
+}
+export interface VerticalLegendGroupInput {
+    hasLabel: boolean;
+    itemCount: number;
+}
+export interface VerticalLegendGroupLayout {
+    lineY: number;
+    labelY?: number;
+    itemsY: number;
+    endY: number;
+}
+/** Resolve the dimensions used by both the interactive and static legends. */
+export declare function resolveLegendMetrics(layout?: LegendLayout): LegendMetrics;
+/**
+ * Lay out vertical legend groups using the long-standing Legend.tsx geometry.
+ * Keeping this calculation renderer-neutral prevents SSR and CSR from drifting
+ * when labels, multiple groups, or custom row heights are used.
+ */
+export declare function layoutVerticalLegendGroups(groups: VerticalLegendGroupInput[], rowHeight: number): VerticalLegendGroupLayout[];

package/dist/components/server/serverChartConfigShared.d.ts

@@ -1,13 +1,42 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartMode } from "../charts/shared/types";
+import type { ChartModeInput, ChartModeResult } from "../charts/shared/chartMode";
+import type { SemioticTheme } from "../store/ThemeStore";
+import type { ReactNode } from "react";
 export type FrameType = "xy" | "ordinal" | "network" | "geo" | "physics";
 export type ServerAccessorValue = string | number | boolean | Date | null | undefined;
 export type ServerAccessor = string | ((datum: Datum) => ServerAccessorValue);
 export type ServerColorScheme = string | string[] | Record<string, string> | undefined;
 export type ServerChartData = Datum | Datum[] | null | undefined;
+export type ServerMargin = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export interface ServerChartLayoutDefaults {
+    /** Force a semantic mode for aliases such as the server-only Sparkline. */
+    mode?: ChartMode;
+    /** HOC-specific primary dimensions. Compact/mobile modes retain shared defaults. */
+    primarySize?: {
+        width: number;
+        height: number;
+    };
+    /** Chart-specific margin contract when the HOC does not use mode margins. */
+    margin?: ServerMargin | ((props: Datum, resolved: ChartModeResult) => ServerMargin);
+    /** HOC defaults applied before explicit props and semantic mode resolution. */
+    modeDefaults?: Partial<ChartModeInput>;
+}
+export interface ServerChartOverlayContext {
+    theme: SemioticTheme;
+}
 export interface ChartConfig {
     frameType: FrameType;
+    layout?: ServerChartLayoutDefaults;
     /** Build frame props from HOC-level props */
     buildProps: (data: ServerChartData, colorBy: ServerAccessor | undefined, colorScheme: ServerColorScheme, common: Datum, rest: Datum) => Datum;
+    /** Optional chart-owned SVG overlay rendered after the shared frame. */
+    renderOverlay?: (frameProps: Datum, context: ServerChartOverlayContext) => ReactNode;
 }
 export declare function accessorValue(accessor: ServerAccessor | undefined, fallback: string, d: Datum): ServerAccessorValue;
 export declare function numericValue(value: ServerAccessorValue): number;

package/dist/components/server/serverChartConfigs.d.ts

@@ -12,22 +12,11 @@ export declare const CHART_CONFIGS: {
     StackedAreaChart: ChartConfig;
     Scatterplot: ChartConfig;
     CandlestickChart: ChartConfig;
-    BubbleChart: {
-        frameType: "xy";
-        buildProps: (data: import("./serverChartConfigShared").ServerChartData, colorBy: import("./serverChartConfigShared").ServerAccessor | undefined, colorScheme: import("./serverChartConfigShared").ServerColorScheme, common: import("../stream/networkColorAccessors").Datum, rest: import("../stream/networkColorAccessors").Datum) => {
-            chartType: string;
-            data: import("./serverChartConfigShared").ServerChartData;
-            xAccessor: any;
-            yAccessor: any;
-            colorAccessor: import("./serverChartConfigShared").ServerAccessor | undefined;
-            sizeAccessor: any;
-            sizeRange: any;
-            colorScheme: import("./serverChartConfigShared").ServerColorScheme;
-        };
-    };
+    BubbleChart: ChartConfig;
     ConnectedScatterplot: ChartConfig;
     QuadrantChart: ChartConfig;
     Heatmap: ChartConfig;
+    TemporalHistogram: ChartConfig;
     XYCustomChart: ChartConfig;
     BarChart: ChartConfig;
     StackedBarChart: ChartConfig;

package/dist/components/server/serverChartConfigsXY.d.ts

@@ -1,6 +1,9 @@
 import { type ChartConfig } from "./serverChartConfigShared";
+export declare const bubbleChart: ChartConfig;
 export declare const sparkline: ChartConfig;
 export declare const lineChart: ChartConfig;
+/** Static-data TemporalHistogram mapped onto the shared time-binned XY pipeline. */
+export declare const temporalHistogram: ChartConfig;
 export declare const areaChart: ChartConfig;
 export declare const differenceChart: ChartConfig;
 export declare const stackedAreaChart: ChartConfig;

package/dist/components/server/serverGaugeOverlay.d.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ServerChartOverlayContext } from "./serverChartConfigShared";
+export interface ServerGaugeDescriptor {
+    gMin: number;
+    gMax: number;
+    sweep: number;
+    value?: number;
+    startAngleDeg: number;
+    thresholds?: Array<{
+        value: number;
+        color: string;
+        label?: string;
+    }>;
+    centerX: number;
+    centerY: number;
+    radius: number;
+    innerRadius: number;
+    showScaleLabels: boolean;
+    needleLength: number;
+    showNeedle: boolean;
+    needleColor?: string;
+    contextValue?: string;
+    contextValueY?: number;
+    valueFontSize?: number;
+}
+/** Gauge-owned chrome rendered outside the ordinal scene (needle/readout/ticks). */
+export declare function renderServerGaugeOverlay(frameProps: Datum, { theme }: ServerChartOverlayContext): React.ReactNode;

package/dist/components/server/staticLegend.d.ts

@@ -7,7 +7,7 @@
 import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
 import type { Datum } from "../charts/shared/datumTypes";
-import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+import type { CategoricalLegendConfig, GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 interface LegendItemLayout {
     category: string;
     width: number;
@@ -45,15 +45,21 @@ export interface StaticLegendConfig {
     hasTitle?: boolean;
     /** SSR legend layout controls */
     legendLayout?: LegendLayout;
+    /** Client <Legend> uses a stable 100px vertical placement box. */
+    reservedWidth?: number;
     /** Optional id namespace used for generated SVG ids */
     idPrefix?: string;
 }
 export interface StaticLegendGroupsConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
     legendGroups: LegendGroup[];
+    /** Client <Legend> uses a stable 100px vertical placement box. */
+    reservedWidth?: number;
 }
 export interface StaticGradientLegendConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
     gradient: GradientLegendConfig;
 }
+/** Build the same categorical config shape consumed by the live Legend. */
+export declare function buildStaticCategoricalLegendConfig(categories: string[], colorScheme: string | string[] | Record<string, string> | undefined, theme: SemioticTheme): CategoricalLegendConfig | undefined;
 export declare function measureStaticLegend(config: StaticLegendConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
 export declare function measureStaticLegendGroups(config: StaticLegendGroupsConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
 export declare function measureStaticGradientLegend(config: StaticGradientLegendConfig): {

package/dist/components/server/staticSVGChrome.d.ts

@@ -11,6 +11,7 @@ import type { RenderEvidence } from "./renderEvidence";
 import { resolveTheme, type ThemeInput } from "./themeResolver";
 import type { SemioticTheme } from "../store/ThemeStore";
 import * as React from "react";
+import { type AxisExtentMode } from "../charts/shared/axisExtent";
 export type FrameType = RenderEvidence["frameType"];
 export type StaticPhysicsFrameProps = PhysicsSettledSVGOptions & {
     config?: ConstructorParameters<typeof PhysicsPipelineStore>[0];
@@ -38,7 +39,32 @@ export interface ThemeAwareProps {
     legendLayout?: LegendLayout;
     /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
     _idPrefix?: string;
+    /** Internal HOC-level legend/margin contract metadata. */
+    __explicitMargin?: unknown;
+    __autoLegendMargin?: boolean;
+    /**
+     * The supplied legend already contains the chart HOC's inferred groups.
+     * Specialized charts use this when their semantic categories cannot be
+     * reconstructed from the lower-level frame data (for example Likert's
+     * split neutral buckets). Caller legend groups may still be composed into
+     * that complete value by the chart config.
+     */
+    __legendIncludesAutomatic?: boolean;
 }
+type LegendPosition = "right" | "left" | "top" | "bottom";
+type StaticLegendHostProps = ThemeAwareProps & {
+    legend?: unknown;
+    colorScheme?: string | string[] | Record<string, string>;
+};
+/**
+ * The client HOCs reserve a stable legend gutter before layout. The static
+ * frame API still uses content measurement by default, but renderChart()
+ * marks HOC requests so both paths share that contract. An explicitly set
+ * side remains fully caller-controlled.
+ */
+export declare function hocLegendMarginMinimum(props: ThemeAwareProps, position: LegendPosition): number | undefined;
+/** Whether the caller, rather than the HOC default, owns a legend side. */
+export declare function hasExplicitLegendMargin(props: ThemeAwareProps, position: LegendPosition): boolean;
 export declare function reserveStaticLegendMargin(margin: {
     top: number;
     right: number;
@@ -52,6 +78,8 @@ export declare function reserveStaticLegendMargin(margin: {
     size: [number, number];
     hasTitle?: boolean;
     legendLayout?: LegendLayout;
+    minimumMargin?: number;
+    preserveExplicitMargin?: boolean;
 }): void;
 export declare function reserveLegendConfigMargin(margin: {
     top: number;
@@ -65,6 +93,8 @@ export declare function reserveLegendConfigMargin(margin: {
     size: [number, number];
     hasTitle?: boolean;
     legendLayout?: LegendLayout;
+    minimumMargin?: number;
+    preserveExplicitMargin?: boolean;
 }): void;
 export declare function renderLegendConfig(legend: unknown, options: {
     theme: ReturnType<typeof resolveTheme>;
@@ -79,15 +109,43 @@ export declare function renderLegendConfig(legend: unknown, options: {
     hasTitle?: boolean;
     legendLayout?: LegendLayout;
     idPrefix?: string;
+    reservedWidth?: number;
+}): React.ReactNode;
+/** Reserve the plot gutter for either a supplied legend config or categories. */
+export declare function reserveFrameLegendMargin(margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, options: {
+    props: StaticLegendHostProps;
+    categories: string[];
+    theme: ReturnType<typeof resolveTheme>;
+    size: [number, number];
+    hasTitle?: boolean;
+}): LegendPosition;
+/** Render caller-supplied or automatic categorical legends with one contract. */
+export declare function renderFrameLegend(options: {
+    props: StaticLegendHostProps;
+    categories: string[];
+    theme: ReturnType<typeof resolveTheme>;
+    size: [number, number];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    hasTitle?: boolean;
 }): React.ReactNode;
 export declare function defaultTickFormat(v: number): string;
 /** Render grid lines for XY charts */
-export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string, axisExtent?: AxisExtentMode): React.ReactNode;
 /** Render grid lines for ordinal charts */
 export declare function renderOrdinalGridSVG(store: OrdinalPipelineStore, layout: {
     width: number;
     height: number;
-}, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+}, theme: SemioticTheme, idPrefix?: string, axisExtent?: AxisExtentMode): React.ReactNode;
 /** Wrap SVG content with accessibility attributes */
 export declare function wrapSVG(content: React.ReactNode, opts: {
     width: number;

package/dist/components/stream/GeoPipelineStore.d.ts

@@ -154,6 +154,8 @@ export declare class GeoPipelineStore implements UpdateResultStore {
      * (e.g., applyZoomScale), to avoid redundant scene builds.
      */
     setRotation(rotation: [number, number, number]): void;
+    /** Whether a projection has been resolved by at least one scene compute. */
+    hasProjection(): boolean;
     /** Get current rotation (for external tracking) */
     getRotation(): [number, number, number];
     /** Get the current base projection state (for zoom reset) */

package/dist/components/stream/GeoSVGOverlay.d.ts

@@ -51,6 +51,8 @@ interface GeoSVGOverlayProps {
         y: number;
         r: number;
     }[];
+    /** Project geographic `[longitude, latitude]` annotation coordinates. */
+    geoProjection?: (longitude: number, latitude: number) => [number, number] | null;
 }
 /**
  * The SVG chrome used by StreamGeoFrame.

package/dist/components/stream/OrdinalBrushOverlay.d.ts

@@ -17,7 +17,7 @@
  */
 import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
-interface OrdinalBrushOverlayProps {
+export interface OrdinalBrushOverlayProps {
     width: number;
     height: number;
     totalWidth: number;
@@ -40,4 +40,3 @@ interface OrdinalBrushOverlayProps {
  * In vertical projection, r maps to y-pixels → uses brushY.
  */
 export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): React.JSX.Element;
-export {};

package/dist/components/stream/OrdinalBrushOverlayLazy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy-loaded wrapper for OrdinalBrushOverlay.
+ *
+ * Same rationale as XYBrushOverlayLazy: d3-brush is only needed when brushing
+ * is enabled. Keep it off the default ordinal cold path (BarChart, PieChart…).
+ */
+import * as React from "react";
+import type { OrdinalBrushOverlayProps } from "./OrdinalBrushOverlay";
+export declare function OrdinalBrushOverlayLazy(props: OrdinalBrushOverlayProps): React.JSX.Element | null;

package/dist/components/stream/SceneToSVG.d.ts

@@ -3,18 +3,20 @@
  *
  * Shared module used by Stream Frames for SSR rendering and
  * by semiotic/server for static SVG export.
+ *
+ * Network and geo serializers live in sibling modules
+ * (SceneToSVGNetwork.tsx / SceneToSVGGeo.tsx) and are re-exported below to
+ * keep this file under the file-size ratchet ceiling; low-level helpers
+ * shared across all three (svgFill, safeSvgId, glyphNodeToSVG, ARC_NOOP)
+ * live in sceneToSVGShared.tsx.
  */
 import * as React from "react";
 import type { SceneNode } from "./types";
-import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel } from "./networkTypes";
 import type { OrdinalSceneNode } from "./ordinalTypes";
-import type { GeoSceneNode } from "./geoTypes";
+export { networkSceneNodeToSVG, networkSceneEdgeToSVG, networkLabelToSVG } from "./SceneToSVGNetwork";
+export { geoSceneNodeToSVG } from "./SceneToSVGGeo";
 export declare function xySceneNodeToSVG(node: SceneNode, i: number, idPrefix?: string): React.ReactNode;
-export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
-export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
-export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;
 export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number, idPrefix?: string): React.ReactNode;
-export declare function geoSceneNodeToSVG(node: GeoSceneNode, i: number): React.ReactNode;
 /**
  * Returns true when running in a true server/Node.js context where
  * window and document are not available.

package/dist/components/stream/SceneToSVGGeo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Scene graph → SVG element converters for the geo family.
+ *
+ * Split out of SceneToSVG.tsx (see scripts/file-size-policy.json) to keep
+ * that module under the file-size ratchet ceiling. Re-exported from
+ * SceneToSVG.tsx so existing imports are unaffected.
+ */
+import * as React from "react";
+import type { GeoSceneNode } from "./geoTypes";
+export declare function geoSceneNodeToSVG(node: GeoSceneNode, i: number): React.ReactNode;

package/dist/components/stream/SceneToSVGNetwork.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scene graph → SVG element converters for the network family.
+ *
+ * Split out of SceneToSVG.tsx (see scripts/file-size-policy.json) to keep
+ * that module under the file-size ratchet ceiling. Re-exported from
+ * SceneToSVG.tsx so existing imports are unaffected.
+ */
+import * as React from "react";
+import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel } from "./networkTypes";
+export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
+export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
+export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;

package/dist/components/stream/XYBrushOverlayLazy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lazy-loaded wrapper for XYBrushOverlay.
+ *
+ * d3-brush pulls d3-selection + d3-drag + d3-transition (~14 KB gz). Most XY
+ * charts never enable brushing, so keep that graph out of the default cold path
+ * and only load it when `brush` / `onBrush` is actually used.
+ *
+ * Pattern mirrors `statisticalOverlaysLazy.ts`.
+ */
+import * as React from "react";
+import type { XYBrushOverlayProps } from "./XYBrushOverlay";
+/**
+ * Renders nothing until the brush module resolves, then mounts the real overlay.
+ * Acceptable: brush is interaction-driven; the first paint of the SVG layer can
+ * lag one tick without affecting chart layout or data marks.
+ */
+export declare function XYBrushOverlayLazy(props: XYBrushOverlayProps): React.JSX.Element | null;

package/dist/components/stream/canvasBackground.d.ts

@@ -17,6 +17,13 @@ export interface PaintCanvasBackgroundOptions {
     width: number;
     height: number;
 }
+export type CanvasBackgroundOptions = Pick<PaintCanvasBackgroundOptions, "background" | "hasBackgroundGraphics" | "themeBackground">;
+/**
+ * Select the background token a canvas will attempt to paint. This is kept
+ * separate from the drawing operation so SVG layer composition can use the
+ * exact same visibility decision as the canvas renderer.
+ */
+export declare function resolveCanvasBackground(options: CanvasBackgroundOptions): string | null;
 /**
  * Paint an opaque chart background when appropriate.
  * Returns true if a fill was applied.

package/dist/components/stream/networkTypes.d.ts

@@ -5,7 +5,7 @@ type NetworkDatumComparator = {
     bivarianceHack(a: Datum, b: Datum): number;
 }["bivarianceHack"];
 type NetworkGroupComparator = (a: number, b: number) => number;
-import type { LegendGroup, LegendLayout } from "../types/legendTypes";
+import type { LegendLayout, LegendValue } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { NetworkSymbolName } from "./symbolPath";
@@ -616,9 +616,7 @@ export interface StreamNetworkFrameProps<T = Datum> extends StreamNetworkInterac
     };
     className?: string;
     background?: string;
-    legend?: ReactNode | {
-        legendGroups: LegendGroup[];
-    };
+    legend?: LegendValue;
     legendPosition?: "right" | "left" | "top" | "bottom";
     legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {