semiotic 3.5.4 → 3.7.0

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-**Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (69KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (189KB gz). Full `semiotic` is 188KB gz.
+**Use sub-path imports** — `semiotic/xy` (90KB gz), `semiotic/ordinal` (74KB gz), `semiotic/network` (68KB gz), `semiotic/geo` (55KB gz), `semiotic/realtime` (95KB gz), `semiotic/server` (127KB gz), `semiotic/utils` (37KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (246KB gz). Full `semiotic` is 203KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
@@ -84,12 +84,15 @@ Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selecti
 ### emphasis
 `emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
 
-## Annotations (XY and ordinal charts)
+## Annotations (all chart families)
 - `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050", labelPosition: "right" }]}` — horizontal reference line (works on XY and vertical ordinal charts). `labelPosition`: "left"|"center"|"right"
 - `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff", labelPosition: "top" }]}` — vertical reference line. `labelPosition`: "top"|"center"|"bottom"
+- `annotations={[{ type: "callout-circle", x: 5, y: 20, label: "Peak", radius: 12 }]}` — data-bound callout; use `callout-rect` with `width`/`height` for a rectangular subject
 - `annotations={[{ type: "category-highlight", category: "Q3 2024", color: "#4589ff", opacity: 0.15 }]}` — highlight a category column/row in ordinal charts
 - `annotations={[{ type: "widget", time: 42, latency: 850, dy: -10, content: <span>Alert</span> }]}` — place React element at data coordinates
 - `annotations={[{ type: "enclose", coordinates: [datum1, datum2], label: "Cluster" }]}` — circle enclosing data points
+- `autoPlaceAnnotations={{ density: true, progressiveDisclosure: true, redundantCues: true }}` — opt-in placement, clutter management, and non-color association support
+- Annotation metadata: `emphasis`, `defensive`, `provenance`, and `lifecycle`; use `applyAnnotationLifecycle`, `applyAnnotationStatus`, and `filterAnnotationsByStatus` from `semiotic/ai`
 
 ## Theming & Brand Styling
 All charts respond to CSS custom properties on any ancestor:

package/dist/components/AccessibleNavTree.d.ts

@@ -0,0 +1,25 @@
+import { type NavTreeNode } from "./ai/navigationTree";
+export interface AccessibleNavTreeProps {
+    tree: NavTreeNode;
+    /** Accessible name for the tree. */
+    label?: string;
+    /** Show the tree visibly (default: screen-reader-only). */
+    visible?: boolean;
+    className?: string;
+    /** Fired when the active node changes (e.g. to highlight the matching mark). */
+    onActiveChange?: (node: NavTreeNode) => void;
+    /**
+     * Controlled active node id. When provided, the parent owns the active node
+     * (e.g. `useNavigationSync` driving it from the chart's hover). The tree
+     * auto-expands the path to a controlled active node so it stays visible.
+     */
+    activeId?: string;
+    /**
+     * `chartId` of the chart this tree describes. Correlates the reception
+     * telemetry the tree emits (`nav-node-focused` / `nav-branch-expanded`
+     * conversation-arc events) back to the chart. Events are only recorded while
+     * the conversation-arc store is enabled — zero-overhead otherwise.
+     */
+    chartId?: string;
+}
+export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId }: AccessibleNavTreeProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Annotation.d.ts

@@ -1,11 +1,41 @@
 import * as React from "react";
+type AnnotationEventHandlers = Record<string, (e: React.SyntheticEvent) => void>;
+type AnnotationNote = {
+    label?: string;
+    title?: string;
+    wrap?: number;
+    orientation?: string;
+    align?: string;
+    noWrap?: boolean;
+};
+type AnnotationConnector = {
+    end?: "arrow";
+    type?: "line" | "curve";
+    curve?: number;
+};
+type AnnotationSubject = {
+    radius?: number;
+    radiusPadding?: number;
+    width?: number;
+    height?: number;
+    custom?: React.ReactElement | React.ReactElement[];
+    x?: number;
+    y?: number;
+    x1?: number;
+    x2?: number;
+    y1?: number;
+    y2?: number;
+    type?: string;
+    depth?: number;
+    [key: string]: unknown;
+};
 /** Props for the single-annotation renderer. Consumed only by `SemioticAnnotation`
  *  below; the broader annotation API flows through the frame-level `annotations`
  *  array and its `svgAnnotationRules` hook. */
 export interface AnnotationProps {
     noteData: {
-        eventListeners?: Record<string, (e: React.SyntheticEvent) => void>;
-        events?: Record<string, (e: React.SyntheticEvent) => void>;
+        eventListeners?: AnnotationEventHandlers;
+        events?: AnnotationEventHandlers;
         type: string;
         screenCoordinates?: number[][];
         /** When truthy, `screenCoordinates` is read as a sequence of anchor points
@@ -19,25 +49,21 @@ export interface AnnotationProps {
         ny?: number;
         dx?: number;
         dy?: number;
-        note: {
-            label?: string;
-            title?: string;
-            wrap?: number;
-            orientation?: string;
-            align?: string;
-            noWrap?: boolean;
-        };
+        note: AnnotationNote;
         i?: number;
         fixedPosition?: boolean;
         label?: string;
-        connector?: {
-            end?: "arrow";
-        };
-        subject?: Record<string, unknown>;
+        connector?: AnnotationConnector;
+        subject?: AnnotationSubject;
         color?: string;
         className?: string;
         disable?: string[];
+        /** SVG opacity cascaded to every stroked/filled child of the annotation. */
+        opacity?: number;
+        /** SVG stroke-dasharray cascaded to every stroked child of the annotation. */
+        strokeDasharray?: string;
         [key: string]: unknown;
     };
 }
 export default function SemioticAnnotation(props: AnnotationProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChartContainer.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { ChartConfig, CopyFormat } from "./export/chartConfig";
+import { type DescribeLevel } from "./ai/describeChart";
 export interface ChartContainerProps {
     /** Chart title */
     title?: string;
@@ -26,8 +27,37 @@ export interface ChartContainerProps {
         /** Enable "Data Summary" action button — shows statistical summary + sample rows */
         dataSummary?: boolean;
     };
-    /** Chart configuration for serialization. Enables the "Copy Config" toolbar action. */
-    chartConfig?: ChartConfig;
+    /**
+     * Chart configuration. Enables the "Copy Config" toolbar action and the
+     * `describe`/`navigable` a11y affordances. Only `component` and `props` are
+     * required — the `version`/`createdAt` serialization metadata is optional
+     * here and synthesized when copying.
+     */
+    chartConfig?: Omit<ChartConfig, "version" | "createdAt"> & Partial<Pick<ChartConfig, "version" | "createdAt">>;
+    /**
+     * Auto-generate a layered (L1–L3) natural-language description from
+     * `chartConfig` and expose it at the container level — the opt-in path to a
+     * fuller accessible reading than the bare chart's terse aria-label. Requires
+     * `chartConfig`. `true` renders a screen-reader-only note; pass
+     * `{ visible: true }` to also show it as a visible caption, or `{ levels }`
+     * to choose verbosity. Backed by `describeChart()`.
+     */
+    describe?: boolean | {
+        levels?: DescribeLevel[];
+        visible?: boolean;
+    };
+    /**
+     * Mount a structured, screen-reader-navigable tree of the chart (chart →
+     * axes/series → data points), built from `chartConfig` — the Olli /
+     * Data Navigator model, as an opt-in at the container layer. Requires
+     * `chartConfig`. `true` renders it screen-reader-only; `{ visible: true }`
+     * shows it; `{ maxLeaves }` caps leaves per branch. Backed by
+     * `buildNavigationTree()` + `AccessibleNavTree`.
+     */
+    navigable?: boolean | {
+        visible?: boolean;
+        maxLeaves?: number;
+    };
     /** Additional controls rendered in the toolbar after built-in actions */
     controls?: React.ReactNode;
     /** Loading state — shows skeleton placeholder */

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

@@ -0,0 +1,349 @@
+/**
+ * Where an annotation came from and how confident we should be in it.
+ * Lives on `annotation.provenance`.
+ */
+export interface AnnotationProvenance {
+    /**
+     * Display name (or stable id) for who created the annotation — a
+     * person, agent, or watcher. Together with `authorKind` this expresses
+     * IDID §8's structured `author: { kind, id }`: `authorKind` is the
+     * actor category, `author` is the name/id.
+     */
+    author?: string;
+    /**
+     * Actor category — *who* created the annotation. IDID §8's
+     * `author.kind`. Distinct from `basis` (*how* it was derived) and from
+     * the coarser `source`. Open union; consumers may extend.
+     */
+    authorKind?: AnnotationActorKind;
+    /**
+     * Origin category. Recognized values are not exhaustive; consumers
+     * may extend with their own source labels. Coarser than the
+     * `authorKind` / `basis` pair — kept for back-compat and as a single
+     * convenience label when the finer split isn't needed.
+     */
+    source?: AnnotationSource;
+    /**
+     * Evidence type — *how* the annotation's claim was derived
+     * (a hand note, a statistical test, a rule, an LLM inference, an
+     * external source). IDID §8's `basis`. Distinct from `authorKind`
+     * (the actor) and `source` (the coarse origin): a `"human"` author can
+     * relay a `"statistical-test"` basis. Lets a reader weight a note by
+     * the strength of its evidence, not just who left it.
+     */
+    basis?: AnnotationBasis;
+    /**
+     * Confidence in the assertion, 0–1. `1` is a hand-placed user
+     * annotation; LLM-suggested annotations typically land below 0.8.
+     */
+    confidence?: number;
+    /** ISO 8601 timestamp marking when the annotation was created. */
+    createdAt?: string;
+    /**
+     * Identifier of the data snapshot the annotation was made against
+     * (IDID §8's `dataVersion`). Lets a consumer tell "this note was
+     * written about last week's data" from "this note still tracks the
+     * current data," independent of wall-clock freshness.
+     */
+    dataVersion?: string;
+    /**
+     * Stable, opaque identifier that survives data refresh and chart
+     * recreation. Used by the `"semantic"` anchor-resolution work to
+     * re-locate "the Q3 spike" after new data arrives, and as the target
+     * of another annotation's `lifecycle.supersedes`.
+     */
+    stableId?: string;
+}
+/**
+ * Actor category for an annotation — *who* created it. IDID §8 models
+ * this as `author.kind`. Open string union: `"system"` covers
+ * non-watcher automated placement, and consumers may pass any other
+ * label (it is preserved).
+ */
+export type AnnotationActorKind = "human" | "agent" | "watcher" | "system" | (string & {});
+/**
+ * Evidence type for an annotation — *how* its claim was derived. IDID
+ * §8's `basis`. Open string union so consumers can add evidence kinds
+ * (e.g. `"forecast"`, `"manual-review"`) without a type change.
+ */
+export type AnnotationBasis = "human-note" | "statistical-test" | "rule" | "llm-inference" | "external-source" | "computed" | (string & {});
+/**
+ * Recognized provenance sources. Open string union — consumers may
+ * pass any other label and it will be preserved.
+ */
+export type AnnotationSource = "user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {});
+/**
+ * How an annotation ages relative to the chart's current data extent.
+ * Default visual treatment (defined in M2): `aging` dims, `stale`
+ * draws a dashed border, `expired` is hidden unless
+ * `showExpiredAnnotations` is on.
+ */
+export type AnnotationFreshness = LifecycleBand;
+import type { AnnotationAnchor } from "../realtime/types";
+export type { AnnotationAnchor } from "../realtime/types";
+import type { LifecycleBand, LifecycleBandThresholds } from "../realtime/lifecycleBands";
+export { bandFromAge, DEFAULT_LIFECYCLE_THRESHOLDS } from "../realtime/lifecycleBands";
+export type { LifecycleBand, LifecycleBandThresholds } from "../realtime/lifecycleBands";
+/**
+ * Editorial standing of an annotation in a multiplayer conversation —
+ * is the note still believed? IDID §8's `status`. Orthogonal to the
+ * temporal `freshness` band: a note can be fresh-but-`disputed` or
+ * stale-but-`accepted`. Closed union — these four are the editorial
+ * state machine the editorial-lifecycle work drives:
+ *
+ * - `"proposed"` — placed but unreviewed (e.g. a watcher's auto-note).
+ * - `"accepted"` — confirmed by a human or agent.
+ * - `"disputed"` — contested; under review.
+ * - `"retracted"` — withdrawn; treat like an expired note.
+ */
+export type AnnotationStatus = "proposed" | "accepted" | "disputed" | "retracted";
+/**
+ * Lifecycle state for an annotation. Lives on `annotation.lifecycle`.
+ *
+ * Two orthogonal axes: the **temporal** band (`freshness`, derived from
+ * `createdAt` + `ttlHint`) and the **editorial** state (`status`,
+ * driven by the multiplayer accept/dispute/retract flow). `supersedes`
+ * links a revision to the note it replaces.
+ */
+export interface AnnotationLifecycle {
+    /**
+     * Current freshness band. When omitted, `computeAnnotationFreshness`
+     * derives it from `ttlHint` and the data's current temporal extent.
+     */
+    freshness?: AnnotationFreshness;
+    /**
+     * Editorial standing (IDID §8's `status`). Set by the multiplayer
+     * accept/dispute/retract flow; orthogonal to `freshness`. When
+     * omitted, the annotation is treated as unconditionally shown (the
+     * pre-editorial-lifecycle behavior). Status-driven visual treatment
+     * is owed alongside the editorial-lifecycle work — the field ships
+     * first so it can be stamped now.
+     */
+    status?: AnnotationStatus;
+    /**
+     * `provenance.stableId` of the annotation this one replaces (IDID
+     * §8's `supersedes`). Forms a revision chain so a reader can trace how
+     * an interpretation changed; the superseded note is typically hidden
+     * once its replacement is `accepted`.
+     */
+    supersedes?: string;
+    /**
+     * How long this annotation should be considered fresh. Either an
+     * ISO 8601 duration string (`"PT24H"`, `"P7D"`) or a number of
+     * milliseconds. The freshness computation walks `fresh → aging
+     * → stale → expired` as the chart's "now" advances past
+     * `createdAt + ttlHint`.
+     */
+    ttlHint?: string | number;
+    /** Anchor resolution strategy. Defaults to `"fixed"` when omitted. */
+    anchor?: AnnotationAnchor;
+}
+/**
+ * Carries the new optional blocks onto whatever annotation type the
+ * chart accepts. Use as `Annotated<typeof myAnnotation>` for explicit
+ * typing, or call `withProvenance()` for inline authoring.
+ */
+export type Annotated<T> = T & {
+    provenance?: AnnotationProvenance;
+    lifecycle?: AnnotationLifecycle;
+};
+/**
+ * Convenience builder — attaches provenance + lifecycle blocks to an
+ * annotation without disturbing its existing fields. Returns a new
+ * object; does not mutate. Pure function, safe to call in SSR.
+ *
+ * ```ts
+ * withProvenance(
+ *   { type: "y-threshold", value: 100, label: "SLA breach" },
+ *   {
+ *     provenance: { author: "alice", source: "user", createdAt: "2026-05-20T14:00:00Z" },
+ *     lifecycle: { ttlHint: "P30D", anchor: "semantic" },
+ *   }
+ * )
+ * ```
+ */
+export declare function withProvenance<T extends object>(annotation: T, blocks: {
+    provenance?: AnnotationProvenance;
+    lifecycle?: AnnotationLifecycle;
+}): Annotated<T>;
+/**
+ * Returns an ISO 8601 wall-clock timestamp suitable for stamping
+ * `provenance.createdAt`. Sugar over `new Date().toISOString()`, but
+ * named to make intent obvious in streaming consumers: "mark this
+ * annotation as created now, so the lifecycle helpers can age it."
+ *
+ * Pair with `applyAnnotationLifecycle({ dataExtent })` on time-series
+ * charts to have annotations age against chart-time rather than
+ * wall-clock — the chart's latest data point becomes the "now"
+ * reference, and recently-stamped annotations stay fresh for as long
+ * as new data is flowing.
+ */
+export declare function currentTimestamp(): string;
+/**
+ * Stamp an annotation with `provenance.createdAt = currentTimestamp()`
+ * (unless it already has a `createdAt`) and optional additional
+ * provenance fields. Intended for the streaming "I'm marking the
+ * latest data point" pattern, where the annotation's age should be
+ * measured from when the consumer added it.
+ *
+ * Equivalent to:
+ *   ```ts
+ *   withProvenance(ann, {
+ *     provenance: { createdAt: currentTimestamp(), ...rest },
+ *     lifecycle: ann.lifecycle,
+ *   })
+ *   ```
+ * — but reads cleaner at call sites and preserves any existing
+ * `createdAt`.
+ */
+export declare function withCurrentProvenance<T extends object>(annotation: T, rest?: Omit<AnnotationProvenance, "createdAt"> & {
+    createdAt?: string;
+}): Annotated<T>;
+/**
+ * Options accepted by `computeAnnotationFreshness` and
+ * `applyAnnotationLifecycle`.
+ */
+export interface ComputeAnnotationFreshnessOptions {
+    /**
+     * "Now" reference for age calculations. Number is epoch ms; string is
+     * any value `Date.parse` accepts. When omitted, defaults to the max
+     * of `dataExtent`, falling back to `Date.now()`.
+     */
+    now?: number | Date | string;
+    /**
+     * The chart's current temporal extent — typically `[oldest, newest]`
+     * x values. Used to derive a sensible "now" for streaming charts
+     * (where wall-clock time and the data's notion of "now" can drift).
+     */
+    dataExtent?: ReadonlyArray<number | Date | string> | {
+        min: number | Date | string;
+        max: number | Date | string;
+    };
+    /**
+     * Override the default age thresholds. Each value is a multiplier of
+     * `ttlHint`. Defaults: aging at 1×, stale at 1.5×, expired at 3×.
+     * Same shape as `LifecycleBandThresholds` from the shared primitive.
+     */
+    thresholds?: LifecycleBandThresholds;
+}
+/**
+ * Classify an annotation into a freshness band. Exported for tests and
+ * for consumers that want the per-annotation band without rebuilding
+ * the entire array.
+ *
+ * Returns the annotation's existing `lifecycle.freshness` verbatim if
+ * the annotation lacks the `createdAt` or `ttlHint` needed to compute
+ * a band — i.e. an explicit assignment always wins over inference.
+ */
+export declare function annotationFreshnessFor<T>(annotation: Annotated<T>, nowMs: number, thresholds?: LifecycleBandThresholds): AnnotationFreshness;
+/**
+ * Walk an annotations array and populate `lifecycle.freshness` on each
+ * entry from its `provenance.createdAt` and `lifecycle.ttlHint`.
+ *
+ * Pure function — returns a new array; does not mutate input. Safe
+ * to call in SSR. Annotations missing the inputs needed to compute a
+ * band keep whatever `lifecycle.freshness` they already had (so an
+ * explicit assignment always wins).
+ *
+ * For non-temporal charts, pass `now` explicitly. For streaming /
+ * time-series charts, pass `dataExtent` — the helper picks the latest
+ * value as "now" so freshness tracks chart-time, not wall-clock.
+ */
+export declare function computeAnnotationFreshness<T>(annotations: ReadonlyArray<Annotated<T>>, options?: ComputeAnnotationFreshnessOptions): Annotated<T>[];
+/**
+ * Style overrides per freshness band. Each map is partial — bands not
+ * present fall back to the defaults below. `null` for a value removes
+ * the default rather than applying it (e.g. `{ opacity: { aging: null } }`
+ * disables dimming aging annotations).
+ */
+export interface AnnotationLifecycleTreatment {
+    opacity?: Partial<Record<AnnotationFreshness, number | null>>;
+    strokeDasharray?: Partial<Record<AnnotationFreshness, string | null>>;
+    /** Suffix appended to `label` for that band. Default suffixes are off. */
+    labelSuffix?: Partial<Record<AnnotationFreshness, string>>;
+    /**
+     * When true, expired annotations stay in the returned array (with
+     * the expired treatment applied). When false (default), expired
+     * annotations are filtered out — matching the "hidden by default"
+     * contract from the talk-readiness roadmap.
+     */
+    showExpiredAnnotations?: boolean;
+}
+export type ApplyAnnotationLifecycleOptions = ComputeAnnotationFreshnessOptions & AnnotationLifecycleTreatment;
+/**
+ * Compute freshness and apply the default visual treatment in one pass.
+ *
+ * Behavior per band (overridable via options):
+ * - **fresh** — no change
+ * - **aging** — `opacity` 0.55
+ * - **stale** — `opacity` 0.35, `strokeDasharray` `"4 4"` (cascades
+ *   through the annotation's stroked children)
+ * - **expired** — filtered out by default; pass
+ *   `showExpiredAnnotations: true` to keep them with `opacity` 0.2 and
+ *   `strokeDasharray` `"2 4"`
+ *
+ * Treatment composes cleanly with annotations that already carry their
+ * own `color` / `opacity` — explicit fields on the annotation win,
+ * the treatment only fills in what isn't already set.
+ */
+export declare function applyAnnotationLifecycle<T>(annotations: ReadonlyArray<Annotated<T>>, options?: ApplyAnnotationLifecycleOptions): Annotated<T>[];
+/**
+ * Style overrides per editorial status. Each map is partial — statuses not
+ * present fall back to the defaults below. `null` for a value removes the
+ * default rather than applying it.
+ */
+export interface AnnotationStatusVisibility {
+    /**
+     * Keep `retracted` annotations instead of filtering them out. Default false
+     * — retracted is hidden like `expired`.
+     */
+    showRetractedAnnotations?: boolean;
+    /**
+     * Keep an annotation that another *present* note supersedes. Default false
+     * — a superseded note is hidden once its replacement is in the array.
+     */
+    showSupersededAnnotations?: boolean;
+}
+export interface AnnotationStatusTreatment extends AnnotationStatusVisibility {
+    /**
+     * Opacity *factor* per status, multiplied into any existing opacity so it
+     * composes with the freshness treatment (run `applyAnnotationLifecycle`
+     * first, then this). `null` disables the factor for that status.
+     */
+    opacity?: Partial<Record<AnnotationStatus, number | null>>;
+    strokeDasharray?: Partial<Record<AnnotationStatus, string | null>>;
+    /**
+     * Suffix appended to a string `label` for that status — the `disputed`
+     * default `" (?)"` is the query affordance the strategy calls for.
+     */
+    labelSuffix?: Partial<Record<AnnotationStatus, string>>;
+}
+/**
+ * Apply the default editorial visibility contract without changing annotation
+ * styling. Retracted notes and notes replaced by a present revision are hidden
+ * unless explicitly requested. Shared by visual treatment, chart descriptions,
+ * and navigation trees so they expose the same current set.
+ */
+export declare function filterAnnotationsByStatus<T>(annotations: ReadonlyArray<Annotated<T>>, options?: AnnotationStatusVisibility): Annotated<T>[];
+/**
+ * Apply the editorial-status visual treatment (M7) — the orthogonal companion
+ * to {@link applyAnnotationLifecycle}'s temporal-freshness treatment. The two
+ * compose (a note can be stale-and-disputed); run freshness first, then this.
+ *
+ * Per status (overridable via options):
+ * - **accepted** — no change (full weight).
+ * - **proposed** — `opacity` ×0.7, dashed `"3 3"`, `label` suffix `" (proposed)"`.
+ *   An unreviewed (e.g. watcher) note reads provisionally.
+ * - **disputed** — `opacity` ×0.7, dashed `"2 3"`, `label` suffix `" (?)"`.
+ *   The suffix is the query affordance: a contested note announces itself.
+ * - **retracted** — filtered out by default (like `expired`); pass
+ *   `showRetractedAnnotations: true` to keep it at `opacity` ×0.25.
+ *
+ * Also resolves **supersession**: a note whose `provenance.stableId` is the
+ * `lifecycle.supersedes` target of another *present, non-retracted* note is
+ * hidden (the revision replaced it), unless `showSupersededAnnotations` is set.
+ *
+ * Pure — returns a new array; safe in SSR. Opacity is multiplied into any
+ * existing value, so it composes with freshness dimming and author-set opacity.
+ */
+export declare function applyAnnotationStatus<T>(annotations: ReadonlyArray<Annotated<T>>, options?: AnnotationStatusTreatment): Annotated<T>[];

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

@@ -0,0 +1,147 @@
+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.
+ *
+ * Semiotic does not measure familiarity — it consumes measurements. Orgs
+ * produce an AudienceProfile through whatever channel makes sense (surveys,
+ * 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.
+ */
+export interface AudienceProfile {
+    /**
+     * Display name. Surfaced in suggestion `reasons[]` when a target fires so
+     * users can see whose policy is influencing the ranking.
+     */
+    name?: string;
+    /**
+     * Per-chart familiarity override (1..5). Replaces the descriptor's
+     * `rubric.familiarity`. Charts not listed fall back to the descriptor.
+     *
+     * @example
+     * familiarity: { BarChart: 5, LineChart: 5, PieChart: 4, BoxPlot: 2 }
+     */
+    familiarity?: Partial<Record<string, number>>;
+    /**
+     * Adoption targets — which charts the org is trying to grow or reduce.
+     * The engine applies a meaningful score bias (±1..3 depending on weight)
+     * so growth targets win close calls and decrease targets fall back unless
+     * they're the only fit.
+     *
+     * @example
+     * targets: {
+     *   PieChart: { direction: "decrease", weight: 1 },
+     *   BoxPlot:  { direction: "increase", weight: 2,
+     *               reason: "we want the team reading distributions, not means" }
+     * }
+     */
+    targets?: Partial<Record<string, AudienceTarget>>;
+    /**
+     * Controls visibility of stretch picks (unfamiliar-but-relevant charts).
+     *   0 — never surface stretches; familiar-only rankings
+     *   1 — surface in a separate `stretchSuggestions` list (default when audience set)
+     *   2 — same as 1 but lowers the familiarity threshold (≤4) for what counts as stretch,
+     *       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";
+    /** 1..3 — controls bias magnitude. Default 1. */
+    weight?: number;
+    /** Human-readable rationale. Surfaces in suggestion.reasons when the target fires. */
+    reason?: string;
+}
+export interface AudienceBiasResult {
+    /** Composite score after audience adjustments. Unclamped — can range outside 0..5. */
+    score: number;
+    /** Effective rubric for the chart after audience overrides. */
+    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`.
+ *
+ * Two terms compose additively:
+ *   • Familiarity bias: (audienceFamiliarity − 3) × 0.5
+ *     — Range ±1.0. At familiarity 5 we add 1.0; at 1 we subtract 1.0.
+ *   • Target bias: ±1.0 × weight
+ *     — Range ±3.0 for weight=3. Strong enough to reorder rankings,
+ *       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, 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."
+ */
+export declare function effectiveFamiliarity(component: string, defaultFamiliarity: number, audience: AudienceProfile | undefined): number;
+/**
+ * Familiarity threshold for what counts as a "stretch" pick under this audience.
+ * Tighter for exposureLevel 1, wider for 2. Returns the highest familiarity a
+ * chart can have and still appear in the stretch surface.
+ */
+export declare function stretchFamiliarityCeiling(audience: AudienceProfile | undefined): number;