@seed-ship/mcp-ui-solid 6.5.0 → 6.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-ship/mcp-ui-solid",
-  "version": "6.5.0",
+  "version": "6.6.1",
   "description": "SolidJS components for rendering MCP-generated UI resources",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -73,6 +73,17 @@
         "default": "./dist/types-export.cjs"
       }
     },
+    "./adapters": {
+      "solid": "./src/adapters/index.ts",
+      "import": {
+        "types": "./dist/adapters.d.ts",
+        "default": "./dist/adapters.js"
+      },
+      "require": {
+        "types": "./dist/adapters.d.cts",
+        "default": "./dist/adapters.cjs"
+      }
+    },
     "./plugins/duckdb": {
       "solid": "./src/plugins/duckdb.ts",
       "import": {
@@ -86,12 +97,13 @@
     },
     "./src/*": "./src/*"
   },
+  "_size-limit-note": "size-limit is a regression guardrail, not a hard cap — it flags accidental bundle bloat. It measures the pre-built dist/index.js and sums the FULL graph reachable from each entry, including lazy import() chunks (leaflet, @antv/g6, chart.js) a consumer fetches on demand, NOT at import time — so the figures are worst-case totals, not eager load cost. Since v6.6.0 the 'Streaming renderer' entry delegates to UIResourceRenderer (Gap 1 parity), so its graph equals the full renderer set; its budget is set to 1 MB (generous headroom — the real eager cost is far lower). The 'Hooks only' and 'Full bundle' limits are pre-existing and unchanged by v6.6.0. size-limit is informational only — it does not gate CI.",
   "size-limit": [
     {
       "name": "Streaming renderer",
       "path": "dist/index.js",
       "import": "{ StreamingUIRenderer }",
-      "limit": "30 KB"
+      "limit": "1 MB"
     },
     {
       "name": "Hooks only",
@@ -143,7 +155,7 @@
     }
   },
   "dependencies": {
-    "@seed-ship/mcp-ui-spec": "^5.0.5",
+    "@seed-ship/mcp-ui-spec": "^5.1.0",
     "@types/dompurify": "^3.0.5",
     "dompurify": "^3.4.1",
     "marked": "^16.3.0",
@@ -195,8 +207,8 @@
   "scripts": {
     "build": "vite build && pnpm build:types",
     "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --composite false && pnpm build:types:copy",
-    "build:types:copy": "cp dist/components/index.d.ts dist/components.d.ts 2>/dev/null || true && cp dist/hooks/index.d.ts dist/hooks.d.ts 2>/dev/null || true && cp dist/types/index.d.ts dist/types.d.ts 2>/dev/null || true && pnpm build:types:cts",
-    "build:types:cts": "cp dist/index.d.ts dist/index.d.cts && cp dist/components.d.ts dist/components.d.cts 2>/dev/null || true && cp dist/hooks.d.ts dist/hooks.d.cts 2>/dev/null || true && cp dist/types.d.ts dist/types.d.cts 2>/dev/null || true && cp dist/validation.d.ts dist/validation.d.cts 2>/dev/null || true && cp dist/types-export.d.ts dist/types-export.d.cts 2>/dev/null || true",
+    "build:types:copy": "cp dist/components/index.d.ts dist/components.d.ts 2>/dev/null || true && cp dist/hooks/index.d.ts dist/hooks.d.ts 2>/dev/null || true && cp dist/types/index.d.ts dist/types.d.ts 2>/dev/null || true && cp dist/adapters/index.d.ts dist/adapters.d.ts 2>/dev/null || true && pnpm build:types:cts",
+    "build:types:cts": "cp dist/index.d.ts dist/index.d.cts && cp dist/components.d.ts dist/components.d.cts 2>/dev/null || true && cp dist/hooks.d.ts dist/hooks.d.cts 2>/dev/null || true && cp dist/types.d.ts dist/types.d.cts 2>/dev/null || true && cp dist/validation.d.ts dist/validation.d.cts 2>/dev/null || true && cp dist/types-export.d.ts dist/types-export.d.cts 2>/dev/null || true && cp dist/adapters.d.ts dist/adapters.d.cts 2>/dev/null || true",
     "dev": "vite build --watch",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/adapters/connector.test.ts

@@ -0,0 +1,165 @@
+/**
+ * v6.6.0 — connector adapters (D5 / D6 of ROADMAP-opendata-macro-mcpui).
+ *
+ * Coverage:
+ *   1. connectorActionsToActionGroup wraps actions into an action-group
+ *   2. connectorResultToUILayout assembles primary + supplemental + actions
+ *   3. primary that is itself a layout has its components spread in
+ *   4. unknown schemaVersion + usable envelope → degraded-but-rendered (R2)
+ *   5. unreadable payload → explicit error layout, never throws (R2)
+ *   6. purity — same input yields a deep-equal output
+ *   7. every shipped spec fixture assembles without a degraded layout
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  connectorResultToUILayout,
+  connectorActionsToActionGroup,
+} from './connector'
+import { CONNECTOR_DYNAMIC_RESULT_V1 } from '@seed-ship/mcp-ui-spec'
+
+const VALID = {
+  schemaVersion: CONNECTOR_DYNAMIC_RESULT_V1,
+  connectorId: 'datagouv',
+  toolName: 'datagouv.search',
+  query: 'immobilier toulouse',
+  queryHash: 'abc123',
+  primary: {
+    id: 'tbl',
+    type: 'table',
+    position: { colStart: 1, colSpan: 12 },
+    params: { columns: [{ key: 'a', label: 'A' }], rows: [] },
+  },
+  supplemental: [
+    { id: 'mtr', type: 'metric', position: { colStart: 1, colSpan: 4 }, params: { title: 'M', value: 1 } },
+  ],
+  actions: [
+    { label: 'Compare', action: 'tool-call', toolName: 'datagouv.search', params: { query: 'x' } },
+  ],
+}
+
+describe('connectorActionsToActionGroup (v6.6.0)', () => {
+  it('wraps actions into an action-group UIComponent', () => {
+    const ag = connectorActionsToActionGroup(VALID.actions as never)
+    expect(ag.type).toBe('action-group')
+    expect((ag.params as { actions: unknown[] }).actions).toHaveLength(1)
+    expect(ag.position).toEqual({ colStart: 1, colSpan: 12 })
+  })
+
+  it('honors id / title / layout / gap options', () => {
+    const ag = connectorActionsToActionGroup(VALID.actions as never, {
+      id: 'my-actions',
+      title: 'Suite',
+      layout: 'end',
+      gap: 'sm',
+    })
+    expect(ag.id).toBe('my-actions')
+    const params = ag.params as { title: string; layout: string; gap: string }
+    expect(params.title).toBe('Suite')
+    expect(params.layout).toBe('end')
+    expect(params.gap).toBe('sm')
+  })
+})
+
+describe('connectorResultToUILayout (v6.6.0)', () => {
+  it('assembles primary + supplemental + actions into one UILayout', () => {
+    const layout = connectorResultToUILayout(VALID)
+    // primary (1) + supplemental (1) + action-group (1)
+    expect(layout.components).toHaveLength(3)
+    expect(layout.components[0].id).toBe('tbl')
+    expect(layout.components[1].id).toBe('mtr')
+    expect(layout.components[2].type).toBe('action-group')
+    expect(layout.grid.columns).toBe(12)
+  })
+
+  it('derives a stable layout id from connectorId + queryHash', () => {
+    const layout = connectorResultToUILayout(VALID)
+    expect(layout.id).toBe('connector-datagouv-abc123')
+  })
+
+  it('omits the action-group when there are no actions', () => {
+    const { actions, ...noActions } = VALID
+    void actions
+    const layout = connectorResultToUILayout(noActions)
+    expect(layout.components.every((c) => c.type !== 'action-group')).toBe(true)
+  })
+
+  it('spreads the components of a primary that is itself a layout', () => {
+    const withLayoutPrimary = {
+      ...VALID,
+      primary: {
+        id: 'inner',
+        components: [
+          { id: 'p1', type: 'metric', position: { colStart: 1, colSpan: 6 }, params: {} },
+          { id: 'p2', type: 'metric', position: { colStart: 7, colSpan: 6 }, params: {} },
+        ],
+        grid: { columns: 12, gap: '1rem' },
+      },
+    }
+    const layout = connectorResultToUILayout(withLayoutPrimary)
+    const ids = layout.components.map((c) => c.id)
+    expect(ids).toContain('p1')
+    expect(ids).toContain('p2')
+  })
+
+  it('fills a missing grid position with full-width', () => {
+    const noPos = {
+      ...VALID,
+      supplemental: undefined,
+      actions: undefined,
+      primary: { id: 'np', type: 'text', params: { content: 'x' } },
+    }
+    const layout = connectorResultToUILayout(noPos)
+    expect(layout.components[0].position).toEqual({ colStart: 1, colSpan: 12 })
+  })
+
+  // ── R2 — unknown schemaVersion, never throw ───────────────
+  it('renders a degraded-but-usable layout for an unknown schemaVersion', () => {
+    const futureVersion = { ...VALID, schemaVersion: 'connector-dynamic-result/v2' }
+    const layout = connectorResultToUILayout(futureVersion)
+    expect(layout.id).toMatch(/^connector-degraded/)
+    // First component is the version warning, the real components follow.
+    expect(layout.components[0].id).toBe('connector-version-warning')
+    expect(layout.components.some((c) => c.id === 'tbl')).toBe(true)
+  })
+
+  it('renders an explicit error layout for an unreadable payload — never throws', () => {
+    for (const bad of [null, undefined, 42, 'nope', {}, { foo: 'bar' }]) {
+      let layout!: ReturnType<typeof connectorResultToUILayout>
+      expect(() => {
+        layout = connectorResultToUILayout(bad)
+      }).not.toThrow()
+      expect(layout.id).toBe('connector-degraded')
+      expect(layout.components[0].id).toBe('connector-degraded-notice')
+      expect(layout.components[0].type).toBe('text')
+    }
+  })
+
+  it('is pure — same input yields a deep-equal output', () => {
+    expect(connectorResultToUILayout(VALID)).toEqual(connectorResultToUILayout(VALID))
+  })
+})
+
+describe('connector adapters — spec fixtures', () => {
+  const FIXTURE_DIR = join(
+    __dirname,
+    '..',
+    '..',
+    '..',
+    'mcp-ui-spec',
+    'examples',
+    'connector'
+  )
+  const fixtures = readdirSync(FIXTURE_DIR).filter((f) => f.endsWith('.json'))
+
+  for (const file of fixtures) {
+    it(`fixture ${file} assembles into a non-degraded layout`, () => {
+      const raw = JSON.parse(readFileSync(join(FIXTURE_DIR, file), 'utf8'))
+      const layout = connectorResultToUILayout(raw)
+      expect(layout.id).not.toMatch(/^connector-degraded/)
+      expect(layout.components.length).toBeGreaterThan(0)
+    })
+  }
+})

package/src/adapters/connector.ts

@@ -0,0 +1,234 @@
+/**
+ * Connector adapters — `ConnectorDynamicResultV1` → MCP-UI render structures.
+ *
+ * @since v6.6.0 (D5 / D6 of ROADMAP-opendata-macro-mcpui)
+ *
+ * ## Opt-in, pure
+ *
+ * These adapters are published under the dedicated subpath
+ * `@seed-ship/mcp-ui-solid/adapters` — they are NEVER imported by the core
+ * renderer path, so a consumer that does not emit connector results pays
+ * nothing for them.
+ *
+ * Every adapter here is a **pure function** (D5) : same input → same
+ * output, no `fetch`, no `localStorage`, no global state, no clock, no
+ * randomness. This is what lets a host re-run an adapter deterministically
+ * after presentation feedback (D1) and replay fixtures in tests.
+ *
+ * ## Unknown schema version — never throw (R2)
+ *
+ * `connectorResultToUILayout()` never throws on the runtime render path.
+ * A payload it cannot read becomes an explicit degraded `UILayout` (a
+ * visible notice), never a silent disappearance and never an exception.
+ */
+
+import type { UIComponent, UILayout, GridPosition } from '../types'
+import {
+  ConnectorDynamicResultV1Schema,
+  CONNECTOR_DYNAMIC_RESULT_V1,
+  type ConnectorAction,
+} from '@seed-ship/mcp-ui-spec'
+import { z } from 'zod'
+
+// ─────────────────────────────────────────────────────────────
+// connectorActionsToActionGroup
+// ─────────────────────────────────────────────────────────────
+
+export interface ConnectorActionsToActionGroupOptions {
+  /** Component id. Default `'connector-actions'`. */
+  id?: string
+  /** Optional heading shown above the buttons. */
+  title?: string
+  /** Button row layout. Default `'horizontal'`. */
+  layout?: 'horizontal' | 'vertical' | 'space-between' | 'end' | 'center'
+  /** Gap between buttons. Default `'md'`. */
+  gap?: 'none' | 'sm' | 'md' | 'lg'
+  /** Grid position. Default full-width. */
+  position?: GridPosition
+}
+
+/**
+ * Wraps a connector's `actions` into an `action-group` `UIComponent`.
+ *
+ * `ConnectorAction` is the exact `action-group` action shape, so this is a
+ * thin, pure envelope — no transformation of the actions themselves.
+ */
+export function connectorActionsToActionGroup(
+  actions: ConnectorAction[],
+  options: ConnectorActionsToActionGroupOptions = {}
+): UIComponent {
+  return {
+    id: options.id ?? 'connector-actions',
+    type: 'action-group',
+    position: options.position ?? { colStart: 1, colSpan: 12 },
+    params: {
+      actions,
+      ...(options.title ? { title: options.title } : {}),
+      layout: options.layout ?? 'horizontal',
+      gap: options.gap ?? 'md',
+    },
+  } as UIComponent
+}
+
+// ─────────────────────────────────────────────────────────────
+// connectorResultToUILayout
+// ─────────────────────────────────────────────────────────────
+
+export interface ConnectorResultToUILayoutOptions {
+  /** Layout id. Default derived from `connectorId` + `queryHash` / `toolName`. */
+  id?: string
+  /** Heading for the actions `action-group`. */
+  actionsTitle?: string
+}
+
+/**
+ * Lenient mirror of `ConnectorDynamicResultV1Schema` — `schemaVersion`
+ * relaxed to any string. Used to tell apart "unknown version but otherwise
+ * a usable envelope" (→ render with a warning, R2) from "truly unreadable"
+ * (→ explicit error state).
+ */
+const LenientResultSchema = z.object({
+  schemaVersion: z.string(),
+  connectorId: z.string().min(1),
+  toolName: z.string().min(1),
+  query: z.string(),
+  queryHash: z.string().optional(),
+  intent: z.string().optional(),
+  primary: z.record(z.unknown()),
+  supplemental: z.array(z.record(z.unknown())).optional(),
+  actions: z.array(z.record(z.unknown())).optional(),
+})
+
+const DEFAULT_GRID = { columns: 12, gap: '1rem' } as const
+
+function withPosition(component: UIComponent): UIComponent {
+  if (component && component.position) return component
+  return { ...component, position: { colStart: 1, colSpan: 12 } }
+}
+
+/** A component is a UILayout when it carries a `components` array. */
+function isLayoutShape(value: Record<string, unknown>): boolean {
+  return Array.isArray((value as { components?: unknown }).components)
+}
+
+function degradedTextComponent(id: string, message: string): UIComponent {
+  return {
+    id,
+    type: 'text',
+    position: { colStart: 1, colSpan: 12 },
+    params: { markdown: true, content: message },
+  } as UIComponent
+}
+
+/**
+ * Assembles a `ConnectorDynamicResultV1` into a single `UILayout` :
+ * `primary` + `supplemental[]` + (`actions` → an `action-group`).
+ *
+ * - When `primary` is itself a layout, its components are spread in.
+ * - Raw data is never sacrificed — every supplied component is kept.
+ * - Pure : no side effects, deterministic.
+ *
+ * ### Degraded behavior (R2)
+ *
+ * - Valid v1 payload → normal assembled layout.
+ * - Unknown `schemaVersion` but an otherwise-usable envelope → the
+ *   components are still rendered, prefixed with a visible warning notice.
+ * - Unreadable payload → an explicit error `UILayout` (a single `text`
+ *   notice). Never throws, never returns an empty layout silently.
+ *
+ * A degraded layout always has an `id` starting with `connector-degraded`,
+ * so a host can detect it (e.g. for telemetry) without inspecting content.
+ */
+export function connectorResultToUILayout(
+  result: unknown,
+  options: ConnectorResultToUILayoutOptions = {}
+): UILayout {
+  const strict = ConnectorDynamicResultV1Schema.safeParse(result)
+
+  // ── Tier 3 : unreadable ───────────────────────────────────
+  if (!strict.success) {
+    const lenient = LenientResultSchema.safeParse(result)
+    if (!lenient.success) {
+      const version =
+        result && typeof result === 'object'
+          ? (result as { schemaVersion?: unknown }).schemaVersion
+          : undefined
+      return {
+        id: 'connector-degraded',
+        components: [
+          degradedTextComponent(
+            'connector-degraded-notice',
+            `### Résultat non rendu\n\nLe résultat du connecteur n'a pas pu être interprété${
+              typeof version === 'string' ? ` (schéma : \`${version}\`)` : ''
+            }. Cet état explicite remplace une disparition silencieuse du rendu.`
+          ),
+        ],
+        grid: { ...DEFAULT_GRID },
+      }
+    }
+    // ── Tier 2 : usable envelope, unknown version ───────────
+    const r = lenient.data
+    const components: UIComponent[] = [
+      degradedTextComponent(
+        'connector-version-warning',
+        `> ⚠ Schéma connecteur non reconnu (\`${r.schemaVersion}\`, attendu \`${CONNECTOR_DYNAMIC_RESULT_V1}\`). Le rendu ci-dessous est en mode dégradé.`
+      ),
+      ...collectComponents(r),
+    ]
+    return {
+      id: options.id ?? `connector-degraded-${r.connectorId}`,
+      components: components.map(withPosition),
+      grid: { ...DEFAULT_GRID },
+    }
+  }
+
+  // ── Tier 1 : valid v1 ─────────────────────────────────────
+  const r = strict.data
+  const components = collectComponents(r, options.actionsTitle).map(withPosition)
+  return {
+    id: options.id ?? layoutId(r.connectorId, r.queryHash ?? r.toolName),
+    components,
+    grid: { ...DEFAULT_GRID },
+  }
+}
+
+/**
+ * Flattens `primary` + `supplemental` + `actions` into a component list.
+ * Shared by the valid and degraded-but-usable paths.
+ */
+function collectComponents(
+  r: {
+    primary: Record<string, unknown>
+    supplemental?: Record<string, unknown>[]
+    actions?: unknown[]
+  },
+  actionsTitle?: string
+): UIComponent[] {
+  const components: UIComponent[] = []
+
+  if (isLayoutShape(r.primary)) {
+    const inner = (r.primary as { components?: UIComponent[] }).components ?? []
+    components.push(...inner)
+  } else {
+    components.push(r.primary as unknown as UIComponent)
+  }
+
+  if (r.supplemental) {
+    components.push(...(r.supplemental as unknown as UIComponent[]))
+  }
+
+  if (Array.isArray(r.actions) && r.actions.length > 0) {
+    components.push(
+      connectorActionsToActionGroup(r.actions as ConnectorAction[], {
+        id: 'connector-actions',
+        title: actionsTitle,
+      })
+    )
+  }
+
+  return components
+}
+
+function layoutId(connectorId: string, suffix: string): string {
+  return `connector-${connectorId}-${suffix}`
+}

package/src/adapters/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @seed-ship/mcp-ui-solid/adapters
+ *
+ * Opt-in, pure adapters that turn connector / macro contracts into MCP-UI
+ * render structures. Published as a dedicated subpath so the core renderer
+ * path never depends on them.
+ *
+ * @example
+ * ```ts
+ * import { connectorResultToUILayout } from '@seed-ship/mcp-ui-solid/adapters'
+ *
+ * const layout = connectorResultToUILayout(connectorResult)
+ * // → <UIResourceRenderer content={layout} />
+ * ```
+ */
+
+export {
+  connectorResultToUILayout,
+  connectorActionsToActionGroup,
+} from './connector'
+export type {
+  ConnectorResultToUILayoutOptions,
+  ConnectorActionsToActionGroupOptions,
+} from './connector'

package/src/components/ActionGroupRenderer.test.tsx

@@ -12,6 +12,7 @@ import type { UIComponent, ActionGroupParams, ActionComponentParams } from '../t
 vi.mock('../hooks/useAction', () => ({
   useAction: () => ({
     execute: vi.fn().mockResolvedValue({ success: true }),
+    executeAction: vi.fn().mockResolvedValue({ success: true }),
     isExecuting: () => false,
     lastResult: () => undefined,
     lastError: () => undefined,

package/src/components/ActionGroupRenderer.tsx

@@ -26,7 +26,12 @@ const ActionButton: Component<{
   action: ActionComponentParams
   index: number
 }> = (props) => {
-  const { execute, isExecuting } = useAction()
+  const { execute, executeAction, isExecuting } = useAction()
+
+  // tool-call and submit both go through the host executor — they show a
+  // loading state and gate disabled while running. link does neither.
+  const isExecutable = () =>
+    props.action.action === 'tool-call' || props.action.action === 'submit'
 
   const handleClick = async (e: MouseEvent) => {
     if (props.action.disabled) return
@@ -34,13 +39,23 @@ const ActionButton: Component<{
     if (props.action.action === 'tool-call' && props.action.toolName) {
       e.preventDefault()
       await execute(props.action.toolName, props.action.params || {})
+    } else if (props.action.action === 'submit') {
+      // submit is NOT a tool call — route it through the executor with the
+      // `action: 'submit'` kind preserved so the host can POST to
+      // params.submit_url etc. Works without a surrounding <form>.
+      e.preventDefault()
+      await executeAction({
+        action: 'submit',
+        toolName: props.action.toolName || 'submit',
+        params: props.action.params || {},
+      })
     } else if (props.action.action === 'link' && props.action.url) {
       window.open(props.action.url, '_blank', 'noopener,noreferrer')
     }
   }
 
   const isDisabled = () =>
-    props.action.disabled || (props.action.action === 'tool-call' && isExecuting())
+    props.action.disabled || (isExecutable() && isExecuting())
 
   const variantClass = () => {
     switch (props.action.variant) {
@@ -98,10 +113,10 @@ const ActionButton: Component<{
         isDisabled() ? 'opacity-50 cursor-not-allowed' : ''
       }`}
     >
-      <Show when={isExecuting() && props.action.action === 'tool-call'}>
+      <Show when={isExecuting() && isExecutable()}>
         <span class="animate-spin h-4 w-4 border-2 border-current border-t-transparent rounded-full" />
       </Show>
-      <Show when={props.action.icon && !(isExecuting() && props.action.action === 'tool-call')}>
+      <Show when={props.action.icon && !(isExecuting() && isExecutable())}>
         <span class="text-current">{props.action.icon}</span>
       </Show>
       {props.action.label}