semiotic 3.7.4 → 3.8.0

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

@@ -2,6 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 import type { ChartCapability, ChartFamily } from "./chartCapabilityTypes";
 import type { IntentId } from "./intents";
 import type { AudienceProfile } from "./audienceProfile";
+import type { ChartRecipe } from "./chartRecipes";
 /**
  * describeChart — generate a layered natural-language description of a chart
  * from its `(component, props)` config, following Lundgard & Satyanarayan's
@@ -66,6 +67,8 @@ export interface DescribeChartResult {
      * an AI- or watcher-authored note is qualified as such.
      */
     annotations?: string;
+    /** Optional recipe risks/misuse guidance, included only when requested. */
+    caveats?: string[];
 }
 export interface DescribeChartOptions {
     /**
@@ -90,6 +93,10 @@ export interface DescribeChartOptions {
      * an unfamiliar reader leans on the description.
      */
     audience?: AudienceProfile;
+    /** Explicit recipe; otherwise `props.recipe`, `props.recipeId`, then registry are checked. */
+    recipe?: ChartRecipe;
+    /** Include declared recipe risks/caveats in the structured result. */
+    includeCaveats?: boolean;
 }
 /** The communicative act a built-in intent implies, or undefined if unknown. */
 export declare function communicativeActForIntent(intent: IntentId): CommunicativeAct | undefined;
@@ -99,6 +106,8 @@ export declare function communicativeActForIntent(intent: IntentId): Communicati
  * family classification. Returns undefined only when nothing identifies it.
  */
 export declare function resolveCommunicativeAct(component: string, context: ChartCapability | DescribeCapabilityContext | undefined): CommunicativeAct | undefined;
+/** True when props carry a provenanced, system/agent-generated alert annotation. */
+export declare function hasGeneratedAlertAnnotation(props: Datum): boolean;
 /** 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;

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

@@ -0,0 +1,16 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { AudienceProfile } from "./audienceProfile";
+import type { ChartRecipe } from "./chartRecipes";
+import type { DescribeChartResult, DescribeLevel } from "./describeChart";
+export interface DescribeRecipeChartOptions {
+    levels?: DescribeLevel[];
+    locale?: string;
+    audience?: AudienceProfile;
+    includeCaveats?: boolean;
+}
+/**
+ * Generate a recipe-specific layered description. A registered implementation
+ * may supply bespoke prose; otherwise declared roles/encodings/intents produce
+ * an honest portable fallback.
+ */
+export declare function describeRecipeChart(recipe: ChartRecipe, props: Datum, options?: DescribeRecipeChartOptions): DescribeChartResult;

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

@@ -0,0 +1,170 @@
+/**
+ * Generative-UI trust layer.
+ *
+ * "Generation is cheap; trust is scarce." An LLM can emit chart code in a
+ * sentence — but hand-written JSX breaks on first paint, and a plausible-looking
+ * chart for the wrong data misleads exactly the reader who can't tell. This
+ * module is the trust layer an AI framework wraps around chart generation: it
+ * turns an LLM's *proposal* (a component name + props) into a result that is
+ * either validated and diagnosed (and, when a renderer is injected, proven to
+ * paint) or accompanied by structured reasons and ranked alternatives to retry
+ * with — never an unchecked chart.
+ *
+ * It composes the already-shipped surface into the documented loop —
+ * **generate → validate → diagnose → repair → render+prove** — and rides
+ * `ChartConfig`, the gate-defended public artifact. It is framework-agnostic by
+ * construction: no Vercel/LangChain/OpenAI/Anthropic SDK enters the library
+ * (the tool-definition shapers below are pure object transforms over JSON
+ * Schema). The one heavy step — rendering to SVG with render evidence — is
+ * *dependency-injected* (`RenderFn`), so this module stays free of server deps
+ * and usable in a browser, an edge runtime, or a notebook.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartConfig } from "../export/chartConfig";
+import type { ValidationResult } from "../charts/shared/validateProps";
+import type { Diagnosis } from "../charts/shared/diagnoseConfig";
+import type { RepairResult } from "./repairChartConfig";
+import type { IntentId } from "./intents";
+import type { RenderEvidence } from "../server/renderEvidence";
+/**
+ * A renderer that turns a validated config into SVG + render evidence. Inject
+ * `renderChartWithEvidence` from `semiotic/server` in Node/SSR; omit it in the
+ * browser (the helper still validates, diagnoses, repairs, and emits JSX).
+ */
+export type RenderFn = (component: string, props: Datum) => {
+    svg: string;
+    evidence: RenderEvidence;
+};
+export interface PrepareChartInput {
+    /** Chart component name the model proposed (e.g. "LineChart"). */
+    component: string;
+    /** Props the model proposed. */
+    props?: Datum;
+}
+export interface PrepareChartOptions {
+    /**
+     * The dataset, used to route a repair when the proposed chart is unknown or a
+     * poor fit. When present, `repair` runs by default.
+     */
+    data?: ReadonlyArray<Datum>;
+    /** Ranking intent passed to repair's alternative search. */
+    intent?: IntentId | IntentId[];
+    /** Run `diagnoseConfig` anti-pattern checks (default true). */
+    diagnose?: boolean;
+    /**
+     * Run repair routing (fit check + ranked alternatives). Default: true when
+     * `data` is provided, false otherwise (repair needs the data to profile).
+     */
+    repair?: boolean;
+    /**
+     * Inject a renderer to prove the config paints (and to read render evidence —
+     * the first-try oracle). When omitted, the result has no `svg`/`evidence`,
+     * and `ok` is decided on validation + diagnostics alone.
+     */
+    render?: RenderFn;
+    /**
+     * Treat error-severity diagnostics as blocking `ok` (default true). Set false
+     * to let a caller surface warnings without failing the gate.
+     */
+    treatErrorsAsBlocking?: boolean;
+}
+export interface PrepareChartResult {
+    /**
+     * True only when the proposal is trustworthy: it validates, carries no
+     * error-severity diagnostics, and — if a renderer was injected — produced a
+     * non-empty scene. A `false` result is the signal to retry with `reasons` and
+     * `repair.alternatives`, never to paint.
+     */
+    ok: boolean;
+    component: string;
+    props: Datum;
+    /** The serializable, validated config — present whenever the component is known. */
+    config?: ChartConfig;
+    /** JSX string for the validated config (only when a config could be built). */
+    jsx?: string;
+    /** Structural validation: required props, types, enums, accessor/data shape. */
+    validation: ValidationResult;
+    /** Anti-pattern diagnostics (empty data, misleading design, contrast, …). */
+    diagnostics: Diagnosis[];
+    /** Fit verdict + ranked alternatives, when repair ran. */
+    repair?: RepairResult;
+    /** Render evidence (mark count, domains, ariaLabel, …) when a renderer ran. */
+    evidence?: RenderEvidence;
+    /** Rendered SVG when a renderer ran. */
+    svg?: string;
+    /** Human-readable reasons the proposal is not `ok` (empty when `ok`). */
+    reasons: string[];
+}
+/**
+ * Run an LLM chart proposal through the trust loop. Pure except for any side
+ * effects of an injected `render` function.
+ */
+export declare function prepareChart(input: PrepareChartInput, options?: PrepareChartOptions): PrepareChartResult;
+/**
+ * A tool definition expressed as JSON Schema — the common denominator every
+ * agent framework accepts. Mirrors the MCP `renderChart` contract so an
+ * in-process tool and the MCP server speak the same shape.
+ */
+export interface ChartToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool input. */
+    inputSchema: Record<string, unknown>;
+}
+export interface ChartToolOptions {
+    /** Override the tool name (default "render_semiotic_chart"). */
+    name?: string;
+    /** Restrict the component enum to this allow-list (default: the whole registry). */
+    components?: ReadonlyArray<string>;
+}
+/**
+ * Build a framework-agnostic tool definition for generating a Semiotic chart.
+ * Pass it (or a shaper's output) to your agent framework, and pair it with
+ * {@link createChartToolHandler} for the execute step.
+ */
+export declare function chartGenerationTool(options?: ChartToolOptions): ChartToolDefinition;
+/** Shape a tool definition for the Anthropic Messages API `tools` array. */
+export declare function toAnthropicTool(def: ChartToolDefinition): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+};
+/** Shape a tool definition for the OpenAI Chat Completions `tools` array. */
+export declare function toOpenAITool(def: ChartToolDefinition): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+};
+/** A flat function-tool shape for the OpenAI Responses API. */
+export interface OpenAIResponsesTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    strict: boolean;
+}
+export interface OpenAIResponsesToolOptions {
+    /**
+     * Enable OpenAI strict mode. The definition must use closed objects and
+     * declare every property as required (nullable properties are supported).
+     * The generic chart tool intentionally leaves `props` open, so use a
+     * component-specific definition before setting this to true.
+     */
+    strict?: boolean;
+}
+/**
+ * Shape a tool definition for the OpenAI Responses API `tools` array.
+ *
+ * This is deliberately separate from {@link toOpenAITool}: Chat Completions
+ * nests the function under `function`, whereas Responses uses a flat object.
+ */
+export declare function toOpenAIResponsesTool(def: ChartToolDefinition, options?: OpenAIResponsesToolOptions): OpenAIResponsesTool;
+/**
+ * Build the execute handler for the chart tool: it runs {@link prepareChart} on
+ * the tool input and returns the trust-loop result. Inject a `render` fn (from
+ * `semiotic/server`) and/or the `data` for fit checking via `optionsFor`.
+ */
+export declare function createChartToolHandler(optionsFor?: (input: PrepareChartInput) => PrepareChartOptions): (input: PrepareChartInput) => PrepareChartResult;

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

@@ -0,0 +1,62 @@
+import type { ChartRecipe } from "./chartRecipes";
+export interface IntentManifest {
+    ididVersion: string;
+    chartId: string;
+    title?: string;
+    author?: string;
+    createdAt?: string;
+    intent: {
+        primary: string;
+        secondary?: string[];
+        communicativeAct?: string;
+    };
+    audience?: {
+        primary?: string;
+        familiarityAssumptions?: Record<string, string>;
+        literacyTargets?: {
+            feature: string;
+            rationale: string;
+        }[];
+    };
+    reception?: {
+        channels: string[];
+        strengths?: string[];
+        risks?: string[];
+        scaffolds?: string[];
+        memorableForm?: boolean;
+    };
+    designContract?: {
+        chartFamily?: string;
+        whyThisForm?: string;
+        whyNotDefault?: string;
+        risks?: string[];
+        misuse?: string[];
+    };
+    accessibility?: {
+        description?: string;
+        navigation?: boolean;
+        dataFallback?: boolean;
+        manualChecks?: string[];
+    };
+    provenance?: {
+        dataSources?: string[];
+        code?: string;
+        reviewStatus?: string;
+        generatedBy?: string;
+    };
+    lifecycle?: {
+        staleAfter?: string;
+        refreshPolicy?: string;
+        annotationStatus?: string;
+    };
+}
+export declare function summarizeIntentManifest(manifest: IntentManifest): string;
+export interface IntentManifestFromRecipeOptions {
+    chartId: string;
+    title?: string;
+    description?: string;
+    dataSources?: string[];
+    reviewStatus?: string;
+}
+/** Project a chart recipe into the cross-chart Intent Mark standard. */
+export declare function intentManifestFromRecipe(recipe: ChartRecipe, options: IntentManifestFromRecipeOptions): IntentManifest;

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

@@ -1,4 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe } from "./chartRecipes";
 /**
  * buildNavigationTree — turn a chart config into a structured, labeled
  * navigation tree (chart → axes/series → data points), following the Olli /
@@ -30,6 +31,8 @@ export interface BuildNavigationTreeOptions {
     /** Cap leaves per branch (keeps a 50k-row chart from building a giant tree). Default 200. */
     maxLeaves?: number;
     locale?: string;
+    /** Explicit recipe; otherwise props/registry dispatch is used. */
+    recipe?: ChartRecipe;
 }
 /**
  * Build a structured navigation tree for a chart config. Full trees for XY,

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

@@ -0,0 +1,72 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { NavTreeNode } from "./navigationTree";
+import type { ChartRecipe } from "./chartRecipes";
+export type ObservedAuditStatus = "pass" | "warn" | "fail" | "manual" | "not-applicable";
+export interface ObservedAuditFinding {
+    id: string;
+    category: "geometry" | "identity" | "coverage" | "interaction" | "accessibility" | "visual" | "manual-at";
+    status: ObservedAuditStatus;
+    message: string;
+    evidence?: Record<string, unknown>;
+    remediation?: string;
+}
+export interface DeclaredRecipeSemantics {
+    dataRoles: string[];
+    intents: string[];
+    accessibilityExpectations: string[];
+    fallbackDeclared: boolean;
+    designContractDeclared: boolean;
+}
+export interface AuditObservedSceneInput {
+    recipe: ChartRecipe;
+    /** A getCustomLayout() result, a node array, or a frame-specific scene bundle. */
+    scene: ReadonlyArray<Record<string, unknown>> | {
+        nodes?: ReadonlyArray<Record<string, unknown>>;
+        sceneNodes?: ReadonlyArray<Record<string, unknown>>;
+        sceneEdges?: ReadonlyArray<Record<string, unknown>>;
+    } | null | undefined;
+    inputData: ReadonlyArray<Datum>;
+    annotations?: ReadonlyArray<Datum>;
+    dimensions: {
+        width: number;
+        height: number;
+        plot?: {
+            x?: number;
+            y?: number;
+            width: number;
+            height: number;
+        };
+    };
+    theme?: {
+        background?: string;
+        categorical?: string[];
+    };
+    layoutConfig?: Record<string, unknown>;
+    chart?: {
+        title?: string;
+        summary?: string;
+        description?: string;
+        accessibleTable?: boolean;
+        navigationTree?: NavTreeNode;
+        selectedIds?: ReadonlyArray<string>;
+    };
+}
+export interface ObservedSceneAuditResult {
+    recipeId: string;
+    ok: boolean;
+    summary: {
+        marks: number;
+        passes: number;
+        warnings: number;
+        failures: number;
+        manual: number;
+    };
+    declaredSemantics: DeclaredRecipeSemantics;
+    observedSceneEvidence: ObservedAuditFinding[];
+    manualATChecks: ObservedAuditFinding[];
+}
+/**
+ * Audit what a custom layout actually emitted. The report deliberately keeps
+ * declared meaning, observed evidence, and manual AT/reception checks separate.
+ */
+export declare function auditObservedScene(input: AuditObservedSceneInput): ObservedSceneAuditResult;

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

@@ -40,6 +40,12 @@ export interface ChartReaderGroundingOptions {
     maxLeaves?: number;
     /** Skip the navigation structure (e.g. to save tokens). Default false. */
     includeStructure?: boolean;
+    /**
+     * Include physics runtime grounding for StreamPhysicsFrame/physics HOCs.
+     * Default: auto-detect from physics chart props. Pass false to omit, true to
+     * force extraction from props, or an object to supply snapshot/evidence rows.
+     */
+    physics?: boolean | PhysicsReaderGroundingInput;
 }
 export interface ChartReaderGroundingIntent {
     /** The communicative act the chart performs. */
@@ -51,6 +57,81 @@ export interface ChartReaderGroundingIntent {
     /** Resolved per-intent scores, when the caller passed them (not from a raw descriptor). */
     intentScores?: Partial<Record<IntentId, number>>;
 }
+export interface PhysicsReaderGroundingAggregate {
+    id?: string;
+    label: string;
+    count: number;
+    secondary?: number;
+    secondaryLabel?: string;
+    observed?: number;
+}
+export interface PhysicsReaderGroundingAggregates {
+    rows: PhysicsReaderGroundingAggregate[];
+    totalCount: number;
+    populatedCount: number;
+    leader?: PhysicsReaderGroundingAggregate;
+}
+export interface PhysicsReaderGroundingSimulation {
+    state?: string;
+    settled?: boolean;
+    elapsedSeconds?: number;
+    paused?: boolean;
+    visible?: boolean;
+    seed?: number;
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    fixedDt?: number;
+    timeScale?: number;
+    maxSubsteps?: number;
+    liveBodies?: number;
+    sleepingBodies?: number;
+    queued?: number;
+    bodyLimit?: number;
+    eviction?: string;
+}
+export interface PhysicsReaderGroundingGeometry {
+    colliders?: number;
+    sensors?: number;
+    springs?: number;
+    activeSensorPairs?: number;
+}
+export interface PhysicsReaderGroundingSediment {
+    bins: number;
+    count: number;
+    total?: number;
+    leader?: {
+        id?: string;
+        label: string;
+        count: number;
+        total?: number;
+    };
+}
+export interface PhysicsReaderGroundingInput {
+    /** PhysicsPipelineSnapshot or a structurally equivalent object. */
+    snapshot?: unknown;
+    /** PhysicsSettledEvidence or a structurally equivalent object. */
+    evidence?: unknown;
+    /** PhysicsPipelineConfig or equivalent runtime config. */
+    config?: unknown;
+    /** Settled projection rows / evidence bin counts. */
+    projectionRows?: readonly unknown[];
+    /** Alias for projectionRows when callers already name the rows aggregates. */
+    aggregates?: readonly unknown[];
+    /** Physics sediment bin snapshots. */
+    sediment?: readonly unknown[];
+    /** Precomputed sediment totals, if available. */
+    sedimentTotals?: unknown;
+}
+export interface PhysicsReaderGrounding {
+    simulation: PhysicsReaderGroundingSimulation;
+    geometry?: PhysicsReaderGroundingGeometry;
+    aggregates?: PhysicsReaderGroundingAggregates;
+    sediment?: PhysicsReaderGroundingSediment;
+    /** Compact prose appended to `ChartReaderGrounding.text`. */
+    text: string;
+}
 export interface ChartReaderGrounding {
     component: string;
     /** Layered L1–L3 description ({ text, levels }). */
@@ -59,6 +140,8 @@ export interface ChartReaderGrounding {
     intent?: ChartReaderGroundingIntent;
     /** Structured navigation tree (chart → axes/series → datum). Omitted when `includeStructure: false`. */
     structure?: NavTreeNode;
+    /** Physics-specific runtime grounding for simulation charts. */
+    physics?: PhysicsReaderGrounding;
     /** L1–L4 joined into one prose blob an LLM can read directly. */
     text: string;
 }

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

@@ -0,0 +1,8 @@
+import type { ChartCapability, ChartDataProfile } from "./chartCapabilityTypes";
+import type { ChartRecipe, DataRoleDefinition } from "./chartRecipes";
+export declare function resolveRecipeRoleField(recipe: ChartRecipe, role: DataRoleDefinition, profile: ChartDataProfile): string | undefined;
+/**
+ * Adapt a declarative recipe into the existing capability engine. Raw custom
+ * frame HOCs remain excluded; named recipes participate as distinct candidates.
+ */
+export declare function recipeToChartCapability(recipe: ChartRecipe): ChartCapability;

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

@@ -0,0 +1,13 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe } from "./chartRecipes";
+import type { NavTreeNode } from "./navigationTree";
+export interface RecipeNavigationOptions {
+    maxLeaves?: number;
+    locale?: string;
+}
+/**
+ * Build navigation from a recipe strategy, or from its declared data roles
+ * when no strategy exists. The fallback always produces data leaves rather
+ * than collapsing an unfamiliar custom chart to a root-only node.
+ */
+export declare function buildRecipeNavigationTree(recipe: ChartRecipe, props: Datum, options?: RecipeNavigationOptions): NavTreeNode;

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

@@ -0,0 +1,11 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartRecipe, DataRoleDefinition, IntentDefinition } from "./chartRecipes";
+export declare function recipeIntentId(intent: IntentDefinition): string | undefined;
+export declare function recipeConfig(props: Datum): Record<string, unknown>;
+export declare function recipeData(props: Datum): Datum[];
+export declare function resolveRecipeForChart(component: string, props: Datum, explicit?: ChartRecipe): ChartRecipe | undefined;
+export declare function fieldForRole(role: DataRoleDefinition, config: Record<string, unknown>, data?: ReadonlyArray<Datum>): string | undefined;
+export declare function roleByName(recipe: ChartRecipe, name: string): DataRoleDefinition | undefined;
+export declare function firstRole(recipe: ChartRecipe, semanticTypes: DataRoleDefinition["semanticType"][]): DataRoleDefinition | undefined;
+export declare function roleValue(datum: Datum, role: DataRoleDefinition | undefined, config: Record<string, unknown>, data: ReadonlyArray<Datum>): unknown;
+export declare function fillRecipeTemplate(template: string, datum: Datum | undefined, recipe: ChartRecipe, config: Record<string, unknown>, data: ReadonlyArray<Datum>, extra?: Record<string, string | number>): string;

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

@@ -1,6 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
 import type { IntentId } from "./intents";
+import type { ObservedSceneAuditResult } from "./observedSceneAudit";
 /**
  * Repair result when the chosen chart fits the data — nothing to fix.
  */
@@ -9,6 +10,8 @@ export interface RepairOkResult {
     component: string;
     /** The same data profile that was evaluated. */
     profile: ChartDataProfile;
+    /** Recipe-specific reception/accessibility repairs, even when data shape fits. */
+    repairs?: string[];
 }
 /**
  * Repair result when the chosen chart doesn't fit. Carries the diagnostic
@@ -24,6 +27,7 @@ export interface RepairAlternativeResult {
     /** Whether the caller intended one of the alternatives anyway. */
     alternatives: Suggestion[];
     profile: ChartDataProfile;
+    repairs?: string[];
 }
 /**
  * Repair result when no capability is registered for the asked component.
@@ -34,6 +38,7 @@ export interface RepairUnknownResult {
     /** Closest matches by family/intent — best effort. */
     alternatives: Suggestion[];
     profile: ChartDataProfile;
+    repairs?: string[];
 }
 export type RepairResult = RepairOkResult | RepairAlternativeResult | RepairUnknownResult;
 export interface RepairOptions {
@@ -45,6 +50,10 @@ export interface RepairOptions {
     maxAlternatives?: number;
     /** Pre-computed profile, avoids recomputation. */
     profile?: ChartDataProfile;
+    /** Current rendered props, used for recipe-specific repair guidance. */
+    props?: Datum;
+    /** Optional observed-scene evidence from auditObservedScene(). */
+    observedSceneAudit?: ObservedSceneAuditResult;
 }
 /**
  * Validate that a chart component is a sensible choice for a dataset, and

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

@@ -2,7 +2,7 @@ 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 AudienceProfile, type ReceptionModality } 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. */
@@ -39,6 +39,12 @@ export interface SuggestChartsOptions extends ProfileDataOptions {
      * `dataScaleProfile.ts`.
      */
     quality?: DataQualityProfile;
+    /** Restrict recipe candidates by portability tier. Built-ins are unaffected. */
+    portability?: "portable" | "local";
+    /** Controls how strongly declared recipe reception risks affect ranking. */
+    riskTolerance?: "low" | "medium" | "high";
+    /** Explicit reception channel when no full AudienceProfile is available. */
+    receptionChannel?: ReceptionModality;
 }
 /**
  * Suggest charts for a dataset, ranked by intent suitability.
@@ -85,6 +91,10 @@ export declare function scoreChart(component: string, data: ReadonlyArray<Datum>
     intent?: IntentId | IntentId[];
     variantKey?: string;
     profile?: ChartDataProfile;
+    audience?: AudienceProfile;
+    portability?: "portable" | "local";
+    riskTolerance?: "low" | "medium" | "high";
+    receptionChannel?: ReceptionModality;
 }): Suggestion | {
     reason: string;
 };

package/dist/components/charts/custom/GeoCustomChart.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+import type { ProjectionProp, StreamGeoFrameProps } from "../../stream/geoTypes";
+import type { GeoCustomLayout } from "../../stream/geoCustomLayout";
+import type { ChartRecipe } from "../../ai/chartRecipes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+export interface GeoCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
+    /** Geographic point data supplied to `GeoLayoutContext.points`. */
+    points?: TDatum[];
+    /** Geographic areas supplied to `GeoLayoutContext.areas`. */
+    areas?: GeoJSON.Feature[];
+    /** Geographic line/flow records supplied to `GeoLayoutContext.lines`. */
+    lines?: TDatum[];
+    /** Layout function that emits GeoFrame scene nodes and optional overlays. */
+    layout: GeoCustomLayout<TConfig>;
+    /** User configuration threaded to `GeoLayoutContext.config`. */
+    layoutConfig?: TConfig;
+    /** Receives a structured diagnostic if the layout throws. */
+    onLayoutError?: StreamGeoFrameProps["onLayoutError"];
+    recipe?: ChartRecipe<TDatum, TConfig>;
+    recipeId?: string;
+    /** Projection resolved before the custom layout runs. @default "equirectangular" */
+    projection?: ProjectionProp;
+    xAccessor?: StreamGeoFrameProps<TDatum>["xAccessor"];
+    yAccessor?: StreamGeoFrameProps<TDatum>["yAccessor"];
+    lineDataAccessor?: StreamGeoFrameProps<TDatum>["lineDataAccessor"];
+    /** Field or function that declares the semantic category used for custom-layout color. */
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[] | Record<string, string>;
+    enableHover?: boolean;
+    tooltip?: TooltipProp;
+    annotations?: Datum[];
+    /** Additional StreamGeoFrame props excluding fields controlled by this HOC. */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "points" | "lines" | "projection" | "size" | "customLayout" | "layoutConfig" | "layoutSelection" | "xAccessor" | "yAccessor" | "lineDataAccessor">>;
+}
+/**
+ * GeoCustomChart — escape hatch for bespoke geographic geometry.
+ *
+ * The frame resolves the projection and continues to own canvas rendering,
+ * polygon/point/line hit-testing, accessibility, tooltips, selection, and SSR.
+ * The supplied layout owns only the scene geometry and SVG overlays.
+ */
+export declare const GeoCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: GeoCustomChartProps<TDatum, TConfig> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};