semiotic 3.8.2 → 3.8.4

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

@@ -14,6 +14,16 @@ export interface SemanticGradientStop {
     /** Optional opacity applied to this stop. */
     opacity?: number;
 }
+/**
+ * Convert value-anchored `semanticGradient` stops (`{ at, color }` on the value
+ * scale, 0–100) into the frame's `gradientFill.colorStops` (offset 0 = top).
+ * Exported so the server (`renderChart`) config resolves it identically to this
+ * HOC — otherwise SSR silently drops `semanticGradient` and paints a flat area.
+ */
+export declare function semanticGradientToColorStops(stops: SemanticGradientStop[]): Array<{
+    offset: number;
+    color: string;
+}>;
 /**
  * AreaChart component props
  */

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/charts/xy/minimapBrushOverlay.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { StreamScales } from "../../stream/types";
+export interface MinimapBrushOverlayProps {
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: StreamScales | null;
+    brushDirection: "x" | "y";
+    extent: [number, number] | null;
+    onBrush: (extent: [number, number] | null) => void;
+}
+export declare function MinimapBrushOverlay({ width, height, margin, scales, brushDirection, extent, onBrush, }: MinimapBrushOverlayProps): React.JSX.Element;

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

@@ -0,0 +1,4 @@
+import * as React from "react";
+import type { MinimapBrushOverlayProps } from "./minimapBrushOverlay";
+/** Renders nothing until d3-brush module resolves, then mounts the brush. */
+export declare function MinimapBrushOverlayLazy(props: MinimapBrushOverlayProps): React.JSX.Element | null;

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

@@ -0,0 +1,8 @@
+import * as React from "react";
+import type { StreamXYFrameHandle } from "../../stream/types";
+export interface ScatterplotMatrixBrushOverlayProps {
+    frameRef: React.RefObject<StreamXYFrameHandle | null>;
+    cellSize: number;
+    onBrush: (extent: [number, number][] | null) => void;
+}
+export declare function ScatterplotMatrixBrushOverlay({ frameRef, cellSize, onBrush, }: ScatterplotMatrixBrushOverlayProps): React.JSX.Element;

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

@@ -0,0 +1,3 @@
+import * as React from "react";
+import type { ScatterplotMatrixBrushOverlayProps } from "./scatterplotMatrixBrushOverlay";
+export declare function ScatterplotMatrixBrushOverlayLazy(props: ScatterplotMatrixBrushOverlayProps): React.JSX.Element | null;

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

@@ -191,6 +191,11 @@ export interface RealtimeFrameHandle {
     remove(id: string | string[]): Datum[];
     /** Update data by ID in place. Requires an ID accessor. Returns previous values. */
     update(id: string | string[], updater: (d: Datum) => Datum): Datum[];
+    /**
+     * Ordinal-only bounded ingest: replace the buffer while preserving category
+     * order and enter/move/exit transitions. XY/network/geo typically omit this.
+     */
+    replace?(data: Datum[]): void;
     clear(): void;
     getData(): Datum[];
     /** Returns the frame's resolved scales, or null if unavailable.

package/dist/components/recipes/gridObservatory.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Pure grid-operations helpers for multi-series power observatories.
+ *
+ * These turn balancing-authority hourly rows into the chart-ready series used by
+ * StackedAreaChart, DifferenceChart, BigNumber, styleRules factories, and
+ * provenanced event annotations. They are domain math — not a React kit — so
+ * agents and pages can share the same pipeline.
+ *
+ * Honesty: {@link reserveMarginPct} is a **readability proxy** from public
+ * demand / net-generation (+ optional interchange) series. It is *not* an ISO
+ * contingency-reserve product. Label it as such in UI and `describeChart` copy.
+ */
+import type { StyleRule } from "../charts/shared/styleRules";
+import type { HatchFill } from "../charts/shared/hatchFill";
+/** Stable fuel keys used across regions when present. */
+export declare const GRID_FUEL_KEYS: readonly ["naturalGas", "coal", "nuclear", "hydro", "wind", "solar", "other"];
+export type GridFuelKey = (typeof GRID_FUEL_KEYS)[number];
+/** Human labels for fuel keys (legend / tooltips). */
+export declare const GRID_FUEL_LABELS: Record<GridFuelKey, string>;
+/**
+ * One hour (or finest grain) in one balancing authority.
+ * Compatible with the strategy schema in docs/strategy/examples-thegrid.md.
+ */
+export type GridHour = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw?: number;
+    netGenMw: number;
+    interchangeMw?: number;
+    fuels: Partial<Record<GridFuelKey, number>>;
+};
+export type ReserveSnapshot = {
+    t: number;
+    ba: string;
+    /** Rough operational headroom proxy — never claim ISO-grade contingency reserve. */
+    reserveMarginPct: number;
+    netLoadMw: number;
+    demandMw: number;
+    netGenMw: number;
+};
+export type ReserveLevels = {
+    /** Margin below this % is "tight" / danger. Default 5. */
+    tight?: number;
+    /** Margin below this % is "watch" / warning. Default 12. */
+    watch?: number;
+    /** Margin at or above this % is comfortable / success. Default 20. */
+    comfortable?: number;
+};
+export type FuelStackRow = {
+    t: number;
+    fuel: GridFuelKey;
+    fuelLabel: string;
+    mw: number;
+    ba: string;
+};
+export type DemandForecastRow = {
+    t: number;
+    a: number;
+    b: number;
+    demandMw: number;
+    forecastMw: number;
+    errorMw: number;
+    ba: string;
+};
+export type OperatingPointSummary = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw: number | null;
+    forecastErrorMw: number | null;
+    netGenMw: number;
+    reserveMarginPct: number;
+    topFuel: GridFuelKey | null;
+    topFuelShare: number;
+    topFuelMw: number;
+    fuelShares: Partial<Record<GridFuelKey, number>>;
+};
+export type GridEventWindow = {
+    id: string;
+    /** Inclusive start epoch ms. */
+    start: number;
+    /** Inclusive end epoch ms. */
+    end: number;
+    label: string;
+    /** Optional longer note for callouts. */
+    note?: string;
+    /** "heat-wave" | "outage" | "demand-spike" | open string. */
+    kind?: string;
+    /** ISO 8601 duration or ms; default "P7D". */
+    ttlHint?: string | number;
+    y?: number;
+    /** Data y for y-threshold style notes. */
+    value?: number;
+};
+/**
+ * Stackable long-form fuel series for StackedAreaChart (`areaBy: "fuel"`).
+ * Zero / missing fuels are omitted so empty keys do not invent area layers.
+ */
+export declare function stackFuelSeries(hours: readonly GridHour[], options?: {
+    fuels?: readonly GridFuelKey[];
+    includeZero?: boolean;
+}): FuelStackRow[];
+/**
+ * DifferenceChart rows: series A = demand, series B = forecast.
+ * Hours without a finite forecast are skipped.
+ */
+export declare function demandForecastRows(hours: readonly GridHour[]): DemandForecastRow[];
+/**
+ * Readability proxy for operational headroom.
+ *
+ * ```
+ * reserveMarginPct = ((supply - demand) / demand) * 100
+ * supply = capacityOrNetGen + max(0, -interchange)  // imports add supply
+ * ```
+ *
+ * When demand is 0, returns 0. Negative values mean demand exceeds supply.
+ *
+ * **Not** ISO contingency reserve (spinning + non-spinning + regulation).
+ * Document that distinction wherever this number is shown.
+ */
+export declare function reserveMarginPct(input: {
+    demand: number;
+    capacityOrNetGen: number;
+    interchange?: number;
+}): number;
+/** Per-hour reserve snapshots derived from {@link GridHour} rows. */
+export declare function reserveSeries(hours: readonly GridHour[]): ReserveSnapshot[];
+/**
+ * Declarative `styleRules` for marks whose primary value is reserve margin %.
+ * Hatch on the tight band so color is not the only encoding.
+ *
+ * Works on BarChart / DotPlot (ordinal) and LineChart / Scatterplot when the
+ * mark value (or `field: "reserveMarginPct"`) is the margin percent.
+ */
+export declare function thresholdBandsForReserve(levels?: ReserveLevels, options?: {
+    field?: string;
+    /** Override hatch for the tight band. */
+    tightHatch?: HatchFill;
+    tightFill?: string;
+    watchFill?: string;
+    comfortableFill?: string;
+}): StyleRule[];
+/**
+ * Annotation band descriptors for reserve threshold strips (y-band style).
+ * Pair with chart `annotations` — not the same object as styleRules.
+ */
+export declare function reserveAnnotationBands(levels?: ReserveLevels): Array<{
+    type: "band";
+    y0: number;
+    y1: number;
+    label: string;
+    color: string;
+    fillOpacity: number;
+    emphasis: "secondary";
+}>;
+/** Summarize the operating point at `now` (or the last hour ≤ now). */
+export declare function summarizeOperatingPoint(hours: readonly GridHour[], now?: number): OperatingPointSummary | null;
+/**
+ * Convert authored event windows into annotation objects with provenance + lifecycle
+ * fields suitable for `applyAnnotationLifecycle`.
+ *
+ * Returns plain annotation dicts (not React nodes). Callers may pass the array to
+ * chart `annotations` after lifecycle treatment.
+ */
+export declare function gridEventAnnotations(events: readonly GridEventWindow[], options?: {
+    now?: number;
+    author?: string;
+    source?: string;
+}): Array<Record<string, unknown>>;
+/** Pick the top N tightest-margin hours for a ranked risk strip. */
+export declare function tightestHours(reserves: readonly ReserveSnapshot[], n?: number): ReserveSnapshot[];
+/** Format MW with locale grouping; returns "—" for non-finite. */
+export declare function formatMw(value: number, digits?: number): string;
+/** Format reserve margin percent with sign awareness. */
+export declare function formatReservePct(value: number, digits?: number): string;

package/dist/components/recipes/recipeChrome.d.ts

@@ -44,6 +44,30 @@ export declare function boundsOf(points: ReadonlyArray<{
     width: number;
     height: number;
 } | null;
+/** Axis-aligned box with a top-left origin (chip, card, scene rect). */
+export interface HullBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type HullPadding = number | {
+    x?: number;
+    y?: number;
+};
+/**
+ * Axis-aligned hull of discrete mark boxes, with optional padding. Use this when
+ * marks are chips/cards with known extents (not just points): the result fully
+ * surrounds the marks so a stroke drawn *after* the marks reads as a true
+ * enclosure (fill under, stroke over). Returns null for an empty set.
+ *
+ * @example
+ * ```ts
+ * const hull = hullFromBoxes(chips, { x: 12, y: 10 })
+ * // overlays: fill rect (under) then marks then stroke-only rect (over)
+ * ```
+ */
+export declare function hullFromBoxes(boxes: ReadonlyArray<HullBox>, padding?: HullPadding): HullBox | null;
 export interface BandLabelProps {
     text: string;
     x: number;

package/dist/components/recipes/sequenceLayout.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Sequence diagram kit — linear spines, span-arc packing, and shared-edge
+ * partition helpers for custom charts that treat a row of marks as a baseline
+ * (dependency arcs, co-reference, genomic links, alternate-hypothesis overlays).
+ *
+ * Pure / SSR-safe. Complements {@link packIntervals} (time tracks) and the
+ * edge-router kit (network S-curves): here the domain is an ordered index on a
+ * baseline and the mark is a vertical-band arc between two anchors.
+ */
+export interface SequenceItem {
+    /** Stable identity used as the position map key. */
+    id: string;
+}
+export interface SequencePosition {
+    id: string;
+    x: number;
+    y: number;
+    /** Zero-based order on the baseline. */
+    index: number;
+}
+export interface LayoutSequenceOptions {
+    width: number;
+    y: number;
+    /** @default min(74, max(34, width * 0.08)) */
+    paddingLeft?: number;
+    /** @default min(74, max(34, width * 0.08)) */
+    paddingRight?: number;
+}
+/**
+ * Place ordered items evenly along a horizontal baseline. Returns a Map keyed
+ * by `id` so callers can look up either end of a span arc in O(1).
+ */
+export declare function layoutSequence(items: readonly SequenceItem[], options: LayoutSequenceOptions): Map<string, SequencePosition>;
+export interface ChipStripItem extends SequenceItem {
+    /** Optional label used by the default width estimator. */
+    label?: string;
+}
+export interface LayoutChipStripOptions extends LayoutSequenceOptions {
+    /** Gap between chips when packing by content width. @default 8 */
+    gap?: number;
+    /**
+     * When true (default), distribute free horizontal space evenly between chips
+     * so the strip still spans the baseline. When false, pack left-to-right.
+     */
+    distribute?: boolean;
+    /** Override per-chip width. Defaults to {@link estimateLabelWidth} of `label`/`id`. */
+    estimateWidth?: (item: ChipStripItem, index: number) => number;
+}
+export interface ChipStripPosition extends SequencePosition {
+    /** Chip width in px (for hulls / hit targets). */
+    width: number;
+}
+/**
+ * Place ordered chips along a baseline, sizing each by estimated label width.
+ * Prefer {@link layoutSequence} when marks are equal-spaced points rather than
+ * variable-width chips.
+ */
+export declare function layoutChipStrip(items: readonly ChipStripItem[], options: LayoutChipStripOptions): Map<string, ChipStripPosition>;
+/**
+ * Rough text width for chip / arc labels. Matches the heuristic used by the
+ * sentence-structure stage and is good enough for layout before paint.
+ */
+export declare function estimateLabelWidth(text: unknown, minimum?: number, charWidth?: number, pad?: number): number;
+export interface SpanInterval {
+    /** Stable identity for the packed result. */
+    id: string;
+    /** Inclusive left index on the sequence baseline. */
+    a: number;
+    /** Inclusive right index on the sequence baseline. */
+    b: number;
+}
+export interface PackedSpanLevel<T extends SpanInterval = SpanInterval> {
+    span: T;
+    /** Zero-based height level (0 = closest to the baseline). */
+    level: number;
+}
+export interface PackSpanLevelsResult<T extends SpanInterval = SpanInterval> {
+    packed: PackedSpanLevel<T>[];
+    /** Number of distinct levels used (`maxLevel + 1`, at least 1). */
+    levelCount: number;
+    maxLevel: number;
+}
+/**
+ * Greedy span packing: assign each interval to the lowest level whose last
+ * right edge is already left of this span's left edge. Short spans are packed
+ * first so long arcs stack above them — the classic dependency-arc layout.
+ *
+ * Indices are treated as inclusive; a span with `a === b` is a zero-width hop.
+ */
+export declare function packSpanLevels<T extends SpanInterval>(spans: readonly T[]): PackSpanLevelsResult<T>;
+export interface ScaleArcBandOptions {
+    /** Y of the sequence baseline (token line). */
+    baselineY: number;
+    /** Top of the free vertical band arcs may occupy. */
+    ceilingY: number;
+    /** From {@link packSpanLevels}. */
+    levelCount: number;
+    /** Vertical room reserved under each peak for a mid-arc label. @default 18 */
+    labelRoom?: number;
+}
+export interface ScaleArcBandResult {
+    /** Height of the shortest (level 0) arc above the baseline foot. */
+    arcLift: number;
+    /** Vertical spacing between successive levels. */
+    levelStep: number;
+}
+/**
+ * Stretch packed arc levels across the free band between `ceilingY` and the
+ * baseline so short plots are not a cramped nest under a blank canvas.
+ */
+export declare function scaleArcBand(options: ScaleArcBandOptions): ScaleArcBandResult;
+export interface SpanArcPathOptions {
+    /**
+     * How far above `baselineY` the arc feet attach (keeps arcs off token chips).
+     * @default 26
+     */
+    footLift?: number;
+}
+/**
+ * Quadratic span arc between two x-positions on a baseline. Pure path `d`
+ * string for SVG overlays / scene edge emission.
+ */
+export declare function spanArcPath(x0: number, x1: number, baselineY: number, peakY: number, options?: SpanArcPathOptions): string;
+/**
+ * Peak y for a packed span level given band metrics from {@link scaleArcBand}.
+ */
+export declare function spanArcPeakY(baselineY: number, level: number, metrics: ScaleArcBandResult): number;
+export type EdgeKeyFn<T> = (edge: T) => string;
+/**
+ * Partition several edge lists into the shared intersection (present in every
+ * set under `keyOf`) and the per-set exclusive remainder. Used by compare views
+ * that paint common topology once and disputed links per hypothesis.
+ *
+ * Shared edges are taken from the first set (stable identity for paint keys).
+ */
+export declare function partitionSharedEdges<T>(edgeSets: readonly (readonly T[])[], keyOf?: EdgeKeyFn<T>): {
+    shared: T[];
+    exclusive: T[][];
+};

package/dist/components/semiotic-recipes-core.d.ts

@@ -39,6 +39,8 @@ export { annotationLayout } from "./recipes/annotationLayout";
 export type { AnnotationLayoutConfig, AnnotationLayoutOptions, AutoPlaceAnnotations, AutoPlaceAnnotationsConfig, AnnotationCohesion, AnnotationAudience, AnnotationMobileConfig, } from "./recipes/annotationLayout";
 export { annotationDensity, annotationBudget, DEFAULT_AREA_PER_ANNOTATION } from "./recipes/annotationDensity";
 export type { AnnotationDensityConfig, AnnotationDensityOptions, AnnotationDensityResult, } from "./recipes/annotationDensity";
+export { GRID_FUEL_KEYS, GRID_FUEL_LABELS, stackFuelSeries, demandForecastRows, reserveMarginPct, reserveSeries, thresholdBandsForReserve, reserveAnnotationBands, summarizeOperatingPoint, gridEventAnnotations, tightestHours, formatMw, formatReservePct, } from "./recipes/gridObservatory";
+export type { GridFuelKey, GridHour, ReserveSnapshot, ReserveLevels, FuelStackRow, DemandForecastRow, OperatingPointSummary, GridEventWindow, } from "./recipes/gridObservatory";
 export { intervalLanesLayout } from "./recipes/intervalLanes";
 export type { IntervalLanesConfig } from "./recipes/intervalLanes";
 export { axisFixedForceLayout, axisFixedForcePositions, rectCollide } from "./recipes/axisFixedForce";
@@ -50,6 +52,8 @@ export type { Run, RunOptions } from "./recipes/runs";
 export { wrapValue, shortestArcDelta, cyclicRangeContains, selectCyclicRange } from "./recipes/cyclical";
 export { packIntervals, activeCountOverDomain } from "./recipes/intervals";
 export type { PackedInterval, PackIntervalsResult, PackIntervalsOptions, ActiveCount, ActiveCountOptions, } from "./recipes/intervals";
+export { layoutSequence, layoutChipStrip, estimateLabelWidth, packSpanLevels, scaleArcBand, spanArcPath, spanArcPeakY, partitionSharedEdges, } from "./recipes/sequenceLayout";
+export type { SequenceItem, SequencePosition, LayoutSequenceOptions, ChipStripItem, LayoutChipStripOptions, ChipStripPosition, SpanInterval, PackedSpanLevel, PackSpanLevelsResult, ScaleArcBandOptions, ScaleArcBandResult, SpanArcPathOptions, EdgeKeyFn, } from "./recipes/sequenceLayout";
 export { polarToXY, xyToAngle, angleScale, radiusScale, ringArcPath, TAU } from "./recipes/radialCoords";
 export type { Point, PolarOptions, AngleScaleOptions, RingArcOptions } from "./recipes/radialCoords";
 export { curvedEdgePath, orthogonalEdgePath, boxEdgeAnchors, fanOutBend, cubicPoint, cubicTangent, cubicPath, } from "./recipes/edgeRouter";
@@ -69,8 +73,8 @@ export type { NetworkSymbolName } from "./stream/symbolPath";
 export { glyphPlacement, glyphExtent, glyphFractionClipRect, DEFAULT_GLYPH_VIEWBOX, DEFAULT_GLYPH_ANCHOR, } from "./stream/glyphDef";
 export type { GlyphDef, GlyphPart, GlyphPlacement } from "./stream/glyphDef";
 export { isotypeInk, isotypePaper, isotypeGhost, isotypeServerGlyph, isotypeChipGlyph, isotypeBoltGlyph, isotypeBusGlyph, isotypePersonPath, isotypePersonGlyph, isotypeNetworkGlyphs, } from "./recipes/isotypeGlyphs";
-export { roundedEnclosure, boundsOf, bandLabel, markCallout, linearAxis, hatchFill } from "./recipes/recipeChrome";
-export type { RoundedEnclosureProps, BandLabelProps, MarkCalloutProps, CalloutConnector, LinearAxisProps, AxisOrient, HatchFillOptions, } from "./recipes/recipeChrome";
+export { roundedEnclosure, boundsOf, hullFromBoxes, bandLabel, markCallout, linearAxis, hatchFill, } from "./recipes/recipeChrome";
+export type { RoundedEnclosureProps, HullBox, HullPadding, BandLabelProps, MarkCalloutProps, CalloutConnector, LinearAxisProps, AxisOrient, HatchFillOptions, } from "./recipes/recipeChrome";
 export { legendGroupsFrom, legendSwatches } from "./recipes/recipeLegend";
 export type { LegendGroupsInput, LegendSwatch, LegendSwatchesProps } from "./recipes/recipeLegend";
 export { buildTooltipEntries, extractTooltipDatum, formatTooltipValue, } from "./recipes/customTooltip";

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

@@ -27,7 +27,9 @@ interface AnnotationScales {
 }
 type AnnotationScale = {
     bivarianceHack(value: DatumValue): number;
-}["bivarianceHack"];
+}["bivarianceHack"] & {
+    domain?: () => DatumValue[];
+};
 interface AnnotationLayout {
     width: number;
     height: number;

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): {