semiotic 3.6.0 → 3.7.0

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

@@ -0,0 +1,89 @@
+import { type ConversationArcEvent, type ConversationArcEventInput, type ConversationArcEventType, type EnableConversationArcOptions } from "./conversationArc";
+/**
+ * Talk-friendly summary of an arc. Computed from the current buffer
+ * each time it's read. `summarizeArc` is exported separately for
+ * server-side or batch use.
+ */
+export interface ConversationArcSummary {
+    /** Total events buffered. */
+    total: number;
+    /** Per-type counts. Missing types implicitly zero. */
+    byType: Partial<Record<ConversationArcEventType, number>>;
+    /** Component names referenced across the buffer (deduplicated). */
+    componentsSeen: string[];
+    /** Audience labels referenced across the buffer (most recent last). */
+    audiencesSeen: string[];
+    /** Latest event's `arcId`, if any. */
+    latestArcId?: string;
+    /** Timestamp of the first event (epoch ms), or `null` if empty. */
+    startedAt: number | null;
+    /** Timestamp of the most recent event (epoch ms), or `null` if empty. */
+    lastAt: number | null;
+    /** Wall-clock duration covered by the buffer in ms, or `0` if empty. */
+    durationMs: number;
+}
+/**
+ * Reduce an event array to the talk-friendly `ConversationArcSummary`.
+ *
+ * Pure function — no `Date.now()` calls, no I/O. Safe to use on
+ * the server, in batch jobs, or against a replayed arc fixture.
+ *
+ * Walks the events once, so cost scales with buffer size; the default
+ * 1000-event capacity makes this trivially fast in practice.
+ */
+export declare function summarizeArc(events: ReadonlyArray<ConversationArcEvent>): ConversationArcSummary;
+/**
+ * Options for {@link useConversationArc}. Mirrors the underlying
+ * `enableConversationArc` options, plus a `disableOnUnmount` escape
+ * hatch for consumers that own the entire arc lifecycle.
+ */
+export interface UseConversationArcOptions extends EnableConversationArcOptions {
+    /**
+     * Auto-enable the arc store on mount. Defaults to `true` — the
+     * common case is "I'm rendering the arc inspector / live dashboard,
+     * I want recording on while I'm mounted." Set to `false` if you
+     * want the hook to read but not flip the enable flag.
+     */
+    enableOnMount?: boolean;
+    /**
+     * Auto-disable on unmount. Defaults to `false` — disabling on
+     * unmount would cut off any other consumer that depends on
+     * recording staying live (the audience picker, an inspector panel
+     * in a sibling tree). Set to `true` if you own the whole session.
+     */
+    disableOnUnmount?: boolean;
+}
+/**
+ * Result returned from {@link useConversationArc}.
+ */
+export interface UseConversationArcResult {
+    /** Live event buffer, refreshed on every recorded event. */
+    /** Frozen snapshot of the live event buffer. Read-only; `.slice()` for a mutable copy. */
+    history: ReadonlyArray<ConversationArcEvent>;
+    /** Reduced summary of the current buffer. Recomputed on each event. */
+    summary: ConversationArcSummary;
+    /** `true` while the store is actively recording. */
+    enabled: boolean;
+    /** Current session ID, or `null` before any `enable*` call. */
+    sessionId: string | null;
+    /** Record an event — stable across renders. Returns the stamped event, or `null` if disabled. */
+    record: (input: ConversationArcEventInput) => ConversationArcEvent | null;
+    /** Clear the buffered events without disabling the store. */
+    clear: () => void;
+}
+/**
+ * React hook that participates in the conversation-arc session.
+ *
+ * Subscribes via `useSyncExternalStore` so re-renders are coordinated
+ * with React's concurrent rendering (no tearing between the buffer
+ * snapshot and the rendered tree). Auto-enables the store on mount
+ * by default; the underlying store is module-scoped, so all hook
+ * instances share the same buffer.
+ *
+ * ```tsx
+ * const { history, summary, record } = useConversationArc()
+ * // Later, in a click handler:
+ * record({ type: "chart-exported", component: "LineChart", format: "jsx" })
+ * ```
+ */
+export declare function useConversationArc(options?: UseConversationArcOptions): UseConversationArcResult;

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

@@ -0,0 +1,61 @@
+import type { NavTreeNode } from "./navigationTree";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * useNavigationSync — keep an `AccessibleNavTree` and a chart in sync, both ways:
+ *
+ *   tree → canvas : landing on a datum node highlights the matching mark (via
+ *                   the selection store — pass `selection` to the chart).
+ *   canvas → tree : hovering/clicking a mark moves the tree's active node (via
+ *                   the observation store — give the chart a `chartId`).
+ *
+ * Both directions ride the existing module-global stores, so **no provider is
+ * required** — the chart just needs `chartId` and `selection={sync.selection}`,
+ * and the tree needs `activeId`/`onActiveChange`. Headless: BYO layout.
+ *
+ * @example
+ * const sync = useNavigationSync({ tree, chartId: "sales", matchFields: ["month"] })
+ * <LineChart chartId="sales" selection={sync.selection} {...props} />
+ * <AccessibleNavTree tree={tree} activeId={sync.activeId} onActiveChange={sync.onActiveChange} />
+ */
+export interface UseNavigationSyncOptions {
+    /** The navigation tree (from `buildNavigationTree`). */
+    tree: NavTreeNode;
+    /** `chartId` set on the chart, so its hover/click can be matched back to a leaf. */
+    chartId?: string;
+    /**
+     * Fields that identify a datum for highlighting + matching. Defaults to the
+     * primitive-valued keys of the first leaf's datum.
+     */
+    matchFields?: string[];
+    /** Selection name shared with the chart's `selection={{ name }}`. Default "__semiotic-nav-sync". */
+    selectionName?: string;
+    /** Which canvas observations move the tree. Default ["hover", "click"]. */
+    observe?: Array<"hover" | "click">;
+    /**
+     * The chart's annotations. An annotation anchored to a datum carries that
+     * datum's identifying fields (the same `matchFields` used for hover sync), so
+     * each one resolves to a nav-tree leaf. Lets a non-visual reader *reach* an
+     * anchored point — e.g. an AI's "anchored conversation" note — via
+     * `focusAnnotation`, and lets the tree mark annotated nodes via `annotatedIds`.
+     */
+    annotations?: ReadonlyArray<Datum>;
+}
+export interface UseNavigationSyncResult {
+    /** Controlled active node id — pass to `AccessibleNavTree`. */
+    activeId: string;
+    /** Change handler — pass to `AccessibleNavTree` (drives the canvas highlight). */
+    onActiveChange: (node: NavTreeNode) => void;
+    /** Pass to the chart as `selection={sync.selection}`. */
+    selection: {
+        name: string;
+    };
+    /** Nav-tree leaf ids that an annotation anchors to — mark these as "has a note". */
+    annotatedIds: Set<string>;
+    /**
+     * Move the tree (and canvas highlight) to an annotation's anchored node.
+     * Accepts an annotation object or its index in `annotations`. Returns `true`
+     * if the anchor resolved to a leaf. The reader lands on the anchored datum.
+     */
+    focusAnnotation: (annotation: Datum | number) => boolean;
+}
+export declare function useNavigationSync(options: UseNavigationSyncOptions): UseNavigationSyncResult;

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

@@ -0,0 +1,168 @@
+import type { ChartCapability, ChartDataProfile, ChartRubric, ChartVariant } from "./chartCapabilityTypes";
+import type { IntentId } from "./intents";
+import { type AudienceProfile } from "./audienceProfile";
+/**
+ * Where a proposal came from. Used by scoring + ranking to weight
+ * trusted sources (manual hand-curated variants) above heuristic
+ * suggestions and model-generated proposals that need verification.
+ */
+export type VariantProposalSource = "manual" | "heuristic" | "model";
+/**
+ * A "what if we tried this configuration?" candidate. Closely
+ * related to `ChartVariant`, but with explicit provenance and an
+ * optional `buildProps` so model-generated proposals can carry
+ * their own prop-construction logic without registering a full
+ * capability.
+ *
+ * The `id` is the durable identifier — the scoring side keys
+ * results by it so consumers can correlate proposals across
+ * propose/evaluate rounds.
+ */
+export interface VariantProposal {
+    /** Stable identifier — `<component>:<key>` is the conventional shape. */
+    id: string;
+    /** Component this proposal would render. */
+    baseComponent: string;
+    /** Human-facing label, usually a registered variant label or generated heuristic label. */
+    label?: string;
+    /**
+     * Per-intent score deltas applied on top of the base capability's
+     * `intentScores`. Use sparingly — over-large deltas are a sign the
+     * proposal should be a separate chart, not a variant.
+     */
+    intentDeltas?: Partial<Record<IntentId, number>>;
+    /** Rubric deltas applied on top of the base capability's rubric. */
+    rubricDeltas?: Partial<ChartRubric>;
+    /**
+     * Build the props this proposal would pass to the component. When
+     * omitted, the engine falls back to the capability's own
+     * `buildProps(profile, variant)`. Model-generated proposals
+     * typically provide their own.
+     */
+    buildProps?: (profile: ChartDataProfile, audience?: AudienceProfile) => Record<string, unknown>;
+    /** Free-form natural-language rationale for the proposal. */
+    rationale?: string;
+    /** Where the proposal originated. */
+    source: VariantProposalSource;
+    /** Optional reference to a registered variant key when the proposal mirrors one. */
+    variantKey?: string;
+    /** Optional tags consumers can filter on (mirrors `ChartVariant.tags`). */
+    tags?: ReadonlyArray<string>;
+}
+/**
+ * Why we'd reject a proposal: missing required field, conflicts with
+ * data type, audience mismatch above threshold, etc. Surfaced through
+ * `VariantScore.reasons`.
+ */
+export type VariantRejectionReason = string;
+/**
+ * Result of evaluating a single proposal against a data profile and
+ * (optionally) an audience. Composes with the existing
+ * `suggestCharts` scoring vocabulary.
+ */
+export interface VariantScore {
+    /** Echoes `VariantProposal.id`. */
+    proposalId: string;
+    /**
+     * How well this proposal matches the profile + audience, 0..5.
+     * Drawn from the same 0..5 scale `suggestCharts` uses so consumers
+     * can mix variant proposals into a unified ranked list.
+     */
+    fit: number;
+    /**
+     * How surprising the proposal is relative to the obvious
+     * recommendation, 0..1. Higher = more novel. The talk-track use
+     * is "a discovery model proposed a Ridgeline where the audience
+     * expected a BoxPlot."
+     */
+    novelty: number;
+    /**
+     * Risk of misleading the audience, 0..1. Higher = more risky.
+     * Drives the visual treatment (warning chip, expanded caveats).
+     */
+    risk: number;
+    /**
+     * Narrative reasons assembled from the capability `fits()` gate,
+     * rubric deltas, audience bias, and the discovery source. Suitable
+     * for tooltips and LLM context.
+     */
+    reasons: ReadonlyArray<string>;
+}
+export interface EvaluateVariantProposalOptions {
+    /** Ranking intent(s). When omitted, fit uses the mean non-zero intent score. */
+    intent?: IntentId | ReadonlyArray<IntentId>;
+    /** Component the user started from — used to estimate cross-family novelty. */
+    baselineComponent?: string;
+}
+/**
+ * Context handed to a discovery function. Carries everything a
+ * proposer needs to inspect the existing recommendation surface:
+ * the dataset profile, the audience, the already-considered
+ * variants, and the intent driving the recommendation.
+ */
+export interface VariantDiscoveryContext {
+    profile: ChartDataProfile;
+    audience?: AudienceProfile;
+    intent?: IntentId | ReadonlyArray<IntentId>;
+    /**
+     * Variants already attached to the base capability — proposers
+     * should avoid re-emitting these unless they have meaningful
+     * deltas a registered variant doesn't.
+     */
+    existingVariants?: ReadonlyArray<ChartVariant>;
+}
+/**
+ * Signature for a proposal generator. Implementations may be
+ * heuristic, LLM-driven, or hand-coded. The engine collects
+ * proposals from every registered discovery function and ranks
+ * the union through `evaluateVariantProposal`.
+ */
+export type ProposeVariantFn = (component: string, capability: ChartCapability, context: VariantDiscoveryContext) => ReadonlyArray<VariantProposal>;
+/**
+ * Signature for a scoring function. The default scorer composes the
+ * capability's `fits()` gate, rubric deltas, and audience bias. External
+ * scorers may add their own novelty/risk computations.
+ */
+export type EvaluateVariantProposalFn = (proposal: VariantProposal, profile: ChartDataProfile, audience?: AudienceProfile, options?: EvaluateVariantProposalOptions) => VariantScore;
+/**
+ * Aggregates proposals from every registered discovery function.
+ *
+ * Each registered function is invoked with the same `(component,
+ * capability, context)` tuple; their results are concatenated and
+ * deduplicated by `VariantProposal.id` (first proposer wins). A
+ * proposer that throws is isolated — the error surfaces through
+ * `console.warn` and the remaining proposers still run.
+ *
+ * The built-in proposer first emits registered `capability.variants` as
+ * manual proposals, then adds conservative heuristic transforms and
+ * same-intent cross-family alternatives. Registered discovery functions
+ * run after that and are deduplicated by `VariantProposal.id`.
+ */
+export declare const proposeVariant: ProposeVariantFn;
+/**
+ * Evaluate a proposal against the same ingredients the capability
+ * recommender uses: fits gate, intent scores, rubric deltas, and audience
+ * profile. `novelty` and `risk` are discovery-specific side channels.
+ */
+export declare const evaluateVariantProposal: EvaluateVariantProposalFn;
+/**
+ * Register a discovery function. Returns an unregister callback.
+ *
+ * `proposeVariant` invokes every registered function and deduplicates
+ * by `VariantProposal.id`. External ML-driven proposers plug in here
+ * without API change.
+ *
+ * Built-in heuristic discovery lives in `proposeVariant` directly. This
+ * registry is the extension surface for consumers and model integrations.
+ */
+export declare function registerVariantDiscovery(fn: ProposeVariantFn): () => void;
+/**
+ * Snapshot the registered discovery functions. Primarily for testing
+ * and for the engine implementation to iterate registered proposers.
+ */
+export declare function getRegisteredVariantDiscovery(): ReadonlyArray<ProposeVariantFn>;
+/**
+ * Drop every registered discovery function. Exposed for tests and
+ * for consumers who need to swap discovery models between sessions.
+ */
+export declare function clearVariantDiscovery(): void;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -64,6 +65,8 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
     annotations?: Datum[];
+    /** Opt into automatic placement for note-like annotations without manual offsets. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** SVG annotation render function */
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
@@ -87,6 +88,8 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
     annotations?: Datum[];
+    /** Opt into automatic placement for note-like annotations without manual offsets. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** SVG annotation render function */
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -64,6 +65,8 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
     annotations?: Datum[];
+    /** Opt into automatic placement for note-like annotations without manual offsets. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** SVG annotation render function */
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -70,6 +71,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects (including threshold coloring) */
     annotations?: Datum[];
+    /** Opt into automatic placement for note-like annotations without manual offsets. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** SVG annotation render function */
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -6,6 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
@@ -72,6 +73,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
     annotations?: Datum[];
+    /** Opt into automatic placement for note-like annotations without manual offsets. */
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
     /** SVG annotation render function */
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */

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

@@ -0,0 +1,42 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
+export type AnnotationEmphasis = "primary" | "secondary";
+/** A rendered annotation node paired with the source annotation it came
+ *  from, so hierarchy treatment can read metadata after the per-type rule has
+ *  produced the node. */
+export interface AnnotationRenderPair {
+    node: React.ReactNode;
+    annotation: Datum;
+}
+/**
+ * Reveal CSS for M3 progressive disclosure. Density-deferred notes are hidden
+ * (opacity 0) until the chart they belong to is hovered or focused. The
+ * selectors are scoped to each frame's stable wrapper class so a chart only
+ * reveals its *own* deferred notes; `:focus-within` covers keyboard users who
+ * focus the canvas (the canvas lives inside the wrapper). Style rules are
+ * document-global regardless of where the `<style>` tag lands, so injecting it
+ * inside the (pointer-events:none) overlay svg is fine. Identical across charts
+ * — duplicate injections are harmless.
+ */
+export declare const ANNOTATION_DISCLOSURE_REVEAL_CSS: string;
+/**
+ * Apply annotation hierarchy — Rahman et al.'s "Hierarchy" consideration,
+ * reusing the same `emphasis` token charts already accept (`"primary"` /
+ * `"secondary"`). A `secondary` annotation dims, shrinks note text through
+ * inherited SVG font-size, and yields z-order; a `primary` one paints at full
+ * weight and on top.
+ *
+ * If no explicit emphasis is declared, annotations with
+ * `provenance.confidence` get an inferred reading order: confidence
+ * descending, then authored array order. The visual output uses that order as
+ * a subtle opacity gradient, with higher-confidence notes painted later.
+ *
+ * Type-agnostic: it wraps whatever the per-type rule produced, so all
+ * annotation types get hierarchy without each rule knowing about it.
+ *
+ * Zero-overhead and structure-preserving when no annotation declares an
+ * explicit emphasis or provenance confidence: the original nodes are returned
+ * untouched (same keys, same order), so existing charts render identically.
+ * Opacity composes multiplicatively with lifecycle freshness opacity.
+ */
+export declare function applyAnnotationEmphasis(pairs: ReadonlyArray<AnnotationRenderPair>): React.ReactNode[];

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

@@ -3,8 +3,8 @@ import type { Datum } from "./datumTypes";
  * Coordinate resolution helpers for annotations.
  *
  * Resolves data coordinates to pixel positions, respecting anchor modes
- * (fixed, latest, sticky), pointId matching, and bounds checking for
- * streaming charts where data scrolls off-screen.
+ * (fixed, latest, sticky, semantic), pointId / stableId matching, and
+ * bounds checking for streaming charts where data scrolls off-screen.
  *
  * Dependencies: types (AnnotationContext)
  * Consumed by: annotationRules.tsx (all annotation type renderers)
@@ -17,6 +17,7 @@ export declare function resolveY(ann: Datum, context: AnnotationContext): number
  * - "fixed" (default): resolve from annotation's own fields
  * - "latest": resolve from the most recent datum in the buffer
  * - "sticky": resolve from annotation fields; if not found, use cached position
+ * - "semantic": resolve from provenance.stableId; if not found, use recorded fields
  */
 export declare function resolveAnchoredPosition(ann: Datum, index: number, context: AnnotationContext): {
     x: number;

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

@@ -1,4 +1,20 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+export { applyAnnotationEmphasis, type AnnotationRenderPair } from "./annotationHierarchy";
+type AnnotationRule = (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
+/**
+ * Run the SVG-overlay annotation pass: dispatch each annotation through the
+ * user's `svgAnnotationRules` (falling back to the default rules), drop the
+ * ones that render nothing, then apply emphasis hierarchy. Shared verbatim by
+ * the XY and ordinal overlays so the dispatch/filter/hierarchy logic lives in
+ * one place.
+ *
+ * Falsy-node semantics match the pre-emphasis `.filter(Boolean)` exactly: a
+ * rule returning `null`/`undefined` ("skip", e.g. the default rules' out-of-
+ * bounds path) — or any other falsy node (`0`/`""`/`false`) — produces no
+ * annotation and is dropped. A user rule that returns `null`/`undefined` falls
+ * through to the default rule, preserving the existing override contract.
+ */
+export declare function renderAnnotationPass(annotations: ReadonlyArray<Datum>, defaultRule: AnnotationRule, userRule: AnnotationRule | undefined, context: AnnotationContext): React.ReactNode[];
 export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;

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

@@ -0,0 +1,14 @@
+import type { Datum } from "./datumTypes";
+/**
+ * Note-like annotations compete for placement and density budgets. Keep this
+ * taxonomy centralized because layout, diagnostics, and accessibility checks
+ * all need to agree on what counts as a note.
+ */
+export declare const NOTE_ANNOTATION_TYPES: readonly ["label", "callout", "callout-circle", "callout-rect", "text", "widget"];
+export type NoteAnnotationType = (typeof NOTE_ANNOTATION_TYPES)[number];
+/** Note types whose default renderer draws a connector unless disabled. */
+export declare const CONNECTOR_ANNOTATION_TYPES: readonly ["label", "callout", "callout-circle", "callout-rect"];
+export declare function annotationType(annotation: Datum): string;
+export declare function isNoteAnnotation(annotation: Datum): boolean;
+export declare function annotationDisablesConnector(annotation: Datum): boolean;
+export declare function annotationDrawsConnector(annotation: Datum): boolean;

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

@@ -0,0 +1,90 @@
+import type { Datum } from "./datumTypes";
+export type A11yPrinciple = "perceivable" | "operable" | "understandable" | "robust" | "compromising" | "assistive" | "flexible";
+/**
+ * - `pass`  — satisfied (by config or by Semiotic's built-ins)
+ * - `fail`  — a problem we can prove from the config
+ * - `warn`  — a likely problem or a default worth revisiting
+ * - `manual`— can't be settled statically; run the named Chartability test
+ * - `not-applicable` — heuristic doesn't apply to this chart
+ */
+export type A11yStatus = "pass" | "fail" | "warn" | "manual" | "not-applicable";
+export interface A11yFinding {
+    /** Stable id, `principle.heuristic-slug` (e.g. "perceivable.low-contrast"). */
+    id: string;
+    principle: A11yPrinciple;
+    /** The Chartability heuristic name, verbatim. */
+    heuristic: string;
+    /** Chartability flags 14 of 50 heuristics as critical. */
+    critical: boolean;
+    status: A11yStatus;
+    message: string;
+    /** How to fix or, for `manual`, the test to run. */
+    fix?: string;
+}
+export interface AccessibilityAuditResult {
+    component: string;
+    /** No critical heuristic is in a `fail` state. (warn/manual don't break this.) */
+    ok: boolean;
+    summary: {
+        criticalsPassed: number;
+        /** Critical heuristics actually evaluated (excludes not-applicable). */
+        criticalsEvaluated: number;
+        fails: number;
+        warnings: number;
+        manual: number;
+        passes: number;
+    };
+    findings: A11yFinding[];
+    /** Always points back to the source framework. */
+    reference: string;
+}
+export interface AuditAccessibilityOptions {
+    /**
+     * Whether the chart is wrapped in a ChartContainer (or otherwise exposes a
+     * data-download / copy-config affordance). Lets the audit credit the
+     * "downloadable table" and "shareable state" heuristics. ChartContainer is
+     * the opt-in layer for full-accessibility chrome (title, caption,
+     * description), so several heuristics soften their remediation toward it.
+     * Default false.
+     */
+    inChartContainer?: boolean;
+    /**
+     * Whether ChartContainer's `describe` option (auto-generated L1–L3 description
+     * via describeChart) is enabled. Lets the "features described" heuristic pass.
+     * Default false.
+     */
+    describe?: boolean;
+    /**
+     * Whether ChartContainer's `navigable` option (a structured, screen-reader-
+     * navigable tree via buildNavigationTree/AccessibleNavTree) is enabled. Lets
+     * the "navigable structure" heuristic pass — including for hierarchy charts.
+     * Default false.
+     */
+    navigable?: boolean;
+}
+/**
+ * Audit a Semiotic chart configuration against the Chartability heuristics.
+ * Pure, SSR-safe, no DOM. See module docstring for what static analysis can
+ * and cannot determine.
+ */
+export declare function auditAccessibility(component: string, props: Datum, options?: AuditAccessibilityOptions): AccessibilityAuditResult;
+/**
+ * Distil an audit result into terse caveat strings — the author-actionable
+ * `fail` and `warn` findings, one line each. Lets the recommender (and an AI
+ * agent) read *receivability* caveats ("8 slices is too many," "color-only
+ * encoding") from the same channel as the perceptual caveats a capability
+ * descriptor already declares, instead of two disconnected surfaces.
+ *
+ * Pure. Pair with {@link auditAccessibility}:
+ * ```ts
+ * const caveats = accessibilityCaveats(auditAccessibility("PieChart", props))
+ * ```
+ *
+ * @param onlyCritical When true, restrict to critical heuristics (the 14 that
+ *   Chartability flags). Default false — include all fail/warn findings.
+ */
+export declare function accessibilityCaveats(result: AccessibilityAuditResult, { onlyCritical }?: {
+    onlyCritical?: boolean;
+}): string[];
+/** Render an audit result as a human-readable report (used by --audit-a11y + MCP). */
+export declare function formatAccessibilityAudit(result: AccessibilityAuditResult): string;

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

@@ -1,9 +1,8 @@
 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";
+export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "value";
 /**
- * Capability tags for runtime behavior. Driven by the
- * `hoc-frame-architecture-audit` Phase 1: each chart declares which
+ * 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.
  *

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

@@ -9,10 +9,8 @@ export interface DiagnosisResult {
     ok: boolean;
     diagnoses: Diagnosis[];
 }
-/**
- * Run anti-pattern diagnostics on a Semiotic chart configuration.
- *
- * Returns actionable diagnoses with severity, code, message, and fix instruction.
- * Runs validateProps internally — validation errors are included as diagnoses.
- */
+/** WCAG contrast ratio between two hex colors. Exported for reuse by the
+ *  accessibility audit (auditAccessibility.ts) — single source of truth for the
+ *  contrast math. Returns null if either color isn't a parseable hex. */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;
 export declare function diagnoseConfig(componentName: string, props: Datum): DiagnosisResult;

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

@@ -8,8 +8,10 @@ import type { Datum } from "./datumTypes";
 export interface NormalizedLinkedHover {
     name: string;
     fields: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    /** Explicit series-identity field for `mode: "series"`; overrides the auto-resolved one. */
+    seriesField?: string;
 }
 export interface NormalizedLinkedBrush {
     name: string;
@@ -26,8 +28,9 @@ export interface NormalizedLinkedBrush {
 export declare function normalizeLinkedHover(prop: boolean | string | {
     name?: string;
     fields?: string[];
-    mode?: "field" | "x-position";
+    mode?: "field" | "x-position" | "series";
     xField?: string;
+    seriesField?: string;
 } | undefined, fallbackFields?: string[]): NormalizedLinkedHover | null;
 /**
  * Normalize the linkedBrush prop into a consistent config object.