@webmcp-auto-ui/sdk 2.5.38 → 2.5.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmcp-auto-ui/sdk",
-  "version": "2.5.38",
+  "version": "2.5.40",
   "description": "Skills CRUD, HyperSkill format, Svelte 5 stores",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/canvas-to-notebook.ts

@@ -4,6 +4,8 @@
  * present, snapshot fallback otherwise.
  */
 
+import { pickFence } from './recipes/fence.js';
+
 export interface WidgetLineage {
   widgetType: string;
   widgetParams: Record<string, unknown>;
@@ -138,13 +140,64 @@ export function canvasToNotebookMarkdown(
   return fm.join('\n') + '\n' + body.join('\n').replace(/\n+$/, '') + '\n';
 }
 
+export interface CanvasToNotebookData {
+  title?: string;
+  description?: string;
+  /** Active MCP servers (name, url) — to seed the notebook widget's data. */
+  servers?: Array<{ name: string; url: string }>;
+  /** Active bundled WebMCP server ids. */
+  webmcpServers?: string[];
+  /** Cells ready to feed into a NotebookState. */
+  cells: Array<{
+    id: string;
+    type: 'md' | 'sql' | 'js';
+    content: string;
+    varname?: string;
+    status?: 'idle';
+  }>;
+}
+
+/** Same logic as canvasToNotebookMarkdown but returns structured cells for direct widget mounting. */
+export function canvasToNotebookCells(
+  blocks: CanvasBlock[],
+  getLineage: (blockId: string) => WidgetLineage | null,
+  opts: CanvasToNotebookOptions = {},
+): CanvasToNotebookData {
+  let counter = 0;
+  const cells: CanvasToNotebookData['cells'] = [];
+
+  for (const block of blocks) {
+    const raw = lineageToCells(block, getLineage(block.id));
+    for (const cell of raw) {
+      const entry: CanvasToNotebookData['cells'][number] = {
+        id: `c${counter++}`,
+        type: cell.kind,
+        content: cell.content,
+        status: 'idle',
+      };
+      if (cell.varname !== undefined) entry.varname = cell.varname;
+      cells.push(entry);
+    }
+  }
+
+  const out: CanvasToNotebookData = { cells };
+  if (opts.title) out.title = opts.title;
+  if (opts.description) out.description = opts.description;
+  if (opts.servers && opts.servers.length > 0) out.servers = opts.servers;
+  if (opts.webmcpServers && opts.webmcpServers.length > 0) out.webmcpServers = opts.webmcpServers;
+  return out;
+}
+
 function renderCell(cell: NotebookCell): string {
   if (cell.kind === 'md') return cell.content;
   if (cell.kind === 'sql') {
     const meta = cell.varname ? `-- @meta {"varname": "${cell.varname}"}\n` : '';
-    return '```sql\n' + meta + cell.content + '\n```';
+    const body = meta + cell.content;
+    const fence = pickFence(body);
+    return fence + 'sql\n' + body + '\n' + fence;
   }
-  return '```js\n' + cell.content + '\n```';
+  const fence = pickFence(cell.content);
+  return fence + 'js\n' + cell.content + '\n' + fence;
 }
 
 function pickArrayParamKey(params: Record<string, unknown>): string | null {

package/src/index.ts

@@ -91,7 +91,7 @@ export type { RemoteMcpRegistryEntry } from './remote-mcp-registry.js';
 // import { canvas } from '@webmcp-auto-ui/sdk/canvas'
 
 // Recipe runner — markdown-fence parser + JS/TS/SQL/etc executor over MCP
-export { parseBody, runCode, estimateTokens, safeStringify, findCodeParamName, buildToolArgs, parseWidgetDisplayCall } from './recipes/index.js';
+export { parseBody, pickFence, runCode, estimateTokens, safeStringify, findCodeParamName, buildToolArgs, parseWidgetDisplayCall, extractTopLevelDecls, hasIdentifierReference } from './recipes/index.js';
 export type { ParsedSegment, RunResult, RunLog, RunTab, RecipeData } from './recipes/index.js';
 
 // Short URL — domain-dependent compact token
@@ -104,10 +104,11 @@ export { extractSampleData } from './widget-sample-data.js';
 export { unwrap } from './unwrap.js';
 
 // Canvas → HyperSkill notebook serializer
-export { lineageToCells, canvasToNotebookMarkdown } from './canvas-to-notebook.js';
+export { lineageToCells, canvasToNotebookMarkdown, canvasToNotebookCells } from './canvas-to-notebook.js';
 export type {
   WidgetLineage,
   CanvasToNotebookOptions,
+  CanvasToNotebookData,
   NotebookCell,
   CanvasBlock,
 } from './canvas-to-notebook.js';

package/src/recipes/fence.ts

@@ -0,0 +1,12 @@
+/**
+ * Pick a backtick fence longer than any run of backticks inside `content`.
+ * CommonMark rule: a fenced code block opens with N≥3 backticks; the content
+ * must not contain a closing fence of the same length, and the closing fence
+ * must be at least as long as the opening. Choosing N = max(3, longestRun+1)
+ * makes round-trips safe even when the cell content embeds Markdown fences.
+ */
+export function pickFence(content: string): string {
+  const runs = content.match(/`+/g) ?? [];
+  const longest = runs.reduce((m, r) => Math.max(m, r.length), 0);
+  return '`'.repeat(Math.max(3, longest + 1));
+}

package/src/recipes/index.ts

@@ -1,3 +1,4 @@
 export { parseBody } from './parse.js';
-export { runCode, estimateTokens, safeStringify, findCodeParamName, buildToolArgs, parseWidgetDisplayCall } from './runner.js';
+export { pickFence } from './fence.js';
+export { runCode, estimateTokens, safeStringify, findCodeParamName, buildToolArgs, parseWidgetDisplayCall, extractTopLevelDecls, hasIdentifierReference } from './runner.js';
 export type { ParsedSegment, RunResult, RunLog, RunTab, RecipeData } from './types.js';

package/src/recipes/parse.ts

@@ -16,14 +16,21 @@ export function parseBody(body: string): ParsedSegment[] {
 
   const segments: ParsedSegment[] = [];
   // Match fenced code blocks with optional language tag.
-  // Non-greedy body; allow any chars between the fences.
-  const re = /```([a-zA-Z0-9_+-]*)\r?\n([\s\S]*?)```/g;
+  // Variable-length fence (≥3 backticks, CommonMark §4.5): the closing fence
+  // must use the same number of backticks as the opening — captured via \1.
+  // The length match is what protects against premature close when cell
+  // content embeds ``` (e.g. widget('text', { content: "...```js..." }))
+  // — pickFence emits 4+ backticks in that case. We deliberately do NOT
+  // require a newline before the closing fence so that indented fences
+  // (common in numbered Markdown lists, where the close is "   ```")
+  // still parse correctly.
+  const re = /(`{3,})([a-zA-Z0-9_+-]*)\r?\n([\s\S]*?)\1/g;
 
   let lastIndex = 0;
   let match: RegExpExecArray | null;
 
   while ((match = re.exec(body)) !== null) {
-    const [full, langRaw, codeRaw] = match;
+    const [full, , langRaw, codeRaw] = match;
     const start = match.index;
 
     if (start > lastIndex) {

package/src/recipes/runner.ts

@@ -78,6 +78,21 @@ function makeCallHelper(multiClient: McpMultiClient | undefined, ctx: RunnerCtx)
   };
 }
 
+/**
+ * Sandbox-wide `unwrap(r)` helper. Many recipes assume MCP results are
+ * wrapped in `{ data | results | items: [...] }` and unwrap them with this
+ * one-liner. Falls through to the input itself, then to an empty array.
+ */
+const unwrapHelper = (r: unknown): unknown => {
+  if (r && typeof r === 'object') {
+    const o = r as Record<string, unknown>;
+    if (o.data !== undefined) return o.data;
+    if (o.results !== undefined) return o.results;
+    if (o.items !== undefined) return o.items;
+  }
+  return r ?? [];
+};
+
 /**
  * Build the `widget(name, params)` helper. Captures each call into the run
  * context so the host can mount them stacked in the run panel.
@@ -85,8 +100,10 @@ function makeCallHelper(multiClient: McpMultiClient | undefined, ctx: RunnerCtx)
 function makeWidgetHelper(ctx: RunnerCtx) {
   return async (name: string, params: Record<string, unknown> = {}) => {
     ctx.log(`widget(${name})`);
-    ctx.widgets.push({ name, params });
-    return { name, params };
+    // Push and return the SAME reference so widget_display(r) can dedup via ===.
+    const entry = { name, params };
+    ctx.widgets.push(entry);
+    return entry;
   };
 }
 
@@ -147,13 +164,16 @@ function namesFromPattern(content: string): string[] {
  *  Skips matches that occur inside a `{}` block (e.g. callback bodies) by
  *  counting unbalanced braces before the match position, on a sanitized copy
  *  of the code where strings and comments are blanked out. */
-function extractTopLevelDecls(code: string): string[] {
+export function extractTopLevelDecls(code: string): string[] {
+  // Order matters: strings before comments. Otherwise a URL like
+  // 'https://x.png' has its `//` consumed as a line comment, leaving an
+  // unbalanced quote that cascades into mismatched braces and drops decls.
   const stripped = code
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/\/\/[^\n]*/g, '')
     .replace(/'(?:\\.|[^'\\])*'/g, "''")
     .replace(/"(?:\\.|[^"\\])*"/g, '""')
-    .replace(/`(?:\\.|[^`\\])*`/g, '``');
+    .replace(/`(?:\\.|[^`\\])*`/g, '``')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '');
   const out = new Set<string>();
   // Identifier-form decls (existing behavior)
   const reId = /^[\t ]*(?:const|let|var|function|class)\s+([a-zA-Z_$][\w$]*)/gm;
@@ -180,6 +200,146 @@ function extractTopLevelDecls(code: string): string[] {
   return Array.from(out);
 }
 
+/** String/comment stripper that PRESERVES template literal interpolations.
+ *  Replaces literal text inside backtick strings with spaces but keeps
+ *  `${...}` expressions intact, so cross-cell dependency detection picks up
+ *  references like `\`Total: ${totalPoints}\``. Single/double-quoted strings
+ *  and comments are blanked entirely. */
+function stripPreservingInterpolations(code: string): string {
+  let out = '';
+  let i = 0;
+  while (i < code.length) {
+    const c = code[i];
+    // Single/double-quoted strings — wholly blanked
+    if (c === "'" || c === '"') {
+      const quote = c;
+      out += ' ';
+      i++;
+      while (i < code.length && code[i] !== quote) {
+        if (code[i] === '\\' && i + 1 < code.length) { out += '  '; i += 2; continue; }
+        out += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      out += ' ';
+      i++;
+      continue;
+    }
+    // Block comment
+    if (c === '/' && code[i + 1] === '*') {
+      out += '  ';
+      i += 2;
+      while (i < code.length && !(code[i] === '*' && code[i + 1] === '/')) {
+        out += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      out += '  ';
+      i += 2;
+      continue;
+    }
+    // Line comment
+    if (c === '/' && code[i + 1] === '/') {
+      while (i < code.length && code[i] !== '\n') { out += ' '; i++; }
+      continue;
+    }
+    // Template literal — preserve ${...} interpolations
+    if (c === '`') {
+      out += ' ';
+      i++;
+      while (i < code.length && code[i] !== '`') {
+        if (code[i] === '\\' && i + 1 < code.length) { out += '  '; i += 2; continue; }
+        if (code[i] === '$' && code[i + 1] === '{') {
+          out += '${';
+          i += 2;
+          let depth = 1;
+          while (i < code.length && depth > 0) {
+            if (code[i] === '{') depth++;
+            else if (code[i] === '}') depth--;
+            out += code[i];
+            i++;
+          }
+          continue;
+        }
+        out += code[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      out += ' ';
+      i++;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** Whether `name` appears as a free identifier in `code` — i.e. as a
+ *  standalone token (not part of a longer name) and not as a property
+ *  accessor (`obj.name` does not count). Strings and comments are stripped
+ *  but template-literal interpolations are preserved. */
+export function hasIdentifierReference(code: string, name: string): boolean {
+  if (!name) return false;
+  const stripped = stripPreservingInterpolations(code);
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(?:^|[^.\\w$])${escaped}(?:[^\\w$]|$)`);
+  return re.test(stripped);
+}
+
+/** Same string/comment stripper as extractTopLevelDecls but preserves
+ *  positions (replaces tokens with same-length whitespace) so callers can
+ *  re-locate matches in the original code. */
+function stripJsTokensSameLength(code: string): string {
+  return code
+    .replace(/'(?:\\.|[^'\\])*'/g, (s) => ' '.repeat(s.length))
+    .replace(/"(?:\\.|[^"\\])*"/g, (s) => ' '.repeat(s.length))
+    .replace(/`(?:\\.|[^`\\])*`/g, (s) => ' '.repeat(s.length))
+    .replace(/\/\*[\s\S]*?\*\//g, (s) => s.replace(/[^\n]/g, ' '))
+    .replace(/\/\/[^\n]*/g, (s) => ' '.repeat(s.length));
+}
+
+/** Top-level identifier-form const/let/var decls (subset of
+ *  extractTopLevelDecls — destructuring/function/class excluded). Used to
+ *  hoist these names outside the try block so a finally-clause writeback can
+ *  access them even when the user code returns early. */
+function extractTopLevelHoistableNames(code: string): string[] {
+  const stripped = stripJsTokensSameLength(code);
+  const out = new Set<string>();
+  const re = /^[\t ]*(?:const|let|var)\s+([a-zA-Z_$][\w$]*)/gm;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(stripped)) !== null) {
+    const before = stripped.slice(0, m.index);
+    const opens = (before.match(/\{/g) ?? []).length;
+    const closes = (before.match(/\}/g) ?? []).length;
+    if (opens === closes) out.add(m[1]);
+  }
+  return [...out];
+}
+
+/** Replace top-level `const|let|var ` keywords (+ trailing whitespace) with
+ *  whitespace of identical length, turning declarations into plain
+ *  assignments. Identifier names are preserved untouched. */
+function stripConstLetVarKeywords(code: string, names: Set<string>): string {
+  if (names.size === 0) return code;
+  const stripped = stripJsTokensSameLength(code);
+  const re = /(^|\n)([\t ]*)(const|let|var)(\s+)([a-zA-Z_$][\w$]*)/g;
+  const ranges: { from: number; to: number }[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(stripped)) !== null) {
+    if (!names.has(m[5])) continue;
+    const before = stripped.slice(0, m.index);
+    const opens = (before.match(/\{/g) ?? []).length;
+    const closes = (before.match(/\}/g) ?? []).length;
+    if (opens !== closes) continue;
+    const kwStart = m.index + m[1].length + m[2].length;
+    const kwEnd = kwStart + m[3].length + m[4].length;
+    ranges.push({ from: kwStart, to: kwEnd });
+  }
+  let result = code;
+  for (const r of ranges.reverse()) {
+    result = result.slice(0, r.from) + ' '.repeat(r.to - r.from) + result.slice(r.to);
+  }
+  return result;
+}
+
 async function runJsLike(
   code: string,
   ctx: RunnerCtx,
@@ -188,27 +348,72 @@ async function runJsLike(
 ): Promise<unknown> {
   // Wrap user code as the body of an async function that executes itself.
   // Users can use `await`, define vars, and return a final value.
-  // We inject `call` and `widget` helpers as parameters so recipes can
+  // We inject `call`, `widget`, `unwrap` helpers as parameters so recipes can
   // invoke MCP tools and emit widgets without preamble.
-  // When a `scope` object is provided, top-level decls of prior blocks are
-  // re-injected as local consts (preamble), and the current block's top-level
-  // decls are written back at the end so the next block can read them.
-  const currentDecls = new Set(extractTopLevelDecls(code));
+  //
+  // Scope propagation: top-level decls of prior blocks are re-injected as
+  // local consts (preamble), and the current block's top-level decls are
+  // written back so the next block can read them.
+  //
+  // Early-return safety: identifier-form const/let/var decls are HOISTED as
+  // `let` outside a try { ... } finally { writeback } block. Recipes
+  // commonly do `if (!x) return;` after a failed call, which would skip a
+  // post-code writeback. With finally-clause writeback, scope propagates
+  // even when the cell returns early. Destructuring / function / class
+  // decls remain inside the try (writeback at end of try) — they only
+  // propagate on natural fall-through, same as before.
+  const allDecls = new Set(extractTopLevelDecls(code));
+  const hoistable = extractTopLevelHoistableNames(code);
+  const hoistableSet = new Set(hoistable);
+  const innerOnly = [...allDecls].filter((n) => !hoistableSet.has(n));
+  const transformedCode = stripConstLetVarKeywords(code, hoistableSet);
   const priorKeys = scope
-    ? Object.keys(scope).filter((k) => /^[a-zA-Z_$][\w$]*$/.test(k) && !currentDecls.has(k))
+    ? Object.keys(scope).filter((k) => /^[a-zA-Z_$][\w$]*$/.test(k) && !allDecls.has(k))
     : [];
   const preamble = priorKeys.map((k) => `const ${k} = __scope__[${JSON.stringify(k)}];`).join('\n');
-  const writeback = scope
-    ? Array.from(currentDecls).map((k) => `__scope__[${JSON.stringify(k)}] = ${k};`).join('\n')
+  const hoist = hoistable.length ? `let ${hoistable.join(', ')};` : '';
+  const finallyWriteback = scope
+    ? hoistable.map((k) => `try { __scope__[${JSON.stringify(k)}] = ${k}; } catch {}`).join('\n')
+    : '';
+  const innerWriteback = scope
+    ? innerOnly.map((k) => `try { __scope__[${JSON.stringify(k)}] = ${k}; } catch {}`).join('\n')
     : '';
-  const wrapped = `return (async () => {\n${preamble}\n${code}\n${writeback}\n})();`;
+  const wrapped = `return (async () => {\n${preamble}\n${hoist}\ntry {\n${transformedCode}\n${innerWriteback}\n} finally {\n${finallyWriteback}\n}\n})();`;
   const fn = new (AsyncFunction as unknown as new (
     ...args: string[]
-  ) => (call: unknown, widget: unknown, __scope__: Record<string, unknown>) => Promise<unknown>)(
-    'call', 'widget', '__scope__', wrapped,
+  ) => (
+    call: unknown,
+    widget: unknown,
+    widget_display: unknown,
+    unwrap: unknown,
+    __scope__: Record<string, unknown>,
+  ) => Promise<unknown>)(
+    'call', 'widget', 'widget_display', 'unwrap', '__scope__', wrapped,
   );
   ctx.log('dispatched (inline async)');
-  const out = await fn(makeCallHelper(multiClient, ctx), makeWidgetHelper(ctx), scope ?? {});
+  // widget_display is an alias for widget that accepts either ({name,params}) or (name, params).
+  // LLMs trained on the autoui MCP tool sometimes emit it directly in JS cells.
+  const widgetHelper = makeWidgetHelper(ctx);
+  const widgetDisplayAlias = async (a: unknown, b?: unknown) => {
+    // Dedup the common LLM pattern `widget_display(widget(...))` /
+    // `const r = await widget(...); widget_display(r)`. The argument is then
+    // the exact `{name, params}` object that widget() just pushed; re-pushing
+    // would render the widget twice.
+    const last = ctx.widgets[ctx.widgets.length - 1];
+    if (last && a === last) return last;
+    if (a && typeof a === 'object' && 'name' in (a as object)) {
+      const o = a as { name?: unknown; params?: unknown };
+      return widgetHelper(String(o.name ?? ''), (o.params as Record<string, unknown>) ?? {});
+    }
+    return widgetHelper(String(a ?? ''), (b as Record<string, unknown>) ?? {});
+  };
+  const out = await fn(
+    makeCallHelper(multiClient, ctx),
+    widgetHelper,
+    widgetDisplayAlias,
+    unwrapHelper,
+    scope ?? {},
+  );
   ctx.log('resolved');
   return out;
 }

package/src/remote-mcp-registry.ts

@@ -18,7 +18,7 @@ export const REMOTE_MCP_REGISTRY: RemoteMcpRegistryEntry[] = [
     id: 'tricoteuses',
     label: 'Tricoteuses',
     description: 'French parliamentary database — amendments, votes, MPs, political groups.',
-    url: 'https://mcp.code4code.eu/mcp',
+    url: 'https://demos.hyperskills.net/mcp-code4code/mcp',
     tags: ['politics', 'france', 'parliament', 'open-data'],
   },
   {

package/src/skills/registry.ts

@@ -99,7 +99,7 @@ export function loadSkills(skills: Skill[]): void {
 const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   {
     name: 'weather-dashboard',
-    mcp: 'https://mcp.code4code.eu/mcp',
+    mcp: 'https://demos.hyperskills.net/mcp-code4code/mcp',
     mcpName: 'tricoteuses',
     description: 'Local weather with temperature, conditions, and forecasts',
     tags: ['weather', 'dashboard'],
@@ -111,7 +111,7 @@ const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   },
   {
     name: 'kpi-overview',
-    mcp: 'https://mcp.code4code.eu/mcp',
+    mcp: 'https://demos.hyperskills.net/mcp-code4code/mcp',
     mcpName: 'tricoteuses',
     description: 'KPI overview: revenue, users, churn',
     tags: ['kpi', 'dashboard'],
@@ -124,7 +124,7 @@ const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   },
   {
     name: 'status-monitor',
-    mcp: 'https://mcp.code4code.eu/mcp',
+    mcp: 'https://demos.hyperskills.net/mcp-code4code/mcp',
     mcpName: 'tricoteuses',
     description: 'Service status monitoring',
     tags: ['ops', 'monitoring'],

package/src/stores/canvas.ts

@@ -301,26 +301,9 @@ function createCanvasVanilla() {
             recipes = parseRecipesFromToolResponse(res) ?? [];
           } catch { /* no recipes */ }
         }
-        // Prefetch full bodies in parallel so apps can render markdown / run
-        // code blocks without re-calling get_recipe per surface.
-        if (recipes.length && tools.some((t: McpTool) => t.name === 'get_recipe')) {
-          recipes = await Promise.all(recipes.map(async (r) => {
-            try {
-              const res = await multiClient.callToolOn(srv.url, 'get_recipe', { name: r.name, id: r.name });
-              const text = (res as { content?: { type?: string; text?: string }[] })
-                .content?.find((c) => c?.type === 'text')?.text;
-              if (!text) return r;
-              let body = text;
-              try {
-                const p = JSON.parse(text);
-                if (p && typeof p === 'object' && typeof (p as { content?: unknown }).content === 'string') {
-                  body = (p as { content: string }).content;
-                }
-              } catch { /* raw markdown */ }
-              return { ...r, body };
-            } catch { return r; }
-          }));
-        }
+        // Bodies are fetched lazily — DiscoveryCache.resolve('get_recipe')
+        // returns null when body is missing, letting the agent loop fall
+        // through to a live MCP dispatch on demand. Avoids 1×N upfront cost.
         setDataServerMeta(name, {
           connected: true, connecting: false,
           tools: tools as McpToolInfo[],

package/tests/registry.test.ts

@@ -74,7 +74,7 @@ describe('loadDemoSkills', () => {
     loadDemoSkills();
     const skills = listSkills();
     expect(skills.length).toBe(3);
-    expect(skills.every(s => s.mcp === 'https://mcp.code4code.eu/mcp')).toBe(true);
+    expect(skills.every(s => s.mcp === 'https://demos.hyperskills.net/mcp-code4code/mcp')).toBe(true);
     expect(skills.every(s => s.mcpName === 'tricoteuses')).toBe(true);
   });
 

package/tests/runner-widget.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { runCode } from '../src/recipes/runner.js';
+
+describe('JS sandbox widget helpers', () => {
+  it('widget(name, params) pushes a single entry', async () => {
+    const res = await runCode(`await widget('echarts-pie', { values: [{ name: 'a', value: 1 }] }); return 42;`, 'js');
+    expect(res.status).toBe('done');
+    expect(res.widgets).toHaveLength(1);
+    expect(res.widgets?.[0]).toMatchObject({ name: 'echarts-pie', params: { values: [{ name: 'a', value: 1 }] } });
+    expect(res.output).toBe(42);
+  });
+
+  it('widget_display(name, params) works as alias of widget()', async () => {
+    const res = await runCode(`widget_display('echarts-pie', { values: [{ name: 'a', value: 1 }] });`, 'js');
+    expect(res.status).toBe('done');
+    expect(res.widgets).toHaveLength(1);
+    expect(res.widgets?.[0]).toMatchObject({ name: 'echarts-pie' });
+  });
+
+  it('widget_display({name, params}) works (autoui MCP shape)', async () => {
+    const res = await runCode(`widget_display({ name: 'echarts-pie', params: { values: [{ name: 'a', value: 1 }] } });`, 'js');
+    expect(res.status).toBe('done');
+    expect(res.widgets).toHaveLength(1);
+    expect(res.widgets?.[0]).toMatchObject({ name: 'echarts-pie' });
+  });
+
+  it('widget_display(widget(...)) does NOT double-push', async () => {
+    // The common LLM pattern that previously rendered the widget twice.
+    const res = await runCode(
+      `const r = await widget('echarts-pie', { values: [] }); widget_display(r);`,
+      'js',
+    );
+    expect(res.status).toBe('done');
+    expect(res.widgets).toHaveLength(1);
+  });
+
+  it('two distinct widget calls produce two entries', async () => {
+    const res = await runCode(
+      `await widget('echarts-pie', { values: [] }); await widget('echarts-bar', { rows: [] });`,
+      'js',
+    );
+    expect(res.status).toBe('done');
+    expect(res.widgets).toHaveLength(2);
+    expect(res.widgets?.[0].name).toBe('echarts-pie');
+    expect(res.widgets?.[1].name).toBe('echarts-bar');
+  });
+});