semiotic 3.7.5 → 3.8.0

package/dist/components/charts/shared/useSyncedPushData.d.ts

@@ -0,0 +1,49 @@
+import type { Datum } from "./datumTypes";
+/**
+ * The slice of a chart's imperative handle this hook drives. Every Semiotic
+ * push-API handle (realtime + non-realtime HOCs) satisfies it structurally;
+ * each method is optional so the hook degrades gracefully on handles that
+ * only support a subset (e.g. append-only).
+ */
+export interface SyncedPushHandle<T = Datum> {
+    push?: (datum: T) => unknown;
+    pushMany?: (data: T[]) => unknown;
+    update?: (id: string, updater: (datum: T) => T) => unknown;
+    remove?: (id: string | string[]) => unknown;
+    clear?: () => unknown;
+}
+/** An id accessor: a field name, or a function of the row (and its index). */
+export type PushIdAccessor<T> = keyof T | ((datum: T, index: number) => string | number | null | undefined);
+export interface SyncedPushDataOptions<T = Datum> {
+    /**
+     * Identifies a row so it can be updated/removed in place. A field name
+     * (`"id"`) or a function. Omit it and rows are keyed by index — fine for
+     * append-mostly streams, but reorders/removals then read positionally.
+     */
+    id?: PushIdAccessor<T>;
+    /**
+     * Clear the buffer and re-sync from scratch whenever this value changes.
+     * Use it for things that invalidate the whole series — a theme remount, a
+     * mode switch, a new data source. The handle identity changing (chart
+     * remount) always forces a reset too.
+     */
+    resetKey?: unknown;
+}
+/**
+ * Pure reconciliation: bring `handle`'s buffer from `previousById` to `rows`,
+ * issuing the minimal push/update/remove calls, and return the new id→row map.
+ *
+ * Exported for direct use and unit testing. The hook is a thin
+ * effect wrapper around this. Rows are matched by `getId`; a row whose
+ * reference changed is `update`d in place (or removed + re-pushed when the
+ * handle has no `update`).
+ */
+export declare function syncPushBuffer<T = Datum>(handle: SyncedPushHandle<T>, previousById: Map<string, T>, rows: ReadonlyArray<T>, getId: ((datum: T, index: number) => string) | null): Map<string, T>;
+/**
+ * Mirror a controlled React array into a push-API chart's buffer.
+ *
+ * @param ref      The same ref you pass to the chart's `ref` prop.
+ * @param data     The rows the chart should currently show.
+ * @param options  `id` accessor and optional `resetKey`.
+ */
+export declare function useSyncedPushData<T = Datum>(ref: React.RefObject<SyncedPushHandle<T> | null>, data: ReadonlyArray<T>, options?: SyncedPushDataOptions<T>): void;

package/dist/components/charts/shared/validationMap.d.ts

@@ -1,13 +1,2 @@
-/**
- * Per-component prop specifications for validation.
- *
- * Pure data — one ComponentSpec entry per Semiotic HOC chart.
- * Shared prop fragments (commonProps, xyAxisProps, etc.) are composed
- * via spread to keep individual entries concise.
- *
- * Consumed by: validateProps.ts (validation engine), diagnoseConfig.ts,
- *              chartConfig.ts. Schema/validation parity is locked by the
- *              Chart Spec Registry (`check:chart-specs`).
- */
 import type { ComponentSpec } from "./validateProps";
 export declare const VALIDATION_MAP: Record<string, ComponentSpec>;

package/dist/components/charts/xy/AreaChart.d.ts

@@ -64,7 +64,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Curve interpolation type
      * @default "monotoneX"

package/dist/components/charts/xy/BubbleChart.d.ts

@@ -55,7 +55,7 @@ export interface BubbleChartProps<TDatum extends Datum = Datum> extends BaseChar
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Bubble opacity
      * @default 0.6

package/dist/components/charts/xy/LineChart.d.ts

@@ -73,7 +73,7 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Curve interpolation type
      * @default "linear"

package/dist/components/charts/xy/MinimapChart.d.ts

@@ -37,7 +37,7 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
     /** Color-by field or function */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme (default: "category10") */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Curve type (default: "linear") */
     curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
     /** Line stroke width (default: 2) */

package/dist/components/charts/xy/MultiAxisLineChart.d.ts

@@ -28,12 +28,12 @@ export interface MultiAxisLineChartProps<TDatum extends Datum = Datum> extends B
     /** Array of data points shared by both series */
     data?: TDatum[];
     /** Field name or function to access x values @default "x" */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /** Series configuration — exactly 2 for dual-axis mode.
      *  If not exactly 2, renders as a normal line chart with a console warning. */
     series: MultiAxisSeriesConfig<TDatum>[];
     /** Color scheme or custom colors array @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Enable hover annotations @default true */
     enableHover?: boolean;
     /** Curve interpolation @default "monotoneX" */

package/dist/components/charts/xy/QuadrantChart.d.ts

@@ -69,7 +69,7 @@ export interface QuadrantChartProps<TDatum extends Datum = Datum> extends BaseCh
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Field name or function to determine point size */
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max radius for points @default [3, 15] */

package/dist/components/charts/xy/Scatterplot.d.ts

@@ -25,7 +25,7 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data or custom colors array @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Field name or function to determine point size */
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max radius for points @default [3, 15] */

package/dist/components/charts/xy/ScatterplotMatrix.d.ts

@@ -12,7 +12,7 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
     /** Field or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Size of each cell in pixels @default 150 */
     cellSize?: number;
     /** Gap between cells in pixels @default 4 */
@@ -39,6 +39,16 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
     showLegend?: boolean;
     /** Field or function to identify each data point in tooltips. Defaults to "Row {index}" */
     idAccessor?: string | ((d: TDatum) => string);
+    /**
+     * Called when a point in any cell is clicked. Receives the clicked row datum
+     * and its grid-relative pixel position `{ x, y }` — the same coordinate space
+     * as `onObservation`. Fires in hover mode (the default); in brush mode the
+     * drag-select overlay captures pointer events, so clicks are not delivered.
+     */
+    onClick?: (datum: TDatum, event: {
+        x: number;
+        y: number;
+    }) => void;
 }
 /**
  * ScatterplotMatrix (SPLOM) — multi-dimensional scatter visualization

package/dist/components/charts/xy/StackedAreaChart.d.ts

@@ -21,7 +21,7 @@ export interface StackedAreaChartProps<TDatum extends Datum = Datum> extends Bas
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -55,7 +55,7 @@ export interface StackedAreaChartProps<TDatum extends Datum = Datum> extends Bas
      * Color scheme for categorical data or custom colors array
      * @default "category10"
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Curve interpolation type
      * @default "monotoneX"
@@ -99,13 +99,16 @@ export interface StackedAreaChartProps<TDatum extends Datum = Datum> extends Bas
      *   wiggle across series — best for high-cardinality series where
      *   relative shape matters more than absolute values.
      * - `"silhouette"`: center the stack symmetrically around y=0.
+     * - `"diverging"`: series with **positive** y stack above 0; series with
+     *   **negative** y stack below 0 (signed benefit / risk stacks). Pass
+     *   negative values for risk layers — do not use absolute magnitudes.
      *
      * Mutually exclusive with `normalize` — when `normalize` is true,
      * baseline is forced to `"zero"`.
      *
      * @default "zero"
      */
-    baseline?: "zero" | "wiggle" | "silhouette";
+    baseline?: "zero" | "wiggle" | "silhouette" | "diverging";
     /**
      * Stack order — controls which series sits at the top, middle, or
      * bottom of the stack. Pair with `baseline: "wiggle"` or
@@ -113,12 +116,14 @@ export interface StackedAreaChartProps<TDatum extends Datum = Datum> extends Bas
      *
      * - `"key"` (default): alphabetical by series key. Stable under
      *   streaming (no re-shuffling on data eviction).
+     * - `"input"`: first-seen series order within the current data
+     *   buffer/window; streaming eviction can change this order.
      * - `"insideOut"`: largest-total series in the middle, smaller series
      *   wrapping outward. The classic d3 streamgraph aesthetic — gives
      *   you a "central anchor" layer with everything else built off of it.
      * - `"asc"` / `"desc"`: by total ascending / descending.
      */
-    stackOrder?: "key" | "insideOut" | "asc" | "desc";
+    stackOrder?: "key" | "input" | "insideOut" | "asc" | "desc";
     /**
      * Enable hover annotations
      * @default true

package/dist/components/controls/controlAudit.d.ts

@@ -0,0 +1,24 @@
+import { type VisualizationControlDefinition } from "./controlContract";
+export type ControlAuditStatus = "pass" | "warn" | "fail";
+export interface ControlAuditFinding {
+    id: string;
+    controlId?: string;
+    status: ControlAuditStatus;
+    message: string;
+    remediation?: string;
+}
+export interface ControlAuditResult {
+    ok: boolean;
+    findings: ControlAuditFinding[];
+}
+export interface AuditVisualizationControlsOptions {
+    controls?: ReadonlyArray<VisualizationControlDefinition>;
+    minimumTargetSize?: number;
+}
+/**
+ * Audit portable control declarations without requiring a mounted chart. It
+ * verifies the invariants an agent or recipe serializer can actually inspect:
+ * semantic type, controlled-state target, keyboard path, value text, and
+ * minimum target size.
+ */
+export declare function auditVisualizationControls({ controls, minimumTargetSize, }: AuditVisualizationControlsOptions): ControlAuditResult;

package/dist/components/controls/controlContract.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Frame-neutral semantics shared by SVG, HTML, and declarative visualization
+ * controls. This module intentionally has no React, frame, or store imports so
+ * it can be included by the small `semiotic/controls` entry point.
+ */
+export declare const VISUALIZATION_CONTROL_TYPES: readonly ["value", "threshold", "partition-boundary", "time-window", "range-boundary"];
+export type VisualizationControlType = (typeof VISUALIZATION_CONTROL_TYPES)[number];
+export type VisualizationControlValue = number | [number, number];
+export type ControlObservationPhase = "control-start" | "control-change" | "control-end";
+export type ControlInputSource = "pointer" | "keyboard" | "programmatic";
+/** A machine-readable interaction emitted by a visualization control. */
+export interface ControlObservation {
+    type: ControlObservationPhase;
+    controlType: VisualizationControlType;
+    value: VisualizationControlValue;
+    chartType: string;
+    timestamp: number;
+    controlId?: string;
+    chartId?: string;
+    source?: ControlInputSource;
+}
+export type ControlObservationCallback = (observation: ControlObservation) => void;
+export interface ControlObservationAdapterOptions {
+    controlType: VisualizationControlType;
+    controlId?: string;
+    chartId?: string;
+    chartType?: string;
+    onObservation?: ControlObservationCallback;
+}
+/**
+ * Creates an adapter for a control implementation. Frame adapters can pass
+ * their existing `onObservation`, while standalone controls can omit it.
+ */
+export declare function createControlObservationAdapter({ controlType, controlId, chartId, chartType, onObservation, }: ControlObservationAdapterOptions): (phase: ControlObservationPhase, value: VisualizationControlValue, source?: ControlInputSource) => void;
+/**
+ * JSON-safe control metadata carried by portable recipes and agent-facing
+ * audits. `target` is the controlled state binding, not a pointer handler.
+ */
+export interface VisualizationControlDefinition {
+    id: string;
+    type: VisualizationControlType;
+    target: string;
+    domain: readonly [number, number];
+    label: string;
+    valueText: string;
+    step?: number;
+    keyboard?: "slider" | "buttons" | "native-range";
+    alternatives?: readonly string[];
+    observations?: readonly ControlObservationPhase[];
+    minimumTargetSize?: number;
+    annotation?: {
+        /** The annotation state key that follows this control's value. */
+        target?: string;
+        /** A portable template, such as "Threshold: {value}". */
+        valueText?: string;
+    };
+}

package/dist/components/data/fromFlintChart.d.ts

@@ -0,0 +1,74 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ChartConfig } from "../export/chartConfig";
+/**
+ * Flint Chart -> Semiotic translator.
+ *
+ * Flint's public request shape is intentionally small: inline or referenced
+ * rows, optional field semantics, and a chart_spec object with chart type,
+ * channel encodings, base size, canvas ceiling, and chart properties. This
+ * adapter consumes that request as an ecosystem boundary format and emits a
+ * Semiotic ChartConfig. It does not call Flint and does not attempt to compile
+ * Flint to backend-native specs.
+ *
+ * Scope (experimental): bar, grouped bar, stacked bar, line, area, scatter,
+ * heatmap, pie/donut, histogram, and boxplot with simple channel bindings.
+ */
+export type FlintEncodingType = "quantitative" | "nominal" | "ordinal" | "temporal";
+export type FlintAggregate = "count" | "sum" | "average" | "mean";
+export interface FlintSemanticAnnotation {
+    semanticType?: string;
+    [key: string]: unknown;
+}
+export interface FlintChartEncoding {
+    field?: string;
+    type?: FlintEncodingType;
+    aggregate?: FlintAggregate;
+    sortOrder?: "ascending" | "descending";
+    sortBy?: string;
+    scheme?: string;
+    [key: string]: unknown;
+}
+export type FlintEncodingInput = FlintChartEncoding | string;
+export type FlintRawEncodingValue = FlintEncodingInput | FlintEncodingInput[];
+export interface FlintChartSize {
+    width: number;
+    height: number;
+}
+export interface FlintChartAssemblyInput {
+    data: {
+        values: Datum[];
+        url?: never;
+    } | {
+        url: string;
+        values?: never;
+    };
+    semantic_types?: Record<string, string | FlintSemanticAnnotation>;
+    chart_spec: {
+        chartType: string;
+        encodings: Record<string, FlintRawEncodingValue>;
+        baseSize?: FlintChartSize;
+        canvasSize?: FlintChartSize;
+        chartProperties?: Record<string, unknown>;
+    };
+    options?: Record<string, unknown>;
+    field_display_names?: Record<string, string>;
+}
+export interface FlintChartConfigMetadata {
+    chartType: string;
+    semanticTypes?: Record<string, string | FlintSemanticAnnotation>;
+    fieldDisplayNames?: Record<string, string>;
+    chartProperties?: Record<string, unknown>;
+    baseSize?: FlintChartSize;
+    canvasSize?: FlintChartSize;
+    dataUrl?: string;
+    options?: Record<string, unknown>;
+    unmappedEncodings?: Record<string, FlintRawEncodingValue>;
+}
+export type FlintChartConfig = ChartConfig & {
+    warnings?: string[];
+    flint: FlintChartConfigMetadata;
+};
+/**
+ * Convert a Flint ChartAssemblyInput into a Semiotic ChartConfig.
+ */
+export declare function fromFlintChart(input: FlintChartAssemblyInput): FlintChartConfig;

package/dist/components/data/fromVegaLite.d.ts

@@ -6,6 +6,7 @@
  * with basic encodings. No layers, facets, selections, or complex transforms.
  */
 import type { ChartConfig } from "../export/chartConfig";
+import type { PortabilityImportResult } from "./portability/result";
 export interface VegaLiteEncoding {
     field?: string;
     type?: "quantitative" | "nominal" | "ordinal" | "temporal";
@@ -43,6 +44,32 @@ export interface VegaLiteSpec {
     transform?: any[];
     [key: string]: any;
 }
+/** Strictness for the typed, experimental Vega-Lite import result. */
+export interface FromVegaLiteOptions {
+    /**
+     * Strict is the safe default: unsupported composition or marks return a
+     * typed refusal instead of a plausible fallback chart. `lossy` retains the
+     * legacy fallback behavior, but reports every known loss explicitly.
+     */
+    mode?: "strict" | "lossy";
+}
+/** Typed result for the experimental, loss-aware Vega-Lite importer. */
+export type VegaLiteImportResult = PortabilityImportResult<ChartConfig>;
+/**
+ * Recover the one base view emitted by attachIDIDAnnotations(). This is
+ * intentionally narrow: arbitrary Vega-Lite layer composition remains
+ * unsupported and must not be guessed as a chart configuration.
+ */
+export declare function unwrapIDIDEnrichedVegaLiteSpec(spec: VegaLiteSpec): VegaLiteSpec;
 export declare function fromVegaLite(spec: VegaLiteSpec): ChartConfig & {
     warnings?: string[];
 };
+/**
+ * Strict, loss-aware Vega-Lite import.
+ *
+ * `fromVegaLite()` remains the stable compatibility helper and therefore
+ * preserves its historical fallback behavior. New portability integrations
+ * should use this result API, whose default is to refuse unsupported semantics
+ * rather than return a chart that merely looks plausible.
+ */
+export declare function fromVegaLiteResult(spec: VegaLiteSpec, options?: FromVegaLiteOptions): VegaLiteImportResult;

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

@@ -9,6 +9,9 @@
  * surface is proven against real consumers.
  */
 export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS, validatePortableCapability, validatePortableAudienceProfile, validatePortableAnnotation, } from "./spec";
-export type { BuiltInIntentId, PortableIntentId, PortableChartRubric, PortableChartVariant, PortableChartCapability, PortableReceptionModality, PortableAudienceTarget, PortableAudienceProfile, PortableAnnotationActorKind, PortableAnnotationSource, PortableAnnotationBasis, PortableAnnotationProvenance, PortableAnnotationFreshness, PortableAnnotationStatus, PortableAnnotationAnchor, PortableAnnotationLifecycle, PortableAnnotated, ValidationResult, } from "./spec";
-export { toVegaLite, attachIDID, readIDID, attachIDIDAnnotations, readIDIDAnnotations, } from "./vegaLite";
-export type { IDIDVegaLiteMeta } from "./vegaLite";
+export type { BuiltInIntentId, PortableIntentId, PortableChartRubric, PortableChartVariant, PortableMobileInteractionCapability, PortableMobileLabelCapability, PortableMobileCustomCapability, PortableMobileCapability, PortableChartCapability, PortableReceptionModality, PortableAudienceTarget, PortableAudienceProfile, PortableAnnotationActorKind, PortableAnnotationSource, PortableAnnotationBasis, PortableAnnotationProvenance, PortableAnnotationFreshness, PortableAnnotationStatus, PortableAnnotationAnchor, PortableAnnotationLifecycle, PortableAnnotated, ValidationResult, } from "./spec";
+export { toVegaLite, toVegaLiteResult, attachIDID, readIDID, attachIDIDAnnotations, readIDIDAnnotations, } from "./vegaLite";
+export type { IDIDVegaLiteMeta, ToVegaLiteOptions, VegaLiteExportResult, } from "./vegaLite";
+export { fromVegaLiteResult, unwrapIDIDEnrichedVegaLiteSpec, } from "../fromVegaLite";
+export type { FromVegaLiteOptions, VegaLiteImportResult, } from "../fromVegaLite";
+export type { PortabilityStatus, PortabilityDiagnosticSeverity, PortabilityDiagnostic, PortabilityLoss, PortabilityProvenance, PortabilityResult, PortabilityImportResult, PortabilityExportResult, } from "./result";

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

@@ -40,6 +40,35 @@ export interface PortableChartVariant {
     /** 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;
@@ -53,6 +82,8 @@ export interface PortableChartCapability {
     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";

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

@@ -16,14 +16,32 @@
 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;
 /**
- * Translate a Semiotic ChartConfig into a Vega-Lite spec. Covers the families
- * `fromVegaLite` covers, so the pair round-trips. Constructs unsupported by
- * Vega-Lite's single-view core surface a warning rather than a wrong spec.
+ * 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): VegaLiteSpec & {
-    warnings?: string[];
-};
+export declare function toVegaLite(config: ChartConfig, options?: ToVegaLiteOptions): VegaLiteSpec | undefined;
 /** The metadata block that rides under `usermeta.idid`. */
 export interface IDIDVegaLiteMeta {
     specVersion: string;

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/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. */