semiotic 3.7.4 → 3.8.0

package/dist/components/charts/physics/physicsPilePhysics.d.ts

@@ -0,0 +1,41 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartLayout } from "./physicsChartShared";
+export interface PhysicsPileMechanicalSampleOptions {
+    categories?: readonly string[];
+    count?: number;
+    idPrefix?: string;
+    seed?: number;
+    unitValue?: number;
+}
+export interface PhysicsPileOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    categoryAccessor: ChartAccessor<TDatum, string>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    unitValue: number;
+    ballRadius: number;
+    seed: number;
+    size: [number, number];
+}
+export declare function generatePhysicsPileMechanicalSamples(options?: PhysicsPileMechanicalSampleOptions): Datum[];
+export interface PileTubeGeometry {
+    laneWidth: number;
+    tubeWidth: number;
+    ballDiameter: number;
+    perRow: number;
+    centerX: (index: number) => number;
+    pileHeight: (count: number) => number;
+}
+/**
+ * Column geometry shared by the pile builder and its projection overlay so the
+ * ghost bar's height is exactly the fill target the stacked units rise to reach.
+ * Units drop into a narrow tube (a few balls wide) so their count reads as
+ * height — a bar chart assembled from falling units, not a spreading heap.
+ */
+export declare function pileTubeGeometry(plot: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, categoryCount: number, ballRadius: number): PileTubeGeometry;
+export declare function buildPhysicsPile<TDatum extends Datum>(options: PhysicsPileOptions<TDatum>): PhysicsChartLayout;

package/dist/components/charts/physics/physicsProcessPrimitives.d.ts

@@ -0,0 +1,38 @@
+import type { PhysicsColliderBodyFilter, PhysicsColliderSpec, PhysicsColliderShape } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsSemanticItem, StreamPhysicsRegionEffect, StreamPhysicsRegionKind } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+export interface PhysicsProcessStage {
+    id: string;
+    label?: string;
+    description?: string;
+    kind?: StreamPhysicsRegionKind | string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface PhysicsProcessBodyGroup<TDatum extends Datum = Datum> {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    bodyIds?: readonly string[];
+    datum?: TDatum;
+    state?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export interface PhysicsProcessBoundaryOptions {
+    id?: string;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    friction?: number;
+    restitution?: number;
+    thickness?: number;
+}
+export declare function physicsProcessBoundaryColliders(shape: PhysicsColliderShape, options?: PhysicsProcessBoundaryOptions): PhysicsColliderSpec[];
+export declare function physicsProcessRegionSemanticItem(region: StreamPhysicsRegionEffect): PhysicsSemanticItem | null;
+export declare function physicsProcessStageSemanticItems(stages: readonly PhysicsProcessStage[]): PhysicsSemanticItem[];
+export declare function physicsProcessGroupSemanticItems<TDatum extends Datum>(groups: readonly PhysicsProcessBodyGroup<TDatum>[]): PhysicsSemanticItem[];

package/dist/components/charts/physics/processFlowPhysics.d.ts

@@ -0,0 +1,97 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsTypes";
+import { groupCompletionRows, type BodyGroupSpec, type ProcessVolumeLayout } from "../../recipes/processPhysics";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface ProcessFlowStageDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /** Relative width share along the route. */
+    share?: number;
+    /**
+     * Continuous forward force while bodies overlap the stage.
+     * Number form is `{ x: force, y: 0 }`.
+     */
+    force?: number | {
+        x?: number;
+        y?: number;
+    };
+    damping?: number;
+    /**
+     * Capacitated processing stand-in: throughput metadata + force/damping.
+     * Full queue DES is ProcessFlow controller territory later.
+     */
+    capacity?: {
+        unitsPerSecond: number;
+        /** Datum field used as work-units (stamped into attributes only for now). */
+        unitAccessor?: string;
+    };
+    /**
+     * Raise drag with a pressure scalar (or occupancy when provided at build time).
+     */
+    pressure?: boolean | {
+        pressure?: number;
+        occupancy?: number;
+        baseDamping?: number;
+        dampingPerUnit?: number;
+        energyPerUnit?: number;
+    };
+    /** Rework / bounce portal toward another stage id. */
+    portal?: {
+        targetStageId: string;
+        force?: {
+            x?: number;
+            y?: number;
+        };
+    };
+    /** Absorbing sink (completion / merge). */
+    absorb?: boolean;
+    kind?: StreamPhysicsRegionEffect["kind"];
+}
+export interface ProcessFlowPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    stages: readonly ProcessFlowStageDef[];
+    size: [number, number];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    stageAccessor?: ChartAccessor<TDatum, string>;
+    groupBy?: ChartAccessor<TDatum, string>;
+    groupLabelAccessor?: ChartAccessor<TDatum, string>;
+    workAccessor?: ChartAccessor<TDatum, number>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    ballRadius?: number;
+    seed?: number;
+    /** Horizontal process lane (default). */
+    route?: "horizontal";
+    groupCompletion?: "allAbsorbed" | "none";
+    /** Optional column x for feature/group anchors (plot-relative fraction 0–1). */
+    groupAnchorAlong?: number;
+    springStiffness?: number;
+    springDamping?: number;
+    gravityX?: number;
+    gravityY?: number;
+    settle?: boolean;
+}
+export interface ProcessFlowProjectionMetadata {
+    kind: "process-flow";
+    plot: PhysicsChartArea["plot"];
+    volume: ProcessVolumeLayout;
+    stages: Array<{
+        id: string;
+        label: string;
+        x: number;
+        width: number;
+        count: number;
+        capacity?: number;
+        absorb?: boolean;
+        portalTarget?: string;
+    }>;
+    groups: BodyGroupSpec[];
+    groupCompletion: ReturnType<typeof groupCompletionRows>;
+    regionEffects: StreamPhysicsRegionEffect[];
+}
+/**
+ * Build a capacitated multi-body process lane: stage regions, optional feature
+ * body-groups, springs toward stage centers, and a settled stage-count projection.
+ */
+export declare function buildProcessFlowPhysics<TDatum extends Datum>(options: ProcessFlowPhysicsOptions<TDatum>): PhysicsChartLayout;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -3,14 +3,22 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Time interval for binning */
     binSize: number;
     /** Chart dimensions as [width, height] */

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -3,13 +3,23 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
+import { type AggregateConfig } from "./aggregate";
+import { type EventTimeConfig } from "./eventTime";
 export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -106,6 +116,25 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     legendInteraction?: LegendInteractionMode;
     /** ID accessor for remove()/update() on the push API */
     pointIdAccessor?: string | ((d: Datum) => string);
+    /**
+     * Opt-in windowed aggregation over event-time. When set, pushed
+     * events are reduced into tumbling/hopping/session windows and the
+     * chart draws one mark per window (mean/sum/min/max/count) plus an
+     * optional ±σ or min–max band — render cost scales with the number of
+     * visible windows, not the arrival rate. This is the **aggregation
+     * window**, distinct from `windowMode`'s RingBuffer eviction.
+     */
+    aggregate?: AggregateConfig;
+    /**
+     * Opt-in event-time ingestion. Buffers pushed events for a bounded
+     * lateness/grace window and releases them to the chart in event-time
+     * order, so out-of-order or merged multi-source streams render
+     * monotonically instead of zigzagging. Late events (older than
+     * `watermark − lateness`) are dropped or kept per policy and surfaced
+     * via `onObservation` as `"late-data"`. Default-off; when unset the
+     * push path is byte-for-byte unchanged.
+     */
+    eventTime?: EventTimeConfig;
 }
 /**
  * RealtimeLineChart - Simplified wrapper for streaming line charts.

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -1,15 +1,23 @@
 import * as React from "react";
-import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
+import type { ArrowOfTime, WindowMode, Style, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -43,6 +51,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     timeExtent?: [number, number];
     /** Fixed value domain */
     valueExtent?: [number, number];
+    /** Value-axis scale. "symlog" supports signed values while compressing large magnitudes. */
+    yScaleType?: "linear" | "log" | "symlog";
     /** Extent padding factor */
     extentPadding?: number;
     /** Category accessor for color-coding dots */
@@ -59,6 +69,10 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     stroke?: string;
     /** Dot stroke width */
     strokeWidth?: number;
+    /** Per-datum dot style. Returned values override the top-level dot primitives and category color. */
+    pointStyle?: (datum: TDatum) => Style & {
+        r?: number;
+    };
     /** Show canvas-drawn axes */
     showAxes?: boolean;
     /** Background fill color */

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/aggregate.d.ts

@@ -0,0 +1,51 @@
+import { WindowAccumulator, type WindowType, type AggregateStat, type AggregateBand } from "../../realtime/WindowAccumulator";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Opt-in windowed-aggregation transform for realtime XY charts. With it
+ * set, pushed events are reduced into event-time windows and the chart
+ * draws one mark per window (mean / sum / min / max / count) plus an
+ * optional ±σ or min–max envelope — bounded render cost regardless of
+ * arrival rate.
+ */
+export interface AggregateConfig {
+    /** Window kind. @default "tumbling" */
+    window?: WindowType;
+    /** Window width — ms or a duration string (`"1m"`, `"10s"`, `"500ms"`). */
+    size: number | string;
+    /** Hop between hopping windows — ms or duration string. @default = size */
+    hop?: number | string;
+    /** Session inactivity gap — ms or duration string (session windows only). */
+    gap?: number | string;
+    /** Statistic rendered as the primary series. @default "mean" */
+    stat?: AggregateStat;
+    /** Envelope drawn around the series. @default "none" */
+    band?: AggregateBand;
+    /** Multiplier for the `stddev` band (drawn as value ± sigma·σ). @default 1 */
+    sigma?: number;
+    /** Keep at most this many most-recent windows. @default unbounded */
+    retain?: number;
+}
+export declare const AGG_TIME = "time";
+export declare const AGG_VALUE = "value";
+export declare const AGG_LOWER = "__aggLower";
+export declare const AGG_UPPER = "__aggUpper";
+export declare const AGG_PARTIAL = "__aggPartial";
+export declare const AGG_COUNT = "count";
+export declare const AGG_START = "__aggStart";
+export declare const AGG_END = "__aggEnd";
+/**
+ * Build a `WindowAccumulator` from a config, parsing duration strings.
+ * Returns `null` when the window width is unparseable, so the caller can
+ * skip aggregation rather than bucket on a zero-width window.
+ */
+export declare function createAccumulator(config: AggregateConfig): WindowAccumulator | null;
+/**
+ * Snapshot the accumulator into frame-ready rows. Each row carries the
+ * primary stat at `value`, the window midpoint at `time`, the band
+ * bounds (when a band is configured), and provenance fields (`count`,
+ * partial flag, raw start/end) for tooltips and partial-window styling.
+ */
+export declare function aggregatedRows(acc: WindowAccumulator, config: AggregateConfig): Datum[];
+/** Whether a config requests a band envelope. */
+export declare function hasBand(config: AggregateConfig): boolean;
+export type { AggregateStat, AggregateBand, WindowType };

package/dist/components/charts/realtime/eventTime.d.ts

@@ -0,0 +1,26 @@
+import { ReorderBuffer, type LatePolicy } from "../../realtime/ReorderBuffer";
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Opt-in event-time ingestion for realtime XY charts. Reorders pushed
+ * events within a bounded grace window so out-of-order arrivals render
+ * in event-time order, at the cost of delaying display by `lateness`.
+ */
+export interface EventTimeConfig {
+    /**
+     * Grace window — ms or a duration string (`"2s"`, `"500ms"`). Events
+     * whose time is older than `watermark − lateness` are late.
+     */
+    lateness: number | string;
+    /**
+     * What to do with a late event:
+     * - `"drop"` (default): discard it (still counted + surfaced).
+     * - `"keep"`: release it immediately, out of order (still counted).
+     */
+    latePolicy?: LatePolicy;
+}
+/**
+ * Build a `ReorderBuffer` from a config and a time accessor, parsing the
+ * lateness duration. Returns `null` when the lateness is unparseable so
+ * the caller can fall back to plain (in-order) ingestion.
+ */
+export declare function createReorderBuffer(config: EventTimeConfig, getTime: (d: Datum) => number): ReorderBuffer<Datum> | null;

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

@@ -0,0 +1,91 @@
+import type { Datum } from "./datumTypes";
+/**
+ * auditMobileVisualization - static mobile-readiness triage for Semiotic chart
+ * configurations.
+ *
+ * This is deliberately conservative: it does not inspect the DOM, resolved CSS,
+ * measured labels, rendered annotation boxes, or real input behavior. It flags
+ * risks that can be inferred from config/data and routes the rest to manual
+ * mobile review. Treat it like auditAccessibility: useful before render, useful
+ * for agents, not a certification.
+ */
+export type MobileAuditStatus = "pass" | "warn" | "manual" | "not-applicable";
+export type MobileAuditCategory = "layout" | "density" | "interaction" | "annotation" | "semantics";
+export type MobileAuditImpact = "high" | "medium" | "low";
+export interface MobileVisualizationFinding {
+    /** Stable id, e.g. "layout.fixed-desktop-size". */
+    id: string;
+    category: MobileAuditCategory;
+    status: MobileAuditStatus;
+    impact: MobileAuditImpact;
+    message: string;
+    fix?: string;
+}
+export interface MobileVisualizationAuditResult {
+    component: string;
+    viewportWidth: number;
+    /** True when no high-impact warning is present. */
+    ok: boolean;
+    summary: {
+        highRisk: number;
+        warnings: number;
+        manual: number;
+        passes: number;
+    };
+    findings: MobileVisualizationFinding[];
+    reference: string;
+}
+export interface AuditMobileVisualizationOptions {
+    /**
+     * Width to audit against. Defaults to 390px, a common modern phone CSS
+     * viewport width. Run multiple widths in CI for stronger coverage.
+     */
+    viewportWidth?: number;
+    /**
+     * Minimum acceptable pointer target. WCAG 2.2 Target Size (Minimum) is 24px;
+     * 44px is the comfortable phone target used here by default.
+     */
+    targetSize?: number;
+    /**
+     * Whether the chart is wrapped in a container that can provide summary text,
+     * controls, caption, download/copy affordances, or a details panel.
+     */
+    inChartContainer?: boolean;
+}
+export interface MobileVisualizationInteractionContract {
+    primary?: string;
+    alternatives?: string[];
+    hoverFallback?: string;
+    targetSize?: number;
+}
+export interface MobileVisualizationLabelContract {
+    strategy?: string;
+    minFontSize?: number;
+}
+export interface MobileVisualizationCustomContract {
+    dataBearingSceneNodes?: boolean;
+    stableIds?: boolean;
+    navigationGranularity?: string;
+}
+export interface MobileVisualizationContract {
+    strategy?: string;
+    responsive?: boolean;
+    supportsResponsiveLayout?: boolean;
+    breakpoints?: number[];
+    minViewportWidth?: number;
+    maxMarks?: number;
+    maxAnnotations?: number;
+    minimumHitTarget?: number;
+    summary?: boolean | string;
+    interaction?: MobileVisualizationInteractionContract;
+    labels?: MobileVisualizationLabelContract;
+    custom?: MobileVisualizationCustomContract;
+}
+/**
+ * Audit a Semiotic chart config for likely mobile visualization problems.
+ * Pure, SSR-safe, no DOM.
+ */
+export declare function auditMobileVisualization(component: string, props?: Datum, options?: AuditMobileVisualizationOptions): MobileVisualizationAuditResult;
+/** Render a mobile visualization audit result as a plain-text report. */
+export declare function formatMobileVisualizationAudit(result: MobileVisualizationAuditResult): string;
+export declare function mobileVisualizationCaveats(): string[];

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

@@ -0,0 +1,145 @@
+/**
+ * Additive ChartDefinition pilot registry.
+ *
+ * This is deliberately a descriptive, pure layer: it imports chart-spec
+ * metadata but never React components, frame stores, server renderers, or
+ * docs modules. The implementation, server, capability, and example links
+ * are strings so hosts can decide what to load. Existing registries remain
+ * authoritative while this seven-chart slice proves the boundary.
+ */
+import { type ChartCapabilities, type ChartCategory, type ChartPropSpec, type ChartSpec, type PropType } from "./chartSpecs";
+/** Version of the definition shape, independently from the package version. */
+export declare const CHART_DEFINITION_SCHEMA_VERSION: 1;
+/** Version of this intentionally small, additive pilot manifest. */
+export declare const CHART_DEFINITION_PILOT_VERSION: "1.0.0";
+export declare const CHART_DEFINITION_PILOT_IDS: readonly ["LineChart", "BarChart", "ForceDirectedGraph", "FlowMap", "GaltonBoardChart", "RealtimeLineChart", "BigNumber"];
+export type ChartDefinitionPilotId = (typeof CHART_DEFINITION_PILOT_IDS)[number];
+export type WireJsonType = Exclude<PropType, "function">;
+/**
+ * Strictly serializable portion of a runtime prop. Function-only and
+ * `omitFromSchema` props live in `runtimeOnlyProps`; mixed string/function
+ * accessors retain their serializable string form and name their broader
+ * runtime contract in the extension field.
+ */
+export interface ChartDefinitionWireProperty {
+    readonly type: WireJsonType | readonly WireJsonType[];
+    readonly enum?: readonly string[];
+    readonly default?: unknown;
+    readonly description?: string;
+    readonly "x-semiotic-runtime-types"?: readonly PropType[];
+}
+export interface ChartDefinitionWireSchema {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, ChartDefinitionWireProperty>>;
+    readonly required: readonly string[];
+    /** Runtime props deliberately absent from the serializable wire surface. */
+    readonly "x-semiotic-runtime-only-props": readonly string[];
+}
+/** A string reference prevents the definition registry from loading React. */
+export interface LazyImplementationReference {
+    readonly module: string;
+    readonly exportName: string;
+}
+export type ChartDefinitionServerSupport = {
+    readonly mode: "render-chart";
+    readonly chartConfig: string;
+} | {
+    readonly mode: "react-ssr-only";
+    readonly reason: string;
+} | {
+    readonly mode: "unavailable";
+    readonly reason: string;
+};
+/**
+ * References into the current docs surface. They remain links for now: the
+ * future ExampleDefinition registry will become the source of truth for them.
+ */
+export interface ChartDefinitionExampleReference {
+    /** `chart-doc` is an interactive documentation demo pending ExampleDefinition migration. */
+    readonly kind?: "example" | "chart-doc";
+    readonly route: string;
+    readonly source: string;
+}
+/** Explicitly additive lifecycle truth; no pilot chart is deprecated. */
+export interface ChartDefinitionLifecycle {
+    readonly status: "stable" | "experimental" | "deprecated" | "internal";
+    readonly since?: string;
+    readonly deprecation?: {
+        readonly since: string;
+        readonly replacement?: string;
+    };
+}
+/** Public docs page and the component identifier consumed by PropTable. */
+export interface ChartDefinitionPropDocs {
+    readonly componentName: string;
+    readonly route: string;
+    readonly source: string;
+}
+export interface ChartDefinitionMetadata {
+    readonly description: string;
+    /** Reused directly from ChartSpec while the existing capability registry leads. */
+    readonly capabilities: ChartCapabilities;
+    readonly capabilityModule: string;
+    readonly chartSpec: string;
+    readonly aiSchemaName: string;
+    readonly lifecycle: ChartDefinitionLifecycle;
+    readonly propDocs: ChartDefinitionPropDocs;
+    readonly support: {
+        readonly browser: "react";
+        readonly server: ChartDefinitionServerSupport;
+    };
+    readonly examples: readonly ChartDefinitionExampleReference[];
+}
+/**
+ * Minimal RFC-aligned manifest shape for the pilot. `wire` is intentionally
+ * serializable; richer prop metadata and lazy implementation references stay
+ * under `runtime`.
+ */
+export interface ChartDefinition<TChart extends string = string> {
+    readonly schemaVersion: typeof CHART_DEFINITION_SCHEMA_VERSION;
+    readonly chartFamily: ChartCategory;
+    readonly chartKind: TChart;
+    readonly wire: {
+        readonly chart: TChart;
+        readonly version: typeof CHART_DEFINITION_PILOT_VERSION;
+        readonly schema: ChartDefinitionWireSchema;
+    };
+    readonly runtime: {
+        readonly propMetadata: Readonly<Record<string, ChartPropSpec>>;
+        readonly implementation: LazyImplementationReference;
+    };
+    readonly metadata: ChartDefinitionMetadata;
+}
+/**
+ * Build a strict wire schema from the current ChartSpec without duplicating
+ * the public prop declaration. This deliberately differs from the legacy AI
+ * schema generator: a function-only prop is omitted here rather than emitted
+ * as an unconstrained JSON-schema property, because a function cannot cross a
+ * persisted/MCP wire boundary.
+ */
+export declare function createChartDefinitionWireSchema(spec: ChartSpec): ChartDefinitionWireSchema;
+/**
+ * One representative per chart family. No existing consumer reads this yet;
+ * its purpose is to make parity and generation work executable before any
+ * registry is migrated.
+ */
+export declare const CHART_DEFINITION_PILOT: Readonly<{
+    [TChart in ChartDefinitionPilotId]: ChartDefinition<TChart>;
+}>;
+export interface ChartDefinitionArtifact {
+    readonly chart: string;
+    readonly schemaVersion: typeof CHART_DEFINITION_SCHEMA_VERSION;
+    readonly wire: ChartDefinition["wire"];
+    readonly runtime: {
+        readonly implementation: LazyImplementationReference;
+        readonly propNames: readonly string[];
+    };
+    readonly metadata: ChartDefinitionMetadata;
+}
+/**
+ * Pure generation hook for future schema/docs/registry emitters. Its output is
+ * JSON-serializable and intentionally has no component or server imports.
+ */
+export declare function generateChartDefinitionArtifacts(registry?: Readonly<Record<string, ChartDefinition>>): readonly ChartDefinitionArtifact[];
+export declare function getChartDefinition(chart: string): ChartDefinition<ChartDefinitionPilotId> | undefined;