semiotic 3.7.3 → 3.7.5

package/dist/components/ai/dataPitfallsBridge.d.ts

@@ -0,0 +1,101 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type AccessibilityAuditResult, type AuditAccessibilityOptions } from "../charts/shared/auditAccessibility";
+import { type DiagnosisResult } from "../charts/shared/diagnoseConfig";
+import { type ChartConfig, type ToConfigOptions } from "../export/chartConfig";
+import { type ChartReaderGrounding, type ChartReaderGroundingOptions } from "./readerGrounding";
+export type DataPitfallsImageMediaType = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+export interface DataPitfallsImageSource {
+    content: string;
+    mediaType: DataPitfallsImageMediaType;
+    filename?: string;
+}
+export interface DataPitfallsTextInput {
+    kind: "code" | "text";
+    content: string;
+    language?: string;
+    filename?: string;
+}
+export interface DataPitfallsImageInput {
+    kind: "image";
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsDocumentInput {
+    kind: "document";
+    content: string;
+    mediaType: "application/pdf";
+    filename?: string;
+}
+export interface DataPitfallsSlideContent {
+    text: string;
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsSlidesInput {
+    kind: "slides";
+    slides: DataPitfallsSlideContent[];
+    filename?: string;
+}
+export type DataPitfallsSingleArtifactInput = DataPitfallsTextInput | DataPitfallsImageInput | DataPitfallsDocumentInput | DataPitfallsSlidesInput;
+export interface DataPitfallsChainStage {
+    role: string;
+    artifact: DataPitfallsSingleArtifactInput;
+}
+export interface DataPitfallsChainInput {
+    kind: "chain";
+    stages: DataPitfallsChainStage[];
+}
+export interface DataPitfallsRenderedChart {
+    /** SVG markup from `semiotic/server` renderChart/renderChartWithEvidence or MCP renderChart. */
+    svg?: string;
+    /** Render evidence from `renderChartWithEvidence` or MCP renderChart. */
+    evidence?: unknown;
+    /** Optional rendered chart image for Data Pitfalls' Vision path. */
+    image?: DataPitfallsImageSource | DataPitfallsImageSource[];
+}
+export interface DataPitfallsBridgeOptions {
+    /** Default true. Include the serializable Semiotic chart config as JSON. */
+    includeConfig?: boolean;
+    /** Default true. Include JSX reconstructed from the serializable chart config. */
+    includeJSX?: boolean;
+    /** Default true. Include describeChart/buildReaderGrounding text and structure. */
+    includeGrounding?: boolean;
+    /** Default true. Include diagnoseConfig output. */
+    includeDiagnostics?: boolean;
+    /** Default true. Include auditAccessibility output. */
+    includeAccessibility?: boolean;
+    /** Optional author or app context, such as the analytical question or intended claim. */
+    context?: string;
+    /** Optional narrative/caption/claim that will be reviewed alongside the chart. */
+    narrative?: string;
+    /** Optional output from a render path. */
+    rendered?: DataPitfallsRenderedChart;
+    /** Forwarded to toConfig. Use includeData: false to omit raw rows from config/JSX stages; other stages may still summarize data. */
+    config?: ToConfigOptions;
+    /** Forwarded to buildReaderGrounding. */
+    grounding?: ChartReaderGroundingOptions;
+    /** Forwarded to auditAccessibility. */
+    accessibility?: AuditAccessibilityOptions;
+    /** Prefix used for generated filenames. Default: component name. */
+    filenamePrefix?: string;
+    /** Extra caller-supplied chain stages, appended last. */
+    additionalStages?: DataPitfallsChainStage[];
+}
+export interface DataPitfallsBridgeResult {
+    input: DataPitfallsChainInput;
+    config: ChartConfig;
+    grounding?: ChartReaderGrounding;
+    diagnosis?: DiagnosisResult;
+    accessibility?: AccessibilityAuditResult;
+}
+/**
+ * Build a Data Pitfalls-compatible chain input from a Semiotic chart config.
+ *
+ * The returned `input` is intentionally dependency-free: pass it to
+ * `detectPitfalls(input, options)` from the `datapitfalls` package in your app,
+ * CI job, or research harness. Semiotic contributes the chart config,
+ * reader-grounding payload, config diagnostics, accessibility audit, and
+ * optional rendered output; Data Pitfalls remains responsible for model-backed
+ * pitfall detection.
+ */
+export declare function buildDataPitfallsBridge(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsBridgeResult;
+/** Convenience wrapper when you only need the Data Pitfalls input object. */
+export declare function toDataPitfallsChain(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsChainInput;

package/dist/components/ai/dataQualityBridge.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Data-quality → provenanced-annotation bridge.
+ *
+ * Ingests data-quality results — dbt source-freshness + test artifacts, Great
+ * Expectations validation results, or a normalized form anyone can hand-build —
+ * and maps them to **provenanced, lifecycled chart annotations**. A failed dbt
+ * freshness check becomes a danger threshold on the chart that says *who* found
+ * it (a system rule), *how* (a freshness rule), *when*, and against *which data
+ * snapshot* — so the chart's communicative act flips from report to alert,
+ * driven entirely by external metadata.
+ *
+ * Doctrine this module honors:
+ * - Pure, no React, no new dependencies — it shapes plain JSON into the
+ *   `Annotated[]` surface that already ships (`withProvenance` + the lifecycle
+ *   helpers do the rest).
+ * - **Read-only overlay.** It consumes a data-quality system's output and never
+ *   writes back into it. Clicking the chart does not trigger a dbt run.
+ * - **Refuse rather than mistranslate.** A check with no faithful chart
+ *   coordinate (a `not_null` test, a uniqueness expectation) is NOT given a
+ *   fabricated position — it is returned in `unplaced[]` with a reason, so the
+ *   30% an adapter can't place is announced rather than hidden.
+ *
+ * The data-quality system owns query execution, governance, and the test
+ * definitions; this bridge owns only the visual overlay and its provenance.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { AnnotationAnchor, AnnotationBasis, AnnotationStatus, Annotated } from "./annotationProvenance";
+export type DataQualityStatus = "pass" | "fail" | "warn" | "error";
+/**
+ * How a check relates to a chart. Only the kinds with a clear visual analog
+ * produce an annotation; the rest are reported as `unplaced`.
+ */
+export type DataQualityCheckKind = "range" | "min" | "max" | "threshold" | "freshness" | "not-null" | "unique" | "accepted-values" | "row-condition" | "custom";
+/**
+ * A single data-quality result, normalized across source systems. The dbt and
+ * Great-Expectations parsers produce these; consumers can also hand-build them
+ * (e.g. to bridge Monte Carlo or a bespoke checker).
+ */
+export interface DataQualityResult {
+    /** Stable id of the check (test/expectation id). Becomes provenance.stableId. */
+    id: string;
+    /** Human-readable check name; falls back to id. Doubles as the provenance author. */
+    name?: string;
+    /** Concise phrase drawn on the chart. Falls back to `name`. Keep it short. */
+    label?: string;
+    status: DataQualityStatus;
+    kind: DataQualityCheckKind;
+    /** Column/field the check applies to (mapped through `fieldMap`). */
+    column?: string;
+    /** Lower bound (range/min). */
+    min?: number;
+    /** Upper bound (range/max). */
+    max?: number;
+    /** Single reference value (threshold/min/max). */
+    value?: number;
+    /** Freshness deadline or observed event time (ISO string or epoch ms). */
+    at?: string | number;
+    /** Free-form detail surfaced in the label. */
+    message?: string;
+    /** Source system. */
+    source?: "dbt" | "great-expectations" | (string & {});
+    /** Evidence type. Defaults to "rule" (deterministic constraint). */
+    basis?: AnnotationBasis;
+    /** 0–1; surfaced in the label only when < 1 (a hard rule needs no percent). */
+    confidence?: number;
+    /** ISO timestamp the check ran. */
+    createdAt?: string;
+    /** Data snapshot id (dbt invocation_id, GE run id). */
+    dataVersion?: string;
+    /** Failing-row count etc., surfaced in the label. */
+    observedCount?: number;
+}
+export interface DataQualityAnnotationOptions {
+    /** Map normalized column names → chart accessor field names. */
+    fieldMap?: Record<string, string>;
+    /** Which axis numeric thresholds map onto. Default "y". (Ranges always band on y.) */
+    valueAxis?: "x" | "y";
+    /** TTL applied to every generated annotation's lifecycle — drives freshness decay. */
+    ttlHint?: string | number;
+    /** Surface passing checks too (default false — only failures/warnings overlay). */
+    includePassed?: boolean;
+    /** Editorial status stamped on generated notes. Default "proposed". */
+    status?: AnnotationStatus;
+    /** Anchor mode. Default "semantic" so notes re-resolve through stableId on refresh. */
+    anchor?: AnnotationAnchor;
+    /** Color for failing/erroring checks. Default CSS var --semiotic-danger. */
+    failColor?: string;
+    /** Color for warnings. Default CSS var --semiotic-warning. */
+    warnColor?: string;
+    /** Color for passing checks (only used when includePassed). Default --semiotic-success. */
+    passColor?: string;
+}
+/** A result the bridge declined to place, with the reason (the D7 honesty surface). */
+export interface UnplacedDataQualityResult {
+    result: DataQualityResult;
+    reason: string;
+}
+export interface DataQualityAnnotationsResult {
+    /** Annotations ready to pass to a chart's `annotations` prop. */
+    annotations: Annotated<Datum>[];
+    /** Results with no faithful chart coordinate, each with a reason. */
+    unplaced: UnplacedDataQualityResult[];
+}
+/**
+ * Map normalized data-quality results to provenanced annotations. The pure core
+ * both the dbt and Great-Expectations parsers funnel through; call it directly
+ * to bridge any other checker.
+ */
+export declare function dataQualityToAnnotations(results: ReadonlyArray<DataQualityResult>, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+/** Subset of a dbt artifact's `metadata` block we read. */
+interface DbtMetadata {
+    generated_at?: string;
+    invocation_id?: string;
+}
+/** A `sources.json` (source-freshness) result entry. */
+interface DbtFreshnessResult {
+    unique_id?: string;
+    status?: string;
+    max_loaded_at?: string;
+    snapshotted_at?: string;
+    criteria?: {
+        warn_after?: {
+            count?: number;
+            period?: string;
+        };
+        error_after?: {
+            count?: number;
+            period?: string;
+        };
+    };
+}
+/** A `run_results.json` result entry (we read the test-relevant fields). */
+interface DbtRunResult {
+    unique_id?: string;
+    status?: string;
+    failures?: number | null;
+    message?: string | null;
+}
+export interface DbtArtifacts {
+    /** Parsed `sources.json` (dbt source freshness). */
+    sources?: {
+        metadata?: DbtMetadata;
+        results?: ReadonlyArray<DbtFreshnessResult>;
+    };
+    /** Parsed `run_results.json`. */
+    runResults?: {
+        metadata?: DbtMetadata;
+        results?: ReadonlyArray<DbtRunResult>;
+    };
+}
+/**
+ * Map dbt artifacts to provenanced annotations. The strongest mapping is source
+ * freshness (`sources.json`) — a real timestamp + status becomes a time
+ * threshold. Test results (`run_results.json`) carry pass/fail but not, without
+ * `manifest.json`, the column/range semantics needed to place them; those land
+ * in `unplaced[]` with a reason (D7).
+ */
+export declare function fromDbtArtifacts(artifacts: DbtArtifacts, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+interface GEExpectationConfig {
+    expectation_type?: string;
+    kwargs?: {
+        column?: string;
+        min_value?: number | null;
+        max_value?: number | null;
+        value?: number | null;
+        [key: string]: unknown;
+    };
+}
+interface GEResultEntry {
+    success?: boolean;
+    expectation_config?: GEExpectationConfig;
+    result?: {
+        observed_value?: number | string;
+        element_count?: number;
+        unexpected_count?: number;
+    };
+}
+export interface GEValidationResult {
+    success?: boolean;
+    results?: ReadonlyArray<GEResultEntry>;
+    meta?: {
+        run_id?: {
+            run_name?: string;
+            run_time?: string;
+        } | string;
+        [key: string]: unknown;
+    };
+    statistics?: {
+        evaluated_expectations?: number;
+        successful_expectations?: number;
+    };
+}
+/**
+ * Map a Great Expectations validation result to provenanced annotations.
+ * Range expectations (`expect_*_to_be_between`) become bands; single-bound
+ * expectations become thresholds. Set/uniqueness/null expectations have no
+ * single chart coordinate and are returned in `unplaced[]`. GE expectations are
+ * statistical assertions, so `basis` defaults to "statistical-test".
+ */
+export declare function fromGreatExpectations(validation: GEValidationResult, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+export {};

package/dist/components/ai/describeChart.d.ts

@@ -99,6 +99,8 @@ export declare function communicativeActForIntent(intent: IntentId): Communicati
  * family classification. Returns undefined only when nothing identifies it.
  */
 export declare function resolveCommunicativeAct(component: string, context: ChartCapability | DescribeCapabilityContext | undefined): CommunicativeAct | undefined;
+/** True when props carry a provenanced, system/agent-generated alert annotation. */
+export declare function hasGeneratedAlertAnnotation(props: Datum): boolean;
 /** Build a number formatter — compact (6.5M) for large magnitudes, plain
  *  otherwise. Exported so the navigation tree formats values identically. */
 export declare function chartValueFormatter(locale?: string): (n: number) => string;

package/dist/components/ai/generativeChart.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Generative-UI trust layer.
+ *
+ * "Generation is cheap; trust is scarce." An LLM can emit chart code in a
+ * sentence — but hand-written JSX breaks on first paint, and a plausible-looking
+ * chart for the wrong data misleads exactly the reader who can't tell. This
+ * module is the trust layer an AI framework wraps around chart generation: it
+ * turns an LLM's *proposal* (a component name + props) into a result that is
+ * either guaranteed-renderable or accompanied by structured reasons and ranked
+ * alternatives to retry with — never a broken chart.
+ *
+ * It composes the already-shipped surface into the documented loop —
+ * **generate → validate → diagnose → repair → render+prove** — and rides
+ * `ChartConfig`, the gate-defended public artifact. It is framework-agnostic by
+ * construction: no Vercel/LangChain/OpenAI/Anthropic SDK enters the library
+ * (the tool-definition shapers below are pure object transforms over JSON
+ * Schema). The one heavy step — rendering to SVG with render evidence — is
+ * *dependency-injected* (`RenderFn`), so this module stays free of server deps
+ * and usable in a browser, an edge runtime, or a notebook.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartConfig } from "../export/chartConfig";
+import type { ValidationResult } from "../charts/shared/validateProps";
+import type { Diagnosis } from "../charts/shared/diagnoseConfig";
+import type { RepairResult } from "./repairChartConfig";
+import type { IntentId } from "./intents";
+import type { RenderEvidence } from "../server/renderEvidence";
+/**
+ * A renderer that turns a validated config into SVG + render evidence. Inject
+ * `renderChartWithEvidence` from `semiotic/server` in Node/SSR; omit it in the
+ * browser (the helper still validates, diagnoses, repairs, and emits JSX).
+ */
+export type RenderFn = (component: string, props: Datum) => {
+    svg: string;
+    evidence: RenderEvidence;
+};
+export interface PrepareChartInput {
+    /** Chart component name the model proposed (e.g. "LineChart"). */
+    component: string;
+    /** Props the model proposed. */
+    props?: Datum;
+}
+export interface PrepareChartOptions {
+    /**
+     * The dataset, used to route a repair when the proposed chart is unknown or a
+     * poor fit. When present, `repair` runs by default.
+     */
+    data?: ReadonlyArray<Datum>;
+    /** Ranking intent passed to repair's alternative search. */
+    intent?: IntentId | IntentId[];
+    /** Run `diagnoseConfig` anti-pattern checks (default true). */
+    diagnose?: boolean;
+    /**
+     * Run repair routing (fit check + ranked alternatives). Default: true when
+     * `data` is provided, false otherwise (repair needs the data to profile).
+     */
+    repair?: boolean;
+    /**
+     * Inject a renderer to prove the config paints (and to read render evidence —
+     * the first-try oracle). When omitted, the result has no `svg`/`evidence`,
+     * and `ok` is decided on validation + diagnostics alone.
+     */
+    render?: RenderFn;
+    /**
+     * Treat error-severity diagnostics as blocking `ok` (default true). Set false
+     * to let a caller surface warnings without failing the gate.
+     */
+    treatErrorsAsBlocking?: boolean;
+}
+export interface PrepareChartResult {
+    /**
+     * True only when the proposal is trustworthy: it validates, carries no
+     * error-severity diagnostics, and — if a renderer was injected — produced a
+     * non-empty scene. A `false` result is the signal to retry with `reasons` and
+     * `repair.alternatives`, never to paint.
+     */
+    ok: boolean;
+    component: string;
+    props: Datum;
+    /** The serializable, validated config — present whenever the component is known. */
+    config?: ChartConfig;
+    /** JSX string for the validated config (only when a config could be built). */
+    jsx?: string;
+    /** Structural validation: required props, types, enums, accessor/data shape. */
+    validation: ValidationResult;
+    /** Anti-pattern diagnostics (empty data, misleading design, contrast, …). */
+    diagnostics: Diagnosis[];
+    /** Fit verdict + ranked alternatives, when repair ran. */
+    repair?: RepairResult;
+    /** Render evidence (mark count, domains, ariaLabel, …) when a renderer ran. */
+    evidence?: RenderEvidence;
+    /** Rendered SVG when a renderer ran. */
+    svg?: string;
+    /** Human-readable reasons the proposal is not `ok` (empty when `ok`). */
+    reasons: string[];
+}
+/**
+ * Run an LLM chart proposal through the trust loop. Pure except for any side
+ * effects of an injected `render` function.
+ */
+export declare function prepareChart(input: PrepareChartInput, options?: PrepareChartOptions): PrepareChartResult;
+/**
+ * A tool definition expressed as JSON Schema — the common denominator every
+ * agent framework accepts. Mirrors the MCP `renderChart` contract so an
+ * in-process tool and the MCP server speak the same shape.
+ */
+export interface ChartToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool input. */
+    inputSchema: Record<string, unknown>;
+}
+export interface ChartToolOptions {
+    /** Override the tool name (default "render_semiotic_chart"). */
+    name?: string;
+    /** Restrict the component enum to this allow-list (default: the whole registry). */
+    components?: ReadonlyArray<string>;
+}
+/**
+ * Build a framework-agnostic tool definition for generating a Semiotic chart.
+ * Pass it (or a shaper's output) to your agent framework, and pair it with
+ * {@link createChartToolHandler} for the execute step.
+ */
+export declare function chartGenerationTool(options?: ChartToolOptions): ChartToolDefinition;
+/** Shape a tool definition for the Anthropic Messages API `tools` array. */
+export declare function toAnthropicTool(def: ChartToolDefinition): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+};
+/** Shape a tool definition for the OpenAI / function-calling `tools` array. */
+export declare function toOpenAITool(def: ChartToolDefinition): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+};
+/**
+ * Build the execute handler for the chart tool: it runs {@link prepareChart} on
+ * the tool input and returns the trust-loop result. Inject a `render` fn (from
+ * `semiotic/server`) and/or the `data` for fit checking via `optionsFor`.
+ */
+export declare function createChartToolHandler(optionsFor?: (input: PrepareChartInput) => PrepareChartOptions): (input: PrepareChartInput) => PrepareChartResult;

package/dist/components/charts/custom/NetworkCustomChart.d.ts

@@ -22,14 +22,27 @@ export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge exte
     /** Color scheme threaded into the layout's `resolveColor` helper. */
     colorScheme?: string | string[];
     enableHover?: boolean;
+    /**
+     * Annotations rendered over the chart. A custom network layout's marks are
+     * anchorable by id: emit a scene node with `id: <foo>` and an annotation with
+     * `pointId: "<foo>"` resolves to that mark's center (the editorial-callout
+     * story, now unified with the built-in network charts). Data-coordinate
+     * anchoring doesn't apply — custom layouts own their own geometry — so anchor
+     * by `pointId`, or draw bespoke callouts with the recipe chrome kit's
+     * `markCallout`.
+     */
+    annotations?: StreamNetworkFrameProps["annotations"];
+    /** Collision-avoiding auto-placement for the annotations above. */
+    autoPlaceAnnotations?: StreamNetworkFrameProps["autoPlaceAnnotations"];
     /**
      * Custom layouts own their own color resolution (the layout function
      * decides what each node looks like), so the auto-legend infrastructure
      * the built-in network HOCs use can't run. To render a legend, build a
-     * `legendGroups` array yourself and pass it through `frameProps.legend`.
+     * `legendGroups` array yourself (see `legendGroupsFrom`) and pass it through
+     * `frameProps.legend`.
      */
     /** Additional StreamNetworkFrame props for advanced customization. */
-    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig">>;
+    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig" | "layoutSelection">>;
 }
 /**
  * NetworkCustomChart — escape hatch for bespoke network geometry.

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

@@ -1,6 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { SymbolName } from "../../stream/symbolPath";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -17,6 +18,12 @@ export interface SwarmPlotProps<TDatum extends Datum = Datum> extends BaseChartP
     colorScheme?: string | string[];
     sizeBy?: ChartAccessor<TDatum, number>;
     sizeRange?: [number, number];
+    /** Field name or function → glyph **shape**: each point renders as a d3-shape
+     *  glyph instead of a circle. Pair with `symbolMap` for stable, legend-matchable
+     *  shapes; unmapped categories auto-assign. Size still tracks `sizeBy`/`pointRadius`. */
+    symbolBy?: ChartAccessor<TDatum, string>;
+    /** Explicit `{category → shape}` map for `symbolBy`; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     pointRadius?: number;
     pointOpacity?: number;
     categoryPadding?: number;

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

@@ -7,6 +7,8 @@ import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types"
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import { type AggregateConfig } from "./aggregate";
+import { type EventTimeConfig } from "./eventTime";
 export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -106,6 +108,25 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     legendInteraction?: LegendInteractionMode;
     /** ID accessor for remove()/update() on the push API */
     pointIdAccessor?: string | ((d: Datum) => string);
+    /**
+     * Opt-in windowed aggregation over event-time. When set, pushed
+     * events are reduced into tumbling/hopping/session windows and the
+     * chart draws one mark per window (mean/sum/min/max/count) plus an
+     * optional ±σ or min–max band — render cost scales with the number of
+     * visible windows, not the arrival rate. This is the **aggregation
+     * window**, distinct from `windowMode`'s RingBuffer eviction.
+     */
+    aggregate?: AggregateConfig;
+    /**
+     * Opt-in event-time ingestion. Buffers pushed events for a bounded
+     * lateness/grace window and releases them to the chart in event-time
+     * order, so out-of-order or merged multi-source streams render
+     * monotonically instead of zigzagging. Late events (older than
+     * `watermark − lateness`) are dropped or kept per policy and surfaced
+     * via `onObservation` as `"late-data"`. Default-off; when unset the
+     * push path is byte-for-byte unchanged.
+     */
+    eventTime?: EventTimeConfig;
 }
 /**
  * RealtimeLineChart - Simplified wrapper for streaming line charts.

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

@@ -0,0 +1,51 @@
+import { WindowAccumulator, type WindowType, type AggregateStat, type AggregateBand } from "../../realtime/WindowAccumulator";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Opt-in windowed-aggregation transform for realtime XY charts. With it
+ * set, pushed events are reduced into event-time windows and the chart
+ * draws one mark per window (mean / sum / min / max / count) plus an
+ * optional ±σ or min–max envelope — bounded render cost regardless of
+ * arrival rate.
+ */
+export interface AggregateConfig {
+    /** Window kind. @default "tumbling" */
+    window?: WindowType;
+    /** Window width — ms or a duration string (`"1m"`, `"10s"`, `"500ms"`). */
+    size: number | string;
+    /** Hop between hopping windows — ms or duration string. @default = size */
+    hop?: number | string;
+    /** Session inactivity gap — ms or duration string (session windows only). */
+    gap?: number | string;
+    /** Statistic rendered as the primary series. @default "mean" */
+    stat?: AggregateStat;
+    /** Envelope drawn around the series. @default "none" */
+    band?: AggregateBand;
+    /** Multiplier for the `stddev` band (drawn as value ± sigma·σ). @default 1 */
+    sigma?: number;
+    /** Keep at most this many most-recent windows. @default unbounded */
+    retain?: number;
+}
+export declare const AGG_TIME = "time";
+export declare const AGG_VALUE = "value";
+export declare const AGG_LOWER = "__aggLower";
+export declare const AGG_UPPER = "__aggUpper";
+export declare const AGG_PARTIAL = "__aggPartial";
+export declare const AGG_COUNT = "count";
+export declare const AGG_START = "__aggStart";
+export declare const AGG_END = "__aggEnd";
+/**
+ * Build a `WindowAccumulator` from a config, parsing duration strings.
+ * Returns `null` when the window width is unparseable, so the caller can
+ * skip aggregation rather than bucket on a zero-width window.
+ */
+export declare function createAccumulator(config: AggregateConfig): WindowAccumulator | null;
+/**
+ * Snapshot the accumulator into frame-ready rows. Each row carries the
+ * primary stat at `value`, the window midpoint at `time`, the band
+ * bounds (when a band is configured), and provenance fields (`count`,
+ * partial flag, raw start/end) for tooltips and partial-window styling.
+ */
+export declare function aggregatedRows(acc: WindowAccumulator, config: AggregateConfig): Datum[];
+/** Whether a config requests a band envelope. */
+export declare function hasBand(config: AggregateConfig): boolean;
+export type { AggregateStat, AggregateBand, WindowType };

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

@@ -0,0 +1,26 @@
+import { ReorderBuffer, type LatePolicy } from "../../realtime/ReorderBuffer";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Opt-in event-time ingestion for realtime XY charts. Reorders pushed
+ * events within a bounded grace window so out-of-order arrivals render
+ * in event-time order, at the cost of delaying display by `lateness`.
+ */
+export interface EventTimeConfig {
+    /**
+     * Grace window — ms or a duration string (`"2s"`, `"500ms"`). Events
+     * whose time is older than `watermark − lateness` are late.
+     */
+    lateness: number | string;
+    /**
+     * What to do with a late event:
+     * - `"drop"` (default): discard it (still counted + surfaced).
+     * - `"keep"`: release it immediately, out of order (still counted).
+     */
+    latePolicy?: LatePolicy;
+}
+/**
+ * Build a `ReorderBuffer` from a config and a time accessor, parsing the
+ * lateness duration. Returns `null` when the lateness is unparseable so
+ * the caller can fall back to plain (in-order) ingestion.
+ */
+export declare function createReorderBuffer(config: EventTimeConfig, getTime: (d: Datum) => number): ReorderBuffer<Datum> | null;

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

@@ -53,6 +53,8 @@ export declare const interpolateInferno: (t: number) => string;
 export declare const interpolateMagma: (t: number) => string;
 export declare const interpolateCividis: (t: number) => string;
 export declare const interpolateTurbo: (t: number) => string;
+export declare const SEQUENTIAL_INTERPOLATORS: Record<string, (t: number) => string>;
+export declare function getSequentialInterpolator(scheme: string | undefined): (t: number) => string;
 export declare const interpolateRdBu: (t: number) => string;
 export declare const interpolatePiYG: (t: number) => string;
 export declare const interpolatePRGn: (t: number) => string;

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

@@ -2,18 +2,7 @@ import type { Datum } from "./datumTypes";
 /**
  * Predefined color schemes
  */
-export declare const COLOR_SCHEMES: {
-    category10: readonly string[];
-    tableau10: readonly string[];
-    set3: readonly string[];
-    blues: (t: number) => string;
-    reds: (t: number) => string;
-    greens: (t: number) => string;
-    oranges: (t: number) => string;
-    purples: (t: number) => string;
-    viridis: (t: number) => string;
-    plasma: (t: number) => string;
-};
+export declare const COLOR_SCHEMES: Record<string, readonly string[] | ((t: number) => string)>;
 /**
  * Default colors for charts
  */

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

@@ -0,0 +1,3 @@
+export declare function getMinMax(values: ReadonlyArray<number>): [number, number];
+export declare function getMin(values: ReadonlyArray<number>, fallback?: number): number;
+export declare function getMax(values: ReadonlyArray<number>, fallback?: number): number;