semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,88 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+export type LandmarkKind = "city" | "culture" | "monument" | "faith" | "nature" | "knowledge" | "defense" | "arena" | "transport";
+export type IsometricTerrainKind = "land" | "ocean" | "forest" | "grassland" | "cropland" | "wetland" | "urban" | "scrub" | "bare" | "snow";
+export interface IsometricTerrainCell {
+    kind: IsometricTerrainKind;
+    /** Fraction of the geographic cell covered by this terrain, from 0 to 1. */
+    coverage?: number;
+    /** Optional per-cell color override. */
+    fill?: string;
+}
+export interface IsometricLandmarkConfig {
+    /** Geographic center represented by the middle grid cell. */
+    center: {
+        lon: number;
+        lat: number;
+    };
+    /** Datum id forced into the middle cell. */
+    centerId?: string;
+    /** Odd number of rows/columns. @default 5 */
+    gridSize?: number;
+    /** Half-width of the local square represented by the board. @default 75 */
+    gridRadiusKm?: number;
+    /** Isometric tile dimensions in pixels. @default 80×40 */
+    tileWidth?: number;
+    tileHeight?: number;
+    /** Source-data accessors. */
+    idAccessor?: string | ((d: Datum) => string);
+    nameAccessor?: string | ((d: Datum) => string);
+    longitudeAccessor?: string | ((d: Datum) => number);
+    latitudeAccessor?: string | ((d: Datum) => number);
+    kindAccessor?: string | ((d: Datum) => LandmarkKind);
+    /** Lower values win when live and fallback candidates share a cell. */
+    candidatePriorityAccessor?: string | ((d: Datum) => number);
+    /** Optional replacement sprite URLs. Transparent PNGs work best. */
+    sprites?: Partial<Record<LandmarkKind, string>>;
+    /** Rendered resource sprite size. @default 32 */
+    resourceSpriteSize?: number;
+    /** Rendered major-city sprite size. @default 64 */
+    citySpriteSize?: number;
+    /** Civ-style terrain palette. */
+    terrainColors?: string[];
+    /** Geographic terrain classification keyed by `tile-{row}-{column}`. */
+    terrainByCell?: Record<string, IsometricTerrainKind | IsometricTerrainCell>;
+    /** Civ-style colors used for classified terrain cells. */
+    terrainPalette?: Partial<Record<IsometricTerrainKind, string>>;
+    tileStroke?: string;
+    showCityLabel?: boolean;
+}
+export interface IsometricLandmarkTile {
+    id: string;
+    row: number;
+    column: number;
+    centerXKm: number;
+    centerYKm: number;
+    terrainIndex: number;
+    landmark: (Datum & {
+        id: string;
+        name: string;
+        kind: LandmarkKind;
+        lon: number;
+        lat: number;
+        distanceKm: number;
+    }) | null;
+    /** All candidates assigned to the cell, with the displayed landmark first. */
+    landmarks: Array<Datum & {
+        id: string;
+        name: string;
+        kind: LandmarkKind;
+        lon: number;
+        lat: number;
+        distanceKm: number;
+    }>;
+}
+export declare const DEFAULT_ISOMETRIC_SPRITE_SIZES: {
+    readonly resource: 32;
+    readonly city: 64;
+};
+/**
+ * Quantize geographic landmarks into an odd square grid and choose one
+ * representative per cell. Selection balances proximity to the cell center
+ * with category reuse so a dense class does not consume the whole board.
+ */
+export declare function selectIsometricLandmarks(points: Datum[], config: IsometricLandmarkConfig): IsometricLandmarkTile[];
+/**
+ * Isometric landmark board for `GeoCustomChart`.
+ */
+export declare const isometricLandmarkLayout: GeoCustomLayout<IsometricLandmarkConfig>;

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

@@ -0,0 +1,17 @@
+import type { GlyphDef } from "../stream/glyphDef";
+export declare const isotypeInk = "#334155";
+export declare const isotypePaper = "#f8fafc";
+export declare const isotypeGhost = "#cbd5e1";
+export declare const isotypeServerGlyph: GlyphDef;
+export declare const isotypeChipGlyph: GlyphDef;
+export declare const isotypeBoltGlyph: GlyphDef;
+export declare const isotypeBusGlyph: GlyphDef;
+export declare const isotypePersonPath = "M 9.12,3.34 C 8.28,3.29 7.44,3.40 6.64,3.69 4.17,3.63 1.97,5.37 0.91,7.51 -1.32,11.80 2.55,17.76 8.19,16.55 11.62,16.13 15.55,14.04 16.17,10.33 16.38,6.53 12.77,3.52 9.12,3.34 Z M 9.35,19.86 C 8.89,19.84 8.41,19.92 7.92,20.11 5.12,21.55 3.72,24.68 2.79,27.54 2.32,29.86 0.87,32.04 1.36,34.49 1.63,37.60 8.04,38.95 8.04,38.95 8.04,38.95 14.67,39.65 16.50,36.33 17.16,31.95 16.34,27.23 14.01,23.42 13.07,21.69 11.36,19.92 9.35,19.86 Z";
+export declare const isotypePersonGlyph: GlyphDef;
+export declare const isotypeNetworkGlyphs: {
+    readonly server: GlyphDef;
+    readonly chip: GlyphDef;
+    readonly bolt: GlyphDef;
+    readonly bus: GlyphDef;
+    readonly person: GlyphDef;
+};

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

@@ -0,0 +1,48 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type MobileAnnotationStrategyMode = "plot" | "callout-list" | "hybrid";
+export interface MobileAnnotationStrategyConfig {
+    /** Activate the strategy explicitly. When omitted, width/breakpoint decides. */
+    active?: boolean;
+    /** Measured plot/container width in CSS pixels. */
+    width?: number;
+    /** Width at or below which the strategy activates. Default 480. */
+    breakpoint?: number;
+    /** Plot-only, list-only, or hybrid visible-plus-list behavior. Default "hybrid". */
+    strategy?: MobileAnnotationStrategyMode;
+    /** Maximum persistent note annotations left in the plot. Alias: maxAnnotations. */
+    maxPlotAnnotations?: number;
+    maxAnnotations?: number;
+    /** Minimum number of note annotations kept in the plot. Default 1. */
+    minPlotAnnotations?: number;
+    minVisible?: number;
+    /** Maximum callout-list items. Default 6. */
+    maxCalloutItems?: number;
+    /** Keep primary/emergency notes in the plot before lower-priority notes. Default true. */
+    preservePrimary?: boolean;
+    /** Prefer mobileText/shortText over full label. Default true. */
+    preferShortText?: boolean;
+    /** Field or function used as an explicit priority score. */
+    priorityAccessor?: string | ((annotation: Datum, index: number) => number | undefined);
+    /** Optional filter for annotations that should move into the callout list. */
+    calloutFilter?: (annotation: Datum, index: number) => boolean;
+}
+export interface MobileAnnotationCalloutItem {
+    id: string;
+    label: string;
+    shortLabel?: string;
+    pointId?: string | number;
+    emphasis?: string;
+    source?: string;
+    priority: number;
+    annotation: Datum;
+}
+export interface MobileAnnotationStrategyResult {
+    active: boolean;
+    strategy: MobileAnnotationStrategyMode;
+    budget: number;
+    visible: Datum[];
+    deferred: Datum[];
+    calloutList: MobileAnnotationCalloutItem[];
+    hidden: Datum[];
+}
+export declare function mobileAnnotationStrategy(annotations: readonly Datum[] | undefined, config?: MobileAnnotationStrategyConfig): MobileAnnotationStrategyResult;

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

@@ -0,0 +1,59 @@
+import type { ResponsiveRule } from "../charts/shared/responsiveRules";
+import type { MobileInteractionConfig, MobileSnapBehavior, MobileStandardControlsMode } from "../charts/shared/types";
+import type { MobileVisualizationContract } from "../charts/shared/auditMobileVisualization";
+export type MobileChartFamily = "line" | "area" | "ordinal" | "scatter" | "network" | "geo" | "small-multiple";
+export interface MobileChartFamilyRecipeOptions {
+    breakpoint?: number;
+    targetSize?: number;
+    mode?: "mobile" | false;
+    density?: "comfortable" | "compact" | "dense";
+    transformProfile?: "overview" | "compare" | "inspect";
+    keepAxes?: boolean;
+    showLegend?: boolean;
+    directLabel?: boolean;
+    maxAnnotations?: number;
+    maxCalloutItems?: number;
+    chartHeight?: number;
+    mobileColumns?: number;
+    tabletColumns?: number;
+    snap?: MobileSnapBehavior;
+    standardControls?: MobileStandardControlsMode;
+    summary?: string;
+}
+export interface MobileChartFamilyRecipe {
+    family: MobileChartFamily;
+    props: Record<string, unknown>;
+    responsiveRules: ResponsiveRule<Record<string, unknown>>[];
+    mobileInteraction: MobileInteractionConfig;
+    mobileSemantics: MobileVisualizationContract;
+}
+export declare function mobileLineChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileAreaChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileOrdinalChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileScatterplotRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileNetworkChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileGeoChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileSmallMultipleRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileChartFamilyRecipe(family: MobileChartFamily, options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export interface MobileBrushAlternativeOptions {
+    targetSize?: number;
+    controls?: Array<"range-inputs" | "chip-filter" | "clear" | "stepper">;
+    summary?: string;
+}
+export declare function mobileBrushAlternatives(options?: MobileBrushAlternativeOptions): {
+    mobileInteraction: {
+        enabled: boolean;
+        targetSize: number;
+        tapToSelect: boolean;
+        tapToLockTooltip: boolean;
+        standardControls: "brush";
+    };
+    mobileSemantics: {
+        interaction: {
+            primary: "filter";
+            alternatives: ("clear" | "range-inputs" | "chip-filter" | "stepper")[];
+            summary: string;
+        };
+    };
+    controls: ("clear" | "range-inputs" | "chip-filter" | "stepper")[];
+};

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

@@ -0,0 +1,102 @@
+/**
+ * Network-analysis kit — pure graph algorithms for network visualizations.
+ *
+ * These are the primitives most network charts end up hand-rolling: adjacency,
+ * breadth-first distances, shortest paths, ego networks, degree / betweenness /
+ * closeness centrality, clustering coefficient, and the "spatial problem"
+ * detector (nodes drawn closer than their graph distance warrants). They pair
+ * naturally with `ForceDirectedGraph`, `NetworkCustomChart`, and the layout
+ * recipes: size nodes by centrality, highlight an ego network on hover, trace a
+ * shortest path, or diagnose a misleading layout.
+ *
+ * All functions are pure and dependency-free. Edges are treated as undirected.
+ */
+export interface GraphNode {
+    id: string;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    value?: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Build an undirected adjacency map: node id → set of neighbor ids. */
+export declare function buildAdjacency(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Map<string, Set<string>>;
+/**
+ * Build a **directed** adjacency map: node id → set of successor ids, following
+ * `source → target` only. The directed sibling of {@link buildAdjacency}, for
+ * DAG / flow / dependency graphs where edge direction carries meaning.
+ */
+export declare function buildDirectedAdjacency(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Map<string, Set<string>>;
+/**
+ * The set of nodes reachable from `start` by following the adjacency (BFS).
+ * Works on either an undirected ({@link buildAdjacency}) or directed
+ * ({@link buildDirectedAdjacency}) adjacency map.
+ *
+ * `start` itself is excluded unless it is reachable via a cycle, or
+ * `includeStart` is set — so on a DAG this is exactly the descendant set, and
+ * on a cyclic graph a node that can reach itself is reported as such.
+ */
+export declare function reachableFrom(adjacency: Map<string, Set<string>>, start: string, options?: {
+    includeStart?: boolean;
+}): Set<string>;
+/** Degree (neighbor count) per node id. */
+export declare function degree(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/** Breadth-first hop distance from `start` to every reachable node. */
+export declare function bfsDistances(adjacency: Map<string, Set<string>>, start: string): Record<string, number>;
+/**
+ * Unweighted shortest path between two node ids (BFS). Returns the path as an
+ * ordered list of ids (inclusive of both ends), or `[]` if unreachable.
+ */
+export declare function shortestPath(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, source: string, target: string): string[];
+/**
+ * The ego network of a node: itself plus every node within `depth` hops.
+ * Returns the set of member ids (use it to highlight neighbors on hover).
+ */
+export declare function egoNetwork(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, id: string, depth?: number): Set<string>;
+/**
+ * Betweenness centrality (Brandes' algorithm, unweighted, undirected). Higher
+ * scores mark bridge nodes that many shortest paths pass through. Raw scores;
+ * wrap with {@link normalizeScores} for a 0–1 encoding (e.g. node size).
+ */
+export declare function betweenness(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/**
+ * Closeness centrality: the inverse of the mean shortest-path distance to all
+ * reachable nodes. Higher = more central. Raw scores; see {@link normalizeScores}.
+ */
+export declare function closeness(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/**
+ * Local clustering coefficient per node (0–1): the fraction of a node's
+ * neighbor pairs that are themselves connected.
+ */
+export declare function clustering(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/** Rescale a score map to 0–1 by its maximum (for size/opacity encodings). */
+export declare function normalizeScores(scores: Record<string, number>): Record<string, number>;
+export interface ProximityProblemOptions {
+    /** Minimum graph-hop distance for a pair to count as "far". @default 4 */
+    minHops?: number;
+    /** Starting screen-distance threshold (in the units of `positions`). @default 0.08 */
+    startThreshold?: number;
+    /** Cap the threshold search at this distance before relaxing `minHops`. @default 0.2 */
+    maxThreshold?: number;
+}
+export interface ProximityProblemResult {
+    /** Ids drawn misleadingly close given their graph distance. */
+    problemIds: Set<string>;
+    /** The screen-distance threshold at which offenders were found. */
+    threshold: number;
+    /** The graph-hop distance used. */
+    minHops: number;
+}
+/**
+ * The "spatial problem": find nodes drawn near each other on screen yet far
+ * apart (or disconnected) in the graph — proximity pretending to be kinship,
+ * the classic force-layout lie. `positions` is a map of node id → screen point
+ * (any consistent coordinate space; distances are compared in those units).
+ * The search escalates the distance threshold, then relaxes `minHops`, until at
+ * least one offending pair is found.
+ */
+export declare function proximityProblem(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, positions: Record<string, Point>, options?: ProximityProblemOptions): ProximityProblemResult;

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

@@ -0,0 +1,83 @@
+/**
+ * Deterministic, physics-free network layouts — the classic static forms that
+ * predate (and often out-read) the force-directed hairball: the arc diagram,
+ * the adjacency matrix, and the circular layout.
+ *
+ * These are composable positioner / structure helpers (not full scene layouts):
+ * they return normalized positions or a matrix structure that you render inside
+ * a `NetworkCustomChart` layout, so you keep full control of styling. Pure and
+ * dependency-free.
+ */
+import type { GraphNode, GraphEdge, Point } from "./networkAnalysis";
+/**
+ * Order node ids by community/group then descending degree, so related nodes sit
+ * together and hubs lead — the ordering that makes arc diagrams and adjacency
+ * matrices legible. Pass `groupAccessor` to read the grouping field (default
+ * `"group"`); nodes without one are ordered by degree alone.
+ */
+export declare function orderByGroupDegree<N extends GraphNode>(nodes: ReadonlyArray<N>, edges: ReadonlyArray<GraphEdge>, groupAccessor?: keyof N | ((n: N) => number | string)): string[];
+export interface ArcLayoutOptions {
+    /** Baseline y position in [0, 1]. @default 0.62 */
+    baseline?: number;
+    /** Horizontal inset kept clear at each end, in [0, 0.5). @default 0.06 */
+    inset?: number;
+}
+/**
+ * Arc diagram: lay the ordered ids out along a horizontal baseline. Draw each
+ * edge as an arc with {@link arcPath}. Returns id → {x, y} in [0, 1].
+ */
+export declare function arcLayout(ids: ReadonlyArray<string>, options?: ArcLayoutOptions): Record<string, Point>;
+/**
+ * An SVG path string for an arc between two points that share a baseline (as in
+ * an arc diagram). The arc bows away from the baseline by `heightRatio` of the
+ * span. Coordinates are whatever space you pass (typically already projected
+ * into the plot).
+ */
+export declare function arcPath(a: Point, b: Point, heightRatio?: number): string;
+export interface CircularLayoutOptions {
+    /** Ring radius in [0, 0.5]. @default 0.42 */
+    radius?: number;
+    /** Center point in [0, 1]. @default { x: 0.5, y: 0.5 } */
+    center?: Point;
+    /** Start angle in radians (0 = up). @default 0 */
+    startAngle?: number;
+}
+/**
+ * Circular layout: place the ordered ids evenly around a ring. Position carries
+ * no meaning (edges cross the interior) — offered mainly as a labeled, stable
+ * arrangement. Returns id → {x, y} in [0, 1].
+ */
+export declare function circularLayout(ids: ReadonlyArray<string>, options?: CircularLayoutOptions): Record<string, Point>;
+export interface MatrixCell {
+    /** Row index (into the ordered id list). */
+    row: number;
+    /** Column index. */
+    col: number;
+    source: string;
+    target: string;
+    /** Summed edge value between the pair (defaults to 1 per edge). */
+    value: number;
+}
+export interface AdjacencyMatrix {
+    /** The ordered ids used for rows and columns. */
+    order: string[];
+    /** One cell per connected (i, j) pair, both triangles (symmetric). */
+    cells: MatrixCell[];
+    /** Number of rows/columns (`order.length`). */
+    size: number;
+    /** Maximum cell value (for opacity/intensity encoding). */
+    maxValue: number;
+}
+export interface AdjacencyMatrixOptions {
+    /** Explicit row/column order; defaults to {@link orderByGroupDegree}. */
+    order?: ReadonlyArray<string>;
+    /** Group accessor used when computing the default order. @default "group" */
+    groupAccessor?: keyof GraphNode | ((n: GraphNode) => number | string);
+}
+/**
+ * Adjacency matrix structure: every connection becomes a filled cell, so nothing
+ * overlaps and dense graphs stay legible. Returns the ordered ids plus the cell
+ * list; render each cell at `(col, row)` in your layout. Symmetric (both
+ * triangles filled); the diagonal is omitted.
+ */
+export declare function adjacencyMatrix(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, options?: AdjacencyMatrixOptions): AdjacencyMatrix;

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

@@ -0,0 +1,122 @@
+import type { VisualToken } from "./tokenEncoding";
+import { type PhysicsBoundsColliderOptions, type PhysicsPlotBounds, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions, type PhysicsXBinColliderOptions } from "../stream/physics/PhysicsPipelineStore";
+import type { PhysicsBodyShape, PhysicsColliderSpec } from "../stream/physics/PhysicsKernel";
+import type { PhysicsSedimentBinSnapshot, PhysicsSedimentColumn, PhysicsSedimentHeightfieldOptions } from "../stream/physics/PhysicsSediment";
+export type NumericScale = (value: number) => number;
+export type BandScale<T = string | number> = ((value: T) => number | undefined) & {
+    bandwidth?: () => number;
+};
+export interface PhysicsScaleColliderOptions<TBand = string | number> {
+    plot: PhysicsPlotBounds;
+    idPrefix?: string;
+    bounds?: false | PhysicsBoundsColliderOptions;
+    xBins?: Omit<PhysicsXBinColliderOptions, "idPrefix" | "yTop" | "yBottom"> & {
+        idPrefix?: string;
+        yTop?: number;
+        yBottom?: number;
+    };
+    xBands?: PhysicsBandColliderOptions<TBand>;
+    yBands?: PhysicsBandColliderOptions<TBand>;
+}
+export interface PhysicsBandColliderOptions<TBand = string | number> {
+    values: readonly TBand[];
+    scale: BandScale<TBand>;
+    bandwidth?: number;
+    wallThickness?: number;
+    includeBoundaryWalls?: boolean;
+    includeInteriorWalls?: boolean;
+    idPrefix?: string;
+}
+export interface GaltonPegsOptions {
+    plot: PhysicsPlotBounds;
+    rows: number;
+    columns?: number;
+    pegRadius?: number;
+    idPrefix?: string;
+    yStart?: number;
+    yEnd?: number;
+    stagger?: boolean;
+    restitution?: number;
+    friction?: number;
+}
+export interface SpawnFromTokensOptions<D = unknown> {
+    idPrefix?: string;
+    x?: number | ((token: VisualToken<D>, index: number) => number);
+    y?: number | ((token: VisualToken<D>, index: number) => number);
+    radius?: number | ((token: VisualToken<D>, index: number) => number);
+    shape?: PhysicsBodyShape | ((token: VisualToken<D>, index: number) => PhysicsBodyShape);
+    mass?: number | ((token: VisualToken<D>, index: number) => number);
+    vx?: number | ((token: VisualToken<D>, index: number) => number);
+    vy?: number | ((token: VisualToken<D>, index: number) => number);
+    jitter?: number | {
+        x?: number;
+        y?: number;
+    };
+    seed?: number;
+    spawnAt?: number | ((token: VisualToken<D>, index: number) => number);
+    datum?: (token: VisualToken<D>, index: number) => unknown;
+}
+export interface SedimentBakeOptions extends PhysicsSedimentHeightfieldOptions {
+    idPrefix?: string;
+    collider?: boolean;
+    colliderThickness?: number;
+    restitution?: number;
+    friction?: number;
+}
+export interface SedimentBakeResult {
+    columns: PhysicsSedimentColumn[];
+    colliders: PhysicsColliderSpec[];
+}
+export interface ArrivalReplayOptions {
+    timeAccessor?: string | ((spawn: PhysicsQueuedSpawn, index: number) => unknown);
+    timeScale?: number;
+    startAt?: number;
+    rebase?: boolean;
+    sort?: boolean;
+}
+/**
+ * Build chart-aligned static colliders from a plot rectangle plus optional
+ * continuous bins or band-scale lanes.
+ */
+export declare function collidersFromScales<TBand = string | number>(options: PhysicsScaleColliderOptions<TBand>): PhysicsColliderSpec[];
+/**
+ * Generate deterministic square peg colliders for Galton/Plinko-style custom
+ * layouts. Square AABBs are intentional: they work with the built-in kernel's
+ * small default collider vocabulary while still reading as point pegs.
+ */
+export declare function galtonPegs(options: GaltonPegsOptions): PhysicsColliderSpec[];
+/**
+ * Convert visual tokens into physics body spawns. Pair with
+ * `generateTokens()` / `layoutTokenGrid()` for HOPs, unitized piles, or
+ * posterior-sample demos inside `PhysicsCustomChart`.
+ */
+export declare function spawnFromTokens<D = unknown>(tokens: readonly VisualToken<D>[], options?: SpawnFromTokensOptions<D>): PhysicsQueuedSpawn[];
+/**
+ * Turn sediment snapshots into drawable columns and optional static colliders.
+ * Use the columns for overlays and the colliders when old data should become
+ * a physical resting surface for live bodies.
+ */
+export declare function sedimentBake(bins: PhysicsSedimentBinSnapshot[], options?: SedimentBakeOptions): SedimentBakeResult;
+/**
+ * Prepare initial spawns for event-time/arrival-time replay. The returned
+ * object spreads directly into a `PhysicsCustomChart` layout result.
+ */
+export declare function arrivalReplay(spawns: readonly PhysicsQueuedSpawn[], options?: ArrivalReplayOptions): {
+    initialSpawns: PhysicsQueuedSpawn[];
+    initialSpawnPacing: PhysicsSpawnPacingOptions;
+};
+export type { PhysicsColliderSpec, PhysicsPlotBounds, PhysicsQueuedSpawn, PhysicsSedimentBinSnapshot, PhysicsSedimentColumn, PhysicsSedimentHeightfieldOptions, PhysicsSpawnPacingOptions };
+export { absorbRegion, bodyGroupSpec, capacitatedRegion, chargeGateRegion, forceFieldRegion, membraneRegion, portalRegion, pressureFieldRegion, processLaneWalls, processStageLayout, processStageRegions, routeSurfaceRegion, stageTargetInVolume } from "./processPhysics";
+export { aggregateRegionCounts, groupCompletionRows, regionCountsToProjectionRows } from "./processAggregates";
+export { processVolumePolygons } from "./processVolumeGeometry";
+export { comparePhysicsTrace, physicsReferenceEnvelope } from "./physicsReference";
+export type { PhysicsReferenceBandSelector, PhysicsReferenceEnvelope, PhysicsReferenceEnvelopeOptions, PhysicsReferenceEnvelopePoint, PhysicsReferenceSampleGrid, PhysicsReferenceTrace, PhysicsScalarTraceSample, PhysicsTraceAccessor, PhysicsTraceComparison, PhysicsTraceComparisonOptions, PhysicsTraceComparisonPoint, PhysicsTraceComparisonStatus, PhysicsTraceInterpolation, PhysicsTraceOutsideDomain } from "./physicsReference";
+export { createProcessJourneyLedger, processJourneyRows, updateProcessJourney } from "./processJourney";
+export { composePhysicsControllers, createCapacityQueueController, createPortalController, createDependencyGateController, createServiceLevelController, createServiceResourcePoolController } from "../stream/physics/PhysicsControllers";
+export type { CapacityQueueAbandonedInfo, CapacityQueueAgeSummary, CapacityQueueBlockedInfo, CapacityQueueControllerOptions, CapacityQueueProcessedInfo, CapacityQueueSnapshot, CapacityQueueVisitInfo, CapacityQueueWindowSnapshot, ComposedPhysicsControllers, DependencyGateController, DependencyGateOptions, DependencyGateSnapshot, PhysicsController, PhysicsControllerTickContext, ServiceLevelCaseInfo, ServiceLevelCaseState, ServiceLevelController, ServiceLevelControllerOptions, ServiceLevelSnapshot, ServiceResourceAssignment, ServiceResourceDefinition, ServiceResourcePoolController, ServiceResourcePoolOptions, ServiceResourcePoolSnapshot } from "../stream/physics/PhysicsControllers";
+export { processChrome } from "./processChrome";
+export type { ProcessChromeGroup, ProcessChromeLayout, ProcessChromeOptions, ProcessChromeStage } from "./processChrome";
+export type { BodyGroupSpec, BodyGroupSpecOptions, ProcessMembraneDef, ProcessRegionBaseOptions, ProcessStageRegionOptions, ProcessStageDef, ProcessVolumeLayout, ProcessVolumeLayoutOptions, ProcessVolumeMembraneBand, ProcessVolumeShape, ProcessVolumeStageBand } from "./processPhysics";
+export type { RegionCountBucket, RegionCountMap } from "./processAggregates";
+export type { ProcessVolumePoint, ProcessVolumePolygon, ProcessVolumePolygonRole } from "./processVolumeGeometry";
+export type { ProcessJourneyEntityState, ProcessJourneyLedger, ProcessJourneyRow, ProcessJourneyStage, ProcessJourneyUpdateOptions } from "./processJourney";

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

@@ -0,0 +1,102 @@
+/**
+ * Pure reference-envelope helpers for physics evidence traces.
+ *
+ * Physics motion does not provide its own baseline. These helpers align
+ * repeated or supplied scalar traces onto one clock, summarize their
+ * distribution, and compare a live trace with the resulting reference band.
+ */
+export type PhysicsTraceInterpolation = "step" | "linear";
+export type PhysicsTraceOutsideDomain = "omit" | "clamp";
+export type PhysicsTraceAccessor<TSample> = string | ((sample: TSample, index: number, traceId: string) => unknown);
+export interface PhysicsReferenceTrace<TSample = PhysicsScalarTraceSample> {
+    id: string;
+    samples: readonly TSample[];
+}
+export interface PhysicsScalarTraceSample {
+    time: number;
+    value: number;
+}
+export type PhysicsReferenceSampleGrid = readonly number[] | {
+    start: number;
+    end: number;
+    step: number;
+};
+export interface PhysicsReferenceEnvelopeOptions<TSample> {
+    runs: readonly PhysicsReferenceTrace<TSample>[];
+    sampleAt: PhysicsReferenceSampleGrid;
+    timeAccessor?: PhysicsTraceAccessor<TSample>;
+    valueAccessor?: PhysicsTraceAccessor<TSample>;
+    /** Quantiles use the R-7 linear estimator. Defaults to 0.1, 0.5, and 0.9. */
+    quantiles?: readonly number[];
+    interpolation?: PhysicsTraceInterpolation;
+    /** Whether values outside each run's authored domain are omitted or held. */
+    outsideDomain?: PhysicsTraceOutsideDomain;
+}
+export interface PhysicsReferenceEnvelopePoint {
+    time: number;
+    count: number;
+    min: number | null;
+    max: number | null;
+    median: number | null;
+    /** Keys are normalized decimal quantiles, for example `quantiles[0.9]`. */
+    quantiles: Partial<Record<number, number | null>>;
+}
+export interface PhysicsReferenceEnvelope {
+    points: PhysicsReferenceEnvelopePoint[];
+    quantiles: number[];
+    interpolation: PhysicsTraceInterpolation;
+    outsideDomain: PhysicsTraceOutsideDomain;
+    runCount: number;
+}
+export type PhysicsReferenceBandSelector = "min" | "median" | "max" | number;
+export type PhysicsTraceComparisonStatus = "below" | "inside" | "above" | "unobserved";
+export interface PhysicsTraceComparisonPoint {
+    time: number;
+    value: number | null;
+    lower: number | null;
+    upper: number | null;
+    status: PhysicsTraceComparisonStatus;
+}
+export interface PhysicsTraceComparisonOptions<TSample> {
+    timeAccessor?: PhysicsTraceAccessor<TSample>;
+    valueAccessor?: PhysicsTraceAccessor<TSample>;
+    /** Defaults to the envelope's interpolation. */
+    interpolation?: PhysicsTraceInterpolation;
+    /** Defaults to the envelope's outside-domain policy. */
+    outsideDomain?: PhysicsTraceOutsideDomain;
+    /** Defaults to the envelope's lowest quantile, then `min`. */
+    lower?: PhysicsReferenceBandSelector;
+    /** Defaults to the envelope's highest quantile, then `max`. */
+    upper?: PhysicsReferenceBandSelector;
+    /** Identifier supplied to function accessors. Defaults to `trace`. */
+    traceId?: string;
+}
+export interface PhysicsTraceComparison {
+    points: PhysicsTraceComparisonPoint[];
+    sampleCount: number;
+    observedSamples: number;
+    belowSamples: number;
+    insideSamples: number;
+    aboveSamples: number;
+    totalDuration: number;
+    observedDuration: number;
+    unobservedDuration: number;
+    belowDuration: number;
+    insideDuration: number;
+    aboveDuration: number;
+    peakExcess: number;
+    peakExcessAt: number | null;
+    peakDeficit: number;
+    peakDeficitAt: number | null;
+}
+/**
+ * Align irregular scalar traces to a common clock and derive a deterministic
+ * quantile envelope. Invalid samples are omitted; inputs are never mutated.
+ */
+export declare function physicsReferenceEnvelope<TSample = PhysicsScalarTraceSample>(options: PhysicsReferenceEnvelopeOptions<TSample>): PhysicsReferenceEnvelope;
+/**
+ * Compare one irregular trace with a reference envelope. Durations use
+ * left-held intervals for step traces and exact linear boundary crossings for
+ * linear traces. Equality with either band edge is inside the reference.
+ */
+export declare function comparePhysicsTrace<TSample = PhysicsScalarTraceSample>(trace: readonly TSample[], envelope: PhysicsReferenceEnvelope, options?: PhysicsTraceComparisonOptions<TSample>): PhysicsTraceComparison;

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

@@ -0,0 +1,32 @@
+/** Pure settled projections derived from physics events and body groups. */
+import type { StreamPhysicsRegionEvent } from "../stream/physics/StreamPhysicsFrame";
+import type { BodyGroupSpec } from "./processPhysics";
+export interface RegionCountBucket {
+    id: string;
+    label?: string;
+    count: number;
+    bodyIds: string[];
+}
+export type RegionCountMap = Record<string, RegionCountBucket>;
+/** Reduce region-enter events into per-region unique body counts. */
+export declare function aggregateRegionCounts(previous: RegionCountMap, event: Pick<StreamPhysicsRegionEvent, "type" | "bodyId" | "region">): RegionCountMap;
+export declare function regionCountsToProjectionRows(counts: RegionCountMap, order?: readonly string[]): Array<{
+    label: string;
+    value: number;
+}>;
+/**
+ * Group-completion ledger for all-members, any-member, and weighted-threshold
+ * stories. Pure: callers supply which member ids have been absorbed.
+ */
+export declare function groupCompletionRows(groups: readonly BodyGroupSpec[], absorbedBodyIds: ReadonlySet<string> | readonly string[]): Array<{
+    id: string;
+    label: string;
+    mode: "allMembersAbsorbed" | "anyAbsorbed" | "threshold";
+    complete: boolean;
+    absorbed: number;
+    total: number;
+    absorbedValue: number;
+    totalValue: number;
+    threshold?: number;
+    missing: string[];
+}>;