semiotic 3.7.5 → 3.8.1

package/dist/components/charts/shared/auditMobileVisualization.d.ts

@@ -0,0 +1,91 @@
+import type { Datum } from "./datumTypes";
+/**
+ * auditMobileVisualization - static mobile-readiness triage for Semiotic chart
+ * configurations.
+ *
+ * This is deliberately conservative: it does not inspect the DOM, resolved CSS,
+ * measured labels, rendered annotation boxes, or real input behavior. It flags
+ * risks that can be inferred from config/data and routes the rest to manual
+ * mobile review. Treat it like auditAccessibility: useful before render, useful
+ * for agents, not a certification.
+ */
+export type MobileAuditStatus = "pass" | "warn" | "manual" | "not-applicable";
+export type MobileAuditCategory = "layout" | "density" | "interaction" | "annotation" | "semantics";
+export type MobileAuditImpact = "high" | "medium" | "low";
+export interface MobileVisualizationFinding {
+    /** Stable id, e.g. "layout.fixed-desktop-size". */
+    id: string;
+    category: MobileAuditCategory;
+    status: MobileAuditStatus;
+    impact: MobileAuditImpact;
+    message: string;
+    fix?: string;
+}
+export interface MobileVisualizationAuditResult {
+    component: string;
+    viewportWidth: number;
+    /** True when no high-impact warning is present. */
+    ok: boolean;
+    summary: {
+        highRisk: number;
+        warnings: number;
+        manual: number;
+        passes: number;
+    };
+    findings: MobileVisualizationFinding[];
+    reference: string;
+}
+export interface AuditMobileVisualizationOptions {
+    /**
+     * Width to audit against. Defaults to 390px, a common modern phone CSS
+     * viewport width. Run multiple widths in CI for stronger coverage.
+     */
+    viewportWidth?: number;
+    /**
+     * Minimum acceptable pointer target. WCAG 2.2 Target Size (Minimum) is 24px;
+     * 44px is the comfortable phone target used here by default.
+     */
+    targetSize?: number;
+    /**
+     * Whether the chart is wrapped in a container that can provide summary text,
+     * controls, caption, download/copy affordances, or a details panel.
+     */
+    inChartContainer?: boolean;
+}
+export interface MobileVisualizationInteractionContract {
+    primary?: string;
+    alternatives?: string[];
+    hoverFallback?: string;
+    targetSize?: number;
+}
+export interface MobileVisualizationLabelContract {
+    strategy?: string;
+    minFontSize?: number;
+}
+export interface MobileVisualizationCustomContract {
+    dataBearingSceneNodes?: boolean;
+    stableIds?: boolean;
+    navigationGranularity?: string;
+}
+export interface MobileVisualizationContract {
+    strategy?: string;
+    responsive?: boolean;
+    supportsResponsiveLayout?: boolean;
+    breakpoints?: number[];
+    minViewportWidth?: number;
+    maxMarks?: number;
+    maxAnnotations?: number;
+    minimumHitTarget?: number;
+    summary?: boolean | string;
+    interaction?: MobileVisualizationInteractionContract;
+    labels?: MobileVisualizationLabelContract;
+    custom?: MobileVisualizationCustomContract;
+}
+/**
+ * Audit a Semiotic chart config for likely mobile visualization problems.
+ * Pure, SSR-safe, no DOM.
+ */
+export declare function auditMobileVisualization(component: string, props?: Datum, options?: AuditMobileVisualizationOptions): MobileVisualizationAuditResult;
+/** Render a mobile visualization audit result as a plain-text report. */
+export declare function formatMobileVisualizationAudit(result: MobileVisualizationAuditResult): string;
+export declare function mobileVisualizationCaveats(): string[];

package/dist/components/charts/shared/chartDefinitionPilot.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Additive ChartDefinition pilot registry.
+ *
+ * This is deliberately a descriptive, pure layer: it imports chart-spec
+ * metadata but never React components, frame stores, server renderers, or
+ * docs modules. The implementation, server, capability, and example links
+ * are strings so hosts can decide what to load. Existing registries remain
+ * authoritative while this seven-chart slice proves the boundary.
+ */
+import { type ChartCapabilities, type ChartCategory, type ChartPropSpec, type ChartSpec, type PropType } from "./chartSpecs";
+/** Version of the definition shape, independently from the package version. */
+export declare const CHART_DEFINITION_SCHEMA_VERSION: 1;
+/** Version of this intentionally small, additive pilot manifest. */
+export declare const CHART_DEFINITION_PILOT_VERSION: "1.0.0";
+export declare const CHART_DEFINITION_PILOT_IDS: readonly ["LineChart", "BarChart", "ForceDirectedGraph", "FlowMap", "GaltonBoardChart", "RealtimeLineChart", "BigNumber"];
+export type ChartDefinitionPilotId = (typeof CHART_DEFINITION_PILOT_IDS)[number];
+export type WireJsonType = Exclude<PropType, "function">;
+/**
+ * Strictly serializable portion of a runtime prop. Function-only and
+ * `omitFromSchema` props live in `runtimeOnlyProps`; mixed string/function
+ * accessors retain their serializable string form and name their broader
+ * runtime contract in the extension field.
+ */
+export interface ChartDefinitionWireProperty {
+    readonly type: WireJsonType | readonly WireJsonType[];
+    readonly enum?: readonly string[];
+    readonly default?: unknown;
+    readonly description?: string;
+    readonly "x-semiotic-runtime-types"?: readonly PropType[];
+}
+export interface ChartDefinitionWireSchema {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, ChartDefinitionWireProperty>>;
+    readonly required: readonly string[];
+    /** Runtime props deliberately absent from the serializable wire surface. */
+    readonly "x-semiotic-runtime-only-props": readonly string[];
+}
+/** A string reference prevents the definition registry from loading React. */
+export interface LazyImplementationReference {
+    readonly module: string;
+    readonly exportName: string;
+}
+export type ChartDefinitionServerSupport = {
+    readonly mode: "render-chart";
+    readonly chartConfig: string;
+} | {
+    readonly mode: "react-ssr-only";
+    readonly reason: string;
+} | {
+    readonly mode: "unavailable";
+    readonly reason: string;
+};
+/**
+ * References into the current docs surface. They remain links for now: the
+ * future ExampleDefinition registry will become the source of truth for them.
+ */
+export interface ChartDefinitionExampleReference {
+    /** `chart-doc` is an interactive documentation demo pending ExampleDefinition migration. */
+    readonly kind?: "example" | "chart-doc";
+    readonly route: string;
+    readonly source: string;
+}
+/** Explicitly additive lifecycle truth; no pilot chart is deprecated. */
+export interface ChartDefinitionLifecycle {
+    readonly status: "stable" | "experimental" | "deprecated" | "internal";
+    readonly since?: string;
+    readonly deprecation?: {
+        readonly since: string;
+        readonly replacement?: string;
+    };
+}
+/** Public docs page and the component identifier consumed by PropTable. */
+export interface ChartDefinitionPropDocs {
+    readonly componentName: string;
+    readonly route: string;
+    readonly source: string;
+}
+export interface ChartDefinitionMetadata {
+    readonly description: string;
+    /** Reused directly from ChartSpec while the existing capability registry leads. */
+    readonly capabilities: ChartCapabilities;
+    readonly capabilityModule: string;
+    readonly chartSpec: string;
+    readonly aiSchemaName: string;
+    readonly lifecycle: ChartDefinitionLifecycle;
+    readonly propDocs: ChartDefinitionPropDocs;
+    readonly support: {
+        readonly browser: "react";
+        readonly server: ChartDefinitionServerSupport;
+    };
+    readonly examples: readonly ChartDefinitionExampleReference[];
+}
+/**
+ * Minimal RFC-aligned manifest shape for the pilot. `wire` is intentionally
+ * serializable; richer prop metadata and lazy implementation references stay
+ * under `runtime`.
+ */
+export interface ChartDefinition<TChart extends string = string> {
+    readonly schemaVersion: typeof CHART_DEFINITION_SCHEMA_VERSION;
+    readonly chartFamily: ChartCategory;
+    readonly chartKind: TChart;
+    readonly wire: {
+        readonly chart: TChart;
+        readonly version: typeof CHART_DEFINITION_PILOT_VERSION;
+        readonly schema: ChartDefinitionWireSchema;
+    };
+    readonly runtime: {
+        readonly propMetadata: Readonly<Record<string, ChartPropSpec>>;
+        readonly implementation: LazyImplementationReference;
+    };
+    readonly metadata: ChartDefinitionMetadata;
+}
+/**
+ * Build a strict wire schema from the current ChartSpec without duplicating
+ * the public prop declaration. This deliberately differs from the legacy AI
+ * schema generator: a function-only prop is omitted here rather than emitted
+ * as an unconstrained JSON-schema property, because a function cannot cross a
+ * persisted/MCP wire boundary.
+ */
+export declare function createChartDefinitionWireSchema(spec: ChartSpec): ChartDefinitionWireSchema;
+/**
+ * One representative per chart family. No existing consumer reads this yet;
+ * its purpose is to make parity and generation work executable before any
+ * registry is migrated.
+ */
+export declare const CHART_DEFINITION_PILOT: Readonly<{
+    [TChart in ChartDefinitionPilotId]: ChartDefinition<TChart>;
+}>;
+export interface ChartDefinitionArtifact {
+    readonly chart: string;
+    readonly schemaVersion: typeof CHART_DEFINITION_SCHEMA_VERSION;
+    readonly wire: ChartDefinition["wire"];
+    readonly runtime: {
+        readonly implementation: LazyImplementationReference;
+        readonly propNames: readonly string[];
+    };
+    readonly metadata: ChartDefinitionMetadata;
+}
+/**
+ * Pure generation hook for future schema/docs/registry emitters. Its output is
+ * JSON-serializable and intentionally has no component or server imports.
+ */
+export declare function generateChartDefinitionArtifacts(registry?: Readonly<Record<string, ChartDefinition>>): readonly ChartDefinitionArtifact[];
+export declare function getChartDefinition(chart: string): ChartDefinition<ChartDefinitionPilotId> | undefined;

package/dist/components/charts/shared/chartFamilySets.d.ts

@@ -0,0 +1,20 @@
+export declare const HIERARCHY_CHARTS: Set<string>;
+export declare const NETWORK_CHARTS: Set<string>;
+export declare const BAR_AREA_CHARTS: Set<string>;
+export declare const TREND_SERIES_CHARTS: Set<string>;
+export declare const ORDINAL_BAR_CHARTS: Set<string>;
+export declare const CURVE_CHARTS: Set<string>;
+export declare const PIE_CHARTS: Set<string>;
+export declare const PART_TO_WHOLE_ACCESSORS: Record<string, string>;
+export declare const PART_TO_WHOLE_CHARTS: Set<string>;
+export declare const NORMALIZED_STACK_ACCESSORS: Record<string, string>;
+export declare const VALUE_CHARTS: Set<string>;
+export declare const XY_WITH_AXES_CHARTS: Set<string>;
+export declare const PHYSICS_MOTION_CHARTS: Set<string>;
+export declare const CONTINUOUS_MOTION_CHARTS: Set<string>;
+export declare const PHYSICS_SETTLED_CHARTS: Set<string>;
+export declare const PHYSICS_DIAGNOSTIC_CHARTS: Set<string>;
+export declare const REALTIME_CHARTS: Set<string>;
+export declare const DUAL_AXIS_CHARTS: Set<string>;
+export declare const GEO_CHARTS: Set<string>;
+export declare const POINT_TARGET_RADIUS_PROP: Record<string, string>;

package/dist/components/charts/shared/chartSelectionUtils.d.ts

@@ -0,0 +1,4 @@
+import type { Datum } from "./datumTypes";
+export declare function resolveHoverXPosition(interactionDatum: Datum, datum: Datum | null | undefined, xField: string): number | null;
+export declare function observationDatum(interactionDatum: Datum): Datum;
+export declare function hasOwnEnumerableKey(value: object | undefined | null): boolean;

package/dist/components/charts/shared/chartSpecCore.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Single source of truth for per-chart prop specifications.
+ *
+ * Three downstream consumers used to maintain their own per-chart entries:
+ *   - `ai/schema.json`                                    (LLM tool definitions)
+ *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
+ *   - `ai/componentMetadata.cjs`                          (category buckets)
+ *
+ * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * this registry — run `npm run docs:chart-specs:schema` to refresh both after
+ * editing a spec. `componentMetadata.cjs` is still
+ * hand-edited but gated for parity by the registry: `check:chart-specs` (run
+ * via `npm run check:chart-specs`) regenerates each chart's schema/
+ * validation/metadata entries with the pure functions in
+ * `scripts/lib/chart-specs-generators.mjs` and fails the build on any
+ * drift, including unexpected adds or removes that bypass the registry.
+ *
+ * Design notes:
+ *   - Shared prop bags (common, xyAxis, ordinalAxis) live in `PROP_BAGS` and
+ *     are referenced by name in each spec so common surface stays in one place.
+ *   - The runtime PropType set ("string" | "number" | "boolean" | "array" |
+ *     "object" | "function") is broader than JSON Schema's, but the schema
+ *     generator emits whatever types this registry declares — including
+ *     "function" inside type unions (canonical entries like
+ *     `RidgelinePlot.tooltip: ["function", "object"]` and
+ *     `SwimlaneChart.onBrush: "function"` already use this convention; LLMs
+ *     read the union and pick a non-function alternative when they can't
+ *     supply a function value). For props that are purely callbacks or
+ *     escape hatches an LLM cannot meaningfully populate, tag the spec
+ *     with `omitFromSchema: true` to keep it in validationMap but out of
+ *     schema.json. `description` and `default` annotations surface in
+ *     schema.json (and MCP responses) but are dropped from validationMap
+ *     (which only reads `type` and `enum`).
+ */
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type DataShape = "array" | "object" | "network" | "realtime" | "none";
+export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "physics" | "value";
+/**
+ * Capability tags for runtime behavior. Each chart declares which
+ * features it actually supports so docs, AI/MCP tools, and CI gates
+ * can read structured truth instead of inferring it from the source.
+ *
+ * All fields are required so a new chart entry can't omit them
+ * silently — the audit's anti-goal "Do not make registry metadata
+ * aspirational. It should describe real runtime behavior and be
+ * checked." applies here.
+ */
+export interface ChartCapabilities {
+    /**
+     * Render pipeline. `canvas` for Stream-Frame-driven charts that
+     * paint to canvas with SVG overlays for chrome (the common case).
+     * `svg` for charts that are pure SVG (none today, but reserved).
+     * `hybrid` for charts that use both — currently every Stream-Frame
+     * HOC qualifies as hybrid; reserve `canvas` for any future
+     * canvas-only fallback.
+     */
+    renderModes: Array<"canvas" | "svg" | "hybrid">;
+    /** Renders a legend swatch column when `colorBy` (or equivalent)
+     *  resolves to non-empty categories. */
+    supportsLegend: boolean;
+    /** Reads from a `selection` prop and dims/highlights matching
+     *  marks via `wrapStyleWithSelection` or equivalent. */
+    supportsSelection: boolean;
+    /** Produces a hover-driven selection (used by linked crosshair /
+     *  cross-filter patterns) via `linkedHover`. */
+    supportsLinkedHover: boolean;
+    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
+     *  can mutate the data list without re-rendering. Hierarchy
+     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
+     *  pure-synthetic charts (GaugeChart) declare false. */
+    supportsPush: boolean;
+    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
+     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
+     *  charts (none yet) and HOC-SSR exclusions also declare false. */
+    supportsSSR: boolean;
+    /**
+     * How color is consumed by the chart's data marks.
+     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
+     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
+     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
+     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
+     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
+     */
+    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
+    /**
+     * Where the geometry comes from.
+     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
+     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
+     * - `custom`: emitted via the frame's customLayout escape hatch
+     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
+     *   XYCustomChart, OrdinalCustomChart).
+     * - `synthetic`: no layout — the chart constructs its scene from
+     *   the input value(s) directly (GaugeChart computes arc geometry).
+     */
+    layoutMode: "plugin" | "custom" | "synthetic";
+    /**
+     * Free-form tag list for opt-in features that don't fit the
+     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
+     * "streamgraph", "minimap". Used by docs feature tables and
+     * potential capability-driven AI suggestions.
+     */
+    specialFeatures: string[];
+}
+export interface ChartPropSpec {
+    /** Allowed runtime types. May be a single value or a union. */
+    type: PropType | PropType[];
+    /** Allowed enum values for string-typed props. */
+    enum?: readonly string[];
+    /** Default value surfaced in schema.json (and shown in MCP getSchema). */
+    default?: unknown;
+    /** Schema-side description; surfaces in LLM tool definitions. */
+    description?: string;
+    /**
+     * When true, the prop is included in validationMap but omitted from
+     * schema.json. Use for handler/callback props (`onClick`, `tooltip`)
+     * and pass-through escape hatches (`frameProps`) that LLMs shouldn't
+     * be asked to populate.
+     */
+    omitFromSchema?: boolean;
+}
+export interface ChartSpec {
+    /** Component name, must match the React export. */
+    name: string;
+    category: ChartCategory;
+    /** Human-readable description for schema.tools[].function.description. */
+    description: string;
+    /** Statically-required props. Push-mode optionality lives in behaviorContracts. */
+    required: string[];
+    /** Drives validation dispatch (validateArrayData / validateNetworkData / …). */
+    dataShape: DataShape;
+    /** Accessor props validated against the data shape at runtime. */
+    dataAccessors: string[];
+    /**
+     * Shared prop bags this chart composes. Bag props are merged in left-to-right
+     * order; chart-specific `ownProps` win on key collision.
+     */
+    propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
+    /** Chart-specific prop spec, overlaid on top of the composed bags. */
+    ownProps: Record<string, ChartPropSpec>;
+    /**
+     * Capability matrix — declarative facts about runtime behavior.
+     * Drives docs feature tables, capability-aware AI/MCP tools, and
+     * the `check:capabilities` drift gate (which verifies, e.g., that
+     * a chart claiming `supportsSSR: true` has a matching entry in
+     * `serverChartConfigs.ts`).
+     */
+    capabilities: ChartCapabilities;
+}
+export declare const PROP_BAGS: {
+    readonly common: Record<string, ChartPropSpec>;
+    readonly xyAxis: Record<string, ChartPropSpec>;
+    readonly ordinalAxis: Record<string, ChartPropSpec>;
+    readonly realtime: Record<string, ChartPropSpec>;
+    readonly physics: Record<string, ChartPropSpec>;
+};
+export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
+export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
+export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
+export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
+export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+/**
+ * Compose a chart's full prop set (bags + ownProps) in deterministic order.
+ * ownProps wins on key collision so a chart can override a shared default.
+ */
+export declare function composeProps(spec: ChartSpec): Record<string, ChartPropSpec>;

package/dist/components/charts/shared/chartSpecs.d.ts

@@ -1,131 +1,12 @@
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
-export type DataShape = "array" | "object" | "network" | "realtime" | "none";
-export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "value";
 /**
- * Capability tags for runtime behavior. Each chart declares which
- * features it actually supports so docs, AI/MCP tools, and CI gates
- * can read structured truth instead of inferring it from the source.
+ * Single source of truth for per-chart prop specifications.
  *
- * All fields are required so a new chart entry can't omit them
- * silently — the audit's anti-goal "Do not make registry metadata
- * aspirational. It should describe real runtime behavior and be
- * checked." applies here.
+ * Spec entries are split by family (`chartSpecsXY.ts`, etc.); this module
+ * re-exports types/helpers and composes `CHART_SPECS`.
+ *
+ * See `chartSpecCore.ts` for types, prop bags, and `composeProps`.
  */
-export interface ChartCapabilities {
-    /**
-     * Render pipeline. `canvas` for Stream-Frame-driven charts that
-     * paint to canvas with SVG overlays for chrome (the common case).
-     * `svg` for charts that are pure SVG (none today, but reserved).
-     * `hybrid` for charts that use both — currently every Stream-Frame
-     * HOC qualifies as hybrid; reserve `canvas` for any future
-     * canvas-only fallback.
-     */
-    renderModes: Array<"canvas" | "svg" | "hybrid">;
-    /** Renders a legend swatch column when `colorBy` (or equivalent)
-     *  resolves to non-empty categories. */
-    supportsLegend: boolean;
-    /** Reads from a `selection` prop and dims/highlights matching
-     *  marks via `wrapStyleWithSelection` or equivalent. */
-    supportsSelection: boolean;
-    /** Produces a hover-driven selection (used by linked crosshair /
-     *  cross-filter patterns) via `linkedHover`. */
-    supportsLinkedHover: boolean;
-    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
-     *  can mutate the data list without re-rendering. Hierarchy
-     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
-     *  pure-synthetic charts (GaugeChart) declare false. */
-    supportsPush: boolean;
-    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
-     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
-     *  charts (none yet) and HOC-SSR exclusions also declare false. */
-    supportsSSR: boolean;
-    /**
-     * How color is consumed by the chart's data marks.
-     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
-     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
-     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
-     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
-     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
-     */
-    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
-    /**
-     * Where the geometry comes from.
-     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
-     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
-     * - `custom`: emitted via the frame's customLayout escape hatch
-     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
-     *   XYCustomChart, OrdinalCustomChart).
-     * - `synthetic`: no layout — the chart constructs its scene from
-     *   the input value(s) directly (GaugeChart computes arc geometry).
-     */
-    layoutMode: "plugin" | "custom" | "synthetic";
-    /**
-     * Free-form tag list for opt-in features that don't fit the
-     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
-     * "streamgraph", "minimap". Used by docs feature tables and
-     * potential capability-driven AI suggestions.
-     */
-    specialFeatures: string[];
-}
-export interface ChartPropSpec {
-    /** Allowed runtime types. May be a single value or a union. */
-    type: PropType | PropType[];
-    /** Allowed enum values for string-typed props. */
-    enum?: readonly string[];
-    /** Default value surfaced in schema.json (and shown in MCP getSchema). */
-    default?: unknown;
-    /** Schema-side description; surfaces in LLM tool definitions. */
-    description?: string;
-    /**
-     * When true, the prop is included in validationMap but omitted from
-     * schema.json. Use for handler/callback props (`onClick`, `tooltip`)
-     * and pass-through escape hatches (`frameProps`) that LLMs shouldn't
-     * be asked to populate.
-     */
-    omitFromSchema?: boolean;
-}
-export interface ChartSpec {
-    /** Component name, must match the React export. */
-    name: string;
-    category: ChartCategory;
-    /** Human-readable description for schema.tools[].function.description. */
-    description: string;
-    /** Statically-required props. Push-mode optionality lives in behaviorContracts. */
-    required: string[];
-    /** Drives validation dispatch (validateArrayData / validateNetworkData / …). */
-    dataShape: DataShape;
-    /** Accessor props validated against the data shape at runtime. */
-    dataAccessors: string[];
-    /**
-     * Shared prop bags this chart composes. Bag props are merged in left-to-right
-     * order; chart-specific `ownProps` win on key collision.
-     */
-    propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
-    /** Chart-specific prop spec, overlaid on top of the composed bags. */
-    ownProps: Record<string, ChartPropSpec>;
-    /**
-     * Capability matrix — declarative facts about runtime behavior.
-     * Drives docs feature tables, capability-aware AI/MCP tools, and
-     * the `check:capabilities` drift gate (which verifies, e.g., that
-     * a chart claiming `supportsSSR: true` has a matching entry in
-     * `serverChartConfigs.ts`).
-     */
-    capabilities: ChartCapabilities;
-}
-export declare const PROP_BAGS: {
-    readonly common: Record<string, ChartPropSpec>;
-    readonly xyAxis: Record<string, ChartPropSpec>;
-    readonly ordinalAxis: Record<string, ChartPropSpec>;
-    readonly realtime: Record<string, ChartPropSpec>;
-};
-export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
-export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
-export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
-export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
-export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+export type { PropType, DataShape, ChartCategory, ChartCapabilities, ChartPropSpec, ChartSpec, } from "./chartSpecCore";
+export { PROP_BAGS, ORIENTATION_ENUM, HORIZONTAL_VERTICAL_ENUM, LEGEND_POSITION_ENUM, CURVE_ENUM, CHART_MODE_ENUM, composeProps, } from "./chartSpecCore";
+import type { ChartSpec } from "./chartSpecCore";
 export declare const CHART_SPECS: Record<string, ChartSpec>;
-/**
- * Compose a chart's full prop set (bags + ownProps) in deterministic order.
- * ownProps wins on key collision so a chart can override a shared default.
- */
-export declare function composeProps(spec: ChartSpec): Record<string, ChartPropSpec>;

package/dist/components/charts/shared/chartSpecsGeo.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const GEO_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsNetwork.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const NETWORK_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsOrdinal.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const ORDINAL_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsPhysics.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const PHYSICS_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsRealtime.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const REALTIME_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsValue.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const VALUE_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/chartSpecsXY.d.ts

@@ -0,0 +1,2 @@
+import type { ChartSpec } from "./chartSpecCore";
+export declare const XY_CHART_SPECS: Record<string, ChartSpec>;

package/dist/components/charts/shared/colorContrast.d.ts

@@ -0,0 +1,3 @@
+/** WCAG contrast ratio between two hex colors.
+ *  Returns null if either color isn't a parseable hex. */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;

package/dist/components/charts/shared/colorUtils.d.ts

@@ -35,6 +35,21 @@ export declare const DEPTH_PALETTE_COLORS: string[];
  * ```
  */
 export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum) => string), colorScale?: (v: string) => string): string;
+/**
+ * Look up a color for `key` in an explicit `{ category: color }` map.
+ *
+ * Guards against two hazards of a naive `key in map` lookup on a
+ * user-supplied object: inherited prototype keys (e.g. `"toString"`,
+ * `"constructor"`) must NOT register as mapped categories, and a mapped
+ * value that isn't a usable color string (a function, number, `""`) must
+ * not leak into a fill/stroke. Returns `undefined` when the key is unmapped
+ * or its value isn't a non-empty string, so callers apply their own default.
+ *
+ * Single source of truth for object-map `colorScheme` resolution across
+ * `createColorScale`, `resolveDefaultFill`, `buildResolveColor`,
+ * `buildColorScale`, and `CategoryColorProvider`.
+ */
+export declare function resolveExplicitColor(map: Record<string, unknown>, key: string | undefined | null): string | undefined;
 /**
  * Creates a color scale function from data
  *
@@ -49,7 +64,7 @@ export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum)
  * const color = colorScale('A') // Returns color for category 'A'
  * ```
  */
-export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[]): (v: string) => string;
+export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[] | Record<string, string>): (v: string) => string;
 /**
  * Generates a size function based on sizeBy configuration.
  *

package/dist/components/charts/shared/datumTypes.d.ts

@@ -18,3 +18,5 @@
  * reason" referenced by the lint policy for `@typescript-eslint/no-explicit-any`.
  */
 export type Datum = Record<string, any>;
+/** Values that can be returned by a chart accessor or stored in a datum field. */
+export type DatumValue = string | number | boolean | Date | Datum | Datum[] | null | undefined;

package/dist/components/charts/shared/diagnoseAnnotationChecks.d.ts

@@ -0,0 +1,6 @@
+import type { Datum } from "./datumTypes";
+import type { Diagnosis } from "./diagnoseTypes";
+/** Interactive widgets need durable identity for replay and normalized events. */
+export declare function checkInteractiveAnnotationIds(_component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkAnnotationConnectors(_component: string, props: Datum, out: Diagnosis[]): void;
+export declare function checkAnnotationDensity(_component: string, props: Datum, out: Diagnosis[]): void;