semiotic 3.7.5 → 3.8.1

package/dist/components/server/animatedGif.d.ts

@@ -1,5 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { SemioticTheme } from "../store/ThemeStore";
+import { type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "../stream/physics/PhysicsPipelineStore";
+import { type PhysicsSettledSceneOptions } from "../stream/physics/PhysicsSettledScene";
 export interface AnimatedGifOptions {
     /** Frames per second (default 12) */
     fps?: number;
@@ -38,6 +40,30 @@ export interface AnimatedGifFrameConfig {
     /** Theme for styling */
     theme: SemioticTheme;
 }
+export interface PhysicsGifFrameProps extends Pick<PhysicsSettledSceneOptions, "bodyStyle" | "getBodyLabel"> {
+    config?: PhysicsPipelineConfig;
+    initialSpawns?: PhysicsQueuedSpawn[];
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    width?: number;
+    height?: number;
+    size?: [number, number];
+    theme?: SemioticTheme | string;
+    title?: string;
+    description?: string;
+    background?: string;
+    className?: string;
+    idPrefix?: string;
+}
+export interface PhysicsGifOptions extends Pick<AnimatedGifOptions, "fps" | "frameCount" | "loop" | "scale" | "background"> {
+    /** Total simulated seconds to render. Used when `frameCount` is omitted. */
+    durationSeconds?: number;
+    /** Fixed simulation steps advanced between rendered frames. Defaults to about `1 / fps`. */
+    stepsPerFrame?: number;
+    /** Fixed timestep used for each simulation step. Defaults to `config.fixedDt` or 1/120. */
+    stepDt?: number;
+    /** Include a frame after spawning at t=0 before advancing the simulation. */
+    includeInitialFrame?: boolean;
+}
 /**
  * Generate SVG strings for each animation frame.
  * This is the core logic shared between GIF export and client-side preview.
@@ -54,6 +80,15 @@ export declare function generateFrameSVGs(chartType: string, data: Datum[], prop
  * Each snapshot is passed directly to `renderChart()`.
  */
 export declare function generateFrameSequence(component: string, snapshots: Datum[], baseProps?: Datum): string[];
+/**
+ * Generate SVG frames by stepping a `PhysicsPipelineStore`.
+ *
+ * Unlike `generateFrameSVGs`, this does not slice data. It enqueues the supplied
+ * physics bodies once, advances the deterministic fixed-step simulation, and
+ * serializes each live snapshot. Use this for Galton boards, event-drop replay,
+ * piles, and custom physics scenes where sim time is the animation axis.
+ */
+export declare function generatePhysicsFrameSVGs(props: PhysicsGifFrameProps, options?: PhysicsGifOptions): string[];
 /**
  * Render a chart as an animated GIF.
  *
@@ -62,3 +97,4 @@ export declare function generateFrameSequence(component: string, snapshots: Datu
  * @returns Buffer containing the animated GIF
  */
 export declare function renderToAnimatedGif(chartType: string, data: Datum[], props: Datum, options?: AnimatedGifOptions): Promise<Buffer>;
+export declare function renderPhysicsToAnimatedGif(props: PhysicsGifFrameProps, options?: PhysicsGifOptions): Promise<Buffer>;

package/dist/components/server/optionalImageTypes.d.ts

@@ -0,0 +1,37 @@
+export interface SharpPipeline {
+    resize(width: number, height: number): SharpPipeline;
+    ensureAlpha(): SharpPipeline;
+    raw(): SharpPipeline;
+    jpeg(options: {
+        quality: number;
+    }): SharpPipeline;
+    png(): SharpPipeline;
+    toBuffer(): Promise<Buffer>;
+}
+export type SharpFactory = (input: Uint8Array, options?: {
+    density: number;
+}) => SharpPipeline;
+export type SharpModule = SharpFactory & {
+    default?: SharpFactory;
+};
+export type GifPalette = number[][] | Uint8Array;
+export interface GifEncoder {
+    writeFrame(indexedPixels: Uint8Array, width: number, height: number, options: {
+        palette: GifPalette;
+        delay: number;
+        repeat: number;
+    }): void;
+    finish(): void;
+    bytes(): Uint8Array;
+}
+export interface GifencExports {
+    GIFEncoder?: () => GifEncoder;
+    quantize?: (pixels: Uint8Array, maxColors: number) => GifPalette;
+    applyPalette?: (pixels: Uint8Array, palette: GifPalette) => Uint8Array;
+    default?: GifencExports;
+}
+export interface GifencRuntimeExports extends GifencExports {
+    GIFEncoder: () => GifEncoder;
+    quantize: (pixels: Uint8Array, maxColors: number) => GifPalette;
+    applyPalette: (pixels: Uint8Array, palette: GifPalette) => Uint8Array;
+}

package/dist/components/server/renderEvidence.d.ts

@@ -18,7 +18,7 @@
 export interface RenderEvidence {
     /** HOC component name as passed to renderChart. */
     component: string;
-    frameType: "xy" | "ordinal" | "network" | "geo";
+    frameType: "xy" | "ordinal" | "network" | "geo" | "physics";
     /** "ok" when the scene produced data marks; "empty" when it did not. */
     status: "ok" | "empty";
     /** True when zero data marks rendered. */

package/dist/components/server/renderToStaticSVG.d.ts

@@ -1,44 +1,12 @@
 import type { Datum } from "../charts/shared/datumTypes";
-import type { LegendLayout } from "../types/legendTypes";
-/**
- * Server-side rendering of Semiotic charts to standalone SVG strings.
- *
- * Uses the shared SceneToSVG converters (same code used by Stream Frames
- * for SSR) plus PipelineStore / OrdinalPipelineStore / NetworkPipelineStore
- * for scene graph computation.
- *
- * Features:
- * - Theme inlining (resolve presets to concrete SVG styles)
- * - Legend rendering (categorical color swatches)
- * - Accessibility (title, desc, role="img")
- * - Grid lines
- * - Annotations (y-threshold, x-threshold, band, label, text, category-highlight)
- * - renderChart HOC-level API
- */
-import * as React from "react";
 import type { StreamXYFrameProps } from "../stream/types";
 import type { StreamNetworkFrameProps } from "../stream/networkTypes";
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
 import type { StreamGeoFrameProps } from "../stream/geoTypes";
-import { type RenderEvidence } from "./renderEvidence";
-import { type ThemeInput } from "./themeResolver";
 import { CHART_CONFIGS } from "./serverChartConfigs";
-type FrameType = "xy" | "ordinal" | "network" | "geo";
-type StaticFrameProps = (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps) & ThemeAwareProps;
-interface ThemeAwareProps {
-    theme?: ThemeInput;
-    showLegend?: boolean;
-    showGrid?: boolean;
-    annotations?: Datum[];
-    title?: string | React.ReactNode;
-    description?: string;
-    background?: string;
-    className?: string;
-    legendPosition?: "right" | "left" | "top" | "bottom";
-    legendLayout?: LegendLayout;
-    /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
-    _idPrefix?: string;
-}
+import { type ThemeInput } from "./themeResolver";
+import { type RenderEvidence } from "./renderEvidence";
+import { type ThemeAwareProps, type StaticFrameProps, type FrameType } from "./staticSVGChrome";
 export declare function renderToStaticSVG(frameType: FrameType, props: StaticFrameProps): string;
 export declare function renderXYToStaticSVG(props: StreamXYFrameProps & ThemeAwareProps): string;
 export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps & ThemeAwareProps): string;

package/dist/components/server/serverChartConfigShared.d.ts

@@ -0,0 +1,21 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type FrameType = "xy" | "ordinal" | "network" | "geo" | "physics";
+export type ServerAccessorValue = string | number | boolean | Date | null | undefined;
+export type ServerAccessor = string | ((datum: Datum) => ServerAccessorValue);
+export type ServerColorScheme = string | string[] | Record<string, string> | undefined;
+export type ServerChartData = Datum | Datum[] | null | undefined;
+export interface ChartConfig {
+    frameType: FrameType;
+    /** Build frame props from HOC-level props */
+    buildProps: (data: ServerChartData, colorBy: ServerAccessor | undefined, colorScheme: ServerColorScheme, common: Datum, rest: Datum) => Datum;
+}
+export declare function accessorValue(accessor: ServerAccessor | undefined, fallback: string, d: Datum): ServerAccessorValue;
+export declare function numericValue(value: ServerAccessorValue): number;
+export declare function viridisColor(i: number, n: number): string;
+export declare function prepareConnectedScatterplotData(data: ServerChartData, rest: Datum): {
+    data: ServerChartData;
+    orderMap: WeakMap<Datum, {
+        idx: number;
+        total: number;
+    }>;
+};

package/dist/components/server/serverChartConfigs.d.ts

@@ -1,10 +1,9 @@
-import type { Datum } from "../charts/shared/datumTypes";
-type FrameType = "xy" | "ordinal" | "network" | "geo";
-interface ChartConfig {
-    frameType: FrameType;
-    /** Build frame props from HOC-level props */
-    buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => Datum;
-}
+/**
+ * Chart-specific prop mapping for renderChart().
+ *
+ * Family implementations live in serverChartConfigs{XY,Ordinal,Network,Geo,Custom,Physics}.ts.
+ */
+import type { ChartConfig } from "./serverChartConfigShared";
 export declare const CHART_CONFIGS: {
     Sparkline: ChartConfig;
     LineChart: ChartConfig;
@@ -15,20 +14,21 @@ export declare const CHART_CONFIGS: {
     CandlestickChart: ChartConfig;
     BubbleChart: {
         frameType: "xy";
-        buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => {
+        buildProps: (data: import("./serverChartConfigShared").ServerChartData, colorBy: import("./serverChartConfigShared").ServerAccessor | undefined, colorScheme: import("./serverChartConfigShared").ServerColorScheme, common: import("../stream/networkColorAccessors").Datum, rest: import("../stream/networkColorAccessors").Datum) => {
             chartType: string;
-            data: any;
+            data: import("./serverChartConfigShared").ServerChartData;
             xAccessor: any;
             yAccessor: any;
-            colorAccessor: any;
+            colorAccessor: import("./serverChartConfigShared").ServerAccessor | undefined;
             sizeAccessor: any;
             sizeRange: any;
-            colorScheme: any;
+            colorScheme: import("./serverChartConfigShared").ServerColorScheme;
         };
     };
     ConnectedScatterplot: ChartConfig;
     QuadrantChart: ChartConfig;
     Heatmap: ChartConfig;
+    XYCustomChart: ChartConfig;
     BarChart: ChartConfig;
     StackedBarChart: ChartConfig;
     GroupedBarChart: ChartConfig;
@@ -44,7 +44,9 @@ export declare const CHART_CONFIGS: {
     LikertChart: ChartConfig;
     FunnelChart: ChartConfig;
     GaugeChart: ChartConfig;
+    OrdinalCustomChart: ChartConfig;
     ForceDirectedGraph: ChartConfig;
+    NetworkCustomChart: ChartConfig;
     SankeyDiagram: ChartConfig;
     ProcessSankey: ChartConfig;
     ChordDiagram: ChartConfig;
@@ -54,5 +56,13 @@ export declare const CHART_CONFIGS: {
     ChoroplethMap: ChartConfig;
     ProportionalSymbolMap: ChartConfig;
     FlowMap: ChartConfig;
+    GeoCustomChart: ChartConfig;
+    GaltonBoardChart: ChartConfig;
+    EventDropChart: ChartConfig;
+    PhysicsPileChart: ChartConfig;
+    CollisionSwarmChart: ChartConfig;
+    ProcessFlowChart: ChartConfig;
+    GauntletChart: ChartConfig;
+    PhysicalFlowChart: ChartConfig;
+    PhysicsCustomChart: ChartConfig;
 };
-export {};

package/dist/components/server/serverChartConfigsCustom.d.ts

@@ -0,0 +1,5 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const xyCustomChart: ChartConfig;
+export declare const ordinalCustomChart: ChartConfig;
+export declare const networkCustomChart: ChartConfig;
+export declare const geoCustomChart: ChartConfig;

package/dist/components/server/serverChartConfigsGeo.d.ts

@@ -0,0 +1,9 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const choroplethMap: ChartConfig;
+export declare const proportionalSymbolMap: ChartConfig;
+/**
+ * FlowMap expands `flows` (edges with source/target ids) + `nodes` (points
+ * with coordinates) into the `lines` shape StreamGeoFrame expects, where
+ * each line carries a `coordinates` array of two {x,y} endpoints.
+ */
+export declare const flowMap: ChartConfig;

package/dist/components/server/serverChartConfigsNetwork.d.ts

@@ -0,0 +1,8 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const forceDirectedGraph: ChartConfig;
+export declare const processSankey: ChartConfig;
+export declare const sankeyDiagram: ChartConfig;
+export declare const chordDiagram: ChartConfig;
+export declare const treeDiagram: ChartConfig;
+export declare const treemap: ChartConfig;
+export declare const circlePack: ChartConfig;

package/dist/components/server/serverChartConfigsOrdinal.d.ts

@@ -0,0 +1,16 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const barChart: ChartConfig;
+export declare const stackedBarChart: ChartConfig;
+export declare const groupedBarChart: ChartConfig;
+export declare const pieChart: ChartConfig;
+export declare const donutChart: ChartConfig;
+export declare const histogram: ChartConfig;
+export declare const boxPlot: ChartConfig;
+export declare const violinPlot: ChartConfig;
+export declare const swarmPlot: ChartConfig;
+export declare const dotPlot: ChartConfig;
+export declare const swimlaneChart: ChartConfig;
+export declare const ridgelinePlot: ChartConfig;
+export declare const likertChart: ChartConfig;
+export declare const funnelChart: ChartConfig;
+export declare const gaugeChart: ChartConfig;

package/dist/components/server/serverChartConfigsPhysics.d.ts

@@ -0,0 +1,9 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const galtonBoardChart: ChartConfig;
+export declare const eventDropChart: ChartConfig;
+export declare const physicsPileChart: ChartConfig;
+export declare const collisionSwarmChart: ChartConfig;
+export declare const processFlowChart: ChartConfig;
+export declare const gauntletChart: ChartConfig;
+export declare const physicalFlowChart: ChartConfig;
+export declare const physicsCustomChart: ChartConfig;

package/dist/components/server/serverChartConfigsXY.d.ts

@@ -0,0 +1,11 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const sparkline: ChartConfig;
+export declare const lineChart: ChartConfig;
+export declare const areaChart: ChartConfig;
+export declare const differenceChart: ChartConfig;
+export declare const stackedAreaChart: ChartConfig;
+export declare const candlestickChart: ChartConfig;
+export declare const scatterplot: ChartConfig;
+export declare const quadrantChart: ChartConfig;
+export declare const connectedScatterplot: ChartConfig;
+export declare const heatmap: ChartConfig;

package/dist/components/server/staticAnnotations.d.ts

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Static annotation rendering for server-side SVG.
  *
@@ -9,8 +9,8 @@ import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 interface AnnotationScales {
-    x?: (v: any) => number;
-    y?: (v: any) => number;
+    x?: AnnotationScale;
+    y?: AnnotationScale;
     /** For ordinal charts: band scale */
     o?: {
         (v: string): number | undefined;
@@ -25,6 +25,9 @@ interface AnnotationScales {
      */
     geoProjection?: (coords: [number, number]) => [number, number] | null;
 }
+type AnnotationScale = {
+    bivarianceHack(value: DatumValue): number;
+}["bivarianceHack"];
 interface AnnotationLayout {
     width: number;
     height: number;

package/dist/components/server/staticGeo.d.ts

@@ -0,0 +1,4 @@
+import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function renderGeoFrame(props: StreamGeoFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticLegend.d.ts

@@ -26,7 +26,7 @@ export interface StaticLegendConfig {
     /** Category labels to show in legend */
     categories: string[];
     /** Color scheme — array of colors or d3-scale-chromatic name */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Theme for text/font colors */
     theme: SemioticTheme;
     /** Legend position */
@@ -71,5 +71,5 @@ export declare function renderStaticGradientLegend(config: StaticGradientLegendC
 /**
  * Extract unique categories from data using an accessor.
  */
-export declare function extractCategories(data: any[], accessor: string | ((d: Datum) => string) | undefined): string[];
+export declare function extractCategories(data: Datum[], accessor: string | ((d: Datum) => string) | undefined): string[];
 export {};

package/dist/components/server/staticNetwork.d.ts

@@ -0,0 +1,8 @@
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
+import type { NetworkPipelineConfig, RealtimeNode, RealtimeEdge, StreamNetworkFrameProps } from "../stream/networkTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function resolveAccessor(accessor: string | ((d: Datum) => DatumValue) | undefined, defaultKey: string): (d: Datum) => DatumValue;
+export declare function buildRealtimeNodes(propsNodes: Datum[], config: NetworkPipelineConfig): RealtimeNode[];
+export declare function buildRealtimeEdges(propsEdges: Datum[], config: NetworkPipelineConfig): RealtimeEdge[];
+export declare function renderNetworkFrame(props: StreamNetworkFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticOrdinal.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { OrdinalPipelineStore } from "../stream/OrdinalPipelineStore";
+import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { SemioticTheme } from "../store/ThemeStore";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function generateOrdinalAxesSVG(store: OrdinalPipelineStore, layout: {
+    width: number;
+    height: number;
+}, props: StreamOrdinalFrameProps, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export declare function renderOrdinalFrame(props: StreamOrdinalFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticPhysics.d.ts

@@ -0,0 +1,3 @@
+import { type EvidenceSink } from "./renderEvidence";
+import type { StaticPhysicsFrameProps } from "./staticSVGChrome";
+export declare function renderPhysicsFrame(props: StaticPhysicsFrameProps, sink?: EvidenceSink): string;

package/dist/components/server/staticSVGChrome.d.ts

@@ -0,0 +1,110 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { LegendLayout } from "../types/legendTypes";
+import type { StreamXYFrameProps, StreamScales, StreamLayout } from "../stream/types";
+import type { StreamNetworkFrameProps, RealtimeEdge } from "../stream/networkTypes";
+import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
+import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import type { PhysicsSettledSVGOptions } from "../stream/physics/PhysicsSettledSVG";
+import type { PhysicsPipelineStore, PhysicsQueuedSpawn } from "../stream/physics/PhysicsPipelineStore";
+import type { OrdinalPipelineStore } from "../stream/OrdinalPipelineStore";
+import type { RenderEvidence } from "./renderEvidence";
+import { resolveTheme, type ThemeInput } from "./themeResolver";
+import type { SemioticTheme } from "../store/ThemeStore";
+import * as React from "react";
+export type FrameType = RenderEvidence["frameType"];
+export type StaticPhysicsFrameProps = PhysicsSettledSVGOptions & {
+    config?: ConstructorParameters<typeof PhysicsPipelineStore>[0];
+    initialSpawns?: PhysicsQueuedSpawn[];
+    projectionRows?: PhysicsSettledSVGOptions["projectionRows"];
+    size?: [number, number];
+    _idPrefix?: string;
+};
+export type StaticFrameProps = (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps | StaticPhysicsFrameProps) & ThemeAwareProps;
+export type CategoricalAccessor = string | ((d: Datum) => string);
+type EdgeEndpoint = RealtimeEdge["source"] | RealtimeEdge["target"] | null | undefined;
+export declare function edgeEndpointId(endpoint: EdgeEndpoint): string | null;
+/** Generate a short stable ID from chart props for unique SVG element IDs */
+export declare function chartUID(props: Datum): string;
+export interface ThemeAwareProps {
+    theme?: ThemeInput;
+    showLegend?: boolean;
+    showGrid?: boolean;
+    annotations?: Datum[];
+    title?: string | React.ReactNode;
+    description?: string;
+    background?: string;
+    className?: string;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
+    /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
+    _idPrefix?: string;
+}
+export declare function reserveStaticLegendMargin(margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, options: {
+    categories: string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+}): void;
+export declare function reserveLegendConfigMargin(margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, options: {
+    legend: unknown;
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+}): void;
+export declare function renderLegendConfig(legend: unknown, options: {
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+    idPrefix?: string;
+}): React.ReactNode;
+export declare function defaultTickFormat(v: number): string;
+/** Render grid lines for XY charts */
+export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+/** Render grid lines for ordinal charts */
+export declare function renderOrdinalGridSVG(store: OrdinalPipelineStore, layout: {
+    width: number;
+    height: number;
+}, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+/** Wrap SVG content with accessibility attributes */
+export declare function wrapSVG(content: React.ReactNode, opts: {
+    width: number;
+    height: number;
+    className: string;
+    title?: string | React.ReactNode;
+    description?: string;
+    background?: string;
+    theme: SemioticTheme;
+    innerTransform: string;
+    innerWidth: number;
+    innerHeight: number;
+    legend?: React.ReactNode;
+    outerElements?: React.ReactNode;
+    defs?: React.ReactNode;
+    /** Prefix for SVG element IDs to avoid collisions in multi-chart documents */
+    idPrefix?: string;
+}): React.ReactElement;
+export declare function generateAxesSVG(scales: StreamScales, layout: StreamLayout, props: StreamXYFrameProps, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export {};

package/dist/components/server/staticXY.d.ts

@@ -0,0 +1,4 @@
+import type { StreamXYFrameProps } from "../stream/types";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function renderStreamXYFrame(props: StreamXYFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

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

@@ -1,9 +1,13 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import type { ControlObservation } from "../controls/controlContract";
+export type { ControlObservation } from "../controls/controlContract";
 interface ObservationBase {
     timestamp: number;
     chartType: string;
     chartId?: string;
 }
+/** Input channel that produced a semantic chart interaction. */
+export type ObservationInputType = "keyboard" | "pointer" | "touch" | "navigation-tree";
 export interface HoverObservation extends ObservationBase {
     type: "hover";
     datum: Datum;
@@ -45,6 +49,24 @@ export interface ClickObservation extends ObservationBase {
 export interface ClickEndObservation extends ObservationBase {
     type: "click-end";
 }
+/** A datum became the reader's active focus target. */
+export interface FocusObservation extends ObservationBase {
+    type: "focus";
+    datum: Datum;
+    inputType: Exclude<ObservationInputType, "touch">;
+}
+/** A datum was deliberately activated, independent of input modality. */
+export interface ActivateObservation extends ObservationBase {
+    type: "activate";
+    datum: Datum;
+    inputType: ObservationInputType;
+}
+/** A stable, interactive annotation was deliberately activated. */
+export interface AnnotationActivateObservation extends ObservationBase {
+    type: "annotation-activate";
+    annotationId: string;
+    inputType: ObservationInputType;
+}
 /**
  * Emitted when an event-time stream receives a record outside its
  * lateness/grace window (see `ReorderBuffer`). Surfaces lateness as an
@@ -64,7 +86,7 @@ export interface LateDataObservation extends ObservationBase {
     /** 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 ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | FocusObservation | ActivateObservation | AnnotationActivateObservation | ControlObservation | LateDataObservation;
 export type OnObservationCallback = (observation: ChartObservation) => void;
 export interface ObservationStoreState {
     /** Ring buffer of recent observations (newest last). Mutated in place for perf. */
@@ -76,4 +98,3 @@ export interface ObservationStoreState {
     clearObservations: () => void;
 }
 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/themeSerialization.d.ts

@@ -0,0 +1,32 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemioticTheme } from "./ThemeStore";
+/**
+ * Convert a SemioticTheme to a CSS custom properties string.
+ * Useful for SSR or generating stylesheet content.
+ *
+ * @param theme - A SemioticTheme object
+ * @param selector - CSS selector to scope the variables (default: `:root`)
+ * @returns CSS string with custom properties
+ *
+ * @example
+ * ```ts
+ * const css = themeToCSS(TUFTE_LIGHT, ".my-charts")
+ * // .my-charts {
+ * //   --semiotic-bg: #fffff8;
+ * //   --semiotic-text: #111111;
+ * //   ...
+ * // }
+ * ```
+ */
+export declare function themeToCSS(theme: SemioticTheme, selector?: string): string;
+/**
+ * Convert a SemioticTheme to a design tokens JSON object.
+ * Compatible with Style Dictionary / Design Token Community Group format.
+ *
+ * @example
+ * ```ts
+ * const tokens = themeToTokens(TUFTE_LIGHT)
+ * // { semiotic: { bg: { $value: "#fffff8", $type: "color" }, ... } }
+ * ```
+ */
+export declare function themeToTokens(theme: SemioticTheme): Datum;

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

@@ -2,6 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 import { type DataSummary } from "../data/DataSummarizer";
 import type { ChartDataProfile, Suggestion } from "../ai/chartCapabilityTypes";
 import type { IntentId } from "../ai/intents";
+import { type ChartReaderGrounding, type ChartReaderGroundingOptions } from "../ai/readerGrounding";
 /**
  * Identifies a single point of interest on the chart — typically the datum
  * the user is currently hovering, clicked, or otherwise focused on. When
@@ -31,6 +32,8 @@ export interface InterrogationContext {
     componentName?: string;
     /** Optional caller-supplied chart props (accessor names, scales, etc.). */
     props?: Record<string, unknown>;
+    /** Optional reader-grounding payload for faithful chart interpretation. */
+    grounding?: ChartReaderGrounding;
     /**
      * The current focused datum — what the user is interactively pointing at.
      * Lets the LLM tailor responses to a specific point ("why is *this* one
@@ -82,6 +85,12 @@ export interface UseChartInterrogationOptions {
      * `onObservation` callback or the convenience `useChartFocus` hook.
      */
     focus?: InterrogationFocus | null;
+    /**
+     * Include `buildReaderGrounding()` in the interrogation context. Pass true
+     * for default grounding, or an options object for capability/audience,
+     * structure, and physics runtime grounding controls.
+     */
+    includeGrounding?: boolean | ChartReaderGroundingOptions;
 }
 export interface UseChartInterrogationResult {
     /** Ask a question. Updates history, annotations, loading, and error. */