semiotic 3.6.0 → 3.7.1

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` (86KB gz), `semiotic/ordinal` (70KB gz), `semiotic/network` (64KB gz), `semiotic/geo` (52KB gz), `semiotic/realtime` (91KB gz), `semiotic/server` (122KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (211KB gz). Full `semiotic` is 190KB 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` (128KB gz), `semiotic/utils` (38KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (250KB 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:
@@ -137,7 +140,7 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 
 ## Key Patterns
 - **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
-- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
+- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderChartWithEvidence()` returns `{ svg, evidence }` (mark counts by scene type, axis domains, empty flag, annotation count, accessible name) so agents can verify the render drew data marks. `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
 - **CLI**: `npx semiotic-ai --list` shows components/import paths/renderability; `npx semiotic-ai --schema GaugeChart` prints one component schema with metadata; `--doctor` validates props JSON and behavior contracts.
-- **MCP**: `npx semiotic-mcp` exposes tools (`getSchema`, `suggestChart`, `diagnoseConfig`, `renderChart`, `applyTheme`, `reportIssue`), resources (`semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`), and prompts (`build-semiotic-chart`, `debug-semiotic-chart`).
+- **MCP**: `npx semiotic-mcp` exposes schema, suggestion, diagnosis, accessibility, grounding, issue, theme, static render (`renderChart`), and ChatGPT Apps render (`renderInteractiveChart`) tools. Resources include `semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`, and the widget template `ui://semiotic/chart-widget.html`. Prompts: `build-semiotic-chart`, `debug-semiotic-chart`.
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/components/AccessibleNavTree.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+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): React.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 default function SemioticAnnotation(props: AnnotationProps): React.JSX.Element;
+export {};

package/dist/components/CategoryColors.d.ts

@@ -37,7 +37,7 @@ export interface CategoryColorProviderProps {
  * </CategoryColorProvider>
  * ```
  */
-export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
 export declare namespace CategoryColorProvider {
     var displayName: string;
 }

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/ChartGrid.d.ts

@@ -33,7 +33,7 @@ export interface ChartGridProps {
  * </ChartGrid>
  * ```
  */
-export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
 export declare namespace ChartGrid {
     var displayName: string;
 }

package/dist/components/ContextLayout.d.ts

@@ -32,7 +32,7 @@ export interface ContextLayoutProps {
  * </ContextLayout>
  * ```
  */
-export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): import("react/jsx-runtime").JSX.Element;
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
 export declare namespace ContextLayout {
     var displayName: string;
 }

package/dist/components/DataSummaryContext.d.ts

@@ -6,7 +6,7 @@ interface DataSummaryState {
 }
 export declare function DataSummaryProvider({ children }: {
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export declare function useDataSummary(): DataSummaryState | null;
 export declare function useDataSummaryToggle(): (() => void) | null;
 export {};

package/dist/components/DetailsPanel.d.ts

@@ -32,7 +32,7 @@ export interface DetailsPanelProps {
     /** Inline style overrides */
     style?: React.CSSProperties;
 }
-export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): React.JSX.Element | null;
 export declare namespace DetailsPanel {
     var displayName: string;
 }

package/dist/components/Legend.d.ts

@@ -1,8 +1,9 @@
+import * as React from "react";
 import { LegendProps, GradientLegendConfig } from "./types/legendTypes";
 /** Gradient legend for continuous/sequential color scales */
 export declare function GradientLegend({ config, orientation, width, }: {
     config: GradientLegendConfig;
     orientation?: "vertical" | "horizontal";
     width?: number;
-}): import("react/jsx-runtime").JSX.Element;
-export default function Legend(props: LegendProps): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
+export default function Legend(props: LegendProps): React.JSX.Element;

package/dist/components/LinkedCharts.d.ts

@@ -86,4 +86,4 @@ export declare function estimateLegendRowCount(labels: string[], width: number):
  * </LinkedCharts>
  * ```
  */
-export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): import("react/jsx-runtime").JSX.Element;
+export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): React.JSX.Element;

package/dist/components/ThemeProvider.d.ts

@@ -7,7 +7,7 @@ interface ThemeProviderProps {
     theme?: ThemePresetName | SemioticThemeUpdate;
     children: React.ReactNode;
 }
-declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): React.JSX.Element;
 declare function useTheme(): SemioticTheme;
 export { ThemeProviderWrapper as ThemeProvider, useTheme };
 export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME };

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -45,5 +45,5 @@ interface FlippingTooltipProps {
  *     guard, React throws `'NaN' is an invalid value for the 'top' css
  *     style property` and the entire frame stops rendering.
  */
-export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): React.JSX.Element | null;
 export {};

package/dist/components/Tooltip/Tooltip.d.ts

@@ -88,7 +88,7 @@ export declare const defaultTooltipStyle: React.CSSProperties;
  * />
  * ```
  */
-export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
+export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Create a multi-line tooltip that displays multiple fields
  *
@@ -131,7 +131,7 @@ export declare function Tooltip(config?: TooltipConfig): (data: Record<string, u
  * />
  * ```
  */
-export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
+export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Type for tooltip prop that chart components accept
  */

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>[];