@webmcp-auto-ui/ui 2.5.27 → 2.5.28

package/src/widgets/notebook/recipe-browser.ts

@@ -0,0 +1,350 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// recipe-browser — vanilla widget renderer
+// Interactive browser: search, filter by kind/tags, layout toggle, preview, pick/download.
+// ---------------------------------------------------------------------------
+
+// NOTE: this widget lives in @webmcp-auto-ui/ui but imports runtime helpers from
+// @webmcp-auto-ui/agent, creating an ESM cycle ui <-> agent. The cycle is safe
+// because these imports are only used inside functions (no top-level eval).
+import { filterRecipes, sortRecipes, recipeToDownloadBlob, recipeToMarkdown } from '@webmcp-auto-ui/agent';
+import type { Recipe } from '@webmcp-auto-ui/agent';
+
+export interface RecipeBrowserData {
+  recipes: Recipe[];
+  filters?: { tags?: string[]; kind?: 'webmcp' | 'mcp' | 'all'; q?: string };
+  layout?: 'list' | 'grid';
+  onPick?: (recipe: Recipe) => void;
+}
+
+const STYLE_ID = 'rb-recipe-browser-styles';
+
+function injectStyles(): void {
+  if (document.getElementById(STYLE_ID)) return;
+  const s = document.createElement('style');
+  s.id = STYLE_ID;
+  s.textContent = `
+    .recipe-browser-root {
+      display: flex; flex-direction: column; gap: 10px;
+      font-family: var(--font-sans, system-ui, sans-serif);
+      color: var(--color-text1, #111);
+      background: var(--color-surface, #fff);
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 10px;
+      padding: 14px;
+      min-height: 360px;
+      box-sizing: border-box;
+    }
+    .recipe-browser-root * { box-sizing: border-box; }
+    .rb-head {
+      display: flex; flex-wrap: wrap; gap: 8px; align-items: center;
+      padding-bottom: 10px;
+      border-bottom: 1px solid var(--color-border, #e4e4e7);
+    }
+    .rb-search {
+      flex: 1 1 200px; min-width: 160px;
+      padding: 7px 10px; font-size: 13px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px;
+      background: var(--color-surface, #fff);
+      color: var(--color-text1, #111);
+      outline: none;
+    }
+    .rb-search:focus { border-color: var(--color-accent, #6a55ff); }
+    .rb-select {
+      padding: 7px 10px; font-size: 12px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px;
+      background: var(--color-surface, #fff);
+      color: var(--color-text1, #111);
+    }
+    .rb-layout-toggle { display: inline-flex; border: 1px solid var(--color-border, #e4e4e7); border-radius: 6px; overflow: hidden; }
+    .rb-layout-btn {
+      background: var(--color-surface, #fff); color: var(--color-text2, #666);
+      border: 0; padding: 7px 10px; font-size: 12px; cursor: pointer;
+    }
+    .rb-layout-btn.rb-on { background: var(--color-accent, #6a55ff); color: #fff; }
+    .rb-body {
+      display: grid; grid-template-columns: minmax(220px, 320px) 1fr;
+      gap: 12px; min-height: 280px;
+    }
+    .rb-body[data-layout="grid"] { grid-template-columns: 1fr; }
+    .rb-body[data-layout="grid"] .rb-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 8px; max-height: none; }
+    .rb-list {
+      display: flex; flex-direction: column; gap: 6px;
+      max-height: 420px; overflow-y: auto;
+      padding-right: 4px;
+    }
+    .rb-item {
+      padding: 9px 11px; border-radius: 8px;
+      background: var(--color-surface2, #f4f4f5);
+      border: 1px solid transparent;
+      cursor: pointer; transition: background .12s, border-color .12s;
+    }
+    .rb-item:hover { background: var(--color-surface3, #eeeef0); }
+    .rb-item.rb-selected { border-color: var(--color-accent, #6a55ff); background: var(--color-surface3, #eeeef0); }
+    .rb-item-name { font-weight: 600; font-size: 13px; margin-bottom: 3px; }
+    .rb-item-desc { font-size: 11.5px; color: var(--color-text2, #666); margin-bottom: 6px; line-height: 1.35; }
+    .rb-item-foot { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }
+    .rb-chip {
+      font-size: 10.5px; font-family: var(--font-mono, monospace);
+      padding: 1px 6px; border-radius: 999px;
+      background: var(--color-surface, #fff);
+      border: 1px solid var(--color-border, #e4e4e7);
+      color: var(--color-text2, #666);
+    }
+    .rb-chip.rb-srv { background: var(--color-accent, #6a55ff); color: #fff; border-color: transparent; }
+    .rb-preview {
+      display: flex; flex-direction: column; min-height: 260px;
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 8px; overflow: hidden;
+      background: var(--color-surface, #fff);
+    }
+    .rb-preview-head {
+      display: flex; align-items: center; gap: 8px;
+      padding: 9px 12px;
+      border-bottom: 1px solid var(--color-border, #e4e4e7);
+      background: var(--color-surface2, #f4f4f5);
+    }
+    .rb-preview-title { flex: 1; font-weight: 600; font-size: 13px; }
+    .rb-preview-body {
+      flex: 1; padding: 12px; overflow-y: auto;
+      font-size: 12.5px; line-height: 1.5;
+      max-height: 420px;
+    }
+    .rb-preview-body pre {
+      background: var(--color-surface2, #f4f4f5);
+      padding: 10px; border-radius: 6px;
+      overflow-x: auto;
+      font-family: var(--font-mono, monospace);
+      font-size: 11.5px;
+      white-space: pre-wrap;
+      margin: 0;
+    }
+    .rb-btn {
+      background: var(--color-surface2, #f4f4f5);
+      border: 1px solid var(--color-border, #e4e4e7);
+      border-radius: 6px; padding: 6px 12px; font-size: 12px;
+      color: var(--color-text1, #111);
+      cursor: pointer;
+    }
+    .rb-btn:hover { background: var(--color-surface3, #eeeef0); }
+    .rb-btn-primary { background: var(--color-accent, #6a55ff); color: #fff; border-color: transparent; }
+    .rb-btn-primary:hover { filter: brightness(1.08); }
+    .rb-empty { padding: 24px; text-align: center; color: var(--color-text2, #666); font-size: 12px; }
+    .rb-placeholder { color: var(--color-text2, #666); font-size: 12px; padding: 24px; text-align: center; }
+  `;
+  document.head.appendChild(s);
+}
+
+function escapeHtml(s: unknown): string {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function detectKind(r: Recipe): 'webmcp' | 'mcp' {
+  // Heuristic: if frontmatter 'servers' present and non-empty, treat as MCP-connected.
+  const srv = (r as any).server ?? (r as any).serverName;
+  if (typeof srv === 'string' && srv && srv !== 'webmcp') return 'mcp';
+  return 'webmcp';
+}
+
+function recipeTags(r: Recipe): string[] {
+  const out: string[] = [];
+  if (Array.isArray(r.servers)) out.push(...r.servers);
+  if (Array.isArray(r.components_used)) out.push(...r.components_used.slice(0, 3));
+  return out;
+}
+
+function serverLabel(r: Recipe): string {
+  const srv = (r as any).server ?? (r as any).serverName;
+  if (typeof srv === 'string' && srv) return srv;
+  if (Array.isArray(r.servers) && r.servers.length) return r.servers[0];
+  return 'webmcp';
+}
+
+function simpleMarkdown(body: string): string {
+  // Minimal safe rendering: escape + preserve paragraphs + wrap fences in <pre>.
+  const escaped = escapeHtml(body);
+  // Code fences
+  const withFences = escaped.replace(/```([a-zA-Z0-9_-]*)\n([\s\S]*?)```/g, (_m, _lang, code) => {
+    return `<pre><code>${code}</code></pre>`;
+  });
+  // Paragraphs (double newlines)
+  const paras = withFences.split(/\n{2,}/).map((p) => {
+    if (p.startsWith('<pre>')) return p;
+    return `<p>${p.replace(/\n/g, '<br/>')}</p>`;
+  });
+  return paras.join('\n');
+}
+
+export function render(container: HTMLElement, data: RecipeBrowserData): () => void {
+  injectStyles();
+
+  const all: Recipe[] = Array.isArray(data?.recipes) ? data.recipes : [];
+  if (!all.length) {
+    container.innerHTML = '<div class="recipe-browser-root"><div class="rb-empty">No recipes available.</div></div>';
+    return () => { container.innerHTML = ''; };
+  }
+
+  const initialFilters = data?.filters ?? {};
+  let q = initialFilters.q ?? '';
+  let kind: 'all' | 'webmcp' | 'mcp' = initialFilters.kind ?? 'all';
+  let layout: 'list' | 'grid' = data?.layout === 'grid' ? 'grid' : 'list';
+  let selectedId: string | null = null;
+
+  const root = document.createElement('div');
+  root.className = 'recipe-browser-root';
+  root.innerHTML = `
+    <div class="rb-head">
+      <input type="search" class="rb-search" placeholder="Search recipes..." value="${escapeHtml(q)}" />
+      <select class="rb-select" data-role="kind">
+        <option value="all"${kind === 'all' ? ' selected' : ''}>All kinds</option>
+        <option value="webmcp"${kind === 'webmcp' ? ' selected' : ''}>WebMCP</option>
+        <option value="mcp"${kind === 'mcp' ? ' selected' : ''}>MCP</option>
+      </select>
+      <div class="rb-layout-toggle">
+        <button type="button" class="rb-layout-btn${layout === 'list' ? ' rb-on' : ''}" data-layout="list">list</button>
+        <button type="button" class="rb-layout-btn${layout === 'grid' ? ' rb-on' : ''}" data-layout="grid">grid</button>
+      </div>
+    </div>
+    <div class="rb-body" data-layout="${layout}">
+      <div class="rb-list" data-role="list"></div>
+      <div class="rb-preview" data-role="preview">
+        <div class="rb-placeholder">Select a recipe to preview.</div>
+      </div>
+    </div>
+  `;
+  container.innerHTML = '';
+  container.appendChild(root);
+
+  const searchEl = root.querySelector('.rb-search') as HTMLInputElement;
+  const kindEl = root.querySelector('[data-role="kind"]') as HTMLSelectElement;
+  const bodyEl = root.querySelector('.rb-body') as HTMLElement;
+  const listEl = root.querySelector('[data-role="list"]') as HTMLElement;
+  const previewEl = root.querySelector('[data-role="preview"]') as HTMLElement;
+  const layoutBtns = Array.from(root.querySelectorAll('.rb-layout-btn')) as HTMLButtonElement[];
+
+  const listeners: Array<{ el: EventTarget; type: string; fn: EventListener }> = [];
+  function on<T extends EventTarget>(el: T, type: string, fn: EventListener) {
+    el.addEventListener(type, fn);
+    listeners.push({ el, type, fn });
+  }
+
+  function applyFilters(): Recipe[] {
+    let filtered = all.slice();
+    if (kind !== 'all') filtered = filtered.filter((r) => detectKind(r) === kind);
+    // Tag filter (optional): keep only recipes whose tags intersect data.filters.tags
+    const wantTags = initialFilters.tags;
+    if (Array.isArray(wantTags) && wantTags.length) {
+      const wanted = new Set(wantTags.map((t) => String(t).toLowerCase()));
+      filtered = filtered.filter((r) => recipeTags(r).some((t) => wanted.has(String(t).toLowerCase())));
+    }
+    filtered = filterRecipes(filtered, q);
+    return sortRecipes(filtered);
+  }
+
+  function renderList() {
+    const items = applyFilters();
+    listEl.innerHTML = '';
+    if (!items.length) {
+      const empty = document.createElement('div');
+      empty.className = 'rb-empty';
+      empty.textContent = 'No matches.';
+      listEl.appendChild(empty);
+      return;
+    }
+    for (const r of items) {
+      const id = r.id ?? r.name ?? '';
+      const node = document.createElement('div');
+      node.className = 'rb-item' + (id === selectedId ? ' rb-selected' : '');
+      const tags = recipeTags(r).slice(0, 4);
+      node.innerHTML = `
+        <div class="rb-item-name">${escapeHtml(r.name || 'Untitled')}</div>
+        <div class="rb-item-desc">${escapeHtml(r.description || 'No description')}</div>
+        <div class="rb-item-foot">
+          <span class="rb-chip rb-srv">${escapeHtml(serverLabel(r))}</span>
+          ${tags.map((t) => `<span class="rb-chip">${escapeHtml(t)}</span>`).join('')}
+        </div>
+      `;
+      on(node, 'click', () => {
+        selectedId = id;
+        renderList();
+        renderPreview(r);
+      });
+      listEl.appendChild(node);
+    }
+  }
+
+  function renderPreview(r: Recipe) {
+    const md = typeof r.body === 'string' && r.body.trim()
+      ? r.body
+      : (() => { try { return recipeToMarkdown(r as any); } catch { return ''; } })();
+    previewEl.innerHTML = `
+      <div class="rb-preview-head">
+        <span class="rb-preview-title">${escapeHtml(r.name || 'Untitled')}</span>
+        <button type="button" class="rb-btn" data-act="download">Download .md</button>
+        <button type="button" class="rb-btn rb-btn-primary" data-act="pick">Pick</button>
+      </div>
+      <div class="rb-preview-body">${md ? simpleMarkdown(md) : '<div class="rb-placeholder">No body.</div>'}</div>
+    `;
+
+    const pickBtn = previewEl.querySelector('[data-act="pick"]') as HTMLButtonElement | null;
+    const dlBtn = previewEl.querySelector('[data-act="download"]') as HTMLButtonElement | null;
+
+    if (pickBtn) {
+      on(pickBtn, 'click', () => {
+        if (typeof data.onPick === 'function') {
+          data.onPick(r);
+        } else {
+          container.dispatchEvent(new CustomEvent('widget:interact', {
+            bubbles: true,
+            detail: { action: 'pick', payload: r },
+          }));
+        }
+      });
+    }
+    if (dlBtn) {
+      on(dlBtn, 'click', () => {
+        try {
+          const { blob, filename } = recipeToDownloadBlob(r as any);
+          triggerDownload(blob, filename);
+        } catch {
+          // fallback
+          const body = typeof r.body === 'string' ? r.body : '';
+          const blob = new Blob([body], { type: 'text/markdown' });
+          const filename = (r.name || r.id || 'recipe').replace(/[^a-z0-9_.-]/gi, '-').toLowerCase() + '.md';
+          triggerDownload(blob, filename);
+        }
+      });
+    }
+  }
+
+  function triggerDownload(blob: Blob, filename: string) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 500);
+  }
+
+  on(searchEl, 'input', () => { q = searchEl.value; renderList(); });
+  on(kindEl, 'change', () => { kind = (kindEl.value as any); renderList(); });
+  for (const btn of layoutBtns) {
+    on(btn, 'click', () => {
+      layout = (btn.dataset.layout as 'list' | 'grid') || 'list';
+      bodyEl.setAttribute('data-layout', layout);
+      layoutBtns.forEach((b) => b.classList.toggle('rb-on', b === btn));
+    });
+  }
+
+  renderList();
+
+  return () => {
+    for (const { el, type, fn } of listeners) el.removeEventListener(type, fn);
+    listeners.length = 0;
+    container.innerHTML = '';
+  };
+}

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

@@ -0,0 +1,124 @@
+---
+widget: notebook-compact
+description: Reactive minimalist notebook with a left gutter showing cell types and named outputs. Cells chain via variable names (→ rows, → df) and display fresh/stale status. Minimal chrome, ideal for quick data exploration.
+schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Unique notebook identifier (for save/share via hyperskill)
+    title:
+      type: string
+      description: Notebook title
+    mode:
+      type: string
+      enum: [edit, view]
+      description: edit allows run/edit/reorder; view hides all controls for read-only display
+    cells:
+      type: array
+      description: Ordered list of cells (markdown, sql, js)
+      items:
+        type: object
+        required: [type, content]
+        properties:
+          type:
+            type: string
+            enum: [md, sql, js]
+          content:
+            type: string
+            description: Cell source (markdown text or code)
+          name:
+            type: string
+            description: Optional cell name
+          varname:
+            type: string
+            description: Named output variable (code cells only), displayed as → varname
+          hideSource:
+            type: boolean
+          hideResult:
+            type: boolean
+---
+
+## When to use
+
+Use `notebook-compact` when the user wants to explore data quickly with a minimal, reactive interface. Ideal for:
+- Iterative SQL / JS exploration where output variables feed each other
+- Quick prototyping where chrome should fade into the background
+- Hackathon playgrounds where users expect a familiar "type, see, share" flow
+- Situations where the reactive dataflow (fresh/stale status) helps the user reason about stale results
+
+Prefer over `notebook-workspace` when there is no multi-source concern and no publish/dashboard end goal.
+Prefer over `notebook-document` when collaboration and comments are not central.
+Prefer over `notebook-editorial` when the result is a working session, not a publication.
+
+## How to use
+
+1. **Create the widget** with a title and 2–4 seed cells:
+   ```
+   widget_display({name: "notebook-compact", params: {
+     title: "Exploration",
+     cells: [
+       {type: "md", content: "### Quick look\n\nLet's inspect the data."},
+       {type: "sql", content: "select * from source limit 10", varname: "rows"},
+       {type: "js", content: "console.table(rows)"}
+     ]
+   }})
+   ```
+
+2. **Name outputs** (`varname`) on the SQL/JS cells so the gutter displays `→ varname` and downstream cells can reference them. Named outputs are injected into the scope of every JS cell executed after them; if a downstream cell's code mentions `varname` (word-boundary match), it is flagged **stale** whenever the upstream cell re-runs, so the user sees what needs replaying.
+
+3. **Start markdown cells with a heading** (`### Title`) — the first line renders larger and gives the cell an anchor.
+
+4. **Let the user iterate** — they can add cells with `+ md / + sql / + js`, reorder via the drag handle, toggle source/result, and run cells with the green pill button.
+
+## Notes
+
+- The Run button lives at the left of each cell's title row, right after the type label.
+- Stop (red pill) appears while running, with a live elapsed timer.
+- After a run, Run becomes the replay button (same green pill, re-click to re-run).
+- **SQL cells** are dispatched to the first matching `*_query_sql` tool on the connected MCP data server (auto-detected).
+- **JS cells** execute on the main thread via `new Function(...)` with upstream named outputs injected as scope — `console.log` / `console.table` results are captured and rendered inline. Note: there is no worker isolation yet, so a `while (true)` loop or other synchronous blocker will freeze the UI thread.
+- Deletions prompt a confirmation modal and are recorded in the history panel; they can be restored from there.
+- `mode: "view"` hides all controls (run, delete, drag, add), making the notebook read-only.
+
+## Left pane — connected data servers
+
+When one or more MCP data servers are connected, a collapsible **left pane** (bookmark-bar styling, collapsed by default) lists their recipes and tools. Clicking any recipe opens it in a viewer modal; each fenced code block inside the recipe has 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, a local `.md` file, or a remote 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>`). Opens at `nb.hyperskills.net` (read-only public viewer) when mode is `view`.
+- **Markdown** — downloads a `.md` file with the notebook content.
+- **PNG** — snapshots the rendered notebook to an image.
+- **JSON** — exports the full widget state for programmatic reuse.
+
+## Integration with connected data servers
+
+If a MCP **data** server is connected (e.g. `tricoteuses`, `metmuseum`), BEFORE seeding cells:
+
+1. Call `{server}_list_recipes()` or `{server}_search_recipes(query)` to find recipes that match the user's intent.
+2. Call `{server}_list_tools()` to see available tables/endpoints.
+3. For each high-signal recipe or table, seed ONE cell that demonstrates it: an SQL `SELECT ... LIMIT 10`, a `run_script` call, or a short markdown note.
+4. Pass the server metadata via the `servers:` param so the UI can render the server menu modal and populate the left pane:
+
+   ```ts
+   widget_display({
+     name: 'notebook-compact',
+     params: {
+       title: '...',
+       cells: [...],
+       servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+     }
+   })
+   ```
+
+If NO data server is connected, seed generic markdown-only cells that explain the notebook's purpose and invite the user to connect an MCP server.
+
+**Filter rule**: only include MCP *data* servers (`kind: 'data'`) in `servers:`. Do NOT include WebMCP UI servers like `autoui` — they don't expose queryable data and would clutter the menu.

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

@@ -0,0 +1,139 @@
+---
+widget: notebook-document
+description: Collaborative notebook styled as a shared document. Optional editor avatars at the top (opt-in), inline highlights in prose, optional margin comments next to cells (editable + threaded replies). Minimal cell chrome, reads as a report with conversation around it.
+schema:
+  type: object
+  properties:
+    id:
+      type: string
+    title:
+      type: string
+    mode:
+      type: string
+      enum: [edit, view]
+    presence:
+      type: array
+      description: Optional list of editors to display as avatars at the top (opt-in). When absent or empty, no presence indicator is rendered.
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+          color:
+            type: string
+    cells:
+      type: array
+      items:
+        type: object
+        required: [type, content]
+        properties:
+          type:
+            type: string
+            enum: [md, sql, js]
+          content:
+            type: string
+            description: For md cells, markdown is rendered and sanitized (use <mark> for inline highlights).
+          hideSource:
+            type: boolean
+          hideResult:
+            type: boolean
+          comment:
+            type: object
+            description: Optional margin comment attached to a code cell. Editable after creation; supports replies.
+            properties:
+              who:
+                type: string
+              when:
+                type: string
+                description: ISO timestamp or relative label. Relative time is recomputed from lastEditAt at render.
+              body:
+                type: string
+              replies:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    who: {type: string}
+                    when: {type: string}
+                    body: {type: string}
+---
+
+## When to use
+
+Use `notebook-document` when the notebook is meant to be read and discussed by a team:
+- Shared analyses where colleagues leave margin comments on specific cells
+- Onboarding guides, knowledge docs, incident retros
+- Any context where the notebook should feel like a Google Doc / Notion page, not a developer tool
+
+Prose cells can contain `<mark>` highlights inline to draw attention to a sentence, and code cells can carry an optional margin comment object showing who commented and when — comments are editable after creation and support threaded replies via a `+ reply` button.
+
+## How to use
+
+1. **Create with prose-heavy seed content** and inline highlights for emphasis:
+   ```
+   widget_display({name: "notebook-document", params: {
+     title: "Weekly review",
+     cells: [
+       {type: "md", content: "Here is this week's summary. <mark>Pay attention to this metric.</mark> More context follows."},
+       {type: "sql", content: "select ...", comment: {who: "reviewer", when: "2m", body: "Can we filter X here?"}},
+       {type: "js", content: "// visualization"}
+     ]
+   }})
+   ```
+
+2. **Attach comments to code cells** by adding a `comment` object. The cell row splits into two columns (cell + comment) only when a comment exists. Comments can be edited inline after creation, and replies can be threaded under them via `+ reply`.
+
+3. **Keep prose short** — the layout punishes walls of text. Break them into several markdown cells with their own handles.
+
+## Notes
+
+- Every cell (prose or code) has its own drag handle for reordering.
+- Prose cells are rendered via an HTML-sanitizing markdown pipeline — `<mark>` is preserved, script/style and other dangerous tags are stripped (XSS closed).
+- `<mark>` inside markdown renders with an amber tint; use sparingly.
+- **Presence is opt-in**: the row of editor avatars and the "X editors online" label appear **only** when the `presence` param is explicitly provided with at least one entry. Without `presence`, nothing is rendered — no fake collaborators.
+- A timestamp under the title reads `edited Xs ago`, computed in real time from the notebook's last edit.
+- The footer shows a single `share` link that opens the share modal. (Live invite/collaboration is not available in this build.)
+- **SQL cells** dispatch to the connected MCP server's `*_query_sql` tool (auto-detected). **JS cells** run in an isolated Web Worker with upstream named outputs in scope.
+- Like the other notebook widgets, `mode: "view"` removes all editing and running controls.
+
+## 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 in as a new cell.
+
+Two toolbar buttons flank this pane:
+
+- **`+ md`** — 3-tab modal (New / File / URL) to create a markdown cell 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 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 document.
+- **JSON** — exports full widget state.
+
+## Integration with connected data servers
+
+When a MCP **data** server is connected (for instance `tricoteuses` or `metmuseum`), the document should open on real material rather than empty placeholders. Before seeding cells, the agent takes a short discovery pass:
+
+1. It calls `{server}_list_recipes()` or `{server}_search_recipes(query)` to locate recipes aligned with the user's topic.
+2. It calls `{server}_list_tools()` to learn which tables and endpoints the server exposes.
+3. For each relevant recipe or table, it seeds a single cell that grounds the document — a short SQL `SELECT ... LIMIT 10`, a `run_script` call, or a prose cell that introduces what the data shows. A margin `comment` on a code cell is a natural way to flag an open question for collaborators.
+4. It passes the server metadata through the `servers:` param so the share affordance and the left pane reflect what is in play:
+
+   ```ts
+   widget_display({
+     name: 'notebook-document',
+     params: {
+       title: '...',
+       cells: [...],
+       servers: [{ name: 'tricoteuses', url: 'https://...', kind: 'data' }]
+     }
+   })
+   ```
+
+When no data server is connected, seed a prose-only skeleton that frames the discussion and invites the reader (or a colleague) to link an MCP server.
+
+**Filter rule**: only MCP *data* servers (`kind: 'data'`) appear in `servers:`. WebMCP UI servers such as `autoui` are excluded — they carry no queryable data and would clutter the collaborative view.