semiotic 3.5.4 → 3.6.0

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;

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

@@ -0,0 +1,73 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+/**
+ * Repair result when the chosen chart fits the data — nothing to fix.
+ */
+export interface RepairOkResult {
+    status: "ok";
+    component: string;
+    /** The same data profile that was evaluated. */
+    profile: ChartDataProfile;
+}
+/**
+ * Repair result when the chosen chart doesn't fit. Carries the diagnostic
+ * reason from the capability's `fits()` plus ranked alternatives that *do*
+ * fit, with their reasons surfaced for caller narration.
+ */
+export interface RepairAlternativeResult {
+    status: "alternative";
+    /** The component the caller asked about. */
+    component: string;
+    /** Why it doesn't fit. */
+    reason: string;
+    /** Whether the caller intended one of the alternatives anyway. */
+    alternatives: Suggestion[];
+    profile: ChartDataProfile;
+}
+/**
+ * Repair result when no capability is registered for the asked component.
+ */
+export interface RepairUnknownResult {
+    status: "unknown";
+    component: string;
+    /** Closest matches by family/intent — best effort. */
+    alternatives: Suggestion[];
+    profile: ChartDataProfile;
+}
+export type RepairResult = RepairOkResult | RepairAlternativeResult | RepairUnknownResult;
+export interface RepairOptions {
+    /** Caller's intent — informs ranking of alternatives when the chart doesn't fit. */
+    intent?: IntentId | IntentId[];
+    /** Non-tabular payload (network/hierarchy/GeoJSON). Forwarded to profileData. */
+    rawInput?: unknown;
+    /** Limit number of alternatives returned (default 3). */
+    maxAlternatives?: number;
+    /** Pre-computed profile, avoids recomputation. */
+    profile?: ChartDataProfile;
+}
+/**
+ * Validate that a chart component is a sensible choice for a dataset, and
+ * if not, propose alternatives that *do* fit — ranked by the caller's
+ * intent if provided.
+ *
+ * This is the "auto-fix" surface for `--doctor` and agent retry loops.
+ * Given a chart + data, returns either:
+ *
+ *   - { status: "ok", component }                — the chart fits, ship it
+ *   - { status: "alternative", reason, alternatives } — the chart doesn't
+ *       fit; here are charts that do, ranked by intent if specified
+ *   - { status: "unknown", alternatives }        — we don't have a
+ *       capability for that component name; here are sensible defaults
+ *
+ * The contract: a caller can always render `alternatives[0]` and get
+ * something useful. The `reason` field is suitable for verbatim display
+ * to the user.
+ *
+ * @example
+ * repairChartConfig("PieChart", productData, { intent: "rank" })
+ *   // → { status: "alternative",
+ *   //     reason: "9 slices is too many for a pie chart",
+ *   //     alternatives: [BarChart, DotPlot, ...] }
+ */
+export declare function repairChartConfig(component: string, data: ReadonlyArray<Datum> | null | undefined, options?: RepairOptions): RepairResult;

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

@@ -0,0 +1,64 @@
+import type { ChartRubric } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+/**
+ * Streaming chart selection has a different shape than static. We don't have
+ * rows yet — we have a *schema*: which fields will arrive, what types, plus
+ * environment hints (throughput, retention).
+ *
+ * Rather than overloading `profileData` (which is row-statistics-centric) we
+ * model streams as a parallel API. The two share the intent vocabulary —
+ * "trend" still means trend — but the suitability logic is its own thing.
+ */
+export type StreamFieldKind = "numeric" | "categorical" | "date" | "boolean";
+export interface StreamFieldSchema {
+    name: string;
+    kind: StreamFieldKind;
+    /** Optional role hint — overrides the engine's inference. */
+    role?: "x" | "y" | "value" | "category" | "series" | "size";
+}
+/**
+ * Schema describing what a stream emits. No data, just shape + environment hints.
+ */
+export interface StreamSchema {
+    fields: ReadonlyArray<StreamFieldSchema>;
+    /**
+     * Hint about expected event rate. Affects chart selection — heatmaps and
+     * waterfalls amortize high-throughput streams better than line charts do.
+     *   • "low"    — < 1 event/sec, line/area charts read well
+     *   • "medium" — ~1-100 events/sec
+     *   • "high"   — > 100 events/sec, prefer aggregating visualizations
+     */
+    throughput?: "low" | "medium" | "high";
+    /**
+     * Hint about how long events are kept in view.
+     *   • "windowed"   — only recent events visible (default)
+     *   • "cumulative" — all events accumulate
+     */
+    retention?: "windowed" | "cumulative";
+}
+/**
+ * Stream capability descriptor — parallel to ChartCapability but operates on
+ * a schema. No `fits(profile)`; instead `fits(schema)` returns null/reason.
+ */
+export interface StreamChartCapability {
+    component: string;
+    importPath: "semiotic/realtime";
+    rubric: ChartRubric;
+    fits: (schema: StreamSchema) => null | string;
+    intentScores: Partial<Record<IntentId, StreamIntentScorer>>;
+    caveats?: (schema: StreamSchema) => ReadonlyArray<string>;
+    buildProps: (schema: StreamSchema) => Record<string, unknown>;
+}
+export type StreamIntentScorer = number | ((schema: StreamSchema) => number);
+export interface StreamSuggestion {
+    component: string;
+    family: "realtime";
+    importPath: "semiotic/realtime";
+    score: number;
+    intentScores: Partial<Record<IntentId, number>>;
+    rubric: ChartRubric;
+    reasons: ReadonlyArray<string>;
+    caveats: ReadonlyArray<string>;
+    /** Props ready to spread into the matching realtime chart. */
+    props: Record<string, unknown>;
+}