@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/unit/client/ref-endpoints.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Client-level URL routing tests for ref endpoints.
+ *
+ * These verify WordPressBlockClient builds the correct URLs and encodes
+ * refs properly. Uses an axios adapter to capture requests without hitting
+ * the network.
+ *
+ * Covers:
+ *   - updateBlockByRef → PATCH /posts/{id}/blocks/by-ref/{ref}
+ *   - deleteBlockByRef → DELETE /posts/{id}/blocks/by-ref/{ref}
+ *   - deleteBlockByRef count > 1 → query param
+ *   - deleteBlockByRef count <= 1 → no count param
+ *   - updateBlock (index path) → PATCH /posts/{id}/blocks/{index} (no by-ref)
+ *   - URL encoding for refs with reserved characters
+ *   - getPageBlocks persist_refs query param (omit / false / true)
+ *   - insertBlocks after_ref / before_ref in body
+ *   - mutateBlockTree ref in body (path absent)
+ *   - mutateBlockTree path in body (ref absent)
+ *   - mutateBlockTree before_ref in move body
+ *   - mutateBlockTree destination_ref in move body
+ *   - Input guards: empty ref, missing post_id, missing data
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import axios from 'axios';
+import { WordPressBlockClient } from '../../../client.js';
+
+type CapturedRequest = {
+  method: string;
+  url: string;
+  baseURL: string;
+  data?: unknown;
+  params?: Record<string, unknown>;
+};
+
+let captured: CapturedRequest[] = [];
+
+function safeJsonParse(s: string): unknown {
+  try { return JSON.parse(s); } catch { return s; }
+}
+
+const realCreate = axios.create.bind(axios);
+
+beforeEach(() => {
+  captured = [];
+  vi.spyOn(axios, 'create').mockImplementation((cfg: any = {}) => {
+    const inst = realCreate(cfg);
+    inst.defaults.adapter = ((config: any) => {
+      captured.push({
+        method: (config.method || 'get').toUpperCase(),
+        url: config.url || '',
+        baseURL: config.baseURL || '',
+        data: typeof config.data === 'string' ? safeJsonParse(config.data) : config.data,
+        params: config.params,
+      });
+      return Promise.resolve({
+        data: { success: true, blocks: [], inserted: [], removed: 0, before_revision_id: 1, revision_id: 2 },
+        status: 200, statusText: 'OK', headers: {}, config,
+      });
+    }) as any;
+    return inst;
+  });
+});
+
+function makeClient() {
+  return new WordPressBlockClient({
+    wordpress_url: 'https://example.test',
+    auth: { username: 'u', application_password: 'p p p p' },
+  });
+}
+
+// ── URL routing ───────────────────────────────────────────────────────────────
+
+describe('Client — ref endpoint URL routing', () => {
+  it('updateBlockByRef hits /blocks/by-ref/{ref} with PATCH', async () => {
+    const client = makeClient();
+    await client.updateBlockByRef(42, 'blk_a3f2c1q9', { attributes: { level: 3 } });
+    const req = captured.find((r) => r.url.includes('/blocks/by-ref/'));
+    expect(req).toBeDefined();
+    expect(req!.method).toBe('PATCH');
+    expect(req!.url).toBe('/posts/42/blocks/by-ref/blk_a3f2c1q9');
+    expect(req!.data).toEqual({ attributes: { level: 3 } });
+  });
+
+  it('deleteBlockByRef hits /blocks/by-ref/{ref} with DELETE', async () => {
+    const client = makeClient();
+    await client.deleteBlockByRef(42, 'blk_target');
+    const req = captured.find((r) => r.url.includes('/blocks/by-ref/'));
+    expect(req).toBeDefined();
+    expect(req!.method).toBe('DELETE');
+    expect(req!.url).toBe('/posts/42/blocks/by-ref/blk_target');
+  });
+
+  it('deleteBlockByRef forwards count > 1 as a query param', async () => {
+    const client = makeClient();
+    await client.deleteBlockByRef(42, 'blk_target', 3);
+    const req = captured.find((r) => r.url.includes('/blocks/by-ref/'));
+    expect(req!.params).toEqual({ count: '3' });
+  });
+
+  it('deleteBlockByRef does not include count when count <= 1', async () => {
+    const client = makeClient();
+    await client.deleteBlockByRef(42, 'blk_target', 1);
+    const req = captured.find((r) => r.url.includes('/blocks/by-ref/'));
+    expect(req!.params).toEqual({});
+  });
+
+  it('updateBlock (index path) hits /blocks/{index} — no by-ref crossover', async () => {
+    const client = makeClient();
+    await client.updateBlock(42, 7, { attributes: { foo: 'bar' } });
+    const req = captured.find((r) => r.method === 'PATCH');
+    expect(req!.url).toBe('/posts/42/blocks/7');
+    expect(req!.url).not.toContain('by-ref');
+  });
+
+  it('encodeURIComponent escapes refs with reserved characters', async () => {
+    const client = makeClient();
+    await client.updateBlockByRef(42, 'weird/ref#abc', { innerHTML: '<p>x</p>' });
+    const req = captured.find((r) => r.url.includes('/blocks/by-ref/'));
+    expect(req!.url).toBe('/posts/42/blocks/by-ref/weird%2Fref%23abc');
+  });
+});
+
+// ── persist_refs query param ──────────────────────────────────────────────────
+
+describe('Client — getPageBlocks persist_refs', () => {
+  it('omits persist_refs when not specified', async () => {
+    const client = makeClient();
+    await client.getPageBlocks(42);
+    const req = captured.find((r) => r.url === '/posts/42/blocks' && r.method === 'GET');
+    expect(req!.params).not.toHaveProperty('persist_refs');
+  });
+
+  it('sends persist_refs=false explicitly', async () => {
+    const client = makeClient();
+    await client.getPageBlocks(42, { persist_refs: false });
+    const req = captured.find((r) => r.url === '/posts/42/blocks' && r.method === 'GET');
+    expect(req!.params?.persist_refs).toBe('false');
+  });
+
+  it('sends persist_refs=true explicitly', async () => {
+    const client = makeClient();
+    await client.getPageBlocks(42, { persist_refs: true });
+    const req = captured.find((r) => r.url === '/posts/42/blocks' && r.method === 'GET');
+    expect(req!.params?.persist_refs).toBe('true');
+  });
+});
+
+// ── insertBlocks after_ref / before_ref body params ───────────────────────────
+
+describe('Client — insertBlocks ref body params', () => {
+  it('forwards after_ref in JSON body', async () => {
+    const client = makeClient();
+    await client.insertBlocks(42, {
+      after_ref: 'blk_anchor',
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/blocks');
+    expect((req!.data as Record<string, unknown>).after_ref).toBe('blk_anchor');
+  });
+
+  it('forwards before_ref in JSON body', async () => {
+    const client = makeClient();
+    await client.insertBlocks(42, {
+      before_ref: 'blk_anchor2',
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/blocks');
+    expect((req!.data as Record<string, unknown>).before_ref).toBe('blk_anchor2');
+  });
+});
+
+// ── mutateBlockTree ref body ──────────────────────────────────────────────────
+
+describe('Client — mutateBlockTree ref/path body', () => {
+  it('sends ref in body when provided (no path)', async () => {
+    const client = makeClient();
+    await client.mutateBlockTree(42, { op: 'update-attrs', ref: 'blk_target', attributes: { level: 3 } });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/mutate');
+    const body = req!.data as Record<string, unknown>;
+    expect(body.ref).toBe('blk_target');
+    expect(body).not.toHaveProperty('path');
+  });
+
+  it('sends path in body when provided (no ref)', async () => {
+    const client = makeClient();
+    await client.mutateBlockTree(42, { op: 'update-attrs', path: [0, 1], attributes: { level: 3 } });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/mutate');
+    const body = req!.data as Record<string, unknown>;
+    expect(body.path).toEqual([0, 1]);
+    expect(body).not.toHaveProperty('ref');
+  });
+
+  it('forwards before_ref in move body', async () => {
+    const client = makeClient();
+    await client.mutateBlockTree(42, { op: 'move', ref: 'blk_source', before_ref: 'blk_anchor' });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/mutate');
+    expect((req!.data as Record<string, unknown>).before_ref).toBe('blk_anchor');
+  });
+
+  it('forwards destination_ref in move body', async () => {
+    const client = makeClient();
+    await client.mutateBlockTree(42, { op: 'move', ref: 'blk_source', destination_ref: 'blk_parent' });
+    const req = captured.find((r) => r.method === 'POST' && r.url === '/posts/42/mutate');
+    expect((req!.data as Record<string, unknown>).destination_ref).toBe('blk_parent');
+  });
+});
+
+// ── Input guards ──────────────────────────────────────────────────────────────
+
+describe('Client — input guards', () => {
+  it('updateBlockByRef rejects empty ref', async () => {
+    const client = makeClient();
+    await expect(client.updateBlockByRef(42, '', { attributes: {} })).rejects.toThrow(/Ref is required/);
+  });
+
+  it('updateBlockByRef rejects missing post_id', async () => {
+    const client = makeClient();
+    await expect(client.updateBlockByRef(undefined as any, 'blk_x', { attributes: {} }))
+      .rejects.toThrow(/Post ID is required/);
+  });
+
+  it('updateBlockByRef requires attributes or innerHTML', async () => {
+    const client = makeClient();
+    await expect(client.updateBlockByRef(42, 'blk_x', {})).rejects.toThrow(/attributes or innerHTML/);
+  });
+
+  it('deleteBlockByRef rejects empty ref', async () => {
+    const client = makeClient();
+    await expect(client.deleteBlockByRef(42, '')).rejects.toThrow(/Ref is required/);
+  });
+});

package/src/__tests__/unit/enrichers/cbp-enricher.test.ts

@@ -0,0 +1,457 @@
+/**
+ * Unit tests for the Code Block Pro enricher (enrichBlock / enrichBlocks).
+ *
+ * The enricher is the one piece of non-trivial logic in the enrichers module:
+ * it generates codeHTML via shiki, infers languages, and updates innerHTML.
+ * All tests run against real shiki (no mocking) because the output format
+ * is stable and the runtime cost is acceptable for a unit suite.
+ *
+ * This file focuses on the CBP enricher. The registerBlockEnricher extension
+ * point is tested here too (it's part of the same module surface).
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';
+import {
+  inferLanguage,
+  enrichBlock,
+  enrichBlocks,
+  registerBlockEnricher,
+  shikiHighlight,
+  type BlockDef,
+} from '../../../enrichers.js';
+
+// Shiki's first getHighlighter() call loads every grammar + theme and can take
+// several seconds — especially on a loaded CI box. getHighlighter() memoises a
+// single module-level promise, so only the FIRST highlight pays that cost; the
+// rest reuse it. Warm it once here, with a generous hook timeout, so no
+// individual test inherits the cold-start latency and trips the default 5s
+// per-test timeout (the cause of an intermittent "generates codeHTML" flake).
+beforeAll(async () => {
+  await shikiHighlight('// warm', 'javascript');
+}, 30_000);
+
+// ── inferLanguage ─────────────────────────────────────────────────────────────
+
+describe('inferLanguage', () => {
+  it.each([
+    ['$var = "hello";',              'php'],
+    ['function myFunc() {}',         'php'],
+    ['.container { display: flex; }', 'css'],
+    ['const x = 1;',                 'javascript'],
+    ['let y = [];',                  'javascript'],
+    ['#!/bin/bash\necho hi',         'bash'],
+    ['{"key": "value"}',             'json'],
+    ['hello world plain text',       'plaintext'],
+  ])('infers %s → %s', (code, expected) => {
+    expect(inferLanguage(code)).toBe(expected);
+  });
+
+  it('returns plaintext for empty string', () => {
+    expect(inferLanguage('')).toBe('plaintext');
+  });
+});
+
+// ── Non-CBP pass-through ──────────────────────────────────────────────────────
+
+describe('enrichBlock — non-CBP pass-through', () => {
+  it('returns original block reference unchanged for core/paragraph', async () => {
+    const block: BlockDef = { name: 'core/paragraph', attributes: { content: 'Hello' } };
+    const result = await enrichBlock(block);
+    expect(result).toBe(block);
+  });
+
+  it('returns original block for any block without a registered enricher', async () => {
+    const block: BlockDef = { name: 'custom/unknown-widget', attributes: {} };
+    const result = await enrichBlock(block);
+    expect(result).toBe(block);
+  });
+
+  it('returns original block when CBP block has no code attribute', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { language: 'php' },
+    };
+    const result = await enrichBlock(block);
+    expect(result).toEqual(block);
+  });
+});
+
+// ── CBP enrichment — happy path ───────────────────────────────────────────────
+
+describe('enrichBlock — Code Block Pro', () => {
+  it('generates codeHTML attribute', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'const x = 1;', language: 'javascript' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.codeHTML).toBeDefined();
+    expect(result.attributes?.codeHTML as string).toContain('<pre class="shiki');
+  });
+
+  it('sets highestLineNumber to line count', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'line1\nline2\nline3', language: 'plaintext' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.highestLineNumber).toBe(3);
+  });
+
+  it('single-line code has highestLineNumber = 1', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'echo "hi";', language: 'php' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.highestLineNumber).toBe(1);
+  });
+
+  /**
+   * Fresh CBP blocks created via the API (e.g. edit_block_tree replace-block)
+   * arrive with no innerHTML. Pre-fix, the enricher only updated codeHTML and
+   * left innerHTML empty, which made the block render as a blank gap on the
+   * front-end. The enricher must build a minimal wrapper so the block is
+   * actually visible after save.
+   */
+  it('builds wrapper innerHTML when block has none', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'const a = 1;', language: 'javascript' },
+    };
+    const result = await enrichBlock(block);
+    expect(typeof result.innerHTML).toBe('string');
+    expect(result.innerHTML).toContain('wp-block-kevinbatdorf-code-block-pro');
+    expect(result.innerHTML).toContain('<pre class="shiki');
+  });
+
+  it('inlines wrapper style from font / colour attributes', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: {
+        code: 'const a = 1;',
+        language: 'javascript',
+        fontFamily: 'Code-Pro-JetBrains-Mono',
+        fontSize: '1rem',
+        lineHeight: '1.25rem',
+        bgColor: '#0F2B62',
+        textColor: '#d8dee9ff',
+      },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).toContain('font-family:Code-Pro-JetBrains-Mono');
+    expect(result.innerHTML).toContain('font-size:1rem');
+    expect(result.innerHTML).toContain('background-color:#0F2B62');
+    expect(result.innerHTML).toContain('color:#d8dee9ff');
+  });
+
+  it('includes copy-textarea when copyButton is enabled', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'const a = 1;', language: 'javascript', copyButton: true },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).toMatch(/<textarea[^>]*>const a = 1;<\/textarea>/);
+  });
+
+  it('omits copy-textarea when copyButton is false', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'const a = 1;', language: 'javascript', copyButton: false },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).not.toContain('<textarea');
+  });
+
+  /**
+   * Regression: a literal `</textarea>` in the source code would otherwise
+   * close the copy-button <textarea> early and corrupt the wrapper. The
+   * enricher must HTML-encode `<` (and `&`, `>`) in the textarea content so
+   * the closing tag in the code is rendered as inert text, not parsed as a
+   * tag boundary.
+   */
+  it('escapes closing textarea in code payload', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: "const x = '</textarea>';", language: 'javascript', copyButton: true },
+    };
+    const result = await enrichBlock(block);
+    // Isolate just the copy-button <textarea> contents — the codeHTML <pre>
+    // above it legitimately escapes its own markup separately.
+    const match = result.innerHTML!.match(/<textarea[^>]*>([\s\S]*?)<\/textarea>/);
+    expect(match).not.toBeNull();
+    const textareaContent = match![1];
+    expect(textareaContent).not.toContain('</textarea>');
+    expect(textareaContent).toContain('&lt;/textarea&gt;');
+  });
+
+  /**
+   * Wrapper-style values come straight from caller-supplied attributes. A
+   * value containing `"` (whether malicious or just a quoted font-name like
+   * `"Helvetica Neue"`) used to break out of the style="" attribute and
+   * either corrupt the markup or inject active content. The enricher now
+   * HTML-encodes attribute values before interpolation.
+   */
+  it('escapes double-quotes in style attribute values', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: {
+        code: 'const a = 1;',
+        language: 'javascript',
+        fontFamily: 'Arial" onerror="alert(1)',
+      },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).not.toContain('onerror="alert(1)');
+    expect(result.innerHTML).toContain('&quot;');
+  });
+
+  it('escapes special characters in className', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: {
+        code: 'const a = 1;',
+        language: 'javascript',
+        className: 'safe" onclick="alert(1)',
+      },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).not.toContain('onclick="alert(1)');
+    // The literal double-quote inside the className value must be encoded
+    // rather than rendered raw, regardless of where the escape happens.
+    expect(result.innerHTML).toMatch(/class="wp-block-kevinbatdorf-code-block-pro[^"]*"/);
+  });
+
+  it('escapes ampersands and angle brackets in style values', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: {
+        code: 'const a = 1;',
+        language: 'javascript',
+        bgColor: '#fff & <script>',
+      },
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).not.toContain('<script>');
+    expect(result.innerHTML).toContain('&amp;');
+    expect(result.innerHTML).toContain('&lt;script&gt;');
+  });
+
+  it('keeps explicit php language without inference', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: '$x = 1;', language: 'php' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('php');
+  });
+});
+
+// ── CBP enrichment — language inference ──────────────────────────────────────
+
+describe('enrichBlock — language inference', () => {
+  /**
+   * Explicit `language: 'plaintext'` is the caller saying "render this as plain
+   * text, no syntax highlighting." Pre-fix the enricher treated 'plaintext' as
+   * "no preference, infer" — so a chat prompt containing "from … from …" was
+   * detected as SQL and rendered with mis-coloured English words. The contract
+   * now is: explicit 'plaintext'/'text'/'plain'/'txt'/'none' is respected;
+   * inference only runs when the attribute is missing, empty, or 'auto'.
+   */
+  it('respects explicit plaintext language without inference', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: '.hero { color: red; }', language: 'plaintext' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('plaintext');
+  });
+
+  it.each(['text', 'plain', 'txt', 'none'])(
+    'respects explicit %s as plaintext alias',
+    async (alias) => {
+      const block: BlockDef = {
+        name: 'kevinbatdorf/code-block-pro',
+        attributes: { code: '.hero { color: red; }', language: alias },
+      };
+      const result = await enrichBlock(block);
+      expect(result.attributes?.language).toBe('plaintext');
+    },
+  );
+
+  it('infers css when language attribute is missing', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: '.hero { color: red; }' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('css');
+  });
+
+  it('infers css when language is "auto"', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: '.hero { color: red; }', language: 'auto' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('css');
+  });
+
+  /**
+   * Regression: chat prompts pasted into a CBP block via the API used to detect
+   * as SQL because inferLanguage's SQL heuristic fires on the word "from" — and
+   * "from" appears twice in the canonical "Set up Block MCP from … from me"
+   * prompt. With explicit plaintext respected, the prompt renders correctly.
+   */
+  it('does not mis-detect English prose as SQL when caller passes plaintext', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: {
+        code: 'Set up Block MCP from https://example.com on my computer. Walk me through anything you need from me — WordPress site URL, username, and Application Password.',
+        language: 'plaintext',
+      },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('plaintext');
+    // The generated codeHTML must not contain SQL keyword tokens for the
+    // English words that previously got mis-coloured.
+    expect(result.attributes?.codeHTML).not.toContain('shiki-token-keyword');
+  });
+
+  it('does not override non-plaintext language with inference', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: '.hero { color: red; }', language: 'javascript' },
+    };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.language).toBe('javascript');
+  });
+});
+
+// ── CBP enrichment — innerHTML update ────────────────────────────────────────
+
+describe('enrichBlock — innerHTML update', () => {
+  it('replaces the <pre class="shiki"> portion in existing innerHTML', async () => {
+    const code = 'const a = 1;';
+    const oldPre = '<pre class="shiki old-theme"><code>old</code></pre>';
+    const innerHTML = `<div class="cbp-wrap">${oldPre}<textarea>${code}</textarea></div>`;
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code, language: 'javascript' },
+      innerHTML,
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).toBeDefined();
+    expect(result.innerHTML).toContain('<pre class="shiki');
+    expect(result.innerHTML).not.toContain('old-theme');
+  });
+
+  it('updates <textarea> content with current code', async () => {
+    const code = 'const updated = true;';
+    const innerHTML = `<div><pre class="shiki old"><code></code></pre><textarea>old code</textarea></div>`;
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code, language: 'javascript' },
+      innerHTML,
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).toContain(`<textarea>${code}</textarea>`);
+    expect(result.innerHTML).not.toContain('old code');
+  });
+});
+
+// ── CBP enrichment — no-op (codeHTML already current) ────────────────────────
+
+describe('enrichBlock — no-op when already enriched', () => {
+  /**
+   * A fully-enriched CBP block has both `codeHTML` (attribute) and `innerHTML`
+   * (the rendered widget). Passing such a block through the enricher again
+   * must be a no-op — same object reference returned. If only one side is
+   * populated, the enricher rebuilds the missing piece so first-pass blocks
+   * created via the API (no innerHTML) still render correctly.
+   */
+  it('returns original block reference when codeHTML and innerHTML are already current', async () => {
+    const code = 'const x = 1;';
+    const firstPass = await enrichBlock({
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code, language: 'javascript' },
+    });
+    const codeHTML = firstPass.attributes?.codeHTML as string;
+    const innerHTML = firstPass.innerHTML as string;
+
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code, language: 'javascript', codeHTML },
+      innerHTML,
+    };
+    const result = await enrichBlock(block);
+    expect(result).toBe(block);
+  });
+});
+
+// ── enrichBlocks ──────────────────────────────────────────────────────────────
+
+describe('enrichBlocks', () => {
+  it('returns empty array for empty input', async () => {
+    expect(await enrichBlocks([])).toEqual([]);
+  });
+
+  it('enriches CBP blocks and passes non-CBP blocks through unchanged', async () => {
+    const blocks: BlockDef[] = [
+      { name: 'core/paragraph', attributes: { content: 'Hello' } },
+      { name: 'kevinbatdorf/code-block-pro', attributes: { code: 'const x = 1;', language: 'javascript' } },
+    ];
+    const results = await enrichBlocks(blocks);
+    expect(results).toHaveLength(2);
+    expect(results[0]).toBe(blocks[0]);
+    expect(results[1].attributes?.codeHTML).toBeDefined();
+  });
+
+  it('processes all CBP blocks in the array', async () => {
+    const blocks: BlockDef[] = [
+      { name: 'kevinbatdorf/code-block-pro', attributes: { code: 'const a = 1;', language: 'javascript' } },
+      { name: 'kevinbatdorf/code-block-pro', attributes: { code: '$x = true;', language: 'php' } },
+    ];
+    const results = await enrichBlocks(blocks);
+    expect(results[0].attributes?.codeHTML).toBeDefined();
+    expect(results[1].attributes?.codeHTML).toBeDefined();
+  });
+});
+
+// ── registerBlockEnricher ─────────────────────────────────────────────────────
+
+describe('registerBlockEnricher', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('runs a custom enricher for its registered block name', async () => {
+    const customFn = vi.fn(async (block: BlockDef) => ({
+      ...block,
+      attributes: { ...block.attributes, custom: true },
+    }));
+    registerBlockEnricher('test/custom-enricher-reg', customFn);
+
+    const block: BlockDef = { name: 'test/custom-enricher-reg', attributes: { foo: 'bar' } };
+    await enrichBlock(block);
+    expect(customFn).toHaveBeenCalledWith(block);
+  });
+
+  it('applies the custom enricher result', async () => {
+    registerBlockEnricher('test/custom-enricher-apply', async (block: BlockDef) => ({
+      ...block,
+      attributes: { ...block.attributes, computed: 'yes' },
+    }));
+
+    const block: BlockDef = { name: 'test/custom-enricher-apply', attributes: { original: true } };
+    const result = await enrichBlock(block);
+    expect(result.attributes?.computed).toBe('yes');
+    expect(result.attributes?.original).toBe(true);
+  });
+
+  it('returns null (no-op) from enricher passes original block through', async () => {
+    registerBlockEnricher('test/noop-enricher', async () => null);
+
+    const block: BlockDef = { name: 'test/noop-enricher', attributes: {} };
+    const result = await enrichBlock(block);
+    expect(result).toBe(block);
+  });
+});