semiotic 3.8.4 → 3.8.6

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/geometry/bumpRibbonGeometry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Screen-space geometry for magnitude-encoded bump-chart ribbons.
+ *
+ * A conventional area chart offsets both boundaries vertically. That makes a
+ * band look artificially thin when its centerline moves sharply between
+ * ranks. This helper follows the idea behind d3.svg.ribbon instead: sample the
+ * centerline, calculate its local normal, then offset by the requested radius.
+ * The visible thickness therefore stays perpendicular to the trajectory.
+ */
+export interface BumpRibbonPoint {
+    x: number;
+    y: number;
+    /** Half of the desired visible ribbon thickness, in pixels. */
+    radius: number;
+}
+export interface BumpRibbonGeometry {
+    topPath: [number, number][];
+    bottomPath: [number, number][];
+    /** Index of the nearest input datum for every sampled path vertex. */
+    datumIndices: number[];
+}
+export interface BumpRibbonGeometryOptions {
+    /** Smooth horizontal-tangent Béziers or straight segments. */
+    curve?: "smooth" | "linear";
+    /** Samples emitted for each interval. Stable counts enable path animation. */
+    samplesPerSegment?: number;
+}
+/**
+ * Build paired boundary paths around a bump-chart centerline.
+ *
+ * The first sample of every interval after the first is omitted because it is
+ * identical to the previous interval's final sample. Every trajectory with
+ * the same number of ranking columns therefore emits the same number of
+ * vertices, which lets StreamXYFrame interpolate paths during data updates.
+ */
+export declare function buildBumpRibbonGeometry(points: BumpRibbonPoint[], options?: BumpRibbonGeometryOptions): BumpRibbonGeometry;

package/dist/components/legendLayout.d.ts

@@ -1,8 +1,26 @@
-import type { LegendLayout } from "./types/legendTypes";
+import type { LegendLayout, LegendValue } from "./types/legendTypes";
 export declare const DEFAULT_LEGEND_SWATCH_SIZE = 16;
 export declare const DEFAULT_LEGEND_LABEL_GAP = 6;
 export declare const DEFAULT_LEGEND_ITEM_GAP = 10;
 export declare const DEFAULT_LEGEND_ROW_HEIGHT = 22;
+export declare const DEFAULT_SIDE_LEGEND_WIDTH = 100;
+export declare const DEFAULT_LEGEND_DISTANCE = 10;
+/**
+ * SVG text has no useful intrinsic width until after it is mounted. Keep the
+ * estimate shared by margin calculation and rendering so side legends never
+ * reserve one width and draw into another.
+ */
+export declare function estimateLegendTextWidth(label: string): number;
+/** Resolve the layout box needed by a left/right legend. */
+export declare function resolveSideLegendWidth(legend: LegendValue | null | undefined, layout?: LegendLayout): number;
+/** Resolve the requested gap between the legend edge and plot edge. */
+export declare function resolveLegendDistance(legend: LegendValue | null | undefined): number;
+/** Resolve plot-adjacent chrome reserved before a left/right legend. */
+export declare function resolveLegendSideGutter(layout?: LegendLayout): number;
+/** Estimate the layout-box height used to place a top/bottom legend. */
+export declare function resolveHorizontalLegendHeight(legend: LegendValue | null | undefined, availableWidth: number, layout?: LegendLayout): number;
+/** Margin required to fit a side legend and its plot-edge gap. */
+export declare function resolveSideLegendMargin(legend: LegendValue | null | undefined, layout?: LegendLayout): number;
 export interface LegendMetrics {
     swatchSize: number;
     labelGap: number;

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>;

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

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+import type { BandInfo } from "./netEnsembleLayout";
+export interface NetEnsembleOverlayOptions {
+    convergeColor: string;
+    branchColor: string;
+    edgeColor: string;
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    showBandLabels: boolean;
+    showExemplars: boolean;
+    showLegend: boolean;
+    textColor: string;
+    subText: string;
+}
+/** Render presentation-only band labels, exemplars, and the directedness key. */
+export declare function buildNetEnsembleOverlays(bands: BandInfo[], o: NetEnsembleOverlayOptions): ReactNode;

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

@@ -0,0 +1,156 @@
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+export { wordTrailsProgressiveReveal, type WordTrailsProgressiveRevealOptions } from "./wordTrailsProgressiveReveal";
+/**
+ * Word Trails — a *quantitatively honest* word cloud.
+ *
+ * Where a classic word cloud (d3-cloud / amueller) packs words into free space
+ * with only size encoding frequency and position meaning nothing, Word Trails
+ * gives position meaning on both axes:
+ *
+ *   - **columns** (x) are a category — e.g. each speaker in a debate;
+ *   - **the vertical axis** (y) is an ordered value — e.g. the debate segment
+ *     where the word peaked, so a word's height reads as *when* it was said;
+ *   - **font size** encodes frequency/weight.
+ *
+ * Each column is laid out with greedy, largest-first placement: every word
+ * searches outward from its segment anchor for the nearest free spot, so the
+ * result is **overlap-free by construction**. A single global font scale
+ * (`scaleToFit`) shrinks every word together until it all fits — relative
+ * magnitude is preserved, nothing is clipped or dropped.
+ *
+ * The reading: scan a column top-to-bottom to follow one speaker through time;
+ * scan across a row to compare what everyone emphasised at the same moment.
+ *
+ * Inspired by Elijah Meeks's 2016 "Word Trails" debate visualization. Because
+ * placement is *box*-aware (not sprite/pixel), the layout needs no canvas text
+ * measurement — it is pure and SSR-clean.
+ *
+ * @example
+ * ```tsx
+ * import { OrdinalCustomChart } from "semiotic/ordinal"
+ * import { wordTrailsLayout } from "semiotic/recipes"
+ *
+ * <OrdinalCustomChart
+ *   data={terms}                     // [{ word, weight, speaker, segment }]
+ *   layout={wordTrailsLayout}
+ *   layoutConfig={{
+ *     textAccessor: "word",
+ *     weightAccessor: "weight",
+ *     columnAccessor: "speaker",
+ *     segmentAccessor: "segment",
+ *   }}
+ *   width={860}
+ *   height={520}
+ * />
+ * ```
+ */
+export interface WordTrailsWordInfo {
+    /** Rendered word text. */
+    word: string;
+    /** Column containing this word. */
+    column: string;
+    /** Quantitative weight used to size this word. */
+    weight: number;
+    /** Ordered segment/time value anchoring this word vertically. */
+    segment: number;
+    /** Exact source row supplied to the chart. */
+    datum: Datum;
+    /** Index of `datum` in the chart's input data. */
+    dataIndex: number;
+    /** Index of the word's column in the final rendered column order. */
+    columnIndex: number;
+    /** Column color after `columnColor` / the chart theme has been resolved. */
+    resolvedColumnColor: string;
+}
+export interface WordTrailsConfig {
+    /** Field (or fn) giving the word text. */
+    textAccessor: string | ((d: Datum) => string);
+    /** Field (or fn) giving the word weight (→ font size). */
+    weightAccessor: string | ((d: Datum) => number);
+    /** Field (or fn) giving the column category (→ x band). */
+    columnAccessor: string | ((d: Datum) => string);
+    /** Field (or fn) giving the ordered segment/time value (→ pinned y). */
+    segmentAccessor: string | ((d: Datum) => number);
+    /** `[min, max]` of the segment axis. Derived from data when omitted. */
+    segmentDomain?: [number, number];
+    /** Explicit column order. Data insertion order when omitted. */
+    columnOrder?: string[];
+    /** Smallest font size, px. @default 11 */
+    minFontSize?: number;
+    /** Largest font size, px. @default 42 */
+    maxFontSize?: number;
+    /** Gap between columns, px. @default 18 */
+    columnGutter?: number;
+    /**
+     * Gap kept between word boxes, px — the density knob. `0` packs words as
+     * tightly as their glyph boxes allow (crowded, still overlap-free); larger
+     * values open the cloud up. @default 2
+     */
+    collisionPadding?: number;
+    /**
+     * Per-word fill override. Return a color for a word (e.g. from a
+     * distinctiveness / sentiment model) or `undefined` to fall back to the
+     * column color. Same word ⇒ same color across columns if you key on the text.
+     */
+    wordColor?: (info: WordTrailsWordInfo) => string | undefined | null;
+    /**
+     * Per-word reveal opacity. Return a value in `[0, 1]`; values are clamped,
+     * and non-finite values resolve to `0`. Every row still participates in
+     * scale-to-fit and collision placement, so changing opacity cannot move the
+     * remaining words. A resolved `0` emits neither a glyph nor an interactive
+     * hit target. By default a nonzero value multiplies the built-in weight
+     * opacity; set `weightOpacity` to `false` when this callback should be the
+     * exact rendered opacity.
+     * @default () => 1
+     */
+    wordOpacity?: (info: WordTrailsWordInfo) => number;
+    /**
+     * Fade lower-weight words from `0.5` to `1` opacity in addition to encoding
+     * weight with font size. Disable this when opacity carries an independent
+     * variable such as recency; `wordOpacity` then controls rendered opacity
+     * exactly. @default true
+     */
+    weightOpacity?: boolean;
+    /** Per-column label color override. Falls back to the categorical palette. */
+    columnColor?: (column: string) => string | undefined | null;
+    /** Draw the speaker/column labels along the top. @default true */
+    showColumnLabels?: boolean;
+    /** Draw the segment/time value axis on the left. @default true */
+    showSegmentAxis?: boolean;
+    /** Approx. number of ticks on the segment axis. @default 6 */
+    segmentTickCount?: number;
+    /** Formats a segment value for the axis + tooltip. @default String */
+    segmentTickFormat?: (v: number) => string;
+    /** Title shown above the segment axis (e.g. "Debate segment"). */
+    segmentAxisLabel?: string;
+    /**
+     * Max rotation magnitude, degrees. Each word gets a deterministic angle in
+     * `[-rotate, +rotate]`. `0` keeps every word horizontal (most legible).
+     * @default 0
+     */
+    rotate?: number;
+    /**
+     * Allow the same word to appear more than once in a column. When `false`
+     * (default), duplicate `(column, word)` rows are merged to a single entry at
+     * the row with the greatest weight (its peak) — the classic word-cloud
+     * reading. When `true`, every row is kept, so a word can trail down its
+     * column once per segment it appeared in. @default false
+     */
+    repeatWords?: boolean;
+    /**
+     * Uniformly shrink every word by one global factor until nothing overlaps.
+     * Relative magnitude is preserved (a word twice as frequent stays twice the
+     * area) — only the absolute scale drops as words are added. Turn it off to
+     * keep exact `minFontSize`/`maxFontSize` sizing and accept overlap.
+     * @default true
+     */
+    scaleToFit?: boolean;
+    /**
+     * Target fraction of each column's area filled by word boxes before the
+     * global scale is reduced. Lower packs looser (more whitespace); higher
+     * starts larger and lets the greedy placer crowd words in. @default 0.6
+     */
+    packingDensity?: number;
+}
+export declare const wordTrailsLayout: OrdinalCustomLayout<WordTrailsConfig>;

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

@@ -0,0 +1,42 @@
+import type { WordTrailsConfig } from "./wordTrails";
+/** Options for a stable, progressive Word Trails reveal. */
+export interface WordTrailsProgressiveRevealOptions {
+    /** Segment that is currently active/reached. Values are clamped to `segmentDomain`. */
+    currentSegment: number;
+    /** Ordered `[oldest, newest]` segment extent used for the fade. */
+    segmentDomain: readonly [number, number];
+    /** Opacity of the oldest reached segment. @default 0.25 */
+    oldestOpacity?: number;
+    /** Opacity of the current segment. @default 1 */
+    currentOpacity?: number;
+    /** Opacity of unreached segments. `0` hides their glyphs and hit targets. @default 0 */
+    futureOpacity?: number;
+    /** Also multiply the reveal by Word Trails' built-in weight fade. @default false */
+    combineWeightOpacity?: boolean;
+}
+/**
+ * Build the two config fields for a stable, progressive segment reveal.
+ *
+ * Reached rows fade linearly from `oldestOpacity` at the start of the domain
+ * to `currentOpacity` at `currentSegment`; future rows use `futureOpacity`.
+ * Word Trails still lays out zero-opacity rows, so playback changes visibility
+ * without reflow. The returned config disables the independent weight-opacity
+ * encoding unless `combineWeightOpacity` is explicitly enabled.
+ *
+ * This is the Word Trails composition counterpart to the runtime-neutral
+ * `opacityFromAge` helper: it keeps the same linear newest-to-oldest reading,
+ * then adds future hiding, layout reservation, and exact weight-opacity
+ * semantics without making the recipes entry point depend on a motion runtime.
+ *
+ * @example
+ * ```tsx
+ * layoutConfig={{
+ *   ...config,
+ *   ...wordTrailsProgressiveReveal({
+ *     currentSegment: iteration,
+ *     segmentDomain: [0, lastIteration]
+ *   })
+ * }}
+ * ```
+ */
+export declare function wordTrailsProgressiveReveal(options: WordTrailsProgressiveRevealOptions): Pick<WordTrailsConfig, "wordOpacity" | "weightOpacity">;

package/dist/components/semiotic-ai-core.d.ts

@@ -18,6 +18,9 @@ export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from ".
 export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";
 export { summarizeData } from "./data/DataSummarizer";
 export type { DataSummary, FieldSummary, FieldType, SummarizeOptions } from "./data/DataSummarizer";
+export { auditData, formatDataAudit, profileNumericFields, toDataAuditNotifications, } from "./data/auditData";
+export type { AuditDataOptions, CheckedNumericContract, DataAuditChartNotification, DataAuditDiagnosis, DataAuditNotificationOptions, DataAuditResult, NumericFieldProfile, ProfileNumericFieldsOptions, } from "./data/auditData";
+export type { NumericAggregateContract, NumericContracts, NumericFieldContract, NumericFieldRole, NumericRequirement, } from "./data/numericContracts";
 export { profileData } from "./ai/profileData";
 export type { ProfileDataOptions } from "./ai/profileData";
 export { inferIntent } from "./ai/inferIntent";

package/dist/components/semiotic-ai-data-audit.d.ts

@@ -0,0 +1,4 @@
+export { auditData, formatDataAudit, profileNumericFields, toDataAuditNotifications, } from "./data/auditData";
+export type { AuditDataOptions, CheckedNumericContract, DataAuditChartNotification, DataAuditDiagnosis, DataAuditNotificationOptions, DataAuditResult, NumericFieldProfile, ProfileNumericFieldsOptions, } from "./data/auditData";
+export type { NumericAggregateContract, NumericContracts, NumericFieldContract, NumericFieldRole, NumericRequirement, } from "./data/numericContracts";
+export type { ChartContainerDataAudit, ChartContainerDataAuditOptions, } from "./chartContainerDataAudit";