semiotic 3.5.4 → 3.7.0

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/readerGrounding.d.ts

@@ -0,0 +1,70 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type DescribeChartResult, type DescribeLevel, type DescribeCapabilityContext, type CommunicativeAct } from "./describeChart";
+import { type NavTreeNode } from "./navigationTree";
+import type { ChartCapability, ChartFamily } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * buildReaderGrounding — the single payload an AI agent reads to interpret a
+ * chart faithfully, without seeing the pixels. It composes the three reception
+ * artifacts the accessibility layer already builds:
+ *
+ *   • {@link describeChart} L1–L3 — encoding, statistics, and trend.
+ *   • the L4 *communicative act* — what the chart is asking the reader to do
+ *     (the intent metadata that lives in each `*.capability.ts`).
+ *   • {@link buildNavigationTree} — the structured chart → axes/series → datum
+ *     tree the agent (or a screen reader) traverses.
+ *
+ * It's the reader-side complement to the author-side capability descriptor: the
+ * descriptor says how a chart *should* be used; this says how a given chart
+ * instance *reads*. Position it as the documented "render evidence" an LLM
+ * consumes — the non-visual reader and the AI reader are the same consumer.
+ *
+ * Pure and SSR-safe (the capability/audience inputs are type-only).
+ */
+export interface ChartReaderGroundingOptions {
+    /**
+     * Intent context powering the L4 communicative-act sentence — a chart's
+     * capability descriptor or a resolved {@link DescribeCapabilityContext}
+     * (e.g. a `Suggestion`'s `{ family, intentScores }`). Optional: without it
+     * the act is inferred from the component's family, best-effort.
+     */
+    capability?: ChartCapability | DescribeCapabilityContext;
+    /** Audience profile — tunes the L4 sentence for reception (low familiarity → orienting nudge). */
+    audience?: AudienceProfile;
+    /** Locale for number formatting. Default "en". */
+    locale?: string;
+    /** Levels for the prose description. Default ["l1","l2","l3"] (L4 is carried in `intent`). */
+    levels?: DescribeLevel[];
+    /** Cap navigation-tree leaves per branch. Forwarded to buildNavigationTree (default 200). */
+    maxLeaves?: number;
+    /** Skip the navigation structure (e.g. to save tokens). Default false. */
+    includeStructure?: boolean;
+}
+export interface ChartReaderGroundingIntent {
+    /** The communicative act the chart performs. */
+    act: CommunicativeAct;
+    /** The L4 illocutionary sentence ("This is an alerting chart; …"). */
+    sentence: string;
+    /** Chart family, when known from the supplied context. */
+    family?: ChartFamily;
+    /** Resolved per-intent scores, when the caller passed them (not from a raw descriptor). */
+    intentScores?: Partial<Record<IntentId, number>>;
+}
+export interface ChartReaderGrounding {
+    component: string;
+    /** Layered L1–L3 description ({ text, levels }). */
+    description: DescribeChartResult;
+    /** Communicative act + L4 sentence, when an act could be resolved. */
+    intent?: ChartReaderGroundingIntent;
+    /** Structured navigation tree (chart → axes/series → datum). Omitted when `includeStructure: false`. */
+    structure?: NavTreeNode;
+    /** L1–L4 joined into one prose blob an LLM can read directly. */
+    text: string;
+}
+/**
+ * Build the combined reader-grounding payload for a chart config. See the
+ * module docstring; pass a `capability` (or a resolved context) for the most
+ * precise L4 act, an `audience` for reception tuning.
+ */
+export declare function buildReaderGrounding(component: string, props: Datum, options?: ChartReaderGroundingOptions): ChartReaderGrounding;

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>;
+}

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

@@ -0,0 +1,109 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type ProfileDataOptions } from "./profileData";
+import type { ChartCapability, ChartDataProfile, ScaledSuggestionGroups, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import { type AudienceProfile } from "./audienceProfile";
+import { type DataQualityProfile, type DataScaleProfile } from "./dataScaleProfile";
+export interface SuggestChartsOptions extends ProfileDataOptions {
+    /** Ranking intent(s). When omitted, suggestions are ranked by mean intent score. */
+    intent?: IntentId | IntentId[];
+    /** Restrict to these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Maximum suggestions to return (default 10). */
+    maxResults?: number;
+    /** Include variant-level suggestions (default true). */
+    includeVariants?: boolean;
+    /** Filter out suggestions with a composite score below this (default 0 — keep all). */
+    minScore?: number;
+    /** Provide a pre-built profile instead of re-deriving from data. */
+    profile?: ChartDataProfile;
+    /** Override the registry. Defaults to the global capability registry. */
+    capabilities?: ReadonlyArray<ChartCapability>;
+    /**
+     * Audience profile — overrides chart familiarity and applies adoption-target
+     * bias to the ranking. See `audienceProfile.ts`.
+     */
+    audience?: AudienceProfile;
+    /**
+     * Forward-looking declaration of the dataset's scale (row count, cardinality,
+     * field count, growth mode). When provided, the engine biases recommendations
+     * toward charts that work at the declared scale rather than the sample size.
+     * See `dataScaleProfile.ts`.
+     */
+    scale?: DataScaleProfile;
+    /**
+     * Declaration of the dataset's quality (completeness, outliers, type
+     * heterogeneity). Affects caveats and biases score modestly. See
+     * `dataScaleProfile.ts`.
+     */
+    quality?: DataQualityProfile;
+}
+/**
+ * Suggest charts for a dataset, ranked by intent suitability.
+ *
+ * Heuristic-only — does not call an LLM. Designed to be cheap enough to run on every
+ * keystroke in a UI, and to feed structured context to an LLM when one is available.
+ */
+export declare function suggestCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): Suggestion[];
+/**
+ * One rejected capability: a chart whose `fits()` returned a reason.
+ * Surfaced by `explainCapabilityFit` for diagnostic panels and `--doctor` auto-fix.
+ */
+export interface RejectedCapability {
+    component: string;
+    family: ChartCapability["family"];
+    importPath: ChartCapability["importPath"];
+    /** Human-readable reason this chart can't render this profile. */
+    reason: string;
+}
+export interface ExplainCapabilityFitResult {
+    /** Capabilities that fit the profile — full ranked suggestion list. */
+    fitting: Suggestion[];
+    /** Capabilities that did not fit, with their rejection reasons. */
+    rejected: RejectedCapability[];
+    /** The profile that was evaluated against (provided or computed). */
+    profile: ChartDataProfile;
+}
+/**
+ * Like `suggestCharts`, but also returns the capabilities that *didn't* fit
+ * along with their rejection reasons. The single best primitive for:
+ *   • "Why isn't there a pie chart option?" UI surfaces (vizmart V.4)
+ *   • `--doctor` auto-fix loops that need to enumerate alternatives
+ *   • Descriptor authoring — quickly see whose `fits()` is too strict
+ *
+ * Mirrors `suggestCharts` for the fitting side. Rejection enumeration walks
+ * every registered capability whether it fits or not.
+ */
+export declare function explainCapabilityFit(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions): ExplainCapabilityFitResult;
+/**
+ * Score a specific (component, variant) pair against a dataset and (optionally) an intent.
+ * Useful for evaluating a chart a user already chose: "is this a good fit for what they want?"
+ */
+export declare function scoreChart(component: string, data: ReadonlyArray<Datum> | null | undefined, options?: {
+    intent?: IntentId | IntentId[];
+    variantKey?: string;
+    profile?: ChartDataProfile;
+}): Suggestion | {
+    reason: string;
+};
+/**
+ * Return suggestions grouped by scale band. The "graduation of views" surface:
+ * the same data + intent can produce different chart recommendations depending
+ * on the row band you optimize for. Useful for narratives like
+ * "now → at 10× → at 100×" or for picking the right chart for a sample vs the
+ * production dataset.
+ *
+ * Behavior: runs `suggestCharts` five times (once per band — tiny/small/medium/
+ * large/huge), pinning the row band on each pass while keeping all other
+ * options stable. Each band returns its own ranked list. The same chart can
+ * appear in multiple bands when its sweet spot spans them.
+ *
+ * The single `effective` value on the return is computed from the *original*
+ * options (declared scale or measured profile), so callers can detect which
+ * band the user's actual data lives in and highlight that tier.
+ */
+export declare function suggestChartsGrouped(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestChartsOptions & {
+    maxPerBand?: number;
+}): ScaledSuggestionGroups;

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

@@ -0,0 +1,92 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type StretchSuggestion } from "./suggestStretchCharts";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import type { AudienceProfile } from "./audienceProfile";
+/**
+ * One panel in a generated dashboard. Pairs a chart suggestion with the
+ * intent that motivated it — consumers render the suggestion and label it
+ * with the intent so readers know *why* that panel exists.
+ */
+export interface DashboardPanel {
+    /** The intent this panel covers. */
+    intent: IntentId;
+    /** The chart picked for that intent. */
+    suggestion: Suggestion;
+}
+export interface DashboardSuggestion {
+    /** Ordered panels, each covering a distinct intent. */
+    panels: DashboardPanel[];
+    /** Intents the engine actually filled. */
+    intentsCovered: IntentId[];
+    /** Intents the engine couldn't fill from this data. */
+    intentsMissing: IntentId[];
+    /**
+     * Stretch panels — unfamiliar-but-fitting charts the audience could grow
+     * into. Empty when no `audience` is provided or `exposureLevel` is 0.
+     * Render alongside the main panels in a distinct surface so users see
+     * them as opt-in literacy growth, not silent defaults.
+     */
+    stretchPanels: StretchSuggestion[];
+    /** The shape profile (computed once, reused for every panel). */
+    profile: ChartDataProfile;
+}
+export interface SuggestDashboardOptions {
+    /**
+     * Intents to attempt. When omitted, the engine picks a sensible default set
+     * based on the data shape (e.g. if `hasTimeAxis`, include "trend"; if
+     * `categoryCount`, include "rank" and "part-to-whole").
+     */
+    intents?: ReadonlyArray<IntentId>;
+    /** Maximum number of panels. Default 6. */
+    maxPanels?: number;
+    /**
+     * When true (default), prefer not to repeat the same chart family across
+     * panels — produces a more varied dashboard. Set false to allow duplicates.
+     */
+    diversifyByFamily?: boolean;
+    /** Allow only these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Optional pre-built profile (avoids recomputation). */
+    profile?: ChartDataProfile;
+    /** Non-tabular payload — forwarded to profileData. */
+    rawInput?: unknown;
+    /**
+     * Audience profile — applies familiarity overrides and adoption-target bias
+     * to every panel's ranking. When set with `exposureLevel >= 1`, the dashboard
+     * additionally returns `stretchPanels` showing unfamiliar-but-fitting charts.
+     */
+    audience?: AudienceProfile;
+    /** Max stretch panels (default min(maxPanels, 3)). */
+    maxStretchPanels?: number;
+}
+/**
+ * Generate a dashboard: a set of complementary chart panels, each
+ * answering a distinct analytical intent on the same dataset.
+ *
+ * The contract: every panel has a stated `intent` and a suggestion that
+ * fits that intent. The engine diversifies by chart family by default to
+ * avoid "every panel is a bar chart" outcomes. Intents that can't be
+ * filled from the data (e.g. "geo" on row data with no lat/lon) are
+ * reported in `intentsMissing` so consumers can show "no fit for geo
+ * here" rather than silently dropping them.
+ *
+ * Heuristic only — no LLM call. The result is suitable for direct
+ * rendering (each panel's `suggestion.props` is spreadable into the
+ * matching chart) or for piping to an LLM as composition context.
+ *
+ * @example
+ * const { panels } = suggestDashboard(data)
+ * return (
+ *   <Grid>
+ *     {panels.map(({ intent, suggestion }) => (
+ *       <Panel key={intent} title={intent}>
+ *         <DynamicChart component={suggestion.component} props={suggestion.props} />
+ *       </Panel>
+ *     ))}
+ *   </Grid>
+ * )
+ */
+export declare function suggestDashboard(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestDashboardOptions): DashboardSuggestion;

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

@@ -0,0 +1,34 @@
+import type { StreamChartCapability, StreamSchema, StreamSuggestion } from "./streamingTypes";
+import type { IntentId } from "./intents";
+export declare function registerStreamChartCapability(capability: StreamChartCapability): void;
+export declare function unregisterStreamChartCapability(component: string): void;
+export declare function getStreamCapabilities(): ReadonlyArray<StreamChartCapability>;
+export interface SuggestStreamChartsOptions {
+    intent?: IntentId | IntentId[];
+    allow?: ReadonlyArray<string>;
+    deny?: ReadonlyArray<string>;
+    maxResults?: number;
+    minScore?: number;
+    capabilities?: ReadonlyArray<StreamChartCapability>;
+}
+/**
+ * Suggest realtime charts for a schema, ranked by intent.
+ *
+ * Parallel to `suggestCharts` but operates on a `StreamSchema` (fields +
+ * throughput/retention hints) rather than row data. Use for live dashboards,
+ * monitoring views, anywhere events arrive over time rather than as a bounded
+ * table.
+ *
+ * @example
+ * const suggestions = suggestStreamCharts({
+ *   fields: [
+ *     { name: "ts", kind: "date" },
+ *     { name: "latency_ms", kind: "numeric" },
+ *     { name: "endpoint", kind: "categorical" },
+ *   ],
+ *   throughput: "high",
+ *   retention: "windowed",
+ * }, { intent: "trend" })
+ * // → [{ component: "RealtimeHeatmap", ... }, { component: "RealtimeWaterfallChart", ... }]
+ */
+export declare function suggestStreamCharts(schema: StreamSchema, options?: SuggestStreamChartsOptions): StreamSuggestion[];

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

@@ -0,0 +1,60 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import { type AudienceProfile } from "./audienceProfile";
+/**
+ * A "stretch pick" — an unfamiliar-but-fitting chart paired with the
+ * familiar chart it could substitute for. Pairing makes the literacy
+ * suggestion concrete: "instead of BarChart, try BoxPlot here, because…"
+ */
+export interface StretchSuggestion {
+    /** The unfamiliar chart we're suggesting as growth. */
+    suggestion: Suggestion;
+    /**
+     * The familiar chart this stretch could replace for the same intent.
+     * Undefined when the stretch is recommended on its own merits (e.g. a
+     * direct "increase" target with no obvious familiar counterpart).
+     */
+    replacing?: string;
+    /** Human-readable rationale, suitable for verbatim display. */
+    rationale: string;
+    /** Audience familiarity for this chart — the number that made it qualify as a stretch. */
+    familiarity: number;
+}
+export interface SuggestStretchChartsOptions {
+    /** Intent(s) to rank by. When omitted, charts are picked by data fit alone. */
+    intent?: IntentId | IntentId[];
+    /** Required — without an audience profile, the concept of "stretch" doesn't apply. */
+    audience?: AudienceProfile;
+    /** Restrict to these component names. */
+    allow?: ReadonlyArray<string>;
+    /** Exclude these component names. */
+    deny?: ReadonlyArray<string>;
+    /** Max stretch picks to return (default 5). */
+    maxResults?: number;
+    /** Pre-built profile. */
+    profile?: ChartDataProfile;
+    /** Non-tabular payload — forwarded to profileData. */
+    rawInput?: unknown;
+    /**
+     * Only return stretches within this score distance of the top familiar pick
+     * (default 1.5). Tighter values keep the suggestions plausible; wider values
+     * expose more variety.
+     */
+    scoreTolerance?: number;
+}
+/**
+ * Find pairs (familiar, stretch) where the stretch chart fits the data,
+ * has audience familiarity at or below the stretch ceiling, and either:
+ *   • is an `increase` target for this audience, OR
+ *   • scores within `scoreTolerance` of a familiar alternative for the
+ *     same intent.
+ *
+ * Each pair is returned as a StretchSuggestion with `replacing` (the
+ * familiar chart it could substitute for) and a rationale string.
+ *
+ * Heuristic only. Use `audience` with care — without target signals, every
+ * audience-unfamiliar chart becomes a candidate, which can drown the
+ * surface in dubious recommendations.
+ */
+export declare function suggestStretchCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestStretchChartsOptions): StretchSuggestion[];

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

@@ -0,0 +1,22 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type ProfileDataOptions } from "./profileData";
+import { type SuggestChartsOptions } from "./suggestCharts";
+import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+export interface UseChartSuggestionsOptions extends SuggestChartsOptions, ProfileDataOptions {
+}
+export interface UseChartSuggestionsResult {
+    suggestions: ReadonlyArray<Suggestion>;
+    profile: ChartDataProfile;
+}
+/**
+ * Memoized chart suggestion hook.
+ *
+ * Heuristic-only: this hook never calls an LLM. Pair with `useChartInterrogation`
+ * to let an LLM re-rank or narrate the heuristic suggestions.
+ *
+ * @example
+ * const { suggestions } = useChartSuggestions(data, { intent: "trend" })
+ * const top = suggestions[0]
+ * return <DynamicChart component={top.component} props={top.props} />
+ */
+export declare function useChartSuggestions(data: ReadonlyArray<Datum> | null | undefined, options?: UseChartSuggestionsOptions): UseChartSuggestionsResult;