@seed-ship/mcp-ui-solid 6.17.0 → 6.18.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.18.0] - 2026-09-14
+
+### Added
+
+- Pure, opt-in comparison/geography/evidence layout helpers in `/adapters`.
+  Caller-supplied IDs, payloads and provenance are preserved; helpers only
+  arrange components and reject incompatible slot types or duplicate IDs.
+- Native chart/data view switch with keyboard-operable buttons, accessible
+  canvas description, localizable chrome and complete point/bubble data.
+- Container-width reflow for read-only composite and nested grids below 640px;
+  original desktop coordinates return when space permits.
+
+### Fixed
+
+- Align the LLM-facing chart/table/graph catalogue with native renderer/schema
+  capabilities, retaining the legacy `QuickchartRegistry` export.
+- Expose existing table search and client paging options in public types and
+  carry bubble radii through the chart contract.
+- Prevent unpositioned layout children from creating implicit extra columns.
+- Guard asynchronous chart creation against superseded props and unmounts.
+- Bound chart data scrolling and apply chart/table custom classes.
+- Validate pagination controls and bubble radii at the renderer boundary;
+  clamp client pages when data shrinks or an initial page exceeds the row count.
+- Preserve nested grid coordinates throughout editable layouts on small screens.
+
+No new runtime dependency, cross-view filtering, host persistence or backend
+wiring. Existing external-renderer trust settings remain unchanged.
+
 ## [6.17.0] - 2026-08-06
 
 Map contract parity across the spec, Solid public types, LLM-facing registry,

package/README.md

@@ -5,6 +5,52 @@ SolidJS components + chat toolkit for MCP-generated UI. Part of the [MCP UI ecos
 [![npm version](https://img.shields.io/npm/v/@seed-ship/mcp-ui-solid.svg)](https://www.npmjs.com/package/@seed-ship/mcp-ui-solid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## What's New in v6.18.0 — presentation foundations
+
+- **Three composition helpers** in `@seed-ship/mcp-ui-solid/adapters`:
+  `createComparisonLayout`, `createGeographyLayout`, `createEvidenceLayout`.
+  They arrange supplied components without fetching, aggregating or inventing
+  data. Component IDs, source links and citation maps are preserved.
+- **Container-responsive grids**: read-only layouts and nested grids stack in
+  source order below 640px of container width, including narrow desktop chat
+  panels. Desktop positions return when space is available. Editable drag/resize
+  mode keeps its explicit grid coordinates.
+- **Native chart/data switch**: Chart.js charts expose an accessible Data view,
+  even when rendering succeeds, including point coordinates and bubble radii.
+  New chrome strings can be overridden with `MCPUIStringsProvider`.
+- **Catalogue parity**: eight chart kinds, table search/paging controls, and
+  schema-supported graph layouts. QuickChart remains a host-only opt-in;
+  time axes require a compatible date adapter registered by the host.
+
+```tsx
+import { UIResourceRenderer } from '@seed-ship/mcp-ui-solid'
+import { createComparisonLayout } from '@seed-ship/mcp-ui-solid/adapters'
+
+const layout = createComparisonLayout({
+  id: 'sales-comparison',
+  chart: {
+    id: 'sales-chart', type: 'chart',
+    params: {
+      type: 'bar', title: 'Sales (EUR)',
+      data: { labels: ['Lyon', 'Nantes'], datasets: [{ label: 'Sales (EUR)', data: [120, 80] }] },
+    },
+  },
+  table: {
+    id: 'sales-table', type: 'table',
+    params: {
+      columns: [{ key: 'city', label: 'Territory' }, { key: 'sales', label: 'Sales (EUR)' }],
+      rows: [{ city: 'Lyon', sales: 120 }, { city: 'Nantes', sales: 80 }],
+    },
+  },
+})
+
+const Comparison = () => <UIResourceRenderer content={layout} />
+```
+
+These helpers are explicitly selected by the caller. They do not consume
+`renderHints` automatically, link selections between views, persist preferences,
+or verify factual claims. See the [MCPs / SolidStart handoff](./docs/briefs/VISUALIZATION-FOUNDATION-2026-09-14.md).
+
 ## What's New in v6.17.0
 
 - **Map type parity** — `center` and marker `position` now use the spec's
@@ -666,16 +712,17 @@ onScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)
 const { state, pinned, close } = useScratchpadState()
 ```
 
-## Component Renderers (19 types)
+## Component Renderers (20 types)
 
 | Type | Features |
 |------|----------|
-| `chart` | Bar, line, pie, scatter, bubble, polarArea, time-series. Native Chart.js or Quickchart fallback. PNG export. |
+| `chart` | Bar, line, pie, doughnut, radar, scatter, bubble, polarArea. Native Chart.js with Chart/Data switch and PNG export; external QuickChart only on host opt-in. Time axes require a date adapter. |
 | `table` | Sortable, pagination, virtualization (10K+), CSV/TSV/JSON export |
 | `metric` | KPI cards with trends and sparklines |
 | `text` | Markdown via marked.js |
 | `code` | Syntax highlighting (highlight.js), line numbers, word wrap |
 | `map` | OpenStreetMap base tiles via Leaflet: markers, clustering, GeoJSON, choropleth, popups, multi-layer, PMTiles |
+| `graph` | Node-link relationships with optional G6; seven schema-supported layouts and layout options |
 | `form` | 18 field types, conditional fields, persistence, tool call submit |
 | `modal` | Portal overlay, sizes sm-full, Escape/backdrop close |
 | `image-gallery` | Grid layout, lightbox, keyboard nav |
@@ -685,7 +732,7 @@ const { state, pinned, close } = useScratchpadState()
 | `link` | Styled link cards |
 | `action` | Tool call buttons |
 | `action-group` | Grouped actions with layout options |
-| `grid` | Nested 12-column CSS Grid |
+| `grid` | Nested CSS Grid; read-only layouts stack in narrow containers |
 | `carousel` | Content carousel |
 | `artifact` | File download/preview |
 | `footer` | Metadata display |

package/dist/adapters/index.d.ts

@@ -16,4 +16,6 @@
 export { connectorResultToUILayout, connectorActionsToActionGroup } from './connector';
 export type { ConnectorResultToUILayoutOptions, ConnectorActionsToActionGroupOptions, } from './connector';
 export { macroRunToScratchpadState, macroInterrogationToChatPromptConfig } from './macro-run';
+export { createComparisonLayout, createGeographyLayout, createEvidenceLayout, } from './presentation';
+export type { ComparisonLayoutInput, GeographyLayoutInput, EvidenceLayoutInput, PresentationComponent, ChartComponent, TableComponent, MapComponent, MetricComponent, TextComponent, LinkComponent, } from './presentation';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EACV,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,yBAAyB,EAAE,oCAAoC,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EACV,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,yBAAyB,EAAE,oCAAoC,EAAE,MAAM,aAAa,CAAC;AAE9F,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,gBAAgB,CAAC"}

package/dist/adapters/presentation.cjs

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const ID_PATTERN = /^[a-z0-9-]+$/;
+const DEFAULT_GRID = { columns: 12, gap: "1rem" };
+function createComparisonLayout(input) {
+  var _a, _b;
+  assertRecipeId(input.id);
+  const inputComponents = [
+    input.chart,
+    input.table,
+    ...input.metrics ?? []
+  ];
+  if (input.summary) inputComponents.push(input.summary);
+  assertUniqueComponentIds(inputComponents);
+  assertType(input.chart, "chart", "chart");
+  assertType(input.table, "table", "table");
+  (_a = input.metrics) == null ? void 0 : _a.forEach((metric, index) => assertType(metric, "metric", `metrics[${index}]`));
+  if (input.summary) assertType(input.summary, "text", "summary");
+  let row = 1;
+  const components = [];
+  if (input.summary) {
+    components.push(copyForLayout(input.summary, fullWidth(row++)));
+  }
+  components.push(...placeMetrics(input.metrics ?? [], row));
+  row += metricRows(((_b = input.metrics) == null ? void 0 : _b.length) ?? 0);
+  components.push(
+    copyForLayout(input.chart, { colStart: 1, colSpan: 7, rowStart: row }),
+    copyForLayout(input.table, { colStart: 8, colSpan: 5, rowStart: row })
+  );
+  return makeLayout(input.id, components, input.metadata);
+}
+function createGeographyLayout(input) {
+  var _a, _b;
+  assertRecipeId(input.id);
+  const inputComponents = [
+    input.map,
+    input.table,
+    ...input.metrics ?? []
+  ];
+  if (input.summary) inputComponents.push(input.summary);
+  assertUniqueComponentIds(inputComponents);
+  assertType(input.map, "map", "map");
+  assertType(input.table, "table", "table");
+  (_a = input.metrics) == null ? void 0 : _a.forEach((metric, index) => assertType(metric, "metric", `metrics[${index}]`));
+  if (input.summary) assertType(input.summary, "text", "summary");
+  let row = 1;
+  const components = [];
+  if (input.summary) {
+    components.push(copyForLayout(input.summary, fullWidth(row++)));
+  }
+  components.push(...placeMetrics(input.metrics ?? [], row));
+  row += metricRows(((_b = input.metrics) == null ? void 0 : _b.length) ?? 0);
+  components.push(
+    copyForLayout(input.map, { colStart: 1, colSpan: 8, rowStart: row }),
+    copyForLayout(input.table, { colStart: 9, colSpan: 4, rowStart: row })
+  );
+  return makeLayout(input.id, components, input.metadata);
+}
+function createEvidenceLayout(input) {
+  var _a;
+  assertRecipeId(input.id);
+  const pieces = [input.summary, input.table, ...input.sources ?? []];
+  assertType(input.summary, "text", "summary");
+  assertType(input.table, "table", "table");
+  (_a = input.sources) == null ? void 0 : _a.forEach((source, index) => assertType(source, "link", `sources[${index}]`));
+  assertUniqueComponentIds(pieces);
+  const components = [
+    copyForLayout(input.summary, fullWidth(1)),
+    copyForLayout(input.table, fullWidth(2)),
+    ...placeSources(input.sources ?? [], 3)
+  ];
+  return makeLayout(input.id, components, input.metadata);
+}
+function makeLayout(id, components, metadata) {
+  assertUniqueComponentIds(components);
+  return { id, components, grid: { ...DEFAULT_GRID }, ...metadata ? { metadata: { ...metadata } } : {} };
+}
+function fullWidth(rowStart) {
+  return { colStart: 1, colSpan: 12, rowStart };
+}
+function placeMetrics(metrics, rowStart) {
+  if (metrics.length === 0) return [];
+  const span = metrics.length === 1 ? 12 : metrics.length === 2 ? 6 : metrics.length === 3 ? 4 : 3;
+  return metrics.map((metric, index) => {
+    const column = index % Math.floor(12 / span) * span + 1;
+    const row = rowStart + Math.floor(index / Math.floor(12 / span));
+    return copyForLayout(metric, { colStart: column, colSpan: span, rowStart: row });
+  });
+}
+function metricRows(count) {
+  if (count === 0) return 0;
+  if (count <= 4) return 1;
+  return Math.ceil(count / 4);
+}
+function placeSources(sources, rowStart) {
+  return sources.map((source, index) => ({
+    ...copyForLayout(source, {
+      colStart: index % 3 * 4 + 1,
+      colSpan: 4,
+      rowStart: rowStart + Math.floor(index / 3)
+    })
+  }));
+}
+function copyForLayout(component, position) {
+  return {
+    ...component,
+    position: { ...position }
+  };
+}
+function assertRecipeId(id) {
+  if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+    throw new Error("Presentation layout id must contain only lower-case letters, digits and hyphens.");
+  }
+}
+function assertType(component, expected, path) {
+  if ((component == null ? void 0 : component.type) !== expected) {
+    throw new Error(`${path} must be a ${expected} component.`);
+  }
+}
+function assertUniqueComponentIds(components) {
+  const ids = /* @__PURE__ */ new Set();
+  const visit = (component, path) => {
+    var _a;
+    if (!component || typeof component.id !== "string" || !ID_PATTERN.test(component.id)) {
+      throw new Error(`${path} must have a stable lower-case component id.`);
+    }
+    if (ids.has(component.id)) throw new Error(`Duplicate component id: ${component.id}`);
+    ids.add(component.id);
+    if (component.type === "grid") {
+      const children = (_a = component.params) == null ? void 0 : _a.children;
+      if (Array.isArray(children)) {
+        children.forEach((child, index) => visit(child, `${path}.children[${index}]`));
+      }
+    }
+  };
+  components.forEach((component, index) => visit(component, `components[${index}]`));
+}
+exports.createComparisonLayout = createComparisonLayout;
+exports.createEvidenceLayout = createEvidenceLayout;
+exports.createGeographyLayout = createGeographyLayout;
+//# sourceMappingURL=presentation.cjs.map

package/dist/adapters/presentation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.cjs","sources":["../../src/adapters/presentation.ts"],"sourcesContent":["/**\n * Opt-in, pure presentation recipes for existing MCP-UI components.\n *\n * These helpers arrange caller-supplied components only. They never fetch,\n * aggregate, sort, infer confidence, or manufacture sources: data, params,\n * citations and component metadata remain the caller's responsibility.\n */\n\nimport type {\n  ChartComponentParams,\n  GridPosition,\n  MapComponentParams,\n  MetricComponentParams,\n  TableComponentParams,\n  TextComponentParams,\n  UIComponent,\n  UILayout,\n} from '../types'\nimport type { LinkComponentParams } from '@seed-ship/mcp-ui-spec'\n\ntype PresentationType = 'chart' | 'table' | 'map' | 'metric' | 'text' | 'link'\n\n/** A recipe owns the eventual grid position, so caller positions are optional. */\nexport type PresentationComponent<T extends PresentationType, Params> = Omit<\n  UIComponent,\n  'type' | 'params' | 'position'\n> & {\n  type: T\n  params: Params\n  position?: GridPosition\n}\n\nexport type ChartComponent = PresentationComponent<'chart', ChartComponentParams>\nexport type TableComponent = PresentationComponent<'table', TableComponentParams>\nexport type MapComponent = PresentationComponent<'map', MapComponentParams>\nexport type MetricComponent = PresentationComponent<'metric', MetricComponentParams>\nexport type TextComponent = PresentationComponent<'text', TextComponentParams>\nexport type LinkComponent = PresentationComponent<'link', LinkComponentParams>\n\nexport interface ComparisonLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  chart: ChartComponent\n  table: TableComponent\n  metrics?: MetricComponent[]\n  summary?: TextComponent\n  metadata?: UILayout['metadata']\n}\n\nexport interface GeographyLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  map: MapComponent\n  table: TableComponent\n  metrics?: MetricComponent[]\n  summary?: TextComponent\n  metadata?: UILayout['metadata']\n}\n\nexport interface EvidenceLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  summary: TextComponent\n  table: TableComponent\n  sources?: LinkComponent[]\n  metadata?: UILayout['metadata']\n}\n\nconst ID_PATTERN = /^[a-z0-9-]+$/\nconst DEFAULT_GRID = { columns: 12, gap: '1rem' } as const\n\n/**\n * Presents a comparison in reading order: optional context and KPIs, then a\n * chart beside the complete table. The supplied rows and chart series keep\n * their original order.\n */\nexport function createComparisonLayout(input: ComparisonLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const inputComponents: Array<PresentationComponent<PresentationType, unknown>> = [\n    input.chart, input.table, ...(input.metrics ?? []),\n  ]\n  if (input.summary) inputComponents.push(input.summary)\n  assertUniqueComponentIds(inputComponents)\n  assertType(input.chart, 'chart', 'chart')\n  assertType(input.table, 'table', 'table')\n  input.metrics?.forEach((metric, index) => assertType(metric, 'metric', `metrics[${index}]`))\n  if (input.summary) assertType(input.summary, 'text', 'summary')\n\n  let row = 1\n  const components: UIComponent[] = []\n  if (input.summary) {\n    components.push(copyForLayout(input.summary, fullWidth(row++)))\n  }\n  components.push(...placeMetrics(input.metrics ?? [], row))\n  row += metricRows(input.metrics?.length ?? 0)\n  components.push(\n    copyForLayout(input.chart, { colStart: 1, colSpan: 7, rowStart: row }),\n    copyForLayout(input.table, { colStart: 8, colSpan: 5, rowStart: row })\n  )\n  return makeLayout(input.id, components, input.metadata)\n}\n\n/**\n * Pairs a geographic overview with the corresponding inspectable table.\n * Map and table data are passed through unchanged, including GeoJSON and\n * citation maps.\n */\nexport function createGeographyLayout(input: GeographyLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const inputComponents: Array<PresentationComponent<PresentationType, unknown>> = [\n    input.map, input.table, ...(input.metrics ?? []),\n  ]\n  if (input.summary) inputComponents.push(input.summary)\n  assertUniqueComponentIds(inputComponents)\n  assertType(input.map, 'map', 'map')\n  assertType(input.table, 'table', 'table')\n  input.metrics?.forEach((metric, index) => assertType(metric, 'metric', `metrics[${index}]`))\n  if (input.summary) assertType(input.summary, 'text', 'summary')\n\n  let row = 1\n  const components: UIComponent[] = []\n  if (input.summary) {\n    components.push(copyForLayout(input.summary, fullWidth(row++)))\n  }\n  components.push(...placeMetrics(input.metrics ?? [], row))\n  row += metricRows(input.metrics?.length ?? 0)\n  components.push(\n    copyForLayout(input.map, { colStart: 1, colSpan: 8, rowStart: row }),\n    copyForLayout(input.table, { colStart: 9, colSpan: 4, rowStart: row })\n  )\n  return makeLayout(input.id, components, input.metadata)\n}\n\n/**\n * Puts the conclusion first, evidence table second, and supplied source links\n * last. Source order is deliberately preserved: this is a presentation recipe,\n * not a confidence or provenance ranking algorithm.\n */\nexport function createEvidenceLayout(input: EvidenceLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const pieces = [input.summary, input.table, ...(input.sources ?? [])]\n  assertType(input.summary, 'text', 'summary')\n  assertType(input.table, 'table', 'table')\n  input.sources?.forEach((source, index) => assertType(source, 'link', `sources[${index}]`))\n  assertUniqueComponentIds(pieces)\n\n  const components: UIComponent[] = [\n    copyForLayout(input.summary, fullWidth(1)),\n    copyForLayout(input.table, fullWidth(2)),\n    ...placeSources(input.sources ?? [], 3),\n  ]\n  return makeLayout(input.id, components, input.metadata)\n}\n\nfunction makeLayout(id: string, components: UIComponent[], metadata?: UILayout['metadata']): UILayout {\n  assertUniqueComponentIds(components)\n  return { id, components, grid: { ...DEFAULT_GRID }, ...(metadata ? { metadata: { ...metadata } } : {}) }\n}\n\nfunction fullWidth(rowStart: number): GridPosition {\n  return { colStart: 1, colSpan: 12, rowStart }\n}\n\nfunction placeMetrics(metrics: MetricComponent[], rowStart: number): UIComponent[] {\n  if (metrics.length === 0) return []\n  const span = metrics.length === 1 ? 12 : metrics.length === 2 ? 6 : metrics.length === 3 ? 4 : 3\n  return metrics.map((metric, index) => {\n    const column = (index % Math.floor(12 / span)) * span + 1\n    const row = rowStart + Math.floor(index / Math.floor(12 / span))\n    return copyForLayout(metric, { colStart: column, colSpan: span, rowStart: row })\n  })\n}\n\nfunction metricRows(count: number): number {\n  if (count === 0) return 0\n  if (count <= 4) return 1\n  return Math.ceil(count / 4)\n}\n\nfunction placeSources(sources: LinkComponent[], rowStart: number): UIComponent[] {\n  return sources.map((source, index) => ({\n    ...copyForLayout(source, {\n      colStart: (index % 3) * 4 + 1,\n      colSpan: 4,\n      rowStart: rowStart + Math.floor(index / 3),\n    }),\n  }))\n}\n\nfunction copyForLayout(\n  component: PresentationComponent<PresentationType, unknown>,\n  position: GridPosition\n): UIComponent {\n  return {\n    ...component,\n    position: { ...position },\n  } as UIComponent\n}\n\nfunction assertRecipeId(id: string): void {\n  if (typeof id !== 'string' || !ID_PATTERN.test(id)) {\n    throw new Error('Presentation layout id must contain only lower-case letters, digits and hyphens.')\n  }\n}\n\nfunction assertType(component: { type: string }, expected: PresentationType, path: string): void {\n  if (component?.type !== expected) {\n    throw new Error(`${path} must be a ${expected} component.`)\n  }\n}\n\n/** Validates source IDs recursively so nested GridRenderer children stay key-safe. */\nfunction assertUniqueComponentIds(components: Array<UIComponent | PresentationComponent<PresentationType, unknown>>): void {\n  const ids = new Set<string>()\n  const visit = (component: { id: unknown; type?: unknown; params?: unknown }, path: string): void => {\n    if (!component || typeof component.id !== 'string' || !ID_PATTERN.test(component.id)) {\n      throw new Error(`${path} must have a stable lower-case component id.`)\n    }\n    if (ids.has(component.id)) throw new Error(`Duplicate component id: ${component.id}`)\n    ids.add(component.id)\n    if (component.type === 'grid') {\n      const children = (component.params as { children?: unknown })?.children\n      if (Array.isArray(children)) {\n        children.forEach((child, index) => visit(child as { id: unknown; type?: unknown; params?: unknown }, `${path}.children[${index}]`))\n      }\n    }\n  }\n  components.forEach((component, index) => visit(component, `components[${index}]`))\n}\n"],"names":[],"mappings":"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"}

package/dist/adapters/presentation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Opt-in, pure presentation recipes for existing MCP-UI components.
+ *
+ * These helpers arrange caller-supplied components only. They never fetch,
+ * aggregate, sort, infer confidence, or manufacture sources: data, params,
+ * citations and component metadata remain the caller's responsibility.
+ */
+import type { ChartComponentParams, GridPosition, MapComponentParams, MetricComponentParams, TableComponentParams, TextComponentParams, UIComponent, UILayout } from '../types';
+import type { LinkComponentParams } from '@seed-ship/mcp-ui-spec';
+type PresentationType = 'chart' | 'table' | 'map' | 'metric' | 'text' | 'link';
+/** A recipe owns the eventual grid position, so caller positions are optional. */
+export type PresentationComponent<T extends PresentationType, Params> = Omit<UIComponent, 'type' | 'params' | 'position'> & {
+    type: T;
+    params: Params;
+    position?: GridPosition;
+};
+export type ChartComponent = PresentationComponent<'chart', ChartComponentParams>;
+export type TableComponent = PresentationComponent<'table', TableComponentParams>;
+export type MapComponent = PresentationComponent<'map', MapComponentParams>;
+export type MetricComponent = PresentationComponent<'metric', MetricComponentParams>;
+export type TextComponent = PresentationComponent<'text', TextComponentParams>;
+export type LinkComponent = PresentationComponent<'link', LinkComponentParams>;
+export interface ComparisonLayoutInput {
+    /** Stable layout id; lower-case letters, digits and hyphens only. */
+    id: string;
+    chart: ChartComponent;
+    table: TableComponent;
+    metrics?: MetricComponent[];
+    summary?: TextComponent;
+    metadata?: UILayout['metadata'];
+}
+export interface GeographyLayoutInput {
+    /** Stable layout id; lower-case letters, digits and hyphens only. */
+    id: string;
+    map: MapComponent;
+    table: TableComponent;
+    metrics?: MetricComponent[];
+    summary?: TextComponent;
+    metadata?: UILayout['metadata'];
+}
+export interface EvidenceLayoutInput {
+    /** Stable layout id; lower-case letters, digits and hyphens only. */
+    id: string;
+    summary: TextComponent;
+    table: TableComponent;
+    sources?: LinkComponent[];
+    metadata?: UILayout['metadata'];
+}
+/**
+ * Presents a comparison in reading order: optional context and KPIs, then a
+ * chart beside the complete table. The supplied rows and chart series keep
+ * their original order.
+ */
+export declare function createComparisonLayout(input: ComparisonLayoutInput): UILayout;
+/**
+ * Pairs a geographic overview with the corresponding inspectable table.
+ * Map and table data are passed through unchanged, including GeoJSON and
+ * citation maps.
+ */
+export declare function createGeographyLayout(input: GeographyLayoutInput): UILayout;
+/**
+ * Puts the conclusion first, evidence table second, and supplied source links
+ * last. Source order is deliberately preserved: this is a presentation recipe,
+ * not a confidence or provenance ranking algorithm.
+ */
+export declare function createEvidenceLayout(input: EvidenceLayoutInput): UILayout;
+export {};
+//# sourceMappingURL=presentation.d.ts.map

package/dist/adapters/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/adapters/presentation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,QAAQ,EACT,MAAM,UAAU,CAAA;AACjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE,KAAK,gBAAgB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;AAE9E,kFAAkF;AAClF,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,gBAAgB,EAAE,MAAM,IAAI,IAAI,CAC1E,WAAW,EACX,MAAM,GAAG,QAAQ,GAAG,UAAU,CAC/B,GAAG;IACF,IAAI,EAAE,CAAC,CAAA;IACP,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAA;AACjF,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAA;AACjF,MAAM,MAAM,YAAY,GAAG,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAA;AAC3E,MAAM,MAAM,eAAe,GAAG,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAA;AACpF,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;AAC9E,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;AAE9E,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,aAAa,CAAA;IACtB,KAAK,EAAE,cAAc,CAAA;IACrB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;CAChC;AAKD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,QAAQ,CAwB7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,QAAQ,CAwB3E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,CAczE"}

package/dist/adapters/presentation.js

@@ -0,0 +1,141 @@
+const ID_PATTERN = /^[a-z0-9-]+$/;
+const DEFAULT_GRID = { columns: 12, gap: "1rem" };
+function createComparisonLayout(input) {
+  var _a, _b;
+  assertRecipeId(input.id);
+  const inputComponents = [
+    input.chart,
+    input.table,
+    ...input.metrics ?? []
+  ];
+  if (input.summary) inputComponents.push(input.summary);
+  assertUniqueComponentIds(inputComponents);
+  assertType(input.chart, "chart", "chart");
+  assertType(input.table, "table", "table");
+  (_a = input.metrics) == null ? void 0 : _a.forEach((metric, index) => assertType(metric, "metric", `metrics[${index}]`));
+  if (input.summary) assertType(input.summary, "text", "summary");
+  let row = 1;
+  const components = [];
+  if (input.summary) {
+    components.push(copyForLayout(input.summary, fullWidth(row++)));
+  }
+  components.push(...placeMetrics(input.metrics ?? [], row));
+  row += metricRows(((_b = input.metrics) == null ? void 0 : _b.length) ?? 0);
+  components.push(
+    copyForLayout(input.chart, { colStart: 1, colSpan: 7, rowStart: row }),
+    copyForLayout(input.table, { colStart: 8, colSpan: 5, rowStart: row })
+  );
+  return makeLayout(input.id, components, input.metadata);
+}
+function createGeographyLayout(input) {
+  var _a, _b;
+  assertRecipeId(input.id);
+  const inputComponents = [
+    input.map,
+    input.table,
+    ...input.metrics ?? []
+  ];
+  if (input.summary) inputComponents.push(input.summary);
+  assertUniqueComponentIds(inputComponents);
+  assertType(input.map, "map", "map");
+  assertType(input.table, "table", "table");
+  (_a = input.metrics) == null ? void 0 : _a.forEach((metric, index) => assertType(metric, "metric", `metrics[${index}]`));
+  if (input.summary) assertType(input.summary, "text", "summary");
+  let row = 1;
+  const components = [];
+  if (input.summary) {
+    components.push(copyForLayout(input.summary, fullWidth(row++)));
+  }
+  components.push(...placeMetrics(input.metrics ?? [], row));
+  row += metricRows(((_b = input.metrics) == null ? void 0 : _b.length) ?? 0);
+  components.push(
+    copyForLayout(input.map, { colStart: 1, colSpan: 8, rowStart: row }),
+    copyForLayout(input.table, { colStart: 9, colSpan: 4, rowStart: row })
+  );
+  return makeLayout(input.id, components, input.metadata);
+}
+function createEvidenceLayout(input) {
+  var _a;
+  assertRecipeId(input.id);
+  const pieces = [input.summary, input.table, ...input.sources ?? []];
+  assertType(input.summary, "text", "summary");
+  assertType(input.table, "table", "table");
+  (_a = input.sources) == null ? void 0 : _a.forEach((source, index) => assertType(source, "link", `sources[${index}]`));
+  assertUniqueComponentIds(pieces);
+  const components = [
+    copyForLayout(input.summary, fullWidth(1)),
+    copyForLayout(input.table, fullWidth(2)),
+    ...placeSources(input.sources ?? [], 3)
+  ];
+  return makeLayout(input.id, components, input.metadata);
+}
+function makeLayout(id, components, metadata) {
+  assertUniqueComponentIds(components);
+  return { id, components, grid: { ...DEFAULT_GRID }, ...metadata ? { metadata: { ...metadata } } : {} };
+}
+function fullWidth(rowStart) {
+  return { colStart: 1, colSpan: 12, rowStart };
+}
+function placeMetrics(metrics, rowStart) {
+  if (metrics.length === 0) return [];
+  const span = metrics.length === 1 ? 12 : metrics.length === 2 ? 6 : metrics.length === 3 ? 4 : 3;
+  return metrics.map((metric, index) => {
+    const column = index % Math.floor(12 / span) * span + 1;
+    const row = rowStart + Math.floor(index / Math.floor(12 / span));
+    return copyForLayout(metric, { colStart: column, colSpan: span, rowStart: row });
+  });
+}
+function metricRows(count) {
+  if (count === 0) return 0;
+  if (count <= 4) return 1;
+  return Math.ceil(count / 4);
+}
+function placeSources(sources, rowStart) {
+  return sources.map((source, index) => ({
+    ...copyForLayout(source, {
+      colStart: index % 3 * 4 + 1,
+      colSpan: 4,
+      rowStart: rowStart + Math.floor(index / 3)
+    })
+  }));
+}
+function copyForLayout(component, position) {
+  return {
+    ...component,
+    position: { ...position }
+  };
+}
+function assertRecipeId(id) {
+  if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+    throw new Error("Presentation layout id must contain only lower-case letters, digits and hyphens.");
+  }
+}
+function assertType(component, expected, path) {
+  if ((component == null ? void 0 : component.type) !== expected) {
+    throw new Error(`${path} must be a ${expected} component.`);
+  }
+}
+function assertUniqueComponentIds(components) {
+  const ids = /* @__PURE__ */ new Set();
+  const visit = (component, path) => {
+    var _a;
+    if (!component || typeof component.id !== "string" || !ID_PATTERN.test(component.id)) {
+      throw new Error(`${path} must have a stable lower-case component id.`);
+    }
+    if (ids.has(component.id)) throw new Error(`Duplicate component id: ${component.id}`);
+    ids.add(component.id);
+    if (component.type === "grid") {
+      const children = (_a = component.params) == null ? void 0 : _a.children;
+      if (Array.isArray(children)) {
+        children.forEach((child, index) => visit(child, `${path}.children[${index}]`));
+      }
+    }
+  };
+  components.forEach((component, index) => visit(component, `components[${index}]`));
+}
+export {
+  createComparisonLayout,
+  createEvidenceLayout,
+  createGeographyLayout
+};
+//# sourceMappingURL=presentation.js.map

package/dist/adapters/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sources":["../../src/adapters/presentation.ts"],"sourcesContent":["/**\n * Opt-in, pure presentation recipes for existing MCP-UI components.\n *\n * These helpers arrange caller-supplied components only. They never fetch,\n * aggregate, sort, infer confidence, or manufacture sources: data, params,\n * citations and component metadata remain the caller's responsibility.\n */\n\nimport type {\n  ChartComponentParams,\n  GridPosition,\n  MapComponentParams,\n  MetricComponentParams,\n  TableComponentParams,\n  TextComponentParams,\n  UIComponent,\n  UILayout,\n} from '../types'\nimport type { LinkComponentParams } from '@seed-ship/mcp-ui-spec'\n\ntype PresentationType = 'chart' | 'table' | 'map' | 'metric' | 'text' | 'link'\n\n/** A recipe owns the eventual grid position, so caller positions are optional. */\nexport type PresentationComponent<T extends PresentationType, Params> = Omit<\n  UIComponent,\n  'type' | 'params' | 'position'\n> & {\n  type: T\n  params: Params\n  position?: GridPosition\n}\n\nexport type ChartComponent = PresentationComponent<'chart', ChartComponentParams>\nexport type TableComponent = PresentationComponent<'table', TableComponentParams>\nexport type MapComponent = PresentationComponent<'map', MapComponentParams>\nexport type MetricComponent = PresentationComponent<'metric', MetricComponentParams>\nexport type TextComponent = PresentationComponent<'text', TextComponentParams>\nexport type LinkComponent = PresentationComponent<'link', LinkComponentParams>\n\nexport interface ComparisonLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  chart: ChartComponent\n  table: TableComponent\n  metrics?: MetricComponent[]\n  summary?: TextComponent\n  metadata?: UILayout['metadata']\n}\n\nexport interface GeographyLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  map: MapComponent\n  table: TableComponent\n  metrics?: MetricComponent[]\n  summary?: TextComponent\n  metadata?: UILayout['metadata']\n}\n\nexport interface EvidenceLayoutInput {\n  /** Stable layout id; lower-case letters, digits and hyphens only. */\n  id: string\n  summary: TextComponent\n  table: TableComponent\n  sources?: LinkComponent[]\n  metadata?: UILayout['metadata']\n}\n\nconst ID_PATTERN = /^[a-z0-9-]+$/\nconst DEFAULT_GRID = { columns: 12, gap: '1rem' } as const\n\n/**\n * Presents a comparison in reading order: optional context and KPIs, then a\n * chart beside the complete table. The supplied rows and chart series keep\n * their original order.\n */\nexport function createComparisonLayout(input: ComparisonLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const inputComponents: Array<PresentationComponent<PresentationType, unknown>> = [\n    input.chart, input.table, ...(input.metrics ?? []),\n  ]\n  if (input.summary) inputComponents.push(input.summary)\n  assertUniqueComponentIds(inputComponents)\n  assertType(input.chart, 'chart', 'chart')\n  assertType(input.table, 'table', 'table')\n  input.metrics?.forEach((metric, index) => assertType(metric, 'metric', `metrics[${index}]`))\n  if (input.summary) assertType(input.summary, 'text', 'summary')\n\n  let row = 1\n  const components: UIComponent[] = []\n  if (input.summary) {\n    components.push(copyForLayout(input.summary, fullWidth(row++)))\n  }\n  components.push(...placeMetrics(input.metrics ?? [], row))\n  row += metricRows(input.metrics?.length ?? 0)\n  components.push(\n    copyForLayout(input.chart, { colStart: 1, colSpan: 7, rowStart: row }),\n    copyForLayout(input.table, { colStart: 8, colSpan: 5, rowStart: row })\n  )\n  return makeLayout(input.id, components, input.metadata)\n}\n\n/**\n * Pairs a geographic overview with the corresponding inspectable table.\n * Map and table data are passed through unchanged, including GeoJSON and\n * citation maps.\n */\nexport function createGeographyLayout(input: GeographyLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const inputComponents: Array<PresentationComponent<PresentationType, unknown>> = [\n    input.map, input.table, ...(input.metrics ?? []),\n  ]\n  if (input.summary) inputComponents.push(input.summary)\n  assertUniqueComponentIds(inputComponents)\n  assertType(input.map, 'map', 'map')\n  assertType(input.table, 'table', 'table')\n  input.metrics?.forEach((metric, index) => assertType(metric, 'metric', `metrics[${index}]`))\n  if (input.summary) assertType(input.summary, 'text', 'summary')\n\n  let row = 1\n  const components: UIComponent[] = []\n  if (input.summary) {\n    components.push(copyForLayout(input.summary, fullWidth(row++)))\n  }\n  components.push(...placeMetrics(input.metrics ?? [], row))\n  row += metricRows(input.metrics?.length ?? 0)\n  components.push(\n    copyForLayout(input.map, { colStart: 1, colSpan: 8, rowStart: row }),\n    copyForLayout(input.table, { colStart: 9, colSpan: 4, rowStart: row })\n  )\n  return makeLayout(input.id, components, input.metadata)\n}\n\n/**\n * Puts the conclusion first, evidence table second, and supplied source links\n * last. Source order is deliberately preserved: this is a presentation recipe,\n * not a confidence or provenance ranking algorithm.\n */\nexport function createEvidenceLayout(input: EvidenceLayoutInput): UILayout {\n  assertRecipeId(input.id)\n  const pieces = [input.summary, input.table, ...(input.sources ?? [])]\n  assertType(input.summary, 'text', 'summary')\n  assertType(input.table, 'table', 'table')\n  input.sources?.forEach((source, index) => assertType(source, 'link', `sources[${index}]`))\n  assertUniqueComponentIds(pieces)\n\n  const components: UIComponent[] = [\n    copyForLayout(input.summary, fullWidth(1)),\n    copyForLayout(input.table, fullWidth(2)),\n    ...placeSources(input.sources ?? [], 3),\n  ]\n  return makeLayout(input.id, components, input.metadata)\n}\n\nfunction makeLayout(id: string, components: UIComponent[], metadata?: UILayout['metadata']): UILayout {\n  assertUniqueComponentIds(components)\n  return { id, components, grid: { ...DEFAULT_GRID }, ...(metadata ? { metadata: { ...metadata } } : {}) }\n}\n\nfunction fullWidth(rowStart: number): GridPosition {\n  return { colStart: 1, colSpan: 12, rowStart }\n}\n\nfunction placeMetrics(metrics: MetricComponent[], rowStart: number): UIComponent[] {\n  if (metrics.length === 0) return []\n  const span = metrics.length === 1 ? 12 : metrics.length === 2 ? 6 : metrics.length === 3 ? 4 : 3\n  return metrics.map((metric, index) => {\n    const column = (index % Math.floor(12 / span)) * span + 1\n    const row = rowStart + Math.floor(index / Math.floor(12 / span))\n    return copyForLayout(metric, { colStart: column, colSpan: span, rowStart: row })\n  })\n}\n\nfunction metricRows(count: number): number {\n  if (count === 0) return 0\n  if (count <= 4) return 1\n  return Math.ceil(count / 4)\n}\n\nfunction placeSources(sources: LinkComponent[], rowStart: number): UIComponent[] {\n  return sources.map((source, index) => ({\n    ...copyForLayout(source, {\n      colStart: (index % 3) * 4 + 1,\n      colSpan: 4,\n      rowStart: rowStart + Math.floor(index / 3),\n    }),\n  }))\n}\n\nfunction copyForLayout(\n  component: PresentationComponent<PresentationType, unknown>,\n  position: GridPosition\n): UIComponent {\n  return {\n    ...component,\n    position: { ...position },\n  } as UIComponent\n}\n\nfunction assertRecipeId(id: string): void {\n  if (typeof id !== 'string' || !ID_PATTERN.test(id)) {\n    throw new Error('Presentation layout id must contain only lower-case letters, digits and hyphens.')\n  }\n}\n\nfunction assertType(component: { type: string }, expected: PresentationType, path: string): void {\n  if (component?.type !== expected) {\n    throw new Error(`${path} must be a ${expected} component.`)\n  }\n}\n\n/** Validates source IDs recursively so nested GridRenderer children stay key-safe. */\nfunction assertUniqueComponentIds(components: Array<UIComponent | PresentationComponent<PresentationType, unknown>>): void {\n  const ids = new Set<string>()\n  const visit = (component: { id: unknown; type?: unknown; params?: unknown }, path: string): void => {\n    if (!component || typeof component.id !== 'string' || !ID_PATTERN.test(component.id)) {\n      throw new Error(`${path} must have a stable lower-case component id.`)\n    }\n    if (ids.has(component.id)) throw new Error(`Duplicate component id: ${component.id}`)\n    ids.add(component.id)\n    if (component.type === 'grid') {\n      const children = (component.params as { children?: unknown })?.children\n      if (Array.isArray(children)) {\n        children.forEach((child, index) => visit(child as { id: unknown; type?: unknown; params?: unknown }, `${path}.children[${index}]`))\n      }\n    }\n  }\n  components.forEach((component, index) => visit(component, `components[${index}]`))\n}\n"],"names":[],"mappings":"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"}

package/dist/adapters.cjs

@@ -2,8 +2,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const connector = require("./adapters/connector.cjs");
 const macroRun = require("./adapters/macro-run.cjs");
+const presentation = require("./adapters/presentation.cjs");
 exports.connectorActionsToActionGroup = connector.connectorActionsToActionGroup;
 exports.connectorResultToUILayout = connector.connectorResultToUILayout;
 exports.macroInterrogationToChatPromptConfig = macroRun.macroInterrogationToChatPromptConfig;
 exports.macroRunToScratchpadState = macroRun.macroRunToScratchpadState;
+exports.createComparisonLayout = presentation.createComparisonLayout;
+exports.createEvidenceLayout = presentation.createEvidenceLayout;
+exports.createGeographyLayout = presentation.createGeographyLayout;
 //# sourceMappingURL=adapters.cjs.map

package/dist/adapters.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"adapters.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/adapters.d.cts

@@ -16,4 +16,6 @@
 export { connectorResultToUILayout, connectorActionsToActionGroup } from './connector';
 export type { ConnectorResultToUILayoutOptions, ConnectorActionsToActionGroupOptions, } from './connector';
 export { macroRunToScratchpadState, macroInterrogationToChatPromptConfig } from './macro-run';
+export { createComparisonLayout, createGeographyLayout, createEvidenceLayout, } from './presentation';
+export type { ComparisonLayoutInput, GeographyLayoutInput, EvidenceLayoutInput, PresentationComponent, ChartComponent, TableComponent, MapComponent, MetricComponent, TextComponent, LinkComponent, } from './presentation';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters.d.ts

@@ -16,4 +16,6 @@
 export { connectorResultToUILayout, connectorActionsToActionGroup } from './connector';
 export type { ConnectorResultToUILayoutOptions, ConnectorActionsToActionGroupOptions, } from './connector';
 export { macroRunToScratchpadState, macroInterrogationToChatPromptConfig } from './macro-run';
+export { createComparisonLayout, createGeographyLayout, createEvidenceLayout, } from './presentation';
+export type { ComparisonLayoutInput, GeographyLayoutInput, EvidenceLayoutInput, PresentationComponent, ChartComponent, TableComponent, MapComponent, MetricComponent, TextComponent, LinkComponent, } from './presentation';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters.js

@@ -1,8 +1,12 @@
 import { connectorActionsToActionGroup, connectorResultToUILayout } from "./adapters/connector.js";
 import { macroInterrogationToChatPromptConfig, macroRunToScratchpadState } from "./adapters/macro-run.js";
+import { createComparisonLayout, createEvidenceLayout, createGeographyLayout } from "./adapters/presentation.js";
 export {
   connectorActionsToActionGroup,
   connectorResultToUILayout,
+  createComparisonLayout,
+  createEvidenceLayout,
+  createGeographyLayout,
   macroInterrogationToChatPromptConfig,
   macroRunToScratchpadState
 };

package/dist/adapters.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
+{"version":3,"file":"adapters.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}