semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,278 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { CustomLayout } from "../stream/customLayout";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { NavTreeNode } from "./navigationTree";
+import type { IntentId } from "./intents";
+import type { VisualizationControlDefinition } from "../controls/controlContract";
+/**
+ * A frame identifies the rendering/runtime substrate a recipe expects. It does
+ * not identify the recipe's analytical meaning — that lives in dataRoles,
+ * encodings, intents, and designContract.
+ */
+export type ChartRecipeFrameFamily = "XYFrame" | "OrdinalFrame" | "NetworkFrame" | "GeoFrame" | "XYCustomChart" | "NetworkCustomChart" | "OrdinalCustomChart" | "GeoCustomChart" | "Other";
+export type ChartRecipePortability = "portable" | "local";
+/**
+ * JSON-schema-compatible metadata for serializable recipe configuration.
+ * Kept structurally open in v0 so callers can use JSON Schema, Zod-emitted
+ * schema, or another serializable schema vocabulary without an adapter.
+ */
+export type SerializableSchema = Record<string, unknown>;
+interface RecipeDatumMarker<TDatum> {
+    /** Type-only marker; never required on a runtime layout function. */
+    readonly __chartRecipeDatumType?: TDatum;
+}
+/**
+ * Any of Semiotic's four custom-layout contracts. The datum marker preserves a
+ * recipe author's datum generic without changing the established layout APIs.
+ */
+export type CustomLayoutFunction<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (CustomLayout<TConfig> | OrdinalCustomLayout<TConfig> | NetworkCustomLayout<TConfig> | GeoCustomLayout<TConfig>) & RecipeDatumMarker<TDatum>;
+/**
+ * Serializable reference used by portable recipes. A host registry resolves
+ * the id to executable layout code; local recipes may carry the function
+ * directly instead.
+ */
+export interface RegisteredRecipeLayout {
+    id: string;
+    importPath?: string;
+    exportName?: string;
+}
+export type DataSemanticType = "nominal" | "ordinal" | "quantitative" | "temporal" | "identifier" | "boolean" | "geographic" | "unknown";
+export interface DataRoleDefinition {
+    /** Open role vocabulary: category/value, node-id, edge-source, longitude, etc. */
+    role: string;
+    /** Concrete/default field used by this recipe/example. May be omitted for computed roles. */
+    field?: string;
+    /** Recipe config key that can bind this role to a different concrete field. */
+    accessor?: string;
+    required?: boolean;
+    semanticType: DataSemanticType;
+    description?: string;
+    /** Which input collection owns the field for multi-table/network/geo recipes. */
+    source?: "data" | "nodes" | "edges" | "areas" | "points" | "lines" | string;
+}
+export type EncodingChannel = "position" | "count" | "color" | "size" | "shape" | "length" | "area" | "angle" | "connection" | "order" | "texture" | "motion" | "label" | string;
+export interface EncodingDefinition {
+    channel: EncodingChannel;
+    /** One role or a relationship among several roles. */
+    role: string | string[];
+    meaning: string;
+    /** Other channels that preserve this meaning when the primary channel fails. */
+    redundantWith?: string[];
+}
+/**
+ * String shorthand keeps v0 manifests approachable. The object form adds the
+ * rationale/strength needed by suggestion and explanation surfaces.
+ */
+export type IntentDefinition = IntentId | {
+    /** Canonical intent id. `name` is accepted as an author-friendly alias. */
+    id?: IntentId;
+    name?: IntentId;
+    strength?: "primary" | "secondary" | "supporting";
+    score?: number;
+    rationale?: string;
+};
+export interface AudienceFitDefinition {
+    audience: string;
+    fit: "strong" | "moderate" | "weak" | "avoid";
+    rationale?: string;
+}
+export interface LiteracyTargetDefinition {
+    concept: string;
+    rationale: string;
+}
+/**
+ * Example-local audience vocabulary. This mirrors the seed manifests used in
+ * the docs while audienceFit supports a compact list for ranking systems.
+ */
+export interface RecipeAudienceDefinition {
+    primary?: string;
+    familiarity?: Record<string, string | number>;
+    literacyTargets?: LiteracyTargetDefinition[];
+}
+export interface ReceptionDefinition {
+    channels: string[];
+    strengths?: string[];
+    risks?: string[];
+    scaffolds?: string[];
+    /** Whether distinct form/memorability is an intentional reception benefit. */
+    memorableForm?: boolean;
+}
+export interface DesignContractDefinition {
+    whyCustom: string;
+    /** Alias used by Intent Mark / portable manifests. */
+    whyThisForm?: string;
+    whyNotDefault?: string;
+    defaultAlternative?: string;
+    tradeoff?: string;
+    caveats?: string[];
+    misuse?: string[];
+}
+export interface RecipeStrategyContext<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    data: ReadonlyArray<TDatum>;
+    config: TConfig;
+    locale?: string;
+}
+export interface RecipeDescription {
+    text: string;
+    levels?: {
+        l1?: string;
+        l2?: string;
+        l3?: string;
+        l4?: string;
+    };
+}
+export type DescriptionStrategy<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (context: RecipeStrategyContext<TDatum, TConfig>) => RecipeDescription;
+export type NavigationStrategy<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (context: RecipeStrategyContext<TDatum, TConfig>) => NavTreeNode;
+/**
+ * JSON-safe navigation contract for portable recipes. Role names resolve
+ * through `dataRoles`; templates use `{field}`, `{role}`, and `{count}` tokens.
+ */
+export interface PortableNavigationStrategy {
+    groupByRole?: string;
+    groupBy?: string[];
+    itemLabelTemplate?: string;
+    summaryTemplate?: string;
+    idRole?: string;
+}
+export interface AccessibilityTableField {
+    role?: string;
+    field?: string;
+    label: string;
+    format?: "number" | "percent" | "date" | string;
+}
+export interface AccessibilityExpectations {
+    keyboardNavigation?: "required" | "recommended" | "not-applicable";
+    accessibleTable?: "required" | "recommended" | "not-applicable";
+    description?: "required" | "recommended" | "not-applicable";
+    /** The semantic unit readers should traverse instead of raw visual primitives. */
+    navigationGranularity?: "datum" | "category" | "group" | "node" | "edge" | "summary" | string;
+    dataBearingSceneNodes?: "required" | "recommended" | "not-applicable";
+    fallbackTable?: boolean;
+    redundantEncodings?: string[];
+    requirements?: string[];
+    /** Fields the scene-backed accessible table must preserve. */
+    tableFields?: AccessibilityTableField[];
+    /** Author-friendly aliases used by portable manifests. */
+    requiresTitle?: boolean;
+    requiresSummary?: boolean;
+    requiresAccessibleTable?: boolean;
+    minimumHitTarget?: number;
+    tableRoles?: string[];
+}
+export interface MobileInteractionDefinition {
+    /** Primary phone interaction, e.g. "tap", "button", "drag", "none". */
+    primary?: string;
+    /** Standard non-hover alternatives available to the reader. */
+    alternatives?: string[];
+    /** How hover detail is recovered on touch devices, e.g. "tap-to-lock". */
+    hoverFallback?: string;
+    /** Comfortable pointer target in CSS pixels. */
+    targetSize?: number;
+}
+export interface MobileLabelDefinition {
+    /** Label strategy at phone width, e.g. "direct", "inline", "external", "legend". */
+    strategy?: string;
+    /** Minimum resolved label font size in CSS pixels. */
+    minFontSize?: number;
+}
+export interface MobileCustomSemanticsDefinition {
+    /** Whether emitted scene nodes retain data semantics for audit/grounding. */
+    dataBearingSceneNodes?: boolean;
+    /** Whether emitted scene nodes use stable ids across renders. */
+    stableIds?: boolean;
+    /** Semantic unit readers should traverse on a phone. */
+    navigationGranularity?: string;
+}
+export interface MobileDesignDefinition {
+    /** Overall mobile design strategy, e.g. "responsive", "small-multiples", "summary-cards". */
+    strategy?: string;
+    /** True when the layout intentionally recomputes for narrow viewports. */
+    responsive?: boolean;
+    /** Alias for responsive, friendlier in portable manifests. */
+    supportsResponsiveLayout?: boolean;
+    /** Widths this recipe/adapter has designed variants for. */
+    breakpoints?: number[];
+    /** Minimum CSS viewport width the authored design supports. */
+    minViewportWidth?: number;
+    /** Mobile mark budget before aggregation/faceting/progressive disclosure. */
+    maxMarks?: number;
+    /** Mobile annotation budget before collapsing notes out of the plot. */
+    maxAnnotations?: number;
+    /** Minimum pointer target the recipe/adapter provides. */
+    minimumHitTarget?: number;
+    /** Whether the mobile view provides a title/summary/card before the visual. */
+    summary?: boolean | string;
+    interaction?: MobileInteractionDefinition;
+    labels?: MobileLabelDefinition;
+    custom?: MobileCustomSemanticsDefinition;
+}
+export interface RecipeAuditExpectations {
+    maxCategories?: number;
+    maxMarks?: number;
+    minimumHitTargetSize?: number;
+    requireStableIds?: boolean;
+    requireDatumCoverage?: boolean;
+    expectedSceneNodeTypes?: string[];
+    checks?: string[];
+}
+export interface RecipeExample<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    data?: ReadonlyArray<TDatum>;
+    config?: TConfig;
+    path?: string;
+}
+export interface RecipePortabilityConfig {
+    schema: SerializableSchema;
+}
+/**
+ * Declarative identity/meaning contract for a custom chart recipe.
+ *
+ * Required v0 fields intentionally stay small. A recipe can participate before
+ * it has a schema, generated description, custom navigation tree, or detailed
+ * audit expectations; those layers can be added without changing its identity.
+ */
+export interface ChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    id: string;
+    name: string;
+    version?: string;
+    frameFamily: ChartRecipeFrameFamily;
+    portability: ChartRecipePortability;
+    layout?: CustomLayoutFunction<TDatum, TConfig> | RegisteredRecipeLayout;
+    layoutConfigSchema?: SerializableSchema;
+    portabilityConfig?: RecipePortabilityConfig;
+    dataRoles: DataRoleDefinition[];
+    encodings?: EncodingDefinition[];
+    intents: IntentDefinition[];
+    audience?: RecipeAudienceDefinition;
+    audienceFit?: AudienceFitDefinition[];
+    reception?: ReceptionDefinition;
+    designContract: DesignContractDefinition;
+    accessibility: AccessibilityExpectations;
+    /** Phone-specific contract consumed by audits, agents, and portable adapters. */
+    mobile?: MobileDesignDefinition;
+    /** Portable controls expose state semantics, never frame-specific handlers. */
+    controls?: ReadonlyArray<VisualizationControlDefinition>;
+    description?: DescriptionStrategy<TDatum, TConfig>;
+    navigation?: NavigationStrategy<TDatum, TConfig> | PortableNavigationStrategy;
+    audit?: RecipeAuditExpectations;
+    caveats?: string[];
+    examples?: RecipeExample<TDatum, TConfig>[];
+}
+/**
+ * Define a chart recipe with full generic inference. Intentionally an identity
+ * function in v0: the value is the shared, inspectable shape rather than hidden
+ * registration or runtime behavior.
+ */
+export declare function defineChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(recipe: ChartRecipe<TDatum, TConfig>): ChartRecipe<TDatum, TConfig>;
+/**
+ * Runtime validation is intentionally limited to contract integrity. It does
+ * not try to validate a recipe's domain-specific layout configuration.
+ */
+export declare function validateChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(recipe: ChartRecipe<TDatum, TConfig>): void;
+export declare function isRegisteredRecipeLayout(layout: unknown): layout is RegisteredRecipeLayout;
+/** True when a value can cross JSON/CLI/MCP boundaries without data loss. */
+export declare function isJsonSafe(value: unknown, seen?: Set<object>): boolean;
+export {};

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

@@ -86,6 +86,108 @@ export interface DataPitfallsBridgeResult {
     diagnosis?: DiagnosisResult;
     accessibility?: AccessibilityAuditResult;
 }
+export type DataPitfallsSeverity = "info" | "warning" | "error" | (string & {});
+export type DataPitfallsInputKind = "text" | "code" | "image" | "document" | "slides" | "chain" | (string & {});
+export interface DataPitfallsFinding {
+    ruleId: string;
+    name: string;
+    domain: string;
+    severity: DataPitfallsSeverity;
+    evidence?: string;
+    remediation?: string;
+    explanation?: string;
+    condition?: string;
+    [key: string]: unknown;
+}
+export interface DataPitfallsReport {
+    kind: DataPitfallsInputKind;
+    findings: DataPitfallsFinding[];
+    [key: string]: unknown;
+}
+export type DataPitfallsNotificationLevel = "info" | "warning" | "error" | "neutral";
+export interface DataPitfallsChartNotification {
+    id?: string;
+    level?: DataPitfallsNotificationLevel;
+    title?: string;
+    message: string;
+    source?: string;
+    dismissible?: boolean;
+}
+export type DataPitfallsNotificationMessage = (finding: DataPitfallsFinding, index: number, report: DataPitfallsReport) => string;
+export interface DataPitfallsNotificationBridgeOptions {
+    /** Cap emitted notifications. `meta.count` keeps the uncapped finding count. */
+    max?: number;
+    /** Prefix for the source tag. Default: "datapitfalls". */
+    sourcePrefix?: string;
+    /** Passed through to ChartContainer notifications when set. */
+    dismissible?: boolean;
+    /** Custom message mapper. Defaults to remediation, explanation, evidence, then condition. */
+    message?: DataPitfallsNotificationMessage;
+}
+export interface DataPitfallsNotificationBridge {
+    notifications: DataPitfallsChartNotification[];
+    meta: {
+        count: number;
+        kind: DataPitfallsInputKind;
+    };
+}
+export type DataPitfallsAnnotationType = "label" | "text";
+export interface DataPitfallsSemioticAnnotation {
+    type: DataPitfallsAnnotationType;
+    title: string;
+    label: string;
+    wrap: number;
+    color: string;
+    className: string;
+    emphasis: "primary" | "secondary";
+    provenance: {
+        author: "datapitfalls";
+        authorKind: "watcher";
+        source: "computed";
+        basis: "llm-inference";
+        stableId: string;
+    };
+    dataPitfall: {
+        ruleId: string;
+        domain: string;
+        severity: DataPitfallsSeverity;
+        evidence: string;
+    };
+    [key: string]: unknown;
+}
+export interface DataPitfallsAnnotationBridgeOptions {
+    /** Override severity colors. Merged over the defaults. */
+    palette?: Partial<Record<string, string>>;
+    /** Cap emitted annotations. `meta.count` keeps the uncapped finding count. */
+    max?: number;
+    /** Text wrap width passed through to Semiotic v3 annotations. Default: 240. */
+    wrap?: number;
+    /** Semiotic v3 annotation type. Default: "label". */
+    type?: DataPitfallsAnnotationType;
+    /**
+     * Optional host-owned anchoring. Return `{ x, y }`, data accessors, or any
+     * other Semiotic annotation fields for findings you can position.
+     */
+    anchorFor?: (finding: DataPitfallsFinding, index: number, report: DataPitfallsReport) => Record<string, unknown> | null | undefined;
+}
+export interface DataPitfallsAnnotationBridge {
+    annotations: DataPitfallsSemioticAnnotation[];
+    meta: {
+        count: number;
+        kind: DataPitfallsInputKind;
+    };
+}
+export declare const DEFAULT_DATA_PITFALLS_ANNOTATION_PALETTE: {
+    readonly info: "#2563eb";
+    readonly warning: "#d97706";
+    readonly error: "#dc2626";
+};
+export declare function dataPitfallsFindingToNotification(finding: DataPitfallsFinding, options?: DataPitfallsNotificationBridgeOptions, index?: number, report?: DataPitfallsReport): DataPitfallsChartNotification;
+export declare function toDataPitfallsNotifications(report: DataPitfallsReport, options?: DataPitfallsNotificationBridgeOptions): DataPitfallsChartNotification[];
+export declare function buildDataPitfallsNotificationBridge(report: DataPitfallsReport, options?: DataPitfallsNotificationBridgeOptions): DataPitfallsNotificationBridge;
+export declare function dataPitfallsFindingToAnnotation(finding: DataPitfallsFinding, options?: DataPitfallsAnnotationBridgeOptions, index?: number, report?: DataPitfallsReport): DataPitfallsSemioticAnnotation;
+export declare function toDataPitfallsAnnotations(report: DataPitfallsReport, options?: DataPitfallsAnnotationBridgeOptions): DataPitfallsSemioticAnnotation[];
+export declare function buildDataPitfallsAnnotationBridge(report: DataPitfallsReport, options?: DataPitfallsAnnotationBridgeOptions): DataPitfallsAnnotationBridge;
 /**
  * Build a Data Pitfalls-compatible chain input from a Semiotic chart config.
  *

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;

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

@@ -6,8 +6,9 @@
  * 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 guaranteed-renderable or accompanied by structured reasons and ranked
- * alternatives to retry with — never a broken chart.
+ * 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
@@ -128,7 +129,7 @@ export declare function toAnthropicTool(def: ChartToolDefinition): {
     description: string;
     input_schema: Record<string, unknown>;
 };
-/** Shape a tool definition for the OpenAI / function-calling `tools` array. */
+/** Shape a tool definition for the OpenAI Chat Completions `tools` array. */
 export declare function toOpenAITool(def: ChartToolDefinition): {
     type: "function";
     function: {
@@ -137,6 +138,30 @@ export declare function toOpenAITool(def: ChartToolDefinition): {
         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

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;