semiotic 3.5.3 → 3.6.0

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-**Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
+**Use sub-path imports** — `semiotic/xy` (86KB gz), `semiotic/ordinal` (70KB gz), `semiotic/network` (64KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (91KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (211KB gz). Full `semiotic` is 190KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)

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

@@ -0,0 +1,90 @@
+import type { ChartRubric } from "./chartCapabilityTypes";
+/**
+ * A serializable description of who's reading the charts and what the
+ * organization is trying to grow.
+ *
+ * Semiotic does not measure familiarity — it consumes measurements. Orgs
+ * produce an AudienceProfile through whatever channel makes sense (surveys,
+ * telemetry, manager judgment, training records) and pass it to the
+ * suggestion APIs. The library applies the bias and returns rankings that
+ * reflect the audience instead of a generic data-literate baseline.
+ *
+ * Strategy memo: docs/strategy/audience-profiles.md
+ */
+export interface AudienceProfile {
+    /**
+     * Display name. Surfaced in suggestion `reasons[]` when a target fires so
+     * users can see whose policy is influencing the ranking.
+     */
+    name?: string;
+    /**
+     * Per-chart familiarity override (1..5). Replaces the descriptor's
+     * `rubric.familiarity`. Charts not listed fall back to the descriptor.
+     *
+     * @example
+     * familiarity: { BarChart: 5, LineChart: 5, PieChart: 4, BoxPlot: 2 }
+     */
+    familiarity?: Partial<Record<string, number>>;
+    /**
+     * Adoption targets — which charts the org is trying to grow or reduce.
+     * The engine applies a meaningful score bias (±1..3 depending on weight)
+     * so growth targets win close calls and decrease targets fall back unless
+     * they're the only fit.
+     *
+     * @example
+     * targets: {
+     *   PieChart: { direction: "decrease", weight: 1 },
+     *   BoxPlot:  { direction: "increase", weight: 2,
+     *               reason: "we want the team reading distributions, not means" }
+     * }
+     */
+    targets?: Partial<Record<string, AudienceTarget>>;
+    /**
+     * Controls visibility of stretch picks (unfamiliar-but-relevant charts).
+     *   0 — never surface stretches; familiar-only rankings
+     *   1 — surface in a separate `stretchSuggestions` list (default when audience set)
+     *   2 — same as 1 but lowers the familiarity threshold (≤4) for what counts as stretch,
+     *       widening the menu
+     */
+    exposureLevel?: 0 | 1 | 2;
+}
+export interface AudienceTarget {
+    direction: "increase" | "decrease";
+    /** 1..3 — controls bias magnitude. Default 1. */
+    weight?: number;
+    /** Human-readable rationale. Surfaces in suggestion.reasons when the target fires. */
+    reason?: string;
+}
+export interface AudienceBiasResult {
+    /** Composite score after audience adjustments. Unclamped — can range outside 0..5. */
+    score: number;
+    /** Effective rubric for the chart after audience overrides. */
+    rubric: ChartRubric;
+    /** Reason string to append to the suggestion when a target fired. */
+    appliedReason?: string;
+}
+/**
+ * Apply an AudienceProfile's bias to a chart's composite score and rubric.
+ * Pure function — used by both `suggestCharts` and `suggestStretchCharts`.
+ *
+ * Two terms compose additively:
+ *   • Familiarity bias: (audienceFamiliarity − 3) × 0.5
+ *     — Range ±1.0. At familiarity 5 we add 1.0; at 1 we subtract 1.0.
+ *   • Target bias: ±1.0 × weight
+ *     — Range ±3.0 for weight=3. Strong enough to reorder rankings,
+ *       not so strong that it overrides chart correctness for the data shape.
+ *
+ * Score is left unclamped so internal sorting reflects the magnitude of bias.
+ */
+export declare function applyAudienceBias(baseScore: number, baseRubric: ChartRubric, component: string, audience: AudienceProfile | undefined): AudienceBiasResult;
+/**
+ * Resolve the effective familiarity for a chart under an audience. Used by
+ * the stretch surface to decide whether a chart qualifies as "unfamiliar."
+ */
+export declare function effectiveFamiliarity(component: string, defaultFamiliarity: number, audience: AudienceProfile | undefined): number;
+/**
+ * Familiarity threshold for what counts as a "stretch" pick under this audience.
+ * Tighter for exposureLevel 1, wider for 2. Returns the highest familiarity a
+ * chart can have and still appear in the stretch surface.
+ */
+export declare function stretchFamiliarityCeiling(audience: AudienceProfile | undefined): number;

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

@@ -0,0 +1,31 @@
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * Three example AudienceProfile shapes. Not authoritative — these are
+ * sketches based on rough industry stereotypes, useful for documentation,
+ * demos, and as starting points consumers can fork.
+ *
+ * To use one in production, copy it and tune to your audience's actual
+ * survey/telemetry data. Do not assume these defaults represent your team.
+ */
+/**
+ * Executive audience — high familiarity with bar/line/pie/gauge,
+ * limited tolerance for unfamiliar chart shapes. Most likely to encounter
+ * dashboards built by analysts; not building their own.
+ */
+export declare const executivePersona: AudienceProfile;
+/**
+ * Analyst audience — broader chart vocabulary, comfortable with
+ * distribution-shape and matrix-shape charts. Building dashboards for
+ * others; can read most things on first encounter.
+ */
+export declare const analystPersona: AudienceProfile;
+/**
+ * Data scientist audience — comfortable with the full distribution-chart
+ * family, regression overlays, and density encodings. Will accept most
+ * exotic shapes if they're more honest about the data.
+ */
+export declare const dataScientistPersona: AudienceProfile;
+/**
+ * Convenience map for consumers loading audience by name (e.g. from a config string).
+ */
+export declare const BUILT_IN_AUDIENCES: Record<string, AudienceProfile>;

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

@@ -0,0 +1,55 @@
+import type { ChartCapability } from "./chartCapabilityTypes";
+import { LineChartCapability } from "../charts/xy/LineChart.capability";
+import { AreaChartCapability } from "../charts/xy/AreaChart.capability";
+import { StackedAreaChartCapability } from "../charts/xy/StackedAreaChart.capability";
+import { ScatterplotCapability } from "../charts/xy/Scatterplot.capability";
+import { ConnectedScatterplotCapability } from "../charts/xy/ConnectedScatterplot.capability";
+import { BubbleChartCapability } from "../charts/xy/BubbleChart.capability";
+import { QuadrantChartCapability } from "../charts/xy/QuadrantChart.capability";
+import { MultiAxisLineChartCapability } from "../charts/xy/MultiAxisLineChart.capability";
+import { MinimapChartCapability } from "../charts/xy/MinimapChart.capability";
+import { DifferenceChartCapability } from "../charts/xy/DifferenceChart.capability";
+import { CandlestickChartCapability } from "../charts/xy/CandlestickChart.capability";
+import { HeatmapCapability } from "../charts/xy/Heatmap.capability";
+import { BarChartCapability } from "../charts/ordinal/BarChart.capability";
+import { GroupedBarChartCapability } from "../charts/ordinal/GroupedBarChart.capability";
+import { StackedBarChartCapability } from "../charts/ordinal/StackedBarChart.capability";
+import { DotPlotCapability } from "../charts/ordinal/DotPlot.capability";
+import { PieChartCapability } from "../charts/ordinal/PieChart.capability";
+import { DonutChartCapability } from "../charts/ordinal/DonutChart.capability";
+import { FunnelChartCapability } from "../charts/ordinal/FunnelChart.capability";
+import { GaugeChartCapability } from "../charts/ordinal/GaugeChart.capability";
+import { LikertChartCapability } from "../charts/ordinal/LikertChart.capability";
+import { SwimlaneChartCapability } from "../charts/ordinal/SwimlaneChart.capability";
+import { HistogramCapability } from "../charts/ordinal/Histogram.capability";
+import { BoxPlotCapability } from "../charts/ordinal/BoxPlot.capability";
+import { SwarmPlotCapability } from "../charts/ordinal/SwarmPlot.capability";
+import { ViolinPlotCapability } from "../charts/ordinal/ViolinPlot.capability";
+import { RidgelinePlotCapability } from "../charts/ordinal/RidgelinePlot.capability";
+import { ForceDirectedGraphCapability } from "../charts/network/ForceDirectedGraph.capability";
+import { SankeyDiagramCapability } from "../charts/network/SankeyDiagram.capability";
+import { ChordDiagramCapability } from "../charts/network/ChordDiagram.capability";
+import { ProcessSankeyCapability } from "../charts/network/ProcessSankey.capability";
+import { TreeDiagramCapability } from "../charts/network/TreeDiagram.capability";
+import { TreemapCapability } from "../charts/network/Treemap.capability";
+import { CirclePackCapability } from "../charts/network/CirclePack.capability";
+import { OrbitDiagramCapability } from "../charts/network/OrbitDiagram.capability";
+import { ChoroplethMapCapability } from "../charts/geo/ChoroplethMap.capability";
+import { ProportionalSymbolMapCapability } from "../charts/geo/ProportionalSymbolMap.capability";
+import { FlowMapCapability } from "../charts/geo/FlowMap.capability";
+import { DistanceCartogramCapability } from "../charts/geo/DistanceCartogram.capability";
+/**
+ * Register a capability for a chart (built-in or third-party). Re-registering by
+ * component name replaces the previous descriptor — useful for overriding defaults.
+ */
+export declare function registerChartCapability(capability: ChartCapability): void;
+/** Remove a previously-registered capability. Does not affect built-ins. */
+export declare function unregisterChartCapability(component: string): void;
+/**
+ * Current capability list — built-ins, then user-registered, with user-registered
+ * overriding built-ins by component name.
+ */
+export declare function getCapabilities(): ReadonlyArray<ChartCapability>;
+/** Look up a capability by component name. */
+export declare function getCapability(component: string): ChartCapability | undefined;
+export { LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, };

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

@@ -0,0 +1,196 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { DataSummary } from "../data/DataSummarizer";
+import type { IntentId } from "./intents";
+/**
+ * Chart family — high-level taxonomy used for filtering and intent matching.
+ */
+export type ChartFamily = "time-series" | "categorical" | "distribution" | "relationship" | "flow" | "network" | "hierarchy" | "geo" | "realtime" | "custom";
+/**
+ * Where a chart is imported from. Used by generators to emit correct import paths.
+ */
+export type ChartImportPath = "semiotic/xy" | "semiotic/ordinal" | "semiotic/network" | "semiotic/geo" | "semiotic/realtime" | "semiotic/ai" | "semiotic";
+/**
+ * Familiarity/accuracy/precision rubric (1-5 each).
+ * Familiarity = how well-known the chart is to a general audience.
+ * Accuracy    = how faithfully it represents the underlying data.
+ * Precision   = how readable individual values are.
+ */
+export interface ChartRubric {
+    familiarity: number;
+    accuracy: number;
+    precision: number;
+}
+/**
+ * The kind of value a field holds, used for axis fitness.
+ */
+export type FieldKind = "numeric" | "categorical" | "date" | "boolean" | "unknown";
+/**
+ * A candidate field for a given role (x, y, series, etc.), with a quality score.
+ */
+export interface FieldCandidate {
+    field: string;
+    kind: FieldKind;
+    /** 0..1 — how good this field is for the role being considered. */
+    quality: number;
+    /** Field-level stats for downstream scorers. */
+    distinctCount?: number;
+    /** True if the field's values are strictly increasing in row order. */
+    monotonic?: boolean;
+}
+/**
+ * Profile of a dataset for chart-fitness scoring. Extends DataSummary with
+ * shape inference (axis candidates, structure detection, primary roles).
+ */
+export interface ChartDataProfile extends DataSummary {
+    /** Original rows (read-only); used by capabilities to compute their own stats. */
+    data: ReadonlyArray<Datum>;
+    /** Candidate fields per role, sorted best-first. */
+    candidates: {
+        x: FieldCandidate[];
+        y: FieldCandidate[];
+        size: FieldCandidate[];
+        category: FieldCandidate[];
+        series: FieldCandidate[];
+        time: FieldCandidate[];
+    };
+    /** Best-guess primary assignment per role (the top candidate, if any). */
+    primary: {
+        x?: string;
+        y?: string;
+        size?: string;
+        category?: string;
+        series?: string;
+        time?: string;
+    };
+    /** Distinct count of the primary category field, if any. */
+    categoryCount?: number;
+    /** Distinct count of the primary series field, if any. */
+    seriesCount?: number;
+    /** Distinct count of the primary x field, if any. */
+    uniqueXCount?: number;
+    /** True when some x value appears in more than one row (suggests aggregation). */
+    hasRepeatedX: boolean;
+    /** True when the primary x candidate is monotonic. */
+    monotonicX: boolean;
+    /** True when there is at least one date-typed candidate. */
+    hasTimeAxis: boolean;
+    /**
+     * How the primary x role was inferred. Capabilities can use this to detect
+     * the "scatter fallback" case (x picked only because there were 2+ numerics,
+     * not because the field is genuinely an x-axis) and decline to recommend
+     * themselves for trend-shaped intents.
+     *
+     * • "time"   — explicit date/time field
+     * • "named"  — numeric whose name matches an x-pattern (month, year, index, …)
+     * • "scatter"— filled in via the two-numeric scatter fallback; weak signal
+     * • "none"   — no x role inferred
+     */
+    xProvenance: "time" | "named" | "scatter" | "none";
+    /** Source dataset looks like a hierarchy (had a `children` array at root). */
+    hasHierarchy: boolean;
+    /** Source dataset looks like a node/edge graph. */
+    hasNetwork: boolean;
+    /** Source dataset looks like GeoJSON (FeatureCollection). */
+    hasGeo: boolean;
+    /** Extracted network payload when hasNetwork is true. */
+    network?: {
+        nodes: ReadonlyArray<Datum>;
+        edges: ReadonlyArray<Datum>;
+    };
+    /** Extracted hierarchy root when hasHierarchy is true. */
+    hierarchy?: Datum;
+    /** Extracted GeoJSON FeatureCollection when hasGeo is true. */
+    geo?: {
+        features: ReadonlyArray<Datum>;
+        points?: ReadonlyArray<Datum>;
+        flows?: ReadonlyArray<Datum>;
+    };
+}
+/**
+ * An intent scorer is either a static 0..5 score or a function evaluated against the profile.
+ */
+export type IntentScorer = number | ((profile: ChartDataProfile) => number);
+/**
+ * Variant — a configuration of the chart that meaningfully changes what it's good for.
+ *
+ * Variants compose into suggestions. The `intentDeltas` are additive against the
+ * base capability's intent scores (clamped to 0..5 by the engine).
+ */
+export interface ChartVariant {
+    key: string;
+    label: string;
+    description?: string;
+    /** Props to merge into the base chart props. */
+    props: Record<string, unknown>;
+    /** Style/role tags (used by consumers like vizmart for filtering). */
+    tags?: ReadonlyArray<string>;
+    /** Per-intent additive score deltas (e.g. {"trend": +1, "outlier-detection": -2}). */
+    intentDeltas?: Partial<Record<IntentId, number>>;
+    /** Rubric deltas — usually small, e.g. smoothing trades precision for familiarity. */
+    rubricDeltas?: Partial<ChartRubric>;
+    /** Caveats specific to this variant — surfaced in suggestion.caveats. */
+    caveats?: ReadonlyArray<string>;
+}
+/**
+ * Result of a capability's `fits()` gate. `null` means the chart fits. A string
+ * is the human-readable reason it doesn't, used for diagnostics and reasoning.
+ */
+export type FitResult = null | string;
+/**
+ * The capability descriptor each chart ships alongside itself.
+ *
+ * Charts that declare a capability participate in `suggestCharts`, `useChartSuggestions`,
+ * and the `interrogateChart` MCP tool's recommendation surface.
+ */
+export interface ChartCapability {
+    component: string;
+    family: ChartFamily;
+    importPath: ChartImportPath;
+    /** Base rubric, before variant/profile adjustments. */
+    rubric: ChartRubric;
+    /**
+     * Hard requirements gate. Return null if the chart can render this profile,
+     * or a human-readable string explaining why not (e.g. "no numeric y candidate").
+     */
+    fits: (profile: ChartDataProfile) => FitResult;
+    /**
+     * Per-intent suitability score (0..5). Missing intents default to 0.
+     * Values may be functions for profile-aware scoring.
+     */
+    intentScores: Partial<Record<IntentId, IntentScorer>>;
+    /**
+     * Variants — different settings that change what the chart is useful for.
+     * Suggestion engine emits one suggestion per (capability × variant) pair.
+     * If empty, the engine still emits a base suggestion.
+     */
+    variants?: ReadonlyArray<ChartVariant>;
+    /** Caveats independent of variants (e.g. "log scale skipped for negative values"). */
+    caveats?: (profile: ChartDataProfile) => ReadonlyArray<string>;
+    /**
+     * Build the props you'd pass to this chart for this dataset. Should produce
+     * a runnable config (accessor names, etc.) so consumers can `<Component {...props}>`.
+     */
+    buildProps: (profile: ChartDataProfile, variant?: ChartVariant) => Record<string, unknown>;
+}
+/**
+ * One suggestion produced by `suggestCharts`. Consumers render this as a card,
+ * pass it to an LLM for re-ranking, or hand the props straight to the chart.
+ */
+export interface Suggestion {
+    component: string;
+    family: ChartFamily;
+    importPath: ChartImportPath;
+    variant?: ChartVariant;
+    /** Composite score for the ranking intent(s), 0..5. */
+    score: number;
+    /** Per-intent scores after variant deltas. */
+    intentScores: Partial<Record<IntentId, number>>;
+    /** Rubric after variant/profile adjustments. */
+    rubric: ChartRubric;
+    /** Narrative reasons this chart fits — suitable for tooltips or LLM context. */
+    reasons: ReadonlyArray<string>;
+    /** Gotchas / things to be careful about. */
+    caveats: ReadonlyArray<string>;
+    /** Ready-to-spread props. */
+    props: Record<string, unknown>;
+}

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

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

@@ -0,0 +1,82 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartCapability } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+/**
+ * One canonical fixture in a scorecard run. Pair canonical data with the
+ * intents/components a human expert would expect to win on it. Use null
+ * `expected` when the fixture is a stress-test that should produce no
+ * fitting chart at all (e.g. flat single-column data, broken GeoJSON).
+ */
+export interface ScorecardFixture {
+    name: string;
+    /** Free-text shape description, used in scorecard output for context. */
+    shape?: string;
+    data: ReadonlyArray<Datum>;
+    /** Optional non-tabular payload (network/hierarchy/GeoJSON). */
+    rawInput?: unknown;
+    /** Intent to rank by. If omitted, scored without intent (mean-of-all). */
+    intent?: IntentId;
+    /** Components the human expert would pick. Empty = "anything fits". */
+    expected?: ReadonlyArray<string>;
+    /** True if the fixture should produce zero fitting suggestions. Mutually exclusive with `expected`. */
+    expectsNoFit?: boolean;
+}
+export interface PerCapabilityScore {
+    component: string;
+    family: ChartCapability["family"];
+    /** Number of fixtures where this capability fit. */
+    fitsOn: number;
+    /** Number of fixtures where this capability was rejected. */
+    rejectedOn: number;
+    /** Number of fixtures where this capability appeared in the top-3 ranked suggestions. */
+    inTopThreeOn: number;
+    /** Fixtures where the human expert picked this chart AND it was in top-3 ranking. */
+    expertAgreementCount: number;
+    /** Mean composite score across fixtures where it fit. */
+    averageScore: number;
+    /** Fraction of suggestions that included at least one caveat. */
+    caveatCoverage: number;
+    /** Fraction of suggestions that picked a non-base variant. */
+    variantUtilization: number;
+}
+export interface PerFixtureScore {
+    fixture: string;
+    shape?: string;
+    intent?: IntentId;
+    expected?: ReadonlyArray<string>;
+    topPick?: {
+        component: string;
+        variantKey?: string;
+        score: number;
+    };
+    topThree: ReadonlyArray<{
+        component: string;
+        variantKey?: string;
+        score: number;
+    }>;
+    fittingCount: number;
+    rejectedCount: number;
+    /** True if the top-3 ranking contained at least one expected component (when expected is provided). */
+    expertAgreement: boolean | null;
+    /** Did the engine honor `expectsNoFit`? */
+    noFitHonored: boolean | null;
+}
+export interface ScorecardReport {
+    perCapability: PerCapabilityScore[];
+    perFixture: PerFixtureScore[];
+    summary: {
+        fixtureCount: number;
+        capabilityCount: number;
+        /** Fraction of expectation-bearing fixtures where the engine agreed with the expert. */
+        expertAgreementRate: number;
+        /** Average caveat coverage across all suggestions. */
+        overallCaveatCoverage: number;
+        /** Average variant utilization across all suggestions. */
+        overallVariantUtilization: number;
+    };
+}
+/**
+ * Run the scorecard. Pure — does no I/O — so it can be called from CI scripts,
+ * vizmart UIs, or test suites.
+ */
+export declare function runQualityScorecard(fixtures: ReadonlyArray<ScorecardFixture>, capabilities?: ReadonlyArray<ChartCapability>): ScorecardReport;