semiotic 3.7.5 → 3.8.0

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

@@ -1,8 +1,9 @@
+import type { ReactElement } from "react";
 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
+ * through `frameProps.legend` (`{ legendGroups }`). All four 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
@@ -55,3 +56,54 @@ export interface LegendGroupsInput {
     sizeLabel?: string;
 }
 export declare function legendGroupsFrom(input: LegendGroupsInput): LegendGroup[];
+export interface LegendSwatch {
+    /** Legend entry label. */
+    label: string;
+    /** Filled-square swatch color (the categorical / fill case). */
+    color?: string;
+    /** Line-stroke swatch color (a horizontal bar — for line-series legends). */
+    line?: string;
+    /** Glyph-shape swatch (the per-datum shape channel). */
+    shape?: NetworkSymbolName;
+    /** Diagonal-hatch swatch (percentile / uncertainty bands). Line color comes
+     *  from `color`, falling back to the label color. */
+    hatch?: boolean;
+}
+export interface LegendSwatchesProps {
+    entries: LegendSwatch[];
+    /** Top-left x of the legend block, in plot coordinates. */
+    x: number;
+    /** Top-left y of the legend block, in plot coordinates. */
+    y: number;
+    /** Stack entries down (`vertical`) or flow them across (`horizontal`).
+     *  @default "vertical" */
+    orientation?: "vertical" | "horizontal";
+    /** Swatch box size in px. @default 14 */
+    swatchSize?: number;
+    /** Row height (vertical) / inter-entry gap (horizontal), px. @default 8 (+ swatch) */
+    gap?: number;
+    /** Gap between a swatch and its label, px. @default 6 */
+    labelGap?: number;
+    /** @default 12 */
+    fontSize?: number;
+    /** Label color. @default "var(--semiotic-text-secondary, #888)" */
+    color?: string;
+    className?: string;
+    keyId?: string | number;
+}
+/**
+ * A self-contained SVG legend a custom layout draws in its `overlays` — the
+ * portable counterpart to {@link legendGroupsFrom} (which feeds the *frame's*
+ * legend via `frameProps.legend`). Custom charts disable the built-in legend,
+ * so this renders swatch + label rows directly: fill squares, line bars, glyph
+ * shapes, and diagonal-hatch swatches, stacked or flowed. `pointerEvents: none`.
+ *
+ * @example
+ * ```ts
+ * legendSwatches({
+ *   x: 0, y: 0, orientation: "horizontal",
+ *   entries: SPHERES.map((s) => ({ label: s, color: COLORS[s] })),
+ * })
+ * ```
+ */
+export declare function legendSwatches(p: LegendSwatchesProps): ReactElement;

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

@@ -13,6 +13,35 @@ export declare function resolveAccessor<T = unknown>(a: string | ((d: Datum) =>
  * it lives here once. Returns `unknown` — narrow at the call site.
  */
 export declare function readField(d: unknown, key: string, fallback: unknown): unknown;
+/**
+ * Return the **raw user datum** from a value that may be a frame wrapper.
+ *
+ * Stream Frames and custom-layout scene nodes carry the user's object under
+ * `.data` (a `RealtimeNode` / `SceneDatum` wrapper), and some interaction
+ * payloads nest it under `.datum` (hit-test results, certain tooltip inputs) —
+ * the wrapped-vs-raw split that bites every `onObservation` consumer. This
+ * collapses all of it: `unwrapDatum(value)` always yields the object you
+ * passed in, whether the frame wrapped it (either way) or not.
+ *
+ * This is **the** unwrap path for both `onObservation` handlers and
+ * `frameProps.tooltipContent` renderers — call it once on the incoming value
+ * instead of hand-rolling `x.data ?? x` guards (and never pre-unwrap the
+ * argument yourself: `unwrapDatum(x?.data ?? x)` can double-unwrap a raw datum
+ * that legitimately carries a `data` field).
+ *
+ * Heuristic footgun: any value with a top-level `data` (or `datum`) property is
+ * treated as a wrapper. If your *raw* datum legitimately has its own such
+ * field, this returns that field instead of the datum — rename the field or
+ * read it directly.
+ *
+ * @example
+ * ```ts
+ * onObservation={(o) => {
+ *   if (o.type === "hover") setActive(unwrapDatum(o.datum))
+ * }}
+ * ```
+ */
+export declare function unwrapDatum<T = Datum>(value: unknown): T | null;
 /**
  * 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
@@ -130,3 +159,26 @@ export declare class LayoutCache<V> {
 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;
+/** Build a scene-node `datum` from a flat field map (a thin wrapper over
+ *  {@link createSafeDatum}, used by recipes that synthesize per-glyph data). */
+export declare function datumFromFields(fields: Record<string, unknown>): Datum;
+/** A stable, URL/key-safe id from an arbitrary label — for keyed overlays and
+ *  transition identity (`"Extra Boba" → "extra-boba"`). */
+export declare function stableGlyphId(value: string): string;
+/** Clamp `value` into `[min, max]`. The one-liner every layout re-declares to
+ *  keep a radius, opacity, or pixel position inside its valid range. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Coerce to a finite non-negative number. Shared by tally/token helpers so
+ *  non-finite inputs fail closed instead of leaking NaN into geometry. */
+export declare function nonNegativeFinite(value: number | undefined): number;
+/** Arithmetic mean of a numeric list; `0` for an empty list (so it's safe to
+ *  feed an unfiltered slice). Recipes average angles, positions, and weights. */
+export declare function mean(values: readonly number[]): number;
+/**
+ * Turn a hex color (`#rgb` or `#rrggbb`) into an `rgba(…)` string at `alpha`.
+ * The dimming-by-alpha helper a custom layout reaches for when it must express
+ * hover/selection fade as a *fill color* (e.g. inside a recipe's `resolveColor`
+ * callback, where the frame's opacity channel isn't available). Non-hex input
+ * is returned unchanged so it composes with CSS-var / `rgb()` colors.
+ */
+export declare function withAlpha(color: string, alpha: number): string;

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

@@ -0,0 +1,59 @@
+/**
+ * Run-length encoding for sequential/categorical series — the "collapse a
+ * per-step categorical field into drawable runs" operation that condition
+ * strips, status timelines, and calendar ribbons all need. A custom layout
+ * draws one rect per run instead of one per step.
+ *
+ * Pure / SSR-safe. Several custom charts re-derived this with three slightly
+ * different signatures (value-change by index, value-change by domain coord,
+ * boolean-present); this is the single form that covers all three.
+ */
+export interface Run<V> {
+    /** The constant value over the run. */
+    value: V;
+    /** Run start on the domain axis — the array index of the first item, or the
+     *  `coord` of the first item when `coord` is supplied. Inclusive. */
+    start: number;
+    /** Run end on the domain axis. Half-open: the run covers `[start, end)`. With
+     *  `coord`, this is the next item's coord (or the last coord + `step` for the
+     *  final run / a run that precedes a gap). Without `coord`, the index after
+     *  the run's last item. */
+    end: number;
+    /** Number of consecutive items in the run. */
+    count: number;
+    /** Index of the run's first item in the input array. */
+    startIndex: number;
+    /** Index of the run's last item in the input array (inclusive). */
+    endIndex: number;
+}
+export interface RunOptions<T, V> {
+    /** Map an item to its position on the domain axis (e.g. day-of-year). When
+     *  omitted, the array index is used and runs are index-based. A gap in
+     *  `coord` (a jump larger than `step`) closes the current run. */
+    coord?: (item: T, index: number) => number;
+    /** Width of one item on the domain axis — closes the final run and detects
+     *  gaps when `coord` is supplied. @default 1 */
+    step?: number;
+    /** Custom equality for grouping adjacent items. @default `Object.is` */
+    equals?: (a: V, b: V) => boolean;
+    /** Presence mode: only items with a truthy value form runs; falsy items break
+     *  the current run and are excluded entirely (the boolean condition-strip
+     *  variant). @default false */
+    truthyOnly?: boolean;
+}
+/**
+ * Collapse a sequential series into runs of equal adjacent values.
+ *
+ * @example value-change runs over a domain coordinate (a condition ring/strip)
+ * ```ts
+ * runs(days, (d) => d.condition, { coord: (d) => d.day, step: 1 })
+ * // → [{ value: "clear", start: 0, end: 5, count: 5, ... }, ...]
+ * ```
+ * @example boolean present/absent runs (a "freezing days" strip)
+ * ```ts
+ * runs(days, (d) => d.belowFreezing, { truthyOnly: true })
+ * ```
+ */
+export declare function runs<T, V = unknown>(items: readonly T[], value: (item: T, index: number) => V, opts?: RunOptions<T, V>): Run<V>[];
+/** Alias for {@link runs} — the textbook name for the transform. */
+export declare const runLengthEncode: typeof runs;

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

@@ -0,0 +1,157 @@
+export type TokenType = "dot" | "icon" | "glyph";
+export type TokenSemantics = "observed-unit" | "unitized-measure" | "possible-outcome" | "posterior-sample" | "hypothetical-case" | "risk-case" | "topic-anchor" | "decorative";
+export type TokenCountStrategy = "actual" | "unitized" | "fixed-denominator" | "quantile" | "sample" | "posterior-sample" | "random-sample";
+export type TokenLayout = "row" | "column" | "grid" | "stack" | "bar-segment" | "waffle" | "beeswarm" | "dotplot" | "quantile-strip" | "small-multiple";
+export type TokenLabelPolicy = "text-plus-token" | "text-plus-icon" | "text-only" | "token-only" | "icon-only" | "none";
+export type TokenTaskIntent = "precise-comparison" | "frequency-reasoning" | "probability-estimation" | "risk-communication" | "memory" | "editorial-engagement" | "public-explanation" | "support-decision" | "measure" | "estimate probability" | "understand risk" | "remember" | "decide";
+export type TokenCapabilityIntent = "compare-categories" | "distribution" | "part-to-whole" | "rank" | "outlier-detection";
+export interface TokenEncoding {
+    tokenType: TokenType;
+    tokenSemantics: TokenSemantics;
+    countStrategy: TokenCountStrategy;
+    layout?: TokenLayout;
+    /** Named icon/glyph key in host code; Semiotic keeps this semantic, not visual. */
+    token?: string;
+    icon?: string;
+    /** Value represented by one complete token for unitized measures. */
+    unitValue?: number;
+    /** Alias for `unitValue`, matching the lower-level `unitize` helper. */
+    unit?: number;
+    /** Human-readable meaning, e.g. "one token = 1,000 commuters". */
+    unitMeaning?: string;
+    tokenCount?: number;
+    maxTokens?: number;
+    minFraction?: number;
+    numerator?: number;
+    denominator?: number;
+    labelPolicy?: TokenLabelPolicy;
+    seed?: number;
+}
+export interface TokenGeneratorInput<D = unknown> {
+    value?: number;
+    /** Scenario/projection endpoint for `unitized` tallies. */
+    rangeValue?: number;
+    numerator?: number;
+    denominator?: number;
+    samples?: readonly number[];
+    data?: readonly D[];
+    valueAccessor?: keyof D | ((d: D) => number);
+}
+export interface VisualToken<D = unknown> {
+    index: number;
+    tokenType: TokenType;
+    tokenSemantics: TokenSemantics;
+    countStrategy: TokenCountStrategy;
+    fraction: number;
+    startFraction: number;
+    value: number;
+    start: number;
+    end: number;
+    unitValue?: number;
+    unitMeaning?: string;
+    highlighted?: boolean;
+    /** Marks a token as the projected/scenario extension of a range tally. */
+    range?: "scenario";
+    quantile?: number;
+    sample?: number;
+    datum?: D;
+}
+export type TokenDiagnosticCode = "TOKEN_SEMANTICS_UNCLEAR" | "MISSING_COUNT_STRATEGY" | "ICON_ONLY_LABELS" | "TOO_MANY_VISIBLE_TOKENS" | "DECORATIVE_PICTOGRAPHS" | "TOKEN_STRATEGY_MISMATCH" | "MISSING_UNIT_VALUE" | "MISSING_UNIT_MEANING";
+export interface TokenDiagnostic {
+    code: TokenDiagnosticCode;
+    severity: "warning" | "info";
+    message: string;
+}
+export interface TokenDiagnosticsContext {
+    visibleTokens?: number;
+    maxRecommendedTokens?: number;
+}
+export interface TokenSet<D = unknown> {
+    tokens: VisualToken<D>[];
+    encoding: TokenEncoding;
+    /**
+     * Strategy-specific source total: value-space for `unitized`/numeric `actual`,
+     * denominator for `fixed-denominator`, sample count for sample/quantile
+     * strategies, and observed datum count for data-backed `actual`.
+     */
+    total: number;
+    /**
+     * Strategy-specific visible amount: represented value for `unitized`, visible
+     * token count for fixed-denominator/sample/quantile/data-backed actual.
+     */
+    shown: number;
+    overflow: boolean;
+    numerator?: number;
+    denominator?: number;
+    unitValue?: number;
+    /** Projected/scenario endpoint when input.rangeValue is supplied. */
+    rangeTotal?: number;
+    /** Tokens extending a unitized tally from total to rangeTotal. */
+    rangeTokens?: VisualToken<D>[];
+    diagnostics: TokenDiagnostic[];
+}
+export interface TokenGridOptions {
+    x?: number;
+    y?: number;
+    columns?: number;
+    rows?: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    gutter?: number;
+    flow?: "row" | "column";
+    columnDirection?: "right" | "left";
+    rowDirection?: "down" | "up";
+    /** Anchor within each cell for the returned point. `[0.5, 1]` is useful for feet-down glyphs. */
+    anchor?: [number, number];
+}
+export interface PositionedToken<D = unknown> extends VisualToken<D> {
+    x: number;
+    y: number;
+    row: number;
+    column: number;
+}
+export interface TokenEncodingSuggestion {
+    recommendedEncoding: string;
+    tokenEncoding?: TokenEncoding;
+    rationale: string;
+    warnings: TokenDiagnostic[];
+    alternatives: string[];
+}
+export interface SuggestTokenEncodingInput {
+    taskIntent: TokenTaskIntent;
+    dataType?: "count" | "measure" | "distribution" | "probability" | "risk" | "category";
+    audience?: "expert" | "general-public" | "internal";
+    precisionNeed?: "low" | "medium" | "high";
+    availableSpace?: "small" | "medium" | "large";
+    concreteEntity?: string;
+}
+export declare function normalizeTokenEncoding(encoding: TokenEncoding): TokenEncoding;
+/**
+ * Generate visible token records from a semantic token encoding.
+ *
+ * This is the frame-agnostic bridge between the strategy layer ("each token
+ * is a case / unit / possible outcome") and today's glyph/dot/icon renderers.
+ * `unitized` delegates to `unitize`, so fractional final glyphs keep the same
+ * ISOTYPE partial-fill convention used by existing custom layouts.
+ */
+export declare function generateTokens<D = unknown>(input: number | readonly number[] | TokenGeneratorInput<D>, encoding: TokenEncoding): TokenSet<D>;
+/**
+ * Position generated tokens in a deterministic row/column grid. The returned
+ * `(x, y)` is the anchor point inside each cell, so use `[0.5, 1]` for
+ * baseline-standing ISOTYPE glyphs and `[0.5, 0.5]` for centered dots/icons.
+ */
+export declare function layoutTokenGrid<D = unknown>(tokenSetOrTokens: TokenSet<D> | readonly VisualToken<D>[], options?: TokenGridOptions): PositionedToken<D>[];
+export declare function diagnoseTokenEncoding(encoding: Partial<TokenEncoding>, context?: TokenDiagnosticsContext): TokenDiagnostic[];
+/**
+ * Bridge token-task intents into the chart capability taxonomy used by
+ * `suggestCharts`. Human-friendly aliases normalize first, so callers can use
+ * either the canonical token intent (`probability-estimation`) or the UI label
+ * alias (`estimate probability`).
+ */
+export declare function tokenTaskIntentToCapabilityIntents(intent: TokenTaskIntent): TokenCapabilityIntent[];
+/**
+ * Task-aware defaults for tokenized reasoning. This does not render a chart;
+ * it returns the semantic encoding Semiotic/IDID can explain, critique, or
+ * hand to `generateTokens` before a custom layout stamps dots/icons/glyphs.
+ */
+export declare function suggestTokenEncoding(input: SuggestTokenEncodingInput): TokenEncodingSuggestion;

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

@@ -0,0 +1,79 @@
+import type { GlyphDef } from "../stream/glyphDef";
+import type { SceneAccessibilityMetadata, SceneDatum, SceneNode, Style } from "../stream/types";
+import type { SymbolName } from "../stream/symbolPath";
+import { type PositionedToken, type TokenEncoding, type TokenGeneratorInput, type TokenGridOptions, type TokenLayout, type TokenSet, type VisualToken } from "./tokenEncoding";
+export type TokenLayerInput<D> = number | readonly number[] | TokenGeneratorInput<D> | TokenSet<D>;
+export type TokenLayerValue<T, D> = T | ((token: PositionedToken<D>) => T | undefined);
+export interface TokenPosition {
+    x: number;
+    y: number;
+    row?: number;
+    column?: number;
+}
+export interface TokenLayerOptions<D = unknown> extends TokenGridOptions {
+    /** Override the encoding's preferred layout for this placement. */
+    layout?: TokenLayout;
+    /** Plot-space width used to infer grid columns or normalize quantile strips. */
+    width?: number;
+    /** Plot-space height used to normalize quantile strips. */
+    height?: number;
+    /** Rendered glyph height / symbol diameter / dot diameter. @default 12
+     *  For user-facing ISOTYPE/icon arrays, prefer 16px+ in the final layout. */
+    tokenSize?: TokenLayerValue<number, D>;
+    /** Dot radius. Defaults to half tokenSize. */
+    radius?: TokenLayerValue<number, D>;
+    /** Primary mark paint. Prefer passing ctx.resolveColor(...) from custom layouts. */
+    color?: TokenLayerValue<string, D>;
+    /** Paint for unhighlighted fixed-denominator tokens. */
+    inactiveColor?: TokenLayerValue<string, D>;
+    /** Paint for projected/scenario range tokens when includeRange is true. */
+    rangeColor?: TokenLayerValue<string, D>;
+    /** Accent paint for glyph role fills. */
+    accent?: TokenLayerValue<string, D>;
+    /** Ghost paint for partial glyph fills. */
+    ghostColor?: TokenLayerValue<string | undefined, D>;
+    /** Symbol shape for dot/icon fallback rendering. */
+    symbolType?: TokenLayerValue<SymbolName, D>;
+    /** Custom origin-centered SVG path for symbol nodes. */
+    symbolPath?: TokenLayerValue<string | undefined, D>;
+    /** Composite pictogram definition for icon/glyph tokens. */
+    glyph?: TokenLayerValue<GlyphDef | undefined, D>;
+    /** Partial-fill axis for glyph tokens. */
+    fractionDirection?: TokenLayerValue<"horizontal" | "vertical", D>;
+    rotation?: TokenLayerValue<number | undefined, D>;
+    style?: TokenLayerValue<Style | undefined, D>;
+    datum?: TokenLayerValue<SceneDatum, D>;
+    accessibleDatum?: TokenLayerValue<SceneAccessibilityMetadata["accessibleDatum"], D>;
+    accessibility?: TokenLayerValue<SceneAccessibilityMetadata["accessibility"], D>;
+    pointId?: TokenLayerValue<string | undefined, D>;
+    idPrefix?: string;
+    include?: (token: PositionedToken<D>) => boolean;
+    /** Render `TokenSet.rangeTokens` after base tokens for unitized scenario tallies. */
+    includeRange?: boolean;
+    /** Custom placement hook for scale-driven strips, stacks, map clusters, etc. */
+    positionToken?: (token: VisualToken<D>, index: number, tokens: readonly VisualToken<D>[]) => TokenPosition;
+    /** Maps a sample/value to plot-space x for quantile/sample strips. */
+    valueToX?: (value: number, token: VisualToken<D>) => number;
+    /** Maps a sample/value to plot-space y for quantile/sample strips. */
+    valueToY?: (value: number, token: VisualToken<D>) => number;
+}
+export interface TokenLayerConfig<D = unknown> {
+    input: TokenLayerInput<D>;
+    encoding?: TokenEncoding;
+    options?: TokenLayerOptions<D>;
+}
+export interface TokenLayerResult<D = unknown> {
+    tokenSet: TokenSet<D>;
+    positionedTokens: PositionedToken<D>[];
+    nodes: SceneNode[];
+}
+/**
+ * Frame-agnostic rendering helper for tokenized reasoning.
+ *
+ * `tokenLayer` is the scene-node bridge for ISOTYPE/icon arrays, risk grids,
+ * quantile dotplots, and hybrid bar-token layouts. It creates the semantic
+ * tokens, positions them, and returns ordinary Semiotic scene nodes so custom
+ * charts still get canvas/SVG rendering, hit testing, keyboard navigation,
+ * pointId annotations, transitions, and accessible table rows.
+ */
+export declare function tokenLayer<D = unknown>({ input, encoding, options, }: TokenLayerConfig<D>): TokenLayerResult<D>;

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

@@ -0,0 +1,108 @@
+/**
+ * `unitize` — the pictogram/tally allocator: turn a magnitude into repeated
+ * unit signs with a fractional final sign (the ISOTYPE rule: symbols repeat,
+ * they do not grow).
+ *
+ * This is the counting sibling of {@link allocateCells} (`waffle.ts`):
+ * `allocateCells` divides a *fixed* number of grid cells proportionally among
+ * categories (largest-remainder, integer cells); `unitize` converts one value
+ * into *as many* signs as it needs at a fixed value-per-sign, preserving the
+ * remainder as a partial sign. Use `allocateCells` for part-to-whole waffles,
+ * `unitize` for unit charts, pictogram rows, arrow bundles, and sign stacks.
+ */
+/** One drawn unit sign. */
+export interface UnitSign {
+    /** 0-based position in the tally (also the grid/wrap index). */
+    index: number;
+    /** How much of this sign is filled, 0–1. All signs but the last are 1. */
+    fraction: number;
+    /** Value where this sign begins (`index * unit`). */
+    start: number;
+    /** Value this sign reaches (`min(value, (index + 1) * unit)`). */
+    end: number;
+    /** Value carried by this sign (`end - start`, i.e. `fraction * unit`). */
+    value: number;
+}
+/** A unit sign inside the projected/scenario extension of a range tally. */
+export interface RangeUnitSign extends UnitSign {
+    /**
+     * Where the range fill begins within this sign, 0–1. Non-zero only on the
+     * boundary sign when the base value ends mid-sign — draw the range fill
+     * clipped from `startFraction` to `fraction` so base and range tile one
+     * sign without double-painting.
+     */
+    startFraction: number;
+}
+export interface UnitizeOptions {
+    /** Value represented by one complete sign. Must be > 0. */
+    unit: number;
+    /**
+     * Cap on the number of signs. When the tally is truncated the result's
+     * `overflow` flag is set (render a `+`, a count label, or scale the unit).
+     * @default Infinity
+     */
+    maxUnits?: number;
+    /**
+     * Drop a trailing partial sign whose fraction falls below this threshold —
+     * 176 at unit 25 is seven arrows, not seven arrows and a 4% stub. The
+     * dropped remainder is still visible as `total - shown`.
+     * @default 0
+     */
+    minFraction?: number;
+}
+export interface UnitizeResult {
+    /** The signs to draw, in order; every sign but the last has fraction 1. */
+    units: UnitSign[];
+    /** The value-per-sign the tally was built with. */
+    unit: number;
+    /** The sanitized input value (non-finite and negative clamp to 0). */
+    total: number;
+    /** Value actually represented by the drawn signs (≤ `total` when capped or a sliver was dropped). */
+    shown: number;
+    /** True when `maxUnits` truncated the tally. */
+    overflow: boolean;
+}
+export interface UnitizeRangeResult extends UnitizeResult {
+    /**
+     * Signs extending the tally from `value` to `rangeValue` — the projected /
+     * scenario portion, conventionally drawn hatched or outlined. Indices
+     * continue the base tally; the first entry carries a non-zero
+     * `startFraction` when the base value ends mid-sign.
+     */
+    rangeUnits: RangeUnitSign[];
+    /** The sanitized range endpoint (≥ `total`). */
+    rangeTotal: number;
+}
+/**
+ * Allocate a value into repeated unit signs with a fractional final sign.
+ *
+ * Feeds any repeated-mark rendering: a row of pictograms, a stack of signs on
+ * a map, an arrow bundle, wrapped unit grids (derive row/column from
+ * `index`). Pair each sign with a `glyph` scene node (its `fraction` maps
+ * directly onto the glyph's partial fill) or clip your own SVG.
+ *
+ * @example
+ * ```ts
+ * const tally = unitize(176, { unit: 25 })
+ * // 8 signs: seven at fraction 1, the last at 0.04 — or drop the stub:
+ * const arrows = unitize(176, { unit: 25, minFraction: 0.08 })
+ * // arrows.units.length === 7, arrows.shown === 175, arrows.total === 176
+ * ```
+ */
+export declare function unitize(value: number, options: UnitizeOptions): UnitizeResult;
+/**
+ * Allocate a value plus a projected/scenario extension: solid signs to
+ * `value`, continuation signs from `value` to `rangeValue` (draw them hatched
+ * or outlined — countable, but visibly not yet real).
+ *
+ * When `value` ends mid-sign, the first range sign shares that sign: its
+ * `startFraction` is where the solid fill stopped, so the two fills tile one
+ * sign exactly.
+ *
+ * @example
+ * ```ts
+ * const { units, rangeUnits } = unitizeRange(325, 580, { unit: 25 })
+ * // 13 solid signs, then 11 hatched signs (the last at fraction 0.2)
+ * ```
+ */
+export declare function unitizeRange(value: number, rangeValue: number, options: UnitizeOptions): UnitizeRangeResult;

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

@@ -0,0 +1,28 @@
+/**
+ * 2D vector kit — the handful of point/vector operations every hand-built
+ * custom layout re-derives when it positions marks in Cartesian space:
+ * add/subtract two points, scale one, take a magnitude, normalize to a unit
+ * direction. A radial network spoke, an edge offset normal to its tangent, a
+ * leader line — all of them open with three or four of these one-liners.
+ *
+ * Pure / SSR-safe, dependency-free. Operates on the shared {@link Point}
+ * (`{ x, y }`) used across the radial and edge-router kits, so results compose
+ * directly with `polarToXY`, `boxEdgeAnchors`, `curvedEdgePath`, and the cubic
+ * helpers in `edgeRouter`.
+ */
+import type { Point } from "./radialCoords";
+export type { Point };
+/** Component-wise sum `a + b`. */
+export declare function addPoints(a: Point, b: Point): Point;
+/** Component-wise difference `a - b` (the vector from `b` to `a`). */
+export declare function subtractPoints(a: Point, b: Point): Point;
+/** Scale a point/vector by a scalar `k`. */
+export declare function scalePoint(a: Point, k: number): Point;
+/** Euclidean length of the vector from the origin to `a`. */
+export declare function pointMagnitude(a: Point): number;
+/**
+ * The unit vector in the direction of `a`. A zero-length vector returns `a`
+ * unchanged (its magnitude is treated as 1) so callers never divide by zero —
+ * the common "tangent of a degenerate edge" case stays finite.
+ */
+export declare function normalizePoint(a: Point): Point;

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

@@ -44,3 +44,46 @@ export interface WaffleConfig {
  * ```
  */
 export declare const waffleLayout: CustomLayout<WaffleConfig>;
+export interface CellWeight {
+    /** Stable identity for the category (used as the secondary sort tiebreak). */
+    key: string;
+    /** Relative weight — cells are allocated proportional to this. */
+    weight: number;
+}
+export interface AllocatedCells extends CellWeight {
+    /** The category's exact (fractional) share of `totalCells`. */
+    exact: number;
+    /** The integer cells assigned to this category. */
+    cells: number;
+    /** Fractional leftover (`exact - floor(exact)`), the largest-remainder key. */
+    remainder: number;
+}
+export interface AllocateCellsOptions {
+    /** Cells guaranteed to every category with a positive weight, even when its
+     *  proportional share rounds below this. Over-allocation is then clawed back
+     *  from the largest categories. @default 0 */
+    minPerCategory?: number;
+}
+/**
+ * Distribute `totalCells` across weighted categories so each gets a count
+ * proportional to its weight, using the **largest-remainder method** (every
+ * cell is assigned; no drift from rounding each share independently). The pure
+ * allocation math behind a feature-mix / proportional waffle: turn `{kind →
+ * count}` into `{kind → grid cells}`.
+ *
+ * With `minPerCategory` every present category keeps at least that many cells
+ * (so small-but-nonzero categories stay visible); the shortfall is reclaimed
+ * from the categories holding the most cells. Categories are returned in input
+ * order — sort the input first if you want a particular legend/fill order.
+ *
+ * @example
+ * ```ts
+ * const alloc = allocateCells(
+ *   [{ key: "monument", weight: 7 }, { key: "museum", weight: 2 }, { key: "park", weight: 1 }],
+ *   100,
+ *   { minPerCategory: 1 },
+ * )
+ * // → [{ key: "monument", cells: 70, … }, { key: "museum", cells: 20, … }, { key: "park", cells: 10, … }]
+ * ```
+ */
+export declare function allocateCells(weights: readonly CellWeight[], totalCells: number, opts?: AllocateCellsOptions): AllocatedCells[];

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

@@ -0,0 +1,47 @@
+/**
+ * Semiotic AI core — chart-free deterministic intelligence for agent backends.
+ *
+ * Import from `semiotic/ai/core` when an agent needs recommendation,
+ * validation, repair, grounding, or provider-tool adapters but does not render
+ * React chart components in the same runtime. `semiotic/ai` remains the
+ * backwards-compatible HOC catalog for code generation.
+ */
+export { validateProps } from "./charts/shared/validateProps";
+export type { ValidationResult } from "./charts/shared/validateProps";
+export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
+export type { Diagnosis, DiagnosisResult } from "./charts/shared/diagnoseConfig";
+export { auditAccessibility, formatAccessibilityAudit, accessibilityCaveats, } from "./charts/shared/auditAccessibility";
+export type { A11yPrinciple, A11yStatus, A11yFinding, AccessibilityAuditResult, AuditAccessibilityOptions, } from "./charts/shared/auditAccessibility";
+export { auditMobileVisualization, formatMobileVisualizationAudit, mobileVisualizationCaveats, } from "./charts/shared/auditMobileVisualization";
+export type { MobileVisualizationAuditResult, AuditMobileVisualizationOptions, } from "./charts/shared/auditMobileVisualization";
+export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from "./export/chartConfig";
+export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";
+export { summarizeData } from "./data/DataSummarizer";
+export type { DataSummary, FieldSummary, FieldType, SummarizeOptions } from "./data/DataSummarizer";
+export { profileData } from "./ai/profileData";
+export type { ProfileDataOptions } from "./ai/profileData";
+export { inferIntent } from "./ai/inferIntent";
+export type { InferIntentResult } from "./ai/inferIntent";
+export { suggestCharts, suggestChartsGrouped, scoreChart, explainCapabilityFit } from "./ai/suggestCharts";
+export type { SuggestChartsOptions, RejectedCapability, ExplainCapabilityFitResult } from "./ai/suggestCharts";
+export { suggestDashboard } from "./ai/suggestDashboard";
+export type { DashboardPanel, DashboardSuggestion, SuggestDashboardOptions } from "./ai/suggestDashboard";
+export { suggestStreamCharts } from "./ai/suggestStreamCharts";
+export type { SuggestStreamChartsOptions } from "./ai/suggestStreamCharts";
+export type { StreamSchema, StreamSuggestion } from "./ai/streamingTypes";
+export { suggestStretchCharts } from "./ai/suggestStretchCharts";
+export type { StretchSuggestion, SuggestStretchChartsOptions } from "./ai/suggestStretchCharts";
+export { repairChartConfig } from "./ai/repairChartConfig";
+export type { RepairResult, RepairOptions } from "./ai/repairChartConfig";
+export { proposeVariant, evaluateVariantProposal } from "./ai/variantDiscovery";
+export type { VariantProposal, VariantScore, EvaluateVariantProposalOptions } from "./ai/variantDiscovery";
+export { describeChart, resolveCommunicativeAct, communicativeActForIntent } from "./ai/describeChart";
+export type { DescribeChartResult, DescribeChartOptions, DescribeLevel, CommunicativeAct, DescribeCapabilityContext } from "./ai/describeChart";
+export { buildReaderGrounding } from "./ai/readerGrounding";
+export type { ChartReaderGrounding, ChartReaderGroundingOptions } from "./ai/readerGrounding";
+export { buildNavigationTree, flattenVisible, countNodes } from "./ai/navigationTree";
+export type { NavTreeNode, NavTreeRole, BuildNavigationTreeOptions } from "./ai/navigationTree";
+export { prepareChart, chartGenerationTool, toAnthropicTool, toOpenAITool, toOpenAIResponsesTool, createChartToolHandler, } from "./ai/generativeChart";
+export type { RenderFn, PrepareChartInput, PrepareChartOptions, PrepareChartResult, ChartToolDefinition, ChartToolOptions, OpenAIResponsesTool, OpenAIResponsesToolOptions, } from "./ai/generativeChart";
+export { inspectChart } from "./ai/chartClinic";
+export type { ChartClinicConfig, ChartClinicInput, ChartClinicOptions, ChartClinicReport, ChartClinicRevisionInput, ChartClinicRevisionStatus, ChartClinicSceneSummary, ChartClinicBundleGuidance, } from "./ai/chartClinic";