semiotic 3.6.0 → 3.7.1

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

@@ -1,4 +1,18 @@
 import type { ChartRubric } from "./chartCapabilityTypes";
+import type { AccessibilityAuditResult } from "../charts/shared/auditAccessibility";
+/**
+ * The channel an audience receives a chart through. Orthogonal to familiarity:
+ * a reader can be highly familiar with a chart type yet unable to *receive* it
+ * in their channel (an 8-slice pie is familiar but illegible to a screen
+ * reader). Defaults to `"visual"` when unset — no receivability bias applied.
+ *
+ *   • `visual`        — sighted reader; the historical default, no bias.
+ *   • `screen-reader` — non-visual; meaning must survive the data table / nav tree.
+ *   • `sonified`      — audio; density and ordering matter more than color.
+ *   • `agent`         — an LLM reading via the grounding payload; same non-visual
+ *                       "is the meaning recoverable without pixels?" question.
+ */
+export type ReceptionModality = "visual" | "screen-reader" | "sonified" | "agent";
 /**
  * A serializable description of who's reading the charts and what the
  * organization is trying to grow.
@@ -8,8 +22,6 @@ import type { ChartRubric } from "./chartCapabilityTypes";
  * telemetry, manager judgment, training records) and pass it to the
  * suggestion APIs. The library applies the bias and returns rankings that
  * reflect the audience instead of a generic data-literate baseline.
- *
- * Strategy memo: docs/strategy/audience-profiles.md
  */
 export interface AudienceProfile {
     /**
@@ -47,6 +59,15 @@ export interface AudienceProfile {
      *       widening the menu
      */
     exposureLevel?: 0 | 1 | 2;
+    /**
+     * The channel this audience receives charts through. When set to a non-visual
+     * modality, `suggestCharts` runs the accessibility audit on each candidate and
+     * `applyAudienceBias` down-ranks charts whose meaning doesn't survive that
+     * channel (and surfaces the receivability findings as caveats). Unset /
+     * `"visual"` keeps the historical behavior — familiarity and targets only.
+     * See {@link receivabilityBias}.
+     */
+    receptionModality?: ReceptionModality;
 }
 export interface AudienceTarget {
     direction: "increase" | "decrease";
@@ -62,7 +83,34 @@ export interface AudienceBiasResult {
     rubric: ChartRubric;
     /** Reason string to append to the suggestion when a target fired. */
     appliedReason?: string;
+    /** Reason string to append when a receivability penalty fired (non-visual modality). */
+    receivabilityReason?: string;
+}
+export interface ReceivabilitySignal {
+    /** Score delta (≤ 0) — the receivability penalty for this channel. */
+    delta: number;
+    /** One-line reason, present only when a penalty applied. */
+    reason?: string;
+    /**
+     * Caveat messages for the findings that drove the penalty — the receivability
+     * slice of the audit, ready to merge into a suggestion's `caveats[]` alongside
+     * the perceptual ones (so both channels read from the same array).
+     */
+    caveats: string[];
 }
+/**
+ * Translate an accessibility audit into a receivability penalty for a non-visual
+ * channel. Pure. `fail` findings on receivability-critical heuristics weigh most;
+ * `warn` findings weigh less; `manual`/`pass`/`not-applicable` never penalize
+ * (we don't punish what we can't prove). Penalty is clamped to a −3 floor so it
+ * reorders rankings without overriding data-shape correctness.
+ *
+ * ```ts
+ * const audit = auditAccessibility("PieChart", props)
+ * const { delta, reason } = receivabilityBias(audit, "screen-reader")
+ * ```
+ */
+export declare function receivabilityBias(audit: AccessibilityAuditResult, modality: ReceptionModality): ReceivabilitySignal;
 /**
  * Apply an AudienceProfile's bias to a chart's composite score and rubric.
  * Pure function — used by both `suggestCharts` and `suggestStretchCharts`.
@@ -75,8 +123,17 @@ export interface AudienceBiasResult {
  *       not so strong that it overrides chart correctness for the data shape.
  *
  * Score is left unclamped so internal sorting reflects the magnitude of bias.
+ *
+ * A third term — *receivability* — composes in when the audience declares a
+ * non-visual `receptionModality` and the caller passes a precomputed
+ * {@link ReceivabilitySignal} (from {@link receivabilityBias}). Familiarity and
+ * receivability are different axes: a chart can be familiar yet unreceivable in
+ * the target channel, and this folds that signal into the same score the
+ * recommender ranks by. The caller computes the signal once and reuses it for
+ * the suggestion's caveats too, so the audit is scanned a single time per
+ * candidate.
  */
-export declare function applyAudienceBias(baseScore: number, baseRubric: ChartRubric, component: string, audience: AudienceProfile | undefined): AudienceBiasResult;
+export declare function applyAudienceBias(baseScore: number, baseRubric: ChartRubric, component: string, audience: AudienceProfile | undefined, receivability?: ReceivabilitySignal): AudienceBiasResult;
 /**
  * Resolve the effective familiarity for a chart under an audience. Used by
  * the stretch surface to decide whether a chart qualifies as "unfamiliar."

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

@@ -1,14 +1,15 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { DataSummary } from "../data/DataSummarizer";
 import type { IntentId } from "./intents";
+import type { ScaleFitFn, QualityFitFn, ScaleBand, CardinalityBand, EffectiveScale } from "./dataScaleProfile";
 /**
  * Chart family — high-level taxonomy used for filtering and intent matching.
  */
-export type ChartFamily = "time-series" | "categorical" | "distribution" | "relationship" | "flow" | "network" | "hierarchy" | "geo" | "realtime" | "custom";
+export type ChartFamily = "time-series" | "categorical" | "distribution" | "relationship" | "flow" | "network" | "hierarchy" | "geo" | "realtime" | "value" | "custom";
 /**
  * Where a chart is imported from. Used by generators to emit correct import paths.
  */
-export type ChartImportPath = "semiotic/xy" | "semiotic/ordinal" | "semiotic/network" | "semiotic/geo" | "semiotic/realtime" | "semiotic/ai" | "semiotic";
+export type ChartImportPath = "semiotic/xy" | "semiotic/ordinal" | "semiotic/network" | "semiotic/geo" | "semiotic/realtime" | "semiotic/value" | "semiotic/ai" | "semiotic";
 /**
  * Familiarity/accuracy/precision rubric (1-5 each).
  * Familiarity = how well-known the chart is to a general audience.
@@ -171,6 +172,38 @@ export interface ChartCapability {
      * a runnable config (accessor names, etc.) so consumers can `<Component {...props}>`.
      */
     buildProps: (profile: ChartDataProfile, variant?: ChartVariant) => Record<string, unknown>;
+    /**
+     * Optional declaration of this chart's sweet spot under scale. Receives the
+     * effective scale (declared `DataScaleProfile` merged with measured profile)
+     * and returns a score delta plus optional caveats. Use `scaleHints(...)` from
+     * `dataScaleProfile.ts` for the common declarative shape.
+     *
+     * When omitted, the engine assumes the chart is scale-agnostic and applies
+     * no scale bias beyond what `intentScores` already encodes in `profile`.
+     */
+    scaleFit?: ScaleFitFn;
+    /**
+     * Optional declaration of this chart's response to data quality (missingness,
+     * outliers, type heterogeneity). Returns a score delta plus caveats. When
+     * omitted, the engine applies a default heuristic that adds caveats for
+     * low completeness on the primary y field.
+     */
+    qualityFit?: QualityFitFn;
+}
+/**
+ * Effective scale range tag on a suggestion. Lets callers group suggestions
+ * by their scale sweet spot, detect threshold crossings as data grows, and
+ * narrate why a recommendation changed.
+ */
+export interface SuggestionScaleRange {
+    /** Band classification of the row count this suggestion was evaluated against. */
+    band: ScaleBand;
+    /** Cardinality band, if known. */
+    cardinalityBand?: CardinalityBand;
+    /** Effective row count the engine reasoned over (declared or measured). */
+    rows: number;
+    /** Whether the row count came from a user-declared profile or the measured data. */
+    rowsSource: "declared" | "measured";
 }
 /**
  * One suggestion produced by `suggestCharts`. Consumers render this as a card,
@@ -193,4 +226,29 @@ export interface Suggestion {
     caveats: ReadonlyArray<string>;
     /** Ready-to-spread props. */
     props: Record<string, unknown>;
+    /**
+     * Scale tag — present when scale/quality information is available, either
+     * through declared `DataScaleProfile` or through the measured profile.
+     * Surfaces what band this chart was scored at so consumers can group by
+     * scale, detect threshold crossings, or narrate "the chart for now → at 10×."
+     */
+    scaleRange?: SuggestionScaleRange;
+}
+/**
+ * Multi-tier grouping of suggestions by scale band. Returned by
+ * `suggestChartsGrouped()`.
+ *
+ * Each tier is a ranked list of suggestions whose `scaleRange.band` falls in
+ * that tier. A single chart can appear in multiple tiers when its sweet-spot
+ * range spans them — that's the "graduation of views" surface: the same data
+ * gets a different chart depending on which scale you're optimizing for.
+ */
+export interface ScaledSuggestionGroups {
+    tiny: Suggestion[];
+    small: Suggestion[];
+    medium: Suggestion[];
+    large: Suggestion[];
+    huge: Suggestion[];
+    /** The effective scale view the engine reasoned over. */
+    effective: EffectiveScale;
 }

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

@@ -0,0 +1,27 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Shared chart-family classification + measure/dimension role resolution.
+ *
+ * `describeChart` (prose) and `buildNavigationTree` (structure) both need to
+ * know which family a component belongs to and which props carry its measure
+ * (quantitative) and dimension (categorical/ordered) accessors. This is the
+ * single source of truth so the two surfaces can't drift apart.
+ *
+ * Pure, dependency-light (types only).
+ */
+export declare const XY_FAMILY: Set<string>;
+export declare const BAR_FAMILY: Set<string>;
+export declare const PART_TO_WHOLE: Set<string>;
+export declare const DISTRIBUTION: Set<string>;
+export interface ChartRoles {
+    measure?: string;
+    measureFallback: string;
+    dimension?: string;
+    dimensionFallback: string;
+}
+/** The measure (quantitative) and dimension (categorical/ordered) accessors, by family. */
+export declare function roles(component: string, props: Datum): ChartRoles;
+/** First string-valued series-splitting accessor among the known channels, if any. */
+export declare function seriesField(props: Datum): string | undefined;
+/** Format a dimension value (the label at an extremum) — dates as ISO day, numbers compactly. */
+export declare function fmtDim(v: unknown, fmtNum: (n: number) => string): string;

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

@@ -0,0 +1,379 @@
+import type { AnnotationStatus } from "./annotationProvenance";
+export type ConversationArcEventType = "suggestion-shown" | "suggestion-chosen" | "audience-set" | "chart-rendered" | "chart-edited" | "chart-replaced" | "chart-exported" | "chart-abandoned" | "interrogation-asked" | "interrogation-answered" | "nav-node-focused" | "nav-branch-expanded" | "annotation-status-changed";
+interface ConversationArcEventBase {
+    /** Discriminator for the event variant. */
+    type: ConversationArcEventType;
+    /** `Date.now()` at the moment the event was recorded. Stamped by the store. */
+    timestamp: number;
+    /** Stable ID for the enabled session — survives until `disableConversationArc()` or `reset()`. */
+    sessionId: string;
+    /** Optional opaque correlation key that threads a single arc together. */
+    arcId?: string;
+    /** Free-form bag for context the talk-track doesn't need a typed slot for. */
+    meta?: Record<string, unknown>;
+}
+export interface SuggestionShownEvent extends ConversationArcEventBase {
+    type: "suggestion-shown";
+    /**
+     * Intent label fed into `suggestCharts` (e.g. "trend", "distribution").
+     * Accepts a single intent or an array — mirrors `SuggestChartsOptions.intent`.
+     */
+    intent?: string | ReadonlyArray<string>;
+    /** Ranked component names in the order the suggester returned them. */
+    components: string[];
+    /** Top suggestion's composite score, if known. */
+    topScore?: number;
+    /** Audience target active when the suggestion ran. */
+    audience?: string;
+}
+export interface SuggestionChosenEvent extends ConversationArcEventBase {
+    type: "suggestion-chosen";
+    component: string;
+    /** 1-based rank in the matching `suggestion-shown` event, if known. */
+    rank?: number;
+    /** Who picked the suggestion: a human, an agent loop, or a default-fall-through. */
+    source?: "user" | "agent" | "auto";
+}
+export interface AudienceSetEvent extends ConversationArcEventBase {
+    type: "audience-set";
+    audience: string;
+    previous?: string;
+}
+export interface ChartRenderedEvent extends ConversationArcEventBase {
+    type: "chart-rendered";
+    component: string;
+    chartId?: string;
+}
+export interface ChartEditedEvent extends ConversationArcEventBase {
+    type: "chart-edited";
+    component: string;
+    chartId?: string;
+    /** Names of props that changed in this edit. */
+    changedProps?: string[];
+}
+export interface ChartReplacedEvent extends ConversationArcEventBase {
+    type: "chart-replaced";
+    from: string;
+    to: string;
+    /** Why the swap happened — `"repair"`, `"variant"`, `"user-rejected"`, etc. */
+    reason?: string;
+}
+export interface ChartExportedEvent extends ConversationArcEventBase {
+    type: "chart-exported";
+    component: string;
+    /** What was exported: `"jsx"`, `"svg"`, `"png"`, `"json"`, `"url"`, etc. */
+    format: string;
+}
+export interface ChartAbandonedEvent extends ConversationArcEventBase {
+    type: "chart-abandoned";
+    component?: string;
+    reason?: string;
+}
+export interface InterrogationAskedEvent extends ConversationArcEventBase {
+    type: "interrogation-asked";
+    /** Chart the question was directed at, if known. */
+    component?: string;
+    /**
+     * Question text. The `useChartInterrogation` instrumentation
+     * truncates to ~500 chars before recording so the ring buffer
+     * stays bounded; callers stamping their own events should do the
+     * same.
+     */
+    query: string;
+    /** Optional payload size hint (e.g. summary token count) for diagnostics. */
+    contextSize?: number;
+}
+export interface InterrogationAnsweredEvent extends ConversationArcEventBase {
+    type: "interrogation-answered";
+    /** Chart the answer was directed at, if known. */
+    component?: string;
+    /**
+     * Answer text. The `useChartInterrogation` instrumentation
+     * truncates to ~2000 chars before recording so multi-kilobyte LLM
+     * responses don't bloat the ring buffer. Callers stamping their
+     * own events should follow the same convention.
+     */
+    answer?: string;
+    /** Number of annotations the response attached, if known. */
+    annotationCount?: number;
+    /**
+     * Round-trip latency in ms from ask to answer, clamped to ≥ 0.
+     * The instrumentation measures via `performance.now()` when
+     * available; the `Date.now()` fallback can produce negative
+     * deltas under clock changes, hence the clamp.
+     */
+    latencyMs?: number;
+    /** Set when the response was an error rather than a successful answer. */
+    error?: boolean;
+}
+/**
+ * A reader focused a node in an `AccessibleNavTree` (keyboard or click). The
+ * first *reception*-side behavioral signal in the arc — which structural nodes
+ * a non-visual (or AI) reader actually visits, the dependent measure visualization-
+ * literacy studies usually lack. Emitted only on genuine tree interaction, not
+ * when the active node is driven externally (canvas → tree sync).
+ */
+export interface NavNodeFocusedEvent extends ConversationArcEventBase {
+    type: "nav-node-focused";
+    /** `chartId` of the chart the tree describes, when correlated. */
+    chartId?: string;
+    /** Tree node id that gained focus. */
+    nodeId: string;
+    /** Node role: `"chart" | "axis" | "series" | "datum"`. */
+    role: string;
+    /** 1-based depth (aria-level). */
+    level: number;
+    /** The node's announced label (the emitter truncates to ~200 chars). */
+    label?: string;
+}
+/** A reader expanded or collapsed a branch in an `AccessibleNavTree`. */
+export interface NavBranchExpandedEvent extends ConversationArcEventBase {
+    type: "nav-branch-expanded";
+    /** `chartId` of the chart the tree describes, when correlated. */
+    chartId?: string;
+    /** Tree node id that was toggled. */
+    nodeId: string;
+    /** Node role of the toggled branch. */
+    role: string;
+    /** 1-based depth (aria-level). */
+    level: number;
+    /** `true` on expand, `false` on collapse. */
+    expanded: boolean;
+}
+/**
+ * An annotation's editorial status transitioned (M7). The accept / dispute /
+ * retract / propose flow is what turns an annotation into the durable,
+ * observable node of the conversation arc (IDID §13.4): the note is the unit
+ * the arc is *about*, not chart chrome.
+ *
+ * `fromStatus`/`toStatus` are deliberately not named `from`/`to` — `summarizeArc`
+ * reads `from`/`to` as chart-component names (the `chart-replaced` shape), so a
+ * status value there would pollute `componentsSeen`.
+ */
+export interface AnnotationStatusChangedEvent extends ConversationArcEventBase {
+    type: "annotation-status-changed";
+    /** `provenance.stableId` of the annotation whose status changed, when known. */
+    annotationId?: string;
+    /** Previous editorial status, if known. */
+    fromStatus?: AnnotationStatus;
+    /** New editorial status. */
+    toStatus: AnnotationStatus;
+    /** `chartId` of the chart carrying the annotation, when correlated. */
+    chartId?: string;
+}
+export type ConversationArcEvent = SuggestionShownEvent | SuggestionChosenEvent | AudienceSetEvent | ChartRenderedEvent | ChartEditedEvent | ChartReplacedEvent | ChartExportedEvent | ChartAbandonedEvent | InterrogationAskedEvent | InterrogationAnsweredEvent | NavNodeFocusedEvent | NavBranchExpandedEvent | AnnotationStatusChangedEvent;
+/**
+ * Input shape accepted by `record()`: the event variant without the
+ * stamped fields (`timestamp` and `sessionId`). Callers may still
+ * provide them to backfill historical events.
+ *
+ * Implemented as a distributive conditional so each member of the
+ * discriminated union keeps its variant-specific payload (e.g.
+ * `SuggestionShownEvent.components`). A non-distributive
+ * `Omit<ConversationArcEvent, ...>` collapses to the union's common
+ * fields and rejects every variant-specific key.
+ */
+export type ConversationArcEventInput = ConversationArcEvent extends infer E ? E extends ConversationArcEvent ? Omit<E, "timestamp" | "sessionId"> & Partial<Pick<E, "timestamp" | "sessionId">> : never : never;
+export type ConversationArcListener = (event: ConversationArcEvent) => void;
+export interface ConversationArcSink {
+    /**
+     * Persist a newly-recorded event. Called only after the store is enabled and
+     * the event is accepted into the ring buffer.
+     */
+    record?(event: ConversationArcEvent): void | Promise<void>;
+    /**
+     * Optional hook for consumers that treat `flush()` as an export boundary.
+     * The in-memory buffer is still cleared by the store after this call.
+     */
+    flush?(events: ReadonlyArray<ConversationArcEvent>): void | Promise<void>;
+    /** Clear durable state owned by this sink. */
+    clear?(): void | Promise<void>;
+    /** Load previously persisted events for replay / hydration. */
+    load?(): ReadonlyArray<ConversationArcEvent> | Promise<ReadonlyArray<ConversationArcEvent>>;
+}
+export interface ConversationArcStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface LocalStorageConversationArcSinkOptions {
+    /** Storage key. Defaults to `semiotic:conversation-arc`. */
+    key?: string;
+    /** Test hook or alternate Storage implementation. Defaults to `window.localStorage`. */
+    storage?: ConversationArcStorageLike;
+    /** Maximum events retained in storage. Defaults to 1000. */
+    maxEvents?: number;
+}
+export interface IndexedDBConversationArcSinkOptions {
+    /** Database name. Defaults to `semiotic-conversation-arc`. */
+    dbName?: string;
+    /** Object store name. Defaults to `events`. */
+    storeName?: string;
+    /** Test hook or alternate IndexedDB factory. Defaults to `globalThis.indexedDB`. */
+    indexedDB?: IDBFactory;
+    /** Maximum events retained in the object store. Defaults to 1000. */
+    maxEvents?: number;
+}
+export type ConversationArcWebhookFetch = (input: string, init?: RequestInit) => Promise<unknown>;
+export interface WebhookConversationArcSinkOptions {
+    url: string;
+    method?: "POST" | "PUT";
+    headers?: Record<string, string>;
+    fetch?: ConversationArcWebhookFetch;
+    mapEvent?: (event: ConversationArcEvent) => unknown;
+}
+export interface LoadConversationArcOptions {
+    /** Capacity of the hydrated ring buffer. Defaults to max(existing, events.length, 1000). */
+    capacity?: number;
+    /** Active session id for future recordings. Replayed event session ids are preserved. */
+    sessionId?: string;
+    /**
+     * Whether the store should accept new events after hydration. Defaults to false
+     * so replaying an artifact cannot accidentally start telemetry.
+     */
+    enabled?: boolean;
+    /** Append to the current buffer instead of replacing it. Defaults to false. */
+    append?: boolean;
+}
+export interface ConversationArcStore {
+    readonly enabled: boolean;
+    readonly sessionId: string | null;
+    readonly capacity: number;
+    /**
+     * Records an event. Returns the stamped event on success, or `null`
+     * if the store is disabled. Stamps `timestamp` and `sessionId` if
+     * the caller didn't.
+     */
+    record(input: ConversationArcEventInput): ConversationArcEvent | null;
+    /** Returns the current buffer (newest last) and clears it. */
+    flush(): ConversationArcEvent[];
+    /**
+     * Returns a frozen, referentially-stable snapshot of the current
+     * buffer. Stable across consecutive calls until the next mutation,
+     * so it can drive `useSyncExternalStore`. Read-only — callers that
+     * need a mutable copy should `.slice()` the result.
+     */
+    getEvents(): ReadonlyArray<ConversationArcEvent>;
+    /**
+     * Subscribe to new events. Returns an unsubscribe function.
+     *
+     * Subscriptions persist across enable/disable transitions — a
+     * subscriber registered before `enableConversationArc()` still
+     * receives events once recording starts. Cleared by `reset()`.
+     */
+    subscribe(listener: ConversationArcListener): () => void;
+    /** Empties the buffer without disabling the store. */
+    clear(): void;
+    /** Disables the store and drops the buffer + subscribers. */
+    reset(): void;
+}
+export interface EnableConversationArcOptions {
+    /** Maximum events retained in the ring buffer. Defaults to 1000. */
+    capacity?: number;
+    /** Override the generated session ID. Useful for cross-tab correlation. */
+    sessionId?: string;
+}
+/**
+ * Subscribe to *any* state mutation in the conversation-arc store —
+ * including `clear`, `flush`, `reset`, and `enable`, in addition to
+ * recorded events. Intended for React hooks that need to re-render
+ * on snapshot changes; event sinks should use `subscribe()` instead.
+ *
+ * Returns an unsubscribe callback.
+ */
+export declare function subscribeToConversationArcChange(listener: () => void): () => void;
+/**
+ * Register an opt-in persistence sink. Sinks receive only accepted events:
+ * disabled telemetry remains a no-op and replay hydration does not re-emit
+ * historical events into durable stores.
+ */
+export declare function registerConversationArcSink(sink: ConversationArcSink): () => void;
+/**
+ * Browser-local durable sink backed by `localStorage`. It appends each accepted
+ * event to a JSON array and exposes `load()` so a session can be replayed later.
+ * When `localStorage` is unavailable (SSR, private browser failures), operations
+ * degrade to no-ops and `load()` returns `[]`.
+ */
+export declare function createLocalStorageConversationArcSink(options?: LocalStorageConversationArcSinkOptions): ConversationArcSink & {
+    load(): ConversationArcEvent[];
+};
+/**
+ * Browser durable sink backed by IndexedDB. Writes are asynchronous and
+ * fire-and-forget from the recorder; callers that need replay can await
+ * `sink.load()`.
+ */
+export declare function createIndexedDBConversationArcSink(options?: IndexedDBConversationArcSinkOptions): ConversationArcSink & {
+    load(): Promise<ConversationArcEvent[]>;
+};
+/**
+ * Minimal webhook sink for app-owned analytics ingestion. The sink posts one
+ * JSON payload per accepted event; retry, batching, authentication refresh, and
+ * sampling policy remain application concerns.
+ */
+export declare function createWebhookConversationArcSink(options: WebhookConversationArcSinkOptions): ConversationArcSink;
+/**
+ * Hydrate the in-memory store from a saved arc without replaying side effects.
+ * The loaded events become visible through `getEvents()` / `useConversationArc`,
+ * but listeners and sinks are not called. Pass `{ enabled: true }` when you want
+ * to resume recording after loading; the default is replay-only.
+ */
+export declare function loadConversationArc(events: ReadonlyArray<ConversationArcEvent>, options?: LoadConversationArcOptions): ReadonlyArray<ConversationArcEvent>;
+/** Alias with the word replay for fixture-driven callers. */
+export declare function replayConversationArc(events: ReadonlyArray<ConversationArcEvent>, options?: LoadConversationArcOptions): ReadonlyArray<ConversationArcEvent>;
+/**
+ * Record an audience-set event. Convenience wrapper around `record`
+ * for the common pattern: "the user picked a new audience profile
+ * and I want to put that in the arc."
+ *
+ * `previous` is optional but recommended — it lets downstream
+ * analytics see the transition rather than just the new state. Pass
+ * `null` when there was no prior audience.
+ *
+ * Returns the stamped event, or `null` if recording is disabled.
+ *
+ * ```ts
+ * import { recordAudienceChange } from "semiotic/ai"
+ *
+ * function AudiencePicker({ value, onChange }) {
+ *   return (
+ *     <select value={value} onChange={(e) => {
+ *       const next = e.target.value
+ *       recordAudienceChange(next, value)
+ *       onChange(next)
+ *     }} />
+ *   )
+ * }
+ * ```
+ */
+export declare function recordAudienceChange(audience: string, previous?: string | null, extra?: {
+    arcId?: string;
+    meta?: Record<string, unknown>;
+}): ConversationArcEvent | null;
+/**
+ * Sugar for an `annotation-status-changed` event (M7). Call it from the
+ * accept / dispute / retract / propose UI so the arc records how an
+ * annotation's editorial standing moved — the durable, observable node of the
+ * conversation. No-op (returns null) until `enableConversationArc()`.
+ */
+export declare function recordAnnotationStatusChange(toStatus: AnnotationStatus, opts?: {
+    annotationId?: string;
+    fromStatus?: AnnotationStatus;
+    chartId?: string;
+    arcId?: string;
+    meta?: Record<string, unknown>;
+}): ConversationArcEvent | null;
+/**
+ * Opt in to conversation-arc telemetry. Safe to call multiple times —
+ * subsequent calls reuse the existing session unless `sessionId` is
+ * explicitly provided.
+ */
+export declare function enableConversationArc(options?: EnableConversationArcOptions): ConversationArcStore;
+/** Turn the store off without dropping the buffered events. */
+export declare function disableConversationArc(): void;
+/**
+ * Always returns a store façade. Methods are safe to call when
+ * disabled — `record()` returns null, `getEvents()`/`flush()` return
+ * empty arrays, `subscribe()` returns a no-op unsubscriber.
+ */
+export declare function getConversationArcStore(): ConversationArcStore;
+export {};