semiotic 3.7.4 → 3.8.0

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

@@ -0,0 +1,166 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { NetworkSymbolName } from "../stream/symbolPath";
+/**
+ * Config for {@link packedClusterMatrix}. Accessors read `node.data.<field>`
+ * (the ingest wrapper) and fall back to the node itself.
+ */
+export interface PackedClusterMatrixConfig {
+    /** Categorical field → matrix column. @default "column" */
+    columnAccessor?: string;
+    /** Categorical field → matrix row (stacked within a column). @default "row" */
+    rowAccessor?: string;
+    /** Numeric field → glyph size (area-encoded). Constant size when omitted. */
+    sizeAccessor?: string;
+    /** Categorical field → glyph hue (via `ctx.resolveColor`). */
+    colorAccessor?: string;
+    /** Fixed hue per category value. Wins over `ctx.resolveColor` for mapped keys —
+     *  the right choice for editorial graphics with a semantic palette. */
+    colorMap?: Record<string, string>;
+    /** Categorical field → glyph shape. Auto-assigned shapes when no `symbolMap`. */
+    symbolAccessor?: string;
+    /** Numeric/date field → lightness shade of the hue (the fourth channel). */
+    shadeAccessor?: string;
+    /** Boolean field → small center dot on the glyph (e.g. a flagged subset). */
+    markerAccessor?: string;
+    /** Explicit column order; otherwise columns sort by count, largest first. */
+    columnOrder?: string[];
+    /** Explicit row order **bottom→top**; otherwise rows sort by count, largest at bottom. */
+    rowOrder?: string[];
+    /** Map a class value to a named glyph (the base mark BECOMES that shape).
+     *  Unmapped values get auto-assigned. Mutually exclusive with `iconAccessor`. */
+    symbolMap?: Record<string, NetworkSymbolName>;
+    /** Shape when no `symbolAccessor` is set. @default "circle" */
+    defaultSymbol?: NetworkSymbolName;
+    /** Categorical field whose value selects an OPTIONAL stroked icon drawn inside
+     *  the (filled circle) base mark — the "most marks are plain circles, a few
+     *  carry an icon" model. Only values present in `iconMap` get an icon. */
+    iconAccessor?: string;
+    /** Map an icon-field value to a glyph. Values omitted here render as a plain
+     *  circle (no icon) — so a single dominant class stays unmarked. */
+    iconMap?: Record<string, NetworkSymbolName>;
+    /** Stroke color of the inner icon. @default "rgba(255,255,255,0.92)" */
+    iconColor?: string;
+    /** Inner-icon stroke width. @default 1 */
+    iconStrokeWidth?: number;
+    /** Inner-icon size as a fraction of the base circle radius. @default 0.72 */
+    iconScale?: number;
+    /** Glyph radius range in px (area = πr²). @default [2, 8] */
+    sizeRange?: [number, number];
+    /** Size value domain. @default data extent */
+    sizeDomain?: [number, number];
+    /** Cap total glyph area at this fraction of the plot; radii scale down to fit
+     *  (keeps clusters packable / non-overlapping on smaller canvases). @default 0.4 */
+    maxAreaFraction?: number;
+    /** How far the shade travels from the base hue (0..1). @default 0.72 */
+    shadeStrength?: number;
+    /** Shade value domain. @default data extent (dates auto-parsed) */
+    shadeDomain?: [number, number];
+    /** Flip the shade ramp (default: low → light, high → dark). */
+    shadeReverse?: boolean;
+    /** Row layout. `"banded"`: orbit rows are aligned global bands (one y-range
+     *  spanning all columns → row labels align, one enclosure per band spans the
+     *  columns, a column is only as tall as its highest occupied band). `"stacked"`:
+     *  each column stacks its own rows independently (cell height ∝ that column's
+     *  count; rows do NOT align). @default "banded" */
+    rowMode?: "banded" | "stacked";
+    /** `"proportional"` (mosaic: cell area ∝ count) or `"uniform"` grid. @default "proportional" */
+    cellSizing?: "proportional" | "uniform";
+    /** Exponent applied to counts when sizing columns/cells. `1` = strict area ∝
+     *  count; `<1` softens the range so small columns stay legible. @default 1 */
+    proportionExponent?: number;
+    /** Gap between columns in px. @default 16 */
+    columnGap?: number;
+    /** Gap between stacked cells in px. @default 12 */
+    rowGap?: number;
+    /** Collision padding between glyphs in px. @default 1 */
+    packPadding?: number;
+    /** Relaxation passes for the packing (capped at 14; a near-uniform seed needs
+     *  few). Higher = tidier/slower. @default 12 */
+    iterations?: number;
+    /** Draw a rounded enclosure hugging each cluster. @default true */
+    showEnclosures?: boolean;
+    enclosureColor?: string;
+    enclosureRadius?: number;
+    enclosureOpacity?: number;
+    enclosureWidth?: number;
+    /** Column header labels across the top. @default true */
+    showColumnHeaders?: boolean;
+    /** Row labels down the left. @default true */
+    showRowLabels?: boolean;
+    columnLabel?: (col: string) => string;
+    rowLabel?: (row: string) => string;
+    headerColor?: string;
+    labelColor?: string;
+    headerFontSize?: number;
+    labelFontSize?: number;
+    /** Top space reserved for headers. @default 26 */
+    headerHeight?: number;
+    /** Left space reserved for row labels. @default 66 */
+    labelWidth?: number;
+    /** Bottom margin reserved for callout labels (only when `callouts` is set). @default 30 */
+    footerHeight?: number;
+    markStroke?: string;
+    markStrokeWidth?: number;
+    /** Center-dot color for `markerAccessor` hits. @default "#ffffff" */
+    markerColor?: string;
+    /** Dim every glyph that doesn't match the highlight. A single `{field,value}`
+     *  or an array (AND — a glyph must match all to stay lit, e.g. a region×orbit
+     *  cell). Drives legend / nav-tree highlighting. */
+    highlight?: {
+        field: string;
+        value: string;
+    } | {
+        field: string;
+        value: string;
+    }[] | null;
+    /** Opacity for dimmed glyphs. @default 0.16 */
+    dimOpacity?: number;
+    /** Editorial leader-line callouts to specific marks. Each picks the first mark
+     *  whose `datum[field] === value` and draws a ring + connector + label. `at`
+     *  places the label: a y in [0,1] of the plot ("1" = bottom) and the label
+     *  tracks the mark's x, or an explicit `{x,y}` in plot px. */
+    callouts?: Array<{
+        field: string;
+        value: string;
+        label: string;
+        at?: number | {
+            x: number;
+            y: number;
+        };
+        connector?: "straight" | "elbow" | "curve";
+    }>;
+    calloutColor?: string;
+}
+/**
+ * `packedClusterMatrix` — a reusable network layout that arranges a flat set of
+ * records into a **matrix of densely-packed clusters**: one column per value of
+ * `columnAccessor`, cells stacked within a column per value of `rowAccessor`,
+ * each cell a beeswarm of variable-radius glyphs. In `"proportional"` sizing the
+ * column widths and cell heights track counts (a mosaic), so a cell's area is
+ * proportional to its record count and packing density stays roughly uniform.
+ *
+ * Each record renders as a **four-channel glyph**: shape (`symbolAccessor`),
+ * hue (`colorAccessor`), size (`sizeAccessor`, area-encoded), and lightness
+ * shade (`shadeAccessor`). Packing is deterministic (seeded `d3-force`) and the
+ * geometry is cached, so hover/selection/filter re-runs re-style without
+ * re-packing. Built to recreate small-multiples beeswarm graphics (e.g. Nadieh
+ * Bremer's "Satellites in Space").
+ *
+ * @example
+ * ```tsx
+ * import { NetworkCustomChart } from "semiotic/network"
+ * import { packedClusterMatrix } from "semiotic/recipes"
+ *
+ * <NetworkCustomChart
+ *   nodes={satellites}            // each: { id, region, orbit, mass, category, klass, launch }
+ *   layout={packedClusterMatrix}
+ *   colorScheme={categoryColors}
+ *   layoutConfig={{
+ *     columnAccessor: "region", rowAccessor: "orbit",
+ *     sizeAccessor: "mass", colorAccessor: "category",
+ *     symbolAccessor: "klass", shadeAccessor: "launch",
+ *   }}
+ * />
+ * ```
+ */
+export declare const packedClusterMatrix: NetworkCustomLayout<PackedClusterMatrixConfig>;

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[];
+}>;

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

@@ -0,0 +1,67 @@
+/**
+ * Process-physics chrome kit — stage bays, capacity badges, absorb basins,
+ * feature sockets, and flow spines for ProcessFlow / custom process layouts.
+ *
+ * Theme via CSS vars (with solid fallbacks so chrome never goes blank):
+ *   --semiotic-process-floor, --semiotic-process-lane, --semiotic-process-border
+ *   --semiotic-process-text, --semiotic-process-muted
+ *   --semiotic-success / warning / danger / info for semantic stage roles
+ */
+import * as React from "react";
+export interface ProcessChromeStage {
+    id: string;
+    label: string;
+    x0: number;
+    x1: number;
+    x: number;
+    width: number;
+    count?: number;
+    capacity?: number;
+    /** Reader-facing capacity badge; defaults to the numeric `cap` label. */
+    capacityLabel?: string;
+    /** Override stage badges without hiding capacity badges across the layout. */
+    showBadge?: boolean;
+    absorb?: boolean;
+    portalTarget?: string;
+    queueDepth?: number;
+    processed?: number;
+}
+export interface ProcessChromeGroup {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+    absorbed?: number;
+    total?: number;
+    complete?: boolean;
+}
+export interface ProcessChromeLayout {
+    width: number;
+    height: number;
+    left: number;
+    right: number;
+    topY: number;
+    bottomY: number;
+    midY: number;
+    stages: readonly ProcessChromeStage[];
+    groups?: readonly ProcessChromeGroup[];
+}
+export interface ProcessChromeOptions {
+    showFlowSpine?: boolean;
+    showStageCounts?: boolean;
+    showCapacityBadges?: boolean;
+    showGroupSockets?: boolean;
+    /** Fit stage labels to the stage band instead of drawing fixed-width pills. */
+    stageLabelMode?: "auto" | "full" | "compact" | "none";
+    /**
+     * When true, stage bays are stroke-only (transparent fill) so particles
+     * and paired charts remain visible through the gate geometry.
+     */
+    outlineStages?: boolean;
+    testId?: string;
+}
+/**
+ * SVG process chrome for overlays / backgroundGraphics.
+ * Pure presentational — call from ProcessFlowChart or PhysicsCustomChart.
+ */
+export declare function processChrome(layout: ProcessChromeLayout, options?: ProcessChromeOptions): React.ReactElement;

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

@@ -0,0 +1,54 @@
+/**
+ * Serializable stage-journey state derived from physics region events.
+ *
+ * Keep this reducer independent from a live physics runtime so authors can
+ * replay, compare, persist, and project the same event stream deterministically.
+ */
+import type { StreamPhysicsRegionEvent } from "../stream/physics/StreamPhysicsFrame";
+export interface ProcessJourneyStage {
+    id: string;
+    label?: string;
+}
+export interface ProcessJourneyEntityState {
+    id: string;
+    currentStageId?: string;
+    furthestStageId?: string;
+    furthestStageIndex: number;
+    visitedStageIds: string[];
+    visitsByStage: Record<string, number>;
+    firstEnteredAt: Record<string, number>;
+    lastEnteredAt: Record<string, number>;
+    regressionCount: number;
+}
+export interface ProcessJourneyLedger {
+    stages: ProcessJourneyStage[];
+    bodyIds: string[];
+    entities: Record<string, ProcessJourneyEntityState>;
+}
+type ProcessJourneyRegionEvent = Pick<StreamPhysicsRegionEvent, "bodyId" | "datum" | "region">;
+export interface ProcessJourneyUpdateOptions {
+    entityId?: (event: ProcessJourneyRegionEvent) => string;
+    stageId?: (event: ProcessJourneyRegionEvent) => string | undefined;
+}
+export interface ProcessJourneyRow {
+    id: string;
+    label: string;
+    reached: number;
+    entered: number;
+    total: number;
+    conversion: number;
+    fromPrevious: number;
+    dropoff: number;
+    visits: number;
+    repeatVisits: number;
+}
+/** Create serializable journey state for a known or initially empty cohort. */
+export declare function createProcessJourneyLedger(options: {
+    stages: readonly ProcessJourneyStage[];
+    bodyIds?: readonly string[];
+}): ProcessJourneyLedger;
+/** Reduce a stage-region enter into unique reach and visit-aware entity state. */
+export declare function updateProcessJourney(previous: ProcessJourneyLedger, event: Pick<StreamPhysicsRegionEvent, "type" | "bodyId" | "datum" | "observation" | "region">, options?: ProcessJourneyUpdateOptions): ProcessJourneyLedger;
+/** Convert a live journey ledger into stable stage reach and conversion rows. */
+export declare function processJourneyRows(ledger: ProcessJourneyLedger): ProcessJourneyRow[];
+export {};