semiotic 3.5.4 → 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/geo/ChoroplethMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ChoroplethMapCapability: ChartCapability;

package/dist/components/charts/geo/DistanceCartogram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DistanceCartogramCapability: ChartCapability;

package/dist/components/charts/geo/FlowMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const FlowMapCapability: ChartCapability;

package/dist/components/charts/geo/ProportionalSymbolMap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ProportionalSymbolMapCapability: ChartCapability;

package/dist/components/charts/index.d.ts

@@ -27,7 +27,7 @@ export type { ScatterplotMatrixProps } from "./xy/ScatterplotMatrix";
 export { MinimapChart } from "./xy/MinimapChart";
 export type { MinimapChartProps, MinimapConfig } from "./xy/MinimapChart";
 export { QuadrantChart } from "./xy/QuadrantChart";
-export type { QuadrantChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
+export type { QuadrantChartProps, QuadrantsConfig, QuadrantsConfigOverride, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
 export { MultiAxisLineChart } from "./xy/MultiAxisLineChart";
 export type { MultiAxisLineChartProps, MultiAxisSeriesConfig } from "./xy/MultiAxisLineChart";
 export { CandlestickChart } from "./xy/CandlestickChart";

package/dist/components/charts/network/ChordDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ChordDiagramCapability: ChartCapability;

package/dist/components/charts/network/CirclePack.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const CirclePackCapability: ChartCapability;

package/dist/components/charts/network/ForceDirectedGraph.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ForceDirectedGraphCapability: ChartCapability;

package/dist/components/charts/network/OrbitDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const OrbitDiagramCapability: ChartCapability;

package/dist/components/charts/network/ProcessSankey.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ProcessSankeyCapability: ChartCapability;

package/dist/components/charts/network/SankeyDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SankeyDiagramCapability: ChartCapability;

package/dist/components/charts/network/TreeDiagram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const TreeDiagramCapability: ChartCapability;

package/dist/components/charts/network/Treemap.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const TreemapCapability: ChartCapability;

package/dist/components/charts/ordinal/BarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/BoxPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const BoxPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/DonutChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DonutChartCapability: ChartCapability;

package/dist/components/charts/ordinal/DotPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const DotPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/FunnelChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const FunnelChartCapability: ChartCapability;

package/dist/components/charts/ordinal/GaugeChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GaugeChartCapability: ChartCapability;

package/dist/components/charts/ordinal/GroupedBarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GroupedBarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/Histogram.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const HistogramCapability: ChartCapability;

package/dist/components/charts/ordinal/Histogram.d.ts

@@ -23,8 +23,10 @@ export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartP
     data?: TDatum[];
     /**
      * Field name or function returning the bin label (used when data is
-     * already binned). Ignored when binning raw values.
-     * @default "category"
+     * already binned). For raw-observation data with no category dimension,
+     * the default treats all rows as a single "All" bucket — no need to set
+     * this explicitly.
+     * @default (d) => d.category ?? "All"
      */
     categoryAccessor?: ChartAccessor<TDatum, string>;
     /**

package/dist/components/charts/ordinal/LikertChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const LikertChartCapability: ChartCapability;

package/dist/components/charts/ordinal/LikertChart.d.ts

@@ -62,7 +62,7 @@ export interface LikertChartProps<TDatum extends Datum = Datum> extends BaseChar
      *
      * Odd count → center level is neutral. Even count → clean negative/positive split.
      */
-    levels: string[];
+    levels?: string[];
     /**
      * "horizontal" (default): diverging bar chart centered at 0%.
      * "vertical": stacked 100% bar chart.

package/dist/components/charts/ordinal/LikertChart.defaults.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_LIKERT_LEVELS: string[];

package/dist/components/charts/ordinal/PieChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const PieChartCapability: ChartCapability;

package/dist/components/charts/ordinal/RidgelinePlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const RidgelinePlotCapability: ChartCapability;

package/dist/components/charts/ordinal/StackedBarChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const StackedBarChartCapability: ChartCapability;

package/dist/components/charts/ordinal/SwarmPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SwarmPlotCapability: ChartCapability;

package/dist/components/charts/ordinal/SwimlaneChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const SwimlaneChartCapability: ChartCapability;

package/dist/components/charts/ordinal/ViolinPlot.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ViolinPlotCapability: ChartCapability;

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

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeHeatmapCapability: StreamChartCapability;

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.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeHistogramCapability: StreamChartCapability;

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.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeLineChartCapability: StreamChartCapability;

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.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeSwarmChartCapability: StreamChartCapability;

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.capability.d.ts

@@ -0,0 +1,2 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+export declare const RealtimeWaterfallChartCapability: StreamChartCapability;

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/realtime/TemporalHistogram.capability.d.ts

@@ -0,0 +1,7 @@
+import type { StreamChartCapability } from "../../ai/streamingTypes";
+/**
+ * TemporalHistogram is the bounded sibling of RealtimeHistogram — same chart
+ * but for static data with a fixed window. For stream selection it competes
+ * with RealtimeHistogram; the choice depends on retention.
+ */
+export declare const TemporalHistogramCapability: StreamChartCapability;