semiotic 3.7.4 → 3.7.5

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

@@ -0,0 +1,145 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * GoFish escape-hatch lambda registry.
+ *
+ * GoFish's serialized IR cannot carry function bodies, so `derive` (a
+ * `(rows) => rows'` data transform) and `mark-fn` (a `(datum) => drawing`
+ * custom glyph) travel as a `lambdaId` that the host resolves through a
+ * bridge. This module is that bridge for the Semiotic interpreter: register a
+ * function under the id the IR references and `interpretGofishIR` will call it
+ * where the grammar genuinely can't reach.
+ *
+ * This is the *only* sanctioned non-grammar path. A spec that resolves to pure
+ * operators + marks needs no lambdas; one that reaches a `derive`/`mark-fn`
+ * names the computation here.
+ */
+export interface DeriveLambda {
+    kind: "derive";
+    /** Transform the in-scope rows — add columns, or emit new rows. */
+    fn: (rows: Datum[]) => Datum[];
+}
+export interface MarkFnLambda {
+    kind: "mark-fn";
+    /**
+     * Draw a bespoke glyph for one datum inside its allocated unit frame
+     * (coordinates in [0,1], mapped to pixels by the interpreter). Returns
+     * primitive marks the interpreter splices into the scene.
+     */
+    fn: (datum: Datum, frame: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => GofishLambdaPrimitive[];
+}
+export type GofishLambda = DeriveLambda | MarkFnLambda;
+/** A primitive a `mark-fn` may emit (unit coords). Mirrors the glyph vocabulary. */
+export type GofishLambdaPrimitive = {
+    kind: "polygon";
+    points: Array<[number, number]>;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+} | {
+    kind: "circle";
+    x: number;
+    y: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+} | {
+    kind: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+    rotate?: number;
+} | {
+    kind: "text";
+    x: number;
+    y: number;
+    text: string;
+    fill?: string;
+    fontSize?: number;
+};
+/** Register a `derive`/`mark-fn` implementation under the id the IR references. */
+export declare function registerGofishLambda(id: string, lambda: GofishLambda): () => void;
+export declare function unregisterGofishLambda(id: string): void;
+export declare function getGofishLambda(id: string): GofishLambda | undefined;
+/** Merge a per-call lambda map over the module registry (per-call wins). */
+export declare function resolveLambda(id: string, perCall?: Record<string, GofishLambda>): GofishLambda | undefined;
+export interface BobaCellGeometry {
+    cup: Array<[number, number]>;
+    tea: Array<[number, number]> | null;
+    straw: Array<[number, number]> | null;
+    /** Thick rim/lid bar across the cup top. */
+    lid: {
+        x1: number;
+        x2: number;
+        y: number;
+    };
+    pearls: Array<{
+        x: number;
+        y: number;
+        r: number;
+        fill: string;
+    }>;
+    ice: Array<{
+        x: number;
+        y: number;
+        w: number;
+        rot: number;
+        fill: string;
+    }>;
+    /** Content box `[bw, bh]` for the `uniform` unit fit; shared across the menu. */
+    box: [number, number];
+    numBobas: number;
+    numIce: number;
+    teaVolume: number;
+    bobaVolume: number;
+    iceVolume: number;
+    totalVolume: number;
+    cupStroke: string;
+}
+/** Single-cup convenience (normalizes against itself). */
+export declare function computeBobaCellGeometry(row: Datum): BobaCellGeometry;
+/**
+ * The built-in `bobaGeometry` derive: solve every cup, then attach `_g`
+ * (geometry against the shared menu-wide normalization) plus the fixed fills
+ * the marks read.
+ */
+export declare const bobaGeometryLambda: DeriveLambda;
+export interface BottleCellGeometry {
+    silhouette: Array<[number, number]>;
+    imageHref: string;
+    fill: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    fillLine: {
+        x1: number;
+        x2: number;
+        y: number;
+    };
+    pct: {
+        x: number;
+        y: number;
+        text: string;
+    };
+    label: {
+        x: number;
+        y: number;
+        text: string;
+    };
+    fillFill: string;
+}
+export declare function computeBottleCellGeometry(row: Datum): BottleCellGeometry;
+/** The built-in `bottleGeometry` derive: attach `_b` (normalized geometry) per bottle. */
+export declare const bottleGeometryLambda: DeriveLambda;

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

@@ -0,0 +1,44 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+/**
+ * Layered flowchart layout for the Mermaid adapter (and any pre-layered DAG).
+ *
+ * A Mermaid flowchart is a directed acyclic graph, not a force graph — so it
+ * should render as a *layered diagram* with shape-appropriate node glyphs,
+ * directional arrows, and edge labels, the way Mermaid draws it. This recipe
+ * does exactly that from the `layer`/`row` coordinates `fromMermaid` already
+ * computes (longest-path layering), so it needs **no layout engine and no new
+ * dependency**. It ships in `semiotic/recipes`, so it tree-shakes — you only
+ * pull it in if you use it.
+ *
+ * For large or dense graphs where crossing-minimization matters, run a real
+ * Sugiyama layouter (the BYO `dagre` recipe, or `d3-dag`) to assign
+ * `layer`/`row`, then render with this layout — the rendering and the
+ * positioning are deliberately separate concerns.
+ *
+ * Pure, SSR-safe: hit-testable rects are emitted as scene nodes; all visual
+ * chrome (shape glyphs, labels, edges, arrowheads, edge labels) is an SVG
+ * `overlays` group painted on top, in plot-relative coordinates.
+ */
+export type MermaidDirection = "TD" | "TB" | "BT" | "LR" | "RL";
+export interface MermaidDagConfig {
+    /** Flow direction. TD/TB top-down, BT bottom-up, LR left-right, RL right-left. @default "TD" */
+    direction?: MermaidDirection;
+    /** Glyph width / height in px (shrunk to fit). @default 150 / 46 */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Node field accessors. @default "layer" / "row" / "label" / "shape" */
+    layerAccessor?: string;
+    rowAccessor?: string;
+    labelAccessor?: string;
+    shapeAccessor?: string;
+    /** Edge label field. @default "label" */
+    edgeLabelAccessor?: string;
+    /** Colors (CSS vars by default so they follow the theme). */
+    nodeFill?: string;
+    nodeStroke?: string;
+    textColor?: string;
+    edgeColor?: string;
+    /** Stroke for decision (diamond) glyphs. */
+    accentColor?: string;
+}
+export declare const mermaidDagLayout: NetworkCustomLayout<MermaidDagConfig>;

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

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

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

@@ -0,0 +1,100 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Recipe chrome kit — small, framework-level building blocks for the decoration
+ * that custom-layout recipes draw in their `overlays` layer: group enclosures,
+ * band/axis labels, and leader-line callouts to a mark.
+ *
+ * These were each hand-rolled per recipe (packedClusterMatrix drew enclosures,
+ * marimekko/bullet/parallelCoordinates placed band labels, the satellites
+ * graphic needed callouts to specific marks). Centralizing them keeps chrome
+ * consistent and lets new recipes opt in instead of re-deriving the geometry.
+ *
+ * All return plain SVG React elements with `pointerEvents: "none"`, so they
+ * decorate without intercepting canvas hit-testing. Pure / SSR-safe.
+ */
+export interface RoundedEnclosureProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Corner radius. @default 10 */
+    radius?: number;
+    stroke?: string;
+    /** @default 1.5 */
+    strokeWidth?: number;
+    /** @default 0.6 */
+    opacity?: number;
+    /** @default "none" */
+    fill?: string;
+    strokeDasharray?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/** A rounded rectangle around a group of marks (a cell, a row/column band, a cluster). */
+export declare function roundedEnclosure(p: RoundedEnclosureProps): ReactElement;
+/** Bounding box of a set of points (each optionally a circle of radius `r`), padded.
+ *  The usual precursor to {@link roundedEnclosure}. Returns null for an empty set. */
+export declare function boundsOf(points: ReadonlyArray<{
+    x: number;
+    y: number;
+    r?: number;
+}>, pad?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export interface BandLabelProps {
+    text: string;
+    x: number;
+    y: number;
+    /** @default "middle" */
+    anchor?: "start" | "middle" | "end";
+    /** @default "middle" */
+    baseline?: "middle" | "hanging" | "auto";
+    /** Hide the label if its estimated width exceeds this (px). */
+    maxWidth?: number;
+    /** @default 12 */
+    fontSize?: number;
+    fontWeight?: number | string;
+    color?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/** A label placed at a band/axis position, suppressed when it would overflow
+ *  `maxWidth` (the dedup pattern marimekko/parallelCoordinates hand-roll). */
+export declare function bandLabel(p: BandLabelProps): ReactElement | null;
+export type CalloutConnector = "straight" | "elbow" | "curve";
+export interface MarkCalloutProps {
+    /** The anchored mark (a position a custom layout emitted). */
+    markX: number;
+    markY: number;
+    /** Where the label text sits. */
+    labelX: number;
+    labelY: number;
+    label: ReactNode;
+    /** @default "straight" */
+    connector?: CalloutConnector;
+    /** Draw a ring of this radius around the mark (editorial highlight). */
+    markRadius?: number;
+    stroke?: string;
+    /** @default 1 */
+    strokeWidth?: number;
+    color?: string;
+    /** @default 11 */
+    fontSize?: number;
+    fontWeight?: number | string;
+    /** text-anchor for the label. @default "middle" */
+    labelAnchor?: "start" | "middle" | "end";
+    /** @default "hanging" */
+    labelBaseline?: "middle" | "hanging" | "auto";
+    className?: string;
+    keyId?: string | number;
+}
+/**
+ * A leader line connecting a label to a mark, with an optional ring around the
+ * mark — the editorial-callout pattern. Custom-layout recipes use it because
+ * the annotation system can't anchor to a mark a layout emits at runtime; the
+ * recipe knows the packed position and can call this directly.
+ */
+export declare function markCallout(p: MarkCalloutProps): ReactElement;

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

@@ -0,0 +1,57 @@
+import type { LegendGroup } from "../types/legendTypes";
+import { type NetworkSymbolName } from "../stream/symbolPath";
+/**
+ * `legendGroupsFrom` — build the `LegendGroup[]` a custom-layout recipe passes
+ * through `frameProps.legend` (`{ legendGroups }`). All three custom-chart HOCs
+ * disable the built-in legend because the *layout* owns color/shape/size; without
+ * this, authors hand-roll the `LegendGroup` shape (its `styleFn`, custom-glyph
+ * `type` render functions, swatch sizing). This closes that gap without the frame
+ * having to guess the author's encoding — the recipe declares each channel and
+ * gets back a ready-to-render array.
+ *
+ * One group is emitted per provided channel, in order: **color → symbol → size**.
+ * Pure / SSR-safe.
+ *
+ * @example
+ * ```tsx
+ * <NetworkCustomChart
+ *   layout={packedClusterMatrix}
+ *   frameProps={{ legend: { legendGroups: legendGroupsFrom({
+ *     colorMap: CATEGORY_COLORS, colorLabel: "Category",
+ *     symbolMap: CLASS_SHAPES, symbolLabel: "Class",
+ *     sizeStops: [200, 2000, 8000], sizeRadius: r, sizeLabel: "Mass (kg)",
+ *   }) } }}
+ * />
+ * ```
+ */
+export interface LegendGroupsInput {
+    /** `{category → color}` map → one swatch per entry, in insertion order. */
+    colorMap?: Record<string, string>;
+    /** Or explicit category keys, with `color` resolving each to a color. */
+    keys?: string[];
+    /** Resolve a key → color (e.g. a recipe's `ctx.resolveColor`). Used with `keys`. */
+    color?: (key: string) => string;
+    /** Color-group heading. @default "" */
+    colorLabel?: string;
+    /** Color swatch glyph — a filled square or a line stroke. @default "fill" */
+    colorType?: "fill" | "line";
+    /** `{category → glyph shape}` map → one shape swatch per entry. */
+    symbolMap?: Record<string, NetworkSymbolName>;
+    /** Fill for the shape swatches (shape, not color, is the encoding here).
+     *  @default "var(--semiotic-text, currentColor)" */
+    symbolColor?: string;
+    /** Symbol-group heading. @default "" */
+    symbolLabel?: string;
+    /** Reference values → circle swatches sized by the mark scale. */
+    sizeStops?: number[];
+    /** Map a value → radius (px) — pass the recipe's own radius scale so the
+     *  legend circles match the marks exactly. Required to draw the size group. */
+    sizeRadius?: (v: number) => number;
+    /** Format a size stop for its label. @default `String` */
+    sizeFormat?: (v: number) => string;
+    /** Size swatch circle fill. @default "var(--semiotic-text, currentColor)" */
+    sizeColor?: string;
+    /** Size-group heading. @default "" */
+    sizeLabel?: string;
+}
+export declare function legendGroupsFrom(input: LegendGroupsInput): LegendGroup[];

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

@@ -5,6 +5,21 @@ import type { Datum } from "../charts/shared/datumTypes";
  * the boundary and lets the layout body call a single function.
  */
 export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) => T)): (d: Datum) => T;
+/**
+ * Read a field off a network-ingest wrapper (`node.data.<key>`) or the node
+ * itself, with a fallback. Network recipes receive `RealtimeNode`/`RealtimeEdge`
+ * wrappers whose user data lives under `.data`; several recipes (lineageDag,
+ * mermaidDag, packedClusterMatrix, …) each re-declared this identical reader, so
+ * it lives here once. Returns `unknown` — narrow at the call site.
+ */
+export declare function readField(d: unknown, key: string, fallback: unknown): unknown;
+/**
+ * Group items into a `Map` keyed by a derived string. Insertion order is
+ * preserved both for keys and within each bucket — recipes rely on stable
+ * ordering for deterministic layout. Several recipes re-declared this; it lives
+ * here once.
+ */
+export declare function groupBy<T>(items: readonly T[], key: (item: T) => string): Map<string, T[]>;
 /**
  * Build a datum object whose own-properties are safe to set from
  * user-supplied accessor names. `Object.create(null)` produces a
@@ -25,3 +40,93 @@ export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) =>
  * scattered across each recipe's inner loops.
  */
 export declare function createSafeDatum(populate: (set: (key: string, value: unknown) => void) => void): Datum;
+/**
+ * A `{field, value}` highlight target — or an array of them, AND-combined (a
+ * datum must match every entry to count as a match, e.g. a region×orbit cell).
+ * `value` is coerced to a string before comparison; a nullish `value` matches
+ * anything (so `{ field, value: null }` is a no-op constraint).
+ */
+export type HighlightMatch = {
+    field: string;
+    value: unknown;
+} | ReadonlyArray<{
+    field: string;
+    value: unknown;
+}>;
+/**
+ * Whether `datum` satisfies a `{field, value}` highlight (or every entry of an
+ * array). A nullish/empty `highlight` matches everything — the "no highlight
+ * active" case. Several recipes hand-rolled this exact field/value loop.
+ */
+export declare function matchesHighlight(datum: Datum, highlight: HighlightMatch | null | undefined): boolean;
+export interface DimOptions {
+    /** A datum is lit only if this predicate passes (e.g. a shared-selection
+     *  predicate, or `parallelCoordinates`'s `highlightFn`). Omit ⇒ no constraint. */
+    predicate?: ((d: Datum) => boolean) | null;
+    /** A datum is lit only if it matches this `{field, value}` (or all, for an
+     *  array). Omit ⇒ no constraint. Composes with `predicate` (both must pass). */
+    highlight?: HighlightMatch | null;
+    /** Opacity used when no cue is active (nothing is dimmed). @default 1 */
+    baseOpacity?: number;
+    /** Opacity for marks that don't match an active cue. @default 0.16 */
+    dimOpacity?: number;
+    /** Additive opacity boost for matching marks when a cue is active, capped at 1
+     *  (e.g. `parallelCoordinates` lifts its 0.45 line opacity by 0.4 on match). @default 0 */
+    brighten?: number;
+}
+/**
+ * The highlight/dim opacity rule, shared across custom-layout recipes. A mark is
+ * "lit" when it satisfies **every** active cue (`highlight` AND `predicate`); if
+ * no cue is active nothing is dimmed and every mark gets `baseOpacity`. Lit marks
+ * get `min(1, baseOpacity + brighten)`, dimmed marks get `dimOpacity`.
+ *
+ * This is the one rule `packedClusterMatrix` and `parallelCoordinates` each
+ * hand-rolled; centralizing it keeps the "matching marks stay lit, the rest dim"
+ * behavior identical. (Recipes whose dimming composes several cues with priority
+ * and rescue rules — e.g. `lineageDag`'s reach-set-over-selection — keep their
+ * bespoke logic; this helper is for the common AND-of-cues case.)
+ */
+export declare function dimFor(datum: Datum, opts?: DimOptions): number;
+/**
+ * Join layout-affecting inputs into a stable content-signature string. Pass the
+ * primitives that change the geometry (dimensions, gaps, orders, a per-datum
+ * fingerprint) — NOT styling/interaction inputs (color, shade, highlight) — so a
+ * re-style or a returning resize reuses a cached layout instead of recomputing it.
+ * Pairs with {@link LayoutCache}.
+ */
+export declare function signatureKey(parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+/**
+ * A tiny bounded geometry cache for expensive layouts (force packing, tree/DAG
+ * positioning). Key it with a {@link signatureKey} of the layout-affecting inputs
+ * so re-styling on interaction never re-runs the layout.
+ *
+ * **The sharp edge:** on `NetworkCustomChart`/`*CustomChart`, `ctx.nodes` is a
+ * *fresh array each `buildScene`* and a `layoutConfig` change re-runs the layout
+ * without re-ingesting topology — so cache by *content* (a fingerprint of the
+ * data), never by array identity. Over `maxSize` distinct keys it clears wholesale
+ * (these layouts churn a handful of signatures, not thousands).
+ */
+export declare class LayoutCache<V> {
+    private readonly maxSize;
+    private store;
+    constructor(maxSize?: number);
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    /** Return the cached value for `key`, or compute + store it on a miss. */
+    getOrCompute(key: string, compute: () => V): V;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * A reusable lightness shader for one base color. Interpolating in CIELAB keeps
+ * the hue and chroma roughly fixed while only lightness moves, so a categorical
+ * hue can carry a second *continuous* channel as shade (e.g. age, recency).
+ *
+ * The returned function takes `t ∈ [0,1]`: `0` lightens toward white, `1`
+ * darkens toward black, `0.5` returns the base. `strength` (0..1) caps how far
+ * each direction travels. Pure / SSR-safe — no DOM. Build once per base color
+ * (it captures two interpolators) and call per datum.
+ */
+export declare function makeShade(baseColor: string, strength?: number): (t: number) => string;
+/** One-shot form of {@link makeShade}: perceptual lightness shade of `baseColor`. */
+export declare function shade(baseColor: string, t: number, strength?: number): string;

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

@@ -78,6 +78,12 @@ export { describeChart, resolveCommunicativeAct, communicativeActForIntent } fro
 export type { DescribeChartResult, DescribeChartOptions, DescribeLevel, CommunicativeAct, DescribeCapabilityContext } from "./ai/describeChart";
 export { buildReaderGrounding } from "./ai/readerGrounding";
 export type { ChartReaderGrounding, ChartReaderGroundingOptions, ChartReaderGroundingIntent } from "./ai/readerGrounding";
+export { buildDataPitfallsBridge, toDataPitfallsChain } from "./ai/dataPitfallsBridge";
+export type { DataPitfallsBridgeOptions, DataPitfallsBridgeResult, DataPitfallsChainInput, DataPitfallsChainStage, DataPitfallsDocumentInput, DataPitfallsImageInput, DataPitfallsImageMediaType, DataPitfallsImageSource, DataPitfallsRenderedChart, DataPitfallsSlideContent, DataPitfallsSlidesInput, DataPitfallsSingleArtifactInput, DataPitfallsTextInput } from "./ai/dataPitfallsBridge";
+export { dataQualityToAnnotations, fromDbtArtifacts, fromGreatExpectations } from "./ai/dataQualityBridge";
+export type { DataQualityStatus, DataQualityCheckKind, DataQualityResult, DataQualityAnnotationOptions, DataQualityAnnotationsResult, UnplacedDataQualityResult, DbtArtifacts, GEValidationResult } from "./ai/dataQualityBridge";
+export { prepareChart, chartGenerationTool, toAnthropicTool, toOpenAITool, createChartToolHandler } from "./ai/generativeChart";
+export type { RenderFn, PrepareChartInput, PrepareChartOptions, PrepareChartResult, ChartToolDefinition, ChartToolOptions } from "./ai/generativeChart";
 export { buildNavigationTree, flattenVisible, countNodes } from "./ai/navigationTree";
 export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
 export { AccessibleNavTree } from "./AccessibleNavTree";

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

@@ -5,4 +5,6 @@
 export { bin, rollup, groupBy, pivot } from "./data/transforms";
 export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
+export { fromArrow } from "./data/fromArrow";
+export type { ArrowTableLike, ArrowColumnLike, ArrowFieldLike, ArrowSchemaLike, FromArrowOptions, } from "./data/fromArrow";
 export { mergeData } from "./geo/mergeData";