@nexusbloom/mcp-server 2.1.0 → 2.1.2

package/README.md

@@ -52,6 +52,16 @@ anything else there corrupts the protocol.
 Every published tool is advertised as an MCP tool **named by its slug**, with its
 real JSON Schema — so it can be called directly:
 
+> **One caveat on slugs.** A slug has to match MCP's tool-name grammar
+> (`[A-Za-z0-9_-]{1,64}`) to be advertised. A catalogue slug that does not — a
+> space, a slash, non-ASCII, or more than 64 characters — is *withheld from the
+> tool list* and reported once on stderr, because a strict host validates every
+> name in that array and rejects the whole response over one bad entry. That
+> would cost an agent every tool rather than one. A withheld tool is still
+> reachable through `{"command":"run"}` and `nexusbloom://catalogue`; it is only
+> not directly callable. `npm run catalogue-check` verifies a catalogue against
+> the grammar.
+
 ```jsonc
 { "name": "env-validator", "arguments": { "env_content": "DEBUG=true" } }
 ```
@@ -66,7 +76,7 @@ which tool it wants:
 | `{"command":"schema","slug":"…"}` | Exact parameters, plus a ready-to-send example invocation. |
 | `{"command":"run","slug":"…","params":{…}}` | Execute a tool. |
 | `{"command":"batch","runs":[{"slug":"…","params":{…}},…]}` | Execute up to 10 tools in one call. |
-| `{"command":"history"}` | What this session has run, newest first. |
+| `{"command":"history"}` | What this **server process** has run, newest first. |
 | `{"command":"history","show":"<id>"}` | One run in full: input, result, timing. |
 | `{"command":"diff","from":"<id>","to":"<id>"}` | Compare two runs field by field. |
 
@@ -201,6 +211,16 @@ Three deliberate constraints:
 - **In memory, never on disk.** Run payloads are user data and frequently
   secrets. A log on disk would be an unencrypted store nobody asked for, and
   losing it on restart costs nothing the tool call did not.
+- **Scoped to the process, not the conversation.** Most hosts keep the stdio
+  process alive across turns, so history spans every conversation turn the
+  process has served — it is not reset between them. Every history response says
+  so, and carries the process start time, because an agent that finds a run it
+  cannot account for needs somewhere to stop guessing. Observed in a real
+  session: an agent correctly reported that an unexplained earlier run had
+  different input, then invented a story about who had changed it and when,
+  and escalated it into a security incident. The facts were right; the cause
+  was fiction. Naming the boundary is what makes "this predates me" a
+  checkable statement.
 - **Bounded.** 50 runs, each payload capped at 8,000 characters. Truncation is
   recorded, and a diff says so — a truncated payload reporting "no differences"
   would be the worst possible failure mode here.
@@ -238,6 +258,20 @@ Input is checked against the tool's own schema before anything is sent, so a
 malformed call costs no API quota and returns an error naming the exact field.
 The API remains authoritative — this only rejects what is provably wrong.
 
+## Developer scripts
+
+| Command | What it does |
+|---|---|
+| `npm run shell` | Interactive MCP client over real stdio. `shell:mock` starts a fake API for you. |
+| `npm run agent-demo` | Walks the path an LLM takes — discover, search, schema, run, batch, recover — with no model needed. `agent-demo:mock` starts its own mock. |
+| `npm run catalogue-check` | Every tool in the seed catalogue walked through the real server: advertise, describe, validate, run, batch, resolve as a resource. Exits non-zero on any failure, so it works as a CI gate. |
+| `npm run mock-api [port]` | The fake API on its own. Reuses a running one or explains what holds the port. |
+
+`agent-demo` checks the API is reachable before it starts. That is deliberate:
+when the mock is not running, every check otherwise fails with its own
+`ECONNREFUSED`, and ten identical failures read as a broken server rather than a
+missing dependency.
+
 ## Design notes
 
 **Execution never guesses.** Slugs resolve by exact match or unambiguous

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "MCP server for NexusBloom \u2014 agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
   "type": "module",
   "main": "index.js",
@@ -34,12 +34,13 @@
     "test": "node --test --import ./test/setup.mjs test/*.test.js",
     "test:coverage": "node --test --experimental-test-coverage --import ./test/setup.mjs test/*.test.js",
     "test:watch": "node --test --watch --import ./test/setup.mjs test/*.test.js",
-    "test:src-only": "node --test --import ./test/setup.mjs test/config.test.js test/errors.test.js test/manifests.test.js test/discovery.test.js test/client.test.js test/validate.test.js test/render.test.js test/cache.test.js test/handlers.test.js test/resources.test.js test/batch.test.js test/progress.test.js test/prompts.test.js test/history.test.js test/local.test.js",
     "shell": "node scripts/mcp-shell.mjs",
     "shell:mock": "node scripts/mcp-shell.mjs --mock",
     "mock-api": "node scripts/mock-api.mjs",
     "agent-demo": "node scripts/agent-demo.mjs",
-    "agent-demo:mock": "node scripts/agent-demo.mjs --url http://127.0.0.1:8787/api",
-    "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done"
+    "agent-demo:mock": "node scripts/agent-demo.mjs --mock",
+    "catalogue-check": "node scripts/full-catalogue-check.mjs",
+    "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done",
+    "prepublishOnly": "npm run lint && npm test && npm run catalogue-check"
   }
 }

package/src/client.js

@@ -24,6 +24,49 @@ export function makeLogger(debug) {
   };
 }
 
+/**
+ * Turn whatever the API put in `error` into a message an agent can act on.
+ *
+ * The obvious version of this is `String(apiMessage).trim() || fallback`, but
+ * `String({})` is `"[object Object]"` — technically a string, useless as a
+ * diagnosis. Production returns structured errors (`error` as an object, an
+ * array, occasionally a number), and the previous code called `.trim()` on the
+ * raw value: optional chaining guards null and undefined, not "exists and is not
+ * a function". Every structured API error therefore died as
+ * `TypeError: apiMessage?.trim is not a function` — thrown from the error path,
+ * so it fired only once something was already broken, and it replaced the real
+ * status and code with a stack trace about the client's own bug.
+ *
+ * So: preserve structure as JSON, because `{"hint":"rate limited"}` tells an
+ * agent what `[object Object]` cannot, and never throw while reporting a
+ * failure.
+ *
+ * @param {unknown} candidate
+ * @param {Response} res
+ * @param {{method: string, url: string}} ctx
+ * @returns {string}
+ */
+export function describeApiError(candidate, res, ctx) {
+  const fallback = `API returned ${res.status} for ${ctx.method} ${ctx.url}`;
+
+  if (candidate === null || candidate === undefined) return fallback;
+
+  if (typeof candidate === "string") return candidate.trim() || fallback;
+
+  if (typeof candidate === "object") {
+    try {
+      const json = JSON.stringify(candidate);
+      return json && json !== "{}" && json !== "[]" ? json : fallback;
+    } catch {
+      // Circular, or a BigInt. The status line still identifies the failure.
+      return fallback;
+    }
+  }
+
+  // number, boolean, bigint, symbol, function — all fine as text.
+  return String(candidate) || fallback;
+}
+
 export class ApiClient {
   /**
    * @param {object} config  From loadConfig().
@@ -143,15 +186,13 @@ export class ApiClient {
     }
 
     if (!res.ok) {
-      const apiMessage =
-        parsed?.error || parsed?.message || parsed?.data?.error || text?.slice(0, 300);
-      const code = parsed?.code || codeForStatus(res.status);
-
-      const message = apiMessage?.trim()
-        ? `${apiMessage}`
-        : `API returned ${res.status} for ${ctx.method} ${ctx.url}`;
+      const message = describeApiError(
+        parsed?.error ?? parsed?.message ?? parsed?.data?.error ?? text?.slice(0, 300),
+        res,
+        ctx,
+      );
 
-      throw new NexusBloomError(message, code, {
+      throw new NexusBloomError(message, parsed?.code || codeForStatus(res.status), {
         status: res.status,
         // The API returns `fields` on schema failures; keep it so an agent can
         // repair exactly the bad keys instead of re-reading the whole schema.

package/src/handlers.js

@@ -18,7 +18,7 @@ import {
   suggest,
 } from "./discovery.js";
 import { asNexusBloomError, ErrorCode, NexusBloomError } from "./errors.js";
-import { ManifestCache, normaliseTool } from "./manifests.js";
+import { ManifestCache, normaliseTool, partitionAdvertisable } from "./manifests.js";
 import {
   renderBatch,
   renderConnectivityReport,
@@ -298,7 +298,7 @@ export function createHandlers({ client, cache, config, history: providedHistory
       }
       const limit = Number.isInteger(args?.limit) && args.limit > 0 ? Math.min(args.limit, 50) : 10;
       const all = history.list();
-      return respond(renderHistory(history.recent(limit), { total: all.length }));
+      return respond(renderHistory(history.recent(limit), { total: all.length, scope: history.scope() }));
     }
 
     if (command === "diff") {
@@ -449,7 +449,19 @@ export function createHandlers({ client, cache, config, history: providedHistory
   }
 
   return {
-    listTools: buildToolList(cache),
+    // Withheld tools are reported once, on stderr, and not behind a debug flag:
+    // a slug the catalogue cannot express as an MCP tool name is a data problem
+    // somebody has to fix, and silence leaves the tool quietly unreachable.
+    listTools: buildToolList(cache, {
+      onWithheld(withheld) {
+        for (const w of withheld) {
+          process.stderr.write(
+            `[catalogue] "${w.slug}" is not advertised as an MCP tool — ${w.reason}. ` +
+              'It is still reachable via {"command":"run"} and nexusbloom://catalogue.\n',
+          );
+        }
+      },
+    }),
     meta,
     batch: runBatch,
     history,
@@ -569,7 +581,7 @@ function enrichNotFound(err, slug, tools) {
  * meta-tool is advertised too — it is how an agent recovers when a direct call
  * is not what it wanted.
  */
-export function buildToolList(cache) {
+export function buildToolList(cache, { onWithheld } = {}) {
   return async function listTools() {
     // A catalogue failure must not fail the whole request. If the API is
     // unreachable, a host that receives a JSON-RPC error considers the *server*
@@ -582,7 +594,16 @@ export function buildToolList(cache) {
       tools = [];
     }
 
-    const entries = tools.map((t) => ({
+    // A slug that is not a legal MCP tool name is held back rather than
+    // emitted. A strict host validates every name in this array and rejects the
+    // entire response over one bad entry, so a single odd slug in the catalogue
+    // would cost the agent every tool — not just that one. The meta-tool still
+    // reaches the withheld tools, and the reason is surfaced rather than
+    // swallowed, so the catalogue can be fixed at source.
+    const { advertisable, withheld } = partitionAdvertisable(tools);
+    if (withheld.length) onWithheld?.(withheld);
+
+    const entries = advertisable.map((t) => ({
       name: t.slug,
       description: buildToolDescription(t),
       inputSchema: t.input_schema,
@@ -597,7 +618,7 @@ export function buildToolList(cache) {
         '- {"command":"list"} — every published tool, one line each\n' +
         '- {"command":"schema","slug":"<slug>"} — exact parameters plus a ready-to-send example\n' +
         '- {"command":"batch","runs":[{"slug":"<slug>","params":{…}},…]} — run up to 10 tools in one call\n' +
-        '- {"command":"history"} / {"command":"history","show":"<id>"} — what this session has run\n' +
+        '- {"command":"history"} / {"command":"history","show":"<id>"} — what this server process has run\n' +
         '- {"command":"diff","from":"<id>","to":"<id>"} — compare two runs field by field\n\n' +
         "Any published tool is also callable directly by its slug, with its own " +
         "parameters as arguments — this tool is for when you do not yet know which one to use.\n\n" +
@@ -613,7 +634,7 @@ export function buildToolList(cache) {
             description:
               "list: all tools. search: find by intent. schema: a tool's parameters. " +
               "run: execute one tool. batch: execute up to 10 tools in one call. " +
-              "history: what this session has run. diff: compare two recorded runs.",
+              "history: what this server process has run, and since when. diff: compare two recorded runs.",
           },
           slug: {
             type: "string",

package/src/history.js

@@ -61,6 +61,37 @@ export class RunHistory {
     this.now = now;
     this.runs = [];
     this._nextId = 1;
+    // When this process started holding history. Present so an agent can tell
+    // "a run this process saw" from "a run from before I was talking" — see
+    // the note on scope below.
+    this.startedAt = new Date(this.now()).toISOString();
+  }
+
+  /**
+   * What "history" actually covers, for callers to surface verbatim.
+   *
+   * This is deliberately not called a session. A host that keeps the stdio
+   * process alive across turns — which is most of them — will hand the same
+   * process several separate conversations, and history spans all of them.
+   *
+   * Observed in a real agent session: the agent found an `r1` it could not
+   * account for, correctly reported that its input differed from its own, and
+   * then invented a causal story about who changed what and when — including
+   * an urgent security conclusion — because nothing in the output said where
+   * the boundary was. The facts were right and the cause was fiction.
+   *
+   * Naming the scope is what stops that: an agent can say "this run predates my
+   * involvement in this process", which is checkable, instead of inventing why.
+   */
+  scope() {
+    return {
+      scope: "server-process",
+      startedAt: this.startedAt,
+      note:
+        "In-memory only. Covers every run since this server process started, " +
+        "which may span multiple conversation turns if your host keeps the " +
+        "process alive. Never written to disk.",
+    };
   }
 
   /**

package/src/manifests.js

@@ -37,6 +37,50 @@ export function normaliseTags(tags) {
  * cannot be called, and letting it through would surface as a tool the agent
  * sees in the list but can never invoke.
  */
+/**
+ * The MCP tool-name grammar.
+ *
+ * A published slug is whatever the catalogue happens to contain, and nothing
+ * upstream constrains it to this. Emitting an illegal name in `tools/list` is
+ * not a cosmetic problem: a strict host validates every name in the array and
+ * rejects the *whole response* over one bad entry, which leaves the agent with
+ * no tools at all rather than one fewer. So illegal slugs are held back from
+ * the tool list and reported instead — see `partitionAdvertisable`.
+ */
+export const MCP_TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/**
+ * Split a catalogue into tools that can be advertised as MCP tools and tools
+ * whose slug cannot be.
+ *
+ * The held-back tools stay fully usable through the meta-tool and the catalogue
+ * resource — they are only prevented from poisoning the tool list for
+ * everything else. That is the difference between "this tool is awkward to
+ * address" and "this tool does not exist".
+ *
+ * @param {object[]} tools normalised tools
+ * @returns {{advertisable: object[], withheld: {slug: string, reason: string}[]}}
+ */
+export function partitionAdvertisable(tools) {
+  const advertisable = [];
+  const withheld = [];
+
+  for (const tool of tools) {
+    const slug = tool?.slug ?? "";
+    if (MCP_TOOL_NAME.test(slug)) {
+      advertisable.push(tool);
+      continue;
+    }
+    let reason;
+    if (!slug) reason = "slug is empty";
+    else if (slug.length > 64) reason = `slug is ${slug.length} characters, the MCP maximum is 64`;
+    else reason = `slug contains characters MCP does not allow in a tool name: ${JSON.stringify(slug)}`;
+    withheld.push({ slug: String(slug), reason });
+  }
+
+  return { advertisable, withheld };
+}
+
 export function normaliseTool(raw) {
   if (!raw || typeof raw !== "object") return null;
   const slug = typeof raw.slug === "string" ? raw.slug.trim() : "";

package/src/render.js

@@ -340,13 +340,22 @@ export function renderResult(slug, data, { durationMs, execution = "remote", rat
  * compare, and inlining fifty payloads would cost more context than the diff the
  * reader actually came for. `history show` carries the payload for one run.
  */
-export function renderHistory(runs, { total } = {}) {
+export function renderHistory(runs, { total, scope } = {}) {
+  // The scope line is load-bearing, not decoration. Without it an agent that
+  // finds a run it cannot account for has no way to tell "this process saw it"
+  // from "it happened before I was involved", and will fill the gap with a
+  // guess. Naming the boundary lets it say "this predates me" and stop there.
+  const scopeLine = scope
+    ? `\nScope: ${scope.scope}, started ${scope.startedAt}. ${scope.note}\n`
+    : "";
+
   if (!runs.length) {
     return {
       text:
-        `# Run history\n\nNo runs recorded in this session.\n\n` +
-        `History lives in memory only: it starts empty on every server start and is never written to disk.`,
-      data: { runs: [], count: 0 },
+        `# Run history\n\nNo runs recorded since this server started.` +
+        scopeLine +
+        `\nHistory is never written to disk.`,
+      data: { runs: [], count: 0, ...(scope ? { scope } : {}) },
     };
   }
 
@@ -358,13 +367,14 @@ export function renderHistory(runs, { total } = {}) {
 
   const text =
     `# Run history\n\n` +
-    `${runs.length} of ${total ?? runs.length} recorded run${runs.length === 1 ? "" : "s"}, newest first.\n\n` +
-    `${lines.join("\n")}\n\n` +
+    `${runs.length} of ${total ?? runs.length} recorded run${runs.length === 1 ? "" : "s"}, newest first.` +
+    scopeLine +
+    `\n${lines.join("\n")}\n\n` +
     `---\n` +
     `Compare two runs with \`{"command":"diff","from":"<id>","to":"<id>"}\`. ` +
     `\`-1\` is the most recent run, \`-2\` the one before it.`;
 
-  return { text, data: { runs, count: runs.length } };
+  return { text, data: { runs, count: runs.length, ...(scope ? { scope } : {}) } };
 }
 
 /** One run in full, with its result. */

package/src/resources.js

@@ -62,7 +62,8 @@ export function createResources({ cache, config, history } = {}) {
           uri: HISTORY_URI,
           name: "Run history",
           description:
-            "What this session has run, newest first: run id, tool, status, duration. " +
+            "What this server process has run, newest first: run id, tool, status, duration, " +
+            "plus the process start time so the boundary is explicit. " +
             "In memory only — never written to disk.",
           mimeType: JSON_MIME,
         },
@@ -137,7 +138,10 @@ export function createResources({ cache, config, history } = {}) {
   function readHistory(log) {
     if (!log) return { runs: [], count: 0, note: "No run log is attached to this resource set." };
     const runs = log.recent(50).map((r) => summariseRun(r));
-    return { runs, count: runs.length };
+    // Same scope block as `{"command":"history"}` — a host pulling this as a
+    // resource has no more idea when the process started than one calling the
+    // command does.
+    return { runs, count: runs.length, scope: log.scope() };
   }
 
   /**
@@ -265,7 +269,7 @@ Meta commands:
 - \`{"command":"schema","slug":"<slug>"}\` — parameters plus a ready-to-send example
 - \`{"command":"run","slug":"<slug>","params":{…}}\` — execute
 - \`{"command":"batch","runs":[…]}\` — up to 10 runs in one call
-- \`{"command":"history"}\` / \`{"command":"history","show":"<id>"}\` — what this session ran
+- \`{"command":"history"}\` / \`{"command":"history","show":"<id>"}\` — what this server process ran
 - \`{"command":"diff","from":"<id>","to":"<id>"}\` — compare two runs, field by field
 
 And when several tools belong to one task, run them in a single turn:

package/src/preview.test.js

@@ -1,185 +0,0 @@
-/**
- * Tier-1 preview inference.
- *
- * Two properties matter more than the individual detectors:
- *   1. it never looks at the slug, so tools that do not exist yet still render;
- *   2. it fails closed — anything unsafe or unrecognised returns null and the
- *      caller emits its normal text block.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  inferPreview,
-  previewResult,
-  isSafeSvg,
-  escapeXml,
-} from "./preview.js";
-
-// ─── colours ────────────────────────────────────────────────────────────────
-
-test("renders an array of hex colours as swatches", () => {
-  const out = inferPreview(["#0b1a31", "#16305c", "#204787"], { slug: "x" });
-  assert.equal(out.kind, "colors");
-  const svg = out.block.resource.text;
-  assert.match(svg, /#0b1a31/);
-  assert.match(svg, /#204787/);
-  assert.match(svg, /<text/);
-});
-
-test("renders 3-digit hex", () => {
-  const out = inferPreview(["#fff", "#000"], { slug: "x" });
-  assert.equal(out.kind, "colors");
-});
-
-test("renders colours pulled from a colour-keyed object", () => {
-  const out = inferPreview({ primary: "#3b82f6", accent: "#ff7a59" }, { slug: "x" });
-  assert.equal(out.kind, "colors");
-  assert.match(out.block.resource.text, /#3b82f6/);
-});
-
-test("ignores an array that is not all hex", () => {
-  assert.equal(inferPreview(["#fff", "not-a-colour"]), null);
-});
-
-test("ignores an oversized swatch list", () => {
-  assert.equal(inferPreview(Array.from({ length: 40 }, () => "#fff")), null);
-});
-
-// ─── gradients ──────────────────────────────────────────────────────────────
-
-test("renders a linear gradient from real stops", () => {
-  const out = inferPreview("linear-gradient(90deg, #3b82f6, #ff7a59)");
-  assert.equal(out.kind, "gradient");
-  const svg = out.block.resource.text;
-  assert.match(svg, /<linearGradient/);
-  assert.match(svg, /#3b82f6/);
-  assert.match(svg, /#ff7a59/);
-});
-
-test("detects a gradient inside a full CSS declaration", () => {
-  // What css-gradient-generator actually returns.
-  const out = inferPreview("background: linear-gradient(90deg, #3b82f6, #ff7a59);");
-  assert.equal(out.kind, "gradient");
-  assert.match(out.block.resource.text, /#3b82f6/);
-});
-
-test("renders a radial gradient as a radialGradient", () => {
-  const out = inferPreview("radial-gradient(circle, #fff, #000)");
-  assert.equal(out.kind, "gradient");
-  assert.match(out.block.resource.text, /<radialGradient/);
-});
-
-test("conic degrades to a stop ramp rather than lying about the shape", () => {
-  const out = inferPreview("conic-gradient(#f00, #0f0, #00f)");
-  assert.equal(out.kind, "gradient-conic");
-  // 3-digit stops are expanded, and drawn as discrete bands not a real conic.
-  assert.match(out.block.resource.text, /#ff0000/);
-  assert.doesNotMatch(out.block.resource.text, /<radialGradient|<linearGradient/);
-});
-
-test("expands 3-digit hex stops", () => {
-  const out = inferPreview("linear-gradient(#abc, #def)");
-  assert.match(out.block.resource.text, /#aabbcc/);
-});
-
-test("a gradient with unresolvable colours yields no preview", () => {
-  assert.equal(inferPreview("linear-gradient(var(--a), var(--b))"), null);
-});
-
-// ─── svg ────────────────────────────────────────────────────────────────────
-
-const safeSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="40" height="20"><rect width="40" height="20" fill="#3b82f6"/></svg>`;
-
-test("renders a safe svg verbatim", () => {
-  const out = inferPreview(safeSvg, { slug: "x" });
-  assert.equal(out.kind, "svg");
-  assert.equal(out.block.resource.text, safeSvg);
-});
-
-test("pads a square svg so a QR code keeps its quiet zone", () => {
-  // 63px at the default 3px module pitch needs >= 4 modules = 12px.
-  const qr = `<svg xmlns="http://www.w3.org/2000/svg" width="63" height="63" viewBox="0 0 63 63"><rect width="63" height="63" fill="#fff"/></svg>`;
-  const out = inferPreview(qr, { slug: "qr-code-generator" });
-  assert.equal(out.kind, "code");
-  assert.match(out.block.resource.text, /width="87" height="87"/);
-  assert.match(out.block.resource.text, /translate\(12,12\)/);
-  assert.match(out.block.resource.text, /fill="#ffffff"/);
-});
-
-test("rejects svg carrying a script", () => {
-  const bad = `<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>`;
-  assert.equal(isSafeSvg(bad), false);
-  const out = inferPreview(bad, { slug: "x" });
-  assert.equal(out.block, null);
-  assert.equal(out.kind, "rejected-svg");
-});
-
-test("rejects svg with an event handler", () => {
-  assert.equal(isSafeSvg(`<svg onload="x()"></svg>`), false);
-  assert.equal(isSafeSvg(`<svg><rect onclick="x()"/></svg>`), false);
-});
-
-test("rejects svg reaching out to the network", () => {
-  assert.equal(isSafeSvg(`<svg><image href="https://evil.example/x.png"/></svg>`), false);
-  assert.equal(isSafeSvg(`<svg><use xlink:href="http://evil/x#y"/></svg>`), false);
-});
-
-test("rejects foreignObject and entity tricks", () => {
-  assert.equal(isSafeSvg(`<svg><foreignObject><body/></foreignObject></svg>`), false);
-  assert.equal(isSafeSvg(`<!DOCTYPE svg [<!ENTITY x SYSTEM "file:///etc/passwd">]><svg/>`), false);
-});
-
-test("accepts a plain svg", () => {
-  assert.equal(isSafeSvg(safeSvg), true);
-});
-
-// ─── data images ────────────────────────────────────────────────────────────
-
-test("renders a raster data uri as a real image block", () => {
-  const out = inferPreview("data:image/png;base64,iVBORw0KGgo=");
-  assert.equal(out.kind, "image");
-  assert.equal(out.block.type, "image");
-  assert.equal(out.block.mimeType, "image/png");
-  assert.equal(out.block.data, "iVBORw0KGgo=");
-});
-
-// ─── falling open ───────────────────────────────────────────────────────────
-
-test("returns null for values with no visual meaning", () => {
-  assert.equal(inferPreview(null), null);
-  assert.equal(inferPreview(undefined), null);
-  assert.equal(inferPreview(42), null);
-  assert.equal(inferPreview("just some text"), null);
-  assert.equal(inferPreview(true), null);
-});
-
-test("a broken detector never throws", () => {
-  const circular = {};
-  circular.self = circular;
-  assert.doesNotThrow(() => inferPreview(circular));
-});
-
-test("finds a preview one level down in a result object", () => {
-  const out = previewResult({ palette: ["#0b1a31", "#3574dd"], count: 5 }, { slug: "color-palette" });
-  assert.equal(out.kind, "colors");
-});
-
-test("returns null when nothing in the result is renderable", () => {
-  assert.equal(previewResult({ count: 5, text: "hello" }, { slug: "x" }), null);
-  assert.equal(previewResult({ error: "nope" }, { slug: "x" }), null);
-});
-
-// ─── escaping ───────────────────────────────────────────────────────────────
-
-test("escapes text interpolated into svg", () => {
-  assert.equal(escapeXml(`<script>&"'`), "&lt;script&gt;&amp;&quot;&apos;");
-});
-
-test("a hex-like label cannot inject markup", () => {
-  // Colours are matched by a strict regex before reaching the renderer, so this
-  // documents that the escape is a second line of defence rather than the gate.
-  const hostile = '" onload="alert(1)';
-  assert.equal(inferPreview([hostile]), null);
-});