semiotic 3.5.1 → 3.5.3

package/dist/components/charts/network/processSankey/streamingLayout.d.ts

@@ -0,0 +1,71 @@
+import type { NetworkCustomLayout } from "../../../stream/networkCustomLayout";
+import type { BezierCache } from "../../../stream/networkTypes";
+import type { Datum } from "../../shared/datumTypes";
+export interface ProcessSankeyBandSpec {
+    id: string;
+    /** Outer band perimeter — same path used for fill and stroke. */
+    pathD: string;
+    fill: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Per-edge 20-px gradient stubs (band-color fade-in for
+     *  systemInTime, fade-out for systemOutTime). When at least one
+     *  stub is present, the band paints outline-only and the stubs
+     *  are the only colored regions inside the perimeter. */
+    gradientStubs?: BandGradientStub[];
+    /** The user's raw node datum, surfaced as `data` in HoverData. */
+    rawDatum: Datum;
+    /** Pre-computed label x/y for the node band. */
+    labelX: number;
+    labelY: number;
+    labelText: string;
+}
+export interface BandGradientStub {
+    pathD: string;
+    x0: number;
+    x1: number;
+    from: 0 | 1;
+    to: 0 | 1;
+}
+export interface ProcessSankeyRibbonSpec {
+    id: string;
+    pathD: string;
+    fill: string;
+    opacity: number;
+    /** The user's raw edge datum, surfaced as `data` in HoverData. */
+    rawDatum: Datum;
+    /**
+     * Pre-computed cubic bezier control points + halfWidth for the
+     * shared particle pipeline. ProcessSankey writes these alongside
+     * the ribbon's path-D string so the frame's particle pool can
+     * spawn / step / render against them without re-deriving the
+     * ribbon geometry. Optional — when omitted the ribbon paints
+     * normally but no particles flow along it.
+     */
+    bezier?: BezierCache;
+}
+export interface ProcessSankeyLayoutConfig {
+    bands: ProcessSankeyBandSpec[];
+    ribbons: ProcessSankeyRibbonSpec[];
+    /** Optional dim opacity for unselected bands/ribbons (linkedHover). */
+    showLabels?: boolean;
+}
+/**
+ * Marker attached to scene-edge datums so the HOC's `tooltipContent`
+ * can route node bands vs. flow ribbons through different default
+ * bodies. `data` still carries the user's original node/edge datum.
+ */
+export interface SceneDatumPayload {
+    __kind: "band" | "ribbon";
+    /** Original node/edge record, as the user pushed it. */
+    data: Datum;
+    /** Stable id for hit-deduplication and ref operations. */
+    id: string;
+}
+export declare const emitProcessSankeyScenes: NetworkCustomLayout<ProcessSankeyLayoutConfig>;
+/**
+ * Test whether an arbitrary HoverData/datum-shaped value carries the
+ * ProcessSankey scene marker. Lets the HOC's tooltipContent narrow to
+ * the band/ribbon variants without leaking the marker key everywhere.
+ */
+export declare function isProcessSankeyScenePayload(d: unknown): d is SceneDatumPayload;

package/dist/components/charts/network/processSankey/tooltipUtils.d.ts

@@ -0,0 +1,41 @@
+import type { ProcessSankeyNodeData } from "./algorithm";
+export interface MassHistoryRow {
+    t: number;
+    total: number;
+}
+export interface MassHistoryRowMarked extends MassHistoryRow {
+    /** "min" | "q25" | "median" | "q75" | "max" — present only when the
+     *  full series was condensed via `pickMassQuantiles`. */
+    mark?: string;
+}
+/**
+ * Distinct (time, total-mass) tuples drawn from a node's sample series.
+ * The same `(t, total)` pair never appears twice — the layout's
+ * same-time pre/post sample collapse is preserved here. Returns an
+ * empty array when `data` has no samples (or is undefined).
+ */
+export declare function massHistoryRows(data: ProcessSankeyNodeData | undefined): MassHistoryRow[];
+/** Number of quantile picks emitted on truncation. Fixed at five —
+ *  `min`, `q25`, `median`, `q75`, `max` — because the picks are
+ *  semantic (named labels), not cap-driven. The `truncateAt` parameter
+ *  on `pickMassQuantiles` controls *when* to truncate, not how many to
+ *  return. */
+export declare const QUANTILE_PICK_COUNT = 5;
+/**
+ * Condense a row series down to the five mass-quantile picks —
+ * `min`, `q25`, `median`, `q75`, `max` — re-sorted by time so the
+ * tooltip table reads chronologically. Returns the input unchanged
+ * when its length is at or below `truncateAt` (default 5).
+ *
+ * Same-time collisions are deduplicated, so very small or very flat
+ * series may yield fewer than five output rows even when truncation
+ * fires; the marks attached are the first ones encountered for each
+ * surviving timestamp, which keeps `min` and `max` stable when ties
+ * are present.
+ *
+ * Note: `truncateAt` is the *trigger threshold*, not the output cap —
+ * once truncation fires, the output always emits the five quantile
+ * picks. To raise/lower the threshold without changing the picks,
+ * pass a different `truncateAt`; to vary the picks, fork this util.
+ */
+export declare function pickMassQuantiles(rows: MassHistoryRow[], truncateAt?: number): MassHistoryRowMarked[];

package/dist/components/charts/ordinal/BarChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BarChart component props
  */
@@ -90,6 +91,17 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Datum[];
+    /**
+     * Overlay a regression line through the bar tops. Accepts `true`
+     * (linear), a method name (`"linear"` | `"polynomial"` | `"loess"`),
+     * or a full `RegressionConfig`. The regression treats categories
+     * as a numeric category-index for fit input; pixel positions are
+     * resolved through the band scale, so the line passes through bar
+     * centers. Best for ordered categories (months, quarters, score
+     * buckets) where a slope reads as a meaningful trend. Sugar over
+     * the `trend` annotation.
+     */
+    regression?: RegressionProp;
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
     /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */

package/dist/components/charts/ordinal/DotPlot.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type RegressionProp } from "../shared/regressionUtils";
 export interface DotPlotProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -34,6 +35,14 @@ export interface DotPlotProps<TDatum extends Datum = Datum> extends BaseChartPro
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Datum[];
+    /**
+     * Overlay a regression line through the dots. Same shape as
+     * Scatterplot's regression prop — accepts boolean, method-string,
+     * or full `RegressionConfig`. Pixel positions resolve through the
+     * band scale, so the line passes through dot centers. Sugar over
+     * the `trend` annotation.
+     */
+    regression?: RegressionProp;
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
     /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */

package/dist/components/charts/ordinal/GaugeChart.d.ts

@@ -27,6 +27,11 @@ export interface GaugeChartProps extends BaseChartProps {
     backgroundColor?: string;
     /** Arc thickness as fraction of radius (0–1, default 0.3) */
     arcWidth?: number;
+    /** Pixel radius for the rounded ends of each arc segment, same prop
+     *  semantics as `DonutChart.cornerRadius`. Default `undefined`
+     *  (sharp corners). Useful for the "pill" aesthetic where each
+     *  threshold zone reads as a discrete capsule. */
+    cornerRadius?: number;
     /** Show needle indicator (default true) */
     showNeedle?: boolean;
     /** Needle color (default: var(--semiotic-text, #333)) */
@@ -94,6 +99,21 @@ export interface GaugeChartProps extends BaseChartProps {
  *   fillZones
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Rounded segment ends — same `cornerRadius` semantics as DonutChart.
+ * // Each threshold zone reads as a capsule with the others.
+ * <GaugeChart
+ *   value={65}
+ *   thresholds={[
+ *     { value: 60, color: "#22c55e" },
+ *     { value: 80, color: "#f59e0b" },
+ *     { value: 100, color: "#ef4444" },
+ *   ]}
+ *   cornerRadius={6}
+ * />
+ * ```
  */
 export declare const GaugeChart: {
     (props: GaugeChartProps & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -83,6 +83,11 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
         color: string;
         opacity?: number;
     };
+    /** Rounded corner radius (in pixels) for the outermost ends of each
+     *  lane. Both ends round: left+right in horizontal orientation, top+bottom
+     *  in vertical. Middle segments of multi-segment lanes stay square so
+     *  pieces visually butt against each other. */
+    roundedTop?: number;
     /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
     valueExtent?: [number | undefined, number | undefined] | [number];
     /** Pass-through props to StreamOrdinalFrame */

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

@@ -87,6 +87,8 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -6,7 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
-export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
+export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Time interval for binning */
@@ -103,6 +103,8 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
     transition?: TransitionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Brush configuration. `true` defaults to `{ dimension: "x", snap: "bin" }`. */
@@ -137,7 +139,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
     pointIdAccessor?: string | ((d: Datum) => string);
 }
 /**
- * RealtimeTemporalHistogram - Streaming temporal histogram.
+ * RealtimeHistogram - Streaming temporal histogram.
  *
  * Wraps StreamXYFrame with `chartType="bar"` and `runtimeMode="streaming"`,
  * binning pushed data points into time-windowed bars. Supports both simple
@@ -149,7 +151,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * @example
  * ```tsx
  * // Simple temporal histogram — push each event, the chart bins by time
- * <RealtimeTemporalHistogram
+ * <RealtimeHistogram
  *   ref={ref}
  *   binSize={20}
  *   fill="#007bff"
@@ -160,7 +162,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * @example
  * ```tsx
  * // Stacked by category — same push API, color by status field
- * <RealtimeTemporalHistogram
+ * <RealtimeHistogram
  *   ref={ref}
  *   binSize={25}
  *   categoryAccessor="category"
@@ -169,14 +171,17 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * />
  * ```
  */
-export declare const RealtimeTemporalHistogram: {
-    <TDatum extends Datum = Datum>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+export declare const RealtimeHistogram: {
+    <TDatum extends Datum = Datum>(props: RealtimeHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-/** @deprecated Use RealtimeTemporalHistogram instead */
-export declare const RealtimeHistogram: {
-    <TDatum extends Datum = Datum>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+/** @deprecated Use `RealtimeHistogram` (the canonical public name) instead. The
+ *  `RealtimeTemporalHistogram` alias is preserved for back-compat with code
+ *  written before the rename and will be removed in a future major version. */
+export declare const RealtimeTemporalHistogram: {
+    <TDatum extends Datum = Datum>(props: RealtimeHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-/** @deprecated Use RealtimeTemporalHistogramProps instead */
-export type RealtimeHistogramProps = RealtimeTemporalHistogramProps;
+/** @deprecated Use `RealtimeHistogramProps` instead. Same component, just the
+ *  pre-rename type alias. */
+export type RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> = RealtimeHistogramProps<TDatum>;

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

@@ -89,6 +89,8 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -87,6 +87,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -89,6 +89,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

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

@@ -40,6 +40,25 @@ export declare function buildDefaultRealtimeTooltip<TDatum extends Datum = Datum
  * scene builder).
  */
 export declare function buildWaterfallTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+/**
+ * Histogram-specific default tooltip.
+ *
+ * The barScene's histogram path enriches each rect's datum with
+ * `{ binStart, binEnd, total, category?, categoryValue? }`. The generic
+ * `x: <time>, y: <value>` shape produces empty strings on those bins
+ * because neither `time` nor `value` exists on the aggregated payload.
+ * This builder surfaces the fields that actually carry meaning for a
+ * histogram bin:
+ *
+ *   range:    <binStart>–<binEnd>
+ *   count:    <total>
+ *   category: <category>        (only when categoryAccessor is set)
+ *
+ * Falls back to the canonical x/y shape if a bin's enriched fields are
+ * absent — guards against a non-streaming render path or a static frame
+ * that bypasses the bin scene.
+ */
+export declare function buildHistogramTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
 /**
  * Heatmap-specific default tooltip.
  *

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

@@ -0,0 +1,59 @@
+/**
+ * Equidistant tick generation for the `axisExtent="exact"` axis mode.
+ *
+ * The default "nice" mode (d3 scale's `.ticks(count)` algorithm)
+ * returns aesthetically-rounded tick values WITHIN the data domain —
+ * the first tick may sit above the data min and the last tick may
+ * sit below the data max. That's the standard reading: round labels
+ * win, exact data bounds lose.
+ *
+ * "exact" mode reverses that tradeoff. The first tick sits exactly at
+ * `dataMin`, the last tick sits exactly at `dataMax`, and the
+ * intermediate ticks are equidistant within the domain. Labels are
+ * whatever the value formatter produces — often not round.
+ *
+ * Works on `scaleLinear` and `scaleTime` (operates on millisecond
+ * timestamps, returns Date objects so downstream formatters receive
+ * the same shape they get from `scale.ticks()`).
+ *
+ * `scaleLog` is supported but the ticks come out evenly spaced in
+ * VALUE space, not pixel space — `[1, 250.75, 500.5, 750.25, 1000]`
+ * instead of `[1, 10, 100, 1000]`. That's intentional for the
+ * "endpoints must read as the actual data bounds" use case the
+ * feature was added for, but it's not "equidistant on the rendered
+ * axis". Users that want log-space-equidistant ticks should pass
+ * explicit `tickValues` (e.g. `[1, 10, 100, 1000]`) — those bypass
+ * `axisExtent` entirely.
+ */
+export type AxisExtentMode = "nice" | "exact";
+/** A d3-style continuous scale (linear, time, log) — the bit we use.
+ *  The `domain()` return type stays as `number[]` / `Date[]` rather
+ *  than a strict 2-tuple because that's what d3-scale's own types
+ *  declare (the runtime contract is "first and last elements are the
+ *  bounds" — d3 never returns a single-element domain in practice). */
+type TickableScale<T = number | Date> = {
+    domain(): T[];
+    ticks(count?: number): T[];
+};
+/**
+ * Generate `count` ticks evenly spaced across the scale's domain,
+ * inclusive of both endpoints. For a domain of `[lo, hi]` and a
+ * count of `n`, returns `[lo, lo + step, ..., hi]` where
+ * `step = (hi - lo) / (n - 1)`.
+ *
+ * Edge cases:
+ * - `count < 2` returns just the two endpoints.
+ * - Empty/zero-width domain returns the endpoints unchanged.
+ * - Date-valued domain returns Date objects (preserving the shape
+ *   d3-scale-time's `.ticks()` returns).
+ */
+export declare function equidistantTicks<T extends number | Date>(scale: TickableScale<T>, count: number): T[];
+/**
+ * Return either equidistant ticks (when `mode === "exact"`) or the
+ * scale's own d3-generated ticks (default "nice" behavior).
+ *
+ * Centralized so XY and ordinal overlay code paths can both call
+ * one function instead of branching at every `.ticks()` site.
+ */
+export declare function ticksForMode<T extends number | Date>(scale: TickableScale<T>, count: number, mode: AxisExtentMode | undefined): T[];
+export {};

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

@@ -35,6 +35,73 @@
 export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime";
+/**
+ * Capability tags for runtime behavior. Driven by the
+ * `hoc-frame-architecture-audit` Phase 1: each chart declares which
+ * features it actually supports so docs, AI/MCP tools, and CI gates
+ * can read structured truth instead of inferring it from the source.
+ *
+ * All fields are required so a new chart entry can't omit them
+ * silently — the audit's anti-goal "Do not make registry metadata
+ * aspirational. It should describe real runtime behavior and be
+ * checked." applies here.
+ */
+export interface ChartCapabilities {
+    /**
+     * Render pipeline. `canvas` for Stream-Frame-driven charts that
+     * paint to canvas with SVG overlays for chrome (the common case).
+     * `svg` for charts that are pure SVG (none today, but reserved).
+     * `hybrid` for charts that use both — currently every Stream-Frame
+     * HOC qualifies as hybrid; reserve `canvas` for any future
+     * canvas-only fallback.
+     */
+    renderModes: Array<"canvas" | "svg" | "hybrid">;
+    /** Renders a legend swatch column when `colorBy` (or equivalent)
+     *  resolves to non-empty categories. */
+    supportsLegend: boolean;
+    /** Reads from a `selection` prop and dims/highlights matching
+     *  marks via `wrapStyleWithSelection` or equivalent. */
+    supportsSelection: boolean;
+    /** Produces a hover-driven selection (used by linked crosshair /
+     *  cross-filter patterns) via `linkedHover`. */
+    supportsLinkedHover: boolean;
+    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
+     *  can mutate the data list without re-rendering. Hierarchy
+     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
+     *  pure-synthetic charts (GaugeChart) declare false. */
+    supportsPush: boolean;
+    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
+     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
+     *  charts (none yet) and HOC-SSR exclusions also declare false. */
+    supportsSSR: boolean;
+    /**
+     * How color is consumed by the chart's data marks.
+     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
+     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
+     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
+     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
+     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
+     */
+    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
+    /**
+     * Where the geometry comes from.
+     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
+     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
+     * - `custom`: emitted via the frame's customLayout escape hatch
+     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
+     *   XYCustomChart, OrdinalCustomChart).
+     * - `synthetic`: no layout — the chart constructs its scene from
+     *   the input value(s) directly (GaugeChart computes arc geometry).
+     */
+    layoutMode: "plugin" | "custom" | "synthetic";
+    /**
+     * Free-form tag list for opt-in features that don't fit the
+     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
+     * "streamgraph", "minimap". Used by docs feature tables and
+     * potential capability-driven AI suggestions.
+     */
+    specialFeatures: string[];
+}
 export interface ChartPropSpec {
     /** Allowed runtime types. May be a single value or a union. */
     type: PropType | PropType[];
@@ -71,6 +138,14 @@ export interface ChartSpec {
     propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
     /** Chart-specific prop spec, overlaid on top of the composed bags. */
     ownProps: Record<string, ChartPropSpec>;
+    /**
+     * Capability matrix — declarative facts about runtime behavior.
+     * Drives docs feature tables, capability-aware AI/MCP tools, and
+     * the `check:capabilities` drift gate (which verifies, e.g., that
+     * a chart claiming `supportsSSR: true` has a matching entry in
+     * `serverChartConfigs.ts`).
+     */
+    capabilities: ChartCapabilities;
 }
 export declare const PROP_BAGS: {
     readonly common: Record<string, ChartPropSpec>;

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

@@ -62,12 +62,18 @@ export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum)
  */
 export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[]): (v: string) => string;
 /**
- * Generates a size function based on sizeBy configuration
+ * Generates a size function based on sizeBy configuration.
+ *
+ * Output is clamped to `sizeRange`. A pushed point whose `sizeBy`
+ * value falls outside the currently-known domain (which can happen
+ * in push mode before the running min/max catches up) renders at
+ * the boundary radius rather than producing an arbitrarily large
+ * (or negative) pixel value.
  *
  * @param dataPoint - The data point
  * @param sizeBy - Field name or function to determine size
  * @param sizeRange - Min and max size range [min, max]
  * @param domain - Optional domain for scaling [minValue, maxValue]
- * @returns Size value
+ * @returns Size value, clamped to `sizeRange` when a domain is given
  */
 export declare function getSize(dataPoint: Datum, sizeBy: string | ((d: Datum) => number), sizeRange?: [number, number], domain?: [number, number]): number;

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

@@ -4,15 +4,13 @@ import type { Accessor } from "./types";
  * Flatten a hierarchical data structure into an array of all nodes
  * by recursively traversing children.
  */
-export declare function flattenHierarchy(data: Datum | null, childrenAccessor: string | ((d: Datum) => any[])): Array<Datum>;
+export declare function flattenHierarchy(data: Datum | null, childrenAccessor: string | ((d: Datum) => Datum[])): Array<Datum>;
 /**
  * Infer nodes from edges when a nodes array is not provided.
  * Extracts unique source/target IDs and returns `{ id }` objects.
  * Returns the provided nodes array if it's non-empty.
  */
-export declare function inferNodesFromEdges(nodes: any[] | undefined, edges: any[], sourceAccessor: string | ((d: Datum) => string), targetAccessor: string | ((d: Datum) => string)): Array<{
-    id: string;
-}>;
+export declare function inferNodesFromEdges(nodes: Datum[] | undefined, edges: Datum[], sourceAccessor: string | ((d: Datum) => string), targetAccessor: string | ((d: Datum) => string)): Datum[];
 /**
  * Convert a valueAccessor prop into a hierarchy sum function.
  * Used by TreeDiagram, Treemap, and CirclePack for d3-hierarchy's `.sum()`.
@@ -26,7 +24,7 @@ export declare function createEdgeStyleFn({ edgeColorBy, colorBy, colorScale, no
     edgeColorBy: "source" | "target" | "gradient" | ((d: Datum) => string);
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
-    nodeStyleFn: (d: any, index?: number) => Datum;
+    nodeStyleFn: (d: Datum, index?: number) => Datum;
     edgeOpacity: number;
     baseStyle?: Record<string, string | number>;
 }): (d: Datum) => Datum;

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

@@ -0,0 +1,99 @@
+/**
+ * radialGeometry — pure math helpers for radial chart authoring.
+ *
+ * The original consumer is `GaugeChart`, which needs to:
+ *   - Convert a sweep angle (degrees) into start-angle + radian
+ *     forms that align with the convention pieScene.ts uses
+ *     (0° = 12 o'clock, positive = clockwise, gap centered at the
+ *     6 o'clock position).
+ *   - Map a value in `[min, max]` to its angle along the arc.
+ *   - Compute the arc's visible bounding box in unit-circle coords
+ *     so a container can fit the arc and pick a maximum radius.
+ *
+ * Custom radial chart authors using `XYCustomChart` or building a
+ * bespoke radial layout can reach for the same primitives without
+ * reimplementing the trigonometry. Surface intentionally tight —
+ * each function is a few lines of math with a documented input
+ * convention.
+ */
+/** Result of `sweepToAngles`. All angles are in the
+ *  12-o'clock-zero, clockwise-positive convention used by pieScene
+ *  and the underlying gauge implementation. */
+export interface SweepAngles {
+    /** Full sweep angle in radians. */
+    sweepRad: number;
+    /** Gap angle (the unfilled portion) in degrees. */
+    gapDeg: number;
+    /** Starting angle of the arc, measured in degrees clockwise from
+     *  12 o'clock. The gap is centered at 6 o'clock (180°), so the
+     *  arc starts at `180° + gapDeg / 2`. */
+    startAngleDeg: number;
+    /** Same as `startAngleDeg`, in radians (12 o'clock = 0). */
+    startAngleRad: number;
+    /** Offset angle in radians measured from +X (3 o'clock, the
+     *  trigonometric convention). Useful for direct `Math.cos` /
+     *  `Math.sin` calls when projecting points onto the arc. */
+    offsetRad: number;
+}
+/**
+ * Convert a sweep angle (degrees) into the four angle forms a
+ * radial chart layout typically needs. Defaults to a 240° sweep
+ * (gauge-style: gap of 120° centered at the bottom).
+ *
+ * @example
+ * ```ts
+ * const { sweepRad, startAngleRad } = sweepToAngles(180) // half-circle
+ * ```
+ */
+export declare function sweepToAngles(sweepDegrees?: number): SweepAngles;
+/**
+ * Map a numeric value in `[min, max]` to its angle along the arc.
+ * Returned angles are in trig-convention radians (suitable for
+ * `Math.cos` / `Math.sin` to project to unit-circle x/y).
+ *
+ * Values outside `[min, max]` are clamped.
+ *
+ * @example
+ * ```ts
+ * const { offsetRad, sweepRad } = sweepToAngles(240)
+ * const θ = valueToAngle(75, 0, 100, sweepRad, offsetRad)
+ * // x = Math.cos(θ), y = Math.sin(θ)
+ * ```
+ */
+export declare function valueToAngle(value: number, min: number, max: number, sweepRad: number, offsetRad: number): number;
+/** Bounding box of the visible arc in unit-circle coordinates
+ *  (radius = 1 around the origin). Multiply by the chosen radius
+ *  to get pixel-space extents. */
+export interface ArcBoundingBox {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    /** `maxX - minX`. Multiply by radius for pixel width. */
+    width: number;
+    /** `maxY - minY`. Multiply by radius for pixel height. */
+    height: number;
+    /** Center of the bbox in unit-circle coords. */
+    cx: number;
+    cy: number;
+}
+/**
+ * Compute the bounding box of an arc with the given sweep, in
+ * unit-circle coordinates. Useful for centering the arc within a
+ * container and picking a maximum radius that keeps the arc inside
+ * the available width/height.
+ *
+ * The bbox includes:
+ *   - The two arc endpoints.
+ *   - The arc's center point `(0, 0)`.
+ *   - Any of the cardinal points `(±1, 0)`, `(0, ±1)` that fall
+ *     within the swept range.
+ *
+ * @example
+ * ```ts
+ * const bbox = computeArcBoundingBox(240)
+ * // Maximize radius so the arc fits in a (W × H) container:
+ * const radius = Math.min((W - 2 * pad) / bbox.width, (H - 2 * pad) / bbox.height)
+ * ```
+ */
+export declare function computeArcBoundingBox(sweepDegrees?: number): ArcBoundingBox;