semiotic 3.8.0 → 3.8.1

package/dist/components/charts/geo/ChoroplethMap.d.ts

@@ -4,6 +4,7 @@ import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes"
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 import { type AreasProp } from "../../geo/useReferenceAreas";
 /**
  * ChoroplethMap component props
@@ -33,6 +34,17 @@ export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseCh
     valueAccessor: ChartAccessor<TDatum, number>;
     /** Sequential color scheme @default "blues" */
     colorScheme?: string;
+    /**
+     * Declarative, threshold-aware feature styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins per property. `when` accepts a predicate
+     * `(feature, ctx) => boolean` (`ctx.value` is the feature's `valueAccessor`
+     * value; rules see the feature with its `properties` flattened, so
+     * `{ field: "iso", eq: "USA" }` works), a declarative threshold
+     * (`{ gt, gte, within, in, … }`), or `true`. A rule's `fill` may be a color
+     * or a HatchFill (hatch flags a feature — e.g. "no data" / "under review").
+     * Layers over the sequential-scale base fill.
+     */
+    styleRules?: StyleRule[];
     /** Geographic projection @default "equalEarth" */
     projection?: ProjectionProp;
     /** Show graticule grid lines */
@@ -43,8 +55,13 @@ export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseCh
     showLegend?: boolean;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Finite projection-fit fraction in `[0, 0.5)`. `0.1` = 10% inset;
+     * nullish values use 0 and invalid values throw. An explicit
+     * `frameProps.projectionExtent` remains authoritative.
+     * @default 0
+     */
+    fitPadding?: number | null;
     /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
     zoomable?: boolean;
     /** [minZoom, maxZoom] @default [1, 8] */

package/dist/components/charts/geo/DistanceCartogram.d.ts

@@ -4,6 +4,7 @@ import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes"
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends BaseChartProps {
     /** Point data with geographic coordinates */
@@ -36,6 +37,12 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     transition?: number;
     /** Field to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware point styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. `ctx` = `{ value, category }`
+     * (category = `colorBy`). A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
     /** Color scheme @default "category10" */
     colorScheme?: string | string[] | Record<string, string>;
     /** Point radius @default 5 */
@@ -46,8 +53,13 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     showLegend?: boolean;
     /** Legend position */
     legendPosition?: LegendPosition;
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Finite projection-fit fraction in `[0, 0.5)`. `0.1` = 10% inset;
+     * nullish values use 0 and invalid values throw. An explicit
+     * `frameProps.projectionExtent` remains authoritative.
+     * @default 0
+     */
+    fitPadding?: number | null;
     /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
     zoomable?: boolean;
     /** [minZoom, maxZoom] @default [1, 8] */

package/dist/components/charts/geo/FlowMap.d.ts

@@ -10,12 +10,11 @@ import type { GeoParticleStyle } from "../../stream/GeoParticlePool";
 import { type AreasProp } from "../../geo/useReferenceAreas";
 export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartProps {
     /** Flow edges with source/target/value */
-    flows?: {
+    flows?: Array<Datum & {
         source: string;
         target: string;
         value?: number;
-        [key: string]: any;
-    }[];
+    }>;
     /** Geographic nodes with coordinates */
     nodes?: TDatum[];
     /** Node ID accessor @default "id" */
@@ -39,7 +38,7 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     /** Background area style */
     areaStyle?: Style;
     /** Edge color accessor */
-    edgeColorBy?: ChartAccessor<any, string>;
+    edgeColorBy?: ChartAccessor<Datum, string>;
     /** Edge opacity @default 0.6 */
     edgeOpacity?: number;
     /** Min/max pixel width for proportional edge width @default [1, 8] */
@@ -60,8 +59,13 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     legendInteraction?: LegendInteractionMode;
     /** Legend position */
     legendPosition?: LegendPosition;
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Finite projection-fit fraction in `[0, 0.5)`. `0.1` = 10% inset;
+     * nullish values use 0 and invalid values throw. An explicit
+     * `frameProps.projectionExtent` remains authoritative.
+     * @default 0
+     */
+    fitPadding?: number | null;
     /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
     zoomable?: boolean;
     /** [minZoom, maxZoom] @default [1, 8] */

package/dist/components/charts/geo/ProportionalSymbolMap.d.ts

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 import type { Style } from "../../stream/types";
 import { type AreasProp } from "../../geo/useReferenceAreas";
 export interface ProportionalSymbolMapProps<TDatum extends Datum = Datum> extends BaseChartProps {
@@ -20,6 +21,12 @@ export interface ProportionalSymbolMapProps<TDatum extends Datum = Datum> extend
     sizeRange?: [number, number];
     /** Field to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware symbol styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. `ctx` = `{ value, category }` (value =
+     * `sizeBy`, category = `colorBy`). A rule `fill` may be a color or HatchFill.
+     */
+    styleRules?: StyleRule[];
     /** Color scheme @default "category10" */
     colorScheme?: string | string[] | Record<string, string>;
     /** Geographic projection @default "equalEarth" */
@@ -38,8 +45,13 @@ export interface ProportionalSymbolMapProps<TDatum extends Datum = Datum> extend
     legendInteraction?: LegendInteractionMode;
     /** Legend position */
     legendPosition?: LegendPosition;
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Finite projection-fit fraction in `[0, 0.5)`. `0.1` = 10% inset;
+     * nullish values use 0 and invalid values throw. An explicit
+     * `frameProps.projectionExtent` remains authoritative.
+     * @default 0
+     */
+    fitPadding?: number | null;
     /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
     zoomable?: boolean;
     /** [minZoom, maxZoom] @default [1, 8] */

package/dist/components/charts/index.d.ts

@@ -133,3 +133,9 @@ export { Tooltip, MultiLineTooltip, normalizeTooltip } from "../Tooltip/Tooltip"
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "../Tooltip/Tooltip";
 export { createHatchPattern } from "./shared/hatchPattern";
 export type { HatchPatternOptions } from "./shared/hatchPattern";
+export { isHatchFill, hatchPatternDef, resolveSvgFill, hatchFillId } from "./shared/hatchFill";
+export type { HatchFill } from "./shared/hatchFill";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, makeXYRuleContext, makeNodeRuleContext, composeStyleRules, makeStyleRuleStyleFn, } from "./shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate, } from "./shared/styleRules";
+export { AnnotationLabel, estimateLabelWidth } from "./shared/AnnotationLabel";
+export type { AnnotationLabelBackground, AnnotationLabelBackgroundConfig, AnnotationLabelProps } from "./shared/AnnotationLabel";

package/dist/components/charts/network/ChordDiagram.d.ts

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * ChordDiagram component props
  */
@@ -17,10 +18,17 @@ export interface ChordDiagramProps<TNode extends Datum = Datum, TEdge extends Da
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string>;
     colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling (see ForceDirectedGraph).
+     * Ordered `{ when, style }` rules; last applicable rule wins. Rules see the
+     * raw node object. A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
     edgeColorBy?: "source" | "target" | ((d: Datum) => string);
     padAngle?: number;
     groupWidth?: number;
-    sortGroups?: (a: any, b: any) => number;
+    /** Compare D3 chord group indices to control their angular order. */
+    sortGroups?: (a: number, b: number) => number;
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;

package/dist/components/charts/network/ForceDirectedGraph.d.ts

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * ForceDirectedGraph component props
  */
@@ -68,6 +69,16 @@ export interface ForceDirectedGraphProps<TNode extends Datum = Datum, TEdge exte
     colorBy?: ChartAccessor<TNode, string>;
     /** d3 scheme name or explicit color array; falls back to theme. */
     colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(node, ctx) => boolean` (rules see the raw node object; `ctx` =
+     * `{ value, category }` where `category` is the `colorBy` group), a
+     * declarative threshold (`{ field, gt, eq, in, … }`), or `true` — so you can
+     * style whole groups of nodes (`{ field: "type", eq: "db" }`). A rule's
+     * `fill` may be a color or a HatchFill. Layers over the resolved node color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Constant pixel radius, or a function/field returning a numeric value
      * scaled into `nodeSizeRange`.

package/dist/components/charts/network/SankeyDiagram.d.ts

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * SankeyDiagram component props
  */
@@ -17,6 +18,13 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string>;
     colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling (see ForceDirectedGraph).
+     * Ordered `{ when, style }` rules; last applicable rule wins. Rules see the
+     * raw node object; `ctx` = `{ value, category }`. A rule `fill` may be a
+     * color or a HatchFill. Layers over the resolved node color.
+     */
+    styleRules?: StyleRule[];
     edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     orientation?: "horizontal" | "vertical";
     nodeAlign?: "justify" | "left" | "right" | "center";
@@ -31,7 +39,7 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     legendPosition?: LegendPosition;
     legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
-    edgeSort?: (a: any, b: any) => number;
+    edgeSort?: (a: TEdge, b: TEdge) => number;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }

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

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BarChart component props
@@ -81,6 +82,26 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
             color: string;
         }>;
     };
+    /**
+     * Declarative, threshold-aware bar styling. An ordered list of
+     * `{ when, style }` rules; every rule whose condition matches a bar
+     * contributes its style, merged in order so the **last applicable rule
+     * wins** per property. `when` accepts a predicate `(datum, ctx) => boolean`,
+     * a declarative threshold (`{ gt, lte, within, in, … }` — compares the
+     * bar's value unless `field` is set), or `true`/omitted (always applies).
+     * A rule's `fill` may be a color string or a declarative
+     * {@link HatchFill} for diagonal hatching (renders on canvas and SSR).
+     * Rules layer over the resolved base color; `frameProps.pieceStyle` and
+     * top-level `stroke`/`strokeWidth`/`opacity` still override them.
+     * @example
+     * ```tsx
+     * styleRules={[
+     *   { when: { gte: 10 }, style: { fill: "var(--semiotic-warning)" } },
+     *   { when: { gt: 15 }, style: { fill: { type: "hatch", background: "#e0a92a", stroke: "#fff" } } },
+     * ]}
+     * ```
+     */
+    styleRules?: StyleRule[];
     /** When true, adds padding below the 0 baseline. Default false (bars flush with axis). */
     baselinePadding?: boolean;
     enableHover?: boolean;

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

@@ -4,6 +4,7 @@ import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
@@ -21,6 +22,16 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded corner radius on bar ends (away from baseline). */
     roundedTop?: number;
+    /**
+     * Declarative, threshold-aware bar styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(datum, ctx) => boolean` (where `ctx.category` is the group
+     * series key), a declarative threshold on the bar value
+     * (`{ gt, lte, within, in, … }`), or `true`. A rule's `fill` may be a color
+     * or a {@link HatchFill}. Layers over the resolved series color;
+     * `frameProps.pieceStyle` overrides.
+     */
+    styleRules?: StyleRule[];
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

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

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type StyleRule } from "../shared/styleRules";
 export interface StackedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -22,6 +23,16 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded top corner radius. Only the topmost stacked segment gets rounded. */
     roundedTop?: number;
+    /**
+     * Declarative, threshold-aware segment styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(datum, ctx) => boolean` (where `ctx.category` is the stack
+     * series key), a declarative threshold on the segment value
+     * (`{ gt, lte, within, in, … }`), or `true`. A rule's `fill` may be a color
+     * or a {@link HatchFill} for hatching a segment (e.g. a "fixed-rate" band).
+     * Layers over the resolved series color; `frameProps.pieceStyle` overrides.
+     */
+    styleRules?: StyleRule[];
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
 import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
 export interface CollisionSwarmChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
@@ -11,6 +12,12 @@ export interface CollisionSwarmChartProps<TDatum extends Datum = Datum> extends
     radiusAccessor?: ChartAccessor<TDatum, number>;
     pointRadius?: number;
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware dot styling. Ordered `{ when, style }` rules;
+     * last applicable rule wins. `ctx` = `{ value, category }` (value = the
+     * `xAccessor` position). A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
     seed?: number;
     xExtent?: [number, number];
     collisionIterations?: number;

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

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type EventDropWindowOptions } from "./physicsChartUtils";
+import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
 import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
 export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
@@ -16,6 +17,12 @@ export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<
     } | ((latestEventTime: number) => number);
     ballRadius?: number;
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware drop styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. `ctx` = `{ value, category }` (value =
+     * the event time). A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
     seed?: number;
     timeExtent?: [number, number];
     timeScale?: number;

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } 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";
 import type { ChartMode } from "../shared/types";
@@ -32,6 +33,13 @@ export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omi
     branchProbability?: number;
     ballRadius?: number;
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware ball styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. Rules resolve against each ball's datum;
+     * `ctx` = `{ value, category }` (category = the colorBy group). A rule `fill`
+     * may be a color or a HatchFill. Layers over the colorBy-derived fill.
+     */
+    styleRules?: StyleRule[];
     referenceLines?: GaltonBoardReferenceLine | GaltonBoardReferenceLine[];
     seed?: number;
     showProjection?: 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;