semiotic 3.7.5 → 3.8.1

package/dist/components/ai/readerGrounding.d.ts

@@ -40,6 +40,12 @@ export interface ChartReaderGroundingOptions {
     maxLeaves?: number;
     /** Skip the navigation structure (e.g. to save tokens). Default false. */
     includeStructure?: boolean;
+    /**
+     * Include physics runtime grounding for StreamPhysicsFrame/physics HOCs.
+     * Default: auto-detect from physics chart props. Pass false to omit, true to
+     * force extraction from props, or an object to supply snapshot/evidence rows.
+     */
+    physics?: boolean | PhysicsReaderGroundingInput;
 }
 export interface ChartReaderGroundingIntent {
     /** The communicative act the chart performs. */
@@ -51,6 +57,81 @@ export interface ChartReaderGroundingIntent {
     /** Resolved per-intent scores, when the caller passed them (not from a raw descriptor). */
     intentScores?: Partial<Record<IntentId, number>>;
 }
+export interface PhysicsReaderGroundingAggregate {
+    id?: string;
+    label: string;
+    count: number;
+    secondary?: number;
+    secondaryLabel?: string;
+    observed?: number;
+}
+export interface PhysicsReaderGroundingAggregates {
+    rows: PhysicsReaderGroundingAggregate[];
+    totalCount: number;
+    populatedCount: number;
+    leader?: PhysicsReaderGroundingAggregate;
+}
+export interface PhysicsReaderGroundingSimulation {
+    state?: string;
+    settled?: boolean;
+    elapsedSeconds?: number;
+    paused?: boolean;
+    visible?: boolean;
+    seed?: number;
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    fixedDt?: number;
+    timeScale?: number;
+    maxSubsteps?: number;
+    liveBodies?: number;
+    sleepingBodies?: number;
+    queued?: number;
+    bodyLimit?: number;
+    eviction?: string;
+}
+export interface PhysicsReaderGroundingGeometry {
+    colliders?: number;
+    sensors?: number;
+    springs?: number;
+    activeSensorPairs?: number;
+}
+export interface PhysicsReaderGroundingSediment {
+    bins: number;
+    count: number;
+    total?: number;
+    leader?: {
+        id?: string;
+        label: string;
+        count: number;
+        total?: number;
+    };
+}
+export interface PhysicsReaderGroundingInput {
+    /** PhysicsPipelineSnapshot or a structurally equivalent object. */
+    snapshot?: unknown;
+    /** PhysicsSettledEvidence or a structurally equivalent object. */
+    evidence?: unknown;
+    /** PhysicsPipelineConfig or equivalent runtime config. */
+    config?: unknown;
+    /** Settled projection rows / evidence bin counts. */
+    projectionRows?: readonly unknown[];
+    /** Alias for projectionRows when callers already name the rows aggregates. */
+    aggregates?: readonly unknown[];
+    /** Physics sediment bin snapshots. */
+    sediment?: readonly unknown[];
+    /** Precomputed sediment totals, if available. */
+    sedimentTotals?: unknown;
+}
+export interface PhysicsReaderGrounding {
+    simulation: PhysicsReaderGroundingSimulation;
+    geometry?: PhysicsReaderGroundingGeometry;
+    aggregates?: PhysicsReaderGroundingAggregates;
+    sediment?: PhysicsReaderGroundingSediment;
+    /** Compact prose appended to `ChartReaderGrounding.text`. */
+    text: string;
+}
 export interface ChartReaderGrounding {
     component: string;
     /** Layered L1–L3 description ({ text, levels }). */
@@ -59,6 +140,8 @@ export interface ChartReaderGrounding {
     intent?: ChartReaderGroundingIntent;
     /** Structured navigation tree (chart → axes/series → datum). Omitted when `includeStructure: false`. */
     structure?: NavTreeNode;
+    /** Physics-specific runtime grounding for simulation charts. */
+    physics?: PhysicsReaderGrounding;
     /** L1–L4 joined into one prose blob an LLM can read directly. */
     text: string;
 }

package/dist/components/ai/recipeCapability.d.ts

@@ -0,0 +1,8 @@
+import type { ChartCapability, ChartDataProfile } from "./chartCapabilityTypes";
+import type { ChartRecipe, DataRoleDefinition } from "./chartRecipes";
+export declare function resolveRecipeRoleField(recipe: ChartRecipe, role: DataRoleDefinition, profile: ChartDataProfile): string | undefined;
+/**
+ * Adapt a declarative recipe into the existing capability engine. Raw custom
+ * frame HOCs remain excluded; named recipes participate as distinct candidates.
+ */
+export declare function recipeToChartCapability(recipe: ChartRecipe): ChartCapability;

package/dist/components/ai/recipeNavigation.d.ts

@@ -0,0 +1,13 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe } from "./chartRecipes";
+import type { NavTreeNode } from "./navigationTree";
+export interface RecipeNavigationOptions {
+    maxLeaves?: number;
+    locale?: string;
+}
+/**
+ * Build navigation from a recipe strategy, or from its declared data roles
+ * when no strategy exists. The fallback always produces data leaves rather
+ * than collapsing an unfamiliar custom chart to a root-only node.
+ */
+export declare function buildRecipeNavigationTree(recipe: ChartRecipe, props: Datum, options?: RecipeNavigationOptions): NavTreeNode;

package/dist/components/ai/recipeSemantics.d.ts

@@ -0,0 +1,11 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe, DataRoleDefinition, IntentDefinition } from "./chartRecipes";
+export declare function recipeIntentId(intent: IntentDefinition): string | undefined;
+export declare function recipeConfig(props: Datum): Record<string, unknown>;
+export declare function recipeData(props: Datum): Datum[];
+export declare function resolveRecipeForChart(component: string, props: Datum, explicit?: ChartRecipe): ChartRecipe | undefined;
+export declare function fieldForRole(role: DataRoleDefinition, config: Record<string, unknown>, data?: ReadonlyArray<Datum>): string | undefined;
+export declare function roleByName(recipe: ChartRecipe, name: string): DataRoleDefinition | undefined;
+export declare function firstRole(recipe: ChartRecipe, semanticTypes: DataRoleDefinition["semanticType"][]): DataRoleDefinition | undefined;
+export declare function roleValue(datum: Datum, role: DataRoleDefinition | undefined, config: Record<string, unknown>, data: ReadonlyArray<Datum>): unknown;
+export declare function fillRecipeTemplate(template: string, datum: Datum | undefined, recipe: ChartRecipe, config: Record<string, unknown>, data: ReadonlyArray<Datum>, extra?: Record<string, string | number>): string;

package/dist/components/ai/repairChartConfig.d.ts

@@ -1,6 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
 import type { IntentId } from "./intents";
+import type { ObservedSceneAuditResult } from "./observedSceneAudit";
 /**
  * Repair result when the chosen chart fits the data — nothing to fix.
  */
@@ -9,6 +10,8 @@ export interface RepairOkResult {
     component: string;
     /** The same data profile that was evaluated. */
     profile: ChartDataProfile;
+    /** Recipe-specific reception/accessibility repairs, even when data shape fits. */
+    repairs?: string[];
 }
 /**
  * Repair result when the chosen chart doesn't fit. Carries the diagnostic
@@ -24,6 +27,7 @@ export interface RepairAlternativeResult {
     /** Whether the caller intended one of the alternatives anyway. */
     alternatives: Suggestion[];
     profile: ChartDataProfile;
+    repairs?: string[];
 }
 /**
  * Repair result when no capability is registered for the asked component.
@@ -34,6 +38,7 @@ export interface RepairUnknownResult {
     /** Closest matches by family/intent — best effort. */
     alternatives: Suggestion[];
     profile: ChartDataProfile;
+    repairs?: string[];
 }
 export type RepairResult = RepairOkResult | RepairAlternativeResult | RepairUnknownResult;
 export interface RepairOptions {
@@ -45,6 +50,10 @@ export interface RepairOptions {
     maxAlternatives?: number;
     /** Pre-computed profile, avoids recomputation. */
     profile?: ChartDataProfile;
+    /** Current rendered props, used for recipe-specific repair guidance. */
+    props?: Datum;
+    /** Optional observed-scene evidence from auditObservedScene(). */
+    observedSceneAudit?: ObservedSceneAuditResult;
 }
 /**
  * Validate that a chart component is a sensible choice for a dataset, and

package/dist/components/ai/suggestCharts.d.ts

@@ -2,7 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 import { type ProfileDataOptions } from "./profileData";
 import type { ChartCapability, ChartDataProfile, ScaledSuggestionGroups, Suggestion } from "./chartCapabilityTypes";
 import type { IntentId } from "./intents";
-import { type AudienceProfile } from "./audienceProfile";
+import { type AudienceProfile, type ReceptionModality } from "./audienceProfile";
 import { type DataQualityProfile, type DataScaleProfile } from "./dataScaleProfile";
 export interface SuggestChartsOptions extends ProfileDataOptions {
     /** Ranking intent(s). When omitted, suggestions are ranked by mean intent score. */
@@ -39,6 +39,12 @@ export interface SuggestChartsOptions extends ProfileDataOptions {
      * `dataScaleProfile.ts`.
      */
     quality?: DataQualityProfile;
+    /** Restrict recipe candidates by portability tier. Built-ins are unaffected. */
+    portability?: "portable" | "local";
+    /** Controls how strongly declared recipe reception risks affect ranking. */
+    riskTolerance?: "low" | "medium" | "high";
+    /** Explicit reception channel when no full AudienceProfile is available. */
+    receptionChannel?: ReceptionModality;
 }
 /**
  * Suggest charts for a dataset, ranked by intent suitability.
@@ -85,6 +91,10 @@ export declare function scoreChart(component: string, data: ReadonlyArray<Datum>
     intent?: IntentId | IntentId[];
     variantKey?: string;
     profile?: ChartDataProfile;
+    audience?: AudienceProfile;
+    portability?: "portable" | "local";
+    riskTolerance?: "low" | "medium" | "high";
+    receptionChannel?: ReceptionModality;
 }): Suggestion | {
     reason: string;
 };

package/dist/components/ai/useNavigationSync.d.ts

@@ -1,3 +1,4 @@
+import type { ChartObservation } from "../store/ObservationStore";
 import type { NavTreeNode } from "./navigationTree";
 import type { Datum } from "../charts/shared/datumTypes";
 /**
@@ -29,8 +30,12 @@ export interface UseNavigationSyncOptions {
     matchFields?: string[];
     /** Selection name shared with the chart's `selection={{ name }}`. Default "__semiotic-nav-sync". */
     selectionName?: string;
-    /** Which canvas observations move the tree. Default ["hover", "click"]. */
-    observe?: Array<"hover" | "click">;
+    /**
+     * Which chart observations move the tree. Defaults to pointer hover/click
+     * plus keyboard focus/activation so raw frames and HOC charts stay in sync
+     * for both pointer and keyboard readers.
+     */
+    observe?: Array<"hover" | "click" | "focus" | "activate">;
     /**
      * The chart's annotations. An annotation anchored to a datum carries that
      * datum's identifying fields (the same `matchFields` used for hover sync), so
@@ -49,6 +54,16 @@ export interface UseNavigationSyncResult {
     selection: {
         name: string;
     };
+    /**
+     * Feed a chart observation directly into the sync. This is useful for raw
+     * StreamFrames or custom interactions that call `onObservation` themselves
+     * instead of publishing through the chart HOCs. Matching pointer and
+     * keyboard observations move the tree; events later received from the global
+     * observation store are de-duplicated by object identity.
+     */
+    onObservation: (observation: ChartObservation) => void;
+    /** Alias of `onObservation` for composing an externally supplied handler. */
+    handleObservation: (observation: ChartObservation) => void;
     /** Nav-tree leaf ids that an annotation anchors to — mark these as "has a note". */
     annotatedIds: Set<string>;
     /**

package/dist/components/chartContainerMobile.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+import type { MobileStandardControlRequest, MobileStandardControlsProps } from "./MobileStandardControls";
+import type { MobileInteractionProp } from "./charts/shared/types";
+export declare function canReceiveChartProps(child: ReactElement): boolean;
+export declare function isMobileStandardControlsProps(value: MobileStandardControlRequest | MobileStandardControlsProps | undefined): value is MobileStandardControlsProps;
+export declare function standardControlsFromInteraction(mobileInteraction: MobileInteractionProp | undefined): MobileStandardControlRequest | undefined;
+export declare function targetSizeFromInteraction(mobileInteraction: MobileInteractionProp | undefined): number | undefined;
+export declare function hasStandardControlsRequest(request: MobileStandardControlRequest | undefined): request is MobileStandardControlRequest;
+export declare function withStandardControls(source: MobileInteractionProp | undefined, controls: MobileStandardControlRequest | undefined): MobileInteractionProp | undefined;

package/dist/components/charts/custom/GeoCustomChart.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+import type { ProjectionProp, StreamGeoFrameProps } from "../../stream/geoTypes";
+import type { GeoCustomLayout } from "../../stream/geoCustomLayout";
+import type { ChartRecipe } from "../../ai/chartRecipes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+export interface GeoCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
+    /** Geographic point data supplied to `GeoLayoutContext.points`. */
+    points?: TDatum[];
+    /** Geographic areas supplied to `GeoLayoutContext.areas`. */
+    areas?: GeoJSON.Feature[];
+    /** Geographic line/flow records supplied to `GeoLayoutContext.lines`. */
+    lines?: TDatum[];
+    /** Layout function that emits GeoFrame scene nodes and optional overlays. */
+    layout: GeoCustomLayout<TConfig>;
+    /** User configuration threaded to `GeoLayoutContext.config`. */
+    layoutConfig?: TConfig;
+    /** Receives a structured diagnostic if the layout throws. */
+    onLayoutError?: StreamGeoFrameProps["onLayoutError"];
+    recipe?: ChartRecipe<TDatum, TConfig>;
+    recipeId?: string;
+    /** Projection resolved before the custom layout runs. @default "equirectangular" */
+    projection?: ProjectionProp;
+    xAccessor?: StreamGeoFrameProps<TDatum>["xAccessor"];
+    yAccessor?: StreamGeoFrameProps<TDatum>["yAccessor"];
+    lineDataAccessor?: StreamGeoFrameProps<TDatum>["lineDataAccessor"];
+    /** Field or function that declares the semantic category used for custom-layout color. */
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[] | Record<string, string>;
+    enableHover?: boolean;
+    tooltip?: TooltipProp;
+    annotations?: Datum[];
+    /** Additional StreamGeoFrame props excluding fields controlled by this HOC. */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "points" | "lines" | "projection" | "size" | "customLayout" | "layoutConfig" | "layoutSelection" | "xAccessor" | "yAccessor" | "lineDataAccessor">>;
+}
+/**
+ * GeoCustomChart — escape hatch for bespoke geographic geometry.
+ *
+ * The frame resolves the projection and continues to own canvas rendering,
+ * polygon/point/line hit-testing, accessibility, tooltips, selection, and SSR.
+ * The supplied layout owns only the scene geometry and SVG overlays.
+ */
+export declare const GeoCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: GeoCustomChartProps<TDatum, TConfig> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/custom/NetworkCustomChart.d.ts

@@ -3,7 +3,8 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { NetworkCustomLayout } from "../../stream/networkCustomLayout";
 import type { Datum } from "../shared/datumTypes";
-import type { BaseChartProps } from "../shared/types";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { ChartRecipe } from "../../ai/chartRecipes";
 export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
     /** Node objects with at least an `id` field. Positions are typically pre-computed by the user (e.g. from dagre / d3-flextree) and read by the layout. */
     nodes?: TNode[];
@@ -13,6 +14,10 @@ export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge exte
     layout: NetworkCustomLayout<TConfig>;
     /** Config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: TConfig;
+    /** Receives a structured diagnostic if the layout throws. */
+    onLayoutError?: StreamNetworkFrameProps["onLayoutError"];
+    recipe?: ChartRecipe<TNode, TConfig>;
+    recipeId?: string;
     /** Field name (or function) for the node id. @default "id" */
     nodeIDAccessor?: StreamNetworkFrameProps["nodeIDAccessor"];
     /** Field name for the edge source id. @default "source" */
@@ -20,7 +25,8 @@ export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge exte
     /** Field name for the edge target id. @default "target" */
     targetAccessor?: StreamNetworkFrameProps["targetAccessor"];
     /** Color scheme threaded into the layout's `resolveColor` helper. */
-    colorScheme?: string | string[];
+    colorBy?: ChartAccessor<TNode, string | number>;
+    colorScheme?: string | string[] | Record<string, string>;
     enableHover?: boolean;
     /**
      * Annotations rendered over the chart. A custom network layout's marks are

package/dist/components/charts/custom/OrdinalCustomChart.d.ts

@@ -3,7 +3,8 @@ import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { OrdinalCustomLayout } from "../../stream/ordinalCustomLayout";
 import type { Datum } from "../shared/datumTypes";
-import type { BaseChartProps } from "../shared/types";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { ChartRecipe } from "../../ai/chartRecipes";
 export interface OrdinalCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
     /** Data passed through to OrdinalLayoutContext.data. */
     data?: TDatum[];
@@ -11,6 +12,10 @@ export interface OrdinalCustomChartProps<TDatum extends Datum = Datum, TConfig e
     layout: OrdinalCustomLayout<TConfig>;
     /** Config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: TConfig;
+    /** Receives a structured diagnostic if the layout throws. */
+    onLayoutError?: StreamOrdinalFrameProps["onLayoutError"];
+    recipe?: ChartRecipe<TDatum, TConfig>;
+    recipeId?: string;
     /** Field name (or function) for the category. The frame builds the o-scale from these. */
     categoryAccessor?: StreamOrdinalFrameProps["categoryAccessor"];
     /** Field name (or function) for the value. The frame builds the r-scale from these. */
@@ -25,7 +30,8 @@ export interface OrdinalCustomChartProps<TDatum extends Datum = Datum, TConfig e
     /** Vertical / horizontal / radial. Default vertical. */
     projection?: StreamOrdinalFrameProps["projection"];
     /** Color scheme threaded into the layout's `resolveColor` helper. */
-    colorScheme?: string | string[];
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[] | Record<string, string>;
     enableHover?: boolean;
     showAxes?: boolean;
     showGrid?: boolean;

package/dist/components/charts/custom/XYCustomChart.d.ts

@@ -3,8 +3,9 @@ import type { StreamXYFrameProps } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { CustomLayout } from "../../stream/customLayout";
 import type { Datum } from "../shared/datumTypes";
-import type { BaseChartProps, AxisConfig } from "../shared/types";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import type { TooltipProp } from "../../Tooltip/Tooltip";
+import type { ChartRecipe } from "../../ai/chartRecipes";
 export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps, AxisConfig {
     /** Data passed through to LayoutContext.data. */
     data?: TDatum[];
@@ -12,6 +13,12 @@ export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extend
     layout: CustomLayout<TConfig>;
     /** Config blob threaded through to LayoutContext.config. */
     layoutConfig?: TConfig;
+    /** Receives a structured diagnostic if the layout throws. */
+    onLayoutError?: StreamXYFrameProps["onLayoutError"];
+    /** Optional meaning/intelligence contract for description, navigation, and audit surfaces. */
+    recipe?: ChartRecipe<TDatum, TConfig>;
+    /** Registered recipe id; portable alternative to embedding the manifest object. */
+    recipeId?: string;
     /**
      * Optional fixed extents — flow into scale construction *before* the layout
      * runs, so scales reflect the layout's intended domain. Layouts that don't
@@ -25,7 +32,9 @@ export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extend
     enableHover?: boolean;
     showLegend?: boolean;
     annotations?: Datum[];
-    colorScheme?: string | string[];
+    /** Field or function that declares the semantic category used for custom-layout color. */
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[] | Record<string, string>;
     tooltip?: TooltipProp;
     /** Additional StreamXYFrame props for advanced customization, excluding XYCustomChart-controlled fields. */
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size" | "customLayout" | "layoutConfig">>;

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,8 +37,14 @@ 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[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Point radius @default 5 */
     pointRadius?: number;
     /** Tooltip */
@@ -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] */
@@ -47,7 +46,7 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     /** Line cap style for flow edges @default "round" */
     edgeLinecap?: "butt" | "round" | "square";
     /** Color scheme for edges @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Show animated particles along flow lines */
     showParticles?: boolean;
     /** Particle appearance and behavior */
@@ -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,8 +21,14 @@ 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[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Geographic projection @default "equalEarth" */
     projection?: ProjectionProp;
     /** Show graticule grid lines */
@@ -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/geo/index.d.ts

@@ -6,3 +6,5 @@ export { FlowMap } from "./FlowMap";
 export type { FlowMapProps } from "./FlowMap";
 export { DistanceCartogram } from "./DistanceCartogram";
 export type { DistanceCartogramProps } from "./DistanceCartogram";
+export { GeoCustomChart } from "../custom/GeoCustomChart";
+export type { GeoCustomChartProps } from "../custom/GeoCustomChart";

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

@@ -96,7 +96,35 @@ export { RealtimeWaterfallChart } from "./realtime/RealtimeWaterfallChart";
 export type { RealtimeWaterfallChartProps } from "./realtime/RealtimeWaterfallChart";
 export { RealtimeHeatmap } from "./realtime/RealtimeHeatmap";
 export type { RealtimeHeatmapProps } from "./realtime/RealtimeHeatmap";
-export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./shared/types";
+export { GaltonBoardChart } from "./physics/GaltonBoardChart";
+export type { GaltonBoardChartProps, GaltonBoardReferenceLine } from "./physics/GaltonBoardChart";
+export { EventDropChart } from "./physics/EventDropChart";
+export type { EventDropChartProps } from "./physics/EventDropChart";
+export { PhysicsPileChart } from "./physics/PhysicsPileChart";
+export type { PhysicsPileChartProps } from "./physics/PhysicsPileChart";
+export { CollisionSwarmChart } from "./physics/CollisionSwarmChart";
+export type { CollisionSwarmChartProps } from "./physics/CollisionSwarmChart";
+export { GauntletChart, GuantletChart, planGauntletPropertyWork, replaceGauntletNegative } from "./physics/GauntletChart";
+export type { GauntletChartProps, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyForceContext, GauntletPropertyDefinition, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions } from "./physics/GauntletChart";
+export { physicsProcessBoundaryColliders, physicsProcessGroupSemanticItems, physicsProcessRegionSemanticItem, physicsProcessStageSemanticItems } from "./physics/physicsProcessPrimitives";
+export type { PhysicsProcessBodyGroup, PhysicsProcessBoundaryOptions, PhysicsProcessStage } from "./physics/physicsProcessPrimitives";
+export { absorbRegion, bodyGroupSpec, capacitatedRegion, chargeGateRegion, forceFieldRegion, membraneRegion, portalRegion, pressureFieldRegion, processLaneWalls, processStageLayout, processStageRegions, routeSurfaceRegion, stageTargetInVolume } from "../recipes/processPhysics";
+export { aggregateRegionCounts, groupCompletionRows, regionCountsToProjectionRows } from "../recipes/processAggregates";
+export { processVolumePolygons } from "../recipes/processVolumeGeometry";
+export { createProcessJourneyLedger, processJourneyRows, updateProcessJourney } from "../recipes/processJourney";
+export type { BodyGroupSpec, BodyGroupSpecOptions, ProcessMembraneDef, ProcessRegionBaseOptions, ProcessStageRegionOptions, ProcessStageDef, ProcessVolumeLayout, ProcessVolumeLayoutOptions, ProcessVolumeMembraneBand, ProcessVolumeShape, ProcessVolumeStageBand } from "../recipes/processPhysics";
+export type { RegionCountBucket, RegionCountMap } from "../recipes/processAggregates";
+export type { ProcessVolumePoint, ProcessVolumePolygon, ProcessVolumePolygonRole } from "../recipes/processVolumeGeometry";
+export type { ProcessJourneyEntityState, ProcessJourneyLedger, ProcessJourneyRow, ProcessJourneyStage, ProcessJourneyUpdateOptions } from "../recipes/processJourney";
+export { PhysicalFlowChart } from "./physics/PhysicalFlowChart";
+export type { PhysicalFlowChartProps } from "./physics/PhysicalFlowChart";
+export { ProcessFlowChart } from "./physics/ProcessFlowChart";
+export type { ProcessFlowChartProps, ProcessFlowProjectionMetadata, ProcessFlowStageDef } from "./physics/ProcessFlowChart";
+export { PhysicsCustomChart } from "./physics/PhysicsCustomChart";
+export type { PhysicsCustomChartProps, PhysicsCustomLayout, PhysicsCustomLayoutContext, PhysicsCustomLayoutResult, PhysicsCustomSpawnDatumResult } from "./physics/PhysicsCustomChart";
+export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode, MobileClearSelectionBehavior, MobileSnapBehavior, MobileInteractionConfig, MobileInteractionProp, MobileStandardControlsMode, ResolvedMobileInteractionConfig, } from "./shared/types";
+export { responsiveRuleMatches, resolveResponsiveRules } from "./shared/responsiveRules";
+export type { ResponsiveOrientation, ResponsiveRuleCondition, ResponsiveRuleContext, ResponsiveRule, ResponsiveRuleMatch, ResponsiveRuleResult, } from "./shared/responsiveRules";
 export { useColorScale, useSortedData, DEFAULT_COLOR } from "./shared/hooks";
 export { COLOR_SCHEMES, DEFAULT_COLORS, getColor, createColorScale, getSize } from "./shared/colorUtils";
 export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText, adaptiveTimeTicks } from "./shared/formatUtils";
@@ -105,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";