semiotic 3.8.0 → 3.8.2

package/dist/components/charts/physics/PhysicalFlowChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
+import type { StyleRule } from "../shared/styleRules";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type PhysicalFlowCoordinateMode, type PhysicalFlowPathConstraint, type PhysicalFlowRawPath } from "./physicsChartUtils";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
@@ -28,6 +29,12 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
     showNodeLabels?: boolean;
     showSensors?: boolean;
     colorBy?: ChartAccessor<TLink, string>;
+    /**
+     * Declarative, threshold-aware particle styling. Ordered `{ when, style }`
+     * rules layer over the `colorBy` fill; last applicable rule wins. `ctx` =
+     * `{ value, category }`, where value is throughput and category is colorBy.
+     */
+    styleRules?: StyleRule[];
     seed?: number;
     tooltip?: TooltipProp;
     paused?: boolean;

package/dist/components/charts/physics/PhysicsCustomChart.d.ts

@@ -1,16 +1,17 @@
 import * as React from "react";
 import type { ReactNode } from "react";
-import { type ScaleLinear } from "d3-scale";
+import type { ScaleLinear } from "d3-scale";
 import type { ThemeSemanticColors } from "../../stream/types";
 import { type PhysicsSemanticItem, type StreamPhysicsBodyForce, type StreamPhysicsFrameProps, type StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsFrame";
 import type { PhysicsController } from "../../stream/physics/PhysicsControllers";
-import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsPipelineStore, PhysicsPipelineConfig, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
 import type { PhysicsColliderSpec, PhysicsSpringSpec } from "../../stream/physics/PhysicsKernel";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
-import { type PhysicsChartArea } from "./physicsChartUtils";
+import type { PhysicsChartArea } from "./physicsChartUtils";
 import { type PhysicsDatumSpawnResult, type PhysicsFrameHandle } from "./physicsHocHandle";
 import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export { resolveCustomLayout } from "./physicsCustomLayout";
 export interface PhysicsCustomLayoutContext<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
     data: TDatum[];
     scales: {
@@ -91,28 +92,6 @@ export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig e
      */
     frameProps?: PhysicsHocFrameProps<"config">;
 }
-interface ResolvedPhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
-    config: PhysicsPipelineConfig;
-    context: PhysicsCustomLayoutContext<TDatum, TConfig>;
-    initialSpawnPacing?: PhysicsSpawnPacingOptions;
-    initialSpawns: PhysicsQueuedSpawn[];
-    result: PhysicsCustomLayoutResult;
-}
-export declare function resolveCustomLayout<TDatum extends Datum, TConfig extends object>(options: {
-    chartId?: string;
-    colorScheme?: string | string[] | Record<string, string>;
-    config?: PhysicsPipelineConfig;
-    data: TDatum[];
-    layout: PhysicsCustomLayout<TDatum, TConfig>;
-    layoutConfig?: TConfig;
-    onObservation?: BaseChartProps["onObservation"];
-    semantic: ThemeSemanticColors;
-    skipLayout?: boolean;
-    size: [number, number];
-    themeCategorical: string[];
-    xExtent?: [number, number];
-    yExtent?: [number, number];
-}): ResolvedPhysicsCustomLayout<TDatum, TConfig>;
 export declare const PhysicsCustomChart: {
     <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: PhysicsCustomChartProps<TDatum, TConfig> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/physics/PhysicsPileChart.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor, ChartMode } from "../shared/types";
+import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
 import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
 export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
@@ -19,6 +20,12 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
     unitValue?: number;
     ballRadius?: number;
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware body styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. `ctx` = `{ value, category }`. A rule
+     * `fill` may be a color or a HatchFill. Layers over the colorBy-derived fill.
+     */
+    styleRules?: StyleRule[];
     seed?: number;
     showProjection?: boolean;
     sediment?: boolean;

package/dist/components/charts/physics/physicsChartShared.d.ts

@@ -1,6 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
 import type { ChartAccessor } from "../shared/types";
 import type { Style } from "../../stream/types";
+import { type StyleRule } from "../shared/styleRules";
 import type { PhysicsColliderSpec } from "../../stream/physics/PhysicsKernel";
 import type { PhysicsPipelineConfig, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
 import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsTypes";
@@ -27,7 +28,22 @@ export interface PhysicsChartArea {
 }
 export declare function physicsChartArea(size: [number, number]): PhysicsChartArea;
 export declare function hashStringColor(value: unknown): string;
-export declare function styleFromColorAccessor<TDatum extends Datum>(colorBy: ChartAccessor<TDatum, string> | undefined, fallback?: string): (body: {
+export interface PhysicsStyleRuleOptions {
+    /** Declarative style rules, merged on top of the colorBy-derived body fill. */
+    styleRules?: ReadonlyArray<StyleRule>;
+    /** Numeric field/accessor a threshold rule compares against (defaults to `value`). */
+    valueAccessor?: string | ((d: Datum) => unknown);
+}
+/**
+ * Build a per-body `bodyStyle` from a `colorBy` accessor. When `styleRules`
+ * are supplied, the merged rule style layers on top of the colorBy-derived
+ * fill (last-applicable rule wins) — the physics counterpart to the ordinal
+ * bar `styleRules`. Rules resolve against the body's original `datum`; `ctx` =
+ * `{ value, category }` where `category` is the colorBy group. Because every
+ * colorBy-driven physics HOC and its SSR config funnel through this helper,
+ * one call wires rules for all of them.
+ */
+export declare function styleFromColorAccessor<TDatum extends Datum>(colorBy: ChartAccessor<TDatum, string> | undefined, fallback?: string, opts?: PhysicsStyleRuleOptions): (body: {
     datum?: unknown;
 }) => Style;
 export declare function baseConfig(seed: number, colliders: PhysicsColliderSpec[], chartType: string, kernel?: Partial<NonNullable<PhysicsPipelineConfig["kernel"]>>): PhysicsPipelineConfig;

package/dist/components/charts/physics/physicsCustomLayout.d.ts

@@ -0,0 +1,32 @@
+import type { ThemeSemanticColors } from "../../stream/types";
+import { type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps } from "../shared/types";
+import type { PhysicsCustomLayout, PhysicsCustomLayoutContext, PhysicsCustomLayoutResult } from "./PhysicsCustomChart";
+interface ResolvedPhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    config: PhysicsPipelineConfig;
+    context: PhysicsCustomLayoutContext<TDatum, TConfig>;
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    initialSpawns: PhysicsQueuedSpawn[];
+    result: PhysicsCustomLayoutResult;
+}
+/**
+ * Resolve the pure PhysicsCustomChart layout contract without importing the
+ * React HOC. Shared by the component and the static server renderer.
+ */
+export declare function resolveCustomLayout<TDatum extends Datum, TConfig extends object>(options: {
+    chartId?: string;
+    colorScheme?: string | string[] | Record<string, string>;
+    config?: PhysicsPipelineConfig;
+    data: TDatum[];
+    layout: PhysicsCustomLayout<TDatum, TConfig>;
+    layoutConfig?: TConfig;
+    onObservation?: BaseChartProps["onObservation"];
+    semantic: ThemeSemanticColors;
+    skipLayout?: boolean;
+    size: [number, number];
+    themeCategorical: string[];
+    xExtent?: [number, number];
+    yExtent?: [number, number];
+}): ResolvedPhysicsCustomLayout<TDatum, TConfig>;
+export {};

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

@@ -0,0 +1,88 @@
+/**
+ * `<AnnotationLabel>` — the single, shared renderer for the text label of a
+ * region-bounding annotation (threshold lines, bands, enclosures, category
+ * highlights) across every frame and the server SSR path.
+ *
+ * Two problems it solves:
+ *   1. **Legibility.** A label sitting over dense marks needs a backdrop to
+ *      stay readable. Historically the region rules hand-rolled a
+ *      `paint-order: stroke` white "halo" inline — and only some of them, and
+ *      the client and server disagreed (client `y-threshold` had a halo, the
+ *      server's didn't). This component makes the halo a first-class,
+ *      consistent option and adds a genuine semitransparent **box** backdrop
+ *      (the rounded panel behind a label like "Fast-scaling · 10").
+ *   2. **Duplication.** Client (`annotationRules.tsx`) and server
+ *      (`staticAnnotations.tsx`) both emit label `<text>`; routing both through
+ *      one component removes the drift.
+ *
+ * `background` is the knob:
+ *   - `"halo"` / `true` — a stroke halo (default for region annotations; matches
+ *      the legacy look byte-for-byte when `haloColor`/`haloWidth` are unset)
+ *   - `"box"` — a filled, optionally-semitransparent rounded rect behind the text
+ *   - `"none"` / `false` — plain text
+ *   - a config object — fine-grained control over either treatment
+ *
+ * The box's geometry is derived from an *estimated* text width (SVG can't
+ * measure text without a live DOM, and the server path has none), which is
+ * accurate enough for a padded backdrop and identical on both backends.
+ */
+import * as React from "react";
+export interface AnnotationLabelBackgroundConfig {
+    /** Backdrop treatment. @default "halo" */
+    type?: "halo" | "box";
+    /**
+     * Backdrop paint. For `"halo"` it is the outline color (defaults to the
+     * plot background so the halo "erases" marks under the text). For `"box"`
+     * it is the panel fill.
+     * @default "var(--semiotic-bg, #ffffff)"
+     */
+    fill?: string;
+    /** Box fill opacity (box mode only). @default 0.85 */
+    opacity?: number;
+    /** Box inner padding in px — number (uniform) or `{x,y}`. @default {x:6,y:3} */
+    padding?: number | {
+        x: number;
+        y: number;
+    };
+    /** Box corner radius in px. @default 3 */
+    radius?: number;
+    /** Box border color (box mode only). */
+    stroke?: string;
+    /** Box border width in px. @default 0 */
+    strokeWidth?: number;
+    /** Halo stroke width in px (halo mode only). @default 3 */
+    haloWidth?: number;
+}
+export type AnnotationLabelBackground = boolean | "halo" | "box" | "none" | AnnotationLabelBackgroundConfig;
+export interface AnnotationLabelProps {
+    x: number;
+    y: number;
+    text: string | number;
+    /** Text color. */
+    fill: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    fontFamily?: string;
+    textAnchor?: "start" | "middle" | "end";
+    dominantBaseline?: React.SVGAttributes<SVGTextElement>["dominantBaseline"];
+    /**
+     * Backdrop treatment. Defaults to `"halo"` (the legacy region-label look).
+     * Pass `"box"` for a semitransparent panel, `"none"` for plain text, or a
+     * config object for fine control.
+     */
+    background?: AnnotationLabelBackground;
+    className?: string;
+}
+/**
+ * Rough width of a rendered label. SVG offers no synchronous text metrics
+ * (and the server has no DOM at all), so we estimate from character count.
+ * ~0.6em per glyph is a reasonable average for the sans-serif UI faces this
+ * library ships; the box carries padding, so a small error is invisible.
+ */
+export declare function estimateLabelWidth(text: string | number, fontSize: number): number;
+/**
+ * Render an annotation's text label with an optional legibility backdrop.
+ * Emits a bare `<text>` (halo/none) or a `<g>` with a backing `<rect>` + text
+ * (box). Safe on both the client SVG overlay and the server static SVG path.
+ */
+export declare function AnnotationLabel(props: AnnotationLabelProps): React.ReactElement;

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

@@ -0,0 +1,35 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+export type ChartAnnotation = Datum;
+export interface AnnotationActivationEvent {
+    annotation: ChartAnnotation;
+    annotationId?: string;
+    chartId?: string;
+    inputType: ObservationInputType;
+}
+export type OnAnnotationActivateCallback = (event: AnnotationActivationEvent) => void;
+export interface AnnotationActivationOptions {
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
+}
+/** Route annotation activation to both a direct callback and the observation store. */
+export declare function useAnnotationActivationOptions(options: AnnotationActivationOptions): AnnotationActivationOptions;
+/**
+ * Resolve a durable annotation identity without ever falling back to array
+ * position. Provenance stable IDs are accepted for agent-authored notes.
+ */
+export declare function annotationStableId(annotation: ChartAnnotation): string | undefined;
+/**
+ * Event props for a widget's existing HTML boundary. Capture phase observes
+ * arbitrary descendant controls without replacing their behavior or adding a
+ * nested interactive element.
+ */
+export declare function annotationActivationProps(annotation: ChartAnnotation, options?: AnnotationActivationOptions): React.HTMLAttributes<HTMLDivElement> & {
+    "data-semiotic-annotation-id"?: string;
+    "data-semiotic-annotation-widget": "";
+};
+/** True when a bubbled frame click originated inside a widget annotation. */
+export declare function isAnnotationActivationTarget(target: EventTarget | null): boolean;

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

@@ -0,0 +1,5 @@
+export declare const TOP_LABEL_BASELINE = 16;
+/** Keep a horizontal-threshold label inside the plot when its rule is near the top. */
+export declare function thresholdLabelY(y: number, height: number): number;
+/** Place a horizontal-band label just inside its visible top edge. */
+export declare function bandLabelY(y0: number, y1: number): number;

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+import { type AnnotationActivationOptions } from "./annotationActivation";
 export { applyAnnotationEmphasis, type AnnotationRenderPair } from "./annotationHierarchy";
 type AnnotationRule = (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
 /**
@@ -17,4 +18,4 @@ type AnnotationRule = (annotation: Datum, index: number, context: AnnotationCont
  * through to the default rule, preserving the existing override contract.
  */
 export declare function renderAnnotationPass(annotations: ReadonlyArray<Datum>, defaultRule: AnnotationRule, userRule: AnnotationRule | undefined, context: AnnotationContext): React.ReactNode[];
-export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
+export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network", activation?: AnnotationActivationOptions): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;

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

@@ -0,0 +1,13 @@
+import type { A11yFinding } from "./auditAccessibility";
+import type { Datum } from "./datumTypes";
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Only declared chart props can be credited as rendered accessibility text.
+ * This keeps the audit aligned with the generated prop schema and validation.
+ */
+export declare function assessAccessibilityText(component: string, props: Datum): {
+    hasTitle: boolean;
+    hasDescription: boolean;
+    hasSummary: boolean;
+    unsupportedFinding: A11yFinding | undefined;
+};

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

@@ -0,0 +1,4 @@
+import type { Datum } from "./datumTypes";
+export declare function resolveHoverXPosition(interactionDatum: Datum, datum: Datum | null | undefined, xField: string): number | null;
+export declare function observationDatum(interactionDatum: Datum): Datum;
+export declare function hasOwnEnumerableKey(value: object | undefined | null): boolean;

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

@@ -6,9 +6,9 @@
  *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
  *   - `ai/componentMetadata.cjs`                          (category buckets)
  *
- * Today, `validationMap.ts` is derived directly from this registry, and
- * `ai/schema.json` is generated from it — run `npm run docs:chart-specs:schema`
- * to refresh the schema after editing a spec. `componentMetadata.cjs` is still
+ * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * this registry — run `npm run docs:chart-specs:schema` to refresh both after
+ * editing a spec. `componentMetadata.cjs` is still
  * hand-edited but gated for parity by the registry: `check:chart-specs` (run
  * via `npm run check:chart-specs`) regenerates each chart's schema/
  * validation/metadata entries with the pure functions in

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

@@ -18,3 +18,5 @@
  * reason" referenced by the lint policy for `@typescript-eslint/no-explicit-any`.
  */
 export type Datum = Record<string, any>;
+/** Values that can be returned by a chart accessor or stored in a datum field. */
+export type DatumValue = string | number | boolean | Date | Datum | Datum[] | null | undefined;

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

@@ -1,4 +1,6 @@
 import type { Datum } from "./datumTypes";
 import type { Diagnosis } from "./diagnoseTypes";
+/** Interactive widgets need durable identity for replay and normalized events. */
+export declare function checkInteractiveAnnotationIds(_component: string, props: Datum, out: Diagnosis[]): void;
 export declare function checkAnnotationConnectors(_component: string, props: Datum, out: Diagnosis[]): void;
 export declare function checkAnnotationDensity(_component: string, props: Datum, out: Diagnosis[]): void;

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

@@ -58,7 +58,7 @@ export declare function formatAxis(type?: "number" | "date" | "percent" | "curre
  * )
  * ```
  */
-export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
+export declare function createTooltip(fields: string[], formatters?: Record<string, (value: string | number | Date) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
 /**
  * Formats large numbers with K/M/B suffixes
  *
@@ -85,7 +85,7 @@ export declare function formatLargeNumber(value: number, decimals?: number): str
  *
  * Used as the default axis tickFormat when no explicit format is provided.
  */
-export declare function smartTickFormat(value: any): string;
+export declare function smartTickFormat(value: string | number | Date | null | undefined): string;
 type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "years";
 /**
  * Creates a hierarchical time axis formatter.
@@ -112,7 +112,7 @@ type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "ye
  * <LineChart data={ts} xFormat={adaptiveTimeTicks("minutes")} />
  * ```
  */
-export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: any, index?: number, allTicks?: number[]) => string;
+export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: string | number | Date, index?: number, allTicks?: number[]) => string;
 /**
  * Truncates text to specified length with ellipsis
  *

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

@@ -0,0 +1,87 @@
+/**
+ * Declarative hatch-fill descriptor — a single value that renders as a
+ * diagonal-line pattern on BOTH rendering backends.
+ *
+ * The library historically had two disjoint hatch primitives: a canvas
+ * `createHatchPattern` (→ `CanvasPattern`) and an SVG `<pattern>` builder
+ * (`hatchFill` recipe / `createSVGHatchPattern`). A caller had to know
+ * which medium they were painting into and hand-produce the right thing —
+ * which is why a `CanvasPattern` returned from a `pieceStyle` silently
+ * collapses to a solid color in SSR (`svgFill` drops non-string fills).
+ *
+ * `HatchFill` closes that gap: it is a plain, serializable descriptor that
+ * can be set directly as `style.fill`. The canvas renderer resolves it to a
+ * `CanvasPattern` (`resolveHatchCanvasPattern`); the SVG serializer resolves
+ * it to a `<pattern>` def + `url(#id)` (`hatchPatternDef` / `hatchFillId`).
+ * One declaration, both mediums — so a bar hatched via a style rule looks
+ * identical whether it is drawn to canvas in the browser or serialized to
+ * SVG on the server.
+ *
+ * @example
+ * ```tsx
+ * <BarChart
+ *   styleRules={[
+ *     { when: { gt: 10 }, style: { fill: { type: "hatch", background: "#ffd166", stroke: "#e0a92a" } } },
+ *   ]}
+ * />
+ * ```
+ */
+import * as React from "react";
+/**
+ * A declarative diagonal-hatch fill. Assign it anywhere a `style.fill`
+ * is accepted (`pieceStyle`, `styleRules`, annotation region `fill`).
+ * Backend-agnostic: resolved to a `CanvasPattern` for canvas and an SVG
+ * `<pattern>` for SSR / the SVG overlay.
+ */
+export interface HatchFill {
+    /** Discriminator — marks this fill as a hatch descriptor. */
+    type: "hatch";
+    /** Tile background color painted under the lines. @default "transparent" */
+    background?: string;
+    /** Color of the diagonal lines. @default "#000" */
+    stroke?: string;
+    /** Width of the diagonal lines in px. @default 1.5 */
+    lineWidth?: number;
+    /** Spacing between lines in px. @default 6 */
+    spacing?: number;
+    /** Angle of the lines in degrees (0 = horizontal, 45 = diagonal). @default 45 */
+    angle?: number;
+    /** Opacity applied to the hatch lines (SVG `<line>` stroke opacity). @default 1 */
+    lineOpacity?: number;
+}
+/** Type guard — is a resolved `style.fill` a `HatchFill` descriptor? */
+export declare function isHatchFill(fill: unknown): fill is HatchFill;
+/**
+ * Stable, content-derived key for a hatch descriptor. Used to cache canvas
+ * patterns and to mint deterministic SVG `<pattern>` ids so identical
+ * descriptors dedupe rather than proliferate.
+ */
+export declare function hatchFillKey(h: HatchFill): string;
+/** Deterministic, SVG-id-safe identifier for a hatch descriptor. */
+export declare function hatchFillId(prefix: string, h: HatchFill): string;
+/**
+ * Resolve a `HatchFill` descriptor to a `CanvasPattern` for the given
+ * context. Cached by descriptor content + DPR. Returns `null` only when
+ * the environment can't create a pattern (SSR/test) — callers fall back
+ * to the descriptor's `background` color.
+ */
+export declare function resolveHatchCanvasPattern(h: HatchFill, ctx: CanvasRenderingContext2D): CanvasPattern | null;
+/**
+ * Render a `HatchFill` descriptor as an SVG `<pattern>` element.
+ * Place the returned element inside `<defs>` (or anywhere valid) and set
+ * `fill="url(#id)"` on the target shape. Mirrors the canvas tile exactly:
+ * parallel lines rotated by `angle` so the two backends read identically.
+ */
+export declare function hatchPatternDef(h: HatchFill, id: string): React.ReactElement;
+/**
+ * Resolve a `style.fill` for an SVG shape. Returns the paint string to use
+ * plus, when the fill is a `HatchFill`, the `<pattern>` def to inject.
+ *
+ * @param fill    the raw `style.fill` (string color, `HatchFill`, or `CanvasPattern`)
+ * @param idBase  prefix for the generated pattern id (should be node-unique-ish)
+ * @param fallback solid color used when `fill` is null/undefined or a raw CanvasPattern
+ */
+export declare function resolveSvgFill(fill: string | HatchFill | CanvasPattern | null | undefined, idBase: string, fallback?: string): {
+    fill: string;
+    def?: React.ReactElement;
+};

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

@@ -7,6 +7,7 @@ import type { TransitionConfig } from "../../stream/types";
 import type { Datum } from "./datumTypes";
 import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { ResponsiveRule } from "./responsiveRules";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "./semanticInteractions";
 /**
  * Default fill color used when no colorBy is specified
  */
@@ -46,13 +47,13 @@ export declare function resolveDefaultFill(color: string | undefined, themeCateg
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
  */
-export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
+export declare function resolveAccessor<T = string | number | boolean | Date | Datum | null | undefined>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
 /**
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or data is empty (push API mode).
  * Supports both string and function accessors for colorBy.
  */
-export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Datum>, colorBy: string | ((d: Datum, i?: number) => string | number) | undefined, colorScheme?: string | string[] | Record<string, string>): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -83,7 +84,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     onObservation?: OnObservationCallback;
     chartType?: string;
     chartId?: string;
-    onClick?: (datum: any, event: {
+    onClick?: (datum: Datum, event: {
         x: number;
         y: number;
     }) => void;
@@ -93,8 +94,8 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
-    customHoverBehavior: (d: Datum | null) => void;
-    customClickBehavior: (d: Datum | null) => void;
+    customHoverBehavior: SemanticHoverBehavior;
+    customClickBehavior: SemanticClickBehavior;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
     crosshairSourceId: string;
 };
@@ -172,7 +173,7 @@ interface ChartModeInput {
     categoryLabel?: string;
     valueLabel?: string;
     /** When truthy, enableHover is forced true regardless of mode (LinkedCharts needs hover) */
-    linkedHover?: any;
+    linkedHover?: LinkedHoverProp;
     /** Optional mobile interaction policy surfaced through useChartMode for custom wrappers. */
     mobileInteraction?: MobileInteractionProp;
     /** Optional mobile semantic contract surfaced through useChartMode for custom wrappers. */

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

@@ -0,0 +1,9 @@
+/**
+ * AUTO-GENERATED from chartSpecs.ts by scripts/regenerate-schema.ts.
+ * Do not edit by hand; run `npm run docs:chart-specs:schema`.
+ *
+ * This compact registry is intentionally separate from validation metadata:
+ * config serialization only needs chart-name membership.
+ */
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare function isKnownChartComponent(componentName: string): boolean;

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

@@ -0,0 +1,16 @@
+export type RegressionPoint = [number, number];
+export interface LeastSquaresResult {
+    points: RegressionPoint[];
+    /**
+     * Linear: `[slope, intercept]`. Polynomial: highest power first, matching
+     * the historical `regression` package result consumed by annotations.
+     */
+    equation: number[];
+}
+/** Fit a two-parameter least-squares line with two-decimal output rounding. */
+export declare function linearRegression(data: ReadonlyArray<readonly [number, number | null]>): LeastSquaresResult;
+/**
+ * Fit an order-N polynomial using normal equations. Coefficients and predicted
+ * points use the former dependency's two-decimal rounding and equation order.
+ */
+export declare function polynomialRegression(data: ReadonlyArray<readonly [number, number | null]>, order?: number): LeastSquaresResult;

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

@@ -27,7 +27,8 @@ export interface PrimitiveStyleOverrides {
     strokeWidth?: number;
     opacity?: number;
 }
-type StyleFnArg = (...args: any[]) => Datum;
+type StyleArgument = Datum | string | number | boolean | Date | null | undefined;
+type StyleFn<TArgs extends StyleArgument[]> = (...args: TArgs) => Datum;
 /** Returns true when at least one override key has a non-undefined value. */
 export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides): boolean;
 /**
@@ -39,5 +40,5 @@ export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides
  * keeps the memoization-stable identity path hot for the common case
  * where a designer has set nothing.
  */
-export declare function mergeShapeStyle<F extends StyleFnArg>(styleFn: F | undefined, overrides: PrimitiveStyleOverrides): F;
+export declare function mergeShapeStyle<TArgs extends StyleArgument[] = []>(styleFn: StyleFn<TArgs> | undefined, overrides: PrimitiveStyleOverrides): StyleFn<TArgs>;
 export {};

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

@@ -0,0 +1,42 @@
+import type { Datum } from "./datumTypes";
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+/** Extra context supplied by Stream Frames to their existing behavior hooks. */
+export interface SemanticInteractionContext {
+    type: "focus" | "activate";
+    inputType: ObservationInputType;
+}
+export type SemanticHoverBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export type SemanticClickBehavior<T = Datum> = (datum: T | null, context?: SemanticInteractionContext) => void;
+export declare function observationInputType(pointerType?: string): "pointer" | "touch";
+/**
+ * Stream Frame keyboard navigation lives on a focusable chart wrapper. Let
+ * native controls rendered inside that wrapper (notably widget annotations)
+ * handle their own keys before the chart consumes Enter, Space, or arrows.
+ */
+export declare function isInteractiveKeyboardTarget(event: Pick<ReactKeyboardEvent, "target" | "currentTarget">): boolean;
+/**
+ * Emit the legacy hover event and its semantic focus companion when present.
+ * Keeping both makes the semantic vocabulary additive for existing consumers.
+ */
+export declare function emitHoverObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;
+/** Emit the legacy click event and its semantic activation companion. */
+export declare function emitClickObservations(options: {
+    onObservation?: OnObservationCallback;
+    datum: Datum | null;
+    x?: number;
+    y?: number;
+    chartType: string;
+    chartId?: string;
+    context?: SemanticInteractionContext;
+    timestamp?: number;
+}): void;

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

@@ -24,4 +24,4 @@
  * mutation throws in strict mode rather than corrupting later reads.
  */
 export declare const EMPTY_ARRAY: readonly unknown[];
-export declare function filterSparseArray<T>(input: readonly T[] | undefined | null): T[];
+export declare function filterSparseArray<T extends object>(input: readonly (T | null | undefined)[] | undefined | null): T[];