semiotic 3.6.0 → 3.7.1

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

@@ -30,6 +30,8 @@ export interface PerCapabilityScore {
     rejectedOn: number;
     /** Number of fixtures where this capability appeared in the top-3 ranked suggestions. */
     inTopThreeOn: number;
+    /** Number of fixtures where this capability was the #1 ranked suggestion. */
+    topPickOn: 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. */
@@ -58,6 +60,10 @@ export interface PerFixtureScore {
     rejectedCount: number;
     /** True if the top-3 ranking contained at least one expected component (when expected is provided). */
     expertAgreement: boolean | null;
+    /** True if the #1 ranked suggestion was an expected component — the strict
+     *  form of agreement. Reported alongside the lenient top-3 form so the
+     *  scorecard can't flatter itself with close-second behavior. */
+    topPickAgreement: boolean | null;
     /** Did the engine honor `expectsNoFit`? */
     noFitHonored: boolean | null;
 }
@@ -69,6 +75,11 @@ export interface ScorecardReport {
         capabilityCount: number;
         /** Fraction of expectation-bearing fixtures where the engine agreed with the expert. */
         expertAgreementRate: number;
+        /** Strict agreement: fraction of expectation-bearing fixtures where the
+         *  engine's #1 pick was an expert pick. Always reported next to the
+         *  lenient top-3 rate — the gap between the two is the honest measure of
+         *  how often the engine is merely "not completely wrong." */
+        top1AgreementRate: number;
         /** Average caveat coverage across all suggestions. */
         overallCaveatCoverage: number;
         /** Average variant utilization across all suggestions. */

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

@@ -1,8 +1,9 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import { type ProfileDataOptions } from "./profileData";
-import type { ChartCapability, ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
+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[];
@@ -25,6 +26,19 @@ export interface SuggestChartsOptions extends ProfileDataOptions {
      * 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.
@@ -74,3 +88,22 @@ export declare function scoreChart(component: string, data: ReadonlyArray<Datum>
 }): 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;