@mcp-html-bridge/ui-engine 0.5.1 → 0.6.0

package/dist/utilities.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tailwind-like atomic utility classes.
+ *
+ * Maps familiar Tailwind class names to our CSS variable system.
+ * LLMs already know Tailwind syntax from training data — by providing
+ * these utilities, we ensure any model produces visually consistent HTML
+ * that automatically respects light/dark mode.
+ *
+ * This is NOT a full Tailwind build. It's a curated subset:
+ * - Layout (flex, grid, gap)
+ * - Spacing (p-*, m-*)
+ * - Typography (text-*, font-*)
+ * - Colors (text-*, bg-*, border-*)
+ * - Borders & radius
+ * - Shadows & effects
+ * - Sizing & overflow
+ */
+export declare function generateUtilityCSS(): string;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wBAAgB,kBAAkB,IAAI,MAAM,CA4S3C"}

package/{src/utilities.ts → dist/utilities.js}

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Tailwind-like atomic utility classes.
  *
@@ -15,9 +16,10 @@
  * - Shadows & effects
  * - Sizing & overflow
  */
-
-export function generateUtilityCSS(): string {
-  return `
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUtilityCSS = generateUtilityCSS;
+function generateUtilityCSS() {
+    return `
 /* ══════════════════════════════════════════
    Tailwind-compatible utility classes
    Mapped to CSS variable theming system
@@ -317,3 +319,4 @@ export function generateUtilityCSS(): string {
 }
 `;
 }
+//# sourceMappingURL=utilities.js.map

package/dist/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAEH,gDA4SC;AA5SD,SAAgB,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0SR,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-html-bridge/ui-engine",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Core UI rendering engine — schema/data → self-contained HTML",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,6 +10,9 @@
       "default": "./dist/index.js"
     }
   },
+  "files": [
+    "dist/"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist"

package/src/engine.ts

@@ -1,118 +0,0 @@
-// ── 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 { renderJSON, getRendererCSS, getRendererJS } from './renderer.js';
-import { renderWithLLM } from './llm-renderer.js';
-import { renderForm, getFormCSS } from './renderers/form.js';
-import { generatePlaygroundHTML, getPlaygroundCSS, getPlaygroundJS } from './playground.js';
-import { generateUtilityCSS } from './utilities.js';
-
-/** Options for rendering */
-interface DataRenderOptions extends RenderOptions {
-  toolName?: string;
-  toolDescription?: string;
-  /** LLM config for semantic rendering. Omit for structural fallback. */
-  llm?: LLMConfig;
-}
-
-/** 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) {
-    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 + playgroundHTML,
-    js: jsParts.join('\n'),
-  });
-}
-
-/**
- * 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 body = renderForm(schema, {
-    toolName: options.toolName,
-    toolDescription: options.toolDescription,
-  });
-
-  const playground = options.debug ? generatePlaygroundHTML() : '';
-
-  const css = [
-    generateThemeCSS(),
-    generateUtilityCSS(),
-    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,
-  });
-}
-
-/** Unified API */
-export async function render(input: EngineInput, options: DataRenderOptions = {}): Promise<string> {
-  if (input.mode === 'schema') {
-    return renderFromSchema(input.schema, {
-      ...options,
-      toolName: input.toolName,
-      toolDescription: input.toolDescription,
-    });
-  }
-  return renderFromData(input.data, {
-    ...options,
-    toolName: input.toolName,
-    toolDescription: input.toolDescription,
-  });
-}

package/src/html-builder.ts

@@ -1,61 +0,0 @@
-// ── Safe HTML string builder with XSS prevention ──
-
-const ESCAPE_MAP: Record<string, string> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-};
-
-/** Escape HTML special characters to prevent XSS */
-export function escapeHtml(str: string): string {
-  return str.replace(/[&<>"']/g, (ch) => ESCAPE_MAP[ch] ?? ch);
-}
-
-/** Build an HTML opening tag with attributes */
-export function tag(
-  name: string,
-  attrs: Record<string, string | boolean | undefined> = {},
-  selfClosing = false
-): string {
-  const attrStr = Object.entries(attrs)
-    .filter(([, v]) => v !== undefined && v !== false)
-    .map(([k, v]) => (v === true ? k : `${k}="${escapeHtml(String(v))}"`))
-    .join(' ');
-  const open = attrStr ? `<${name} ${attrStr}` : `<${name}`;
-  return selfClosing ? `${open} />` : `${open}>`;
-}
-
-/** Wrap content in a style tag */
-export function style(css: string): string {
-  return `<style>\n${css}\n</style>`;
-}
-
-/** Wrap content in a script tag */
-export function script(js: string): string {
-  return `<script>\n${js}\n</script>`;
-}
-
-/** Wrap content in a complete HTML document */
-export function document(opts: {
-  title?: string;
-  css?: string;
-  js?: string;
-  body: string;
-}): string {
-  const titleTag = opts.title ? `<title>${escapeHtml(opts.title)}</title>` : '';
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-${titleTag}
-${opts.css ? style(opts.css) : ''}
-</head>
-<body>
-${opts.body}
-${opts.js ? script(opts.js) : ''}
-</body>
-</html>`;
-}

package/src/llm-renderer.ts

@@ -1,129 +0,0 @@
-/**
- * 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 };