semiotic 3.8.6 → 3.8.7

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

@@ -9,7 +9,7 @@ import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { PhysicsProcessBodyGroup } from "./physicsProcessPrimitives";
 import type { PhysicsHocFrameProps, PhysicsRerunMS, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
 import type { GauntletEvent, GauntletGate, GauntletLayout, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyDefinition } from "./gauntletTypes";
-export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     idAccessor?: ChartAccessor<TDatum, string>;
@@ -43,6 +43,11 @@ export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<B
         positiveProperties: Map<string, GauntletPropertyDefinition>;
     }) => string;
     paused?: boolean;
+    /**
+     * Deterministic seed, matching every other physics HOC. An explicit
+     * `frameProps.config.kernel.seed` still wins so existing snapshots hold.
+     */
+    seed?: number;
     /**
      * Replay the full compound simulation this many milliseconds after it
      * settles. Omit or pass `null` for a single run; `0` replays on the next

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

@@ -0,0 +1,61 @@
+/**
+ * Gauntlet terminal state — the end of the authored tape, computed without
+ * running the simulation.
+ *
+ * ## Why this exists
+ *
+ * Every event-tape physics chart owes the same contract: **its end state must be
+ * computable from the authored inputs alone.** If the outcome only exists as the
+ * residue of a simulation, then reduced motion, SSR, snapshot export, and
+ * `describeChart` cannot state it, and the chart is a movie rather than a
+ * reading. `CrucibleChart` satisfies this by compiling `terminalState` /
+ * `terminalSpawns`; `ChainReactionChart` satisfies it by deriving task state from
+ * the data at `currentTime`. Gauntlet had no such function — this is it.
+ *
+ * The fold below mirrors the live `runGauntletTick` state path exactly (same
+ * `applyGauntletEffect` / `recordGauntletEvent` / viability / final-outcome
+ * order), so the pure answer and the simulated answer agree. Terminal means the
+ * tape has fully run: every authored event is due, including capacity-gated
+ * ones, because at terminal every gate visit has been processed.
+ *
+ * ## The one thing this cannot predict
+ *
+ * `GauntletChart` has a **second outcome source that is not in the tape**: with
+ * `crashDetection` enabled (the default), a core whose simulated trajectory
+ * touches the crash line is killed and its outcome is overridden to
+ * `"bad_design_crash"`. That is a genuine physics-derived finding, and no pure
+ * function can compute it — it depends on the trajectory.
+ *
+ * So this resolver returns the **authored-tape terminal state**. It equals the
+ * simulated settled state whenever the run does not crash (notably with
+ * `crashDetection={false}`, where the tape is the whole story). When crash
+ * detection is armed, treat the pure result as "the outcome the plan earns on
+ * paper" and the simulated `killed` / `crashX` fields as the physical override.
+ * Charts that need a fully authored reading should disable crash detection.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { GauntletEvent, GauntletLayout, GauntletProjectState, GauntletPropertyDefinition, GauntletViabilityFn } from "./gauntletTypes";
+export interface GauntletTerminalOptions<TDatum extends Datum = Datum> {
+    /** Initial project states, as `createInitialState` produces them. */
+    projects: readonly GauntletProjectState<TDatum>[];
+    /** Authored tape, or the per-project function form. */
+    events?: readonly GauntletEvent[] | ((project: GauntletProjectState<TDatum>, layout: GauntletLayout) => readonly GauntletEvent[]);
+    layout: GauntletLayout;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    viability?: GauntletViabilityFn<TDatum>;
+    outcome?: (project: GauntletProjectState<TDatum>, context: {
+        layout: GauntletLayout;
+        negativeProperties: Map<string, GauntletPropertyDefinition>;
+        positiveProperties: Map<string, GauntletPropertyDefinition>;
+    }) => string;
+}
+/**
+ * Fold one project's whole authored tape into its terminal state.
+ *
+ * Pure: no store, no kernel, no clock. Given the same inputs it returns the
+ * same state, which is what makes it usable for SSR and snapshot export.
+ */
+export declare function resolveGauntletTerminalState<TDatum extends Datum = Datum>(project: GauntletProjectState<TDatum>, options: GauntletTerminalOptions<TDatum>): GauntletProjectState<TDatum>;
+/** Terminal state for every project in a run. */
+export declare function resolveGauntletTerminalStates<TDatum extends Datum = Datum>(options: GauntletTerminalOptions<TDatum>): GauntletProjectState<TDatum>[];

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

@@ -0,0 +1,6 @@
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicalFlowProjectionMetadata } from "./physicsChartUtils";
+export declare function formatPhysicalFlowThroughput(value: number): string;
+export declare function physicalFlowPathD(points: PhysicalFlowProjectionMetadata["links"][number]["path"]): string;
+/** Build keyboard/reader targets from the authored throughput routes. */
+export declare function physicalFlowSemanticItems(metadata: PhysicalFlowProjectionMetadata | undefined): PhysicsSemanticItem[];

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

@@ -1,9 +1,9 @@
 import * as React from "react";
 import type { FrameGraphicsProp } from "../../stream/useFrame";
-import type { PhysicsSemanticItem, StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsBodySelection, PhysicsSemanticItem, StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { Datum } from "../shared/datumTypes";
-import type { BaseChartProps, ChartMode } from "../shared/types";
+import type { BaseChartProps, ChartMode, LinkedHoverProp, SelectionConfig } from "../shared/types";
 import { type ChartModeResult } from "../shared/hooks";
 export type PhysicsHocFrameProps<TOmitted extends keyof StreamPhysicsFrameProps = never> = Partial<Omit<StreamPhysicsFrameProps, "initialSpawns" | "initialSpawnPacing" | "size" | TOmitted>>;
 /**
@@ -18,7 +18,48 @@ export type PhysicsSharedChartProps = {
     legendPosition?: StreamPhysicsFrameProps["legendPosition"];
     legendLayout?: StreamPhysicsFrameProps["legendLayout"];
     svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+    /**
+     * Shared selection. Pass a `{ name }` config to join the selection store
+     * (cross-highlight inside `LinkedCharts`), or a resolved
+     * `{ isActive, predicate }` body predicate directly.
+     */
+    selection?: PhysicsChartSelection;
+    /** Emit hover into the shared selection store for cross-chart highlighting. */
+    linkedHover?: LinkedHoverProp;
 };
+/**
+ * What a physics HOC's `selection` prop accepts.
+ *
+ * `SelectionConfig` (`{ name }`) joins the shared selection store, so physics
+ * bodies cross-highlight inside `LinkedCharts` like every other family.
+ * `PhysicsBodySelection` (`{ isActive, predicate }`) stays available as the
+ * direct escape hatch for hosts that resolve a body predicate themselves.
+ */
+export type PhysicsChartSelection = SelectionConfig | PhysicsBodySelection | null;
+export interface PhysicsSelectionOptions {
+    selection?: PhysicsChartSelection;
+    linkedHover?: LinkedHoverProp;
+    colorBy?: unknown;
+    chartType: string;
+    chartId?: string;
+    onObservation?: BaseChartProps["onObservation"];
+    onClick?: BaseChartProps["onClick"];
+    onBodyHover?: StreamPhysicsFrameProps["onBodyHover"];
+    fallbackFields?: string[];
+    unwrapSourceDatum?: boolean;
+}
+export interface PhysicsSelectionResult {
+    selection: PhysicsBodySelection | null;
+    onBodyHover?: StreamPhysicsFrameProps["onBodyHover"];
+}
+/**
+ * Wire a physics HOC into the shared selection store.
+ *
+ * The store resolves a predicate over *data*, while the frame wants a predicate
+ * over *bodies*, so the resolved predicate is lifted through `body.datum`.
+ * Bodies with no datum (walls, pegs, chrome) never match a data selection.
+ */
+export declare function usePhysicsSelection(options: PhysicsSelectionOptions): PhysicsSelectionResult;
 /** Galton / pile sampling mode (orthogonal to ChartMode display modes). */
 export type PhysicsSimulationMode = "sample" | "mechanical";
 /** Delay between a settled physics run and a fresh seeded replay. */
@@ -128,6 +169,8 @@ export declare function resolvePhysicsFrameSharedProps(props: Pick<BaseChartProp
     legendLayout?: StreamPhysicsFrameProps["legendLayout"];
     svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
 }, frameProps: Partial<StreamPhysicsFrameProps> | undefined, semanticItems?: PhysicsSemanticItem[], modeExtras?: {
+    /** Resolved body predicate from {@link usePhysicsSelection}. */
+    selection?: PhysicsBodySelection | null;
     chartMode?: ChartMode;
     className?: string;
     title?: string;

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

@@ -0,0 +1,9 @@
+import type { Datum } from "./datumTypes";
+/**
+ * Statically detect the serializable HatchFill form styleRules can carry.
+ * Function-valued rule styles may also return hatches at runtime, but the
+ * config-only audit cannot inspect those honestly.
+ */
+export declare function hasDeclaredHatchFill(props: Datum): boolean;
+/** True only when every declared hex color belongs to the safe palette. */
+export declare function usesCvdSafePalette(colorScheme: unknown): boolean;

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

@@ -5,5 +5,5 @@
  * 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", "BumpChart", "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", "CrucibleChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "BumpChart", "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", "UnitPileChart", "CollisionSwarmChart", "GauntletChart", "CrucibleChart", "ProcessFlowChart", "PacketFlowChart", "ChainReactionChart", "BigNumber"];
 export declare function isKnownChartComponent(componentName: string): boolean;

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

@@ -1,6 +1,7 @@
 import type { Accessor } from "./types";
 import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { LegendLayout, LegendValue } from "../../types/legendTypes";
+import { type AxisChromeInput } from "../../legendLayout";
 import type { Datum } from "./datumTypes";
 /**
  * Hook to create a legend and compute margins with legend-aware adjustment.
@@ -8,7 +9,7 @@ import type { Datum } from "./datumTypes";
  * expansion pattern that every chart with color encoding repeats.
  */
 export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, chartWidth, legendLayout, hasTitle, }: {
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, chartWidth, legendLayout, hasTitle, axisChrome, }: {
     data: Array<Datum>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
@@ -25,6 +26,12 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
     legendLayout?: LegendLayout;
     /** Reserve the chart-title band above a top legend. */
     hasTitle?: boolean;
+    /**
+     * Axis chrome on the legend's side. A top/bottom legend is placed outside
+     * this band, so the reserved margin has to include it or the legend lands
+     * past the canvas edge.
+     */
+    axisChrome?: AxisChromeInput;
 }): {
     legend: LegendValue | undefined;
     margin: MarginType;

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

@@ -1,4 +1,5 @@
 import type { Datum } from "./datumTypes";
+import type { AxisChromeInput } from "../../legendLayout";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
 import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
@@ -81,6 +82,12 @@ export interface ChartSetupInput {
     height: number;
     /** Whether the resolved chart mode includes a title. */
     hasTitle?: boolean;
+    /**
+     * Bottom-axis chrome, so a bottom legend reserves space outside the tick
+     * labels rather than only being drawn past them. Omit for charts with no
+     * horizontal axis (pie/donut/radial) — the gutter resolves to 0.
+     */
+    axisChrome?: AxisChromeInput;
 }
 /**
  * Output from useChartSetup.

package/dist/components/data/portability/capabilityBinding.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bind a library-neutral IDID capability descriptor to a Semiotic runtime
+ * capability. A portable `intentScores` field is authoritative when present;
+ * omission retains the host's ranking policy.
+ *
+ * The portable descriptor intentionally cannot contain executable `fits` or
+ * `buildProps` functions. Treating it as a complete runtime capability would
+ * therefore make every dataset appear to fit, which is precisely the kind of
+ * plausible-but-unsafe recommendation the portability layer refuses to make.
+ *
+ * This binder overlays the descriptor's portable policy (rubric, intent
+ * scores, variants, caveats, and mobile contract) onto a host-resolved
+ * capability while retaining the host's executable data-fit, prop-building,
+ * scale, quality, and numeric-contract logic.
+ */
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+import { type PortableChartCapability } from "./spec";
+import type { PortabilityDiagnostic, PortabilityLoss, PortabilityProvenance, PortabilityStatus } from "./result";
+/** Runtime capability plus the exact portable descriptor that shaped it. */
+export interface BoundPortableChartCapability extends ChartCapability {
+    readonly portableDescriptor: PortableChartCapability;
+}
+/** Structured activation result; refused results never contain a capability. */
+export interface PortableCapabilityBindingResult {
+    status: PortabilityStatus;
+    capability?: BoundPortableChartCapability;
+    diagnostics: readonly PortabilityDiagnostic[];
+    lossReport: readonly PortabilityLoss[];
+    provenance: PortabilityProvenance;
+}
+/**
+ * Activate a portable descriptor against an explicitly resolved host
+ * capability.
+ *
+ * The component ids must match. The portable rubric/intent scores are
+ * authoritative for ranking; portable variants replace host variants when the
+ * field is present (an omitted variants field means no carried variants).
+ * Host `fits`, `buildProps`, numeric contracts, scale/quality gates, and
+ * dynamic caveats remain in force.
+ */
+export declare function bindPortableCapability(descriptor: unknown, host: ChartCapability | undefined): PortableCapabilityBindingResult;

package/dist/components/data/portability/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS, validatePortableCapability, validatePortableAudienceProfile, validatePortableAnnotation, } from "./spec";
 export type { BuiltInIntentId, PortableIntentId, PortableChartRubric, PortableChartVariant, PortableMobileInteractionCapability, PortableMobileLabelCapability, PortableMobileCustomCapability, PortableMobileCapability, PortableChartCapability, PortableReceptionModality, PortableAudienceTarget, PortableAudienceProfile, PortableAnnotationActorKind, PortableAnnotationSource, PortableAnnotationBasis, PortableAnnotationProvenance, PortableAnnotationFreshness, PortableAnnotationStatus, PortableAnnotationAnchor, PortableAnnotationLifecycle, PortableAnnotated, ValidationResult, } from "./spec";
+export { bindPortableCapability } from "./capabilityBinding";
+export type { BoundPortableChartCapability, PortableCapabilityBindingResult, } from "./capabilityBinding";
 export { toVegaLite, toVegaLiteResult, attachIDID, readIDID, attachIDIDAnnotations, readIDIDAnnotations, } from "./vegaLite";
 export type { IDIDVegaLiteMeta, ToVegaLiteOptions, VegaLiteExportResult, } from "./vegaLite";
 export { fromVegaLiteResult, unwrapIDIDEnrichedVegaLiteSpec, } from "../fromVegaLite";

package/dist/components/legendLayout.d.ts

@@ -17,6 +17,62 @@ export declare function resolveSideLegendWidth(legend: LegendValue | null | unde
 export declare function resolveLegendDistance(legend: LegendValue | null | undefined): number;
 /** Resolve plot-adjacent chrome reserved before a left/right legend. */
 export declare function resolveLegendSideGutter(layout?: LegendLayout): number;
+/**
+ * Height of the chrome a horizontal axis draws *outside* the plot rect, which
+ * a top/bottom legend has to clear.
+ *
+ * The axis renderers place tick labels on a baseline 18px past the axis line
+ * and an axis title at 40px (58px when ticks are rotated); each needs a few
+ * more pixels for descenders. A bottom legend anchored at `plotBottom +
+ * legendDistance` lands in exactly that band, so without this reservation the
+ * legend and the tick labels draw at the same y.
+ */
+export declare const AXIS_TICK_CHROME = 22;
+export declare const AXIS_TITLE_CHROME = 46;
+export declare const ROTATED_AXIS_TITLE_CHROME = 64;
+export interface AxisChromeInput {
+    /** A horizontal axis renders on this side of the plot. */
+    hasAxis?: boolean;
+    /** An axis title (`xLabel` / `valueLabel` / `categoryLabel`) is present. */
+    hasAxisLabel?: boolean;
+    /** Tick labels are rotated, which pushes the axis title further out. */
+    rotatedTicks?: boolean;
+}
+/**
+ * Space to reserve between the plot edge and a top/bottom legend.
+ *
+ * `legendLayout.axisGutter` is the explicit override (including `0` to opt out
+ * and restore pre-3.8.7 placement); otherwise the band is derived from the
+ * axis chrome actually being drawn, and is 0 when there is no axis on that
+ * side — so pie/donut and axes-off charts are unaffected.
+ */
+export declare function resolveAxisChromeGutter(input?: AxisChromeInput, layout?: LegendLayout): number;
+/**
+ * Resolve `axisChrome` for an XY chart HOC's `useChartLegendAndMargin` call.
+ * Mirrors `server/staticXY.tsx`'s `renderStreamXYFrame` (`hasAxis:
+ * showAxes !== false`, `hasAxisLabel: !!xLabel`) so a bottom-legend chart
+ * reserves the same margin on the client as `renderChart` does on the
+ * server — leaving either side to guess (the pre-3.8.8 default) makes the
+ * client over- or under-reserve relative to the SSR output whenever a
+ * wrapped legend pushes the reservation past the 80px floor.
+ */
+export declare function resolveXYAxisChrome(input: {
+    showAxes?: boolean;
+    xLabel?: unknown;
+}): AxisChromeInput;
+/**
+ * Resolve `axisChrome` for an ordinal chart HOC's `useChartLegendAndMargin`
+ * call. Mirrors `server/staticOrdinal.tsx`'s `renderOrdinalFrame`: the
+ * bottom axis is the value axis for `"horizontal"` projection, the category
+ * axis otherwise, and radial projections draw no axis at all. See
+ * `resolveXYAxisChrome` for why this must track the server computation.
+ */
+export declare function resolveOrdinalAxisChrome(input: {
+    showAxes?: boolean;
+    projection?: "horizontal" | "vertical" | "radial";
+    hasCategoryLabel: boolean;
+    hasValueLabel: boolean;
+}): AxisChromeInput;
 /** Estimate the layout-box height used to place a top/bottom legend. */
 export declare function resolveHorizontalLegendHeight(legend: LegendValue | null | undefined, availableWidth: number, layout?: LegendLayout): number;
 /** Margin required to fit a side legend and its plot-edge gap. */

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

@@ -0,0 +1,82 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+import type { GeoScales } from "../stream/geoTypes";
+import type { Style } from "../stream/types";
+export type GeographicDotGridShape = "circle" | "square" | "hexagon";
+export type GeographicDotGridAccessor = string | ((datum: GeographicDotGridDatum, index: number) => unknown);
+export interface GeographicDotGridDatum extends Datum {
+    /** Stable source feature identity. */
+    featureId: string;
+    /** Source feature position in the filtered areas array. */
+    featureIndex: number;
+    /** Grid position in the chart-wide lattice. */
+    gridRow: number;
+    gridColumn: number;
+    /** Geographic location obtained by inverting the sampled cell center. */
+    longitude: number;
+    latitude: number;
+    /** Stable index among the retained, in-mask dots. */
+    dotIndex: number;
+}
+export interface GeographicDotGridSampleOptions {
+    /** Approximate pixel width/height of one lattice cell. @default 10 */
+    cellSize?: number;
+    /**
+     * Alternative density control: number of lattice columns across the
+     * projected geographic bounds. Takes precedence over cellSize.
+     */
+    columns?: number;
+    /** Pixel inset applied to the geographic sampling bounds. @default 0 */
+    layoutPadding?: number;
+    /** Chart-space lattice origin. Stable origins make resize transitions predictable. */
+    gridOrigin?: [number, number];
+    /**
+     * Maximum candidate cells tested. Coarser spacing is chosen automatically
+     * when the requested lattice would exceed this guard. @default 25000
+     */
+    maxSamples?: number;
+    /** Exclude source features before their projected bounds are sampled. */
+    featureFilter?: (feature: GeoJSON.Feature, index: number) => boolean;
+    /** Exclude retained dots after feature attribution. */
+    dotFilter?: (datum: GeographicDotGridDatum, index: number) => boolean;
+}
+export interface GeographicDotGridConfig extends GeographicDotGridSampleOptions {
+    /** Geometry emitted for each occupied lattice cell. @default "circle" */
+    shape?: GeographicDotGridShape;
+    /** Radius in pixels. Overrides radiusRatio. */
+    dotRadius?: number;
+    /** Radius as a fraction of cellSize. @default 0.24 */
+    radiusRatio?: number;
+    /** Direct fill field/function. categoryAccessor + the chart palette is used otherwise. */
+    fillAccessor?: GeographicDotGridAccessor;
+    categoryAccessor?: GeographicDotGridAccessor;
+    /** Additional per-dot style. */
+    markStyle?: Style | ((datum: GeographicDotGridDatum, index: number) => Style);
+    /** Draw faint source boundaries over the dot field. @default false */
+    showOutline?: boolean;
+    outlineStyle?: Style;
+}
+interface GeographicDotGridSampleResult {
+    dots: GeographicDotGridDatum[];
+    cellSize: number;
+    features: GeoJSON.Feature[];
+}
+/**
+ * Sample fitted geographic polygons onto a chart-space lattice.
+ *
+ * Each candidate cell center is inverted through the active projection and
+ * retained only when it falls inside a source feature. The result is useful
+ * independently of React for inspecting density or composing custom layouts.
+ */
+export declare function sampleGeographicDotGrid(areas: GeoJSON.Feature[], scales: Pick<GeoScales, "geoPath" | "invertedPoint">, dimensions: {
+    width: number;
+    height: number;
+}, options?: GeographicDotGridSampleOptions): GeographicDotGridSampleResult;
+/**
+ * Polygon-to-lattice mask for `GeoCustomChart`.
+ *
+ * Unlike a tile cartogram, this retains the projected land silhouette: every
+ * occupied screen-space grid cell becomes a small circle, square, or hexagon.
+ */
+export declare const geographicDotGridLayout: GeoCustomLayout<GeographicDotGridConfig>;
+export {};

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

@@ -0,0 +1,100 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+import type { Style } from "../stream/types";
+export type GeographicGridShape = "circle" | "square" | "hexagon";
+export type GeographicGridSource = "auto" | "areas" | "points";
+export interface GeographicGridInput<T = Datum> {
+    datum: T;
+    /** Source-space x coordinate. Longitude or projected x both work. */
+    x: number;
+    /** Source-space y coordinate. Latitude or projected y both work. */
+    y: number;
+}
+export interface GridifiedGeographicPoint<T = Datum> extends GeographicGridInput<T> {
+    row: number;
+    column: number;
+}
+export interface GridifyGeographicPointsOptions {
+    /** Number of grid columns. Inferred from count and aspect ratio by default. */
+    columns?: number;
+    /** Number of grid rows. Inferred from count and occupancy by default. */
+    rows?: number;
+    /**
+     * Target fraction of grid cells occupied when rows are inferred.
+     * Extra cells preserve coastline/continental whitespace. @default 0.72
+     */
+    occupancy?: number;
+    /** Width / height of the intended display. @default 1.8 */
+    aspectRatio?: number;
+}
+type GridAccessor<T> = string | ((datum: T) => unknown);
+export interface GeographicGridConfig {
+    /** Prefer area features, point rows, or whichever source is populated. @default "auto" */
+    source?: GeographicGridSource;
+    /**
+     * Explicit grid placement. When both accessors return finite values, the
+     * authored table is used instead of automatic geographic gridification.
+     */
+    rowAccessor?: GridAccessor<Datum>;
+    columnAccessor?: GridAccessor<Datum>;
+    /** Geographic point accessors used by automatic point gridification. */
+    longitudeAccessor?: GridAccessor<Datum>;
+    latitudeAccessor?: GridAccessor<Datum>;
+    idAccessor?: GridAccessor<Datum>;
+    labelAccessor?: GridAccessor<Datum>;
+    categoryAccessor?: GridAccessor<Datum>;
+    /**
+     * Optional quantitative size encoding. Mark area is proportional to this
+     * value; omit it for equal-area geographic units.
+     */
+    sizeAccessor?: GridAccessor<Datum>;
+    /** Explicit size domain. Inferred from finite values by default. */
+    sizeDomain?: [number, number];
+    /**
+     * Minimum/maximum mark radius as fractions of the available cell radius.
+     * @default [0.36, 1]
+     */
+    sizeRange?: [number, number];
+    /** Direct fill field/function. categoryAccessor + the chart palette is used otherwise. */
+    fillAccessor?: GridAccessor<Datum>;
+    /** Additional per-mark style. */
+    markStyle?: Style | ((datum: Datum, index: number) => Style);
+    /** Mark geometry. @default "circle" */
+    shape?: GeographicGridShape;
+    /** Grid columns for automatic placement. */
+    columns?: number;
+    /** Grid rows for automatic placement. */
+    rows?: number;
+    /** Target automatic-grid occupancy. @default 0.72 */
+    occupancy?: number;
+    /** Fraction of each cell reserved between marks. @default 0.12 */
+    cellPadding?: number;
+    /** Pixel inset around the complete grid. @default 8 */
+    layoutPadding?: number;
+    /** Render labels over marks. @default true */
+    showLabels?: boolean;
+    labelColor?: string;
+    labelFontSize?: number;
+    labelFontFamily?: string;
+    labelFontWeight?: number | string;
+    /** Maximum visible label length. @default 4 */
+    maxLabelLength?: number;
+    /** Exclude records before placement. */
+    filter?: (datum: Datum, index: number) => boolean;
+}
+/**
+ * Snap geographic/projected points to unique cells while preserving their
+ * coarse relative position. Edge points claim cells first, leaving central
+ * clusters to absorb most of the unavoidable displacement.
+ */
+export declare function gridifyGeographicPoints<T>(input: GeographicGridInput<T>[], options?: GridifyGeographicPointsOptions): GridifiedGeographicPoint<T>[];
+/**
+ * Geographic table/cartogram layout for `GeoCustomChart`.
+ *
+ * It accepts either authored row/column positions (state tile grids and other
+ * known cartograms) or automatically gridifies projected point/area centroids.
+ * Every result remains a native Geo scene node, retaining canvas rendering,
+ * SSR, hit testing, keyboard navigation, tooltips, and shared selection.
+ */
+export declare const geographicGridLayout: GeoCustomLayout<GeographicGridConfig>;
+export {};

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

@@ -120,3 +120,5 @@ export type { BodyGroupSpec, BodyGroupSpecOptions, ProcessMembraneDef, ProcessRe
 export type { RegionCountBucket, RegionCountMap } from "./processAggregates";
 export type { ProcessVolumePoint, ProcessVolumePolygon, ProcessVolumePolygonRole } from "./processVolumeGeometry";
 export type { ProcessJourneyEntityState, ProcessJourneyLedger, ProcessJourneyRow, ProcessJourneyStage, ProcessJourneyUpdateOptions } from "./processJourney";
+export { describePhysicsStageGeography, physicsChargePoint, physicsDestination, physicsStageColliders, physicsStageGeography } from "./physicsStageGeography";
+export type { PhysicsDestinationZone, PhysicsStageColliderOptions, PhysicsStageGeography, PhysicsStageGeographyOptions, PhysicsZone } from "./physicsStageGeography";