@mcp-html-bridge/ui-engine 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-html-bridge/ui-engine",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Core UI rendering engine — schema/data → self-contained HTML",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -1,91 +1,80 @@
-// ── Engine Orchestrator: main entry point ──
-import type { EngineInput, RenderIntent, RenderOptions, JSONSchema } from './types.js';
+// ── Engine Orchestrator: JSON → self-contained HTML document ──
+import type { EngineInput, RenderOptions, JSONSchema } from './types.js';
+import type { LLMConfig } from './llm-renderer.js';
 import { document as htmlDocument } from './html-builder.js';
 import { generateThemeCSS } from './theme.js';
 import { generateBridgeJS } from './bridge.js';
-import { sniff, sniffSchema } from './data-sniffer.js';
+import { renderJSON, getRendererCSS, getRendererJS } from './renderer.js';
+import { renderWithLLM } from './llm-renderer.js';
 import { renderForm, getFormCSS } from './renderers/form.js';
-import { renderDataGrid, getDataGridCSS, getDataGridJS } from './renderers/data-grid.js';
-import { renderJsonTree, getJsonTreeCSS, getJsonTreeJS } from './renderers/json-tree.js';
-import { renderReadingBlock, getReadingBlockCSS } from './renderers/reading-block.js';
-import { renderMetricsCard, getMetricsCardCSS } from './renderers/metrics-card.js';
-import { renderComposite, getCompositeCSS } from './renderers/composite.js';
 import { generatePlaygroundHTML, getPlaygroundCSS, getPlaygroundJS } from './playground.js';
+import { generateUtilityCSS } from './utilities.js';
 
-/** Extended options that allow explicit renderer selection */
+/** Options for rendering */
 interface DataRenderOptions extends RenderOptions {
   toolName?: string;
   toolDescription?: string;
-  /** Explicitly choose a renderer. Skips auto-detection when set. */
-  renderer?: RenderIntent;
+  /** LLM config for semantic rendering. Omit for structural fallback. */
+  llm?: LLMConfig;
 }
 
-/** Assemble a full HTML document from a chosen renderer's output */
-function assembleDocument(
-  intent: RenderIntent,
-  data: unknown,
-  metadata: Record<string, unknown>,
-  options: DataRenderOptions
-): string {
-  let body: string;
-  const cssParts = [generateThemeCSS()];
-  const jsParts = [generateBridgeJS()];
-
-  switch (intent) {
-    case 'data-grid':
-      body = renderDataGrid(data, metadata);
-      cssParts.push(getDataGridCSS());
-      jsParts.push(getDataGridJS());
-      break;
-    case 'metrics-card':
-      body = renderMetricsCard(data, metadata);
-      cssParts.push(getMetricsCardCSS());
-      break;
-    case 'reading-block':
-      body = renderReadingBlock(data, metadata);
-      cssParts.push(getReadingBlockCSS());
-      break;
-    case 'json-tree':
-      body = renderJsonTree(data, metadata);
-      cssParts.push(getJsonTreeCSS());
-      jsParts.push(getJsonTreeJS());
-      jsParts.push(`__mcpTreeData = ${JSON.stringify(data)};`);
-      break;
-    case 'composite':
-      body = renderComposite(data, metadata);
-      cssParts.push(getDataGridCSS(), getMetricsCardCSS(), getReadingBlockCSS(), getJsonTreeCSS(), getCompositeCSS());
-      jsParts.push(getDataGridJS(), getJsonTreeJS());
-      break;
-    default:
-      body = renderJsonTree(data, metadata);
-      cssParts.push(getJsonTreeCSS());
-      jsParts.push(getJsonTreeJS());
-      jsParts.push(`__mcpTreeData = ${JSON.stringify(data)};`);
-  }
+/** Build the document wrapper around an HTML body fragment */
+function buildDocument(body: string, options: DataRenderOptions, extraCSS = '', extraJS = ''): string {
+  const cssParts = [generateThemeCSS(), generateUtilityCSS(), extraCSS];
+  const jsParts = [generateBridgeJS(), extraJS];
 
   if (options.debug) {
-    body += generatePlaygroundHTML();
     cssParts.push(getPlaygroundCSS());
     jsParts.push(getPlaygroundJS());
   }
 
+  const playgroundHTML = options.debug ? generatePlaygroundHTML() : '';
+
   return htmlDocument({
     title: options.title ?? options.toolName ?? 'MCP Result',
     css: cssParts.join('\n'),
-    body,
+    body: body + playgroundHTML,
     js: jsParts.join('\n'),
   });
 }
 
-/** Render a form from a JSON Schema (for tool input) */
+/**
+ * Render any JSON data as a full HTML document.
+ *
+ * - If `options.llm` is provided: calls the LLM for semantic rendering (async).
+ * - If omitted: uses the structural renderer (sync, returned as resolved Promise).
+ */
+export async function renderFromData(
+  data: unknown,
+  options: DataRenderOptions = {}
+): Promise<string> {
+  if (options.llm) {
+    const body = await renderWithLLM(data, options.llm);
+    // Always include structural CSS/JS — the LLM fallback path may produce structural HTML
+    return buildDocument(body, options, getRendererCSS(), getRendererJS());
+  }
+
+  const body = renderJSON(data);
+  return buildDocument(body, options, getRendererCSS(), getRendererJS());
+}
+
+/**
+ * Sync structural rendering (no LLM). Use when you know you don't need LLM.
+ */
+export function renderFromDataSync(
+  data: unknown,
+  options: Omit<DataRenderOptions, 'llm'> = {}
+): string {
+  const body = renderJSON(data);
+  return buildDocument(body, options, getRendererCSS(), getRendererJS());
+}
+
+/** Render a form from a JSON Schema (for tool input). Always sync. */
 export function renderFromSchema(
   schema: JSONSchema,
   options: DataRenderOptions = {}
 ): string {
-  const sniffResult = sniffSchema(schema as Record<string, unknown>);
-
   const body = renderForm(schema, {
-    ...sniffResult.metadata,
     toolName: options.toolName,
     toolDescription: options.toolDescription,
   });
@@ -94,6 +83,7 @@ export function renderFromSchema(
 
   const css = [
     generateThemeCSS(),
+    generateUtilityCSS(),
     getFormCSS(),
     options.debug ? getPlaygroundCSS() : '',
   ].join('\n');
@@ -111,33 +101,8 @@ export function renderFromSchema(
   });
 }
 
-/**
- * Render HTML from tool result data.
- *
- * When `options.renderer` is set, that renderer is used directly —
- * the heuristic sniffer is bypassed entirely. This is the recommended
- * path when an LLM (e.g. Claude in Claude Code) has already decided
- * the best visualization strategy.
- *
- * When `options.renderer` is omitted, falls back to the built-in
- * confidence-scored heuristic sniffer for auto-detection.
- */
-export function renderFromData(
-  data: unknown,
-  options: DataRenderOptions = {}
-): string {
-  if (options.renderer) {
-    // LLM-driven path: explicit renderer, no heuristic
-    return assembleDocument(options.renderer, data, {}, options);
-  }
-
-  // Fallback: heuristic auto-detection
-  const results = sniff(data);
-  return assembleDocument(results[0].intent, data, results[0].metadata, options);
-}
-
 /** Unified API */
-export function render(input: EngineInput, options: DataRenderOptions = {}): string {
+export async function render(input: EngineInput, options: DataRenderOptions = {}): Promise<string> {
   if (input.mode === 'schema') {
     return renderFromSchema(input.schema, {
       ...options,
@@ -151,22 +116,3 @@ export function render(input: EngineInput, options: DataRenderOptions = {}): str
     toolDescription: input.toolDescription,
   });
 }
-
-/**
- * Available renderers — exported for programmatic use.
- * Each renderer takes raw data and returns an HTML fragment (not a full document).
- * Use renderFromData() with `renderer` option for full document output.
- */
-export const renderers = {
-  'data-grid': renderDataGrid,
-  'metrics-card': renderMetricsCard,
-  'json-tree': renderJsonTree,
-  'reading-block': renderReadingBlock,
-  'composite': renderComposite,
-  'form': renderForm,
-} as const;
-
-/** List of available renderer names */
-export const availableRenderers: readonly RenderIntent[] = [
-  'data-grid', 'metrics-card', 'json-tree', 'reading-block', 'composite', 'form',
-];

package/src/index.ts

@@ -3,36 +3,32 @@ export {
   render,
   renderFromSchema,
   renderFromData,
-  renderers,
-  availableRenderers,
+  renderFromDataSync,
 } from './engine.js';
 
-// Heuristic sniffer (fallback when no LLM is available)
-export { sniff, sniffSchema } from './data-sniffer.js';
+// Universal JSON → HTML renderer (structural fallback)
+export { renderJSON, getRendererCSS, getRendererJS } from './renderer.js';
+
+// LLM-powered semantic renderer
+export { renderWithLLM, RENDERING_PROMPT } from './llm-renderer.js';
+export type { LLMConfig } from './llm-renderer.js';
 
 // Building blocks (for custom composition)
 export { generateThemeCSS } from './theme.js';
+export { generateUtilityCSS } from './utilities.js';
 export { generateBridgeJS } from './bridge.js';
 export { escapeHtml, tag, style, script, document } from './html-builder.js';
 
-// Individual renderers (for direct LLM-driven usage)
-export { renderDataGrid, getDataGridCSS, getDataGridJS } from './renderers/data-grid.js';
-export { renderMetricsCard, getMetricsCardCSS } from './renderers/metrics-card.js';
-export { renderJsonTree, getJsonTreeCSS, getJsonTreeJS } from './renderers/json-tree.js';
-export { renderReadingBlock, getReadingBlockCSS } from './renderers/reading-block.js';
-export { renderComposite, getCompositeCSS } from './renderers/composite.js';
+// Form renderer (JSON Schema → form UI)
 export { renderForm, getFormCSS } from './renderers/form.js';
 
 // Re-export types
 export type {
-  RenderIntent,
-  SniffResult,
   RenderOptions,
   EngineInput,
   SchemaInput,
   DataInput,
   JSONSchema,
-  Renderer,
   MCPToolDefinition,
   MCPServerInfo,
 } from './types.js';

package/src/llm-renderer.ts

@@ -0,0 +1,129 @@
+/**
+ * LLM-powered semantic renderer.
+ *
+ * The structural renderer (renderer.ts) maps JSON shapes to HTML mechanically.
+ * This module sends JSON to an LLM with a rendering prompt,
+ * letting the model understand semantics and produce the best HTML.
+ *
+ * Supports any OpenAI-compatible API.
+ */
+
+/** Configuration for the LLM endpoint */
+export interface LLMConfig {
+  /** API base URL (e.g. "http://localhost:11434/v1") */
+  apiUrl: string;
+  /** API key (optional for local models) */
+  apiKey?: string;
+  /** Model name */
+  model: string;
+}
+
+/**
+ * The rendering prompt.
+ *
+ * This is intentionally short and non-prescriptive. We tell the model
+ * WHAT to do (produce the best HTML for this data), not HOW to do it
+ * (don't enumerate SVG, markdown, etc.). The model should figure out
+ * the semantics on its own.
+ */
+const SYSTEM_PROMPT = `You are a JSON-to-HTML renderer. You receive JSON data and produce an HTML fragment that visualizes it in the best way possible.
+
+Rules:
+1. Output ONLY an HTML fragment. No <html>, <head>, <body> wrappers — those exist already.
+2. Understand what the data MEANS, not just its shape. Render content in its native form — if something is meant to be seen, show it; if it's meant to be read, format it; if it's structured, organize it.
+3. Use these CSS variables for theming (light/dark mode is handled automatically):
+   Colors: --bg-primary, --bg-secondary, --bg-tertiary, --bg-elevated, --text-primary, --text-secondary, --text-tertiary, --accent, --accent-subtle, --success, --warning, --danger, --info (each has a -subtle variant), --border, --border-strong
+   Typography: --font-sans, --font-mono, --text-xs to --text-3xl
+   Spacing: --sp-1 (4px) to --sp-12 (48px)
+   Radius: --radius-sm, --radius-md, --radius-lg, --radius-full
+   Shadows: --shadow-sm, --shadow-md, --shadow-lg
+   Utility classes: .card, .badge, .badge-success, .badge-warning, .badge-danger, .badge-info, .section-title
+4. Tailwind-compatible utility classes are available. Use them freely: flex, grid, gap-*, p-*, m-*, text-*, bg-*, border, rounded-*, shadow-*, font-*, items-*, justify-*, w-full, h-full, overflow-*, relative/absolute, etc. Responsive prefixes sm: and md: work too.
+5. Do not invent data. Do not add commentary. Just the HTML.
+6. Do not wrap output in markdown code fences.`;
+
+/**
+ * Call an OpenAI-compatible chat completions API.
+ */
+async function callLLM(
+  data: unknown,
+  config: LLMConfig
+): Promise<string> {
+  const url = config.apiUrl.replace(/\/+$/, '') + '/chat/completions';
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (config.apiKey) {
+    headers['Authorization'] = `Bearer ${config.apiKey}`;
+  }
+
+  const body = {
+    model: config.model,
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user', content: JSON.stringify(data, null, 2) },
+    ],
+    temperature: 0.2,
+    max_tokens: 16384,
+  };
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`LLM API ${response.status}: ${text.slice(0, 300)}`);
+  }
+
+  const result = await response.json() as {
+    choices?: Array<{ message?: { content?: string } }>;
+  };
+
+  const content = result.choices?.[0]?.message?.content;
+  if (!content) {
+    throw new Error('LLM returned empty response');
+  }
+
+  return stripCodeFences(content);
+}
+
+/** Remove markdown code fences if the LLM wrapped its output */
+function stripCodeFences(html: string): string {
+  const trimmed = html.trim();
+  const fenceMatch = trimmed.match(/^```(?:html)?\s*\n([\s\S]*?)\n\s*```$/);
+  if (fenceMatch) {
+    return fenceMatch[1].trim();
+  }
+  return trimmed;
+}
+
+/**
+ * Render JSON data using an LLM for semantic understanding.
+ * Returns an HTML fragment (not a full document).
+ * Falls back to structural renderer on failure.
+ */
+export async function renderWithLLM(
+  data: unknown,
+  config: LLMConfig
+): Promise<string> {
+  try {
+    const html = await callLLM(data, config);
+    return `<div class="mcp-root">${html}</div>`;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`  LLM rendering failed: ${message}`);
+    console.error('  Falling back to structural renderer.');
+
+    const { renderJSON } = await import('./renderer.js');
+    const fallbackHTML = renderJSON(data);
+    const errorBanner = `<div style="padding:var(--sp-3);margin-bottom:var(--sp-4);background:var(--warning-subtle);border:1px solid var(--warning);border-radius:var(--radius-sm);font-size:var(--text-sm);color:var(--text-primary)">LLM rendering failed: ${message.replace(/</g, '&lt;')}. Showing structural fallback.</div>`;
+    return `<div class="mcp-root">${errorBanner}${fallbackHTML}</div>`;
+  }
+}
+
+/** Export the system prompt for inspection/customization */
+export { SYSTEM_PROMPT as RENDERING_PROMPT };