semiotic 3.8.3 → 3.8.5

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

@@ -0,0 +1,55 @@
+/**
+ * Pure LineChart series-feature prep for the SSR / renderChart path.
+ *
+ * Mirrors the client HOC orchestration of:
+ *   - `useSeriesFeatures` (forecast / anomaly via `buildForecast`)
+ *   - gapStrategy (break / interpolate / zero)
+ *   - directLabel endpoint annotations
+ *   - segment-aware lineStyle (createSegmentLineStyle)
+ *
+ * Client uses lazy dynamic import + React state for these; SSR can call
+ * the pure statisticalOverlays entry points synchronously.
+ */
+import type { Datum } from "./datumTypes";
+import { type AnomalyConfig, type ForecastConfig } from "./statisticalOverlays";
+export interface LineSeriesSsrInput {
+    data: unknown;
+    xAccessor?: string | ((d: Datum) => unknown);
+    yAccessor?: string | ((d: Datum) => unknown);
+    lineBy?: string | ((d: Datum) => unknown);
+    colorBy?: string | ((d: Datum) => unknown);
+    colorScheme?: unknown;
+    color?: string;
+    forecast?: ForecastConfig;
+    anomaly?: AnomalyConfig;
+    gapStrategy?: "break" | "interpolate" | "zero";
+    directLabel?: boolean | {
+        position?: "start" | "end";
+        fontSize?: number;
+    };
+    /** Existing annotations to merge with statistical + direct-label ones. */
+    annotations?: Datum[];
+    themeCategorical?: string[];
+    /** Base lineStyle from buildLineStyle — wrapped with segment styling when forecast is set. */
+    baseLineStyle?: (d: Datum, group?: string) => Datum;
+}
+export interface LineSeriesSsrResult {
+    data: Datum[];
+    xAccessor: string | ((d: Datum) => unknown);
+    yAccessor: string | ((d: Datum) => unknown);
+    groupAccessor: string | ((d: Datum) => unknown) | undefined;
+    colorAccessor: string | ((d: Datum) => unknown) | undefined;
+    annotations: Datum[];
+    lineStyle?: (d: Datum, group?: string) => Datum;
+    yExtent?: [number, number];
+    /** Extra right/left margin for direct labels. */
+    marginExtra?: {
+        left?: number;
+        right?: number;
+    };
+}
+/**
+ * Prepare LineChart props for static SSR: forecast/anomaly data + annotations,
+ * gap handling, direct labels, segment lineStyle.
+ */
+export declare function prepareLineSeriesForSsr(input: LineSeriesSsrInput): LineSeriesSsrResult;

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

@@ -43,7 +43,7 @@ export type LinkedBrushProp = string | {
     yField?: string;
 };
 /**
- * Chart display mode — controls default chrome, size, and interaction.
+ * Chart display mode — controls default decoration, size, and interaction.
  * User-provided props always override mode defaults.
  */
 export type ChartMode = "primary" | "context" | "sparkline" | "mobile";
@@ -98,7 +98,7 @@ export interface ResolvedMobileInteractionConfig {
  * Base props shared across all chart components
  */
 export interface BaseChartProps {
-    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    /** Display mode: "primary" (full decoration), "context" (compact), "sparkline" (inline), or "mobile" (touch-first) */
     mode?: ChartMode;
     /** Chart width in pixels. Default: 600 */
     width?: number;

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

@@ -5,7 +5,7 @@ export interface ValidationResult {
     valid: boolean;
     errors: string[];
 }
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function" | "null";
 export interface PropDef {
     type: PropType | PropType[];
     enum?: readonly string[];

package/dist/components/charts/xy/AreaChart.d.ts

@@ -14,6 +14,16 @@ export interface SemanticGradientStop {
     /** Optional opacity applied to this stop. */
     opacity?: number;
 }
+/**
+ * Convert value-anchored `semanticGradient` stops (`{ at, color }` on the value
+ * scale, 0–100) into the frame's `gradientFill.colorStops` (offset 0 = top).
+ * Exported so the server (`renderChart`) config resolves it identically to this
+ * HOC — otherwise SSR silently drops `semanticGradient` and paints a flat area.
+ */
+export declare function semanticGradientToColorStops(stops: SemanticGradientStop[]): Array<{
+    offset: number;
+    color: string;
+}>;
 /**
  * AreaChart component props
  */

package/dist/components/charts/xy/minimapBrushOverlay.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { StreamScales } from "../../stream/types";
+export interface MinimapBrushOverlayProps {
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: StreamScales | null;
+    brushDirection: "x" | "y";
+    extent: [number, number] | null;
+    onBrush: (extent: [number, number] | null) => void;
+}
+export declare function MinimapBrushOverlay({ width, height, margin, scales, brushDirection, extent, onBrush, }: MinimapBrushOverlayProps): React.JSX.Element;

package/dist/components/charts/xy/minimapBrushOverlayLazy.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import type { MinimapBrushOverlayProps } from "./minimapBrushOverlay";
+/** Renders nothing until d3-brush module resolves, then mounts the brush. */
+export declare function MinimapBrushOverlayLazy(props: MinimapBrushOverlayProps): React.JSX.Element | null;

package/dist/components/charts/xy/scatterplotMatrixBrushOverlay.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+import type { StreamXYFrameHandle } from "../../stream/types";
+export interface ScatterplotMatrixBrushOverlayProps {
+    frameRef: React.RefObject<StreamXYFrameHandle | null>;
+    cellSize: number;
+    onBrush: (extent: [number, number][] | null) => void;
+}
+export declare function ScatterplotMatrixBrushOverlay({ frameRef, cellSize, onBrush, }: ScatterplotMatrixBrushOverlayProps): React.JSX.Element;

package/dist/components/charts/xy/scatterplotMatrixBrushOverlayLazy.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+import type { ScatterplotMatrixBrushOverlayProps } from "./scatterplotMatrixBrushOverlay";
+export declare function ScatterplotMatrixBrushOverlayLazy(props: ScatterplotMatrixBrushOverlayProps): React.JSX.Element | null;

package/dist/components/data/auditData.d.ts

@@ -0,0 +1,51 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { Diagnosis } from "../charts/shared/diagnoseTypes";
+import { type NumericContracts, type NumericFieldRole, type NumericRequirement } from "./numericContracts";
+export interface DataAuditDiagnosis extends Diagnosis {
+    readonly domain: "data";
+    readonly field?: string;
+    readonly role?: NumericFieldRole;
+    /** Bounded, zero-based row indices; `count` carries the full total. */
+    readonly rows?: ReadonlyArray<number>;
+    readonly count?: number;
+}
+export interface CheckedNumericContract {
+    readonly role: NumericFieldRole;
+    readonly accessor: string;
+    readonly dataProp: string;
+    readonly requirements: ReadonlyArray<NumericRequirement>;
+    readonly allowMissing: boolean;
+    readonly missingValue?: number;
+    readonly domain: boolean;
+}
+export interface DataAuditResult {
+    readonly component: string;
+    readonly ok: boolean;
+    readonly rowCount: number;
+    readonly summary: {
+        readonly fieldsChecked: number;
+        readonly errors: number;
+        readonly warnings: number;
+    };
+    readonly contracts: ReadonlyArray<CheckedNumericContract>;
+    readonly diagnoses: ReadonlyArray<DataAuditDiagnosis>;
+}
+export interface AuditDataOptions {
+    /** Override the registered/built-in contract (useful for one-off custom charts). */
+    readonly contracts?: NumericContracts;
+    /** Disable the conservative, 10×IQR scale-domination warning. */
+    readonly checkOutliers?: boolean;
+}
+/**
+ * Audit the intrinsic numeric safety of data for a selected chart.
+ *
+ * This is the input-side companion to `diagnoseConfig` (representation) and
+ * `auditAccessibility` (reception). It is pure, deterministic, React-free, and
+ * accepts function accessors without serializing or executing arbitrary code
+ * outside the caller's own process.
+ */
+export declare function auditData(component: string, props: Datum, data?: ReadonlyArray<Datum>, options?: AuditDataOptions): DataAuditResult;
+export { profileNumericFields } from "./numericFieldProfiler";
+export type { NumericFieldProfile, ProfileNumericFieldsOptions } from "./numericFieldProfiler";
+export { formatDataAudit, toDataAuditNotifications } from "./dataAuditPresentation";
+export type { DataAuditChartNotification, DataAuditNotificationOptions } from "./dataAuditPresentation";

package/dist/components/data/dataAuditPresentation.d.ts

@@ -0,0 +1,18 @@
+import type { DataAuditResult } from "./auditData";
+export interface DataAuditChartNotification {
+    readonly id: string;
+    readonly level: "warning" | "error";
+    readonly title: string;
+    readonly message: string;
+    readonly source: "Semiotic data audit";
+    readonly dismissible: true;
+}
+export interface DataAuditNotificationOptions {
+    /** Maximum individual findings before a final overflow notice. Default 6. */
+    readonly max?: number;
+    /** Omit non-blocking warnings. Default false. */
+    readonly errorsOnly?: boolean;
+}
+export declare function formatDataAudit(result: DataAuditResult): string;
+/** Map audit findings directly onto ChartContainer's notification contract. */
+export declare function toDataAuditNotifications(result: DataAuditResult, options?: DataAuditNotificationOptions): DataAuditChartNotification[];

package/dist/components/data/dataAuditSources.d.ts

@@ -0,0 +1,9 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { NumericContracts, NumericFieldContract } from "./numericContracts";
+/** Resolve a contract's outer or line-object nested row source. */
+export declare function rowsForNumericField(field: NumericFieldContract, props: Datum, data: ReadonlyArray<Datum> | undefined): {
+    dataProp: string;
+    rows: ReadonlyArray<Datum>;
+};
+/** Find explicit empty outer arrays and all-empty declared nested series. */
+export declare function explicitEmptyNumericSources(contracts: NumericContracts, props: Datum, data: ReadonlyArray<Datum> | undefined): string[];

package/dist/components/data/numericContracts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Serializable numeric input contracts for chart capabilities.
+ *
+ * The contract table deliberately lives below the AI/capability registry. It is
+ * consumed by `diagnoseConfig` and `ChartContainer`, both of which must stay
+ * lightweight, while capability descriptors reference the same objects.
+ */
+export type NumericFieldRole = "x" | "y" | "value" | "size" | "count" | "opacity" | "time" | "lower" | "upper" | "open" | "close" | "high" | "low" | (string & {});
+export type NumericRequirement = "finite" | "positive" | "non-negative" | "integer" | "unit-interval";
+export interface NumericFieldContract {
+    /** Semantic role used in findings and dynamic scale checks. */
+    readonly role: NumericFieldRole;
+    /** Name of the chart prop that contains a string/function accessor. */
+    readonly accessor: string;
+    /** Resolve this field only when every named chart prop is present. */
+    readonly whenProps?: ReadonlyArray<string>;
+    /** Accessor used by the chart when the prop is omitted. */
+    readonly defaultAccessor?: string;
+    /** Collection prop to inspect. Defaults to `data`. */
+    readonly dataProp?: string;
+    /** Prop naming a nested row array (for line-object `coordinates`, for example). */
+    readonly nestedDataAccessorProp?: string;
+    /** Nested row-array field used when that prop is omitted. */
+    readonly defaultNestedDataAccessor?: string;
+    /** Every numeric binding is finite by default. */
+    readonly requirements?: ReadonlyArray<NumericRequirement>;
+    /** Temporal coercion supported by the chart: Date only, or Date + date-like strings. */
+    readonly temporalValues?: "date" | "date-like";
+    /** Permit null/undefined values as intentional gaps. Default false. */
+    readonly allowMissing?: boolean;
+    /** Finite numeric fallback the renderer applies to missing values. */
+    readonly missingValue?: number;
+    /** Whether equal values create a zero-span scale domain. */
+    readonly domain?: boolean;
+}
+export interface NumericAggregateContract {
+    readonly kind: "positive-total" | "normalized-total";
+    /** Numeric field role to aggregate. */
+    readonly role: NumericFieldRole;
+    /** Optional grouping accessor prop (for one normalization total per x/category). */
+    readonly groupAccessor?: string;
+    readonly defaultGroupAccessor?: string;
+    /** Only enforce the aggregate when this boolean prop is true. */
+    readonly whenProp?: string;
+}
+export interface NumericContracts {
+    readonly fields: ReadonlyArray<NumericFieldContract>;
+    readonly aggregates?: ReadonlyArray<NumericAggregateContract>;
+}
+/**
+ * Compact built-in table. Shared contract objects are intentionally reused so
+ * this adds very little to `semiotic/utils/core` when diagnostics import it.
+ */
+export declare const BUILT_IN_NUMERIC_CONTRACTS: Readonly<Record<string, NumericContracts>>;
+/** Internal hook used by the public capability registry for third-party charts. */
+export declare function registerNumericContracts(component: string, contracts: NumericContracts | undefined): void;
+/** Internal hook used when a third-party capability is unregistered. */
+export declare function unregisterNumericContracts(component: string): void;
+export declare function getNumericContracts(component: string): NumericContracts | undefined;

package/dist/components/data/numericFieldProfiler.d.ts

@@ -0,0 +1,23 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export interface NumericFieldProfile {
+    readonly field: string;
+    readonly observedCount: number;
+    readonly finiteCount: number;
+    readonly missingCount: number;
+    readonly nonFiniteCount: number;
+    readonly nonNumericCount: number;
+    readonly zeroCount: number;
+    readonly negativeCount: number;
+    readonly fractionalCount: number;
+    readonly min?: number;
+    readonly q1?: number;
+    readonly median?: number;
+    readonly q3?: number;
+    readonly max?: number;
+}
+export interface ProfileNumericFieldsOptions {
+    /** Include exact quartiles. Disable when another profiler already sorts fields. */
+    readonly quantiles?: boolean;
+}
+/** Profile invalid/missing numeric candidates without silently dropping them. */
+export declare function profileNumericFields(data: ReadonlyArray<Datum> | null | undefined, options?: ProfileNumericFieldsOptions): Readonly<Record<string, NumericFieldProfile>>;

package/dist/components/realtime/types.d.ts

@@ -191,6 +191,11 @@ export interface RealtimeFrameHandle {
     remove(id: string | string[]): Datum[];
     /** Update data by ID in place. Requires an ID accessor. Returns previous values. */
     update(id: string | string[], updater: (d: Datum) => Datum): Datum[];
+    /**
+     * Ordinal-only bounded ingest: replace the buffer while preserving category
+     * order and enter/move/exit transitions. XY/network/geo typically omit this.
+     */
+    replace?(data: Datum[]): void;
     clear(): void;
     getData(): Datum[];
     /** Returns the frame's resolved scales, or null if unavailable.

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

@@ -0,0 +1,176 @@
+/**
+ * Pure grid-operations helpers for multi-series power observatories.
+ *
+ * These turn balancing-authority hourly rows into the chart-ready series used by
+ * StackedAreaChart, DifferenceChart, BigNumber, styleRules factories, and
+ * provenanced event annotations. They are domain math — not a React kit — so
+ * agents and pages can share the same pipeline.
+ *
+ * Honesty: {@link reserveMarginPct} is a **readability proxy** from public
+ * demand / net-generation (+ optional interchange) series. It is *not* an ISO
+ * contingency-reserve product. Label it as such in UI and `describeChart` copy.
+ */
+import type { StyleRule } from "../charts/shared/styleRules";
+import type { HatchFill } from "../charts/shared/hatchFill";
+/** Stable fuel keys used across regions when present. */
+export declare const GRID_FUEL_KEYS: readonly ["naturalGas", "coal", "nuclear", "hydro", "wind", "solar", "other"];
+export type GridFuelKey = (typeof GRID_FUEL_KEYS)[number];
+/** Human labels for fuel keys (legend / tooltips). */
+export declare const GRID_FUEL_LABELS: Record<GridFuelKey, string>;
+/**
+ * One hour (or finest grain) in one balancing authority.
+ * Compatible with the strategy schema in docs/strategy/examples-thegrid.md.
+ */
+export type GridHour = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw?: number;
+    netGenMw: number;
+    interchangeMw?: number;
+    fuels: Partial<Record<GridFuelKey, number>>;
+};
+export type ReserveSnapshot = {
+    t: number;
+    ba: string;
+    /** Rough operational headroom proxy — never claim ISO-grade contingency reserve. */
+    reserveMarginPct: number;
+    netLoadMw: number;
+    demandMw: number;
+    netGenMw: number;
+};
+export type ReserveLevels = {
+    /** Margin below this % is "tight" / danger. Default 5. */
+    tight?: number;
+    /** Margin below this % is "watch" / warning. Default 12. */
+    watch?: number;
+    /** Margin at or above this % is comfortable / success. Default 20. */
+    comfortable?: number;
+};
+export type FuelStackRow = {
+    t: number;
+    fuel: GridFuelKey;
+    fuelLabel: string;
+    mw: number;
+    ba: string;
+};
+export type DemandForecastRow = {
+    t: number;
+    a: number;
+    b: number;
+    demandMw: number;
+    forecastMw: number;
+    errorMw: number;
+    ba: string;
+};
+export type OperatingPointSummary = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw: number | null;
+    forecastErrorMw: number | null;
+    netGenMw: number;
+    reserveMarginPct: number;
+    topFuel: GridFuelKey | null;
+    topFuelShare: number;
+    topFuelMw: number;
+    fuelShares: Partial<Record<GridFuelKey, number>>;
+};
+export type GridEventWindow = {
+    id: string;
+    /** Inclusive start epoch ms. */
+    start: number;
+    /** Inclusive end epoch ms. */
+    end: number;
+    label: string;
+    /** Optional longer note for callouts. */
+    note?: string;
+    /** "heat-wave" | "outage" | "demand-spike" | open string. */
+    kind?: string;
+    /** ISO 8601 duration or ms; default "P7D". */
+    ttlHint?: string | number;
+    y?: number;
+    /** Data y for y-threshold style notes. */
+    value?: number;
+};
+/**
+ * Stackable long-form fuel series for StackedAreaChart (`areaBy: "fuel"`).
+ * Zero / missing fuels are omitted so empty keys do not invent area layers.
+ */
+export declare function stackFuelSeries(hours: readonly GridHour[], options?: {
+    fuels?: readonly GridFuelKey[];
+    includeZero?: boolean;
+}): FuelStackRow[];
+/**
+ * DifferenceChart rows: series A = demand, series B = forecast.
+ * Hours without a finite forecast are skipped.
+ */
+export declare function demandForecastRows(hours: readonly GridHour[]): DemandForecastRow[];
+/**
+ * Readability proxy for operational headroom.
+ *
+ * ```
+ * reserveMarginPct = ((supply - demand) / demand) * 100
+ * supply = capacityOrNetGen + max(0, -interchange)  // imports add supply
+ * ```
+ *
+ * When demand is 0, returns 0. Negative values mean demand exceeds supply.
+ *
+ * **Not** ISO contingency reserve (spinning + non-spinning + regulation).
+ * Document that distinction wherever this number is shown.
+ */
+export declare function reserveMarginPct(input: {
+    demand: number;
+    capacityOrNetGen: number;
+    interchange?: number;
+}): number;
+/** Per-hour reserve snapshots derived from {@link GridHour} rows. */
+export declare function reserveSeries(hours: readonly GridHour[]): ReserveSnapshot[];
+/**
+ * Declarative `styleRules` for marks whose primary value is reserve margin %.
+ * Hatch on the tight band so color is not the only encoding.
+ *
+ * Works on BarChart / DotPlot (ordinal) and LineChart / Scatterplot when the
+ * mark value (or `field: "reserveMarginPct"`) is the margin percent.
+ */
+export declare function thresholdBandsForReserve(levels?: ReserveLevels, options?: {
+    field?: string;
+    /** Override hatch for the tight band. */
+    tightHatch?: HatchFill;
+    tightFill?: string;
+    watchFill?: string;
+    comfortableFill?: string;
+}): StyleRule[];
+/**
+ * Annotation band descriptors for reserve threshold strips (y-band style).
+ * Pair with chart `annotations` — not the same object as styleRules.
+ */
+export declare function reserveAnnotationBands(levels?: ReserveLevels): Array<{
+    type: "band";
+    y0: number;
+    y1: number;
+    label: string;
+    color: string;
+    fillOpacity: number;
+    emphasis: "secondary";
+}>;
+/** Summarize the operating point at `now` (or the last hour ≤ now). */
+export declare function summarizeOperatingPoint(hours: readonly GridHour[], now?: number): OperatingPointSummary | null;
+/**
+ * Convert authored event windows into annotation objects with provenance + lifecycle
+ * fields suitable for `applyAnnotationLifecycle`.
+ *
+ * Returns plain annotation dicts (not React nodes). Callers may pass the array to
+ * chart `annotations` after lifecycle treatment.
+ */
+export declare function gridEventAnnotations(events: readonly GridEventWindow[], options?: {
+    now?: number;
+    author?: string;
+    source?: string;
+}): Array<Record<string, unknown>>;
+/** Pick the top N tightest-margin hours for a ranked risk strip. */
+export declare function tightestHours(reserves: readonly ReserveSnapshot[], n?: number): ReserveSnapshot[];
+/** Format MW with locale grouping; returns "—" for non-finite. */
+export declare function formatMw(value: number, digits?: number): string;
+/** Format reserve margin percent with sign awareness. */
+export declare function formatReservePct(value: number, digits?: number): string;

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

@@ -0,0 +1,167 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { HighlightMatch } from "./recipeUtils";
+/**
+ * `netEnsembleLayout` — a layout for **ensembles of disconnected (or only
+ * trivially connected) DAGs**: a "bag of little graphs" that force-directed
+ * layout scatters into meaningless blobs and hierarchical layouts (dagre,
+ * flextree) can't place at all because they assume one connected root.
+ *
+ * The organizing idea comes from the mathematical notion of a **net** (a
+ * Moore–Smith net: a function from a *directed set*). A directed set is a
+ * partial order in which every pair of elements has a common upper bound —
+ * "everything eventually flows together." A DAG hands you a partial order for
+ * free via reachability (`u ≤ v` iff `v` is reachable from `u`), and a finite
+ * directed set must have a single greatest element. For a weakly-connected DAG
+ * that collapses to a one-line, O(V+E) test: **count the sinks.** Exactly one
+ * sink ⟹ the component is a net converging to a single limit; two or more sinks
+ * ⟹ it fails directedness (some pair has no common descendant). See
+ * `/recipes/net-ensemble` for the full explanation.
+ *
+ * The layout:
+ *  1. splits the graph into weakly-connected components,
+ *  2. tests each for directedness (the sink count),
+ *  3. fingerprints each component with Weisfeiler–Leman color refinement so
+ *     order-isomorphic components — the recurring *motifs* — group together,
+ *  4. lays each component out so flow converges toward its sink(s) at the
+ *     bottom (the convergence-to-a-limit made spatial), and
+ *  5. arranges the ensemble as small multiples grouped into motif bands,
+ *     turning a hairball-of-blobs into a **census** ("12 chains, 4 diamonds,
+ *     3 branching forks, 1 oddball") — the thing force layout can never show.
+ *
+ * Emits one hit-testable scene node per drawn mark (individual nodes at full
+ * detail, one node per component when cells collapse), so it inherits keyboard
+ * nav, annotation anchoring, and shared selection for free. Pure / SSR-safe.
+ */
+export interface NetEnsembleConfig {
+    /** Edge field naming the source node id. @default "source" */
+    sourceAccessor?: string;
+    /** Edge field naming the target node id. @default "target" */
+    targetAccessor?: string;
+    /** Node field for the display label. @default "label" */
+    labelAccessor?: string;
+    /** Node field for a category (used by `colorMode: "category"`). @default "category" */
+    categoryAccessor?: string;
+    /** Group order-isomorphic components into labelled motif bands. When `false`,
+     *  every component is placed in one band ordered by size. @default true */
+    groupByMotif?: boolean;
+    /** Band ordering. @default "frequency" */
+    sort?: "frequency" | "size" | "directedness";
+    /** What node fill encodes. @default "directedness" */
+    colorMode?: "directedness" | "category" | "motif";
+    /** Node radius at full detail (px). @default 4 */
+    nodeRadius?: number;
+    /** Gap between component cells (px). @default 16 */
+    cellGap?: number;
+    /** Gap between motif bands (px). @default 22 */
+    bandGap?: number;
+    /** Height reserved for a band's header/label + exemplar (px). @default 34 */
+    headerHeight?: number;
+    /** Below this cell size (px) a component collapses to a single glyph — the
+     *  census view for large ensembles. @default 38 */
+    minCellForFull?: number;
+    /** Largest cell edge (px). @default 120 */
+    maxCellSize?: number;
+    /** Smallest cell edge (px) before the layout stops shrinking to fit. @default 12 */
+    minCellSize?: number;
+    /** Weisfeiler–Leman refinement rounds for the motif fingerprint. More rounds
+     *  distinguish subtler structural differences. @default 3 */
+    fingerprintRounds?: number;
+    /** Draw the motif descriptor + instance count in each band header. @default true */
+    showBandLabels?: boolean;
+    /** Draw the representative component once per band (the "template"). @default true */
+    showExemplars?: boolean;
+    /** Draw the directedness legend. @default true */
+    showLegend?: boolean;
+    /** Fill for converging (single-sink) components. @default theme info */
+    convergeColor?: string;
+    /** Fill for branching (multi-sink) components. @default theme warning */
+    branchColor?: string;
+    /** Edge stroke color. @default theme border */
+    edgeColor?: string;
+    /** Dim marks that don't match this `{field, value}` highlight. */
+    highlight?: HighlightMatch | null;
+}
+export interface NetEnsemblePlacedNode {
+    id: string;
+    cx: number;
+    cy: number;
+    r: number;
+    datum: Datum;
+    category: string;
+}
+export interface NetEnsemblePlacedEdge {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** One weakly-connected component of the ensemble, with its net diagnostics. */
+export interface NetEnsembleComponent {
+    /** Node ids belonging to this component. */
+    ids: string[];
+    nodeCount: number;
+    edgeCount: number;
+    /** Sinks (out-degree 0) and sources (in-degree 0) within the component. */
+    sinkCount: number;
+    sourceCount: number;
+    /**
+     * True iff the component is a **directed set** (a net with a single limit):
+     * for a weakly-connected DAG this holds exactly when there is one sink, so
+     * every pair of nodes shares a common descendant. Multiple sinks ⟹ some pair
+     * has no common upper bound and the component fails directedness.
+     */
+    directed: boolean;
+    /** Weisfeiler–Leman fingerprint — order-isomorphic components share it. */
+    motif: string;
+    /** Short human descriptor of the shape (e.g. `"chain of 5"`, `"diamond / mesh"`). */
+    descriptor: string;
+}
+/** A motif class: one recurring structural shape and how many times it appears. */
+export interface NetEnsembleMotif {
+    motif: string;
+    descriptor: string;
+    count: number;
+    directed: boolean;
+}
+export interface NetEnsembleAnalysis {
+    /** Every weakly-connected component, with net diagnostics. */
+    components: NetEnsembleComponent[];
+    /** The distinct motif classes, most frequent first. */
+    motifs: NetEnsembleMotif[];
+    /** Components that converge to a single sink (are directed nets). */
+    directedCount: number;
+    /** Components that branch to two or more sinks. */
+    branchingCount: number;
+}
+/**
+ * Analyze a graph as an **ensemble of nets** — headless, no rendering. Splits
+ * the graph into weakly-connected components, tests each for directedness (the
+ * sink count), fingerprints them so recurring motifs group together, and
+ * returns the motif census. The pure core of {@link netEnsembleLayout}; reach
+ * for it when you want the diagnostics (how many chains? how many branch?)
+ * without drawing, e.g. to drive a summary readout or a data-quality check.
+ */
+export declare function analyzeNetEnsemble(nodes: ReadonlyArray<{
+    id: string;
+}>, edges: ReadonlyArray<{
+    source: string;
+    target: string;
+}>, options?: {
+    fingerprintRounds?: number;
+}): NetEnsembleAnalysis;
+export interface BandInfo {
+    motif: string;
+    descriptor: string;
+    count: number;
+    directed: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    exemplar: {
+        nodes: NetEnsemblePlacedNode[];
+        edges: NetEnsemblePlacedEdge[];
+    } | null;
+}
+export declare const netEnsembleLayout: NetworkCustomLayout<NetEnsembleConfig>;