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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-html-bridge/ui-engine",
-  "version": "0.2.0",
+  "version": "0.3.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,5 +1,5 @@
 // ── Engine Orchestrator: main entry point ──
-import type { EngineInput, RenderOptions, JSONSchema } from './types.js';
+import type { EngineInput, RenderIntent, RenderOptions, JSONSchema } from './types.js';
 import { document as htmlDocument } from './html-builder.js';
 import { generateThemeCSS } from './theme.js';
 import { generateBridgeJS } from './bridge.js';
@@ -12,81 +12,52 @@ import { renderMetricsCard, getMetricsCardCSS } from './renderers/metrics-card.j
 import { renderComposite, getCompositeCSS } from './renderers/composite.js';
 import { generatePlaygroundHTML, getPlaygroundCSS, getPlaygroundJS } from './playground.js';
 
-/** Render a form from a JSON Schema (for tool input) */
-export function renderFromSchema(
-  schema: JSONSchema,
-  options: RenderOptions & { toolName?: string; toolDescription?: string } = {}
-): string {
-  const sniffResult = sniffSchema(schema as Record<string, unknown>);
-
-  const body = renderForm(schema, {
-    ...sniffResult.metadata,
-    toolName: options.toolName,
-    toolDescription: options.toolDescription,
-  });
-
-  const playground = options.debug ? generatePlaygroundHTML() : '';
-
-  const css = [
-    generateThemeCSS(),
-    getFormCSS(),
-    options.debug ? getPlaygroundCSS() : '',
-  ].join('\n');
-
-  const js = [
-    generateBridgeJS(),
-    options.debug ? getPlaygroundJS() : '',
-  ].join('\n');
-
-  return htmlDocument({
-    title: options.title ?? options.toolName ?? 'MCP Tool',
-    css,
-    body: body + playground,
-    js,
-  });
+/** Extended options that allow explicit renderer selection */
+interface DataRenderOptions extends RenderOptions {
+  toolName?: string;
+  toolDescription?: string;
+  /** Explicitly choose a renderer. Skips auto-detection when set. */
+  renderer?: RenderIntent;
 }
 
-/** Render HTML from tool result data */
-export function renderFromData(
+/** Assemble a full HTML document from a chosen renderer's output */
+function assembleDocument(
+  intent: RenderIntent,
   data: unknown,
-  options: RenderOptions & { toolName?: string; toolDescription?: string } = {}
+  metadata: Record<string, unknown>,
+  options: DataRenderOptions
 ): string {
-  const results = sniff(data);
-  const best = results[0];
-
   let body: string;
   const cssParts = [generateThemeCSS()];
   const jsParts = [generateBridgeJS()];
 
-  switch (best.intent) {
+  switch (intent) {
     case 'data-grid':
-      body = renderDataGrid(data, best.metadata);
+      body = renderDataGrid(data, metadata);
       cssParts.push(getDataGridCSS());
       jsParts.push(getDataGridJS());
       break;
     case 'metrics-card':
-      body = renderMetricsCard(data, best.metadata);
+      body = renderMetricsCard(data, metadata);
       cssParts.push(getMetricsCardCSS());
       break;
     case 'reading-block':
-      body = renderReadingBlock(data, best.metadata);
+      body = renderReadingBlock(data, metadata);
       cssParts.push(getReadingBlockCSS());
       break;
     case 'json-tree':
-      body = renderJsonTree(data, best.metadata);
+      body = renderJsonTree(data, metadata);
       cssParts.push(getJsonTreeCSS());
       jsParts.push(getJsonTreeJS());
-      // Inject tree data for copy-all
       jsParts.push(`__mcpTreeData = ${JSON.stringify(data)};`);
       break;
     case 'composite':
-      body = renderComposite(data, best.metadata);
-      // Composite may use all renderers, include all CSS/JS
+      body = renderComposite(data, metadata);
       cssParts.push(getDataGridCSS(), getMetricsCardCSS(), getReadingBlockCSS(), getJsonTreeCSS(), getCompositeCSS());
       jsParts.push(getDataGridJS(), getJsonTreeJS());
       break;
     default:
-      body = renderJsonTree(data, best.metadata);
+      body = renderJsonTree(data, metadata);
       cssParts.push(getJsonTreeCSS());
       jsParts.push(getJsonTreeJS());
       jsParts.push(`__mcpTreeData = ${JSON.stringify(data)};`);
@@ -106,8 +77,67 @@ export function renderFromData(
   });
 }
 
+/** Render a form from a JSON Schema (for tool input) */
+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,
+  });
+
+  const playground = options.debug ? generatePlaygroundHTML() : '';
+
+  const css = [
+    generateThemeCSS(),
+    getFormCSS(),
+    options.debug ? getPlaygroundCSS() : '',
+  ].join('\n');
+
+  const js = [
+    generateBridgeJS(),
+    options.debug ? getPlaygroundJS() : '',
+  ].join('\n');
+
+  return htmlDocument({
+    title: options.title ?? options.toolName ?? 'MCP Tool',
+    css,
+    body: body + playground,
+    js,
+  });
+}
+
+/**
+ * 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: RenderOptions = {}): string {
+export function render(input: EngineInput, options: DataRenderOptions = {}): string {
   if (input.mode === 'schema') {
     return renderFromSchema(input.schema, {
       ...options,
@@ -121,3 +151,22 @@ export function render(input: EngineInput, options: RenderOptions = {}): string
     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

@@ -1,10 +1,28 @@
 // ── Public API ──
-export { render, renderFromSchema, renderFromData } from './engine.js';
+export {
+  render,
+  renderFromSchema,
+  renderFromData,
+  renderers,
+  availableRenderers,
+} from './engine.js';
+
+// Heuristic sniffer (fallback when no LLM is available)
 export { sniff, sniffSchema } from './data-sniffer.js';
+
+// Building blocks (for custom composition)
 export { generateThemeCSS } from './theme.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';
+export { renderForm, getFormCSS } from './renderers/form.js';
+
 // Re-export types
 export type {
   RenderIntent,