semiotic 3.7.4 → 3.7.5

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

@@ -63,7 +63,7 @@ export interface ChartSetupInput {
     /** Custom content rendered in place of the default skeleton while `loading` is true. */
     loadingContent?: ReactNode | false;
     /** Empty content override */
-    emptyContent?: ReactNode;
+    emptyContent?: ReactNode | false;
     /** Resolved width from useChartMode */
     width: number;
     /** Resolved height from useChartMode */

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

@@ -65,7 +65,7 @@ interface DataSetupOptions extends ScaffoldOptions {
     chartId?: string;
     loading?: boolean;
     loadingContent?: ReactNode | false;
-    emptyContent?: ReactNode;
+    emptyContent?: ReactNode | false;
 }
 interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {
     /** Sparse-filtered copy of the input data array. */

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

@@ -12,7 +12,7 @@ import type { Datum } from "./datumTypes";
 type AccessorLike = string | ((...args: any[]) => any);
 interface ArrayDataValidation {
     componentName: string;
-    data: any[] | undefined | null;
+    data: any;
     accessors?: Record<string, AccessorLike | undefined>;
     requiredProps?: Datum;
 }

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

@@ -1,6 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
+import type { SymbolName } from "../../stream/symbolPath";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -29,6 +30,14 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max radius for points @default [3, 15] */
     sizeRange?: [number, number];
+    /** Field name or function → glyph **shape**: each mark renders as a d3-shape
+     *  glyph instead of a circle (the per-datum shape channel). Pair with a
+     *  `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` (e.g. `{ Civil: "star" }`);
+     *  unmapped categories auto-assign from the shape sequence. */
+    symbolMap?: Record<string, SymbolName>;
     /** Default point radius when sizeBy is not specified @default 5 */
     pointRadius?: number;
     /** Point opacity @default 0.8 */

package/dist/components/data/fromArrow.d.ts

@@ -0,0 +1,54 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Apache Arrow → Semiotic rows (v1).
+ *
+ * Reads an Arrow table (DuckDB-Wasm result set, Arrow IPC, Parquet-via-Arrow)
+ * into the plain row objects the chart accessor path expects, so an in-browser
+ * analytics engine can feed Semiotic with one call.
+ *
+ * **Honest scope (v1).** Semiotic's data path is row-oriented and validates the
+ * `data` prop with `Array.isArray`, so a chart's `data` must be a real array of
+ * row objects. This adapter therefore materializes rows — but leanly: it reads
+ * each requested column cell-by-cell into a plain object, avoiding Arrow's own
+ * `Table.toArray()` row-proxy machinery, and it supports column projection so
+ * you only pay for the fields you chart. The genuinely zero-copy columnar path
+ * (a typed-array accessor mode + bulk ring-buffer ingest) is deliberately
+ * *not* built here: it touches the ingestion core and waits on a named consumer
+ * plus profiling evidence, rather than being built on spec.
+ *
+ * Pure, dependency-free: the Arrow table is duck-typed, so `apache-arrow` never
+ * enters Semiotic's dependencies — you bring the table, this reads it.
+ */
+/** A column vector, duck-typed to apache-arrow's `Vector`. */
+export interface ArrowColumnLike {
+    get(index: number): unknown;
+}
+/** A schema field, duck-typed to apache-arrow's `Field`. */
+export interface ArrowFieldLike {
+    name: string;
+}
+/** A table schema, duck-typed to apache-arrow's `Schema`. */
+export interface ArrowSchemaLike {
+    fields: ReadonlyArray<ArrowFieldLike>;
+}
+/** An Arrow table, duck-typed to apache-arrow's `Table` (and DuckDB-Wasm results). */
+export interface ArrowTableLike {
+    numRows: number;
+    schema: ArrowSchemaLike;
+    getChild(name: string): ArrowColumnLike | null | undefined;
+}
+export interface FromArrowOptions {
+    /** Project a subset of columns. Omit to read every column in the schema. */
+    fields?: ReadonlyArray<string>;
+    /**
+     * Convert Arrow int64/uint64 values (returned as `bigint`) to `number`, since
+     * the chart scales and `toNumber` coercion work in `number`. Default true.
+     * Values outside `Number.MAX_SAFE_INTEGER` are left as `bigint` (and warned).
+     */
+    coerceBigInt?: boolean;
+}
+/**
+ * Materialize an Arrow table into Semiotic row objects. Pass the result
+ * straight to a chart's `data` prop: `<LineChart data={fromArrow(table)} … />`.
+ */
+export declare function fromArrow(table: ArrowTableLike, options?: FromArrowOptions): Datum[];

package/dist/components/data/fromMermaid.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Mermaid → Semiotic graph (alpha).
+ *
+ * Mermaid is the dominant text-to-graph language across GitHub, Notion, and LLM
+ * output — but it renders as flat, hard-to-style, non-interactive, *inaccessible*
+ * SVG. This adapter parses Mermaid `graph`/`flowchart` syntax into a topology
+ * Semiotic can render with hover, isolation, theme tokens, keyboard navigation,
+ * and an accessible navigation tree.
+ *
+ * The gofish lesson applies hard (D7): **reconstruct the diagram's semantics,
+ * not its pixels.** A Mermaid flowchart is a DAG, not a force graph, so this
+ * adapter doesn't just emit nodes/edges — it computes a layered layout
+ * (longest-path layering) and stamps each node with `layer`/`row` coordinates,
+ * ready for the `lineageDagLayout` recipe via `NetworkCustomChart`. The raw
+ * topology is also returned, so a consumer who wants a force layout
+ * (`ForceDirectedGraph`) can use it directly.
+ *
+ * Scope (alpha): `graph`/`flowchart` with TD/TB/BT/LR/RL direction, node shapes,
+ * and labeled edges. Other Mermaid diagram types (sequence, class, state, er,
+ * gantt, pie, mindmap, …) are declined with a reason rather than mistranslated.
+ *
+ * Pure, dependency-free: a small dedicated parser, never a Mermaid runtime dep.
+ */
+export type MermaidDirection = "TD" | "TB" | "BT" | "LR" | "RL";
+export type MermaidNodeShape = "rect" | "round" | "stadium" | "subroutine" | "cylinder" | "circle" | "diamond" | "hexagon" | "flag";
+export interface MermaidNode {
+    id: string;
+    label: string;
+    shape: MermaidNodeShape;
+    /** Longest-path layer (0 = a source with no incoming edges). */
+    layer: number;
+    /** Order within the layer (insertion order). */
+    row: number;
+}
+export interface MermaidEdge {
+    source: string;
+    target: string;
+    label?: string;
+}
+export interface MermaidResult {
+    kind: "flowchart";
+    direction: MermaidDirection;
+    nodes: MermaidNode[];
+    edges: MermaidEdge[];
+    warnings?: string[];
+}
+export declare function fromMermaid(text: string): MermaidResult;

package/dist/components/data/fromObservablePlot.d.ts

@@ -0,0 +1,69 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Observable Plot → Semiotic translator.
+ *
+ * A sibling to `fromVegaLite`: maps a declarative Observable Plot spec to a
+ * Semiotic `ChartConfig`, so a chart sketched in a notebook crosses the
+ * notebook→production rewrite tax and arrives with everything a throwaway Plot
+ * chart never had — accessible tables, keyboard navigation, descriptions, the
+ * a11y audit, theme tokens, annotation provenance, and SSR.
+ *
+ * Honest hard part (the reason this stages behind `unstable_`): Plot's public
+ * API is *imperative JS* (`Plot.line(data, {…})`), not declarative JSON. This
+ * adapter consumes the **declarative shape of a Plot spec** — the `{ marks,
+ * x, y, color, … }` object you'd pass to `Plot.plot()`, with each mark
+ * expressed as `{ type, data?, options? }`. Where a mark, channel, or
+ * transform has no faithful Semiotic equivalent, it surfaces a warning and
+ * refuses to approximate, rather than emit a plausible-but-wrong chart.
+ *
+ * Scope (alpha): core marks — line/lineY/lineX, barY/barX, dot, areaY/area,
+ * rectY (binned → histogram), cell, tick — with basic channels. No layered
+ * multi-mark plots, facets, or Plot transforms (binX/groupY/stackY as option
+ * wrappers).
+ */
+import type { ChartConfig } from "../export/chartConfig";
+/** A channel value: a field name (string), a constant (number), or — declined — a function. */
+export type ObservablePlotChannel = string | number | ((d: Datum, i: number) => unknown);
+export interface ObservablePlotMarkOptions {
+    x?: ObservablePlotChannel;
+    y?: ObservablePlotChannel;
+    fill?: ObservablePlotChannel;
+    stroke?: ObservablePlotChannel;
+    r?: ObservablePlotChannel;
+    z?: ObservablePlotChannel;
+    curve?: string;
+    [key: string]: unknown;
+}
+export interface ObservablePlotMark {
+    /** The Plot mark function name, e.g. "line", "barY", "dot", "areaY", "cell". */
+    type: string;
+    data?: Datum[];
+    options?: ObservablePlotMarkOptions;
+}
+export interface ObservablePlotScale {
+    label?: string;
+    type?: string;
+    scheme?: string;
+    domain?: unknown;
+    range?: unknown;
+    [key: string]: unknown;
+}
+export interface ObservablePlotSpec {
+    marks?: ObservablePlotMark[];
+    /** Shared data, when marks don't each carry their own. */
+    data?: Datum[];
+    width?: number;
+    height?: number;
+    title?: string;
+    x?: ObservablePlotScale;
+    y?: ObservablePlotScale;
+    color?: ObservablePlotScale;
+    r?: ObservablePlotScale;
+    fx?: unknown;
+    fy?: unknown;
+    facet?: unknown;
+    [key: string]: unknown;
+}
+export declare function fromObservablePlot(spec: ObservablePlotSpec): ChartConfig & {
+    warnings?: string[];
+};

package/dist/components/data/portability/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * IDID portability spec — runtime surface (v0.1, experimental).
+ *
+ * Library-neutral types, dependency-free validators, an outbound Vega-Lite
+ * translator, and the IDID-over-Vega-Lite binding. The canonical published
+ * artifact is the JSON Schema set in `/spec/v0.1`.
+ *
+ * Exposed via `semiotic/experimental` behind the `unstable_` prefix while the
+ * surface is proven against real consumers.
+ */
+export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS, validatePortableCapability, validatePortableAudienceProfile, validatePortableAnnotation, } from "./spec";
+export type { BuiltInIntentId, PortableIntentId, PortableChartRubric, PortableChartVariant, PortableChartCapability, PortableReceptionModality, PortableAudienceTarget, PortableAudienceProfile, PortableAnnotationActorKind, PortableAnnotationSource, PortableAnnotationBasis, PortableAnnotationProvenance, PortableAnnotationFreshness, PortableAnnotationStatus, PortableAnnotationAnchor, PortableAnnotationLifecycle, PortableAnnotated, ValidationResult, } from "./spec";
+export { toVegaLite, attachIDID, readIDID, attachIDIDAnnotations, readIDIDAnnotations, } from "./vegaLite";
+export type { IDIDVegaLiteMeta } from "./vegaLite";

package/dist/components/data/portability/spec.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The IDID portability spec — runtime surface (v0.1).
+ *
+ * The canonical, published artifact is the set of JSON Schemas in `/spec/v0.1`.
+ * This module is the reference implementation's *runtime companion*: portable
+ * TypeScript types that mirror those schemas, plus small dependency-free
+ * structural validators for hosts that don't want to pull in a full JSON-schema
+ * engine (per spec doctrine: zero new core dependencies).
+ *
+ * The schemas are library-neutral — none of these types import from a chart
+ * family. Keeping them pure is what lets the ideas travel into ecosystems that
+ * have no concept of a Semiotic chart.
+ *
+ * Field/type fidelity with the published JSON Schemas is enforced by
+ * `portability.test.ts` (the round-trip gate), so the two cannot drift.
+ */
+/** The spec version this build targets. Matches the `/spec/v0.1` directory. */
+export declare const IDID_SPEC_VERSION = "0.1";
+/** The 13 built-in communicative intents. Hosts may register more (open string). */
+export declare const BUILTIN_INTENT_IDS: readonly ["trend", "compare-series", "compare-categories", "rank", "part-to-whole", "distribution", "correlation", "flow", "hierarchy", "geo", "outlier-detection", "composition-over-time", "change-detection"];
+export type BuiltInIntentId = (typeof BUILTIN_INTENT_IDS)[number];
+/** Any intent id — built-in or host-registered. */
+export type PortableIntentId = BuiltInIntentId | (string & {});
+export interface PortableChartRubric {
+    /** How well-known the chart is to a general audience (1–5). */
+    familiarity: number;
+    /** How faithfully it represents the underlying data (1–5). */
+    accuracy: number;
+    /** How readable individual values are (1–5). */
+    precision: number;
+}
+export interface PortableChartVariant {
+    key: string;
+    label: string;
+    description?: string;
+    intentDeltas?: Partial<Record<PortableIntentId, number>>;
+    rubricDeltas?: Partial<PortableChartRubric>;
+    caveats?: ReadonlyArray<string>;
+    tags?: ReadonlyArray<string>;
+    /** Implementation-specific props; opaque to the spec. */
+    props?: Record<string, unknown>;
+}
+export interface PortableChartCapability {
+    /** Stable chart name (e.g. "BarChart"). */
+    component: string;
+    /** Coarse family — open string ("xy" | "ordinal" | "network" | …). */
+    family?: string;
+    /** Where the implementing library exposes the chart (advisory). */
+    importPath?: string;
+    rubric: PortableChartRubric;
+    /** Per-intent suitability, 0–5. Missing intents default to 0. */
+    intentScores?: Partial<Record<PortableIntentId, number>>;
+    variants?: ReadonlyArray<PortableChartVariant>;
+    /** Static, audience-independent caveats. */
+    caveats?: ReadonlyArray<string>;
+    tags?: ReadonlyArray<string>;
+}
+export type PortableReceptionModality = "visual" | "screen-reader" | "sonified" | "agent";
+export interface PortableAudienceTarget {
+    direction: "increase" | "decrease";
+    /** 1–3; default 1. */
+    weight?: number;
+    reason?: string;
+}
+export interface PortableAudienceProfile {
+    name?: string;
+    /** Per-chart familiarity override, 1–5, keyed by component. */
+    familiarity?: Record<string, number>;
+    /** Adoption targets keyed by component. */
+    targets?: Record<string, PortableAudienceTarget>;
+    exposureLevel?: 0 | 1 | 2;
+    receptionModality?: PortableReceptionModality;
+}
+/** Open string — recognized: human | agent | watcher | system. */
+export type PortableAnnotationActorKind = "human" | "agent" | "watcher" | "system" | (string & {});
+/** Open string — recognized: user | ai | agent | import | computed | system. */
+export type PortableAnnotationSource = "user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {});
+/** Open string — recognized: human-note | statistical-test | rule | llm-inference | external-source | computed. */
+export type PortableAnnotationBasis = "human-note" | "statistical-test" | "rule" | "llm-inference" | "external-source" | "computed" | (string & {});
+export interface PortableAnnotationProvenance {
+    author?: string;
+    authorKind?: PortableAnnotationActorKind;
+    source?: PortableAnnotationSource;
+    basis?: PortableAnnotationBasis;
+    /** 0–1. */
+    confidence?: number;
+    /** ISO 8601 timestamp. */
+    createdAt?: string;
+    dataVersion?: string;
+    stableId?: string;
+}
+/** Closed union. */
+export type PortableAnnotationFreshness = "fresh" | "aging" | "stale" | "expired";
+/** Closed union. */
+export type PortableAnnotationStatus = "proposed" | "accepted" | "disputed" | "retracted";
+/** Closed union. */
+export type PortableAnnotationAnchor = "fixed" | "latest" | "sticky" | "semantic";
+export interface PortableAnnotationLifecycle {
+    freshness?: PortableAnnotationFreshness;
+    status?: PortableAnnotationStatus;
+    /** provenance.stableId of the annotation this one replaces. */
+    supersedes?: string;
+    /** ISO 8601 duration string or milliseconds. */
+    ttlHint?: string | number;
+    anchor?: PortableAnnotationAnchor;
+}
+/** Any annotation may carry the two optional blocks. */
+export type PortableAnnotated<T = Record<string, unknown>> = T & {
+    provenance?: PortableAnnotationProvenance;
+    lifecycle?: PortableAnnotationLifecycle;
+};
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Structurally validate a portable chart capability. Dependency-free; mirrors
+ * the required/range constraints in chart-capability.schema.json. Not a full
+ * JSON-Schema validation — for that, run the published schema through ajv.
+ */
+export declare function validatePortableCapability(value: unknown): ValidationResult;
+/** Structurally validate a portable audience profile. */
+export declare function validatePortableAudienceProfile(value: unknown): ValidationResult;
+/**
+ * Structurally validate the provenance + lifecycle blocks on an annotation.
+ * Validates only the two IDID blocks; the rest of the annotation (positional
+ * fields, type, label) is the host's concern.
+ */
+export declare function validatePortableAnnotation(value: unknown): ValidationResult;

package/dist/components/data/portability/vegaLite.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Outbound Vega-Lite + the IDID-over-Vega-Lite binding (v0.1).
+ *
+ * `toVegaLite` is the inverse of `fromVegaLite`: a Semiotic ChartConfig back to
+ * a Vega-Lite spec. Round-tripping through the dominant interchange format —
+ * *with the IDID metadata preserved* — is the portability claim in runnable
+ * form.
+ *
+ * The binding functions (`attachIDID` / `readIDID`, `attachIDIDAnnotations` /
+ * `readIDIDAnnotations`) define WHERE the three portable primitives ride on a
+ * Vega-Lite spec so the spec and its IDID metadata travel together. The
+ * convention is documented in `/spec/README.md`.
+ *
+ * Pure, dependency-free, no chart-family imports.
+ */
+import type { ChartConfig } from "../../export/chartConfig";
+import type { VegaLiteSpec } from "../fromVegaLite";
+import type { PortableAnnotated, PortableAudienceProfile, PortableChartCapability } from "./spec";
+/**
+ * Translate a Semiotic ChartConfig into a Vega-Lite spec. Covers the families
+ * `fromVegaLite` covers, so the pair round-trips. Constructs unsupported by
+ * Vega-Lite's single-view core surface a warning rather than a wrong spec.
+ */
+export declare function toVegaLite(config: ChartConfig): VegaLiteSpec & {
+    warnings?: string[];
+};
+/** The metadata block that rides under `usermeta.idid`. */
+export interface IDIDVegaLiteMeta {
+    specVersion: string;
+    capability?: PortableChartCapability;
+    audience?: PortableAudienceProfile;
+    /** Provenanced annotations carried alongside the spec. */
+    annotations?: PortableAnnotated[];
+}
+/**
+ * Attach a capability descriptor and/or an audience profile to a Vega-Lite
+ * spec under `usermeta.idid`. A non-IDID renderer ignores `usermeta`; an
+ * IDID-aware host reads it (e.g. to route the capability through a suggestion
+ * engine). Returns a new spec; the input is not mutated.
+ */
+export declare function attachIDID(spec: VegaLiteSpec, meta: {
+    capability?: PortableChartCapability;
+    audience?: PortableAudienceProfile;
+}): VegaLiteSpec;
+/** Read the IDID metadata block from a Vega-Lite spec, if present. */
+export declare function readIDID(spec: VegaLiteSpec): IDIDVegaLiteMeta | undefined;
+/**
+ * Attach provenanced/lifecycled annotations to a Vega-Lite spec.
+ *
+ * The annotations are stored verbatim (with their provenance/lifecycle blocks)
+ * under the spec's `usermeta.idid.annotations` — that is the round-trip
+ * contract, and it composes with capability/audience metadata under the same
+ * key. As a courtesy to non-IDID renderers, each annotation that has a
+ * representable shape also emits a best-effort `rule`/`text` mark in an
+ * appended layer, so a plain Vega-Lite renderer still draws something. When no
+ * annotation is representable, no layer is added (avoiding an invalid empty
+ * layer) and the metadata still rides on `usermeta`. Returns a new spec; the
+ * input is not mutated.
+ */
+export declare function attachIDIDAnnotations(spec: VegaLiteSpec, annotations: ReadonlyArray<PortableAnnotated>): VegaLiteSpec;
+/** Read provenanced annotations back from a Vega-Lite spec. */
+export declare function readIDIDAnnotations(spec: VegaLiteSpec): PortableAnnotated[];

package/dist/components/realtime/ReorderBuffer.d.ts

@@ -0,0 +1,54 @@
+export type LatePolicy = "drop" | "keep";
+export interface ReorderBufferConfig<T> {
+    /** Grace window in ms. Events older than `watermark − lateness` are late. */
+    lateness: number;
+    /** Event-time accessor (ms). */
+    getTime: (item: T) => number;
+    /**
+     * What to do with a late event:
+     * - `"drop"` (default): discard it (still counted).
+     * - `"keep"`: release it immediately, out of order (still counted).
+     */
+    latePolicy?: LatePolicy;
+}
+export interface ReorderResult<T> {
+    /**
+     * Events ready to append to the main buffer now, in event-time order.
+     * Already reflects the late policy — dropped late events are excluded.
+     */
+    released: T[];
+    /** The events that were late this push (informational; for diagnostics). */
+    late: T[];
+}
+/**
+ * Buffers pushed events and releases them in event-time order once they
+ * fall outside the grace window. Stateful; one instance per series.
+ */
+export declare class ReorderBuffer<T> {
+    private readonly lateness;
+    private readonly getTime;
+    private readonly latePolicy;
+    private held;
+    private _watermark;
+    private _lateCount;
+    constructor(config: ReorderBufferConfig<T>);
+    /**
+     * Ingest one event. Returns the events that became safe to emit (in
+     * event-time order) plus any late events seen this push.
+     */
+    push(item: T): ReorderResult<T>;
+    /** Release all events whose time is at or before `watermark − lateness`. */
+    private drain;
+    /**
+     * Release everything still held, in event-time order — e.g. when the
+     * stream ends and the remaining grace-window events should be shown.
+     */
+    flush(): T[];
+    clear(): void;
+    /** Largest event-time seen, or `-Infinity` if empty. */
+    get watermark(): number;
+    /** Total late events seen since construction (or last `clear`). */
+    get lateCount(): number;
+    /** Events currently held inside the grace window. */
+    get heldCount(): number;
+}

package/dist/components/realtime/RunningStats.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Accumulates count, mean, variance, standard deviation, min, and max
+ * over a stream of numbers using Welford's online algorithm.
+ *
+ * Numerically stable in a single pass — preferred over the naive
+ * "sum of squares minus square of sum" form, which loses precision
+ * when values are large or closely clustered.
+ */
+export declare class RunningStats {
+    private _count;
+    private _mean;
+    private _m2;
+    private _min;
+    private _max;
+    /**
+     * Incorporate a value. O(1). Non-finite values (NaN, ±Infinity) are
+     * ignored — they would corrupt every downstream statistic — matching
+     * `IncrementalExtent`'s filter so all accumulators agree on what counts.
+     */
+    push(value: number): void;
+    /**
+     * Fold another accumulator's statistics into this one, in O(1),
+     * without revisiting the underlying values. Uses the parallel
+     * variance combine (Chan, Golub & LeVeque). Associative and
+     * commutative up to floating-point rounding — `a.merge(b)` then
+     * `a.merge(c)` yields the same result as merging in any order.
+     *
+     * Merging an empty accumulator is a no-op; merging into an empty
+     * accumulator copies the other's state.
+     */
+    merge(other: RunningStats): void;
+    /** Reset to the empty state. */
+    clear(): void;
+    /** A detached copy — useful for snapshotting a window before rollup. */
+    clone(): RunningStats;
+    /** Number of values incorporated. */
+    get count(): number;
+    /** Arithmetic mean, or 0 when empty. */
+    get mean(): number;
+    /**
+     * Sum of all values. Derived as `mean × count`, so it carries the
+     * same (tiny) floating drift as the running mean rather than a
+     * separate exact accumulator.
+     */
+    get sum(): number;
+    /**
+     * Population variance (divides by `count`). 0 when fewer than two
+     * values have been seen. Use this for a complete window of points —
+     * the window *is* the population. See {@link sampleVariance} for the
+     * unbiased estimator over a sample.
+     */
+    get variance(): number;
+    /** Population standard deviation — `sqrt(variance)`. */
+    get stddev(): number;
+    /**
+     * Sample variance (divides by `count − 1`, Bessel's correction).
+     * 0 when fewer than two values have been seen.
+     */
+    get sampleVariance(): number;
+    /** Sample standard deviation — `sqrt(sampleVariance)`. */
+    get sampleStddev(): number;
+    /** Smallest value seen, or `Infinity` when empty. */
+    get min(): number;
+    /** Largest value seen, or `-Infinity` when empty. */
+    get max(): number;
+}

package/dist/components/realtime/WindowAccumulator.d.ts

@@ -0,0 +1,105 @@
+/** The Kafka Streams window taxonomy. */
+export type WindowType = "tumbling" | "hopping" | "session";
+/** Which statistic the aggregated series carries as its primary value. */
+export type AggregateStat = "mean" | "sum" | "min" | "max" | "count";
+/** Envelope drawn around the aggregated series. */
+export type AggregateBand = "stddev" | "minmax" | "none";
+export interface WindowAccumulatorConfig {
+    /** Window kind. Defaults to `"tumbling"`. */
+    window?: WindowType;
+    /**
+     * Window width in **milliseconds** (already parsed from any duration
+     * string by the caller). For session windows this is unused; pass
+     * `gap` instead.
+     */
+    size: number;
+    /**
+     * Advance between consecutive hopping windows, in ms. Only meaningful
+     * for `window: "hopping"`; must satisfy `0 < hop ≤ size`. Defaults to
+     * `size`, which makes hopping degenerate to tumbling.
+     */
+    hop?: number;
+    /**
+     * Inactivity gap in ms that closes a session. Only meaningful for
+     * `window: "session"`. Two events within `gap` of each other (in
+     * event-time) share a session; an event bridging two sessions merges
+     * them.
+     */
+    gap?: number;
+    /**
+     * Keep at most this many most-recent windows; older windows are
+     * pruned on push. Bounds memory for an unbounded stream. Defaults to
+     * unbounded (`Infinity`).
+     */
+    retain?: number;
+}
+/** A closed or still-filling aggregation window. */
+export interface AggregatedWindow {
+    /** Inclusive window start (event-time ms). */
+    start: number;
+    /** Exclusive window end (event-time ms). */
+    end: number;
+    /** Number of events in the window. */
+    count: number;
+    mean: number;
+    sum: number;
+    min: number;
+    max: number;
+    /** Population standard deviation. */
+    stddev: number;
+    /**
+     * `true` while the window may still receive events — the trailing,
+     * still-filling window(s) up to the latest watermark. Render these
+     * distinctly (the partial-bin convention) so a viewer doesn't read a
+     * half-filled aggregate as final.
+     */
+    partial: boolean;
+}
+/**
+ * Accumulates event-time windowed statistics. Stateful and mutable —
+ * one instance per streaming series. Pure with respect to event order.
+ */
+export declare class WindowAccumulator {
+    private readonly type;
+    private readonly size;
+    private readonly hop;
+    private readonly gap;
+    private readonly retain;
+    private windows;
+    private sessions;
+    private latest;
+    constructor(config: WindowAccumulatorConfig);
+    /** Incorporate one event. Non-finite time/value are ignored. */
+    push(time: number, value: number): void;
+    private pushFixed;
+    private bump;
+    private pushSession;
+    private prune;
+    /**
+     * Snapshot the current windows as aggregated rows, sorted by start.
+     * For tumbling/hopping a window is `partial` while the watermark has
+     * not yet passed its end; for session windows the most recent session
+     * is `partial` while within `gap` of the watermark.
+     */
+    emit(): AggregatedWindow[];
+    private emitFixed;
+    private emitSessions;
+    private row;
+    /** Number of live windows (or sessions). */
+    get windowCount(): number;
+    /** The watermark — largest event-time seen, or `-Infinity` if empty. */
+    get watermark(): number;
+    clear(): void;
+}
+/**
+ * Pull the primary value for a stat off an aggregated window. `count`
+ * reads the event count; the rest read the matching `RunningStats`
+ * field.
+ */
+export declare function statValue(w: AggregatedWindow, stat: AggregateStat): number;
+/**
+ * Compute the [lower, upper] band bounds for an aggregated window.
+ * `stddev` draws `value ± k·σ` around the chosen stat; `minmax` draws
+ * the observed range. Returns `null` for `none`.
+ */
+export declare function bandBounds(w: AggregatedWindow, band: AggregateBand, stat: AggregateStat, sigma?: number): [number, number] | null;