semiotic 3.7.3 → 3.7.5

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

@@ -0,0 +1,57 @@
+import type { LegendGroup } from "../types/legendTypes";
+import { type NetworkSymbolName } from "../stream/symbolPath";
+/**
+ * `legendGroupsFrom` — build the `LegendGroup[]` a custom-layout recipe passes
+ * through `frameProps.legend` (`{ legendGroups }`). All three custom-chart HOCs
+ * disable the built-in legend because the *layout* owns color/shape/size; without
+ * this, authors hand-roll the `LegendGroup` shape (its `styleFn`, custom-glyph
+ * `type` render functions, swatch sizing). This closes that gap without the frame
+ * having to guess the author's encoding — the recipe declares each channel and
+ * gets back a ready-to-render array.
+ *
+ * One group is emitted per provided channel, in order: **color → symbol → size**.
+ * Pure / SSR-safe.
+ *
+ * @example
+ * ```tsx
+ * <NetworkCustomChart
+ *   layout={packedClusterMatrix}
+ *   frameProps={{ legend: { legendGroups: legendGroupsFrom({
+ *     colorMap: CATEGORY_COLORS, colorLabel: "Category",
+ *     symbolMap: CLASS_SHAPES, symbolLabel: "Class",
+ *     sizeStops: [200, 2000, 8000], sizeRadius: r, sizeLabel: "Mass (kg)",
+ *   }) } }}
+ * />
+ * ```
+ */
+export interface LegendGroupsInput {
+    /** `{category → color}` map → one swatch per entry, in insertion order. */
+    colorMap?: Record<string, string>;
+    /** Or explicit category keys, with `color` resolving each to a color. */
+    keys?: string[];
+    /** Resolve a key → color (e.g. a recipe's `ctx.resolveColor`). Used with `keys`. */
+    color?: (key: string) => string;
+    /** Color-group heading. @default "" */
+    colorLabel?: string;
+    /** Color swatch glyph — a filled square or a line stroke. @default "fill" */
+    colorType?: "fill" | "line";
+    /** `{category → glyph shape}` map → one shape swatch per entry. */
+    symbolMap?: Record<string, NetworkSymbolName>;
+    /** Fill for the shape swatches (shape, not color, is the encoding here).
+     *  @default "var(--semiotic-text, currentColor)" */
+    symbolColor?: string;
+    /** Symbol-group heading. @default "" */
+    symbolLabel?: string;
+    /** Reference values → circle swatches sized by the mark scale. */
+    sizeStops?: number[];
+    /** Map a value → radius (px) — pass the recipe's own radius scale so the
+     *  legend circles match the marks exactly. Required to draw the size group. */
+    sizeRadius?: (v: number) => number;
+    /** Format a size stop for its label. @default `String` */
+    sizeFormat?: (v: number) => string;
+    /** Size swatch circle fill. @default "var(--semiotic-text, currentColor)" */
+    sizeColor?: string;
+    /** Size-group heading. @default "" */
+    sizeLabel?: string;
+}
+export declare function legendGroupsFrom(input: LegendGroupsInput): LegendGroup[];

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

@@ -5,6 +5,21 @@ import type { Datum } from "../charts/shared/datumTypes";
  * the boundary and lets the layout body call a single function.
  */
 export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) => T)): (d: Datum) => T;
+/**
+ * Read a field off a network-ingest wrapper (`node.data.<key>`) or the node
+ * itself, with a fallback. Network recipes receive `RealtimeNode`/`RealtimeEdge`
+ * wrappers whose user data lives under `.data`; several recipes (lineageDag,
+ * mermaidDag, packedClusterMatrix, …) each re-declared this identical reader, so
+ * it lives here once. Returns `unknown` — narrow at the call site.
+ */
+export declare function readField(d: unknown, key: string, fallback: unknown): unknown;
+/**
+ * Group items into a `Map` keyed by a derived string. Insertion order is
+ * preserved both for keys and within each bucket — recipes rely on stable
+ * ordering for deterministic layout. Several recipes re-declared this; it lives
+ * here once.
+ */
+export declare function groupBy<T>(items: readonly T[], key: (item: T) => string): Map<string, T[]>;
 /**
  * Build a datum object whose own-properties are safe to set from
  * user-supplied accessor names. `Object.create(null)` produces a
@@ -25,3 +40,93 @@ export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) =>
  * scattered across each recipe's inner loops.
  */
 export declare function createSafeDatum(populate: (set: (key: string, value: unknown) => void) => void): Datum;
+/**
+ * A `{field, value}` highlight target — or an array of them, AND-combined (a
+ * datum must match every entry to count as a match, e.g. a region×orbit cell).
+ * `value` is coerced to a string before comparison; a nullish `value` matches
+ * anything (so `{ field, value: null }` is a no-op constraint).
+ */
+export type HighlightMatch = {
+    field: string;
+    value: unknown;
+} | ReadonlyArray<{
+    field: string;
+    value: unknown;
+}>;
+/**
+ * Whether `datum` satisfies a `{field, value}` highlight (or every entry of an
+ * array). A nullish/empty `highlight` matches everything — the "no highlight
+ * active" case. Several recipes hand-rolled this exact field/value loop.
+ */
+export declare function matchesHighlight(datum: Datum, highlight: HighlightMatch | null | undefined): boolean;
+export interface DimOptions {
+    /** A datum is lit only if this predicate passes (e.g. a shared-selection
+     *  predicate, or `parallelCoordinates`'s `highlightFn`). Omit ⇒ no constraint. */
+    predicate?: ((d: Datum) => boolean) | null;
+    /** A datum is lit only if it matches this `{field, value}` (or all, for an
+     *  array). Omit ⇒ no constraint. Composes with `predicate` (both must pass). */
+    highlight?: HighlightMatch | null;
+    /** Opacity used when no cue is active (nothing is dimmed). @default 1 */
+    baseOpacity?: number;
+    /** Opacity for marks that don't match an active cue. @default 0.16 */
+    dimOpacity?: number;
+    /** Additive opacity boost for matching marks when a cue is active, capped at 1
+     *  (e.g. `parallelCoordinates` lifts its 0.45 line opacity by 0.4 on match). @default 0 */
+    brighten?: number;
+}
+/**
+ * The highlight/dim opacity rule, shared across custom-layout recipes. A mark is
+ * "lit" when it satisfies **every** active cue (`highlight` AND `predicate`); if
+ * no cue is active nothing is dimmed and every mark gets `baseOpacity`. Lit marks
+ * get `min(1, baseOpacity + brighten)`, dimmed marks get `dimOpacity`.
+ *
+ * This is the one rule `packedClusterMatrix` and `parallelCoordinates` each
+ * hand-rolled; centralizing it keeps the "matching marks stay lit, the rest dim"
+ * behavior identical. (Recipes whose dimming composes several cues with priority
+ * and rescue rules — e.g. `lineageDag`'s reach-set-over-selection — keep their
+ * bespoke logic; this helper is for the common AND-of-cues case.)
+ */
+export declare function dimFor(datum: Datum, opts?: DimOptions): number;
+/**
+ * Join layout-affecting inputs into a stable content-signature string. Pass the
+ * primitives that change the geometry (dimensions, gaps, orders, a per-datum
+ * fingerprint) — NOT styling/interaction inputs (color, shade, highlight) — so a
+ * re-style or a returning resize reuses a cached layout instead of recomputing it.
+ * Pairs with {@link LayoutCache}.
+ */
+export declare function signatureKey(parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+/**
+ * A tiny bounded geometry cache for expensive layouts (force packing, tree/DAG
+ * positioning). Key it with a {@link signatureKey} of the layout-affecting inputs
+ * so re-styling on interaction never re-runs the layout.
+ *
+ * **The sharp edge:** on `NetworkCustomChart`/`*CustomChart`, `ctx.nodes` is a
+ * *fresh array each `buildScene`* and a `layoutConfig` change re-runs the layout
+ * without re-ingesting topology — so cache by *content* (a fingerprint of the
+ * data), never by array identity. Over `maxSize` distinct keys it clears wholesale
+ * (these layouts churn a handful of signatures, not thousands).
+ */
+export declare class LayoutCache<V> {
+    private readonly maxSize;
+    private store;
+    constructor(maxSize?: number);
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    /** Return the cached value for `key`, or compute + store it on a miss. */
+    getOrCompute(key: string, compute: () => V): V;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * A reusable lightness shader for one base color. Interpolating in CIELAB keeps
+ * the hue and chroma roughly fixed while only lightness moves, so a categorical
+ * hue can carry a second *continuous* channel as shade (e.g. age, recency).
+ *
+ * The returned function takes `t ∈ [0,1]`: `0` lightens toward white, `1`
+ * darkens toward black, `0.5` returns the base. `strength` (0..1) caps how far
+ * each direction travels. Pure / SSR-safe — no DOM. Build once per base color
+ * (it captures two interpolators) and call per datum.
+ */
+export declare function makeShade(baseColor: string, strength?: number): (t: number) => string;
+/** One-shot form of {@link makeShade}: perceptual lightness shade of `baseColor`. */
+export declare function shade(baseColor: string, t: number, strength?: number): string;

package/dist/components/semiotic-ai.d.ts

@@ -78,6 +78,12 @@ export { describeChart, resolveCommunicativeAct, communicativeActForIntent } fro
 export type { DescribeChartResult, DescribeChartOptions, DescribeLevel, CommunicativeAct, DescribeCapabilityContext } from "./ai/describeChart";
 export { buildReaderGrounding } from "./ai/readerGrounding";
 export type { ChartReaderGrounding, ChartReaderGroundingOptions, ChartReaderGroundingIntent } from "./ai/readerGrounding";
+export { buildDataPitfallsBridge, toDataPitfallsChain } from "./ai/dataPitfallsBridge";
+export type { DataPitfallsBridgeOptions, DataPitfallsBridgeResult, DataPitfallsChainInput, DataPitfallsChainStage, DataPitfallsDocumentInput, DataPitfallsImageInput, DataPitfallsImageMediaType, DataPitfallsImageSource, DataPitfallsRenderedChart, DataPitfallsSlideContent, DataPitfallsSlidesInput, DataPitfallsSingleArtifactInput, DataPitfallsTextInput } from "./ai/dataPitfallsBridge";
+export { dataQualityToAnnotations, fromDbtArtifacts, fromGreatExpectations } from "./ai/dataQualityBridge";
+export type { DataQualityStatus, DataQualityCheckKind, DataQualityResult, DataQualityAnnotationOptions, DataQualityAnnotationsResult, UnplacedDataQualityResult, DbtArtifacts, GEValidationResult } from "./ai/dataQualityBridge";
+export { prepareChart, chartGenerationTool, toAnthropicTool, toOpenAITool, createChartToolHandler } from "./ai/generativeChart";
+export type { RenderFn, PrepareChartInput, PrepareChartOptions, PrepareChartResult, ChartToolDefinition, ChartToolOptions } from "./ai/generativeChart";
 export { buildNavigationTree, flattenVisible, countNodes } from "./ai/navigationTree";
 export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
 export { AccessibleNavTree } from "./AccessibleNavTree";

package/dist/components/semiotic-data.d.ts

@@ -5,4 +5,6 @@
 export { bin, rollup, groupBy, pivot } from "./data/transforms";
 export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
+export { fromArrow } from "./data/fromArrow";
+export type { ArrowTableLike, ArrowColumnLike, ArrowFieldLike, ArrowSchemaLike, FromArrowOptions, } from "./data/fromArrow";
 export { mergeData } from "./geo/mergeData";

package/dist/components/semiotic-experimental.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Experimental entry point for temporary adapters and unstable previews.
+ *
+ * Anything imported from "semiotic/experimental" is intentionally outside
+ * Semiotic's stable public API. Exports may be renamed, moved, or removed
+ * without a deprecation window and are excluded from stable API-surface and
+ * bundle-size gates.
+ */
+export { EXPERIMENTAL_GOFISH_ADAPTER_NAME, unstable_fromGofishIR, } from "./recipes/gofishIR";
+export type { GofishIRDocument as UnstableGofishIRDocument, GofishChartConfig as UnstableGofishChartConfig, GofishChartFamily as UnstableGofishChartFamily, FromGofishIROptions as UnstableFromGofishIROptions, } from "./recipes/gofishIR";
+export { registerGofishLambda as unstable_registerGofishLambda, unregisterGofishLambda as unstable_unregisterGofishLambda, } from "./recipes/gofishLambdas";
+export type { GofishLambda as UnstableGofishLambda, } from "./recipes/gofishLambdas";
+export { gofishIRExamples as unstable_gofishIRExamples, flowerIR as unstable_gofishFlowerIR, bottleIR as unstable_gofishBottleIR, polarRibbonIR as unstable_gofishPolarRibbonIR, titanicCircleTreemapIR as unstable_gofishTitanicCircleTreemapIR, pythonMemoryIR as unstable_gofishPythonMemoryIR, bobaIR as unstable_gofishBobaIR, } from "./recipes/gofishIRExamples";
+export type { GofishIRExample as UnstableGofishIRExample } from "./recipes/gofishIRExamples";
+export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS as unstable_BUILTIN_INTENT_IDS, validatePortableCapability as unstable_validatePortableCapability, validatePortableAudienceProfile as unstable_validatePortableAudienceProfile, validatePortableAnnotation as unstable_validatePortableAnnotation, toVegaLite as unstable_toVegaLite, attachIDID as unstable_attachIDID, readIDID as unstable_readIDID, attachIDIDAnnotations as unstable_attachIDIDAnnotations, readIDIDAnnotations as unstable_readIDIDAnnotations, } from "./data/portability";
+export { fromObservablePlot as unstable_fromObservablePlot } from "./data/fromObservablePlot";
+export { fromMermaid as unstable_fromMermaid } from "./data/fromMermaid";
+export type { MermaidResult as UnstableMermaidResult, MermaidNode as UnstableMermaidNode, MermaidEdge as UnstableMermaidEdge, MermaidDirection as UnstableMermaidDirection, MermaidNodeShape as UnstableMermaidNodeShape, } from "./data/fromMermaid";
+export type { ObservablePlotSpec as UnstableObservablePlotSpec, ObservablePlotMark as UnstableObservablePlotMark, ObservablePlotMarkOptions as UnstableObservablePlotMarkOptions, ObservablePlotScale as UnstableObservablePlotScale, ObservablePlotChannel as UnstableObservablePlotChannel, } from "./data/fromObservablePlot";
+export type { BuiltInIntentId as UnstableBuiltInIntentId, PortableIntentId as UnstablePortableIntentId, PortableChartRubric as UnstablePortableChartRubric, PortableChartVariant as UnstablePortableChartVariant, PortableChartCapability as UnstablePortableChartCapability, PortableReceptionModality as UnstablePortableReceptionModality, PortableAudienceTarget as UnstablePortableAudienceTarget, PortableAudienceProfile as UnstablePortableAudienceProfile, PortableAnnotationProvenance as UnstablePortableAnnotationProvenance, PortableAnnotationLifecycle as UnstablePortableAnnotationLifecycle, PortableAnnotated as UnstablePortableAnnotated, ValidationResult as UnstablePortabilityValidationResult, IDIDVegaLiteMeta as UnstableIDIDVegaLiteMeta, } from "./data/portability";

package/dist/components/semiotic-network.d.ts

@@ -13,6 +13,8 @@ export { CirclePack } from "./charts/network/CirclePack";
 export { OrbitDiagram } from "./charts/network/OrbitDiagram";
 export { ProcessSankey } from "./charts/network/ProcessSankey";
 export { NetworkCustomChart } from "./charts/custom/NetworkCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
 export type { ForceDirectedGraphProps } from "./charts/network/ForceDirectedGraph";
 export type { SankeyDiagramProps } from "./charts/network/SankeyDiagram";
@@ -23,6 +25,6 @@ export type { TreemapProps } from "./charts/network/Treemap";
 export type { CirclePackProps } from "./charts/network/CirclePack";
 export type { OrbitDiagramProps } from "./charts/network/OrbitDiagram";
 export type { NetworkCustomChartProps } from "./charts/custom/NetworkCustomChart";
-export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
+export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, NetworkHtmlMark, } from "./stream/networkCustomLayout";
 export { validateProcessSankey, formatProcessSankeyIssue, } from "./charts/network/processSankey/algorithm";
 export type { ProcessSankeyNode as ProcessSankeyValidatorNode, ProcessSankeyEdge as ProcessSankeyValidatorEdge, ProcessSankeyIssue, } from "./charts/network/processSankey/algorithm";

package/dist/components/semiotic-ordinal.d.ts

@@ -21,6 +21,8 @@ export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
 export { FunnelChart } from "./charts/ordinal/FunnelChart";
 export { LikertChart } from "./charts/ordinal/LikertChart";
 export { OrdinalCustomChart } from "./charts/custom/OrdinalCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";

package/dist/components/semiotic-realtime.d.ts

@@ -6,12 +6,20 @@ import StreamXYFrame from "./stream/StreamXYFrame";
 import StreamNetworkFrame from "./stream/StreamNetworkFrame";
 import { RingBuffer } from "./realtime/RingBuffer";
 import { IncrementalExtent } from "./realtime/IncrementalExtent";
+import { RunningStats } from "./realtime/RunningStats";
+import { WindowAccumulator, statValue, bandBounds } from "./realtime/WindowAccumulator";
+import { parseWindowDuration } from "./realtime/parseWindowDuration";
+import { ReorderBuffer } from "./realtime/ReorderBuffer";
 import { RealtimeLineChart } from "./charts/realtime/RealtimeLineChart";
 import { RealtimeHistogram, TemporalHistogram } from "./charts/realtime/RealtimeHistogram";
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
+export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RunningStats, WindowAccumulator, statValue, bandBounds, parseWindowDuration, ReorderBuffer, RealtimeLineChart, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
+export type { WindowType, AggregateStat, AggregateBand, WindowAccumulatorConfig, AggregatedWindow, } from "./realtime/WindowAccumulator";
+export type { AggregateConfig } from "./charts/realtime/aggregate";
+export type { LatePolicy, ReorderBufferConfig, ReorderResult, } from "./realtime/ReorderBuffer";
+export type { EventTimeConfig } from "./charts/realtime/eventTime";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
 export type { RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";

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

@@ -13,6 +13,12 @@ export { flextreeLayout } from "./recipes/flextree";
 export type { FlextreeConfig } from "./recipes/flextree";
 export { dagreLayout } from "./recipes/dagre";
 export type { DagreConfig } from "./recipes/dagre";
+export { lineageDagLayout } from "./recipes/lineageDag";
+export type { LineageDagConfig, LineageLod, LineageStoreSlot } from "./recipes/lineageDag";
+export { mermaidDagLayout } from "./recipes/mermaidDag";
+export type { MermaidDagConfig } from "./recipes/mermaidDag";
+export { packedClusterMatrix } from "./recipes/packedClusterMatrix";
+export type { PackedClusterMatrixConfig } from "./recipes/packedClusterMatrix";
 export { marimekkoLayout } from "./recipes/marimekko";
 export type { MarimekkoConfig } from "./recipes/marimekko";
 export { bulletLayout } from "./recipes/bullet";
@@ -24,5 +30,18 @@ export type { AnnotationLayoutConfig, AnnotationLayoutOptions, AutoPlaceAnnotati
 export { annotationDensity, annotationBudget, DEFAULT_AREA_PER_ANNOTATION } from "./recipes/annotationDensity";
 export type { AnnotationDensityConfig, AnnotationDensityOptions, AnnotationDensityResult, } from "./recipes/annotationDensity";
 export type { CustomLayout, LayoutContext, LayoutResult, } from "./stream/customLayout";
-export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
+export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, NetworkHtmlMark, } from "./stream/networkCustomLayout";
 export type { OrdinalCustomLayout, OrdinalLayoutContext, OrdinalLayoutResult, } from "./stream/ordinalCustomLayout";
+export { shade, makeShade, readField, groupBy } from "./recipes/recipeUtils";
+export { dimFor, matchesHighlight, signatureKey, LayoutCache } from "./recipes/recipeUtils";
+export type { DimOptions, HighlightMatch } from "./recipes/recipeUtils";
+export { symbolPathString, symbolRadius, symbolExtent, SYMBOL_SEQUENCE } from "./stream/symbolPath";
+export type { NetworkSymbolName } from "./stream/symbolPath";
+export { roundedEnclosure, boundsOf, bandLabel, markCallout } from "./recipes/recipeChrome";
+export type { RoundedEnclosureProps, BandLabelProps, MarkCalloutProps, CalloutConnector, } from "./recipes/recipeChrome";
+export { legendGroupsFrom } from "./recipes/recipeLegend";
+export type { LegendGroupsInput } from "./recipes/recipeLegend";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
+export { buildTooltipEntries, extractTooltipDatum, formatTooltipValue, } from "./recipes/customTooltip";
+export type { CustomTooltipEntry, CustomTooltipEntryOptions, } from "./recipes/customTooltip";

package/dist/components/semiotic-themes.d.ts

@@ -79,3 +79,5 @@ export declare function themeToCSS(theme: SemioticTheme, selector?: string): str
  * ```
  */
 export declare function themeToTokens(theme: SemioticTheme): Datum;
+export { designTokensToTheme } from "./store/designTokens";
+export type { DesignTokensToThemeOptions } from "./store/designTokens";

package/dist/components/semiotic-xy.d.ts

@@ -18,6 +18,8 @@ export { QuadrantChart } from "./charts/xy/QuadrantChart";
 export { MultiAxisLineChart } from "./charts/xy/MultiAxisLineChart";
 export { CandlestickChart } from "./charts/xy/CandlestickChart";
 export { XYCustomChart } from "./charts/custom/XYCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";
 export type { CustomLayout, LayoutContext, LayoutResult } from "./stream/customLayout";
 export type { LineChartProps } from "./charts/xy/LineChart";

package/dist/components/semiotic.d.ts

@@ -32,8 +32,10 @@ export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartTyp
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
 export type { SelectionConfig, LinkedHoverProp, LinkedBrushProp } from "./charts/shared/types";
 export type { LinkedChartsProps } from "./LinkedCharts";
-export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
-export type { UseSelectionOptions, UseSelectionResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
+export { useSelection, useSelectionActions, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
 export { useChartObserver } from "./LinkedCharts";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./LinkedCharts";
 export type { ChartObservation, OnObservationCallback } from "./store/ObservationStore";
@@ -62,6 +64,8 @@ export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export { smartTickFormat, adaptiveTimeTicks } from "./charts/shared/formatUtils";
 export { darkenColor, lightenColor } from "./charts/shared/colorManipulation";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "./Tooltip/Tooltip";
+export { smartTooltipEntries } from "./charts/shared/tooltipUtils";
+export type { SmartTooltipEntry, SmartTooltipResult } from "./charts/shared/tooltipUtils";
 export type { ArrowOfTime, WindowMode, ThresholdType, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, AnnotationContext, AnnotationAnchorMode, CrosshairStyle, HoverAnnotationConfig, HoverData } from "./realtime/types";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
 export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";

package/dist/components/store/ObservationStore.d.ts

@@ -45,7 +45,26 @@ export interface ClickObservation extends ObservationBase {
 export interface ClickEndObservation extends ObservationBase {
     type: "click-end";
 }
-export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation;
+/**
+ * Emitted when an event-time stream receives a record outside its
+ * lateness/grace window (see `ReorderBuffer`). Surfaces lateness as an
+ * observable signal — for stream diagnostics — rather than silently
+ * dropping it.
+ */
+export interface LateDataObservation extends ObservationBase {
+    type: "late-data";
+    /** The late datum that arrived outside the grace window. */
+    datum: Datum;
+    /** Event-time of the late datum. */
+    eventTime: number;
+    /** Watermark (largest event-time seen) when it arrived. */
+    watermark: number;
+    /** Whether it was dropped or kept, per the late policy. */
+    policy: "drop" | "keep";
+    /** Running total of late events seen on this chart. */
+    lateCount: number;
+}
+export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | LateDataObservation;
 export type OnObservationCallback = (observation: ChartObservation) => void;
 export interface ObservationStoreState {
     /** Ring buffer of recent observations (newest last). Mutated in place for perf. */
@@ -56,5 +75,5 @@ export interface ObservationStoreState {
     pushObservation: (observation: ChartObservation) => void;
     clearObservations: () => void;
 }
-export declare const ObservationProvider: import("react").FC<import("./createStore").StoreProviderProps<ObservationStoreState>>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R) => R;
+export declare const ObservationProvider: import("react").FC<import("./createStore").StoreProviderProps<ObservationStoreState>>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;
 export {};

package/dist/components/store/SelectionStore.d.ts

@@ -27,4 +27,4 @@ export interface SelectionStoreState {
     clearSelection: (selectionName: string) => void;
 }
 export declare function buildPredicate(selection: Selection, requestingClientId?: string): (d: Datum) => boolean;
-export declare const SelectionProvider: import("react").FC<import("./createStore").StoreProviderProps<SelectionStoreState>>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R) => R;
+export declare const SelectionProvider: import("react").FC<import("./createStore").StoreProviderProps<SelectionStoreState>>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;

package/dist/components/store/ThemeStore.d.ts

@@ -100,4 +100,4 @@ export type SemioticThemeUpdate = Omit<Partial<SemioticTheme>, "colors" | "typog
 };
 export type ThemeStoreUpdate = SemioticThemeUpdate | "light" | "dark" | "high-contrast";
 export declare function resolveThemeUpdate(current: SemioticTheme, theme: ThemeStoreUpdate): SemioticTheme;
-export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R) => R;
+export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;

package/dist/components/store/TooltipStore.d.ts

@@ -2,5 +2,5 @@ interface TooltipStoreState {
     tooltip: unknown;
     changeTooltip: (tooltip: unknown) => void;
 }
-declare const TooltipProvider: import("react").FC<import("./createStore").StoreProviderProps<TooltipStoreState>>, useTooltip: <R>(selector: (state: TooltipStoreState) => R) => R;
+declare const TooltipProvider: import("react").FC<import("./createStore").StoreProviderProps<TooltipStoreState>>, useTooltip: <R>(selector: (state: TooltipStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;
 export { TooltipProvider, useTooltip };

package/dist/components/store/createStore.d.ts

@@ -3,4 +3,4 @@ export interface StoreProviderProps<T> {
     children: React.ReactNode;
     initialState?: Partial<T>;
 }
-export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<StoreProviderProps<T>>, <R>(selector: (state: T) => R) => R];
+export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<StoreProviderProps<T>>, <R>(selector: (state: T) => R, equalityFn?: (a: R, b: R) => boolean) => R];

package/dist/components/store/designTokens.d.ts

@@ -0,0 +1,15 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemioticTheme } from "./ThemeStore";
+type ColorRole = "primary" | "secondary" | "background" | "surface" | "text" | "textSecondary" | "border" | "grid" | "focus" | "annotation" | "success" | "danger" | "warning" | "error" | "info";
+export interface DesignTokensToThemeOptions {
+    /** Theme to merge resolved roles onto. Defaults to LIGHT/DARK by detected bg. */
+    base?: SemioticTheme;
+    /** Pin a role to a token path, e.g. `{ primary: "color.brand.500" }`. */
+    mapping?: Partial<Record<ColorRole | "fontFamily" | "categorical", string>>;
+}
+/**
+ * Build a `SemioticTheme` from a W3C Design Tokens object. Inverse of
+ * `themeToTokens`; round-trips exactly for tokens under a `semiotic.*` group.
+ */
+export declare function designTokensToTheme(tokens: Datum, options?: DesignTokensToThemeOptions): SemioticTheme;
+export {};

package/dist/components/store/useSelection.d.ts

@@ -23,6 +23,28 @@ export interface UseSelectionResult {
     clientId: string;
 }
 export declare function useSelection(options: UseSelectionOptions): UseSelectionResult;
+export interface UseSelectionActionsResult {
+    /** Set a point selection (categorical values) under this client's clause. */
+    selectPoints: (fieldValues: Record<string, unknown[]>) => void;
+    /** Clear this client's clause. */
+    clear: () => void;
+    /** This client's ID. */
+    clientId: string;
+}
+/**
+ * Write-only access to a named selection that **does not subscribe** to the
+ * selection state — selecting only the stable `setClause`/`clearClause`
+ * actions, so the calling component never re-renders when the selection
+ * changes.
+ *
+ * Use this when a *container* needs to push a selection (e.g. from a hover
+ * handler) but only the leaf consumers (the charts reading the selection)
+ * should re-render. Pairs with `LinkedCharts` for the
+ * provider-at-top / consumers-at-leaves pattern: the writer stays out of the
+ * re-render path, avoiding per-interaction reconciliation + allocation in the
+ * container subtree. For read + write, use `useSelection`.
+ */
+export declare function useSelectionActions(name: string, clientId?: string): UseSelectionActionsResult;
 export interface UseLinkedHoverOptions {
     /** Selection name. Defaults to "hover" */
     name?: string;

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

@@ -0,0 +1,44 @@
+import * as React from "react";
+import type { NetworkHtmlMark } from "./networkCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+export interface NetworkHtmlMarksLayerProps {
+    /** Marks emitted by the custom layout (`NetworkLayoutResult.htmlMarks`). */
+    marks: NetworkHtmlMark[] | undefined;
+    /** The frame's margin — the layer is offset by it so marks align with the
+     *  canvas and SVG `overlays`, which translate their content by the same. */
+    margin: {
+        top: number;
+        left: number;
+    };
+    /** Shared-selection projection, provided so mark content can subscribe via
+     *  `useCustomLayoutSelection()` and restyle on selection change without a
+     *  relayout (parity with the SVG `overlays` subtree). `null` when unwired. */
+    selection?: CustomLayoutSelection | null;
+    /**
+     * Pixels beyond each visible edge of the scrolling viewport for which marks are
+     * still mounted (so a scroll reveals already-present DOM, not blank space).
+     * Marks farther than this off-screen are not rendered at all. Defaults to 400.
+     */
+    overscan?: number;
+}
+/**
+ * Renders a custom network layout's {@link NetworkHtmlMark}s into one
+ * absolutely-positioned DOM layer above the canvas and SVG `overlays`.
+ *
+ * Each mark is its own positioned element, keyed by `id`, so the browser can
+ * composite `opacity`/`transform`/`visibility` changes on the mark's content
+ * without re-rasterizing it (the win over SVG `<foreignObject>`), and a
+ * position-only layout re-run repositions without remounting. The wrapper sets
+ * only placement + sizing + `pointer-events`; everything visual comes from
+ * `content`.
+ *
+ * Marks are viewport-culled against the nearest scrollable ancestor (plus
+ * `overscan`): a mark more than `overscan` px outside the visible window is not
+ * in the DOM at all, so a large topology mounts only roughly a viewport's worth
+ * regardless of total size, and the per-hover/paint cost stays bounded. When
+ * there's no scrollable ancestor (the content fits) every mark renders.
+ *
+ * Returns `null` when there are no marks, so layouts that don't use the feature
+ * render no extra DOM.
+ */
+export declare function NetworkHtmlMarksLayer({ marks, margin, selection, overscan, }: NetworkHtmlMarksLayerProps): React.ReactElement | null;

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

@@ -1,4 +1,6 @@
 import { ParticlePool } from "./ParticlePool";
+import type { NetworkHtmlMark } from "./networkCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import { type Quadtree } from "d3-quadtree";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
@@ -29,6 +31,21 @@ export declare class NetworkPipelineStore {
     labels: NetworkLabel[];
     /** Overlays returned from customNetworkLayout (consumed by StreamNetworkFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    /** HTML marks returned from customNetworkLayout — positioned DOM nodes the
+     *  frame renders in a layer above the canvas/overlays (consumed by
+     *  StreamNetworkFrame). Empty for built-in chart types. */
+    customLayoutHtmlMarks: NetworkHtmlMark[];
+    private _customLayoutDiagnosticsWarned;
+    /** Per-frame restyle callbacks from the custom layout result. When set, the
+     *  frame routes selection changes through `restyleScene()` (style-only repaint)
+     *  instead of a full `buildScene()`. */
+    private _customRestyle;
+    private _customRestyleEdge;
+    /** True when the active custom layout supplied a `restyle`/`restyleEdge`. */
+    hasCustomRestyle: boolean;
+    /** Base (as-emitted) style per mark, so a restyle pass starts from the layout's
+     *  own style rather than compounding patches across selection changes. */
+    private _baseStyles;
     private _nodeQuadtree;
     private _maxNodeRadius;
     /** Bumped whenever sceneNodes is rebuilt; keys the quadtree cache. */
@@ -108,6 +125,21 @@ export declare class NetworkPipelineStore {
     /**
      * Build the scene graph from current layout positions.
      */
+    /** Update the selection the layout reads at the next `buildScene`, without
+     *  triggering a rebuild. The frame calls this on selection change; whether it
+     *  then repaints (restyle) or rebuilds is the frame's decision. */
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    /** Snapshot each mark's as-emitted style so {@link restyleScene} can re-apply
+     *  patches from the original rather than compounding. */
+    private snapshotBaseStyles;
+    /**
+     * Re-apply the custom layout's `restyle`/`restyleEdge` to the existing scene
+     * for `selection`, mutating styles **in place** off each mark's base style.
+     * Does NOT bump the scene revision — positions are unchanged, so the quadtree
+     * stays valid and no relayout/repack happens. The frame repaints the canvas
+     * after calling this. No-op when the layout supplied no restyle callbacks.
+     */
+    restyleScene(selection: CustomLayoutSelection | null): void;
     buildScene(size: [number, number]): void;
     /**
      * Lazily (re)build the circle-node spatial index. Only built when the scene

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

@@ -19,10 +19,22 @@ type AnnotationAnchorNode = {
     r?: number;
     /** Arc nodes (chord, radial) carry an outer radius. */
     outerR?: number;
+    /** Symbol nodes (the per-datum glyph channel) carry a d3-symbol area. */
+    size?: number;
 };
 type NetworkAnnotationContext = AnnotationContext & {
     sceneNodes?: AnnotationAnchorNode[];
 };
+/** Anchor id for a scene node — used to resolve `pointId`-anchored annotations
+ *  to a mark a layout emitted (incl. custom-layout marks). Exported for tests. */
+export declare function nodeAnchorId(node: AnnotationAnchorNode): string | undefined;
+/** Center + effective radius of a scene node for annotation anchoring. Exported
+ *  for tests. */
+export declare function nodeCenter(node: AnnotationAnchorNode): {
+    x: number;
+    y: number;
+    r: number;
+} | null;
 export interface NetworkSVGOverlayProps {
     width: number;
     height: number;

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

@@ -20,6 +20,7 @@ import { type Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 export declare class OrdinalPipelineStore {
     private buffer;
     private rExtent;
@@ -33,6 +34,7 @@ export declare class OrdinalPipelineStore {
     private getStack;
     private getGroup;
     private getColor;
+    private getSymbol;
     private getConnector;
     private getDataId;
     /** Discovered categories in insertion order */
@@ -55,6 +57,13 @@ export declare class OrdinalPipelineStore {
     columns: Record<string, OrdinalColumn>;
     /** Overlays returned from customLayout (consumed by StreamOrdinalFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    private _customLayoutDiagnosticsWarned;
+    /** Per-frame restyle callback from the custom layout result (see OrdinalLayoutResult.restyle). */
+    private _customRestyle;
+    /** True when the active custom layout supplied a `restyle`. */
+    hasCustomRestyle: boolean;
+    /** Base (as-emitted) style per node, so restyle passes don't compound. */
+    private _baseStyles;
     version: number;
     /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
     private _dataVersion;
@@ -142,5 +151,14 @@ export declare class OrdinalPipelineStore {
     get size(): number;
     getOAccessor(): (d: Datum) => string;
     getRAccessor(): (d: Datum) => number;
+    /** Update the selection the layout reads at the next rebuild, without one. */
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    private applyCustomRestyle;
+    /**
+     * Re-apply the custom layout's `restyle` to the existing scene for
+     * `selection`, off each node's base style — no relayout, no quadtree rebuild.
+     * No-op when the layout supplied no `restyle`.
+     */
+    restyleScene(selection: CustomLayoutSelection | null): void;
     updateConfig(config: Partial<OrdinalPipelineConfig>): void;
 }