@webmcp-auto-ui/ui 2.5.27 → 2.5.28

package/src/widgets/notebook/recipes/editorial.md

@@ -0,0 +1,120 @@
+---
+widget: notebook-editorial
+description: Publication-ready notebook with serif prose and inline cells, all drag-and-droppable in a single ordered flow. Inspired by Observable — cells can be prose paragraphs, sql queries, or js charts, mixed freely in any order to build an article-like narrative.
+schema:
+  type: object
+  properties:
+    id:
+      type: string
+    title:
+      type: string
+    mode:
+      type: string
+      enum: [edit, view]
+    kicker:
+      type: string
+      description: Small uppercase label above the title (e.g. "analysis", "memo", "brief"). Editable inline. Defaults to "untitled".
+    cells:
+      type: array
+      description: Mixed flow of prose and code cells. All share the same ordering and can be reordered together.
+      items:
+        type: object
+        required: [type, content]
+        properties:
+          type:
+            type: string
+            enum: [md, sql, js]
+            description: md = prose paragraph (markdown rendered + sanitized), sql = query cell with table output, js = code cell with chart output
+          content:
+            type: string
+          hideSource:
+            type: boolean
+          hideResult:
+            type: boolean
+---
+
+## When to use
+
+Use `notebook-editorial` when the notebook is meant to be published or shared as a finished artifact:
+- Research memos with code appendices visible on demand
+- Blog-style writeups mixing narrative and runnable code
+- Final deliverables where prose leads and code supports
+
+The distinguishing feature: prose paragraphs and code cells share a single ordered list, both drag-and-droppable with the same handle. This lets users rearrange the story freely without thinking about "sections".
+
+## How to use
+
+1. **Start with prose-first seed content** and intersperse code cells:
+   ```
+   widget_display({name: "notebook-editorial", params: {
+     title: "Q3 observations",
+     kicker: "memo",
+     cells: [
+       {type: "md", content: "This memo covers the highlights of last quarter."},
+       {type: "md", content: "We first look at revenue, then at churn."},
+       {type: "sql", content: "select * from source limit 10"},
+       {type: "md", content: "The table above suggests..."},
+       {type: "js", content: "// render a chart"}
+     ]
+   }})
+   ```
+
+2. **Use prose paragraphs as transitions** between code blocks. The layout emphasizes reading flow.
+
+3. **Code cells render their result in the editorial style**:
+   - SQL cells show a minimal mono-spaced table (live data from the connected MCP server's `*_query_sql` tool).
+   - JS cells run in an isolated Web Worker with upstream named outputs in scope.
+
+4. **Reorder cells freely** — the user can drag a prose paragraph from the bottom to the top, or swap a chart and its introduction, all via the same handle.
+
+## Notes
+
+- The serif font (EB Garamond, with Georgia fallback) applies only to prose content inside this widget — it signals "publication" the moment the user sees it.
+- The **kicker** above the title ("analysis", "memo", "internal") is editable inline — click to rename. Keep it short.
+- Prose cells are rendered via an HTML-sanitizing markdown pipeline: markdown syntax is resolved, unsafe tags are stripped (XSS closed), `<mark>` and other editorial tags are preserved.
+- The footer exposes a single `share` button.
+- Run / Stop controls are at the left of each code cell's header, same as the other notebook layouts.
+- Unlike the other widgets, `notebook-editorial` does not separate prose and code into different flows — they are the same flow in one list.
+
+## Left pane — resources from connected servers
+
+A collapsible **left pane** (bookmark-bar styling, collapsed by default) lists recipes and tools exposed by connected MCP data servers. Clicking any recipe opens a viewer modal; fenced code blocks expose a `↳ inject` button that drops the snippet into the article flow as a new cell.
+
+Two toolbar buttons flank this pane:
+
+- **`+ md`** — 3-tab modal (New / File / URL) to insert a prose paragraph from scratch, a local `.md` file, or a URL.
+- **`+ recipe`** — 3-tab modal (Browser / File / URL) to import a recipe from a connected server, a local `.recipe.md` file, or a URL.
+
+## Share
+
+The `share` button in the footer offers **four formats**:
+
+- **Hyperskill link** — copies both the canonical Hyperskill URL and a short domain-scoped URL (`?n=<token>`). The read-only public viewer lives at `nb.hyperskills.net`.
+- **Markdown** — downloads a `.md` file.
+- **PNG** — snapshots the rendered article.
+- **JSON** — exports full widget state.
+
+## Integration with connected data servers
+
+An editorial piece earns its weight when the prose is anchored to real material. If a MCP **data** server is connected (say `tricoteuses` or `metmuseum`), the agent should — before composing the memo — go and see what the server has to offer:
+
+1. Call `{server}_list_recipes()` or `{server}_search_recipes(query)` to find recipes that speak to the subject at hand.
+2. Call `{server}_list_tools()` to survey the available tables and endpoints.
+3. For each recipe or table worth citing, seed one cell that lets the reader touch the evidence — a modest SQL `SELECT ... LIMIT 10`, a `run_script` call, or a prose paragraph that introduces the figure to come. Let prose and code alternate; the editorial flow is built for exactly that.
+4. Pass the server metadata through the `servers:` param so the footer's share affordance, the left pane, and the connect modal reflect the provenance of the piece:
+
+   ```ts
+   widget_display({
+     name: 'notebook-editorial',
+     params: {
+       title: '...',
+       kicker: 'memo',
+       cells: [...],
+       servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+     }
+   })
+   ```
+
+When no data server is connected, seed a prose-first skeleton that stakes out the argument and gently invites the reader to connect an MCP server so the memo can take on flesh.
+
+**Filter rule**: only MCP *data* servers (`kind: 'data'`) belong in `servers:`. WebMCP UI servers like `autoui` are kept out — they hold no queryable material and have no place in the editorial masthead.

package/src/widgets/notebook/recipes/workspace.md

@@ -0,0 +1,119 @@
+---
+widget: notebook-workspace
+description: Dense analyst workspace with a header bar (title, draft/published tag, run all, publish) and a left sidebar listing data sources and cells for navigation. Cells display their name, execution time, and row counts. Targets data-team workflows with a publishable deliverable.
+schema:
+  type: object
+  properties:
+    id:
+      type: string
+    title:
+      type: string
+    mode:
+      type: string
+      enum: [edit, view]
+    cells:
+      type: array
+      items:
+        type: object
+        required: [type, content]
+        properties:
+          type:
+            type: string
+            enum: [md, sql, js]
+          content:
+            type: string
+          name:
+            type: string
+            description: Cell name shown in sidebar navigation (e.g. "intro", "sql_sales", "plot")
+          hideSource:
+            type: boolean
+          hideResult:
+            type: boolean
+---
+
+## When to use
+
+Use `notebook-workspace` for analyst-oriented work that needs:
+- Multi-cell analyses with named, navigable cells (sidebar)
+- A clear separation between the editing context and a publishable "app" view
+- A data source reference permanently visible (even as placeholder: "no source connected")
+- Team workflows where "run all" and "publish" are distinct actions
+
+This layout is more enterprise-flavoured than `notebook-compact`. Prefer it when the user is building something to hand off, not just exploring.
+
+## How to use
+
+1. **Create with named cells** so the sidebar navigation is meaningful:
+   ```
+   widget_display({name: "notebook-workspace", params: {
+     title: "My analysis",
+     cells: [
+       {type: "md", name: "intro", content: "What we are investigating."},
+       {type: "sql", name: "fetch_rows", content: "select * from source limit 100"},
+       {type: "js", name: "visualize", content: "// chart the rows"}
+     ]
+   }})
+   ```
+
+2. **The sidebar shows** data sources (when connected) and the numbered list of cells. Clicking a cell item scrolls to it and focuses its textarea for immediate editing.
+
+3. **The header has** `run all` / `share` / `publish` buttons.
+   - **`run all`** sequentially executes every non-markdown cell from top to bottom.
+   - **`publish`** is the primary (accent-coloured) CTA — it flips the notebook to `mode: 'view'`, tags it `published` (from `draft`), and emits a Hyperskill share link automatically.
+   - The **title** is editable inline in the header and persists across reloads via localStorage.
+
+## Notes
+
+- Cells are added via buttons in the sidebar (not in the header).
+- Run controls (green/red pill) sit at the left of each cell's header, right after the drag handle.
+- Each cell head can be renamed inline in the sidebar (click the "N · name" item).
+- The sidebar under "sources" shows a placeholder when no MCP source is connected. Each source row is clickable: a `connect via mcp…` entry opens the servers modal so the user can hook one up without leaving the notebook.
+- **SQL cells** dispatch to the connected MCP server's `*_query_sql` tool (auto-detected).
+- **JS cells** execute in an isolated Web Worker with upstream named outputs injected as scope.
+
+## Left pane — resources from connected servers
+
+A collapsible **left pane** (bookmark-bar styling, collapsed by default) lists recipes and tools exposed by connected MCP data servers. Clicking any recipe opens a viewer modal; each fenced code block inside exposes a `↳ inject` button that drops the snippet into the notebook as a new cell.
+
+Two toolbar buttons flank this pane:
+
+- **`+ md`** — 3-tab modal (New / File / URL) to create a markdown cell from scratch, from a local `.md` file, or from a URL.
+- **`+ recipe`** — 3-tab modal (Browser / File / URL) to import a recipe from a connected server, a local `.recipe.md` file, or a URL.
+
+## Share & publish
+
+The `share` button offers **four formats**:
+
+- **Hyperskill link** — copies both the canonical Hyperskill URL and a short domain-scoped URL (`?n=<token>`). The published view is served read-only at `nb.hyperskills.net`.
+- **Markdown** — downloads a `.md` file with the notebook content.
+- **PNG** — snapshots the rendered notebook.
+- **JSON** — exports full widget state.
+
+`publish` wraps these: it sets `mode: 'view'`, tags the notebook `published`, and copies the Hyperskill link in one gesture — the canonical way to hand off a finished analysis.
+
+## Integration with connected data servers
+
+If a MCP **data** server is currently connected (the user has linked one, e.g. `tricoteuses`, `metmuseum`), BEFORE seeding cells the agent MUST:
+
+1. Call `{server}_list_recipes()` or `{server}_search_recipes(query)` to discover data recipes relevant to the user's intent.
+2. Call `{server}_list_tools()` to see available tables and endpoints.
+3. For each high-signal recipe or table, seed ONE named cell that demonstrates it — typical shapes:
+   - an SQL `SELECT ... LIMIT 10` with a meaningful cell name (e.g. `fetch_amendments`)
+   - a `run_script` invocation for recipes requiring code
+   - a short markdown cell describing the recipe and its parameters
+4. Pass the server metadata via the `servers:` param so the sidebar "sources" section, the left pane, and the server menu modal render correctly:
+
+   ```ts
+   widget_display({
+     name: 'notebook-workspace',
+     params: {
+       title: '...',
+       cells: [...],
+       servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+     }
+   })
+   ```
+
+If NO data server is connected, seed generic markdown-only cells that describe the intended analysis and invite the user to connect an MCP server — this matches the "no source connected" sidebar placeholder.
+
+**Filter rule**: only MCP *data* servers (`kind: 'data'`) belong in `servers:`. Do NOT include WebMCP UI servers such as `autoui` — they expose no queryable data and would clutter the sources sidebar.

package/src/widgets/notebook/resource-extractor.ts

@@ -0,0 +1,162 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// Extract notebook cells from imported resources (recipe body, tool def, md).
+// Consumed by import-modals.ts and left-pane.ts.
+// ---------------------------------------------------------------------------
+
+import { parseBody } from '@webmcp-auto-ui/sdk';
+import { uid, defaultCellContent } from './shared.js';
+import type { NotebookCell, CellType } from './shared.js';
+
+// Languages we map directly to a code cell type
+const LANG_TO_TYPE: Record<string, CellType> = {
+  sql: 'sql',
+  psql: 'sql',
+  mysql: 'sql',
+  sqlite: 'sql',
+  js: 'js',
+  javascript: 'js',
+  ts: 'js',       // treat TS as js source (stripped at runtime is user's concern)
+  typescript: 'js',
+  node: 'js',
+};
+
+/** Languages that map to 'js' but use a syntax superset that will fail at
+ *  runtime (interfaces, type annotations, `as` casts, etc.). We log a warning
+ *  whenever such a fence is mapped so the user gets a hint. */
+const TS_LIKE_LANGS = new Set(['ts', 'typescript']);
+
+export function fenceLangToCellType(lang: string): CellType | null {
+  const key = (lang || '').toLowerCase().trim();
+  if (TS_LIKE_LANGS.has(key)) {
+    try {
+      console.warn(
+        `[notebook] Fence language "${key}" mapped to JS — TS-specific syntax (interfaces, type annotations, "as" casts) will fail at runtime.`
+      );
+    } catch { /* ignore */ }
+  }
+  return LANG_TO_TYPE[key] ?? null;
+}
+
+/**
+ * Build a notebook cell from a single fence (lang + content).
+ * Unsupported languages fall back to a markdown cell wrapping the fence.
+ */
+export function extractCellFromFence(lang: string, content: string): NotebookCell {
+  const cellType = fenceLangToCellType(lang);
+  if (cellType) {
+    return { id: uid(), type: cellType, content: content.trim(), hideSource: false, hideResult: false };
+  }
+  // Detect pseudo-code MCP tool calls like: query_sql({sql: "..."})
+  // Only attempted when the fence language is unknown/text (cellType === null).
+  const trimmed = content.trim();
+  const callMatch = trimmed.match(/^([A-Za-z_][\w]*)\s*\(\s*(\{[\s\S]*\})\s*\)\s*;?\s*$/);
+  if (callMatch) {
+    const name = callMatch[1];
+    const argsRaw = callMatch[2];
+    if (name === 'query_sql') {
+      const sql = extractSqlFromLooseObject(argsRaw);
+      if (sql != null) {
+        return { id: uid(), type: 'sql', content: sql.trim(), hideSource: false, hideResult: false };
+      }
+    }
+    return {
+      id: uid(),
+      type: 'js',
+      content: `// MCP tool call: ${name}\nawait callTool('${name}', ${argsRaw});`,
+      hideSource: false,
+      hideResult: false,
+    };
+  }
+  // Preserve the original fence in markdown so users see it verbatim
+  return {
+    id: uid(),
+    type: 'md',
+    content: '```' + (lang || '') + '\n' + content.trim() + '\n```',
+    hideSource: false,
+    hideResult: false,
+  };
+}
+
+/**
+ * Best-effort extraction of the `sql` property value from a loose JS-object literal
+ * (unquoted keys, possibly single-quoted strings). Returns null if no sql key found.
+ */
+function extractSqlFromLooseObject(argsRaw: string): string | null {
+  // Essai 1: JSON.parse direct (cheap, rarely works for loose objects)
+  try {
+    const parsed = JSON.parse(argsRaw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.sql === 'string') {
+      return parsed.sql;
+    }
+  } catch {
+    /* fallthrough */
+  }
+  // Essai 2: regex extract sql: "..." (double-quoted)
+  const dq = argsRaw.match(/sql\s*:\s*"([\s\S]*?)"/);
+  if (dq) return dq[1];
+  // Essai 3: regex extract sql: '...' (single-quoted)
+  const sq = argsRaw.match(/sql\s*:\s*'([\s\S]*?)'/);
+  if (sq) return sq[1];
+  return null;
+}
+
+/**
+ * Extract cells from a full recipe body (markdown with frontmatter already stripped).
+ * Returns: a single intro markdown cell (first prose block) + one cell per fenced block.
+ */
+export function extractCellsFromRecipe(body: string, opts?: { title?: string; description?: string }): NotebookCell[] {
+  const cells: NotebookCell[] = [];
+  if (opts?.title || opts?.description) {
+    const md = ['# ' + (opts?.title ?? 'Imported recipe'), opts?.description ?? ''].filter(Boolean).join('\n\n');
+    cells.push({ id: uid(), type: 'md', content: md, hideSource: false, hideResult: false });
+  }
+  const segments = parseBody(body || '');
+  for (const seg of segments) {
+    if (seg.type === 'markdown') {
+      cells.push({ id: uid(), type: 'md', content: seg.content.trim(), hideSource: false, hideResult: false });
+    } else {
+      cells.push(extractCellFromFence(seg.lang || 'text', seg.content));
+    }
+  }
+  return cells;
+}
+
+/**
+ * Produce 2 cells for a tool: md (name + description + schema) + a starter call cell.
+ */
+export interface McpToolLike {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+  schema?: unknown;
+  serverName?: string;
+}
+
+export function extractCellsFromTool(tool: McpToolLike): NotebookCell[] {
+  const schema = tool.inputSchema ?? tool.schema ?? {};
+  const schemaStr = JSON.stringify(schema, null, 2);
+  const mdParts: string[] = [
+    `## ${tool.name}${tool.serverName ? ` · \`${tool.serverName}\`` : ''}`,
+  ];
+  if (tool.description) mdParts.push(tool.description);
+  mdParts.push('```json\n' + schemaStr + '\n```');
+
+  const isSql = /(_|^)query_sql$|(^|_)sql_query$/i.test(tool.name);
+  const cellType: CellType = isSql ? 'sql' : 'js';
+  const template = isSql
+    ? '-- call via MCP bridge: ' + tool.name + '\n' + defaultCellContent('sql')
+    : '// call via MCP bridge\nawait callTool(' + JSON.stringify(tool.name) + ', {});';
+
+  return [
+    { id: uid(), type: 'md', content: mdParts.join('\n\n'), hideSource: false, hideResult: false },
+    { id: uid(), type: cellType, content: template, hideSource: false, hideResult: false },
+  ];
+}
+
+/**
+ * Wrap raw markdown content as a single md cell.
+ */
+export function extractCellFromMarkdown(md: string): NotebookCell {
+  return { id: uid(), type: 'md', content: (md || '').trim(), hideSource: false, hideResult: false };
+}

package/src/widgets/notebook/share-handlers.ts

@@ -0,0 +1,222 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// Share handlers — real implementations for notebook share modal.
+// 4 formats: JSON, Markdown, Hyperskill link (+ short), PNG snapshot.
+// ---------------------------------------------------------------------------
+
+import { encode, buildShortUrl } from '@webmcp-auto-ui/sdk';
+import type { NotebookState, NotebookCell } from './shared.js';
+
+// ---------------------------------------------------------------------------
+// JSON export
+// ---------------------------------------------------------------------------
+
+export async function shareAsJson(state: NotebookState): Promise<void> {
+  const minimal = minify(state);
+  const blob = new Blob([JSON.stringify(minimal, null, 2)], { type: 'application/json' });
+  triggerDownload(blob, sanitizeFilename(state.title || 'notebook') + '.json');
+}
+
+// ---------------------------------------------------------------------------
+// Markdown export
+// ---------------------------------------------------------------------------
+
+export async function shareAsMarkdown(state: NotebookState): Promise<void> {
+  const md = serializeToMarkdown(state);
+  const blob = new Blob([md], { type: 'text/markdown' });
+  triggerDownload(blob, sanitizeFilename(state.title || 'notebook') + '.md');
+}
+
+function serializeToMarkdown(state: NotebookState): string {
+  const parts: string[] = [];
+  if (state.title) parts.push(`# ${state.title}`, '');
+  for (const cell of state.cells) {
+    if (cell.type === 'md') {
+      parts.push(stripHtml(cell.content).trim(), '');
+    } else {
+      const lang = cell.type === 'sql' ? 'sql' : 'js';
+      const varname = cell.varname ? ` // → ${cell.varname}` : '';
+      parts.push('```' + lang + varname, cell.content.trim(), '```', '');
+    }
+  }
+  return parts.join('\n').trim() + '\n';
+}
+
+function stripHtml(s: string): string {
+  if (typeof document === 'undefined') return s;
+  const d = document.createElement('div');
+  d.innerHTML = s;
+  return d.textContent || '';
+}
+
+// ---------------------------------------------------------------------------
+// Hyperskill link (+ short URL)
+// ---------------------------------------------------------------------------
+
+export interface HyperskillShareResult {
+  fullUrl: string;
+  shortUrl: string;
+}
+
+export async function shareAsHyperskill(state: NotebookState): Promise<HyperskillShareResult> {
+  const origin = typeof window !== 'undefined' ? window.location.href.split('?')[0] : 'https://example.com';
+  const payload = JSON.stringify(minify(state));
+  const fullUrl = await encode(origin, payload);
+  const shortUrl = await buildShortUrl(origin, payload);
+  try {
+    await navigator.clipboard?.writeText(fullUrl);
+  } catch {
+    /* clipboard API can fail silently (focus, permission) */
+  }
+  return { fullUrl, shortUrl };
+}
+
+// ---------------------------------------------------------------------------
+// PNG snapshot — uses __exportPng widget hook (commit ded48c9) if present,
+// falls back to a library-free DOM → SVG → PNG pipeline.
+// ---------------------------------------------------------------------------
+
+export async function shareAsPng(state: NotebookState, container: HTMLElement): Promise<void> {
+  // Preferred: widget-level hook
+  const hook = (container as any).__exportPng as (() => Promise<Blob>) | undefined;
+  if (typeof hook === 'function') {
+    try {
+      const blob = await hook();
+      triggerDownload(blob, sanitizeFilename(state.title || 'notebook') + '.png');
+      return;
+    } catch {
+      /* fall through to fallback */
+    }
+  }
+  // Fallback: SVG foreignObject → canvas → PNG
+  const blob = await domToPngBlob(container);
+  triggerDownload(blob, sanitizeFilename(state.title || 'notebook') + '.png');
+}
+
+async function domToPngBlob(el: HTMLElement): Promise<Blob> {
+  const rect = el.getBoundingClientRect();
+  const w = Math.max(1, Math.ceil(rect.width));
+  const h = Math.max(1, Math.ceil(rect.height));
+  const serialized = new XMLSerializer().serializeToString(el);
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">
+    <foreignObject width="100%" height="100%">
+      <div xmlns="http://www.w3.org/1999/xhtml">${serialized}</div>
+    </foreignObject>
+  </svg>`;
+  const svgBlob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+  const url = URL.createObjectURL(svgBlob);
+  const img = new Image();
+  await new Promise<void>((resolve, reject) => {
+    img.onload = () => resolve();
+    img.onerror = (e) => reject(e);
+    img.src = url;
+  });
+  const canvas = document.createElement('canvas');
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext('2d')!;
+  ctx.fillStyle = 'white';
+  ctx.fillRect(0, 0, w, h);
+  ctx.drawImage(img, 0, 0);
+  URL.revokeObjectURL(url);
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('toBlob failed'))), 'image/png');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher used by shared.ts::openShareModal callback
+// ---------------------------------------------------------------------------
+
+export type ShareKind = 'hyperskill' | 'json' | 'markdown' | 'png';
+
+export interface ShareResultInfo {
+  fmt: string;
+  kind: ShareKind | string;
+  message: string;
+  url?: string;
+  shortUrl?: string;
+  fullUrl?: string;
+}
+
+export interface ShareDispatchOptions {
+  container?: HTMLElement;
+  onResult?: (info: ShareResultInfo) => void;
+}
+
+export async function dispatchShare(
+  fmt: string,
+  state: NotebookState,
+  opts: ShareDispatchOptions = {},
+): Promise<void> {
+  try {
+    if (fmt === 'json') {
+      await shareAsJson(state);
+      opts.onResult?.({ fmt, kind: 'json', message: 'JSON downloaded' });
+    } else if (fmt === 'md' || fmt === 'markdown') {
+      await shareAsMarkdown(state);
+      opts.onResult?.({ fmt, kind: 'markdown', message: 'Markdown downloaded' });
+    } else if (fmt === 'hyperskill' || fmt === 'hs') {
+      const { fullUrl, shortUrl } = await shareAsHyperskill(state);
+      opts.onResult?.({
+        fmt,
+        kind: 'hyperskill',
+        message: 'URL copied',
+        url: shortUrl || fullUrl,
+        shortUrl,
+        fullUrl,
+      });
+    } else if (fmt === 'png') {
+      if (!opts.container) throw new Error('png export requires container');
+      await shareAsPng(state, opts.container);
+      opts.onResult?.({ fmt, kind: 'png', message: 'PNG downloaded' });
+    } else {
+      throw new Error(`Unknown share format: ${fmt}`);
+    }
+  } catch (err: any) {
+    opts.onResult?.({ fmt, kind: fmt, message: 'Error: ' + String(err?.message ?? err) });
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip non-serializable / transient fields from state for share/encode.
+ */
+function minify(state: NotebookState): Record<string, unknown> {
+  return {
+    id: state.id,
+    title: state.title,
+    mode: state.mode,
+    kicker: state.kicker,
+    cells: state.cells.map((c: NotebookCell) => ({
+      id: c.id,
+      type: c.type,
+      content: c.content,
+      name: c.name,
+      varname: c.varname,
+      hideSource: c.hideSource,
+      hideResult: c.hideResult,
+      comment: c.comment ?? undefined,
+      // intentionally skip lastResult, runState, lastMs — transient
+    })),
+  };
+}
+
+function triggerDownload(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+function sanitizeFilename(name: string): string {
+  return name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9._-]/g, '') || 'notebook';
+}