tabbied-mcp 0.2.3 → 0.2.4

package/README.md

@@ -7,12 +7,24 @@ or any other MCP client.
 
 ## Use it without installing anything
 
-The same server runs at `https://tabbied.com/mcp`:
+The same server runs at `https://tabbied.com/mcp`, with no account or key:
 
 ```bash
-claude mcp add --transport http tabbied https://tabbied.com/mcp
+claude mcp add --transport http tabbied https://tabbied.com/mcp   # Claude Code
+codex mcp add tabbied --url https://tabbied.com/mcp               # Codex
 ```
 
+- **Claude** (web and desktop): Customize, Connectors, + Add, Add custom
+  connector; enter the URL and choose "No sign in".
+- **ChatGPT**: turn on Developer mode (Settings, Security and login), then add
+  it under [Plugins](https://chatgpt.com/plugins) with the URL as a public
+  endpoint. ChatGPT reaches hosted servers only.
+- **Codex**: the command above, or `[mcp_servers.tabbied]` with
+  `url = "https://tabbied.com/mcp"` in `~/.codex/config.toml`, which the CLI,
+  the IDE extension and the ChatGPT desktop app share.
+- **Cursor** and other clients that read an `mcpServers` JSON file (VS Code's
+  `.vscode/mcp.json` uses `servers` with `"type": "http"` instead):
+
 ```jsonc
 {
   "mcpServers": {
@@ -23,22 +35,36 @@ claude mcp add --transport http tabbied https://tabbied.com/mcp
 
 ## Or run it locally, and render real files
 
+The local server adds `render_design`, which the remote one cannot offer:
+rendering a css-doodle pattern needs a real browser. It drives Chromium through
+Playwright, which this package does not install, so start the server with
+Playwright beside it, and download the browser once:
+
 ```bash
-claude mcp add tabbied -- npx -y tabbied-mcp
+npx playwright install chromium
+
+claude mcp add tabbied -- npx -y -p tabbied-mcp -p playwright tabbied-mcp   # Claude Code
+codex mcp add tabbied -- npx -y -p tabbied-mcp -p playwright tabbied-mcp    # Codex
 ```
 
+Claude Desktop (`claude_desktop_config.json`), Cursor and other clients that
+start local servers from JSON:
+
 ```jsonc
 {
   "mcpServers": {
-    "tabbied": { "command": "npx", "args": ["-y", "tabbied-mcp"] }
+    "tabbied": {
+      "command": "npx",
+      "args": ["-y", "-p", "tabbied-mcp", "-p", "playwright", "tabbied-mcp"]
+    }
   }
 }
 ```
 
-The local server adds `render_design`, which the remote one cannot offer -
-rendering a css-doodle pattern needs a real browser. Install a Playwright
-alongside it (`npm i -D playwright`) or point `TABBIED_CHROMIUM` at a Chromium
-binary.
+A Playwright installed in the project the server starts in is found too
+(`npm i -D playwright`), and `TABBIED_CHROMIUM` points it at a Chromium binary
+of your own. Without either, `npx -y tabbied-mcp` serves the other six tools,
+and `render_design` says what to install. Needs Node 20 or later.
 
 ## Tools
 
@@ -48,24 +74,49 @@ binary.
 | `get_design` | The full record for one slug, plus ready-to-paste snippets. |
 | `preview_design` | The rendered preview image for up to six designs, so the model can *look*. |
 | `get_docs` | The complete API reference (`llms-full.txt`). |
+| `list_templates` | The Tabbied website templates, a page at a time, filtered by category or by words. |
+| `get_template` | One template's editable-section spec, its download links, and how to edit each format. |
 | `render_design` | SVG or PNG at any size, seed, palette, and option set. **Local only.** |
 
 Slugs are opaque - `cleat`, `karst`, `radius` - so the intended flow is
 `search_designs` to narrow, `preview_design` to look, then `get_design` for the
 options. Choosing off tags alone is the main way this goes wrong.
 
+The website templates are licensed per Tabbied account, not with this package:
+downloading one needs an account that has chosen it, under the
+[Template License](https://tabbied.com/terms-of-service/#template-license).
+
+Setup for each client, the tools and example prompts are also on
+[tabbied.com/docs/mcp](https://tabbied.com/docs/mcp/).
+
 ## Programmatic use
 
-The package's main entry point is runtime-agnostic (no node imports), so it can
-be embedded in a Worker or any Web-standard server. It exposes the tools and an
-`McpServer` factory; the transport is the MCP SDK's:
+The package is ESM only (the `tabbied-mcp` bin is unaffected). Its main entry
+point is runtime-agnostic (no node imports), so it can be embedded in a Worker
+or any Web-standard server. It exposes the tools and an `McpServer` factory;
+the transport is the MCP SDK's. On Node, `tabbied-mcp/node` has the readers the
+bin itself uses:
 
 ```ts
 import { createMcpHandler } from '@modelcontextprotocol/server';
 import { buildServer, catalogTools } from 'tabbied-mcp';
-
-const tools = catalogTools({ catalog, fetchPreview, fetchDocs });
-
+import {
+  fetchDocs,
+  fetchPreview,
+  fetchTemplate,
+  fetchTemplateCatalog,
+  loadCatalog,
+} from 'tabbied-mcp/node';
+
+const tools = catalogTools({
+  catalog: await loadCatalog(),
+  fetchPreview,
+  fetchDocs,
+  fetchTemplateCatalog,
+  fetchTemplate,
+});
+
+// A Web-standard fetch handler, for Bun.serve, Deno.serve or a Node adapter.
 export default {
   fetch: createMcpHandler(() => buildServer(tools)).fetch,
 };
@@ -74,6 +125,19 @@ export default {
 Pass the *factory*, not a built server: MCP v2 is stateless and the handler
 constructs one server per request.
 
+Only `catalog` is required. Each fetcher adds tools, and one left out drops
+them: `fetchPreview` gives `preview_design`, `fetchDocs` gives `get_docs`,
+`fetchTemplateCatalog` gives `list_templates`, and with `fetchTemplate` as
+well, `get_template`. With all five, as above, it serves the same six tools as
+the hosted server at `https://tabbied.com/mcp`. `renderTool(catalog)`, also
+from `tabbied-mcp/node`, is `render_design`, for a host with a browser.
+
+The Node readers take the catalog and the docs from the installed `tabbied`
+package and the rest from tabbied.com. A Worker cannot use them, so it passes
+its own: each is an async function returning the same JSON (`Catalog`,
+`TemplateCatalog` and the rest are exported types), and the hosted server's
+read its own static assets.
+
 Built on [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
 v2, so it speaks the stateless `2026-07-28` revision and still serves 2025-era
 clients. `docs/mcp-server.md` in the repository has the details.

package/dist/info.d.ts

@@ -1,5 +1,5 @@
 export declare const SERVER_NAME = "tabbied";
-export declare const VERSION = "0.2.3";
+export declare const VERSION = "0.2.4";
 /**
  * Shown to the model as a preamble. It carries what no tool description can,
  * because they are properties of the *set* rather than of one call: slugs

package/dist/info.js

@@ -5,7 +5,7 @@
 // `version-packages` step rewrites it from package.json
 // (scripts/sync-version.mjs), and test/info.test.mjs pins the two together.
 export const SERVER_NAME = 'tabbied';
-export const VERSION = '0.2.3';
+export const VERSION = '0.2.4';
 /**
  * Shown to the model as a preamble. It carries what no tool description can,
  * because they are properties of the *set* rather than of one call: slugs

package/dist/info.js.map

@@ -1 +1 @@
-{"version":3,"file":"info.js","sourceRoot":"","sources":["../src/info.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,wDAAwD;AACxD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;6QAMiP,CAAC","sourcesContent":["// Server identity and the instructions clients hand to the model.\n//\n// VERSION is a literal rather than a package.json read because this module is\n// bundled into a Cloudflare Worker, which has no filesystem. The release's\n// `version-packages` step rewrites it from package.json\n// (scripts/sync-version.mjs), and test/info.test.mjs pins the two together.\nexport const SERVER_NAME = 'tabbied';\nexport const VERSION = '0.2.3';\n\n/**\n * Shown to the model as a preamble. It carries what no tool description can,\n * because they are properties of the *set* rather than of one call: slugs\n * cannot be guessed, the previews are what a choice should rest on, and the\n * sizing rule is the most common way a correct-looking integration renders as\n * nothing.\n */\nexport const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.\n\nDesigns are addressed by slug, and slugs are opaque - \"cleat\", \"karst\", \"radius\" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.\n\nMetadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.\n\nWhen you write integration code, remember a pattern has no intrinsic size: it fills its parent and collapses to nothing in a parent that sizes to content. Pass height or aspectRatio unless the parent is definitely sized. get_docs has the full API contract and recipes.`;\n"]}
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../src/info.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,wDAAwD;AACxD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;6QAMiP,CAAC","sourcesContent":["// Server identity and the instructions clients hand to the model.\n//\n// VERSION is a literal rather than a package.json read because this module is\n// bundled into a Cloudflare Worker, which has no filesystem. The release's\n// `version-packages` step rewrites it from package.json\n// (scripts/sync-version.mjs), and test/info.test.mjs pins the two together.\nexport const SERVER_NAME = 'tabbied';\nexport const VERSION = '0.2.4';\n\n/**\n * Shown to the model as a preamble. It carries what no tool description can,\n * because they are properties of the *set* rather than of one call: slugs\n * cannot be guessed, the previews are what a choice should rest on, and the\n * sizing rule is the most common way a correct-looking integration renders as\n * nothing.\n */\nexport const INSTRUCTIONS = `Tabbied is a catalog of generative patterns (css-doodle) usable as backgrounds, textures, posters, and exported SVG/PNG assets.\n\nDesigns are addressed by slug, and slugs are opaque - \"cleat\", \"karst\", \"radius\" say nothing about what they look like. Never guess one: call search_designs, which filters on a closed vocabulary of motifs, moods, density, and intended use.\n\nMetadata narrows the field; it does not settle it. These are pictures, so call preview_design on your shortlist and look before you commit. Choosing off tags alone is the main way this goes wrong.\n\nWhen you write integration code, remember a pattern has no intrinsic size: it fills its parent and collapses to nothing in a parent that sizes to content. Pass height or aspectRatio unless the parent is definitely sized. get_docs has the full API contract and recipes.`;\n"]}

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export { fetchDocs, fetchPreview, fetchTemplate, fetchTemplateCatalog, loadCatalog, tabbiedRoot, } from './resources.js';
+export { renderTool } from './render.js';

package/dist/node/index.js

@@ -0,0 +1,7 @@
+// The Node half, for hosts that run on Node rather than a Worker: what the
+// `tabbied-mcp` bin itself passes to `catalogTools`, plus `render_design`.
+// Kept off the main entry point, which a Worker bundles and which must stay
+// free of node imports (see ../index.ts).
+export { fetchDocs, fetchPreview, fetchTemplate, fetchTemplateCatalog, loadCatalog, tabbiedRoot, } from './resources.js';
+export { renderTool } from './render.js';
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC","sourcesContent":["// The Node half, for hosts that run on Node rather than a Worker: what the\n// `tabbied-mcp` bin itself passes to `catalogTools`, plus `render_design`.\n// Kept off the main entry point, which a Worker bundles and which must stay\n// free of node imports (see ../index.ts).\nexport {\n  fetchDocs,\n  fetchPreview,\n  fetchTemplate,\n  fetchTemplateCatalog,\n  loadCatalog,\n  tabbiedRoot,\n} from './resources.js';\nexport { renderTool } from './render.js';\n"]}

package/dist/node/render.js

@@ -16,11 +16,49 @@ const RENDER_TIMEOUT_MS = 180_000;
 // A PNG returned inline is spent context. Past this the file stays on disk and
 // the agent gets the path - better a usable pointer than a truncated image.
 const INLINE_BYTE_BUDGET = 1_500_000;
+// Past these a PNG is tens of megapixels (or a browser canvas limit), which
+// no asset this tool exists for needs.
+const SIZE_MAX = 4096;
+const SCALE_MAX = 4;
 const text = (value) => ({ type: 'text', text: value });
 const toolError = (message) => ({
     content: [text(message)],
     isError: true,
 });
+/** A whole number in [min, max], the default when absent, or null when invalid. */
+function integerArg(value, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max
+        ? value
+        : null;
+}
+/**
+ * The CLI's own message out of its stderr: each `tabbied:` line and the
+ * indented lines that continue it. Anything else there (Node's warnings, a
+ * deprecation notice from a dependency) is noise to the agent. When there is
+ * no such line, the CLI died some other way, and the tail is the best guess.
+ */
+function cliMessage(stderr) {
+    const lines = stderr.split('\n');
+    const kept = [];
+    let continuing = false;
+    for (const line of lines) {
+        if (line.startsWith('tabbied:')) {
+            kept.push(line);
+            continuing = true;
+        }
+        else if (continuing && /^\s+\S/.test(line)) {
+            kept.push(line);
+        }
+        else {
+            continuing = false;
+        }
+    }
+    return kept.length > 0
+        ? kept.join('\n')
+        : lines.filter((line) => line.trim()).slice(-5).join('\n');
+}
 export function renderTool(catalog) {
     return {
         definition: {
@@ -30,12 +68,14 @@ export function renderTool(catalog) {
                 'palette, and option set. Use this to produce an actual asset - or to ' +
                 'preview a *customized* configuration, which preview_design cannot show ' +
                 'you (it only has the stock palette and defaults). Needs Playwright ' +
-                'installed alongside this server. Without "out" the image comes back ' +
-                'inline; with it, the file is written where you ask.',
+                'where this server runs (start it as `npx -y -p tabbied-mcp -p ' +
+                'playwright tabbied-mcp`, with `npx playwright install chromium` once). ' +
+                'Without "out" the image comes back inline; with it, the file is ' +
+                'written where you ask, replacing any file already there.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    slug: { type: 'string', description: 'The design to render.' },
+                    slug: { type: 'string', minLength: 1, description: 'The design to render.' },
                     format: {
                         type: 'string',
                         enum: ['svg', 'png'],
@@ -44,26 +84,40 @@ export function renderTool(catalog) {
                     },
                     out: {
                         type: 'string',
-                        description: 'Absolute path to write to. Omit to get the image back inline ' +
-                            'instead of on disk.',
+                        minLength: 1,
+                        description: 'Absolute path to write to, ending in .svg or .png to match ' +
+                            '"format". Omit to get the image back inline instead of on disk.',
                     },
                     seed: {
                         type: 'string',
+                        minLength: 1,
                         description: 'Fixed seed - the same seed always gives the same image. Random ' +
                             'when omitted.',
                     },
                     palette: {
                         type: 'array',
-                        items: { type: 'string' },
+                        items: { type: 'string', minLength: 1 },
+                        minItems: 1,
                         description: "CSS colors, background first. Omit for the design's authored palette.",
                     },
                     options: {
                         type: 'object',
-                        description: 'Option values keyed by option id, e.g. {"scale": 3}. Read the ' +
-                            'ids and ranges off get_design.',
+                        additionalProperties: { type: ['string', 'number', 'boolean'] },
+                        description: 'Option values keyed by option id, e.g. {"frequency": 0.6}. Read ' +
+                            'the ids, ranges, and choices off get_design.',
+                    },
+                    width: {
+                        type: 'integer',
+                        minimum: 1,
+                        maximum: SIZE_MAX,
+                        description: 'Pixels wide (default 960).',
+                    },
+                    height: {
+                        type: 'integer',
+                        minimum: 1,
+                        maximum: SIZE_MAX,
+                        description: 'Pixels tall (default 960).',
                     },
-                    width: { type: 'integer', description: 'Pixels wide (default 960).' },
-                    height: { type: 'integer', description: 'Pixels tall (default 960).' },
                     fit: {
                         type: 'string',
                         enum: ['grid', 'cover', 'fixed'],
@@ -71,6 +125,8 @@ export function renderTool(catalog) {
                     },
                     scale: {
                         type: 'integer',
+                        minimum: 1,
+                        maximum: SCALE_MAX,
                         description: 'PNG device-scale factor. Defaults to 2 when writing a file and ' +
                             '1 when returning inline, to keep the response small.',
                     },
@@ -78,6 +134,9 @@ export function renderTool(catalog) {
                 required: ['slug', 'format'],
                 additionalProperties: false,
             },
+            // It writes a file, so it is not read-only; it only ever adds or
+            // replaces the one file it was asked for.
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
         },
         async run(args) {
             const slug = typeof args.slug === 'string' ? args.slug : '';
@@ -90,118 +149,157 @@ export function renderTool(catalog) {
                 return toolError(`"${slug}" paints effects SVG cannot represent, so it has no vector ` +
                     'export. Render it as PNG instead.');
             }
+            // The schema states these, but a host that skips validation (or calls
+            // run() directly) must not hand the CLI a path it would resolve against
+            // whatever directory the server happened to start in.
+            const out = typeof args.out === 'string' && args.out.length > 0 ? args.out : null;
+            if (out !== null && !path.isAbsolute(out)) {
+                return toolError(`"out" must be an absolute path, got "${out}". A relative one would ` +
+                    "land in the server's working directory, not yours.");
+            }
+            if (out !== null && path.extname(out).toLowerCase() !== `.${format}`) {
+                return toolError(`"out" must end in .${format} to match format "${format}", got "${out}".`);
+            }
+            const inline = out === null;
+            const width = integerArg(args.width, 960, 1, SIZE_MAX);
+            const height = integerArg(args.height, 960, 1, SIZE_MAX);
+            const scale = integerArg(args.scale, inline ? 1 : 2, 1, SCALE_MAX);
+            if (width === null || height === null) {
+                return toolError(`"width" and "height" must be whole pixels from 1 to ${SIZE_MAX}.`);
+            }
+            if (scale === null) {
+                return toolError(`"scale" must be a whole number from 1 to ${SCALE_MAX}.`);
+            }
+            // Options reach the CLI as one "id: value; id: value" string, so a `;`
+            // inside a value would end it and start an option of its own, past
+            // every check on the first. Ranges and choices are the CLI's to check.
+            let options = null;
+            if (args.options !== undefined) {
+                if (!args.options || typeof args.options !== 'object' || Array.isArray(args.options)) {
+                    return toolError('"options" must be an object of option values keyed by id.');
+                }
+                const ids = design.options.map((option) => option.id);
+                const pairs = [];
+                for (const [id, value] of Object.entries(args.options)) {
+                    if (!ids.includes(id)) {
+                        return toolError(`"${slug}" has no option "${id}" (has: ${ids.join(', ') || 'none'}).`);
+                    }
+                    if (!['string', 'number', 'boolean'].includes(typeof value) || /[;\n]/.test(String(value))) {
+                        return toolError(`Option "${id}" must be a single string, number, or boolean value ` +
+                            '(no ";" or line breaks).');
+                    }
+                    pairs.push(`${id}: ${String(value)}`);
+                }
+                if (pairs.length > 0)
+                    options = pairs.join('; ');
+            }
             const root = tabbiedRoot();
             if (!root) {
                 return toolError('The `tabbied` package is not installed next to this server, so the ' +
                     'renderer is unavailable. Run `npm install tabbied`.');
             }
-            const inline = typeof args.out !== 'string' || args.out.length === 0;
             // An inline render gets a scratch directory, removed once its bytes
-            // have been read back.
+            // have been read back, or once the render has failed.
             const scratch = inline ? await mkdtemp(path.join(tmpdir(), 'tabbied-')) : null;
-            const outPath = scratch ? path.join(scratch, `${slug}.${format}`) : args.out;
-            const discard = () => (scratch ? rm(scratch, { recursive: true, force: true }) : Promise.resolve());
-            const scale = typeof args.scale === 'number' && Number.isFinite(args.scale)
-                ? Math.trunc(args.scale)
-                : inline
-                    ? 1
-                    : 2;
+            const outPath = scratch ? path.join(scratch, `${slug}.${format}`) : out;
+            let keepScratch = false;
+            // A value that starts with "-" (a seed of "--browser", say) would read
+            // as the next flag, so it goes as --flag=value, which the CLI takes
+            // from tabbied 0.7.1. Everything else stays two arguments, which every
+            // version of the CLI reads.
+            const flag = (name, value) => value.startsWith('-') ? [`--${name}=${value}`] : [`--${name}`, value];
             const argv = [
                 path.join(root, 'dist', 'cli.js'),
                 'render',
                 slug,
-                '--out',
-                outPath,
-                '--format',
-                format,
-                '--scale',
-                String(scale),
+                ...flag('out', outPath),
+                ...flag('format', format),
+                ...flag('scale', String(scale)),
+                ...flag('size', `${width}x${height}`),
             ];
-            const push = (flag, value) => argv.push(flag, value);
             if (typeof args.seed === 'string' && args.seed)
-                push('--seed', args.seed);
+                argv.push(...flag('seed', args.seed));
             if (typeof args.fit === 'string')
-                push('--fit', args.fit);
-            const width = typeof args.width === 'number' ? Math.trunc(args.width) : 960;
-            const height = typeof args.height === 'number' ? Math.trunc(args.height) : 960;
-            push('--size', `${width}x${height}`);
-            if (Array.isArray(args.palette) && args.palette.length) {
-                push('--palette', args.palette.filter(Boolean).join(','));
-            }
-            if (args.options && typeof args.options === 'object') {
-                const pairs = Object.entries(args.options)
-                    .map(([id, value]) => `${id}: ${String(value)}`)
-                    .join('; ');
-                if (pairs)
-                    push('--options', pairs);
+                argv.push(...flag('fit', args.fit));
+            if (Array.isArray(args.palette)) {
+                const colors = args.palette.filter((color) => typeof color === 'string' && color.trim().length > 0);
+                if (colors.length > 0)
+                    argv.push(...flag('palette', colors.join(',')));
             }
-            let stderr = '';
+            if (options)
+                argv.push(...flag('options', options));
             try {
-                // No shell: argv goes straight to node, so a palette or option value
-                // can't be read as shell syntax.
-                ({ stderr } = await run(process.execPath, argv, {
-                    timeout: RENDER_TIMEOUT_MS,
-                    maxBuffer: 8 * 1024 * 1024,
-                }));
-            }
-            catch (error) {
-                const detail = error && typeof error === 'object' && 'stderr' in error
-                    ? String(error.stderr).trim()
-                    : error instanceof Error
-                        ? error.message
-                        : String(error);
-                return toolError(`Rendering failed: ${detail || 'the CLI exited non-zero.'}\n\n` +
-                    'If this says a browser is missing, install one alongside the ' +
-                    'server (`npm i -D playwright`) or point TABBIED_CHROMIUM at a ' +
-                    'Chromium binary.');
-            }
-            // The CLI reports SVG-fidelity caveats on stderr; they matter enough to
-            // pass through rather than swallow.
-            const notes = stderr
-                .split('\n')
-                .filter((line) => line.trim().startsWith('note:'))
-                .join('\n');
-            if (!inline) {
-                const { size } = await stat(outPath);
-                return {
-                    content: [
-                        text(`Rendered ${slug} to ${outPath} (${width}x${height}` +
-                            (format === 'png' ? ` @${scale}x` : '') +
-                            `, ${Math.round(size / 1024)} KB).` +
-                            (notes ? `\n${notes}` : '')),
-                    ],
-                };
-            }
-            if (format === 'svg') {
-                const svg = await readFile(outPath, 'utf-8');
-                await discard();
+                let stderr = '';
+                try {
+                    // No shell: argv goes straight to node, so a palette or option value
+                    // can't be read as shell syntax.
+                    ({ stderr } = await run(process.execPath, argv, {
+                        timeout: RENDER_TIMEOUT_MS,
+                        maxBuffer: 8 * 1024 * 1024,
+                    }));
+                }
+                catch (error) {
+                    const failure = error;
+                    if (failure.killed) {
+                        return toolError(`Rendering timed out after ${RENDER_TIMEOUT_MS / 1000}s. Try a smaller ` +
+                            'width/height or scale.');
+                    }
+                    const detail = typeof failure.stderr === 'string' && failure.stderr.trim()
+                        ? cliMessage(failure.stderr)
+                        : (failure.message ?? String(error));
+                    return toolError(`Rendering failed:\n${detail}`);
+                }
+                // The CLI reports SVG-fidelity caveats on stderr; they matter enough to
+                // pass through rather than swallow.
+                const notes = stderr
+                    .split('\n')
+                    .filter((line) => line.trim().startsWith('note:'))
+                    .join('\n');
+                if (!inline) {
+                    const { size } = await stat(outPath);
+                    return {
+                        content: [
+                            text(`Rendered ${slug} to ${outPath} (${width}x${height}` +
+                                (format === 'png' ? ` @${scale}x` : '') +
+                                `, ${Math.round(size / 1024)} KB).` +
+                                (notes ? `\n${notes}` : '')),
+                        ],
+                    };
+                }
+                if (format === 'svg') {
+                    const svg = await readFile(outPath, 'utf-8');
+                    return {
+                        content: [
+                            text(`Rendered ${slug} as SVG (${width}x${height}).` +
+                                (notes ? `\n${notes}` : '')),
+                            text(svg),
+                        ],
+                    };
+                }
+                const png = await readFile(outPath);
+                const data = png.toString('base64');
+                if (data.length > INLINE_BYTE_BUDGET) {
+                    // Kept: the answer tells the agent to read it from that path.
+                    keepScratch = true;
+                    return {
+                        content: [
+                            text(`Rendered ${slug} to ${outPath} - ${Math.round(png.byteLength / 1024)} KB, too large to return inline. Read it from that path, or ` +
+                                're-render smaller (lower "scale", or a smaller width/height).'),
+                        ],
+                    };
+                }
                 return {
                     content: [
-                        text(`Rendered ${slug} as SVG (${width}x${height}).` +
+                        text(`Rendered ${slug} (${width}x${height} @${scale}x).` +
                             (notes ? `\n${notes}` : '')),
-                        text(svg),
+                        { type: 'image', data, mimeType: 'image/png' },
                     ],
                 };
             }
-            const png = await readFile(outPath);
-            const data = png.toString('base64');
-            if (data.length > INLINE_BYTE_BUDGET) {
-                // Kept: the answer tells the agent to read it from that path.
-                return {
-                    content: [
-                        text(`Rendered ${slug} to ${outPath} - ${Math.round(png.byteLength / 1024)} KB, too large to return inline. Read it from that path, or ` +
-                            're-render smaller (lower "scale", or a smaller width/height).'),
-                    ],
-                };
+            finally {
+                if (scratch && !keepScratch)
+                    await rm(scratch, { recursive: true, force: true });
             }
-            await discard();
-            return {
-                content: [
-                    text(`Rendered ${slug} (${width}x${height} @${scale}x).` +
-                        (notes ? `\n${notes}` : '')),
-                    { type: 'image', data, mimeType: 'image/png' },
-                ],
-            };
         },
     };
 }