semiotic 3.7.4 → 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/validateChartData.d.ts

@@ -12,7 +12,7 @@ import type { Datum } from "./datumTypes";
 type AccessorLike = string | ((...args: any[]) => any);
 interface ArrayDataValidation {
     componentName: string;
-    data: any[] | undefined | null;
+    data: any;
     accessors?: Record<string, AccessorLike | undefined>;
     requiredProps?: Datum;
 }

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

@@ -1,6 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
+import type { SymbolName } from "../../stream/symbolPath";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -24,11 +25,19 @@ 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] */
     sizeRange?: [number, number];
+    /** Field name or function → glyph **shape**: each mark renders as a d3-shape
+     *  glyph instead of a circle (the per-datum shape channel). Pair with a
+     *  `symbolMap` for stable, legend-matchable shapes; unmapped categories
+     *  auto-assign. Size still tracks `sizeBy`/`pointRadius`. */
+    symbolBy?: ChartAccessor<TDatum, string>;
+    /** Explicit `{category → shape}` map for `symbolBy` (e.g. `{ Civil: "star" }`);
+     *  unmapped categories auto-assign from the shape sequence. */
+    symbolMap?: Record<string, SymbolName>;
     /** Default point radius when sizeBy is not specified @default 5 */
     pointRadius?: number;
     /** Point opacity @default 0.8 */

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

@@ -0,0 +1,54 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Apache Arrow → Semiotic rows (v1).
+ *
+ * Reads an Arrow table (DuckDB-Wasm result set, Arrow IPC, Parquet-via-Arrow)
+ * into the plain row objects the chart accessor path expects, so an in-browser
+ * analytics engine can feed Semiotic with one call.
+ *
+ * **Honest scope (v1).** Semiotic's data path is row-oriented and validates the
+ * `data` prop with `Array.isArray`, so a chart's `data` must be a real array of
+ * row objects. This adapter therefore materializes rows — but leanly: it reads
+ * each requested column cell-by-cell into a plain object, avoiding Arrow's own
+ * `Table.toArray()` row-proxy machinery, and it supports column projection so
+ * you only pay for the fields you chart. The genuinely zero-copy columnar path
+ * (a typed-array accessor mode + bulk ring-buffer ingest) is deliberately
+ * *not* built here: it touches the ingestion core and waits on a named consumer
+ * plus profiling evidence, rather than being built on spec.
+ *
+ * Pure, dependency-free: the Arrow table is duck-typed, so `apache-arrow` never
+ * enters Semiotic's dependencies — you bring the table, this reads it.
+ */
+/** A column vector, duck-typed to apache-arrow's `Vector`. */
+export interface ArrowColumnLike {
+    get(index: number): unknown;
+}
+/** A schema field, duck-typed to apache-arrow's `Field`. */
+export interface ArrowFieldLike {
+    name: string;
+}
+/** A table schema, duck-typed to apache-arrow's `Schema`. */
+export interface ArrowSchemaLike {
+    fields: ReadonlyArray<ArrowFieldLike>;
+}
+/** An Arrow table, duck-typed to apache-arrow's `Table` (and DuckDB-Wasm results). */
+export interface ArrowTableLike {
+    numRows: number;
+    schema: ArrowSchemaLike;
+    getChild(name: string): ArrowColumnLike | null | undefined;
+}
+export interface FromArrowOptions {
+    /** Project a subset of columns. Omit to read every column in the schema. */
+    fields?: ReadonlyArray<string>;
+    /**
+     * Convert Arrow int64/uint64 values (returned as `bigint`) to `number`, since
+     * the chart scales and `toNumber` coercion work in `number`. Default true.
+     * Values outside `Number.MAX_SAFE_INTEGER` are left as `bigint` (and warned).
+     */
+    coerceBigInt?: boolean;
+}
+/**
+ * Materialize an Arrow table into Semiotic row objects. Pass the result
+ * straight to a chart's `data` prop: `<LineChart data={fromArrow(table)} … />`.
+ */
+export declare function fromArrow(table: ArrowTableLike, options?: FromArrowOptions): Datum[];

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

@@ -0,0 +1,47 @@
+/**
+ * Mermaid → Semiotic graph (alpha).
+ *
+ * Mermaid is the dominant text-to-graph language across GitHub, Notion, and LLM
+ * output — but it renders as flat, hard-to-style, non-interactive, *inaccessible*
+ * SVG. This adapter parses Mermaid `graph`/`flowchart` syntax into a topology
+ * Semiotic can render with hover, isolation, theme tokens, keyboard navigation,
+ * and an accessible navigation tree.
+ *
+ * The gofish lesson applies hard (D7): **reconstruct the diagram's semantics,
+ * not its pixels.** A Mermaid flowchart is a DAG, not a force graph, so this
+ * adapter doesn't just emit nodes/edges — it computes a layered layout
+ * (longest-path layering) and stamps each node with `layer`/`row` coordinates,
+ * ready for the `lineageDagLayout` recipe via `NetworkCustomChart`. The raw
+ * topology is also returned, so a consumer who wants a force layout
+ * (`ForceDirectedGraph`) can use it directly.
+ *
+ * Scope (alpha): `graph`/`flowchart` with TD/TB/BT/LR/RL direction, node shapes,
+ * and labeled edges. Other Mermaid diagram types (sequence, class, state, er,
+ * gantt, pie, mindmap, …) are declined with a reason rather than mistranslated.
+ *
+ * Pure, dependency-free: a small dedicated parser, never a Mermaid runtime dep.
+ */
+export type MermaidDirection = "TD" | "TB" | "BT" | "LR" | "RL";
+export type MermaidNodeShape = "rect" | "round" | "stadium" | "subroutine" | "cylinder" | "circle" | "diamond" | "hexagon" | "flag";
+export interface MermaidNode {
+    id: string;
+    label: string;
+    shape: MermaidNodeShape;
+    /** Longest-path layer (0 = a source with no incoming edges). */
+    layer: number;
+    /** Order within the layer (insertion order). */
+    row: number;
+}
+export interface MermaidEdge {
+    source: string;
+    target: string;
+    label?: string;
+}
+export interface MermaidResult {
+    kind: "flowchart";
+    direction: MermaidDirection;
+    nodes: MermaidNode[];
+    edges: MermaidEdge[];
+    warnings?: string[];
+}
+export declare function fromMermaid(text: string): MermaidResult;

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

@@ -0,0 +1,69 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Observable Plot → Semiotic translator.
+ *
+ * A sibling to `fromVegaLite`: maps a declarative Observable Plot spec to a
+ * Semiotic `ChartConfig`, so a chart sketched in a notebook crosses the
+ * notebook→production rewrite tax and arrives with everything a throwaway Plot
+ * chart never had — accessible tables, keyboard navigation, descriptions, the
+ * a11y audit, theme tokens, annotation provenance, and SSR.
+ *
+ * Honest hard part (the reason this stages behind `unstable_`): Plot's public
+ * API is *imperative JS* (`Plot.line(data, {…})`), not declarative JSON. This
+ * adapter consumes the **declarative shape of a Plot spec** — the `{ marks,
+ * x, y, color, … }` object you'd pass to `Plot.plot()`, with each mark
+ * expressed as `{ type, data?, options? }`. Where a mark, channel, or
+ * transform has no faithful Semiotic equivalent, it surfaces a warning and
+ * refuses to approximate, rather than emit a plausible-but-wrong chart.
+ *
+ * Scope (alpha): core marks — line/lineY/lineX, barY/barX, dot, areaY/area,
+ * rectY (binned → histogram), cell, tick — with basic channels. No layered
+ * multi-mark plots, facets, or Plot transforms (binX/groupY/stackY as option
+ * wrappers).
+ */
+import type { ChartConfig } from "../export/chartConfig";
+/** A channel value: a field name (string), a constant (number), or — declined — a function. */
+export type ObservablePlotChannel = string | number | ((d: Datum, i: number) => unknown);
+export interface ObservablePlotMarkOptions {
+    x?: ObservablePlotChannel;
+    y?: ObservablePlotChannel;
+    fill?: ObservablePlotChannel;
+    stroke?: ObservablePlotChannel;
+    r?: ObservablePlotChannel;
+    z?: ObservablePlotChannel;
+    curve?: string;
+    [key: string]: unknown;
+}
+export interface ObservablePlotMark {
+    /** The Plot mark function name, e.g. "line", "barY", "dot", "areaY", "cell". */
+    type: string;
+    data?: Datum[];
+    options?: ObservablePlotMarkOptions;
+}
+export interface ObservablePlotScale {
+    label?: string;
+    type?: string;
+    scheme?: string;
+    domain?: unknown;
+    range?: unknown;
+    [key: string]: unknown;
+}
+export interface ObservablePlotSpec {
+    marks?: ObservablePlotMark[];
+    /** Shared data, when marks don't each carry their own. */
+    data?: Datum[];
+    width?: number;
+    height?: number;
+    title?: string;
+    x?: ObservablePlotScale;
+    y?: ObservablePlotScale;
+    color?: ObservablePlotScale;
+    r?: ObservablePlotScale;
+    fx?: unknown;
+    fy?: unknown;
+    facet?: unknown;
+    [key: string]: unknown;
+}
+export declare function fromObservablePlot(spec: ObservablePlotSpec): ChartConfig & {
+    warnings?: string[];
+};

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

@@ -0,0 +1,17 @@
+/**
+ * IDID portability spec — runtime surface (v0.1, experimental).
+ *
+ * Library-neutral types, dependency-free validators, an outbound Vega-Lite
+ * translator, and the IDID-over-Vega-Lite binding. The canonical published
+ * artifact is the JSON Schema set in `/spec/v0.1`.
+ *
+ * Exposed via `semiotic/experimental` behind the `unstable_` prefix while the
+ * surface is proven against real consumers.
+ */
+export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS, validatePortableCapability, validatePortableAudienceProfile, validatePortableAnnotation, } from "./spec";
+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";