semiotic 3.7.4 → 3.8.0

package/dist/components/data/portability/result.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared result vocabulary for experimental portability adapters.
+ *
+ * An adapter must make a supported translation, a known loss, and a refusal
+ * distinguishable to callers. Warnings attached to an otherwise plausible
+ * chart are not sufficient: another renderer cannot infer that it should not
+ * render an approximation.
+ */
+/** Whether an adapter translated exactly, translated with declared loss, or refused. */
+export type PortabilityStatus = "success" | "lossy" | "refused";
+export type PortabilityDiagnosticSeverity = "warning" | "error";
+/** A stable, machine-readable adapter diagnostic. */
+export interface PortabilityDiagnostic {
+    code: string;
+    severity: PortabilityDiagnosticSeverity;
+    message: string;
+    path?: string;
+}
+/** A declared semantic loss for an explicitly lossy translation. */
+export interface PortabilityLoss {
+    code: string;
+    message: string;
+    path?: string;
+}
+/**
+ * Enough information to identify an adapter operation without coupling this
+ * library-neutral result shape to a particular renderer or chart config.
+ */
+export interface PortabilityProvenance {
+    adapter: string;
+    direction: "import" | "export";
+    sourceFormat: string;
+    targetFormat: string;
+    specVersion?: string;
+    /** Metadata that travelled with the source artifact, when it is serializable. */
+    metadata?: Record<string, unknown>;
+}
+/** Base result shared by adapters that import and export different artifact types. */
+export interface PortabilityResult {
+    status: PortabilityStatus;
+    diagnostics: readonly PortabilityDiagnostic[];
+    lossReport: readonly PortabilityLoss[];
+    provenance: PortabilityProvenance;
+}
+/** Result shape for adapters that produce a Semiotic configuration. */
+export interface PortabilityImportResult<TConfig> extends PortabilityResult {
+    config?: TConfig;
+}
+/** Result shape for adapters that produce a foreign artifact or spec. */
+export interface PortabilityExportResult<TArtifact> extends PortabilityResult {
+    artifact?: TArtifact;
+}

package/dist/components/data/portability/spec.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The IDID portability spec — runtime surface (v0.1).
+ *
+ * The canonical, published artifact is the set of JSON Schemas in `/spec/v0.1`.
+ * This module is the reference implementation's *runtime companion*: portable
+ * TypeScript types that mirror those schemas, plus small dependency-free
+ * structural validators for hosts that don't want to pull in a full JSON-schema
+ * engine (per spec doctrine: zero new core dependencies).
+ *
+ * The schemas are library-neutral — none of these types import from a chart
+ * family. Keeping them pure is what lets the ideas travel into ecosystems that
+ * have no concept of a Semiotic chart.
+ *
+ * Field/type fidelity with the published JSON Schemas is enforced by
+ * `portability.test.ts` (the round-trip gate), so the two cannot drift.
+ */
+/** The spec version this build targets. Matches the `/spec/v0.1` directory. */
+export declare const IDID_SPEC_VERSION = "0.1";
+/** The 13 built-in communicative intents. Hosts may register more (open string). */
+export declare const BUILTIN_INTENT_IDS: readonly ["trend", "compare-series", "compare-categories", "rank", "part-to-whole", "distribution", "correlation", "flow", "hierarchy", "geo", "outlier-detection", "composition-over-time", "change-detection"];
+export type BuiltInIntentId = (typeof BUILTIN_INTENT_IDS)[number];
+/** Any intent id — built-in or host-registered. */
+export type PortableIntentId = BuiltInIntentId | (string & {});
+export interface PortableChartRubric {
+    /** How well-known the chart is to a general audience (1–5). */
+    familiarity: number;
+    /** How faithfully it represents the underlying data (1–5). */
+    accuracy: number;
+    /** How readable individual values are (1–5). */
+    precision: number;
+}
+export interface PortableChartVariant {
+    key: string;
+    label: string;
+    description?: string;
+    intentDeltas?: Partial<Record<PortableIntentId, number>>;
+    rubricDeltas?: Partial<PortableChartRubric>;
+    caveats?: ReadonlyArray<string>;
+    tags?: ReadonlyArray<string>;
+    /** Implementation-specific props; opaque to the spec. */
+    props?: Record<string, unknown>;
+}
+export interface PortableMobileInteractionCapability {
+    primary?: string;
+    alternatives?: ReadonlyArray<string>;
+    hoverFallback?: string;
+    targetSize?: number;
+}
+export interface PortableMobileLabelCapability {
+    strategy?: string;
+    minFontSize?: number;
+}
+export interface PortableMobileCustomCapability {
+    dataBearingSceneNodes?: boolean;
+    stableIds?: boolean;
+    navigationGranularity?: string;
+}
+export interface PortableMobileCapability {
+    strategy?: string;
+    responsive?: boolean;
+    supportsResponsiveLayout?: boolean;
+    breakpoints?: ReadonlyArray<number>;
+    minViewportWidth?: number;
+    maxMarks?: number;
+    maxAnnotations?: number;
+    minimumHitTarget?: number;
+    summary?: boolean | string;
+    interaction?: PortableMobileInteractionCapability;
+    labels?: PortableMobileLabelCapability;
+    custom?: PortableMobileCustomCapability;
+}
+export interface PortableChartCapability {
+    /** Stable chart name (e.g. "BarChart"). */
+    component: string;
+    /** Coarse family — open string ("xy" | "ordinal" | "network" | …). */
+    family?: string;
+    /** Where the implementing library exposes the chart (advisory). */
+    importPath?: string;
+    rubric: PortableChartRubric;
+    /** Per-intent suitability, 0–5. Missing intents default to 0. */
+    intentScores?: Partial<Record<PortableIntentId, number>>;
+    variants?: ReadonlyArray<PortableChartVariant>;
+    /** Static, audience-independent caveats. */
+    caveats?: ReadonlyArray<string>;
+    /** Phone-specific design contract for mobile audits and responsive adapters. */
+    mobile?: PortableMobileCapability;
+    tags?: ReadonlyArray<string>;
+}
+export type PortableReceptionModality = "visual" | "screen-reader" | "sonified" | "agent";
+export interface PortableAudienceTarget {
+    direction: "increase" | "decrease";
+    /** 1–3; default 1. */
+    weight?: number;
+    reason?: string;
+}
+export interface PortableAudienceProfile {
+    name?: string;
+    /** Per-chart familiarity override, 1–5, keyed by component. */
+    familiarity?: Record<string, number>;
+    /** Adoption targets keyed by component. */
+    targets?: Record<string, PortableAudienceTarget>;
+    exposureLevel?: 0 | 1 | 2;
+    receptionModality?: PortableReceptionModality;
+}
+/** Open string — recognized: human | agent | watcher | system. */
+export type PortableAnnotationActorKind = "human" | "agent" | "watcher" | "system" | (string & {});
+/** Open string — recognized: user | ai | agent | import | computed | system. */
+export type PortableAnnotationSource = "user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {});
+/** Open string — recognized: human-note | statistical-test | rule | llm-inference | external-source | computed. */
+export type PortableAnnotationBasis = "human-note" | "statistical-test" | "rule" | "llm-inference" | "external-source" | "computed" | (string & {});
+export interface PortableAnnotationProvenance {
+    author?: string;
+    authorKind?: PortableAnnotationActorKind;
+    source?: PortableAnnotationSource;
+    basis?: PortableAnnotationBasis;
+    /** 0–1. */
+    confidence?: number;
+    /** ISO 8601 timestamp. */
+    createdAt?: string;
+    dataVersion?: string;
+    stableId?: string;
+}
+/** Closed union. */
+export type PortableAnnotationFreshness = "fresh" | "aging" | "stale" | "expired";
+/** Closed union. */
+export type PortableAnnotationStatus = "proposed" | "accepted" | "disputed" | "retracted";
+/** Closed union. */
+export type PortableAnnotationAnchor = "fixed" | "latest" | "sticky" | "semantic";
+export interface PortableAnnotationLifecycle {
+    freshness?: PortableAnnotationFreshness;
+    status?: PortableAnnotationStatus;
+    /** provenance.stableId of the annotation this one replaces. */
+    supersedes?: string;
+    /** ISO 8601 duration string or milliseconds. */
+    ttlHint?: string | number;
+    anchor?: PortableAnnotationAnchor;
+}
+/** Any annotation may carry the two optional blocks. */
+export type PortableAnnotated<T = Record<string, unknown>> = T & {
+    provenance?: PortableAnnotationProvenance;
+    lifecycle?: PortableAnnotationLifecycle;
+};
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Structurally validate a portable chart capability. Dependency-free; mirrors
+ * the required/range constraints in chart-capability.schema.json. Not a full
+ * JSON-Schema validation — for that, run the published schema through ajv.
+ */
+export declare function validatePortableCapability(value: unknown): ValidationResult;
+/** Structurally validate a portable audience profile. */
+export declare function validatePortableAudienceProfile(value: unknown): ValidationResult;
+/**
+ * Structurally validate the provenance + lifecycle blocks on an annotation.
+ * Validates only the two IDID blocks; the rest of the annotation (positional
+ * fields, type, label) is the host's concern.
+ */
+export declare function validatePortableAnnotation(value: unknown): ValidationResult;

package/dist/components/data/portability/vegaLite.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Outbound Vega-Lite + the IDID-over-Vega-Lite binding (v0.1).
+ *
+ * `toVegaLite` is the inverse of `fromVegaLite`: a Semiotic ChartConfig back to
+ * a Vega-Lite spec. Round-tripping through the dominant interchange format —
+ * *with the IDID metadata preserved* — is the portability claim in runnable
+ * form.
+ *
+ * The binding functions (`attachIDID` / `readIDID`, `attachIDIDAnnotations` /
+ * `readIDIDAnnotations`) define WHERE the three portable primitives ride on a
+ * Vega-Lite spec so the spec and its IDID metadata travel together. The
+ * convention is documented in `/spec/README.md`.
+ *
+ * Pure, dependency-free, no chart-family imports.
+ */
+import type { ChartConfig } from "../../export/chartConfig";
+import type { VegaLiteSpec } from "../fromVegaLite";
+import type { PortableAnnotated, PortableAudienceProfile, PortableChartCapability } from "./spec";
+import type { PortabilityExportResult } from "./result";
+/** Options for the strict, typed outbound Vega-Lite adapter. */
+export interface ToVegaLiteOptions {
+    /**
+     * Allow a documented approximation. The default is false, so a caller never
+     * receives a visually plausible but semantically different Vega-Lite spec by
+     * accident.
+     */
+    allowLossy?: boolean;
+}
+/** Typed result for Vega-Lite export. A refused result deliberately has no spec. */
+export interface VegaLiteExportResult extends PortabilityExportResult<VegaLiteSpec> {
+    spec?: VegaLiteSpec;
+}
+/**
+ * Translate a Semiotic ChartConfig into Vega-Lite through an explicit result.
+ * Unsupported components are refused by default; pass `allowLossy` only when
+ * the caller has chosen to accept the listed semantic loss.
+ */
+export declare function toVegaLiteResult(config: ChartConfig, options?: ToVegaLiteOptions): VegaLiteExportResult;
+/**
+ * Convenience wrapper for the supported subset. Returns undefined on refusal
+ * rather than synthesizing a placeholder chart; use `toVegaLiteResult()` when
+ * a caller needs the structured diagnostic and loss report.
+ */
+export declare function toVegaLite(config: ChartConfig, options?: ToVegaLiteOptions): VegaLiteSpec | undefined;
+/** The metadata block that rides under `usermeta.idid`. */
+export interface IDIDVegaLiteMeta {
+    specVersion: string;
+    capability?: PortableChartCapability;
+    audience?: PortableAudienceProfile;
+    /** Provenanced annotations carried alongside the spec. */
+    annotations?: PortableAnnotated[];
+}
+/**
+ * Attach a capability descriptor and/or an audience profile to a Vega-Lite
+ * spec under `usermeta.idid`. A non-IDID renderer ignores `usermeta`; an
+ * IDID-aware host reads it (e.g. to route the capability through a suggestion
+ * engine). Returns a new spec; the input is not mutated.
+ */
+export declare function attachIDID(spec: VegaLiteSpec, meta: {
+    capability?: PortableChartCapability;
+    audience?: PortableAudienceProfile;
+}): VegaLiteSpec;
+/** Read the IDID metadata block from a Vega-Lite spec, if present. */
+export declare function readIDID(spec: VegaLiteSpec): IDIDVegaLiteMeta | undefined;
+/**
+ * Attach provenanced/lifecycled annotations to a Vega-Lite spec.
+ *
+ * The annotations are stored verbatim (with their provenance/lifecycle blocks)
+ * under the spec's `usermeta.idid.annotations` — that is the round-trip
+ * contract, and it composes with capability/audience metadata under the same
+ * key. As a courtesy to non-IDID renderers, each annotation that has a
+ * representable shape also emits a best-effort `rule`/`text` mark in an
+ * appended layer, so a plain Vega-Lite renderer still draws something. When no
+ * annotation is representable, no layer is added (avoiding an invalid empty
+ * layer) and the metadata still rides on `usermeta`. Returns a new spec; the
+ * input is not mutated.
+ */
+export declare function attachIDIDAnnotations(spec: VegaLiteSpec, annotations: ReadonlyArray<PortableAnnotated>): VegaLiteSpec;
+/** Read provenanced annotations back from a Vega-Lite spec. */
+export declare function readIDIDAnnotations(spec: VegaLiteSpec): PortableAnnotated[];

package/dist/components/export/chartConfig.d.ts

@@ -11,6 +11,17 @@ export interface ChartConfig {
     createdAt: string;
     /** Optional serialized selection/brush state */
     selections?: SerializedSelections;
+    /** Present for portable/local recipe configs. */
+    recipeId?: string;
+    portable?: boolean;
+    reason?: string;
+    warnings?: string[];
+    manifest?: {
+        name: string;
+        intents: string[];
+        audience?: string[];
+        frameFamily: string;
+    };
 }
 export interface ToConfigOptions {
     /** Include data arrays in the config. Default: true */

package/dist/components/realtime/ReorderBuffer.d.ts

@@ -0,0 +1,54 @@
+export type LatePolicy = "drop" | "keep";
+export interface ReorderBufferConfig<T> {
+    /** Grace window in ms. Events older than `watermark − lateness` are late. */
+    lateness: number;
+    /** Event-time accessor (ms). */
+    getTime: (item: T) => number;
+    /**
+     * What to do with a late event:
+     * - `"drop"` (default): discard it (still counted).
+     * - `"keep"`: release it immediately, out of order (still counted).
+     */
+    latePolicy?: LatePolicy;
+}
+export interface ReorderResult<T> {
+    /**
+     * Events ready to append to the main buffer now, in event-time order.
+     * Already reflects the late policy — dropped late events are excluded.
+     */
+    released: T[];
+    /** The events that were late this push (informational; for diagnostics). */
+    late: T[];
+}
+/**
+ * Buffers pushed events and releases them in event-time order once they
+ * fall outside the grace window. Stateful; one instance per series.
+ */
+export declare class ReorderBuffer<T> {
+    private readonly lateness;
+    private readonly getTime;
+    private readonly latePolicy;
+    private held;
+    private _watermark;
+    private _lateCount;
+    constructor(config: ReorderBufferConfig<T>);
+    /**
+     * Ingest one event. Returns the events that became safe to emit (in
+     * event-time order) plus any late events seen this push.
+     */
+    push(item: T): ReorderResult<T>;
+    /** Release all events whose time is at or before `watermark − lateness`. */
+    private drain;
+    /**
+     * Release everything still held, in event-time order — e.g. when the
+     * stream ends and the remaining grace-window events should be shown.
+     */
+    flush(): T[];
+    clear(): void;
+    /** Largest event-time seen, or `-Infinity` if empty. */
+    get watermark(): number;
+    /** Total late events seen since construction (or last `clear`). */
+    get lateCount(): number;
+    /** Events currently held inside the grace window. */
+    get heldCount(): number;
+}

package/dist/components/realtime/RunningStats.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Accumulates count, mean, variance, standard deviation, min, and max
+ * over a stream of numbers using Welford's online algorithm.
+ *
+ * Numerically stable in a single pass — preferred over the naive
+ * "sum of squares minus square of sum" form, which loses precision
+ * when values are large or closely clustered.
+ */
+export declare class RunningStats {
+    private _count;
+    private _mean;
+    private _m2;
+    private _min;
+    private _max;
+    /**
+     * Incorporate a value. O(1). Non-finite values (NaN, ±Infinity) are
+     * ignored — they would corrupt every downstream statistic — matching
+     * `IncrementalExtent`'s filter so all accumulators agree on what counts.
+     */
+    push(value: number): void;
+    /**
+     * Fold another accumulator's statistics into this one, in O(1),
+     * without revisiting the underlying values. Uses the parallel
+     * variance combine (Chan, Golub & LeVeque). Associative and
+     * commutative up to floating-point rounding — `a.merge(b)` then
+     * `a.merge(c)` yields the same result as merging in any order.
+     *
+     * Merging an empty accumulator is a no-op; merging into an empty
+     * accumulator copies the other's state.
+     */
+    merge(other: RunningStats): void;
+    /** Reset to the empty state. */
+    clear(): void;
+    /** A detached copy — useful for snapshotting a window before rollup. */
+    clone(): RunningStats;
+    /** Number of values incorporated. */
+    get count(): number;
+    /** Arithmetic mean, or 0 when empty. */
+    get mean(): number;
+    /**
+     * Sum of all values. Derived as `mean × count`, so it carries the
+     * same (tiny) floating drift as the running mean rather than a
+     * separate exact accumulator.
+     */
+    get sum(): number;
+    /**
+     * Population variance (divides by `count`). 0 when fewer than two
+     * values have been seen. Use this for a complete window of points —
+     * the window *is* the population. See {@link sampleVariance} for the
+     * unbiased estimator over a sample.
+     */
+    get variance(): number;
+    /** Population standard deviation — `sqrt(variance)`. */
+    get stddev(): number;
+    /**
+     * Sample variance (divides by `count − 1`, Bessel's correction).
+     * 0 when fewer than two values have been seen.
+     */
+    get sampleVariance(): number;
+    /** Sample standard deviation — `sqrt(sampleVariance)`. */
+    get sampleStddev(): number;
+    /** Smallest value seen, or `Infinity` when empty. */
+    get min(): number;
+    /** Largest value seen, or `-Infinity` when empty. */
+    get max(): number;
+}

package/dist/components/realtime/WindowAccumulator.d.ts

@@ -0,0 +1,105 @@
+/** The Kafka Streams window taxonomy. */
+export type WindowType = "tumbling" | "hopping" | "session";
+/** Which statistic the aggregated series carries as its primary value. */
+export type AggregateStat = "mean" | "sum" | "min" | "max" | "count";
+/** Envelope drawn around the aggregated series. */
+export type AggregateBand = "stddev" | "minmax" | "none";
+export interface WindowAccumulatorConfig {
+    /** Window kind. Defaults to `"tumbling"`. */
+    window?: WindowType;
+    /**
+     * Window width in **milliseconds** (already parsed from any duration
+     * string by the caller). For session windows this is unused; pass
+     * `gap` instead.
+     */
+    size: number;
+    /**
+     * Advance between consecutive hopping windows, in ms. Only meaningful
+     * for `window: "hopping"`; must satisfy `0 < hop ≤ size`. Defaults to
+     * `size`, which makes hopping degenerate to tumbling.
+     */
+    hop?: number;
+    /**
+     * Inactivity gap in ms that closes a session. Only meaningful for
+     * `window: "session"`. Two events within `gap` of each other (in
+     * event-time) share a session; an event bridging two sessions merges
+     * them.
+     */
+    gap?: number;
+    /**
+     * Keep at most this many most-recent windows; older windows are
+     * pruned on push. Bounds memory for an unbounded stream. Defaults to
+     * unbounded (`Infinity`).
+     */
+    retain?: number;
+}
+/** A closed or still-filling aggregation window. */
+export interface AggregatedWindow {
+    /** Inclusive window start (event-time ms). */
+    start: number;
+    /** Exclusive window end (event-time ms). */
+    end: number;
+    /** Number of events in the window. */
+    count: number;
+    mean: number;
+    sum: number;
+    min: number;
+    max: number;
+    /** Population standard deviation. */
+    stddev: number;
+    /**
+     * `true` while the window may still receive events — the trailing,
+     * still-filling window(s) up to the latest watermark. Render these
+     * distinctly (the partial-bin convention) so a viewer doesn't read a
+     * half-filled aggregate as final.
+     */
+    partial: boolean;
+}
+/**
+ * Accumulates event-time windowed statistics. Stateful and mutable —
+ * one instance per streaming series. Pure with respect to event order.
+ */
+export declare class WindowAccumulator {
+    private readonly type;
+    private readonly size;
+    private readonly hop;
+    private readonly gap;
+    private readonly retain;
+    private windows;
+    private sessions;
+    private latest;
+    constructor(config: WindowAccumulatorConfig);
+    /** Incorporate one event. Non-finite time/value are ignored. */
+    push(time: number, value: number): void;
+    private pushFixed;
+    private bump;
+    private pushSession;
+    private prune;
+    /**
+     * Snapshot the current windows as aggregated rows, sorted by start.
+     * For tumbling/hopping a window is `partial` while the watermark has
+     * not yet passed its end; for session windows the most recent session
+     * is `partial` while within `gap` of the watermark.
+     */
+    emit(): AggregatedWindow[];
+    private emitFixed;
+    private emitSessions;
+    private row;
+    /** Number of live windows (or sessions). */
+    get windowCount(): number;
+    /** The watermark — largest event-time seen, or `-Infinity` if empty. */
+    get watermark(): number;
+    clear(): void;
+}
+/**
+ * Pull the primary value for a stat off an aggregated window. `count`
+ * reads the event count; the rest read the matching `RunningStats`
+ * field.
+ */
+export declare function statValue(w: AggregatedWindow, stat: AggregateStat): number;
+/**
+ * Compute the [lower, upper] band bounds for an aggregated window.
+ * `stddev` draws `value ± k·σ` around the chosen stat; `minmax` draws
+ * the observed range. Returns `null` for `none`.
+ */
+export declare function bandBounds(w: AggregatedWindow, band: AggregateBand, stat: AggregateStat, sigma?: number): [number, number] | null;

package/dist/components/realtime/parseWindowDuration.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse a window duration to milliseconds.
+ *
+ * - A finite number is returned as-is (already milliseconds).
+ * - A string is parsed as one or more `<number><unit>` terms summed
+ *   together: `"1m"`, `"500ms"`, `"1m30s"`.
+ *
+ * Returns `null` for unparseable input (empty string, unknown unit,
+ * non-positive result, non-finite number) so callers can fall back to
+ * a default rather than silently bucketing on a zero-width window.
+ */
+export declare function parseWindowDuration(spec: number | string): number | null;

package/dist/components/realtime/types.d.ts

@@ -205,6 +205,17 @@ export interface RealtimeFrameHandle {
      *  export a chart-specific handle (e.g. `LikertChartHandle`) that
      *  extends this interface and narrows `getScales()`. */
     getScales?(): unknown | null;
+    /** The most recent custom layout result (as returned by the chart's
+     *  `layout(ctx)` function) — host readback so a page that needs the computed
+     *  placement (stats, inspectors) doesn't re-run the layout function itself.
+     *  Null before the first layout completes or when the chart has no custom
+     *  layout. A failed retry can retain the prior result; use
+     *  `getLayoutFailure()` to distinguish recovery. Typed as `unknown` at this shared boundary; the family frame
+     *  handles narrow it to their `LayoutResult` shape. */
+    getCustomLayout?(): unknown | null;
+    /** Latest structured custom-layout failure. Family frame handles narrow this
+     * to `CustomLayoutFailureDiagnostic`; absent on frames without layouts. */
+    getLayoutFailure?(): unknown | null;
 }
 export interface RealtimeScales {
     time: ScaleLinear<number, number>;

package/dist/components/recipes/annotationLayout.d.ts

@@ -51,6 +51,13 @@ export interface AnnotationLayoutConfig {
     responsive?: boolean | {
         minWidth?: number;
     };
+    /**
+     * Mobile annotation policy. This composes the existing responsive + density +
+     * progressive-disclosure passes into a phone-friendly default: keep the core
+     * notes persistent, collapse secondary notes, and prefer short/mobile copy
+     * when provided. Off by default.
+     */
+    mobile?: boolean | AnnotationMobileConfig;
     /**
      * M5 — cohesion mode (Rahman et al.'s "Cohesion"). `"blended"` lets notes
      * adopt the chart's visual language (mark colors / chart typography — the
@@ -69,6 +76,28 @@ export interface AnnotationLayoutConfig {
     audience?: AnnotationAudience;
 }
 export type AnnotationCohesion = "blended" | "layer";
+export interface AnnotationMobileConfig {
+    /** Width at or below which mobile behavior activates. Default 480px. */
+    breakpoint?: number;
+    /** Plot-only, callout-list, or hybrid mobile note behavior. */
+    strategy?: "plot" | "callout-list" | "hybrid";
+    /** Max persistent notes at phone width. Default 2. */
+    maxAnnotations?: number;
+    /** Maximum notes expected to move into an external mobile callout list. */
+    maxCalloutItems?: number;
+    /** Minimum notes kept regardless of budget. Default 1. */
+    minVisible?: number;
+    /** Keep shed notes hidden/revealable rather than dropping them. Default true. */
+    progressiveDisclosure?: boolean;
+    /** Responsive breakpoint override. Defaults to `breakpoint`. */
+    responsive?: boolean | {
+        minWidth?: number;
+    };
+    /** Annotation cohesion to apply at phone width. */
+    cohesion?: AnnotationCohesion;
+    /** Prefer annotation.mobileText / shortText for label text. Default true. */
+    preferShortText?: boolean;
+}
 /** Structural subset of `AudienceProfile` the annotation layer reads — anything
  *  with a per-chart `familiarity` map satisfies it, so a real `AudienceProfile`
  *  can be passed directly without coupling `recipes` to the `ai` module. */