@mcp-html-bridge/ui-engine 0.1.0

package/src/renderers/composite.ts

@@ -0,0 +1,73 @@
+// ── Composite Renderer: orchestrates multiple renderers for mixed data ──
+import { escapeHtml } from '../html-builder.js';
+import { sniff } from '../data-sniffer.js';
+import { renderDataGrid } from './data-grid.js';
+import { renderJsonTree } from './json-tree.js';
+import { renderReadingBlock } from './reading-block.js';
+import { renderMetricsCard } from './metrics-card.js';
+import type { RenderIntent } from '../types.js';
+
+function humanizeKey(key: string): string {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]/g, ' ')
+    .replace(/^\w/, (c) => c.toUpperCase())
+    .trim();
+}
+
+function renderByIntent(intent: RenderIntent, data: unknown, metadata: Record<string, unknown>): string {
+  switch (intent) {
+    case 'data-grid':
+      return renderDataGrid(data, metadata);
+    case 'metrics-card':
+      return renderMetricsCard(data, metadata);
+    case 'reading-block':
+      return renderReadingBlock(data, metadata);
+    case 'json-tree':
+      return renderJsonTree(data, metadata);
+    default:
+      return renderJsonTree(data, metadata);
+  }
+}
+
+export function renderComposite(
+  data: unknown,
+  _metadata: Record<string, unknown>
+): string {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    // For arrays or primitives, just sniff and render directly
+    const results = sniff(data);
+    const best = results[0];
+    return renderByIntent(best.intent, data, best.metadata);
+  }
+
+  const obj = data as Record<string, unknown>;
+  const sections: string[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    const results = sniff(value);
+    const best = results[0];
+    const label = humanizeKey(key);
+
+    sections.push(`<section class="composite-section animate-in">
+  <h3 class="section-title">${escapeHtml(label)}</h3>
+  ${renderByIntent(best.intent, value, best.metadata)}
+</section>`);
+  }
+
+  return `<div class="composite-layout">${sections.join('\n')}</div>`;
+}
+
+export function getCompositeCSS(): string {
+  return `
+.composite-layout {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-8);
+}
+
+.composite-section {
+  /* Each section self-contained */
+}
+`;
+}

package/src/renderers/data-grid.ts

@@ -0,0 +1,159 @@
+// ── Data Grid Renderer: Array of objects → sortable table ──
+import { escapeHtml } from '../html-builder.js';
+
+const STATUS_MAP: Record<string, string> = {
+  active: 'badge-success',
+  enabled: 'badge-success',
+  available: 'badge-success',
+  in_stock: 'badge-success',
+  completed: 'badge-success',
+  inactive: 'badge-danger',
+  disabled: 'badge-danger',
+  out_of_stock: 'badge-danger',
+  backorder: 'badge-warning',
+  pending: 'badge-warning',
+  processing: 'badge-warning',
+  low_stock: 'badge-warning',
+  info: 'badge-info',
+  draft: 'badge-info',
+};
+
+function formatCell(value: unknown, key: string): string {
+  if (value === null || value === undefined) return '<span class="null">—</span>';
+
+  const strVal = String(value);
+
+  // Status badge detection
+  const normalized = strVal.toLowerCase().replace(/[\s-]+/g, '_');
+  if (STATUS_MAP[normalized]) {
+    return `<span class="badge ${STATUS_MAP[normalized]}">${escapeHtml(strVal)}</span>`;
+  }
+
+  // Price formatting detection
+  if (typeof value === 'number' && /price|cost|amount|total|revenue/i.test(key)) {
+    return `<span class="price">$${value.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}</span>`;
+  }
+
+  // Number formatting
+  if (typeof value === 'number') {
+    return `<span class="num">${value.toLocaleString()}</span>`;
+  }
+
+  // Boolean
+  if (typeof value === 'boolean') {
+    return value ? '<span class="bool-true">✓</span>' : '<span class="bool-false">✗</span>';
+  }
+
+  // Nested object/array → compact JSON
+  if (typeof value === 'object') {
+    return `<code class="cell-json">${escapeHtml(JSON.stringify(value))}</code>`;
+  }
+
+  return escapeHtml(strVal);
+}
+
+function humanizeKey(key: string): string {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]/g, ' ')
+    .replace(/^\w/, (c) => c.toUpperCase())
+    .trim();
+}
+
+export function renderDataGrid(
+  data: unknown,
+  metadata: Record<string, unknown>
+): string {
+  const rows = data as Record<string, unknown>[];
+  const columns = (metadata['columns'] as string[]) ?? Object.keys(rows[0] ?? {});
+
+  const headerCells = columns
+    .map(
+      (col, i) =>
+        `<th onclick="__mcpSort(${i})" class="sortable">${escapeHtml(humanizeKey(col))}<span class="sort-icon">⇅</span></th>`
+    )
+    .join('');
+
+  const bodyRows = rows
+    .map(
+      (row, ri) =>
+        `<tr class="animate-in" style="animation-delay:${Math.min(ri * 20, 300)}ms">${columns.map((col) => `<td>${formatCell(row[col], col)}</td>`).join('')}</tr>`
+    )
+    .join('\n');
+
+  const rowCount = rows.length;
+  const colCount = columns.length;
+
+  return `<div class="grid-container card">
+  <div class="grid-header">
+    <span class="grid-meta">${rowCount} rows × ${colCount} columns</span>
+  </div>
+  <div class="table-wrap">
+    <table class="data-table" id="mcp-grid">
+      <thead><tr>${headerCells}</tr></thead>
+      <tbody>${bodyRows}</tbody>
+    </table>
+  </div>
+</div>`;
+}
+
+export function getDataGridCSS(): string {
+  return `
+.grid-container { overflow: hidden; }
+.grid-header {
+  display: flex; justify-content: space-between; align-items: center;
+  padding-bottom: var(--sp-3); margin-bottom: var(--sp-3); border-bottom: 1px solid var(--border);
+}
+.grid-meta { font-size: var(--text-xs); color: var(--text-tertiary); }
+.table-wrap { overflow-x: auto; }
+.data-table { width: 100%; border-collapse: collapse; font-size: var(--text-sm); }
+.data-table th {
+  text-align: left; padding: var(--sp-2) var(--sp-3);
+  font-weight: 600; color: var(--text-secondary); font-size: var(--text-xs);
+  text-transform: uppercase; letter-spacing: 0.05em;
+  border-bottom: 2px solid var(--border);
+  white-space: nowrap; user-select: none;
+}
+.sortable { cursor: pointer; }
+.sortable:hover { color: var(--accent); }
+.sort-icon { margin-left: 4px; opacity: 0.3; font-size: 10px; }
+.data-table td {
+  padding: var(--sp-2) var(--sp-3); border-bottom: 1px solid var(--border);
+  vertical-align: middle;
+}
+.data-table tbody tr:hover { background: var(--accent-subtle); }
+.data-table tbody tr:nth-child(even) { background: var(--bg-secondary); }
+.data-table tbody tr:nth-child(even):hover { background: var(--accent-subtle); }
+
+.null { color: var(--text-tertiary); }
+.price { font-weight: 600; font-variant-numeric: tabular-nums; }
+.num { font-variant-numeric: tabular-nums; }
+.bool-true { color: var(--success); font-weight: 700; }
+.bool-false { color: var(--danger); font-weight: 700; }
+.cell-json { font-size: var(--text-xs); max-width: 200px; overflow: hidden; text-overflow: ellipsis; display: inline-block; }
+`;
+}
+
+export function getDataGridJS(): string {
+  return `
+function __mcpSort(colIdx) {
+  var table = document.getElementById('mcp-grid');
+  if (!table) return;
+  var tbody = table.tBodies[0];
+  var rows = Array.from(tbody.rows);
+  var dir = table.dataset.sortDir === 'asc' ? 'desc' : 'asc';
+  table.dataset.sortDir = dir;
+  table.dataset.sortCol = colIdx;
+
+  rows.sort(function(a, b) {
+    var av = a.cells[colIdx].textContent.trim();
+    var bv = b.cells[colIdx].textContent.trim();
+    var an = parseFloat(av.replace(/[^\\d.-]/g, ''));
+    var bn = parseFloat(bv.replace(/[^\\d.-]/g, ''));
+    if (!isNaN(an) && !isNaN(bn)) return dir === 'asc' ? an - bn : bn - an;
+    return dir === 'asc' ? av.localeCompare(bv) : bv.localeCompare(av);
+  });
+
+  rows.forEach(function(row) { tbody.appendChild(row); });
+}`;
+}

package/src/renderers/form.ts

@@ -0,0 +1,200 @@
+// ── Form Renderer: JSON Schema → interactive form ──
+import type { JSONSchema } from '../types.js';
+import { escapeHtml } from '../html-builder.js';
+
+function renderField(name: string, schema: JSONSchema, required: boolean): string {
+  const label = schema.title ?? name;
+  const desc = schema.description ? `<div class="field-desc">${escapeHtml(schema.description)}</div>` : '';
+  const requiredAttr = required ? 'required' : '';
+  const requiredMark = required ? '<span class="required">*</span>' : '';
+
+  // Enum → capsule select
+  if (schema.enum && schema.enum.length > 0) {
+    const capsules = schema.enum
+      .map((v) => {
+        const val = escapeHtml(String(v));
+        return `<label class="capsule"><input type="radio" name="${escapeHtml(name)}" value="${val}"><span>${val}</span></label>`;
+      })
+      .join('\n');
+    return `<div class="field animate-in">
+  <label class="field-label">${escapeHtml(label)}${requiredMark}</label>
+  ${desc}
+  <div class="capsule-group">${capsules}</div>
+</div>`;
+  }
+
+  // Boolean → toggle
+  if (schema.type === 'boolean') {
+    const checked = schema.default === true ? 'checked' : '';
+    return `<div class="field animate-in">
+  <label class="toggle-label">
+    <input type="checkbox" name="${escapeHtml(name)}" ${checked}>
+    <span class="toggle-switch"></span>
+    <span>${escapeHtml(label)}${requiredMark}</span>
+  </label>
+  ${desc}
+</div>`;
+  }
+
+  // Nested object → collapsible section
+  if (schema.type === 'object' && schema.properties) {
+    const inner = renderProperties(schema.properties, schema.required ?? []);
+    return `<details class="nested-section animate-in" open>
+  <summary class="section-title">${escapeHtml(label)}${requiredMark}</summary>
+  ${desc}
+  <div class="nested-fields">${inner}</div>
+</details>`;
+  }
+
+  // Array → textarea hint
+  if (schema.type === 'array') {
+    return `<div class="field animate-in">
+  <label class="field-label" for="f-${escapeHtml(name)}">${escapeHtml(label)}${requiredMark}</label>
+  ${desc}
+  <textarea id="f-${escapeHtml(name)}" name="${escapeHtml(name)}" class="input textarea" placeholder="JSON array..." ${requiredAttr}>${escapeHtml(String(schema.default ?? ''))}</textarea>
+</div>`;
+  }
+
+  // Number/integer
+  if (schema.type === 'number' || schema.type === 'integer') {
+    const min = schema.minimum !== undefined ? `min="${schema.minimum}"` : '';
+    const max = schema.maximum !== undefined ? `max="${schema.maximum}"` : '';
+    const step = schema.type === 'integer' ? 'step="1"' : '';
+    const def = schema.default !== undefined ? `value="${escapeHtml(String(schema.default))}"` : '';
+    return `<div class="field animate-in">
+  <label class="field-label" for="f-${escapeHtml(name)}">${escapeHtml(label)}${requiredMark}</label>
+  ${desc}
+  <input type="number" id="f-${escapeHtml(name)}" name="${escapeHtml(name)}" class="input" ${min} ${max} ${step} ${def} ${requiredAttr}>
+</div>`;
+  }
+
+  // String (default)
+  const inputType = schema.format === 'email' ? 'email'
+    : schema.format === 'uri' ? 'url'
+    : schema.format === 'date' ? 'date'
+    : schema.format === 'date-time' ? 'datetime-local'
+    : schema.format === 'password' ? 'password'
+    : 'text';
+
+  const isLong = (schema.maxLength && schema.maxLength > 200) || schema.format === 'textarea';
+  const def = schema.default !== undefined ? escapeHtml(String(schema.default)) : '';
+
+  if (isLong) {
+    return `<div class="field animate-in">
+  <label class="field-label" for="f-${escapeHtml(name)}">${escapeHtml(label)}${requiredMark}</label>
+  ${desc}
+  <textarea id="f-${escapeHtml(name)}" name="${escapeHtml(name)}" class="input textarea" ${requiredAttr}>${def}</textarea>
+</div>`;
+  }
+
+  return `<div class="field animate-in">
+  <label class="field-label" for="f-${escapeHtml(name)}">${escapeHtml(label)}${requiredMark}</label>
+  ${desc}
+  <input type="${inputType}" id="f-${escapeHtml(name)}" name="${escapeHtml(name)}" class="input" value="${def}" ${requiredAttr}>
+</div>`;
+}
+
+function renderProperties(
+  properties: Record<string, JSONSchema>,
+  required: string[]
+): string {
+  const reqSet = new Set(required);
+  return Object.entries(properties)
+    .map(([name, schema]) => renderField(name, schema, reqSet.has(name)))
+    .join('\n');
+}
+
+export function renderForm(
+  schema: JSONSchema,
+  metadata: Record<string, unknown>
+): string {
+  const toolName = metadata['toolName'] as string | undefined;
+  const toolDesc = metadata['toolDescription'] as string | undefined;
+
+  const header = toolName
+    ? `<div class="form-header"><h2>${escapeHtml(toolName)}</h2>${toolDesc ? `<p class="form-desc">${escapeHtml(toolDesc)}</p>` : ''}</div>`
+    : '';
+
+  const fields = schema.properties
+    ? renderProperties(schema.properties, schema.required ?? [])
+    : '<p class="text-secondary">No input parameters required.</p>';
+
+  return `${header}
+<form id="mcp-form" class="mcp-form card" onsubmit="return __mcpSubmit(event)">
+${fields}
+<div class="form-actions">
+  <button type="submit" class="btn btn-primary">Execute Tool</button>
+  <button type="reset" class="btn btn-ghost">Reset</button>
+</div>
+</form>`;
+}
+
+export function getFormCSS(): string {
+  return `
+.mcp-form { display: flex; flex-direction: column; gap: var(--sp-5); max-width: 640px; }
+.form-header h2 { font-size: var(--text-2xl); font-weight: 700; }
+.form-desc { color: var(--text-secondary); margin-top: var(--sp-1); }
+
+.field { display: flex; flex-direction: column; gap: var(--sp-1); }
+.field-label { font-weight: 600; font-size: var(--text-sm); color: var(--text-primary); }
+.field-desc { font-size: var(--text-xs); color: var(--text-tertiary); }
+.required { color: var(--danger); margin-left: 2px; }
+
+.input {
+  padding: var(--sp-2) var(--sp-3);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  font-size: var(--text-sm);
+  font-family: var(--font-sans);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+}
+.input:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-subtle); }
+.textarea { min-height: 80px; resize: vertical; }
+
+.capsule-group { display: flex; flex-wrap: wrap; gap: var(--sp-2); }
+.capsule input { display: none; }
+.capsule span {
+  display: inline-block;
+  padding: var(--sp-1) var(--sp-3);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-full);
+  font-size: var(--text-sm);
+  cursor: pointer;
+  transition: all var(--duration-fast) var(--ease-out);
+}
+.capsule input:checked + span { background: var(--accent); color: var(--accent-text); border-color: var(--accent); }
+.capsule span:hover { border-color: var(--accent); }
+
+.toggle-label { display: flex; align-items: center; gap: var(--sp-2); cursor: pointer; font-weight: 600; font-size: var(--text-sm); }
+.toggle-label input { display: none; }
+.toggle-switch {
+  width: 36px; height: 20px; background: var(--border-strong); border-radius: 10px;
+  position: relative; transition: background var(--duration-fast) var(--ease-out);
+}
+.toggle-switch::after {
+  content: ''; position: absolute; top: 2px; left: 2px;
+  width: 16px; height: 16px; background: white; border-radius: 50%;
+  transition: transform var(--duration-fast) var(--ease-out);
+}
+.toggle-label input:checked + .toggle-switch { background: var(--accent); }
+.toggle-label input:checked + .toggle-switch::after { transform: translateX(16px); }
+
+.nested-section { border: 1px solid var(--border); border-radius: var(--radius-md); padding: var(--sp-4); }
+.nested-section summary { cursor: pointer; user-select: none; }
+.nested-fields { margin-top: var(--sp-4); display: flex; flex-direction: column; gap: var(--sp-4); }
+
+.form-actions { display: flex; gap: var(--sp-3); margin-top: var(--sp-2); }
+.btn {
+  padding: var(--sp-2) var(--sp-5); border-radius: var(--radius-sm);
+  font-weight: 600; font-size: var(--text-sm); cursor: pointer; border: none;
+  transition: all var(--duration-fast) var(--ease-out);
+}
+.btn-primary { background: var(--accent); color: var(--accent-text); }
+.btn-primary:hover { background: var(--accent-hover); }
+.btn-ghost { background: transparent; color: var(--text-secondary); border: 1px solid var(--border); }
+.btn-ghost:hover { background: var(--bg-tertiary); }
+`;
+}

package/src/renderers/json-tree.ts

@@ -0,0 +1,141 @@
+// ── JSON Tree Renderer: recursive collapsible tree ──
+import { escapeHtml } from '../html-builder.js';
+
+function typeClass(val: unknown): string {
+  if (val === null) return 'jt-null';
+  if (typeof val === 'string') return 'jt-string';
+  if (typeof val === 'number') return 'jt-number';
+  if (typeof val === 'boolean') return 'jt-boolean';
+  return '';
+}
+
+function formatValue(val: unknown): string {
+  if (val === null) return '<span class="jt-null">null</span>';
+  if (typeof val === 'string') return `<span class="jt-string">"${escapeHtml(val)}"</span>`;
+  if (typeof val === 'number') return `<span class="jt-number">${val}</span>`;
+  if (typeof val === 'boolean') return `<span class="jt-boolean">${val}</span>`;
+  return escapeHtml(String(val));
+}
+
+function renderNode(key: string | null, val: unknown, depth: number): string {
+  const keyHtml = key !== null ? `<span class="jt-key">${escapeHtml(key)}</span><span class="jt-colon">: </span>` : '';
+  const indent = depth * 16;
+  const nodeId = `jt-${Math.random().toString(36).slice(2, 8)}`;
+
+  if (val === null || typeof val !== 'object') {
+    return `<div class="jt-line" style="padding-left:${indent}px">
+  ${keyHtml}${formatValue(val)}
+  <button class="jt-copy" onclick="__mcpCopy(this)" data-val="${escapeHtml(JSON.stringify(val))}" title="Copy">⎘</button>
+</div>`;
+  }
+
+  const isArray = Array.isArray(val);
+  const entries = isArray
+    ? (val as unknown[]).map((v, i) => [String(i), v] as const)
+    : Object.entries(val as Record<string, unknown>);
+
+  const bracket = isArray ? ['[', ']'] : ['{', '}'];
+  const count = entries.length;
+  const preview = count === 0 ? (isArray ? '[]' : '{}') : '';
+
+  if (count === 0) {
+    return `<div class="jt-line" style="padding-left:${indent}px">${keyHtml}<span class="jt-bracket">${preview}</span></div>`;
+  }
+
+  const children = entries.map(([k, v]) => renderNode(isArray ? null : k, v, depth + 1)).join('\n');
+
+  return `<div class="jt-node" style="padding-left:${indent}px">
+  <div class="jt-toggle" onclick="__mcpToggle('${nodeId}')">
+    <span class="jt-arrow" id="${nodeId}-arrow">▼</span>
+    ${keyHtml}<span class="jt-bracket">${bracket[0]}</span>
+    <span class="jt-count">${count} ${isArray ? 'items' : 'keys'}</span>
+    <button class="jt-copy" onclick="event.stopPropagation();__mcpCopy(this)" data-val="${escapeHtml(JSON.stringify(val))}" title="Copy">⎘</button>
+  </div>
+  <div class="jt-children" id="${nodeId}">${children}</div>
+  <div style="padding-left:0"><span class="jt-bracket">${bracket[1]}</span></div>
+</div>`;
+}
+
+export function renderJsonTree(
+  data: unknown,
+  _metadata: Record<string, unknown>
+): string {
+  return `<div class="json-tree card">
+  <div class="jt-toolbar">
+    <button class="btn btn-ghost btn-sm" onclick="__mcpExpandAll()">Expand All</button>
+    <button class="btn btn-ghost btn-sm" onclick="__mcpCollapseAll()">Collapse All</button>
+    <button class="btn btn-ghost btn-sm" onclick="__mcpCopyAll()">Copy JSON</button>
+  </div>
+  <div class="jt-root">${renderNode(null, data, 0)}</div>
+</div>`;
+}
+
+export function getJsonTreeCSS(): string {
+  return `
+.json-tree { font-family: var(--font-mono); font-size: var(--text-sm); overflow-x: auto; }
+.jt-toolbar { display: flex; gap: var(--sp-2); margin-bottom: var(--sp-3); padding-bottom: var(--sp-3); border-bottom: 1px solid var(--border); }
+.btn-sm { padding: var(--sp-1) var(--sp-2); font-size: var(--text-xs); }
+
+.jt-line, .jt-node > .jt-toggle { padding: 2px 0; display: flex; align-items: center; gap: 4px; }
+.jt-toggle { cursor: pointer; user-select: none; }
+.jt-toggle:hover { background: var(--accent-subtle); border-radius: var(--radius-sm); }
+.jt-arrow { font-size: 10px; width: 14px; text-align: center; transition: transform var(--duration-fast) var(--ease-out); display: inline-block; }
+.jt-arrow.collapsed { transform: rotate(-90deg); }
+
+.jt-key { color: var(--accent); font-weight: 600; }
+.jt-colon { color: var(--text-tertiary); }
+.jt-string { color: #22863a; }
+.jt-number { color: #005cc5; }
+.jt-boolean { color: #d73a49; }
+.jt-null { color: var(--text-tertiary); font-style: italic; }
+.jt-bracket { color: var(--text-tertiary); font-weight: 700; }
+.jt-count { color: var(--text-tertiary); font-size: var(--text-xs); margin-left: var(--sp-1); }
+
+@media (prefers-color-scheme: dark) {
+  .jt-string { color: #7ee787; }
+  .jt-number { color: #79c0ff; }
+  .jt-boolean { color: #ff7b72; }
+}
+
+.jt-children { overflow: hidden; }
+.jt-children.hidden { display: none; }
+.jt-copy {
+  opacity: 0; border: none; background: none; cursor: pointer;
+  color: var(--text-tertiary); font-size: 14px; padding: 0 4px;
+  transition: opacity var(--duration-fast) var(--ease-out);
+}
+.jt-line:hover .jt-copy, .jt-toggle:hover .jt-copy { opacity: 1; }
+.jt-copy:hover { color: var(--accent); }
+`;
+}
+
+export function getJsonTreeJS(): string {
+  return `
+var __mcpTreeData;
+function __mcpToggle(id) {
+  var el = document.getElementById(id);
+  var arrow = document.getElementById(id + '-arrow');
+  if (!el) return;
+  el.classList.toggle('hidden');
+  if (arrow) arrow.classList.toggle('collapsed');
+}
+function __mcpExpandAll() {
+  document.querySelectorAll('.jt-children').forEach(function(el) { el.classList.remove('hidden'); });
+  document.querySelectorAll('.jt-arrow').forEach(function(el) { el.classList.remove('collapsed'); });
+}
+function __mcpCollapseAll() {
+  document.querySelectorAll('.jt-children').forEach(function(el) { el.classList.add('hidden'); });
+  document.querySelectorAll('.jt-arrow').forEach(function(el) { el.classList.add('collapsed'); });
+}
+function __mcpCopy(btn) {
+  var val = btn.getAttribute('data-val');
+  navigator.clipboard.writeText(val).then(function() {
+    var orig = btn.textContent;
+    btn.textContent = '✓';
+    setTimeout(function() { btn.textContent = orig; }, 1000);
+  });
+}
+function __mcpCopyAll() {
+  if (__mcpTreeData) navigator.clipboard.writeText(JSON.stringify(__mcpTreeData, null, 2));
+}`;
+}

package/src/renderers/metrics-card.ts

@@ -0,0 +1,108 @@
+// ── Metrics Card Renderer: KPI/summary → card layout ──
+import { escapeHtml } from '../html-builder.js';
+
+function formatMetricValue(value: number, key: string): string {
+  // Percentage
+  if (/rate|ratio|percent|pct/i.test(key)) {
+    return `${(value * (value <= 1 ? 100 : 1)).toFixed(1)}%`;
+  }
+  // Currency
+  if (/price|cost|revenue|amount|total|value/i.test(key)) {
+    if (value >= 1_000_000) return `$${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1_000) return `$${(value / 1_000).toFixed(1)}K`;
+    return `$${value.toFixed(2)}`;
+  }
+  // Large numbers
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}K`;
+  // Scientific notation for very small/large
+  if (Math.abs(value) < 0.001 && value !== 0) return value.toExponential(2);
+
+  return Number.isInteger(value) ? value.toLocaleString() : value.toFixed(2);
+}
+
+function humanizeKey(key: string): string {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]/g, ' ')
+    .replace(/^\w/, (c) => c.toUpperCase())
+    .trim();
+}
+
+export function renderMetricsCard(
+  data: unknown,
+  _metadata: Record<string, unknown>
+): string {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return '<div class="card">Invalid metrics data</div>';
+  }
+
+  const obj = data as Record<string, unknown>;
+  const cards: string[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'number') {
+      const formatted = formatMetricValue(value, key);
+      const label = humanizeKey(key);
+      cards.push(`<div class="metric-card animate-in">
+  <div class="metric-label">${escapeHtml(label)}</div>
+  <div class="metric-value">${escapeHtml(formatted)}</div>
+</div>`);
+    } else if (typeof value === 'string') {
+      cards.push(`<div class="metric-card metric-text animate-in">
+  <div class="metric-label">${escapeHtml(humanizeKey(key))}</div>
+  <div class="metric-text-value">${escapeHtml(value)}</div>
+</div>`);
+    }
+  }
+
+  return `<div class="metrics-grid">${cards.join('\n')}</div>`;
+}
+
+export function getMetricsCardCSS(): string {
+  return `
+.metrics-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: var(--sp-4);
+}
+
+.metric-card {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: var(--sp-5);
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-2);
+  transition: box-shadow var(--duration-fast) var(--ease-out),
+              transform var(--duration-fast) var(--ease-out);
+}
+.metric-card:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+.metric-label {
+  font-size: var(--text-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-tertiary);
+}
+
+.metric-value {
+  font-size: var(--text-3xl);
+  font-weight: 800;
+  color: var(--text-primary);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: -0.02em;
+}
+
+.metric-text-value {
+  font-size: var(--text-base);
+  font-weight: 500;
+  color: var(--text-secondary);
+}
+`;
+}