semiotic 3.5.4 → 3.7.0

package/dist/components/ai/dataScaleProfile.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Scale-aware suggestion overlay. The companion to AudienceProfile: where
+ * AudienceProfile describes *who* reads the chart, DataScaleProfile and
+ * DataQualityProfile describe *how big* and *how clean* the data actually is.
+ *
+ * Semiotic does not measure scale or quality from the data passed to it —
+ * the row data may be a sample, a future projection, or completely absent.
+ * Orgs declare these facts up front and the suggestion engine biases
+ * rankings accordingly. Identical philosophy to AudienceProfile.
+ *
+ * The two profiles compose additively with the audience overlay:
+ *
+ *   composite = baseScore
+ *             + scaleBias(scale,   capability, profile)
+ *             + qualityBias(quality, capability, profile)
+ *             + audienceBias(audience, capability)
+ *
+ * Each layer can be omitted independently. Most adjust ranking only, but
+ * per-chart scale preferences can also hard-filter via `minBand`/`maxBand`
+ * exclusions in addition to `fits()`.
+ */
+import type { ChartCapability, ChartDataProfile } from "./chartCapabilityTypes";
+/**
+ * Coarse row-count band. Used for grouping suggestions ("show me charts that
+ * work at small scale") and for surfacing scale-band on each suggestion.
+ *
+ * Defaults below are research-backed starting points — see DEFAULT_SCALE_THRESHOLDS.
+ */
+export type ScaleBand = "tiny" | "small" | "medium" | "large" | "huge";
+/**
+ * Coarse cardinality band. A "low"-cardinality field is bar-chart-able;
+ * "high" almost always wants treemap, force layout, or aggregation.
+ */
+export type CardinalityBand = "low" | "medium" | "high";
+/**
+ * Field-count band. "narrow" datasets need at most one mark per column;
+ * "wide" datasets typically need a matrix-style layout (parallel coords,
+ * scatterplot matrix, heatmap of fields).
+ */
+export type FieldBand = "narrow" | "typical" | "wide";
+/**
+ * Research-backed default breakpoints. Treat as starting points — orgs override
+ * via `DataScaleProfile.thresholds`.
+ *
+ * Row thresholds:
+ *   • tiny ≤ 3      — single-value territory; recommendation often "a value, not a chart"
+ *   • small ≤ 25    — Miller's 7±2 plus a comfortable buffer; bar/pie/dot legible
+ *   • medium ≤ 250  — line/scatter/area sweet spot (Cleveland-McGill, position channel)
+ *   • large ≤ 5000  — dense scatter/heatmap/ridgeline (Munzner ch. 10 quantitative encoding)
+ *   • huge > 5000   — aggregation, sampling, density reduction required (Few, "Now You See It")
+ *
+ * Cardinality (per categorical field):
+ *   • low ≤ 7       — Miller (1956); robust bar chart
+ *   • medium ≤ 25   — bar still legible with care; treemap competitive
+ *   • high > 25     — treemap, packed force, or aggregation
+ *
+ * Field count:
+ *   • narrow ≤ 3    — single-mark-per-row layouts dominate
+ *   • typical ≤ 10  — standard catalog applies
+ *   • wide > 10     — parallel coords / scatterplot matrix territory
+ *
+ * References:
+ *   - Miller, G.A. (1956). "The Magical Number Seven, Plus or Minus Two."
+ *     Psychological Review, 63(2), 81–97.
+ *   - Cleveland, W.S. & McGill, R. (1984). "Graphical Perception: Theory,
+ *     Experimentation, and Application to the Development of Graphical Methods."
+ *     JASA, 79(387), 531–554.
+ *   - Munzner, T. (2014). Visualization Analysis and Design, ch. 10.
+ *   - Few, S. (2009). Now You See It: Simple Visualization Techniques for
+ *     Quantitative Analysis.
+ */
+export declare const DEFAULT_SCALE_THRESHOLDS: {
+    readonly rows: {
+        readonly tiny: 3;
+        readonly small: 25;
+        readonly medium: 250;
+        readonly large: 5000;
+    };
+    readonly cardinality: {
+        readonly low: 7;
+        readonly medium: 25;
+    };
+    readonly fields: {
+        readonly narrow: 3;
+        readonly typical: 10;
+    };
+};
+export interface ScaleThresholds {
+    rows?: {
+        tiny?: number;
+        small?: number;
+        medium?: number;
+        large?: number;
+    };
+    cardinality?: {
+        low?: number;
+        medium?: number;
+    };
+    fields?: {
+        narrow?: number;
+        typical?: number;
+    };
+}
+/**
+ * Per-chart scale preference — analogous to AudienceProfile.targets but scoped
+ * to scale fit. Lets orgs say "we'd rather not see Heatmap below 100 rows even
+ * when the engine thinks it's competitive."
+ */
+export interface ChartScalePreference {
+    /** Add this many points to the composite score for this chart. Range -3..+3. */
+    bias?: number;
+    /** Restrict suggestion of this chart to data with rows in this band or above. */
+    minBand?: ScaleBand;
+    /** Restrict suggestion of this chart to data with rows in this band or below. */
+    maxBand?: ScaleBand;
+    /** Human-readable rationale. Surfaces in suggestion.reasons when the rule fires. */
+    reason?: string;
+}
+/**
+ * Forward-looking declaration of how big the user's data actually is. The row
+ * data passed to suggestCharts may be a sample, a stub, or a future projection;
+ * DataScaleProfile is what the chart needs to actually handle at production.
+ *
+ * Every field is optional. Omitting a field falls back to what profileData()
+ * measured from the sample. Specifying a field overrides the measurement.
+ */
+export interface DataScaleProfile {
+    /**
+     * Production row count. May be larger than the sample passed to suggestCharts.
+     * Accepts a band string ("medium") for hand-waving estimates, or an exact number.
+     */
+    rows?: number | ScaleBand;
+    /**
+     * Production field/column count. Affects parallel-coords / matrix recommendations.
+     */
+    fields?: number | FieldBand;
+    /**
+     * Per-field cardinality. Use field name as key; value is distinct count or band.
+     * @example cardinality: { region: 12, status: "low" }
+     */
+    cardinality?: Partial<Record<string, number | CardinalityBand>>;
+    /**
+     * Aggregate cardinality fallback when per-field isn't declared. The "typical"
+     * categorical field in this dataset has this much cardinality.
+     */
+    typicalCardinality?: number | CardinalityBand;
+    /**
+     * How does this dataset grow?
+     *   • "static"    — fixed, or refreshed periodically as a whole
+     *   • "appending" — grows by adding rows; old rows are stable
+     *   • "windowed"  — sliding window of recent data (e.g. last 7 days)
+     * Affects streaming recommendations and decay/staleness defaults.
+     */
+    growth?: "static" | "appending" | "windowed";
+    /**
+     * Override the default scale thresholds for this profile. Orgs use this to
+     * encode their own definition of "small" / "medium" / "large" — e.g. a BI
+     * shop where 10k rows is "small" because dashboards typically run 100k+.
+     */
+    thresholds?: ScaleThresholds;
+    /**
+     * Per-chart preferences. Like AudienceProfile.familiarity / .targets,
+     * orgs can override scale fit on a per-component basis.
+     * @example charts: { Heatmap: { minBand: "medium", reason: "below 50 rows the cells are dominant noise" } }
+     */
+    charts?: Partial<Record<string, ChartScalePreference>>;
+    /** Display name. Surfaced in suggestion.reasons when scale bias fires. */
+    name?: string;
+}
+/**
+ * User-declared data-quality profile. Quality issues affect *which treatment*
+ * of a chart is recommended (broken vs connected lines, log vs linear, with vs
+ * without regression overlay), and can add caveats. Quality biases score
+ * modestly but biases caveats heavily.
+ */
+export interface DataQualityProfile {
+    /**
+     * Fraction of non-null values (0..1). Map of field name → completeness, or
+     * a single aggregate. 1.0 = complete; 0.5 = half the values missing.
+     * @example completeness: { revenue: 0.98, cohort: 0.62 }
+     */
+    completeness?: Partial<Record<string, number>> | number;
+    /**
+     * Fraction of values flagged as outliers (0..1). Affects recommendations
+     * for regression overlays, log scales, and outlier-detection intent.
+     * @example outliers: { revenue: 0.04 }
+     */
+    outliers?: Partial<Record<string, number>> | number;
+    /**
+     * Fraction of values that don't match the dominant type for the field (0..1).
+     * Strings mixed into a numeric column, dates in arbitrary formats, etc.
+     * High heterogeneity → caveats and possibly reject from numeric-required charts.
+     */
+    typeHeterogeneity?: Partial<Record<string, number>> | number;
+    /** Display name. Surfaced in suggestion.reasons when quality bias fires. */
+    name?: string;
+}
+/**
+ * Classify a row count into a ScaleBand using the profile's thresholds (or defaults).
+ */
+export declare function classifyRowBand(rows: number, scale?: DataScaleProfile): ScaleBand;
+/**
+ * Classify cardinality. Per-field if the field is named; otherwise the aggregate.
+ */
+export declare function classifyCardinalityBand(count: number, scale?: DataScaleProfile): CardinalityBand;
+/**
+ * Classify field count.
+ */
+export declare function classifyFieldBand(count: number, scale?: DataScaleProfile): FieldBand;
+/**
+ * Compare two bands by order (tiny < small < medium < large < huge).
+ * Returns negative if a < b, zero if equal, positive if a > b.
+ */
+export declare function compareBands(a: ScaleBand, b: ScaleBand): number;
+/**
+ * Resolve a declared `rows` value (number, band, or undefined) to an effective
+ * row count for bias calculations. Bands resolve to the midpoint of their range.
+ *
+ * When the user declares a number, we use it directly. When they declare a band,
+ * we use a representative point inside that band. When they declare nothing,
+ * we fall back to the profile's measured rowCount.
+ */
+export declare function resolveRowsToNumber(declared: number | ScaleBand | undefined, measuredRows: number, scale?: DataScaleProfile): number;
+/**
+ * Resolve a declared cardinality value to a number.
+ */
+export declare function resolveCardinalityToNumber(declared: number | CardinalityBand | undefined, measured: number | undefined, scale?: DataScaleProfile): number | undefined;
+/**
+ * The effective scale view the engine reasons over. Merges the declared
+ * DataScaleProfile with the profile's measured stats. Surfaced on each
+ * Suggestion so callers can detect threshold crossings ("you outgrew this
+ * chart") and so the conversational layer can narrate scale rationale.
+ */
+export interface EffectiveScale {
+    /** Effective row count after merging declared scale with measured profile. */
+    rows: number;
+    /** Band classification of the effective row count. */
+    rowBand: ScaleBand;
+    /** Effective field count. */
+    fields: number;
+    /** Band classification of the effective field count. */
+    fieldBand: FieldBand;
+    /** Typical-category cardinality, if known. */
+    typicalCardinality?: number;
+    /** Band of that cardinality. */
+    cardinalityBand?: CardinalityBand;
+    /** Pass-through of growth mode (defaults to "static"). */
+    growth: "static" | "appending" | "windowed";
+    /** Source of the rows number: "declared" if user provided, "measured" otherwise. */
+    rowsSource: "declared" | "measured";
+}
+/**
+ * Compute the effective scale for a profile under the optional declared scale.
+ * When no scale is declared, the profile's measured stats define everything.
+ */
+export declare function computeEffectiveScale(profile: ChartDataProfile, scale?: DataScaleProfile): EffectiveScale;
+export interface ScaleBiasResult {
+    /** Score delta to apply to the suggestion composite. */
+    delta: number;
+    /** Reasons to append to the suggestion.reasons[] array. */
+    reasons: string[];
+    /** Caveats to append (mostly from quality). */
+    caveats: string[];
+    /** True if a per-chart minBand/maxBand restriction excluded this chart. */
+    excluded: boolean;
+}
+/**
+ * Apply scale and quality bias to a chart's composite score.
+ *
+ * Two terms compose additively beyond the audience bias:
+ *   • Capability scale-fit: each capability optionally declares a `scaleFit`
+ *     function returning {delta, reason?, caveat?}. Range ±SCALE_BIAS_MAX.
+ *   • Org per-chart preference: `DataScaleProfile.charts[component]` can
+ *     pin a chart to a band range (excludes outside it) and add an
+ *     org-defined bias. Range ±PREFERENCE_BIAS_MAX.
+ *
+ * Pure function — used by both `suggestCharts` and any caller that needs
+ * to reason about a single (capability × variant × scale) tuple.
+ */
+export declare function applyScaleBias(capability: ChartCapability, profile: ChartDataProfile, effectiveScale: EffectiveScale, scale: DataScaleProfile | undefined, quality: DataQualityProfile | undefined): ScaleBiasResult;
+/**
+ * Declarative sugar for capability authors. Convert a hint object into a
+ * scaleFit function. The hint object expresses the sweet-spot row range and
+ * optional cardinality range; the engine derives a smooth bias curve.
+ *
+ * Use this when the chart's scale behavior is straightforward. For more
+ * sophisticated logic (e.g. "smoothing variant degrades faster at high cardinality"),
+ * write a scaleFit function directly.
+ *
+ * @example
+ * scaleFit: scaleHints({
+ *   rows: { sweetSpot: [25, 1000], caveatAbove: 5000 },
+ *   cardinality: { sweetSpot: [3, 15], caveatAbove: 30 },
+ * })
+ */
+export interface ScaleHintInput {
+    rows?: {
+        sweetSpot: [number, number];
+        caveatAbove?: number;
+        caveatBelow?: number;
+    };
+    cardinality?: {
+        sweetSpot: [number, number];
+        caveatAbove?: number;
+    };
+}
+export type ScaleFitFn = (profile: ChartDataProfile, effective: EffectiveScale, scale: DataScaleProfile | undefined) => ScaleFitResult | null;
+export interface ScaleFitResult {
+    delta: number;
+    reason?: string;
+    caveats?: string[];
+}
+export type QualityFitFn = (profile: ChartDataProfile, quality: DataQualityProfile) => ScaleFitResult | null;
+/**
+ * Build a scaleFit function from a declarative hint shape. Smooth bias —
+ * positive inside the sweet spot, decays toward zero, and tips negative
+ * past the caveat thresholds. The decay is gradual rather than a cliff
+ * so a chart isn't all-or-nothing at the boundary.
+ */
+export declare function scaleHints(hint: ScaleHintInput): ScaleFitFn;

package/dist/components/ai/describeChart.d.ts

@@ -0,0 +1,114 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartCapability, ChartFamily } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * describeChart — generate a layered natural-language description of a chart
+ * from its `(component, props)` config, following Lundgard & Satyanarayan's
+ * four-level model of semantic content (IEEE VIS 2021):
+ *
+ *   L1 (encoding)   — chart type and what's mapped to which channel.
+ *   L2 (statistics) — ranges, mean, extrema (the level blind/low-vision
+ *                     readers rank *most* useful, alongside L3).
+ *   L3 (trends)     — overall direction and notable shape over an ordered axis.
+ *   L4 (intent)     — the *illocutionary* sentence: what communicative act the
+ *                     chart performs and which feature it asks the reader to act
+ *                     on ("This is an alerting chart; the May spike warrants a
+ *                     closer look."). Opt-in — only emitted when the caller
+ *                     supplies the chart's capability descriptor (or an explicit
+ *                     communicative act). Without that intent metadata, the
+ *                     domain meaning stays the author's `summary` or an LLM's
+ *                     job, as before.
+ *
+ * Pure, SSR-safe, dependency-light (the new capability/audience inputs are
+ * type-only — no runtime registry pull). Wired into ChartContainer as an opt-in
+ * full-accessibility affordance (see ChartContainer's `describe` prop); also
+ * usable directly, surfaced by the accessibility audit, and composed by
+ * `buildReaderGrounding` into the agent-reader payload.
+ */
+export type DescribeLevel = "l1" | "l2" | "l3" | "l4";
+/**
+ * The communicative act a chart performs — its illocutionary force, the verb
+ * behind "what is this chart *doing*?". Derived from the dominant intent (or
+ * the chart family as a fallback) and used to phrase the L4 sentence.
+ */
+export type CommunicativeAct = "alerting" | "tracking" | "comparing" | "ranking" | "apportioning" | "characterizing" | "relating" | "tracing" | "nesting" | "locating" | "presenting";
+/**
+ * Lightweight intent context for the L4 sentence. Either hand `describeChart`
+ * a full {@link ChartCapability} (its static `intentScores` are read; function
+ * scorers are skipped since no data profile is in scope here) or this resolved
+ * shape — e.g. a `Suggestion`'s already-resolved `{ family, intentScores }`,
+ * which is the most precise source.
+ */
+export interface DescribeCapabilityContext {
+    /** Chart family — anchors the communicative act when intent scores are absent. */
+    family?: ChartFamily;
+    /** Per-intent scores (0..5), already resolved. The top-scoring intent picks the act. */
+    intentScores?: Partial<Record<IntentId, number>>;
+    /** Explicit override — skips intent/family inference entirely. */
+    act?: CommunicativeAct;
+}
+export interface DescribeChartResult {
+    /** The selected levels joined into one description (what you'd feed a summary). */
+    text: string;
+    /** Each level on its own, so callers can pick verbosity. */
+    levels: {
+        l1?: string;
+        l2?: string;
+        l3?: string;
+        l4?: string;
+    };
+    /**
+     * The author's marked features, as a sentence — present only when the chart
+     * carries `annotations`. An annotation is author intent in its purest form,
+     * so it leads `text` ahead of the auto-derived L1–L3: a non-visual or agent
+     * reader hears what the author chose to call out first. Provenance-aware —
+     * an AI- or watcher-authored note is qualified as such.
+     */
+    annotations?: string;
+}
+export interface DescribeChartOptions {
+    /**
+     * Which semantic levels to include. Default ["l1","l2","l3"]. L4 is appended
+     * automatically when `capability` (or `capability.act`) is provided and
+     * `levels` is left at the default; pass `levels` explicitly to override.
+     */
+    levels?: DescribeLevel[];
+    /** Locale for number formatting. Default "en". */
+    locale?: string;
+    /**
+     * Intent context that powers the L4 illocutionary sentence — a chart's
+     * capability descriptor or a resolved {@link DescribeCapabilityContext}.
+     * Closes the L1–L3 → L4 gap by joining the *production*-side intent metadata
+     * (which already lives in each `*.capability.ts`) to the *reception*-side
+     * description.
+     */
+    capability?: ChartCapability | DescribeCapabilityContext;
+    /**
+     * Audience profile — tunes the L4 sentence for reception. When the chart's
+     * familiarity for this audience is low, L4 appends a brief orienting nudge so
+     * an unfamiliar reader leans on the description.
+     */
+    audience?: AudienceProfile;
+}
+/** The communicative act a built-in intent implies, or undefined if unknown. */
+export declare function communicativeActForIntent(intent: IntentId): CommunicativeAct | undefined;
+/**
+ * Resolve the communicative act for a chart from (in priority order) an explicit
+ * act, the dominant resolved intent, the declared family, or the component's own
+ * family classification. Returns undefined only when nothing identifies it.
+ */
+export declare function resolveCommunicativeAct(component: string, context: ChartCapability | DescribeCapabilityContext | undefined): CommunicativeAct | undefined;
+/** Build a number formatter — compact (6.5M) for large magnitudes, plain
+ *  otherwise. Exported so the navigation tree formats values identically. */
+export declare function chartValueFormatter(locale?: string): (n: number) => string;
+/**
+ * One human phrase for a single annotation — its kind (provenance-qualified),
+ * plus its label if it has one: `an AI-suggested callout labeled "Peak"`.
+ * Exported so the navigation tree (`buildNavigationTree`) labels its annotation
+ * nodes with the same vocabulary the prose description uses — tree and prose
+ * speak the same language. Editorial status is *not* included here (it would
+ * change the prose sentence); callers that want it append it themselves.
+ */
+export declare function annotationPhrase(ann: Datum): string;
+export declare function describeChart(component: string, props: Datum, options?: DescribeChartOptions): DescribeChartResult;

package/dist/components/ai/diffProfile.d.ts

@@ -0,0 +1,51 @@
+import type { ChartDataProfile, FieldKind } from "./chartCapabilityTypes";
+export type PrimaryRole = "x" | "y" | "size" | "category" | "series" | "time";
+export interface FieldTypeChange {
+    field: string;
+    from: FieldKind | "unknown";
+    to: FieldKind | "unknown";
+}
+export interface PrimaryRoleChange {
+    role: PrimaryRole;
+    from: string | undefined;
+    to: string | undefined;
+}
+export interface ProfileDiff {
+    /** Row count change (b.rowCount - a.rowCount). */
+    rowCountChange: number;
+    /** Fields present in b but not in a. */
+    added: ReadonlyArray<string>;
+    /** Fields present in a but not in b. */
+    removed: ReadonlyArray<string>;
+    /** Fields whose inferred type changed. */
+    typeChanges: ReadonlyArray<FieldTypeChange>;
+    /** Primary role re-assignments (e.g. x switched from "month" to "date"). */
+    primaryChanges: ReadonlyArray<PrimaryRoleChange>;
+    /** Suggestion components that fit a but not b. */
+    becameUnfit: ReadonlyArray<string>;
+    /** Suggestion components that fit b but not a. */
+    becameFit: ReadonlyArray<string>;
+    /** True when no observable change was detected. */
+    unchanged: boolean;
+}
+/**
+ * Compare two profiles and report what changed plus how the change affects
+ * chart suitability. Useful for:
+ *
+ *   • "Why does my dashboard look different after the data refreshed?"
+ *   • Editor warnings when a CSV upload would change the visible charts.
+ *   • CI checks that flag when a fixture migration affects descriptor coverage.
+ *
+ * Doesn't compute *which suggestions ranked first* (that requires intent +
+ * full suggestCharts). Reports only structural deltas — added/removed fields,
+ * type changes, primary role re-assignments, fit set changes.
+ *
+ * @example
+ * const a = profileData(yesterdaysData)
+ * const b = profileData(todaysData)
+ * const diff = diffProfile(a, b)
+ * if (diff.becameUnfit.length) {
+ *   console.warn(`These charts no longer fit: ${diff.becameUnfit.join(", ")}`)
+ * }
+ */
+export declare function diffProfile(a: ChartDataProfile, b: ChartDataProfile): ProfileDiff;

package/dist/components/ai/inferIntent.d.ts

@@ -0,0 +1,24 @@
+import type { IntentId } from "./intents";
+export interface InferIntentResult {
+    intent: IntentId;
+    /** 1..5 score for ranking ties. Higher = stronger match. */
+    confidence: number;
+    /** Other plausible intents, sorted by confidence. */
+    alternates: ReadonlyArray<{
+        intent: IntentId;
+        confidence: number;
+    }>;
+}
+/**
+ * Map a natural-language query to a built-in intent. Returns `null` when no
+ * pattern matches with meaningful confidence.
+ *
+ * @example
+ * inferIntent("when did revenue peak?")
+ *   // → { intent: "outlier-detection", confidence: 4, alternates: [] }
+ * inferIntent("show me the trend over time")
+ *   // → { intent: "trend", confidence: 4, alternates: [] }
+ * inferIntent("hello")
+ *   // → null
+ */
+export declare function inferIntent(query: string): InferIntentResult | null;

package/dist/components/ai/intents.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical intent taxonomy for chart suggestion / interrogation.
+ *
+ * An "intent" is what the user is trying to *see* in the data. Charts declare how
+ * well they serve each intent in their capability descriptor. The suggestion engine
+ * filters and ranks by intent.
+ *
+ * The taxonomy is fixed but extensible: consumers can call `registerIntent` to add
+ * domain-specific intents at runtime. The IntentId type stays union-of-known so
+ * built-in code remains type-safe; registered intents are addressable as plain strings.
+ */
+export type BuiltInIntentId = "trend" | "compare-series" | "compare-categories" | "rank" | "part-to-whole" | "distribution" | "correlation" | "flow" | "hierarchy" | "geo" | "outlier-detection" | "composition-over-time" | "change-detection";
+/**
+ * Any intent — built-in or user-registered. Custom intents are plain strings.
+ */
+export type IntentId = BuiltInIntentId | (string & {});
+export interface IntentDescriptor {
+    id: IntentId;
+    label: string;
+    description: string;
+    /** Soft hint of which chart family typically serves this intent. */
+    familyHint?: "time-series" | "categorical" | "distribution" | "relationship" | "flow" | "network" | "hierarchy" | "geo";
+}
+/** Get an intent descriptor by id, or undefined if not registered. */
+export declare function getIntent(id: IntentId): IntentDescriptor | undefined;
+/** All currently-registered intents (built-in + user-added). */
+export declare function listIntents(): IntentDescriptor[];
+/**
+ * Register a custom intent at runtime. Idempotent — re-registering with the same id
+ * replaces the descriptor.
+ */
+export declare function registerIntent(intent: IntentDescriptor): void;
+/** Sentinel set used by capability authors to opt out of an intent without misspelling. */
+export declare const BUILT_IN_INTENT_IDS: ReadonlySet<BuiltInIntentId>;

package/dist/components/ai/navigationTree.d.ts

@@ -0,0 +1,45 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * buildNavigationTree — turn a chart config into a structured, labeled
+ * navigation tree (chart → axes/series → data points), following the Olli /
+ * Data Navigator model: a navigable *structure*, uncoupled from how the chart
+ * is rendered (canvas, SVG, image). A screen-reader user descends the tree —
+ * "Series sales" → "point 3 of 9: March, 6,800" — with spoken structural
+ * context at each level, instead of wading through a flat point list.
+ *
+ * Pure and SSR-safe. Composes `describeChart()` for node labels so the tree and
+ * the prose description speak the same language. Rendered by `AccessibleNavTree`
+ * and surfaced as the opt-in ChartContainer `navigable` affordance.
+ */
+export type NavTreeRole = "chart" | "axis" | "series" | "datum" | "annotation";
+export interface NavTreeNode {
+    /** Stable id within the tree. */
+    id: string;
+    role: NavTreeRole;
+    /** What assistive tech announces for this node. */
+    label: string;
+    /** 1-based depth (maps to aria-level). */
+    level: number;
+    /** Measure value, for datum leaves. */
+    value?: number;
+    /** Raw datum, for datum leaves. */
+    datum?: Datum | null;
+    children?: NavTreeNode[];
+}
+export interface BuildNavigationTreeOptions {
+    /** Cap leaves per branch (keeps a 50k-row chart from building a giant tree). Default 200. */
+    maxLeaves?: number;
+    locale?: string;
+}
+/**
+ * Build a structured navigation tree for a chart config. Full trees for XY,
+ * bar, part-to-whole, and distribution families; for everything else (network,
+ * hierarchy, geo, single value) it returns a root-only node with an L1 label
+ * rather than inventing a structure.
+ */
+export declare function buildNavigationTree(component: string, props: Datum, options?: BuildNavigationTreeOptions): NavTreeNode;
+/** Flatten a tree to its visible nodes given a set of expanded node ids, in DFS
+ *  order. Used by the renderer for roving-tabindex keyboard navigation. */
+export declare function flattenVisible(root: NavTreeNode, expanded: Set<string>): NavTreeNode[];
+/** Total descendant + self count — handy for tests and summaries. */
+export declare function countNodes(root: NavTreeNode): number;

package/dist/components/ai/profileData.d.ts

@@ -0,0 +1,16 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartDataProfile } from "./chartCapabilityTypes";
+export interface ProfileDataOptions {
+    /** If you have access to the raw input (which might be {nodes, edges} or GeoJSON), pass it for structure detection. */
+    rawInput?: unknown;
+    /** Override the field used as the primary series, useful when the heuristic guesses wrong. */
+    seriesField?: string;
+}
+/**
+ * Build a ChartDataProfile from row data. Extends DataSummary with shape inference —
+ * candidate fields per role, distinct counts, monotonicity, and structure detection.
+ *
+ * Designed to be called once per dataset; the result is what `suggestCharts` and
+ * capability evaluators consume.
+ */
+export declare function profileData(data: ReadonlyArray<Datum> | null | undefined, options?: ProfileDataOptions): ChartDataProfile;

package/dist/components/ai/qualityFixtures.d.ts

@@ -0,0 +1,2 @@
+import type { ScorecardFixture } from "./qualityScorecard";
+export declare const CANONICAL_FIXTURES: ReadonlyArray<ScorecardFixture>;