semiotic 3.7.5 → 3.8.1

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * StackedAreaChart component props
  */
@@ -21,7 +22,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 +56,13 @@ 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>;
+    /**
+     * Declarative, threshold-aware styling for the stacked series. Ordered
+     * `{ when, style }` rules; last applicable rule wins. Per-SERIES. A rule
+     * `fill` may be a color or a HatchFill. Layers over the resolved series color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Curve interpolation type
      * @default "monotoneX"
@@ -99,13 +106,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 +123,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/charts/xy/differenceSegments.d.ts

@@ -0,0 +1,49 @@
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Crossover-segmented record used by the area pipeline. One row per
+ * vertex along either the upper or lower boundary; `__diffSegment` is a
+ * group key per segment so the area scene builder produces one polygon
+ * per id with the correct fill color.
+ */
+export interface SegmentRow {
+    __x: number;
+    /** Upper boundary y value (max of A, B). The area pipeline reads this. */
+    __y: number;
+    /** Lower boundary y value (min of A, B) — picked up as per-datum y0. */
+    __y0: number;
+    /** Segment id. Format: `"seg-<index>-<winner>"`. */
+    __diffSegment: string;
+    /** Which series is on top in this segment ("A" or "B"). Drives fill. */
+    __diffWinner: "A" | "B";
+    /** Original A value at this x (or interpolated at crossovers). */
+    __valA: number;
+    /** Original B value at this x (or interpolated at crossovers). */
+    __valB: number;
+    /** Original datum (for tooltip lookup at non-crossover vertices). */
+    __sourceDatum?: Datum;
+}
+/**
+ * Walk sorted data, splitting at each A↔B crossover. Inserts an
+ * interpolated vertex on BOTH sides of every crossover so adjacent
+ * segments meet at a zero-width point (no jagged edges).
+ *
+ * Non-finite rows are skipped; the algorithm tracks the most recent
+ * VALID non-tie row (not the index neighbor) for crossover detection,
+ * so a non-finite gap doesn't drop a crossover that straddles it.
+ *
+ * Tie rows (a === b) are handled distinctly from non-tie rows:
+ *
+ *   - When a tie row sits BETWEEN two non-tie rows with the SAME
+ *     winner, the tie is emitted in that winner's segment as a
+ *     zero-width vertex.
+ *   - When a tie row sits between non-tie rows with DIFFERENT winners,
+ *     the FIRST tie of the run becomes the crossover vertex. The old
+ *     segment closes at the tie's x, the new segment opens at the same
+ *     point, and any subsequent tie rows (multi-tie runs) carry into
+ *     the new segment as zero-width vertices.
+ *
+ * This preserves the data's actual zero-difference point: if the user
+ * supplied a tie row explicitly, the fill switches color exactly at
+ * that x rather than at a linear-interpolated x that ignored the tie.
+ */
+export declare function computeDifferenceSegments<TDatum extends Datum>(raw: TDatum[], getX: (d: TDatum) => number, getA: (d: TDatum) => number, getB: (d: TDatum) => number): SegmentRow[];

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

@@ -0,0 +1,12 @@
+import type { D3BrushEvent } from "d3-brush";
+import type { Datum } from "../shared/datumTypes";
+export interface ScatterplotMatrixHoverInfo {
+    datum: Datum;
+    xField: string;
+    yField: string;
+    colIndex: number;
+    rowIndex: number;
+    px: number;
+    py: number;
+}
+export declare function isTwoDimensionalBrushSelection(selection: D3BrushEvent<Datum>["selection"]): selection is [[number, number], [number, number]];

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

@@ -0,0 +1,97 @@
+import * as React from "react";
+export type SentenceFilterPrimitive = string | number | boolean | null;
+export type SentenceFilterValue = SentenceFilterPrimitive | string[] | number[] | [number, number];
+export interface SentenceFilterOption<T = SentenceFilterPrimitive> {
+    value: T;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    count?: number;
+    disabled?: boolean;
+    keywords?: string[];
+}
+export interface SentenceFilterBaseDefinition<T = SentenceFilterValue> {
+    label: string;
+    description?: string;
+    disabled?: boolean;
+    allowClear?: boolean;
+    emptyLabel?: React.ReactNode;
+    accent?: string;
+    formatValue?: (value: T, filters: Record<string, SentenceFilterValue>) => React.ReactNode;
+    getAccessibleValue?: (value: T, filters: Record<string, SentenceFilterValue>) => string;
+}
+export interface SentenceFilterSelectDefinition extends SentenceFilterBaseDefinition {
+    type: "select";
+    options: SentenceFilterOption[];
+    searchable?: boolean;
+}
+export interface SentenceFilterMultiSelectDefinition extends SentenceFilterBaseDefinition {
+    type: "multiselect";
+    options: SentenceFilterOption[];
+    searchable?: boolean;
+    conjunction?: "and" | "or";
+}
+export interface SentenceFilterNumberDefinition extends SentenceFilterBaseDefinition<number> {
+    type: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+    inputMode?: "input" | "slider" | "both";
+}
+export interface SentenceFilterRangeDefinition extends SentenceFilterBaseDefinition<[number, number]> {
+    type: "range";
+    min: number;
+    max: number;
+    step?: number;
+}
+export interface SentenceFilterToggleDefinition extends SentenceFilterBaseDefinition<boolean> {
+    type: "toggle";
+    trueLabel?: React.ReactNode;
+    falseLabel?: React.ReactNode;
+}
+export interface SentenceFilterTextDefinition extends SentenceFilterBaseDefinition<string> {
+    type: "text";
+    suggestions?: SentenceFilterOption<string>[];
+    placeholder?: string;
+}
+export type SentenceFilterDefinition = SentenceFilterSelectDefinition | SentenceFilterMultiSelectDefinition | SentenceFilterNumberDefinition | SentenceFilterRangeDefinition | SentenceFilterToggleDefinition | SentenceFilterTextDefinition;
+export interface SentenceFilterChangeMeta {
+    key: string;
+    previousValue: SentenceFilterValue;
+    value: SentenceFilterValue;
+    source: "pointer" | "keyboard" | "input" | "clear" | "programmatic";
+}
+export interface SentenceFilterRenderContext {
+    key: string;
+    value: SentenceFilterValue;
+    filters: Record<string, SentenceFilterValue>;
+    definition: SentenceFilterDefinition;
+    setValue: (value: SentenceFilterValue, source?: SentenceFilterChangeMeta["source"]) => void;
+    close: () => void;
+}
+export interface SentenceFilterProps {
+    sentence: string;
+    /** Controlled filter values. */
+    filters?: Record<string, SentenceFilterValue>;
+    /** Initial values for the optional uncontrolled form. */
+    defaultFilters?: Record<string, SentenceFilterValue>;
+    definitions: Record<string, SentenceFilterDefinition>;
+    onChange?: (filters: Record<string, SentenceFilterValue>, meta: SentenceFilterChangeMeta) => void;
+    as?: React.ElementType;
+    className?: string;
+    style?: React.CSSProperties;
+    size?: "small" | "medium" | "large" | "inherit";
+    align?: "start" | "center" | "end";
+    wrap?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    ariaLabel?: string;
+    id?: string;
+    renderControl?: (context: SentenceFilterRenderContext) => React.ReactNode;
+    onOpenChange?: (key: string | null) => void;
+}
+/**
+ * An editorial, natural-language filter control. Values are native inline
+ * buttons and their editors open in an accessible non-modal dialog.
+ */
+export declare function SentenceFilter({ sentence, filters: controlledFilters, defaultFilters, definitions, onChange, as: As, className, style, size, align, wrap, disabled, readOnly, ariaLabel, id, renderControl, onOpenChange, }: SentenceFilterProps): React.ReactElement;
+export default SentenceFilter;

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Vega-Lite to Semiotic translator.
  * Converts a Vega-Lite spec into a Semiotic ChartConfig.
@@ -6,32 +7,32 @@
  * 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";
     aggregate?: string;
     scale?: {
         scheme?: string;
-        range?: any;
-        domain?: any;
+        range?: Array<string | number>;
+        domain?: Array<string | number | boolean | Date>;
     };
     axis?: {
         title?: string;
         labelAngle?: number;
     };
-    value?: any;
+    value?: string | number | boolean | null;
     bin?: boolean | {
         maxbins?: number;
     };
     stack?: boolean | string | null;
 }
 export interface VegaLiteSpec {
-    mark: string | {
+    mark: string | ({
         type: string;
-        [key: string]: any;
-    };
+    } & Datum);
     data?: {
-        values?: any[];
+        values?: Datum[];
         url?: string;
     };
     encoding?: Record<string, VegaLiteEncoding>;
@@ -40,9 +41,45 @@ export interface VegaLiteSpec {
     title?: string | {
         text: string;
     };
-    transform?: any[];
-    [key: string]: any;
+    transform?: Datum[];
+    layer?: VegaLiteSpec[];
+    hconcat?: VegaLiteSpec[];
+    vconcat?: VegaLiteSpec[];
+    concat?: VegaLiteSpec[];
+    facet?: Datum;
+    repeat?: Datum | string[];
+    params?: Datum[];
+    selection?: Datum;
+    usermeta?: Datum & {
+        idid?: Datum;
+    };
 }
+/** 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>;