semiotic 3.7.5 → 3.8.1

package/ai/surface-manifest.json

@@ -0,0 +1,201 @@
+{
+  "__generated": true,
+  "__source": [
+    "package.json",
+    "ai/schema.json",
+    "ai/componentMetadata.cjs",
+    "src/components/semiotic-ai.ts",
+    "ai/mcp-server.ts"
+  ],
+  "version": "3.8.1",
+  "components": {
+    "schema": 54,
+    "aiChartExports": 51,
+    "mcpRenderable": 48,
+    "browserOnly": 6,
+    "categories": {
+      "xy": [
+        "AreaChart",
+        "BubbleChart",
+        "CandlestickChart",
+        "ConnectedScatterplot",
+        "DifferenceChart",
+        "Heatmap",
+        "LineChart",
+        "MinimapChart",
+        "MultiAxisLineChart",
+        "QuadrantChart",
+        "Scatterplot",
+        "ScatterplotMatrix",
+        "StackedAreaChart"
+      ],
+      "ordinal": [
+        "BarChart",
+        "BoxPlot",
+        "DonutChart",
+        "DotPlot",
+        "FunnelChart",
+        "GaugeChart",
+        "GroupedBarChart",
+        "Histogram",
+        "LikertChart",
+        "PieChart",
+        "RidgelinePlot",
+        "StackedBarChart",
+        "SwarmPlot",
+        "SwimlaneChart",
+        "ViolinPlot"
+      ],
+      "network": [
+        "ChordDiagram",
+        "CirclePack",
+        "ForceDirectedGraph",
+        "OrbitDiagram",
+        "ProcessSankey",
+        "SankeyDiagram",
+        "TreeDiagram",
+        "Treemap"
+      ],
+      "geo": [
+        "ChoroplethMap",
+        "DistanceCartogram",
+        "FlowMap",
+        "ProportionalSymbolMap"
+      ],
+      "realtime": [
+        "RealtimeHeatmap",
+        "RealtimeHistogram",
+        "RealtimeLineChart",
+        "RealtimeSwarmChart",
+        "RealtimeWaterfallChart",
+        "TemporalHistogram"
+      ],
+      "physics": [
+        "CollisionSwarmChart",
+        "EventDropChart",
+        "GaltonBoardChart",
+        "GauntletChart",
+        "PhysicalFlowChart",
+        "PhysicsPileChart",
+        "ProcessFlowChart"
+      ],
+      "value": [
+        "BigNumber"
+      ]
+    },
+    "aiChartExportNames": [
+      "AreaChart",
+      "BarChart",
+      "BigNumber",
+      "BoxPlot",
+      "BubbleChart",
+      "CandlestickChart",
+      "ChordDiagram",
+      "CirclePack",
+      "CollisionSwarmChart",
+      "ConnectedScatterplot",
+      "DifferenceChart",
+      "DonutChart",
+      "DotPlot",
+      "EventDropChart",
+      "ForceDirectedGraph",
+      "FunnelChart",
+      "GaltonBoardChart",
+      "GaugeChart",
+      "GauntletChart",
+      "GroupedBarChart",
+      "Heatmap",
+      "Histogram",
+      "LikertChart",
+      "LineChart",
+      "MinimapChart",
+      "MultiAxisLineChart",
+      "OrbitDiagram",
+      "PhysicalFlowChart",
+      "PhysicsCustomChart",
+      "PhysicsPileChart",
+      "PieChart",
+      "ProcessFlowChart",
+      "ProcessSankey",
+      "QuadrantChart",
+      "RealtimeHeatmap",
+      "RealtimeHistogram",
+      "RealtimeLineChart",
+      "RealtimeSwarmChart",
+      "RealtimeWaterfallChart",
+      "RidgelinePlot",
+      "SankeyDiagram",
+      "Scatterplot",
+      "ScatterplotMatrix",
+      "StackedAreaChart",
+      "StackedBarChart",
+      "SwarmPlot",
+      "SwimlaneChart",
+      "TemporalHistogram",
+      "TreeDiagram",
+      "Treemap",
+      "ViolinPlot"
+    ],
+    "geoExcludedFromAIExports": [
+      "ChoroplethMap",
+      "DistanceCartogram",
+      "FlowMap",
+      "ProportionalSymbolMap"
+    ]
+  },
+  "mcp": {
+    "toolCount": 23,
+    "tools": [
+      "applyTheme",
+      "auditAccessibility",
+      "auditChart",
+      "auditMobileVisualization",
+      "createChart",
+      "diagnoseConfig",
+      "explainChart",
+      "getChartSchema",
+      "getSchema",
+      "groundChart",
+      "improveChart",
+      "interrogateChart",
+      "proposeChartVariants",
+      "renderChart",
+      "renderInteractiveChart",
+      "repairChartConfig",
+      "reportIssue",
+      "suggestChart",
+      "suggestCharts",
+      "suggestDashboard",
+      "suggestStreamCharts",
+      "suggestStretchCharts",
+      "suggestTokenEncoding"
+    ],
+    "publicProfile": {
+      "toolCount": 5,
+      "tools": [
+        "createChart",
+        "improveChart",
+        "explainChart",
+        "auditChart",
+        "getChartSchema"
+      ],
+      "activation": "semiotic-mcp --profile public or MCP_TOOL_PROFILE=public"
+    },
+    "resourceCount": 8,
+    "resources": [
+      "semiotic-behavior-contracts",
+      "semiotic-build-info",
+      "semiotic-chatgpt-chart-widget",
+      "semiotic-components",
+      "semiotic-examples",
+      "semiotic-schema",
+      "semiotic-surface-manifest",
+      "semiotic-system-prompt"
+    ],
+    "promptCount": 2,
+    "prompts": [
+      "build-semiotic-chart",
+      "debug-semiotic-chart"
+    ]
+  }
+}

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-**Use sub-path imports** — `semiotic/xy` (96KB gz), `semiotic/ordinal` (78KB gz), `semiotic/network` (73KB gz), `semiotic/geo` (57KB gz), `semiotic/realtime` (104KB gz), `semiotic/server` (132KB gz), `semiotic/utils` (39KB gz), `semiotic/recipes` (19KB gz), `semiotic/themes` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (269KB gz). Full `semiotic` is 216KB gz.
+**Use sub-path imports** — `semiotic/xy` (108KB gz), `semiotic/ordinal` (88KB gz), `semiotic/network` (93KB gz), `semiotic/geo` (66KB gz), `semiotic/realtime` (119KB gz), `semiotic/realtime/core` (118KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (124KB gz), `semiotic/server/node` (124KB gz), `semiotic/server/edge` (123KB gz), `semiotic/utils` (59KB gz), `semiotic/utils/core` (58KB gz), `semiotic/utils/react` (4KB gz), `semiotic/recipes` (53KB gz), `semiotic/recipes/core` (52KB gz), `semiotic/recipes/react` (1KB gz), `semiotic/themes` (6KB gz), `semiotic/themes/core` (6KB gz), `semiotic/themes/react` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (104KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (394KB gz), `semiotic/ai/core` (67KB gz), `semiotic/controls` (10KB gz), `semiotic/rough` (3KB gz). Full `semiotic` is 251KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
@@ -33,7 +33,7 @@ All ordinal HOCs (except Pie/Donut) support `categoryFormat` — a function `(la
 - **OrbitDiagram** — animated radial/orbital hierarchy (use this, not TreeDiagram, for animated orbiting nodes). `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`. For static radial trees use `TreeDiagram layout="radial"`.
 
 ## Network Data (`nodes: object[]`, `edges: object[]`)
-- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize` (number|string|fn), `nodeSizeRange`, `edgeWidth`, `edgeOpacity`, `iterations`, `forceStrength`, `showLabels`, `nodeLabel`, `tooltip`, `showLegend`
+- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize` (number|string|fn), `nodeSizeRange`, `edgeWidth`, `edgeOpacity`, `iterations`, `forceStrength`, `layoutExecution` (`auto`|`worker`|`sync`), `showLabels`, `nodeLabel`, `tooltip`, `showLegend`
 - **SankeyDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 - **ChordDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 
@@ -54,6 +54,16 @@ Sizing: all Realtime HOCs accept both `size={[600, 400]}` (tuple) and `width={60
 
 Pushed data shape: `{ time: Date.now(), value: 42 }` for line/waterfall/heatmap, add `category` for histogram/swarm.
 
+## Physics (`semiotic/physics`)
+
+Use only when motion maps to the data semantics; the settled projection is what readers should use for the chart. Import from `semiotic/physics`.
+
+- **GaltonBoardChart** — `data`, `valueAccessor` ("value"), `bins`, `mode` ("sample"|"mechanical"), `pegRows`, `mechanicalCount`, `branchProbability`, `colorBy`, `seed`, `size`. Distribution/sampling drop that settles into bins; mechanical mode can generate a seeded no-data demonstration.
+- **EventDropChart** — `data`, `timeAccessor` ("time"), `arrivalAccessor` ("arrivalTime"), `windows={{size}}`, `watermark={{delay}}`, `timeScale`, `colorBy`, `size`. Event-time arrival replay and late/watermark windows.
+- **PhysicsPileChart** — `data`, `categoryAccessor` ("category"), `valueAccessor` ("value"), `mode` ("sample"|"mechanical"), `mechanicalCount`, `mechanicalCategories`, `unitValue`, `colorBy`, `showProjection`, `size`. Unitized category piles; mechanical mode can generate a seeded no-data capacity sketch; default projection overlay keeps exact totals readable; raise `unitValue` for large values.
+- **CollisionSwarmChart** — `data`, `xAccessor` ("x"), optional `groupAccessor`, `radiusAccessor`, `xExtent`, `collisionIterations`, `settle`, `showProjection`, `colorBy`, `size`. Collision-relaxed dot-strip/swarm chart that preserves quantitative axis position and optional group lanes.
+- **PhysicsCustomChart** — `data`, `layout(ctx)`, `layoutConfig`, `config`, `colorBy`, `size`. Escape hatch for bespoke physics scenes; layouts return bodies/colliders/sensors plus optional SVG overlays.
+
 ### Push API on HOC charts
 Many HOC charts support the push API via `forwardRef`. **Omit the `data` prop** (do NOT pass `data={[]}`) and push imperatively:
 ```jsx
@@ -79,12 +89,13 @@ For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdin
 `onClick={(datum, { x, y }) => ...}` — called when a data element is clicked. Receives the original datum and pixel coordinates. Works on lines, bars, areas, pie slices, nodes, and geo features.
 
 ### onObservation
-Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selection", datum: <your data>, x, y, timestamp, chartType, chartId }`. The `datum` field is your original data object. Hover-end/click-end events omit `datum`.
+Callback receiving `ChartObservation`. Pointer exploration emits `hover`/`click`; keyboard or structured traversal additionally emits semantic `focus`/`activate` with `inputType: "keyboard"|"pointer"|"touch"|"navigation-tree"`. Stable widget annotations emit `annotation-activate` with `annotationId`. Events also include `timestamp`, `chartType`, and optional `chartId`; datum events carry your original data object. Hover-end/click-end events omit `datum`.
 
 ### emphasis
 `emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
 
 ## Annotations (all chart families)
+- Give interactive `widget` annotations an `id`, `stableId`, or `provenance.stableId`; activation identity never falls back to array index. Observe widget activation on Stream Frames with `onAnnotationActivate`, or on HOCs through `frameProps.onAnnotationActivate`.
 - `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050", labelPosition: "right" }]}` — horizontal reference line (works on XY and vertical ordinal charts). `labelPosition`: "left"|"center"|"right"
 - `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff", labelPosition: "top" }]}` — vertical reference line. `labelPosition`: "top"|"center"|"bottom"
 - `annotations={[{ type: "callout-circle", x: 5, y: 20, label: "Peak", radius: 12 }]}` — data-bound callout; use `callout-rect` with `width`/`height` for a rectangular subject
@@ -94,6 +105,11 @@ Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selecti
 - `autoPlaceAnnotations={{ density: true, progressiveDisclosure: true, redundantCues: true }}` — opt-in placement, clutter management, and non-color association support
 - Annotation metadata: `emphasis`, `defensive`, `provenance`, and `lifecycle`; use `applyAnnotationLifecycle`, `applyAnnotationStatus`, and `filterAnnotationsByStatus` from `semiotic/ai`
 
+## ISOTYPE & Icon Size Guidance
+- Repeated pictograms, semantic icons, and glyph tokens should be visibly legible in the final rendered layout. Treat 16px as the minimum intended rendered icon dimension for ISOTYPE/icon-array designs.
+- This is design guidance, not a Semiotic-enforced minimum. Low-level helpers may default smaller for dense or sparkline-like contexts, so set `tokenSize`, glyph `size`, SVG slots, or wrapping explicitly when producing AI-authored examples.
+- If the available width would shrink icons below that visual floor, wrap the tokens into multiple rows/columns, reduce the number of visible tokens, change the unit value, or choose a non-icon encoding instead of shipping tiny pictograms.
+
 ## Theming & Brand Styling
 All charts respond to CSS custom properties on any ancestor:
 ```css
@@ -142,6 +158,6 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 - **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
 - **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderChartWithEvidence()` returns `{ svg, evidence }` (mark counts by scene type, axis domains, empty flag, annotation count, accessible name) so agents can verify the render drew data marks. `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
 - **CLI**: `npx semiotic-ai --list` shows components/import paths/renderability; `npx semiotic-ai --schema GaugeChart` prints one component schema with metadata; `--doctor` validates props JSON and behavior contracts.
-- **MCP**: `npx semiotic-mcp` exposes schema, suggestion, diagnosis, accessibility, grounding, issue, theme, static render (`renderChart`), and ChatGPT Apps render (`renderInteractiveChart`) tools. Resources include `semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`, and the widget template `ui://semiotic/chart-widget.html`. Prompts: `build-semiotic-chart`, `debug-semiotic-chart`.
+- **MCP**: `npx semiotic-mcp` exposes schema, chart suggestion, token-encoding suggestion (`suggestTokenEncoding` for ISOTYPE/dot/icon arrays), diagnosis, accessibility, grounding, issue, theme, static render (`renderChart`), and ChatGPT Apps render (`renderInteractiveChart`) tools. Resources include `semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`, and the widget template `ui://semiotic/chart-widget.html`. Prompts: `build-semiotic-chart`, `debug-semiotic-chart`.
 - **Data Pitfalls bridge**: `toDataPitfallsChain(component, props, { rendered, context, narrative })` from `semiotic/ai` returns a dependency-free `datapitfalls` chain input containing config, JSX, reader grounding, diagnostics, accessibility audit, and optional render evidence/image.
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/__tests__/scenarios/mcpProtocolTypes.d.ts

@@ -0,0 +1,20 @@
+import type { Datum } from "../../components/charts/shared/datumTypes";
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result: Datum;
+    error?: Datum;
+}
+export interface ListedMcpTool {
+    name: string;
+    _meta?: {
+        ui?: {
+            resourceUri: string;
+        };
+        "openai/outputTemplate"?: string;
+    };
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+    };
+}

package/dist/components/AccessibleNavTree.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import { type NavTreeNode } from "./ai/navigationTree";
+import { type OnObservationCallback } from "./store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "./charts/shared/annotationActivation";
 export interface AccessibleNavTreeProps {
     tree: NavTreeNode;
     /** Accessible name for the tree. */
@@ -22,5 +24,9 @@ export interface AccessibleNavTreeProps {
      * the conversation-arc store is enabled — zero-overhead otherwise.
      */
     chartId?: string;
+    /** Normalized focus/activation events produced by structured navigation. */
+    onObservation?: OnObservationCallback;
+    /** Observe activation of an annotation leaf in the navigation tree. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
 }
-export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId }: AccessibleNavTreeProps): React.JSX.Element;
+export declare function AccessibleNavTree({ tree, label, visible, className, onActiveChange, activeId: controlledActiveId, chartId, onObservation, onAnnotationActivate }: AccessibleNavTreeProps): React.JSX.Element;

package/dist/components/CategoryColors.d.ts

@@ -14,7 +14,7 @@ export interface CategoryColorProviderProps {
      */
     categories?: string[];
     /** Color scheme to use for auto-assignment. Default: "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     children: React.ReactNode;
 }
 /**

package/dist/components/ChartContainer.d.ts

@@ -1,6 +1,62 @@
 import * as React from "react";
 import type { ChartConfig, CopyFormat } from "./export/chartConfig";
 import { type DescribeLevel } from "./ai/describeChart";
+import type { ChartMode, MobileInteractionProp } from "./charts/shared/types";
+import { type MobileStandardControlRequest, type MobileStandardControlsProps } from "./MobileStandardControls";
+import { type MobileVisualizationContract } from "./charts/shared/auditMobileVisualization";
+export type ChartNotificationLevel = "info" | "success" | "warning" | "error" | "neutral";
+/**
+ * One entry in a ChartContainer's notification stack — chart-level context
+ * that has no single mark to anchor to: an audit or data-pitfall finding, a
+ * data-quality result that couldn't be placed on the plot, or any
+ * user-authored notice about the chart as a whole.
+ */
+export interface ChartNotification {
+    /** Stable identity — keys dismissal across re-renders. Falls back to the
+     *  array index, so pass an `id` whenever the list can reorder or stream. */
+    id?: string;
+    /** Maps to the theme's semantic role color. Default: "info". */
+    level?: ChartNotificationLevel;
+    /** Short bold lead-in (e.g. the finding name). */
+    title?: string;
+    /** Body content. */
+    message: React.ReactNode;
+    /** Small uppercase origin tag (e.g. "datapitfalls · Graphical Gaffes"). */
+    source?: string;
+    /** Default true. Set false for must-see notices that can't be dismissed. */
+    dismissible?: boolean;
+}
+export interface ChartContainerMobileOptions {
+    /** Width at or below which the container applies mobile CSS affordances. Default 480. */
+    breakpoint?: number;
+    /** Semantic mobile contract passed to child charts that do not already declare one. */
+    semantics?: MobileVisualizationContract;
+    /** Default chart mode to inject into a single child chart when it has no mode. Pass false to disable. */
+    chartMode?: ChartMode | false;
+    /** Touch-first interaction policy passed to child charts that do not already declare one. */
+    mobileInteraction?: MobileInteractionProp;
+    /**
+     * Render touch-sized fallback controls for complex mobile gestures. Pass a
+     * control request ("brush", "zoom", "legend", "all", true, or an array) or
+     * a full MobileStandardControls config with callbacks and state.
+     */
+    standardControls?: MobileStandardControlRequest | MobileStandardControlsProps;
+    /** Mobile-only summary rendered between header and chart body. */
+    summary?: React.ReactNode;
+    /** Let a non-transformed chart scroll horizontally rather than clip. Prefer responsiveRules when possible. */
+    allowHorizontalScroll?: boolean;
+    /** Hide toolbar controls behind CSS at phone width. Default false. */
+    hideToolbar?: boolean;
+}
+export interface ChartContainerMobileAuditOptions {
+    /** Phone viewport used for the authoring audit. Default 390. */
+    viewportWidth?: number;
+    /** Expected touch target size in CSS pixels. Default 44. */
+    targetSize?: number;
+    /** Render a visible warning banner in addition to console warnings. */
+    visible?: boolean;
+}
+export type ChartContainerMobileAudit = boolean | "warn" | ChartContainerMobileAuditOptions;
 export interface ChartContainerProps {
     /** Chart title */
     title?: string;
@@ -60,6 +116,28 @@ export interface ChartContainerProps {
     };
     /** Additional controls rendered in the toolbar after built-in actions */
     controls?: React.ReactNode;
+    /**
+     * Persistent content rendered between the header and chart body. Useful for
+     * data-source notices, refresh actions, and other status banners that should
+     * remain visible while the chart is loading.
+     */
+    banner?: React.ReactNode;
+    /**
+     * Chart-level notices rendered as a dismissible, severity-leveled stack
+     * between the header and the chart body — the surface for findings that
+     * have no mark to anchor to (a data-pitfalls or audit finding about the
+     * whole chart, an unplaceable data-quality result) and for any custom
+     * user-authored notice. The stack is an `aria-live="polite"` status region,
+     * so notifications that arrive while streaming are announced.
+     */
+    notifications?: ChartNotification[];
+    /**
+     * Called when a notification's dismiss button is clicked. Dismissal state
+     * is tracked internally (keyed by `notification.id`, falling back to array
+     * index) whether or not this is provided — use the callback to sync your
+     * own store or telemetry.
+     */
+    onNotificationDismiss?: (notification: ChartNotification, index: number) => void;
     /** Loading state — shows skeleton placeholder */
     loading?: boolean;
     /** Error state — shows error message (overrides children) */
@@ -70,6 +148,19 @@ export interface ChartContainerProps {
     status?: "live" | "stale" | "paused" | "error" | "static";
     /** Details panel rendered alongside the chart (e.g. DetailsPanel component) */
     detailsPanel?: React.ReactNode;
+    /**
+     * Mobile container affordances. Does not resize the chart by itself; it
+     * provides mobile semantics, optional child `mode`, summary placement, and
+     * narrow-viewport CSS so ChartContainer participates in the same mobile
+     * contract as chart HOCs, custom recipes, and audits.
+     */
+    mobile?: boolean | ChartContainerMobileOptions;
+    /**
+     * Optional authoring-time mobile audit. Requires `chartConfig`; `"warn"` logs
+     * mobile findings to the console, while `{ visible: true }` also renders a
+     * compact warning banner in the container.
+     */
+    mobileAudit?: ChartContainerMobileAudit;
     /** CSS class for the outer container */
     className?: string;
     /** Inline style overrides */

package/dist/components/ChartGrid.d.ts

@@ -9,6 +9,16 @@ export interface ChartGridProps {
     minCellWidth?: number;
     /** Gap between cells in pixels. Default: 16 */
     gap?: number;
+    /** Columns between mobile and tablet breakpoints. Leave undefined to use the base grid. */
+    tabletColumns?: number;
+    /** Columns at the mobile breakpoint. Default: 1 */
+    mobileColumns?: number;
+    /** Mobile breakpoint used by generated CSS. Default 480. */
+    mobileBreakpoint?: number;
+    /** Tablet breakpoint used by generated CSS. Default 860. */
+    tabletBreakpoint?: number;
+    /** Defaults injected into direct child charts when the child has not declared the prop. */
+    chartDefaults?: Record<string, unknown>;
     /** CSS class for the grid container */
     className?: string;
     /** Inline style overrides */
@@ -33,7 +43,7 @@ export interface ChartGridProps {
  * </ChartGrid>
  * ```
  */
-export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
+export declare function ChartGrid({ children, columns, minCellWidth, gap, tabletColumns, mobileColumns, mobileBreakpoint, tabletBreakpoint, chartDefaults, className, style, }: ChartGridProps): React.JSX.Element;
 export declare namespace ChartGrid {
     var displayName: string;
 }

package/dist/components/CircularBrush.d.ts

@@ -0,0 +1,61 @@
+import * as React from "react";
+/**
+ * `CircularBrush` — an accessible range brush over a **cyclical** domain
+ * (day-of-year, hour-of-day, compass bearing, phase). The radial counterpart to
+ * the linear `RealtimeHistogram` brush: a selected arc with two draggable
+ * handles, wrap-around ranges, pointer-capture drag, and full keyboard control.
+ *
+ * **Control-surface contract.** This is a *control*, not a chart: it takes
+ * `value` + `domain`/`period` + geometry + `onChange`, and never reaches into a
+ * chart's internals. Layer it over a chart that shares its coordinate space (an
+ * absolutely-positioned overlay, or embed its `<g>` in the chart's SVG) and feed
+ * `onChange` into your own state — or into the linked-selection store — so the
+ * brush drives a selection without a provider. Geometry in, value out.
+ *
+ * **Accessibility.** Each handle and the range itself is a `role="slider"` with
+ * `aria-valuemin/max/now` (and `aria-valuetext` when `formatValue` is given),
+ * reachable by Tab and nudgeable with ←/→ (Shift = `largeStep`). Built on the
+ * tested radial (`polarToXY`/`xyToAngle`/`ringArcPath`) + cyclical
+ * (`wrapValue`/`shortestArcDelta`) kit, so wrap-around never unwinds the long way.
+ */
+export interface CircularBrushValue {
+    /** Range start, in domain units (e.g. day-of-year). */
+    start: number;
+    /** Range end, in domain units. When `start > end` the range wraps the cycle. */
+    end: number;
+}
+export interface CircularBrushProps {
+    /** The current selected range. Controlled. */
+    value: CircularBrushValue;
+    /** Called with the next value, or an updater — mirrors `setState`, so you can
+     *  pass a `useState` setter directly. */
+    onChange: (next: CircularBrushValue | ((current: CircularBrushValue) => CircularBrushValue)) => void;
+    /** Cycle length in domain units. @default 365 (day-of-year) */
+    period?: number;
+    /** Outer radius of the brush ring, px. @default 180 */
+    radius?: number;
+    /** Inner radius of the brush band, px. @default 14 */
+    innerRadius?: number;
+    /** SVG width, px. @default `radius * 2 + 40` */
+    width?: number;
+    /** SVG height, px. @default `radius * 2 + 40` */
+    height?: number;
+    /** Keyboard nudge step (←/→), domain units. @default 1 */
+    step?: number;
+    /** Shift+arrow step, domain units. @default 7 */
+    largeStep?: number;
+    /** Accessible label prefix for the handles + range. @default "Range" */
+    label?: string;
+    /** Format a domain value for `aria-valuetext` (e.g. a date). */
+    formatValue?: (value: number) => string;
+    /** Brush arc fill. @default a translucent primary */
+    arcFill?: string;
+    /** Brush arc + handle stroke. @default white */
+    stroke?: string;
+    className?: string;
+    /** Inline style for the root `<svg>`. Use it to position the control as an
+     *  overlay over a chart sharing its coordinate space — e.g.
+     *  `{ position: "absolute", inset: 0, width: "100%", height: "100%" }`. */
+    style?: React.CSSProperties;
+}
+export declare function CircularBrush({ value, onChange, period, radius, innerRadius, width, height, step, largeStep, label, formatValue, arcFill, stroke, className, style, }: CircularBrushProps): React.ReactElement;

package/dist/components/ContextLayout.d.ts

@@ -8,6 +8,10 @@ export interface ContextLayoutProps {
     position?: "right" | "left" | "bottom" | "top";
     /** Size of the context panel in pixels. Default: 250 */
     contextSize?: number;
+    /** Mobile context placement. Default: "bottom" */
+    mobilePosition?: "top" | "bottom" | "preserve";
+    /** Mobile breakpoint used by generated CSS. Default 480. */
+    mobileBreakpoint?: number;
     /** Gap between primary and context panels in pixels. Default: 12 */
     gap?: number;
     /** CSS class for the layout container */
@@ -32,7 +36,7 @@ export interface ContextLayoutProps {
  * </ContextLayout>
  * ```
  */
-export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
+export declare function ContextLayout({ children, context, position, contextSize, mobilePosition, mobileBreakpoint, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
 export declare namespace ContextLayout {
     var displayName: string;
 }

package/dist/components/DirectManipulationControl.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+import type { ControlObservationCallback, VisualizationControlType } from "./controls/controlContract";
+export { VISUALIZATION_CONTROL_TYPES } from "./controls/controlContract";
+export type { ControlObservation, ControlObservationCallback, ControlObservationPhase, VisualizationControlDefinition, VisualizationControlType, VisualizationControlValue, } from "./controls/controlContract";
+export interface DirectManipulationControlProps {
+    /** Controlled numeric value expressed in the chart's data domain. */
+    value: number;
+    /** Called on pointer drag or keyboard nudge. */
+    onChange: (value: number) => void;
+    /** Convert a pointer event in the control's frame coordinate space to a value. */
+    pointerToValue: (event: React.PointerEvent<SVGGElement>) => number | null | undefined;
+    /** Inclusive value domain. */
+    min: number;
+    max: number;
+    /** Keyboard and pointer quantization step. @default 1 */
+    step?: number;
+    /** Shift+arrow nudge. @default step * 5 */
+    largeStep?: number;
+    /** Position in the shared SVG/frame coordinate space. */
+    x: number;
+    y: number;
+    /** Semantic machine-readable control classification. */
+    controlType?: VisualizationControlType;
+    /** Stable identity for observations, audits, and portable recipes. */
+    controlId?: string;
+    /** Accessible label. */
+    label: string;
+    /** Optional human-readable current value. */
+    valueText?: string;
+    /** Handle radius in CSS/SVG pixels. @default 12 */
+    radius?: number;
+    /** Handle fill. Defaults to the active Semiotic surface token. */
+    fill?: string;
+    /** Handle stroke. Defaults to the active Semiotic primary token. */
+    stroke?: string;
+    strokeWidth?: number;
+    /** Optional text rendered next to the handle. */
+    labelText?: React.ReactNode;
+    labelDx?: number;
+    labelDy?: number;
+    labelClassName?: string;
+    className?: string;
+    disabled?: boolean;
+    onChangeStart?: (value: number) => void;
+    onChangeEnd?: (value: number) => void;
+    /** Optional adapter to the same onObservation stream used by frames. */
+    onObservation?: ControlObservationCallback;
+    /** Owning chart identity when this control is layered over a frame. */
+    chartId?: string;
+    /** Owning frame/chart name used by control observations. */
+    chartType?: string;
+}
+/**
+ * A small SVG-native control surface for a chart that owns its own scales.
+ *
+ * `DirectManipulationControl` deliberately does not know about a particular
+ * Semiotic frame. The chart supplies `pointerToValue`, making this usable in
+ * XY, ordinal, geographic, radial, and custom-layout overlays without the
+ * control reaching into frame internals. It contributes the repeated parts
+ * every visualization control needs: pointer capture, data-domain clamping,
+ * keyboard stepping, focus semantics, and a stable machine-readable type.
+ */
+export declare function DirectManipulationControl({ value, onChange, pointerToValue, min, max, step, largeStep, x, y, controlType, controlId, label, valueText, radius, fill, stroke, strokeWidth, labelText, labelDx, labelDy, labelClassName, className, disabled, onChangeStart, onChangeEnd, onObservation, chartId, chartType, }: DirectManipulationControlProps): React.ReactElement;

package/dist/components/LinkedCharts.d.ts

@@ -1,12 +1,14 @@
 import * as React from "react";
 import type { ResolutionMode } from "./store/SelectionStore";
-type LegendInteractionMode = "highlight" | "isolate" | "none";
+export type LegendInteractionMode = "highlight" | "isolate" | "none";
 export { useSelection, useSelectionActions, useLinkedHover, useBrushSelection, useFilteredData } from "./store/useSelection";
 export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./store/useSelection";
 export { useChartObserver } from "./store/useObservation";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
 /** Hook: returns true when a parent LinkedCharts is handling the legend. */
 export declare function useLinkedLegendSuppression(): boolean;
+/** Hook: returns true when descendants are already inside a LinkedCharts provider. */
+export declare function useLinkedChartsActive(): boolean;
 /** Register a chart's current color categories with the nearest LinkedCharts. */
 export declare function useLinkedChartCategories(categories: string[]): void;
 /** True when a chart can register live categories with a parent LinkedCharts. */

package/dist/components/MobileAnnotationCalloutList.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+import type { MobileAnnotationCalloutItem } from "./recipes/mobileAnnotationStrategy";
+export interface MobileAnnotationCalloutListProps {
+    items: readonly MobileAnnotationCalloutItem[];
+    title?: React.ReactNode;
+    empty?: React.ReactNode;
+    ordered?: boolean;
+    renderItem?: (item: MobileAnnotationCalloutItem, index: number) => React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function MobileAnnotationCalloutList({ items, title, empty, ordered, renderItem, className, style, }: MobileAnnotationCalloutListProps): React.JSX.Element | null;
+export default MobileAnnotationCalloutList;