semiotic 3.7.5 → 3.8.0

package/dist/components/stream/networkTypes.d.ts

@@ -2,11 +2,12 @@ import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
 import type { LegendGroup, LegendLayout } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, SceneDatum, SceneAccessibilityMetadata } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { NetworkSymbolName } from "./symbolPath";
+import type { GlyphDef } from "./glyphDef";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -52,6 +53,8 @@ export interface RealtimeNode {
     __hierarchyNode?: unknown;
     /** @internal Circle-pack layout radius. Set by `hierarchyLayoutPlugin`. */
     __radius?: number;
+    /** @internal Pre-resolved force-layout radius used by worker snapshots. */
+    __forceRadius?: number;
     /**
      * @internal Chord-layout extension. Carries the start/end angles
      * for the arc segment representing this node, computed by
@@ -182,7 +185,7 @@ export interface RealtimeNetworkFrameProps {
     showParticles?: boolean;
     particleStyle?: ParticleStyle;
     colorBy?: string | ((d: RealtimeNode) => string);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     edgeColorBy?: "source" | "target" | ((d: RealtimeEdge) => string);
     edgeOpacity?: number;
     nodeLabel?: string | ((d: RealtimeNode) => string);
@@ -205,6 +208,8 @@ export interface NetworkCircleNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -221,6 +226,8 @@ export interface NetworkRectNode {
     h: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -242,6 +249,8 @@ export interface NetworkArcNode {
     endAngle: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     _pulseIntensity?: number;
@@ -268,6 +277,47 @@ export interface NetworkSymbolNode {
     rotation?: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
+    id?: string;
+    label?: string;
+    depth?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}
+/**
+ * Glyph node — the composite-pictogram channel for network scenes: a
+ * multi-part `GlyphDef` stamped at (cx, cy) with per-node `color`/`accent`
+ * paints and optional partial fill. The network sibling of the XY/ordinal/geo
+ * `GlyphSceneNode`.
+ */
+export interface NetworkGlyphNode {
+    type: "glyph";
+    cx: number;
+    cy: number;
+    /** Rendered height in px — width follows the definition's viewBox aspect. */
+    size: number;
+    /** The multi-part pictogram definition to stamp. */
+    glyph: GlyphDef;
+    /** Primary paint for parts declaring `"color"`. Falls back to `style.fill`. */
+    color?: string;
+    /** Accent paint for parts declaring `"accent"`. */
+    accent?: string;
+    /** Partial fill 0–1. @default 1 */
+    fraction?: number;
+    /** Where the partial fill begins, 0–1. @default 0 */
+    fractionStart?: number;
+    /** Partial-fill axis. @default "horizontal" */
+    fractionDirection?: "horizontal" | "vertical";
+    /** Ghost paint drawn at full extent beneath a partial fill. */
+    ghostColor?: string;
+    /** Rotation in radians about (cx, cy). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     id?: string;
     label?: string;
     depth?: number;
@@ -333,7 +383,7 @@ export interface NetworkCurvedEdge {
     _cachedPath2D?: Path2D;
     _cachedPath2DSource?: string;
 }
-export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode;
+export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode | NetworkGlyphNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
 /** Label data for the SVG overlay */
 export interface NetworkLabel {
@@ -410,6 +460,8 @@ export interface NetworkPipelineConfig {
     edgeSort?: (a: unknown, b: unknown) => number;
     iterations?: number;
     forceStrength?: number;
+    /** @internal Skip simulation after worker-computed positions are applied. */
+    __skipForceSimulation?: boolean;
     padAngle?: number;
     groupWidth?: number;
     sortGroups?: (a: unknown, b: unknown) => number;
@@ -426,7 +478,7 @@ export interface NetworkPipelineConfig {
     showLabels?: boolean;
     labelMode?: "leaf" | "parent" | "all";
     colorBy?: string | ((d: Datum) => string | number);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
     themeCategorical?: string[];
     /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
@@ -479,6 +531,8 @@ export interface NetworkPipelineConfig {
     /** When provided, replaces both layout dispatch and scene building.
      *  Receives raw nodes/edges and returns positioned scene primitives. */
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** Called when `customNetworkLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared-selection predicate, surfaced to a custom layout as
@@ -508,6 +562,12 @@ export interface StreamNetworkFrameProps<T = Datum> {
     nodeWidth?: number;
     iterations?: number;
     forceStrength?: number;
+    /** Execute force layout synchronously, in a worker, or choose by graph cost. */
+    layoutExecution?: "auto" | "worker" | "sync";
+    /** Content displayed while an internally-managed worker layout is pending. */
+    layoutLoadingContent?: ReactNode | false;
+    /** Receives internally-managed force-layout lifecycle changes. */
+    onLayoutStateChange?: (state: "pending" | "ready" | "error") => void;
     padAngle?: number;
     groupWidth?: number;
     sortGroups?: (a: unknown, b: unknown) => number;
@@ -522,7 +582,7 @@ export interface StreamNetworkFrameProps<T = Datum> {
     nodeStyle?: (d: Datum) => Datum;
     edgeStyle?: (d: Datum) => Datum;
     colorBy?: string | ((d: Datum) => string | number);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     edgeOpacity?: number;
     colorByDepth?: boolean;
@@ -597,6 +657,8 @@ export interface StreamNetworkFrameProps<T = Datum> {
      *  Receives raw nodes/edges + dimensions/theme, returns positioned scene
      *  primitives. See `semiotic/recipes` for reference layouts (flextree, dagre). */
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
+    /** Called when `customNetworkLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared-selection predicate, surfaced to a custom layout as
@@ -628,5 +690,14 @@ export interface StreamNetworkFrameHandle {
     };
     relayout(): void;
     getTension(): number;
+    /** The most recent custom layout result (sceneNodes/sceneEdges/overlays as
+     *  returned by `customNetworkLayout`) — host readback so pages that need the
+     *  computed placement don't re-run the layout. Null before the first layout
+     *  or when no custom layout is configured. A failed retry retains the prior
+     *  good result; inspect `getLayoutFailure()` to distinguish recovery. */
+    getCustomLayout(): import("./networkCustomLayout").NetworkLayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by a successful layout,
+     * removing the custom layout, or `clear()`. */
+    getLayoutFailure(): import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
 }
 export type NetworkRendererFn = (ctx: CanvasRenderingContext2D, nodes: NetworkSceneNode[], edges: NetworkSceneEdge[], size: [number, number]) => void;

package/dist/components/stream/ordinalCanvasRenderers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Chart-type → canvas renderer dispatch for StreamOrdinalFrame.
+ * Connectors are always included when the chart type builds them into the scene.
+ */
+import type { OrdinalChartType } from "./ordinalTypes";
+export type OrdinalAnyRendererFn = (ctx: CanvasRenderingContext2D, nodes: any[], scales: any, layout: any) => void;
+export declare const ORDINAL_CANVAS_RENDERERS: Record<OrdinalChartType, OrdinalAnyRendererFn[]>;

package/dist/components/stream/ordinalDataIndex.d.ts

@@ -0,0 +1,5 @@
+import type { Datum } from "../charts/shared/datumTypes";
+type CategoryAccessor = string | ((datum: Datum) => string) | undefined;
+/** Build the source-data category index used by aggregate pulse marks. */
+export declare function buildOrdinalCategoryIndex(data: readonly Datum[], categoryAccessor: CategoryAccessor): Map<string, number[]>;
+export {};

package/dist/components/stream/ordinalDefaultTooltip.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default ordinal hover tooltip for StreamOrdinalFrame.
+ * Uses shared `defaultTooltipStyle` for theme CSS-var consistency.
+ */
+import * as React from "react";
+import type { HoverData } from "./ordinalTypes";
+declare function DefaultOrdinalTooltip({ hover }: {
+    hover: HoverData;
+}): React.JSX.Element | null;
+export { DefaultOrdinalTooltip };

package/dist/components/stream/ordinalDomain.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure ordinal domain + column projection helpers for OrdinalPipelineStore.
+ */
+import type { ScaleBand } from "d3-scale";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { OrdinalColumn, OrdinalLayout, OrdinalPipelineConfig } from "./ordinalTypes";
+export interface OrdinalValueDomainInput {
+    data: Datum[];
+    chartType: OrdinalPipelineConfig["chartType"];
+    projection?: OrdinalPipelineConfig["projection"];
+    normalize?: boolean;
+    rExtent?: OrdinalPipelineConfig["rExtent"];
+    extentPadding?: number;
+    baselinePadding?: boolean;
+    axisExtent?: OrdinalPipelineConfig["axisExtent"];
+    getO: (d: Datum) => string;
+    getR: (d: Datum) => number;
+    getStack?: (d: Datum) => string;
+    /** IncrementalExtent-style [min, max]; Infinity/-Infinity when empty. */
+    rawRExtent: [number, number];
+}
+/**
+ * Compute the ordinal value (r) domain from data + chart type rules.
+ * Pure: no store mutation; callers supply accessors and raw extent.
+ */
+export declare function computeOrdinalValueDomain(input: OrdinalValueDomainInput): [number, number];
+export interface BuildOrdinalColumnsInput {
+    data: Datum[];
+    oExtent: string[];
+    oScale: ScaleBand<string>;
+    projection: string;
+    layout: OrdinalLayout;
+    dynamicColumnWidth?: OrdinalPipelineConfig["dynamicColumnWidth"];
+    getO: (d: Datum) => string;
+    getR: (d: Datum) => number;
+}
+/** Project band scale + data into per-category column geometry. */
+export declare function buildOrdinalColumns(input: BuildOrdinalColumnsInput): Record<string, OrdinalColumn>;

package/dist/components/stream/ordinalPipelineUpdateResults.d.ts

@@ -0,0 +1,12 @@
+import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
+/** Result bookkeeping and invalidation policy for the Ordinal store pilot. */
+export declare class OrdinalPipelineUpdateResults {
+    private tracker;
+    get last(): UpdateResult;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[]): UpdateResult;
+}
+export {};

package/dist/components/stream/ordinalPulse.d.ts

@@ -0,0 +1,10 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { RingBuffer } from "../realtime/RingBuffer";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PulseConfig } from "./types";
+/**
+ * Apply pulse-derived fields to ordinal scene nodes without rebuilding their
+ * layout. Wedges aggregate their category's source data; other supported
+ * nodes map directly to one source datum.
+ */
+export declare function applyOrdinalPulse(pulse: PulseConfig, nodes: OrdinalSceneNode[], timestampBuffer: RingBuffer<number>, datumIndex: ReadonlyMap<Datum, number>, getCategoryIndices: (category: string) => number[] | undefined, now: number): boolean;

package/dist/components/stream/ordinalPulseResources.d.ts

@@ -0,0 +1,3 @@
+import type { RingBuffer } from "../realtime/RingBuffer";
+/** Keep a pulse timestamp ring aligned with the retained ordinal data. */
+export declare function syncOrdinalPulseTimestampBuffer<T>(pulseEnabled: boolean, buffer: RingBuffer<T>, timestamps: RingBuffer<number> | null, timestamp: number): RingBuffer<number> | null;

package/dist/components/stream/ordinalSceneBuilders/sceneBuilderMap.d.ts

@@ -0,0 +1,5 @@
+/**
+ * chartType → pure scene builder dispatch for OrdinalPipelineStore.
+ */
+import type { SceneBuilderFn } from "./types";
+export declare const ORDINAL_SCENE_BUILDERS: Record<string, SceneBuilderFn>;

package/dist/components/stream/ordinalSpatialIndex.d.ts

@@ -0,0 +1,9 @@
+import { type Quadtree } from "d3-quadtree";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PointSceneNode } from "./types";
+export interface OrdinalPointSpatialIndex {
+    readonly maxRadius: number;
+    readonly quadtree: Quadtree<PointSceneNode> | null;
+}
+/** Build the optional point-hit index for large ordinal point scenes. */
+export declare function buildOrdinalPointSpatialIndex(scene: readonly OrdinalSceneNode[]): OrdinalPointSpatialIndex;

package/dist/components/stream/ordinalTypes.d.ts

@@ -3,7 +3,7 @@ import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
-import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
+import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
@@ -54,6 +54,8 @@ export interface WedgeSceneNode {
     };
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     category?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -163,9 +165,9 @@ export interface TrapezoidSceneNode {
     _targetOpacity?: number;
     _transitionKey?: string;
 }
-export type { Style, PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
-import type { PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
-export type OrdinalSceneNode = RectSceneNode | PointSceneNode | SymbolSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
+export type { Style, PointSceneNode, RectSceneNode, SymbolSceneNode, GlyphSceneNode } from "./types";
+import type { PointSceneNode, RectSceneNode, SymbolSceneNode, GlyphSceneNode } from "./types";
+export type OrdinalSceneNode = RectSceneNode | PointSceneNode | SymbolSceneNode | GlyphSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
 export interface OrdinalColumn {
     name: string;
     x: number;
@@ -205,6 +207,13 @@ export interface OrdinalPipelineConfig {
     oAccessor?: string | ((d: Datum) => string);
     /** @deprecated Use valueAccessor */
     rAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
+    /**
+     * Escape hatch for a *stable* function accessor whose captured semantics
+     * change without its identity changing. Accessor equality is identity-based,
+     * so such a change is otherwise invisible. Bump this number to force the
+     * store to re-resolve accessors, rebuild the category domain, and reset value
+     * extents. Prefer changing the accessor identity where you can. */
+    accessorRevision?: number;
     multiAxis?: boolean;
     rExtent?: [number?, number?];
     oExtent?: string[];
@@ -254,7 +263,7 @@ export interface OrdinalPipelineConfig {
     dynamicColumnWidth?: string | ((data: Datum[]) => number);
     pieceStyle?: (d: Datum, category?: string) => Style;
     summaryStyle?: (d: Datum, category?: string) => Style;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     themeCategorical?: string[];
     /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
     themeSemantic?: ThemeSemanticColors;
@@ -275,6 +284,8 @@ export interface OrdinalPipelineConfig {
      *  Receives an OrdinalLayoutContext (scales, dimensions, theme,
      *  resolveColor) and returns scene nodes plus optional overlays. */
     customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
+    /** Called when `customLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved margin — passed through so OrdinalLayoutContext.dimensions.margin
@@ -304,6 +315,12 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     oAccessor?: string | ((d: T) => string);
     /** @deprecated Use valueAccessor instead */
     rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    /**
+     * Force category/value re-derivation when a stable accessor's external
+     * semantics changed without a new function identity. Prefer changing the
+     * accessor reference where possible.
+     */
+    accessorRevision?: number;
     multiAxis?: boolean;
     projection?: "vertical" | "horizontal" | "radial";
     size?: [number, number];
@@ -369,7 +386,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
     pieceStyle?: (d: Datum, category?: string) => Style;
     summaryStyle?: (d: Datum, category?: string) => Style;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     barColors?: Record<string, string>;
     showAxes?: boolean;
     showCategoryTicks?: boolean;
@@ -393,6 +410,7 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
     customHoverBehavior?: (d: HoverData | null) => void;
+    customClickBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
@@ -416,8 +434,12 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     legendCategoryAccessor?: string | ((d: T) => string);
     /** Fires when the current legend category domain changes after scene rebuilds. */
     onCategoriesChange?: (categories: string[]) => void;
-    backgroundGraphics?: ReactNode;
-    foregroundGraphics?: ReactNode;
+    /** SVG behind the canvas. Function form receives `{ size, margin, scales }`
+     *  with the frame's resolved `{o, r, projection}` scales (null pre-layout). */
+    backgroundGraphics?: FrameGraphicsProp<OrdinalScales>;
+    /** SVG on top (in the overlay). Function form receives `{ size, margin, scales }`
+     *  with the frame's resolved `{o, r, projection}` scales (null pre-layout). */
+    foregroundGraphics?: FrameGraphicsProp<OrdinalScales>;
     title?: string | ReactNode;
     className?: string;
     background?: string;
@@ -450,6 +472,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
      *  `semiotic/recipes` for reference layouts (marimekko, parallel
      *  coordinates, bullet). */
     customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
+    /** Called when `customLayout` throws. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: object;
     /** Resolved shared selection projected into `OrdinalLayoutContext.selection`.
@@ -480,6 +504,14 @@ export interface StreamOrdinalFrameHandle<T = Datum> {
     clear(): void;
     getData(): T[];
     getScales(): OrdinalScales | null;
+    /** The most recent custom layout result — host readback so pages that need
+     *  the computed placement don't re-run the layout. Null before the first
+     *  layout or when no custom layout is configured. A failed retry retains the
+     *  prior good result; inspect `getLayoutFailure()` to distinguish recovery. */
+    getCustomLayout(): import("./ordinalCustomLayout").OrdinalLayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by a successful layout,
+     * removing the custom layout, or `clear()`. */
+    getLayoutFailure(): import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
 }
 export interface OrdinalLayout {
     width: number;

package/dist/components/stream/paintNeeds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared paint-gate helpers for Stream Frame render loops.
+ *
+ * Frames differ in scene types, but the decision "should this rAF clear and
+ * redraw the data canvas?" is the same shape everywhere: dirty/scene rebuild,
+ * transition, continuous animation, particles, live encodings.
+ */
+export interface DataPaintNeedsInput {
+    /** Prop/layout dirty or scene rebuilt this frame. */
+    dirtyOrRebuilt: boolean;
+    /** Transition animation is advancing. */
+    transitioning: boolean;
+    /** Layout animation tick (orbit, force step, etc.). */
+    animationTicked?: boolean;
+    /** Particles / continuous mode wants a frame. */
+    continuous?: boolean;
+    /** Pulse / decay / threshold / topology-diff encodings are live. */
+    liveEncoding?: boolean;
+    /** Family-specific force (rotation applied, zoom, etc.). */
+    forced?: boolean;
+}
+/**
+ * True when the data canvas should clear and redraw this frame.
+ * Interaction-only or annotation-only rAF retries should leave data alone.
+ */
+export declare function needsDataCanvasPaint(input: DataPaintNeedsInput): boolean;
+/**
+ * True when an interaction overlay canvas should clear/draw.
+ * Pass `hadContentLastFrame` so a hover-end still gets one clear.
+ */
+export declare function needsInteractionCanvasPaint(active: boolean, hadContentLastFrame: boolean): boolean;

package/dist/components/stream/physics/CapacityQueueController.d.ts

@@ -0,0 +1,5 @@
+/** FIFO capacity-queue controller: stateful region service riding StreamPhysicsFrame's live heartbeat. */
+import type { PhysicsController } from "./PhysicsControllers";
+import type { CapacityQueueControllerOptions } from "./CapacityQueueTypes";
+/** FIFO region service with visit evidence, overflow staging, and live metrics. */
+export declare function createCapacityQueueController(options: CapacityQueueControllerOptions): PhysicsController;

package/dist/components/stream/physics/CapacityQueueTypes.d.ts

@@ -0,0 +1,134 @@
+import type { PhysicsBodyState, PhysicsColliderBodyFilter } from "./PhysicsKernel";
+import type { StreamPhysicsRegionVector } from "./StreamPhysicsFrame";
+/** Current age distribution for visits admitted to a capacity queue. */
+export interface CapacityQueueAgeSummary {
+    count: number;
+    meanSeconds: number;
+    p50Seconds: number;
+    p95Seconds: number;
+    oldestSeconds: number;
+}
+/** Rolling simulated-time service evidence. */
+export interface CapacityQueueWindowSnapshot {
+    seconds: number;
+    arrivals: number;
+    arrivalWork: number;
+    completions: number;
+    completedWork: number;
+    processedWork: number;
+    arrivalsPerSecond: number;
+    throughputPerSecond: number;
+    /** Service work consumed / available work capacity, clamped to 0-1. */
+    utilization: number;
+    /** Incoming work rate / service rate. Values above 1 indicate overload. */
+    pressure: number;
+}
+/** Live capacity queue metrics for projection, evidence, and UI. */
+export interface CapacityQueueSnapshot {
+    regionId: string;
+    queueDepth: number;
+    processedCount: number;
+    unitsPerSecond: number;
+    /** Remaining work units currently in the admitted queue. */
+    remainingWork: number;
+    meanRemainingWork: number;
+    /** Current admitted + blocked work still waiting for service. */
+    waitingWork: number;
+    blockedDepth: number;
+    blockedWork: number;
+    /** Unique physical entries observed, including entries initially blocked. */
+    arrivalCount: number;
+    admittedCount: number;
+    admittedWork: number;
+    /** Cumulative service work consumed, including partially processed jobs. */
+    processedWork: number;
+    completedWork: number;
+    blockedCount: number;
+    abandonedCount: number;
+    abandonedWork: number;
+    peakQueueDepth: number;
+    peakRemainingWork: number;
+    queueAge: CapacityQueueAgeSummary;
+    meanCompletedQueueSeconds: number;
+    window: CapacityQueueWindowSnapshot;
+    /** Latest simulated clock observed by the controller. */
+    simulatedAt: number;
+    /** Coarse reporting bucket suitable for React equality checks. */
+    metricRevision: number;
+}
+export interface CapacityQueueVisitInfo {
+    bodyId: string;
+    jobId: string;
+    visitId: string;
+    visit: number;
+    regionId: string;
+    work: number;
+    queuedAt: number;
+}
+export interface CapacityQueueProcessedInfo extends CapacityQueueVisitInfo {
+    completedAt: number;
+    queueSeconds: number;
+}
+export interface CapacityQueueBlockedInfo extends CapacityQueueVisitInfo {
+    blockedAt: number;
+}
+export interface CapacityQueueAbandonedInfo extends CapacityQueueVisitInfo {
+    abandonedAt: number;
+    remainingWork: number;
+    queueSeconds: number;
+}
+export interface CapacityQueueControllerOptions {
+    id?: string;
+    /** Must match a StreamPhysicsRegionEffect id (sensor region). */
+    regionId: string;
+    /** Work units processed per second while the queue is non-empty. */
+    unitsPerSecond: number;
+    /** Only matching bodies may enter the queue. Uses collider body-filter semantics. */
+    bodyFilter?: PhysicsColliderBodyFilter;
+    /** String form reads `body.datum[field]`; defaults to work/reviewWork/value. */
+    unitAccessor?: string | ((body: PhysicsBodyState) => number);
+    /**
+     * Semantic job identity. String form reads `body.datum[field]`; defaults to
+     * body id. Multiple matching bodies with the same key consume one visit.
+     */
+    jobKey?: string | ((body: PhysicsBodyState) => string | number | null | undefined);
+    /** Impulse applied when a body finishes processing (default forward release). */
+    releaseImpulse?: StreamPhysicsRegionVector;
+    onProcessed?: (body: PhysicsBodyState, info: CapacityQueueProcessedInfo) => void;
+    onQueued?: (body: PhysicsBodyState, info: CapacityQueueVisitInfo) => void;
+    onBlocked?: (body: PhysicsBodyState, info: CapacityQueueBlockedInfo) => void;
+    onAbandoned?: (body: PhysicsBodyState, info: CapacityQueueAbandonedInfo) => void;
+    queueLayout?: "lane" | "none";
+    queueSlotSpacing?: number;
+    queueStiffness?: number;
+    /** Max admitted visits; overflow is measured while it waits outside. */
+    maxQueue?: number;
+    /** Rolling simulated-time window for throughput/utilization (default 30s). */
+    metricWindowSeconds?: number;
+    /** Coarse snapshot cadence used by HOC callbacks (default 0.25s). */
+    snapshotIntervalSeconds?: number;
+    continuous?: boolean;
+}
+export interface CapacityQueueEntry {
+    bodyId: string;
+    jobId: string;
+    visitId: string;
+    visit: number;
+    remaining: number;
+    total: number;
+    queuedAt: number;
+    sequence: number;
+}
+export interface CapacityBlockedEntry extends CapacityQueueVisitInfo {
+    blockedAt: number;
+    sequence: number;
+}
+export interface CapacityMetricSlice {
+    start: number;
+    end: number;
+    arrivals: number;
+    arrivalWork: number;
+    completions: number;
+    completedWork: number;
+    processedWork: number;
+}

package/dist/components/stream/physics/MatterPhysicsEngineAdapter.d.ts

@@ -0,0 +1,42 @@
+import type { PhysicsEngineCapabilities } from "./PhysicsEngineAdapter";
+import type { PhysicsBodySpec, PhysicsColliderSpec } from "./PhysicsKernel";
+export declare const MATTER_PHYSICS_PACKAGE = "matter-js";
+export declare const MATTER_PHYSICS_IMPORT_PATH = "semiotic/physics/matter";
+export declare const MATTER_PHYSICS_CAPABILITIES: PhysicsEngineCapabilities;
+export declare const MATTER_PHYSICS_INSTALL: {
+    readonly engine: "Matter.js";
+    readonly importPath: "semiotic/physics/matter";
+    readonly packageName: "matter-js";
+    readonly installCommand: "npm install matter-js";
+};
+export interface MatterVectorLike {
+    x: number;
+    y: number;
+}
+export interface MatterBoundsLike {
+    min: MatterVectorLike;
+    max: MatterVectorLike;
+}
+export interface MatterBodyLike {
+    id?: string | number;
+    label?: string;
+    position?: MatterVectorLike;
+    velocity?: MatterVectorLike;
+    angle?: number;
+    mass?: number;
+    circleRadius?: number;
+    bounds?: MatterBoundsLike;
+    isSensor?: boolean;
+    plugin?: Record<string, unknown>;
+}
+export interface MatterMigrationOptions {
+    datumFromPlugin?: string;
+    fallbackRadius?: number;
+    idPrefix?: string;
+}
+export declare function matterBodyToPhysicsBodySpec(body: MatterBodyLike, index?: number, options?: MatterMigrationOptions): PhysicsBodySpec;
+export declare function matterBodyToPhysicsColliderSpec(body: MatterBodyLike, index?: number, options?: MatterMigrationOptions): PhysicsColliderSpec;
+export declare function matterBodiesToPhysicsSpawns(bodies: readonly MatterBodyLike[], options?: MatterMigrationOptions): PhysicsBodySpec[];
+export declare function matterBodiesToPhysicsColliders(bodies: readonly MatterBodyLike[], options?: MatterMigrationOptions): PhysicsColliderSpec[];
+export declare function loadMatterPhysicsPeer(): Promise<unknown>;
+export declare function matterPhysicsDependencyError(cause?: unknown): Error;