@webmcp-auto-ui/ui 2.5.27 → 2.5.28

package/src/index.ts

@@ -16,38 +16,48 @@ export { default as MarkdownView } from './primitives/MarkdownView.svelte';
 export { default as CodeView } from './primitives/CodeView.svelte';
 export { renderMarkdown, highlightCode, createMarkdownRenderer } from './primitives/markdown-renderer.js';
 
-// Simple widgets (PJ blocks)
-export { default as StatBlock } from './widgets/simple/StatBlock.svelte';
-export { default as KVBlock } from './widgets/simple/KVBlock.svelte';
-export { default as ListBlock } from './widgets/simple/ListBlock.svelte';
-export { default as ChartBlock } from './widgets/simple/ChartBlock.svelte';
-export { default as AlertBlock } from './widgets/simple/AlertBlock.svelte';
-export { default as CodeBlock } from './widgets/simple/CodeBlock.svelte';
-export { default as TextBlock } from './widgets/simple/TextBlock.svelte';
-export { default as ActionsBlock } from './widgets/simple/ActionsBlock.svelte';
-export { default as TagsBlock } from './widgets/simple/TagsBlock.svelte';
+// Simple widgets (vanilla renderers) — contract: render(container, data): () => void
+export { render as renderStat }    from './widgets/simple/stat.js';
+export { render as renderKv }      from './widgets/simple/kv.js';
+export { render as renderList }    from './widgets/simple/list.js';
+export { render as renderChart }   from './widgets/simple/chart.js';
+export { render as renderAlert }   from './widgets/simple/alert.js';
+export { render as renderCode }    from './widgets/simple/code.js';
+export { render as renderText }    from './widgets/simple/text.js';
+export { render as renderActions } from './widgets/simple/actions.js';
+export { render as renderTags }    from './widgets/simple/tags.js';
 
-// Rich widgets (Archive)
-export { default as StatCard } from './widgets/rich/StatCard.svelte';
-export { default as DataTable } from './widgets/rich/DataTable.svelte';
-export { default as Timeline } from './widgets/rich/Timeline.svelte';
-export { default as ProfileCard } from './widgets/rich/ProfileCard.svelte';
-export { default as Trombinoscope } from './widgets/rich/Trombinoscope.svelte';
-export { default as JsonViewer } from './widgets/rich/JsonViewer.svelte';
-export { default as Hemicycle } from './widgets/rich/Hemicycle.svelte';
-export { default as Chart } from './widgets/rich/Chart.svelte';
-export { default as Cards } from './widgets/rich/Cards.svelte';
-export { default as GridData } from './widgets/rich/GridData.svelte';
-export { default as Sankey } from './widgets/rich/Sankey.svelte';
-export { default as MapView } from './widgets/rich/MapView.svelte';
-export { default as D3Widget } from './widgets/rich/D3Widget.svelte';
-export { default as JsSandbox } from './widgets/rich/JsSandbox.svelte';
-export { default as LogViewer } from './widgets/rich/LogViewer.svelte';
-export { default as Gallery } from './widgets/rich/Gallery.svelte';
-export { default as Carousel } from './widgets/rich/Carousel.svelte';
+// Rich widgets (vanilla renderers)
+export { render as renderStatCard }      from './widgets/rich/stat-card.js';
+export { render as renderDataTable }     from './widgets/rich/data-table.js';
+export { render as renderTimeline }      from './widgets/rich/timeline.js';
+export { render as renderProfile }       from './widgets/rich/profile.js';
+export { render as renderTrombinoscope } from './widgets/rich/trombinoscope.js';
+export { render as renderJsonViewer }    from './widgets/rich/json-viewer.js';
+export { render as renderHemicycle }     from './widgets/rich/hemicycle.js';
+export { render as renderChartRich }     from './widgets/rich/chart-rich.js';
+export { render as renderCards }         from './widgets/rich/cards.js';
+export { render as renderGridData }      from './widgets/rich/grid-data.js';
+export { render as renderSankey }        from './widgets/rich/sankey.js';
+export { render as renderMap }           from './widgets/rich/map.js';
+export { render as renderD3 }            from './widgets/rich/d3.js';
+export { render as renderJsSandbox }     from './widgets/rich/js-sandbox.js';
+export { render as renderLog }           from './widgets/rich/log.js';
+export { render as renderGallery }       from './widgets/rich/gallery.js';
+export { render as renderCarousel }      from './widgets/rich/carousel.js';
 
-// Safe image (URL validation + error fallback)
-export { default as SafeImage } from './widgets/SafeImage.svelte';
+// Notebook widget renderers (vanilla)
+export { render as renderCompact }              from './widgets/notebook/compact.js';
+export { render as renderWorkspace }            from './widgets/notebook/workspace.js';
+export { render as renderDocument }             from './widgets/notebook/document.js';
+export { render as renderEditorial }            from './widgets/notebook/editorial.js';
+export { render as renderRecipeBrowserWidget } from './widgets/notebook/recipe-browser.js';
+// Notebook types (optional public API)
+export type { NotebookState, NotebookCell } from './widgets/notebook/shared.js';
+
+// Safe image helper (URL validation + error fallback)
+export { createSafeImage } from './widgets/helpers/safe-image.js';
+export type { SafeImageOptions } from './widgets/helpers/safe-image.js';
 
 // Widget export utility
 export { exportWidget, getExportFormats, exportWidgetAs } from './widgets/export-widget.js';
@@ -90,6 +100,7 @@ export { default as ModelLoader } from './agent/ModelLoader.svelte';
 /** @deprecated Use ModelLoader instead. Alias maintained for backward compatibility. */
 export { default as GemmaLoader } from './agent/ModelLoader.svelte';
 export { default as McpStatus } from './agent/McpStatus.svelte';
+export { default as ModelCacheManager } from './agent/ModelCacheManager.svelte';
 export { default as AgentProgress } from './agent/AgentProgress.svelte';
 export { default as McpConnector } from './agent/McpConnector.svelte';
 export { default as ChatPanel } from './agent/ChatPanel.svelte';
@@ -98,6 +109,7 @@ export { default as AgentConsole } from './agent/AgentConsole.svelte';
 export { default as SettingsPanel } from './agent/SettingsPanel.svelte';
 export { default as RemoteMCPserversDemo } from './agent/RemoteMCPserversDemo.svelte';
 export { default as WebMCPserversList } from './agent/WebMCPserversList.svelte';
+export { default as DataServersPanel } from './agent/DataServersPanel.svelte';
 export { default as EphemeralBubble } from './agent/EphemeralBubble.svelte';
 export { default as TokenBubble } from './agent/TokenBubble.svelte';
 export { default as DiagnosticModal } from './agent/DiagnosticModal.svelte';

package/src/widgets/WidgetRenderer.svelte

@@ -2,95 +2,94 @@
   import { type Component, onMount, onDestroy } from 'svelte';
   import type { WebMcpServer } from '@webmcp-auto-ui/core';
   import { bus } from '../messaging/bus.svelte.js';
-  // Simple widgets
-  import StatBlock from './simple/StatBlock.svelte';
-  import KVBlock from './simple/KVBlock.svelte';
-  import ListBlock from './simple/ListBlock.svelte';
-  import ChartBlock from './simple/ChartBlock.svelte';
-  import AlertBlock from './simple/AlertBlock.svelte';
-  import CodeBlock from './simple/CodeBlock.svelte';
-  import TextBlock from './simple/TextBlock.svelte';
-  import ActionsBlock from './simple/ActionsBlock.svelte';
-  import TagsBlock from './simple/TagsBlock.svelte';
-  // Rich widgets
-  import StatCard from './rich/StatCard.svelte';
-  import DataTable from './rich/DataTable.svelte';
-  import Timeline from './rich/Timeline.svelte';
-  import ProfileCard from './rich/ProfileCard.svelte';
-  import Trombinoscope from './rich/Trombinoscope.svelte';
-  import JsonViewer from './rich/JsonViewer.svelte';
-  import Hemicycle from './rich/Hemicycle.svelte';
-  import Chart from './rich/Chart.svelte';
-  import Cards from './rich/Cards.svelte';
-  import GridData from './rich/GridData.svelte';
-  import Sankey from './rich/Sankey.svelte';
-  import MapView from './rich/MapView.svelte';
-  import D3Widget from './rich/D3Widget.svelte';
-  import JsSandbox from './rich/JsSandbox.svelte';
-  import LogViewer from './rich/LogViewer.svelte';
-  import Gallery from './rich/Gallery.svelte';
-  import Carousel from './rich/Carousel.svelte';
-
-  type Emit = (action: string, payload: unknown) => void;
 
-  /** Native widget entry: component + prop builder */
-  type NativeEntry = {
-    component: Component<any>;
-    props: (data: Record<string, unknown>, emit: Emit) => Record<string, unknown>;
-  };
+  // Monotonic counter for busId generation — avoids collisions on sub-ms remounts.
+  let busIdCounter = 0;
+  function makeBusId(widgetType: string): string {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return `block_${widgetType}_${crypto.randomUUID()}`;
+    }
+    return `block_${widgetType}_${Date.now()}-${++busIdCounter}`;
+  }
 
-  /** Simple helper: passes { data } */
-  const d = (c: Component<any>): NativeEntry => ({
-    component: c,
-    props: (data) => ({ data }),
-  });
+  // Safe clone for data passed to vanilla renderers — strips Svelte 5 $state
+  // proxies without crashing on BigInt / circular refs / undefined values.
+  function safeClone<T>(value: T): T {
+    if (value === null || typeof value !== 'object') return value;
+    try {
+      return structuredClone(value);
+    } catch (err) {
+      console.warn('[WidgetRenderer] structuredClone failed, falling back to shallow copy', err);
+      return { ...(value as Record<string, unknown>) } as T;
+    }
+  }
 
-  /** Spec helper: passes { spec } */
-  const s = (c: Component<any>): NativeEntry => ({
-    component: c,
-    props: (data) => ({ spec: data }),
-  });
+  // ── Native vanilla renderers ─────────────────────────────────────────────
+  // Simple widgets
+  import { render as renderStat }    from './simple/stat.js';
+  import { render as renderKv }      from './simple/kv.js';
+  import { render as renderList }    from './simple/list.js';
+  import { render as renderChart }   from './simple/chart.js';
+  import { render as renderAlert }   from './simple/alert.js';
+  import { render as renderCode }    from './simple/code.js';
+  import { render as renderText }    from './simple/text.js';
+  import { render as renderActions } from './simple/actions.js';
+  import { render as renderTags }    from './simple/tags.js';
+  // Rich widgets
+  import { render as renderStatCard }      from './rich/stat-card.js';
+  import { render as renderProfile }       from './rich/profile.js';
+  import { render as renderJsonViewer }    from './rich/json-viewer.js';
+  import { render as renderChartRich }     from './rich/chart-rich.js';
+  import { render as renderSankey }        from './rich/sankey.js';
+  import { render as renderHemicycle }     from './rich/hemicycle.js';
+  import { render as renderDataTable }     from './rich/data-table.js';
+  import { render as renderTimeline }      from './rich/timeline.js';
+  import { render as renderTrombinoscope } from './rich/trombinoscope.js';
+  import { render as renderCards }         from './rich/cards.js';
+  import { render as renderGridData }      from './rich/grid-data.js';
+  import { render as renderMap }           from './rich/map.js';
+  import { render as renderD3 }            from './rich/d3.js';
+  import { render as renderJsSandbox }    from './rich/js-sandbox.js';
+  import { render as renderLog }           from './rich/log.js';
+  import { render as renderGallery }       from './rich/gallery.js';
+  import { render as renderCarousel }      from './rich/carousel.js';
 
-  /** Spec + events helper */
-  const se = (
-    c: Component<any>,
-    events: (emit: Emit) => Record<string, unknown>,
-  ): NativeEntry => ({
-    component: c,
-    props: (data, emit) => ({ spec: data, ...events(emit) }),
-  });
+  /** A vanilla renderer: returns cleanup or Promise thereof. */
+  type VanillaRenderer = (
+    container: HTMLElement,
+    data: Record<string, unknown>,
+  ) => void | (() => void) | Promise<void | (() => void)>;
 
-  /** Static map of all native widget types → component + props */
-  const NATIVE_MAP: Record<string, NativeEntry> = {
-    // Simple widgets (data prop)
-    'stat':           d(StatBlock),
-    'kv':             d(KVBlock),
-    'list':           { component: ListBlock, props: (data, emit) => ({ data, onitemclick: (item: unknown, index: unknown) => emit('itemclick', { item, index }) }) },
-    'chart':          d(ChartBlock),
-    'alert':          d(AlertBlock),
-    'code':           d(CodeBlock),
-    'text':           d(TextBlock),
-    'actions':        d(ActionsBlock),
-    'tags':           d(TagsBlock),
-    // Rich widgets (spec prop)
-    'stat-card':      s(StatCard),
-    'profile':        s(ProfileCard),
-    'json-viewer':    s(JsonViewer),
-    'chart-rich':     s(Chart),
-    'sankey':         s(Sankey),
-    'map':            s(MapView),
-    'd3':             s(D3Widget),
-    'js-sandbox':     s(JsSandbox),
-    'log':            s(LogViewer),
-    // Rich widgets (spec prop + event callbacks)
-    'data-table':     se(DataTable,     (emit) => ({ onrowclick: (row: unknown) => emit('rowclick', row) })),
-    'timeline':       se(Timeline,      (emit) => ({ oneventclick: (e: unknown) => emit('eventclick', e) })),
-    'trombinoscope':  se(Trombinoscope, (emit) => ({ onpersonclick: (p: unknown) => emit('personclick', p) })),
-    'hemicycle':      se(Hemicycle,     (emit) => ({ ongroupclick: (g: unknown) => emit('groupclick', g) })),
-    'cards':          se(Cards,         (emit) => ({ oncardclick: (c: unknown) => emit('cardclick', c) })),
-    'grid-data':      se(GridData,      (emit) => ({ oncellclick: (r: unknown, c: unknown, v: unknown) => emit('cellclick', { row: r, col: c, value: v }) })),
-    'gallery':        se(Gallery,       (emit) => ({ onimageclick: (img: unknown, i: unknown) => emit('imageclick', { image: img, index: i }) })),
-    'carousel':       se(Carousel,      (emit) => ({ onslidechange: (slide: unknown, i: unknown) => emit('slidechange', { slide, index: i }) })),
+  /** Static map of all native widget types → vanilla renderer */
+  const NATIVE_VANILLA_MAP: Record<string, VanillaRenderer> = {
+    // Simple
+    'stat':           renderStat,
+    'kv':             renderKv,
+    'list':           renderList,
+    'chart':          renderChart,
+    'alert':          renderAlert,
+    'code':           renderCode,
+    'text':           renderText,
+    'actions':        renderActions,
+    'tags':           renderTags,
+    // Rich
+    'stat-card':      renderStatCard,
+    'profile':        renderProfile,
+    'json-viewer':    renderJsonViewer,
+    'chart-rich':     renderChartRich,
+    'sankey':         renderSankey,
+    'hemicycle':      renderHemicycle,
+    'data-table':     renderDataTable,
+    'timeline':       renderTimeline,
+    'trombinoscope':  renderTrombinoscope,
+    'cards':          renderCards,
+    'grid-data':      renderGridData,
+    'map':            renderMap,
+    'd3':             renderD3,
+    'js-sandbox':     renderJsSandbox,
+    'log':            renderLog,
+    'gallery':        renderGallery,
+    'carousel':       renderCarousel,
   };
 
   interface Props {
@@ -103,7 +102,7 @@
   let { id, type, data, servers, oninteract }: Props = $props();
 
   // Auto-register on the FONC message bus
-  const busId = id ?? `block_${type}_${Date.now().toString(36)}`;
+  const busId = id ?? makeBusId(type);
   const unregisterBus = bus.register(busId, type, ['data-update', 'interact', '*'], (msg) => {
     if (msg.channel === 'data-update' && msg.payload && typeof msg.payload === 'object') {
       oninteract?.(type, 'bus-update', msg.payload);
@@ -116,7 +115,7 @@
     bus.broadcast(busId, 'interact', { type, action, payload });
   }
 
-  // ── Renderer resolution: servers > native > fallback ────────────
+  // ── Renderer resolution: servers > native vanilla > fallback ────────────
 
   // Look up a custom widget entry from connected WebMCP servers
   const customWidgetEntry = $derived.by(() => {
@@ -129,36 +128,48 @@
   });
 
   const customRenderer = $derived(customWidgetEntry?.renderer ?? null);
+  const isCustomVanilla = $derived(customWidgetEntry?.vanilla === true);
 
-  /** True when the custom renderer is a vanilla function (not a Svelte component) */
-  const isVanillaRenderer = $derived(customWidgetEntry?.vanilla === true);
+  const nativeVanillaRenderer = $derived<VanillaRenderer | undefined>(
+    customRenderer ? undefined : NATIVE_VANILLA_MAP[type],
+  );
+
+  /** True when a vanilla renderer (custom or native) should be used */
+  const useVanilla = $derived(isCustomVanilla || !!nativeVanillaRenderer);
 
-  const nativeEntry: NativeEntry | undefined = $derived(
-    customRenderer ? undefined : NATIVE_MAP[type],
+  /** The effective vanilla renderer to invoke */
+  const vanillaRenderer = $derived<VanillaRenderer | null>(
+    isCustomVanilla
+      ? (customRenderer as VanillaRenderer)
+      : (nativeVanillaRenderer ?? null),
   );
 
-  // Deep-clone data to strip Svelte 5 $state proxies — only needed for vanilla
-  // renderers whose third-party libs (Cytoscape, Plotly, etc.) use
-  // Object.defineProperty which conflicts with Svelte 5 proxies.
-  // Native Svelte components handle proxied data fine and benefit from
-  // fine-grained reactivity, so they receive raw `data` directly.
-  const plainData: Record<string, unknown> = $derived(JSON.parse(JSON.stringify(data)));
+  // Deep-clone data to strip Svelte 5 $state proxies — vanilla renderers + third-party
+  // libs (D3, Leaflet, etc.) rely on Object.defineProperty which conflicts with proxies.
+  const plainData: Record<string, unknown> = $derived(safeClone(data) as Record<string, unknown>);
 
   // ── Vanilla renderer container + lifecycle ────────────
   let vanillaContainer: HTMLElement | undefined = $state(undefined);
 
   $effect(() => {
-    if (!isVanillaRenderer || !vanillaContainer) return;
+    if (!useVanilla || !vanillaRenderer || !vanillaContainer) return;
+    const container = vanillaContainer;
     // Clear previous content
-    vanillaContainer.innerHTML = '';
+    container.innerHTML = '';
+
+    // Listen for the standard vanilla event contract: CustomEvent('widget:interact')
+    const onInteract = (ev: Event) => {
+      const ce = ev as CustomEvent<{ action?: string; payload?: unknown }>;
+      const action = ce.detail?.action ?? 'interact';
+      emit(action, ce.detail?.payload);
+    };
+    container.addEventListener('widget:interact', onInteract);
 
     let cleanup: (() => void) | void;
     let cancelled = false;
 
     try {
-      const result = (customRenderer as (container: HTMLElement, data: Record<string, unknown>) => void | (() => void) | Promise<void | (() => void)>)(
-        vanillaContainer, plainData,
-      );
+      const result = vanillaRenderer(container, plainData);
       if (result && typeof (result as Promise<unknown>).then === 'function') {
         (result as Promise<void | (() => void)>).then(
           (c) => { if (!cancelled) cleanup = c ?? undefined; },
@@ -172,6 +183,7 @@
 
     return () => {
       cancelled = true;
+      container.removeEventListener('widget:interact', onInteract);
       if (typeof cleanup === 'function') {
         try { cleanup(); } catch (err) { console.error('[WidgetRenderer] cleanup failed:', err); }
       }
@@ -238,12 +250,10 @@
   });
 </script>
 
-{#if isVanillaRenderer}
+{#if useVanilla}
   <div bind:this={vanillaContainer} class="vanilla-container w-full h-full overflow-auto p-2"></div>
 {:else if customRenderer}
   <svelte:component this={customRenderer as Component<any>} {data} {id} />
-{:else if nativeEntry}
-  <svelte:component this={nativeEntry.component} {...nativeEntry.props(data, emit)} />
 {:else}
   <div class="p-3 font-mono text-xs text-text2">[{type}]</div>
 {/if}

package/src/widgets/export-widget.ts

@@ -5,7 +5,15 @@
 
 import { toPng } from 'html-to-image';
 
-const TARGET_PNG_WIDTH = 2048;
+const TARGET_PNG_WIDTH = 4096;
+
+export type WidgetExportHook = (scale: number) => Promise<Blob>;
+
+declare global {
+  interface HTMLElement {
+    __exportPng?: WidgetExportHook;
+  }
+}
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
@@ -95,6 +103,25 @@ async function exportPng(type: string, containerEl: HTMLElement): Promise<void>
   const scrollH = Math.max(containerEl.scrollHeight, containerEl.clientHeight, 1);
   const pixelRatio = TARGET_PNG_WIDTH / scrollW;
 
+  // Canvas-based widgets (cytoscape, etc.) expose a native exporter via __exportPng.
+  // html-to-image would only recapture the already-rasterised on-screen pixels,
+  // so we route to the widget's own resolution-independent exporter when available.
+  if (typeof containerEl.__exportPng === 'function') {
+    const scale = Math.max(2, Math.ceil(TARGET_PNG_WIDTH / scrollW));
+    try {
+      const blob = await containerEl.__exportPng(scale);
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = name;
+      a.click();
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+      return;
+    } catch (err) {
+      console.error('[exportWidget] native __exportPng failed, falling back to html-to-image', err);
+    }
+  }
+
   const bg = (typeof document !== 'undefined'
     ? getComputedStyle(document.documentElement).getPropertyValue('--color-surface').trim()
     : '') || '#ffffff';

package/src/widgets/helpers/safe-image.ts

@@ -0,0 +1,78 @@
+/**
+ * SafeImage (vanilla) — URL validation, error fallback, placeholder rendering.
+ * Replaces SafeImage.svelte. Used by Profile/Cards/Carousel/Gallery/Trombinoscope renderers.
+ */
+
+export interface SafeImageOptions {
+  src: string | undefined | null;
+  alt?: string;
+  className?: string;
+  style?: string;
+  loading?: 'lazy' | 'eager';
+  fallbackText?: string;
+  hideOnError?: boolean;
+}
+
+const VALID_PREFIXES = ['http://', 'https://', 'data:', '/'];
+
+function isValidSrc(src: unknown): src is string {
+  return typeof src === 'string' && src.length > 0 && VALID_PREFIXES.some((p) => (src as string).startsWith(p));
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+}
+
+function buildPlaceholder(label: string, opts: SafeImageOptions): HTMLElement {
+  const div = document.createElement('div');
+  div.className = `flex items-center justify-center bg-surface2 text-text2 text-xs ${opts.className ?? ''}`.trim();
+  if (opts.style) div.setAttribute('style', opts.style);
+  div.setAttribute('role', 'img');
+  div.setAttribute('aria-label', label);
+  div.innerHTML =
+    '<svg class="w-5 h-5 opacity-40 mr-1" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">' +
+    '<rect x="3" y="3" width="18" height="18" rx="2"/>' +
+    '<circle cx="8.5" cy="8.5" r="1.5"/>' +
+    '<path d="M21 15l-5-5L5 21"/></svg>' +
+    `<span class="truncate max-w-[80%]">${escapeHtml(label)}</span>`;
+  return div;
+}
+
+function buildHidden(): HTMLElement {
+  const el = document.createElement('div');
+  el.style.display = 'none';
+  el.setAttribute('aria-hidden', 'true');
+  return el;
+}
+
+/**
+ * Returns an HTMLElement for the given image source.
+ * - Invalid/missing URL → placeholder (or hidden element if hideOnError).
+ * - Valid URL → <img> that self-replaces with placeholder on load error.
+ */
+export function createSafeImage(opts: SafeImageOptions): HTMLElement {
+  const label = opts.fallbackText ?? opts.alt ?? 'Image';
+
+  if (!isValidSrc(opts.src)) {
+    return opts.hideOnError ? buildHidden() : buildPlaceholder(label, opts);
+  }
+
+  const img = document.createElement('img');
+  img.src = opts.src;
+  img.alt = opts.alt ?? '';
+  if (opts.className) img.className = opts.className;
+  if (opts.style) img.setAttribute('style', opts.style);
+  img.loading = opts.loading ?? 'lazy';
+  img.referrerPolicy = 'no-referrer';
+
+  img.addEventListener(
+    'error',
+    () => {
+      const replacement = opts.hideOnError ? buildHidden() : buildPlaceholder(label, opts);
+      img.replaceWith(replacement);
+    },
+    { once: true },
+  );
+
+  return img;
+}

package/src/widgets/notebook/chart-renderer.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Chart renderer — Vega-Lite via lazy dynamic import of vega-embed.
+//
+// Design notes:
+//  - vega-embed is imported dynamically so it does not bloat the initial
+//    bundle. The first chart render pays a one-time cost; subsequent charts
+//    share the cached module.
+//  - On failure (missing dep, invalid spec, CSP denies eval, etc.) we fall
+//    back to a readable <pre>JSON</pre> preview of the spec so the user
+//    still sees *something* rather than an empty panel.
+//  - vega-embed is declared as an optional peer dependency in package.json;
+//    apps that want interactive charts install it, others degrade gracefully.
+// ---------------------------------------------------------------------------
+
+export interface ChartRenderer {
+  mount(container: HTMLElement, spec: unknown): void | Promise<void>;
+  destroy(): void;
+}
+
+let cachedEmbed: Promise<any> | null = null;
+
+function loadEmbed(): Promise<any> {
+  if (!cachedEmbed) {
+    // @ts-ignore — vega-embed is an optional peer dep; resolved at runtime
+    cachedEmbed = import('vega-embed').then((m: any) => m?.default ?? m);
+  }
+  return cachedEmbed;
+}
+
+function escapeHtml(s: string): string {
+  return String(s ?? '').replace(/[&<>"']/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+}
+
+function renderFallback(container: HTMLElement, spec: unknown, reason?: string): void {
+  let preview: string;
+  try { preview = JSON.stringify(spec, null, 2); } catch { preview = String(spec); }
+  const note = reason ? `<div class="nb-chart-fallback-note">${escapeHtml(reason)}</div>` : '';
+  container.innerHTML = `${note}<pre class="nb-chart-fallback">${escapeHtml(preview)}</pre>`;
+}
+
+/**
+ * Render a Vega / Vega-Lite spec into the given container. Resolves once the
+ * chart is mounted (or falls back to a JSON preview on error). Never throws.
+ */
+export async function renderChart(container: HTMLElement, spec: unknown): Promise<void> {
+  if (!container) return;
+  if (!spec || typeof spec !== 'object') {
+    renderFallback(container, spec, 'Invalid chart spec');
+    return;
+  }
+  try {
+    const embed = await loadEmbed();
+    if (typeof embed !== 'function') {
+      renderFallback(container, spec, 'vega-embed unavailable');
+      return;
+    }
+    container.innerHTML = '';
+    await embed(container, spec as any, { actions: false, renderer: 'canvas' });
+  } catch (err: any) {
+    renderFallback(container, spec, `chart render failed: ${String(err?.message ?? err)}`);
+  }
+}