@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/integration/dual-storage.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Integration: dual-storage enforcement (yoast/faq-block)
+ *
+ * A "dual" block (e.g. yoast/faq-block, yoast/how-to-block) requires BOTH
+ * `attributes` AND `innerHTML` on every write. Sending only `attributes`
+ * must return HTTP 400 with code `dual_storage_requires_both`.
+ *
+ * This test:
+ *   1. Calls list_block_types to detect whether Yoast is installed.
+ *      If the `yoast/faq-block` type is absent, the test is skipped.
+ *   2. Creates a throwaway post with a yoast/faq-block.
+ *   3. Sends an update with only `attributes` (no innerHTML).
+ *   4. Asserts the 400 / dual_storage_requires_both response.
+ *
+ * If dual-storage scanning has not yet been run on the site (the scan builds
+ * the classification map), the plugin may not know that yoast/faq-block is
+ * `dual` and the write could succeed with 200 instead of 400. In that case
+ * we emit a console.log and allow the test to pass — the enforcement only
+ * fires after a storage-mode scan has been run.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { makeLiveClient, skipUnlessLive, withTestPost, LIVE_ENV } from './setup.js';
+import axios from 'axios';
+
+const skip = skipUnlessLive();
+
+describe.skipIf(skip)('dual-storage enforcement (integration)', () => {
+  let yoastInstalled = false;
+  let dualBlockName: string | null = null;
+
+  beforeAll(async () => {
+    if (skip) return;
+    try {
+      const client = makeLiveClient();
+      const result = await client.getBlockTypes({ namespace: 'yoast' });
+      const candidates = result.block_types.filter(
+        (bt) =>
+          bt.name === 'yoast/faq-block' ||
+          bt.name === 'yoast/how-to-block' ||
+          bt.storage_mode === 'dual'
+      );
+      if (candidates.length > 0) {
+        yoastInstalled = true;
+        dualBlockName = candidates[0].name;
+      }
+    } catch {
+      yoastInstalled = false;
+    }
+  });
+
+  it('update with only attributes on a dual-storage block returns 400 or 200 (requires scan)', async () => {
+    if (!yoastInstalled || !dualBlockName) {
+      console.log('[integration] No dual-storage block found (Yoast not installed or no dual blocks) — skipping');
+      return;
+    }
+
+    const client = makeLiveClient();
+
+    const faqInnerHtml = '<div class="schema-faq"><div class="schema-faq-section"><strong class="schema-faq-question">Test Q</strong><p class="schema-faq-answer">Test A</p></div></div>';
+    const faqAttributes = {
+      questions: [{ id: 'faq-q1', question: 'Test Q', answer: 'Test A', jsonAnswer: 'Test A', jsonQuestion: 'Test Q' }],
+    };
+
+    await withTestPost(client, async (postId) => {
+      // Insert the dual-storage block.
+      const inserted = await client.insertBlocks(postId, {
+        after: 'start',
+        blocks: [
+          {
+            name: dualBlockName!,
+            attributes: faqAttributes,
+            innerHTML: faqInnerHtml,
+          },
+        ],
+      });
+      expect(inserted.success).toBe(true);
+      const blockIndex = inserted.inserted[0]?.index;
+      expect(blockIndex).toBeGreaterThanOrEqual(0);
+
+      // Try to update with ONLY attributes — dual enforcement should reject it.
+      const credentials = Buffer.from(
+        `${LIVE_ENV.user}:${LIVE_ENV.password}`
+      ).toString('base64');
+      const url = `${LIVE_ENV.url.replace(/\/+$/, '')}/wp-json/gk-block-api/v1/posts/${postId}/blocks/${blockIndex}`;
+
+      const response = await axios.patch(
+        url,
+        { attributes: faqAttributes },
+        {
+          headers: {
+            Authorization: `Basic ${credentials}`,
+            'Content-Type': 'application/json',
+          },
+          timeout: 15_000,
+          validateStatus: () => true,
+        }
+      );
+
+      if (response.status === 400) {
+        // Dual-storage enforcement is active — verify the error code.
+        const body = response.data as Record<string, unknown>;
+        expect(body.code).toBe('dual_storage_requires_both');
+        expect(body.message).toBeTruthy();
+      } else if (response.status === 200) {
+        // The plugin returned a 200 because the storage-mode scan classifying
+        // this block as `dual` had not been run on this site. Silently
+        // logging-and-continuing turns the test green even though the
+        // enforcement path was never exercised — the same outcome a real
+        // regression that broke enforcement would produce. Fail loudly so
+        // CI surfaces the missing precondition instead of papering over it.
+        throw new Error(
+          `[integration] dual-storage not enforced for ${dualBlockName} ` +
+            '— call scan_storage_modes to classify the block as dual, then re-run this suite. ' +
+            'The 200 response means the precondition for this test is not met, not that the test passed.'
+        );
+      } else {
+        // Any other status is unexpected.
+        throw new Error(`Unexpected status ${response.status} from dual-storage update`);
+      }
+    });
+  }, 45_000);
+
+  it('update with both attributes AND innerHTML on a dual block succeeds', async () => {
+    if (!yoastInstalled || !dualBlockName) {
+      console.log('[integration] No dual-storage block found — skipping');
+      return;
+    }
+
+    const client = makeLiveClient();
+
+    const faqInnerHtml = '<div class="schema-faq"><div class="schema-faq-section"><strong class="schema-faq-question">Test Q</strong><p class="schema-faq-answer">Test A</p></div></div>';
+    const faqAttributes = {
+      questions: [{ id: 'faq-q1', question: 'Test Q', answer: 'Test A', jsonAnswer: 'Test A', jsonQuestion: 'Test Q' }],
+    };
+
+    await withTestPost(client, async (postId) => {
+      const inserted = await client.insertBlocks(postId, {
+        after: 'start',
+        blocks: [{ name: dualBlockName!, attributes: faqAttributes, innerHTML: faqInnerHtml }],
+      });
+      const blockIndex = inserted.inserted[0]?.index;
+      expect(blockIndex).toBeGreaterThanOrEqual(0);
+
+      // Update with BOTH attributes AND innerHTML — must always succeed.
+      const updatedHtml = '<div class="schema-faq"><div class="schema-faq-section"><strong class="schema-faq-question">Updated Q</strong><p class="schema-faq-answer">Test A</p></div></div>';
+      const result = await client.updateBlock(postId, blockIndex, {
+        attributes: {
+          questions: [{ id: 'faq-q1', question: 'Updated Q', answer: 'Test A', jsonAnswer: 'Test A', jsonQuestion: 'Updated Q' }],
+        },
+        innerHTML: updatedHtml,
+      });
+      expect(result.success).toBe(true);
+    });
+  }, 45_000);
+});

package/src/__tests__/integration/error-envelopes.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Integration: real REST error envelope shapes
+ *
+ * The unit tests in src/__tests__/error-translator.test.ts verify that our
+ * TypeScript translation layer maps codes correctly. THIS file verifies that
+ * the live PHP plugin actually returns the error codes and HTTP statuses we
+ * claim — i.e., our documented constants match what's on the wire.
+ *
+ * We sample 8 representative codes from the documented 49 and trigger each
+ * one deliberately against a live post:
+ *
+ *   1. rest_no_route     — hit a non-existent route
+ *   2. post not found    — reference a post that doesn't exist (403 or 404
+ *                          depending on whether the permission check or the
+ *                          lookup check fires first)
+ *   3. rest_forbidden    — write with wrong credentials (401 or 403)
+ *   4. invalid_path      — mutate with an out-of-range path
+ *   5. legacy_block      — insert a ugb/text block (always hard-rejected)
+ *   6. invalid_ref       — updateBlockByRef with a made-up ref
+ *                          (skipped when by-ref route is absent)
+ *   7. invalid_block     — insert a non-registered block name
+ *   8. cleanup           — verify the shared post is trashed correctly
+ *
+ * Each assertion checks:
+ *   - HTTP status is in the expected range for the error class
+ *   - Response body has a `code` field (machine-readable)
+ *   - Response body has a `message` string (non-empty)
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import axios from 'axios';
+import { makeLiveClient, skipUnlessLive, LIVE_ENV, hasRoute } from './setup.js';
+
+const skip = skipUnlessLive();
+
+/** Raw request against the REST API without the MCP client's retry logic. */
+async function rawRequest(
+  method: 'get' | 'post' | 'patch' | 'delete',
+  path: string,
+  body?: unknown,
+  credentials?: string
+): Promise<{ status: number; code?: string; message?: string; data?: unknown }> {
+  const creds =
+    credentials ??
+    Buffer.from(`${LIVE_ENV.user}:${LIVE_ENV.password}`).toString('base64');
+  const base = LIVE_ENV.url.replace(/\/+$/, '');
+  const url = `${base}/wp-json/gk-block-api/v1${path}`;
+
+  const response = await axios.request({
+    method,
+    url,
+    data: body,
+    headers: {
+      Authorization: `Basic ${creds}`,
+      'Content-Type': 'application/json',
+    },
+    timeout: 15_000,
+    validateStatus: () => true,
+  });
+
+  const b = response.data as Record<string, unknown> | undefined;
+  return {
+    status: response.status,
+    code: typeof b?.code === 'string' ? b.code : undefined,
+    message: typeof b?.message === 'string' ? b.message : undefined,
+    data: b?.data,
+  };
+}
+
+describe.skipIf(skip)('real REST error envelopes (integration)', () => {
+  // We need a live post ID for several tests.
+  let livePostId: number;
+  let liveHeadingIndex: number;
+
+  beforeAll(async () => {
+    if (skip) return;
+    const client = makeLiveClient();
+    const created = await client.createPost({
+      title: `[integration-test] error-envelopes ${Date.now()}`,
+      status: 'draft',
+      blocks: [
+        {
+          name: 'core/heading',
+          attributes: { level: 2, content: 'Error envelope test post' },
+          innerHTML: '<h2 class="wp-block-heading">Error envelope test post</h2>',
+        },
+      ],
+    });
+    livePostId = created.id;
+
+    const blocks = await client.getPageBlocks(livePostId);
+    const h = blocks.blocks.find((b) => b.name === 'core/heading');
+    liveHeadingIndex = h?.index ?? 0;
+  });
+
+  it('rest_no_route: GET to a non-existent route returns 404 + rest_no_route', async () => {
+    const result = await rawRequest('get', '/nonexistent-route-xyz');
+    expect(result.status).toBe(404);
+    expect(result.code).toBe('rest_no_route');
+    expect(result.message).toBeTruthy();
+  });
+
+  it('auth gate fires before post lookup for non-existent post IDs (403 or 404)', async () => {
+    // Using a post ID that doesn't exist (999999999). Depending on whether the
+    // permission check or the post lookup runs first, we get 403 or 404.
+    // Both are valid — we just confirm a structured error envelope is returned.
+    const result = await rawRequest('get', '/posts/999999999/blocks');
+    expect([403, 404]).toContain(result.status);
+    expect(result.message).toBeTruthy();
+    // Some plugin versions return a code, others return a status-only envelope.
+    if (result.code) {
+      expect(typeof result.code).toBe('string');
+    }
+  });
+
+  it('rest_forbidden: write with bad credentials returns 401 or 403', async () => {
+    const badCreds = Buffer.from('nobody:wrongpassword').toString('base64');
+    const result = await rawRequest(
+      'patch',
+      `/posts/${livePostId}/blocks/${liveHeadingIndex}`,
+      { attributes: { content: 'forbidden write' } },
+      badCreds
+    );
+    expect([401, 403]).toContain(result.status);
+    expect(result.message).toBeTruthy();
+  });
+
+  it('invalid_path: mutate with out-of-range path returns 400 + path error code', async () => {
+    const result = await rawRequest('post', `/posts/${livePostId}/mutate`, {
+      op: 'update-attrs',
+      path: [999, 999, 999],
+      attributes: { content: 'never land' },
+    });
+    expect(result.status).toBe(400);
+    expect(['invalid_path', 'path_not_found', 'path_out_of_bounds']).toContain(result.code);
+    expect(result.message).toBeTruthy();
+  });
+
+  it('legacy_block: inserting a ugb/text block returns 400 + legacy_block', async () => {
+    const result = await rawRequest('post', `/posts/${livePostId}/blocks`, {
+      after: 0,
+      blocks: [{ name: 'ugb/text', attributes: {}, innerHTML: '<div>legacy</div>' }],
+    });
+    expect(result.status).toBe(400);
+    expect(result.code).toBe('legacy_block');
+    expect(result.message).toBeTruthy();
+  });
+
+  it('invalid_ref: updateBlockByRef with a made-up ref returns a structured error (when route exists)', async () => {
+    const byRefExists = await hasRoute('by-ref');
+    if (!byRefExists) {
+      console.log('[integration] by-ref route not present — skipping invalid_ref test');
+      return;
+    }
+
+    const result = await rawRequest(
+      'patch',
+      `/posts/${livePostId}/blocks/by-ref/blk_00000000`,
+      { attributes: { content: 'no such ref' } }
+    );
+    expect([400, 404]).toContain(result.status);
+    // The plugin returns `ref_stale` or `invalid_ref` depending on version.
+    if (result.code) {
+      expect(result.code).toMatch(/ref|not_found/i);
+    }
+    expect(result.message).toBeTruthy();
+  });
+
+  it('invalid_block: inserting a non-registered block name returns 400', async () => {
+    const result = await rawRequest('post', `/posts/${livePostId}/blocks`, {
+      after: 0,
+      blocks: [{ name: 'nonexistent/totally-fake-block', attributes: {}, innerHTML: '<div>x</div>' }],
+    });
+    expect(result.status).toBe(400);
+    expect(result.message).toBeTruthy();
+  });
+
+  it('inner_html_required: inserting a paragraph with content attr but no innerHTML returns 400', async () => {
+    // Regression for the "Block contains unexpected or invalid content" bug:
+    // attribute-only inserts of a source-bound block (core/paragraph) used
+    // to serialize as a self-closing comment; Gutenberg flagged the block on
+    // reload because the parsed DOM ("") disagreed with the saved attribute.
+    // The plugin now rejects up front with `inner_html_required` and lists
+    // the offending attribute names in `data.source_bound_attributes`.
+    const result = await rawRequest('post', `/posts/${livePostId}/blocks`, {
+      after: 0,
+      blocks: [{ name: 'core/paragraph', attributes: { content: 'should reject' } }],
+    });
+    expect(result.status).toBe(400);
+    expect(result.code).toBe('inner_html_required');
+    expect(result.message).toMatch(/innerHTML/i);
+    const data = result.data as any;
+    expect(data?.block).toBe('core/paragraph');
+    expect(data?.source_bound_attributes).toContain('content');
+  });
+
+  it('inner_html_required: providing innerHTML alongside attributes is accepted (round-trip)', async () => {
+    // Negative-space check: the rejection above must not become a blanket
+    // "no attributes-only" — the canonical form (attrs + innerHTML) still
+    // succeeds, and the saved post_content carries non-self-closing markup
+    // that re-parses with the same content the agent sent.
+    const insertResult = await rawRequest('post', `/posts/${livePostId}/blocks`, {
+      after: 0,
+      blocks: [
+        {
+          name: 'core/paragraph',
+          attributes: { content: 'integration round-trip' },
+          innerHTML: '<p>integration round-trip</p>',
+        },
+      ],
+    });
+    // POST returns 201 Created on success.
+    expect([200, 201]).toContain(insertResult.status);
+
+    // Read the post back through the typed MCP client so we get the
+    // canonical { blocks: [...] } shape regardless of REST wrapping.
+    const client = makeLiveClient();
+    const blocks = await client.getPageBlocks(livePostId);
+    const hit = blocks.blocks.find(
+      (b: any) => b.name === 'core/paragraph' && (b.innerHTML ?? '').includes('integration round-trip')
+    );
+    expect(hit).toBeTruthy();
+    expect(hit!.innerHTML).toContain('<p>');
+    expect(hit!.innerHTML).toContain('</p>');
+  });
+
+  // Move cleanup to afterAll so the shared post is trashed even if any of
+  // the assertions above fail. As a regular `it()` it would skip on failure
+  // and leak the test post into the live site, polluting later runs.
+  afterAll(async () => {
+    if (!livePostId) {
+      return;
+    }
+    const client = makeLiveClient();
+    const result = await client.updatePost(livePostId, { status: 'trash' });
+    expect(result.success).toBe(true);
+  });
+});

package/src/__tests__/integration/global-setup.ts

@@ -0,0 +1,17 @@
+/**
+ * Vitest globalSetup for integration tests.
+ *
+ * Vitest does NOT support a top-level `globalTeardown` config key — teardown
+ * must be returned from the globalSetup function. The default-exported
+ * function below runs once before the suite (no setup work yet) and returns
+ * a teardown that sweeps any throwaway posts that leaked due to unexpected
+ * process exit, test timeouts, or beforeAll failures. Only fires when env
+ * vars are set (cleanupTestPosts() is a no-op otherwise).
+ */
+import { cleanupTestPosts } from './setup.js';
+
+export default function setup(): () => Promise<void> {
+  return async function teardown(): Promise<void> {
+    await cleanupTestPosts();
+  };
+}

package/src/__tests__/integration/rate-limit.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Integration: rate-limit enforcement
+ *
+ * The plugin allows 10 writes/minute per post (sliding 60-second window).
+ * Firing 11 sequential writes to the same post must cause the 11th to return
+ * HTTP 429 with code `rate_limit_exceeded`.
+ *
+ * Determinism notes:
+ *   - We drive real writes (not fake timers); the plugin's transient-based
+ *     counter is authoritative.
+ *   - We do NOT test bucket reset (that would require a real 60-second sleep).
+ *     We verify only that the limit fires.
+ *   - To avoid the retry logic in WordPressBlockClient absorbing the 429
+ *     (the client *does* retry 429s as per isRetryable()), we fire raw axios
+ *     calls for the overflow write so we see the raw 429.
+ *
+ * Cleanup: the throwaway post is trashed in teardown regardless of failure.
+ * The rate-limit transient expires on its own within 60 seconds.
+ */
+
+import { describe, it, expect } from 'vitest';
+import axios from 'axios';
+import { makeLiveClient, skipUnlessLive, withTestPost, LIVE_ENV } from './setup.js';
+
+const skip = skipUnlessLive();
+
+const RATE_LIMIT = 10; // must match Block_CRUD::WRITE_LIMIT in the plugin
+
+/** Fire a raw PATCH without the MCP client's retry logic. */
+async function rawPatch(
+  postId: number,
+  blockIndex: number,
+  suffix: number
+): Promise<{ status: number; code?: string }> {
+  const credentials = Buffer.from(
+    `${LIVE_ENV.user}:${LIVE_ENV.password}`
+  ).toString('base64');
+
+  const url = `${LIVE_ENV.url.replace(/\/+$/, '')}/wp-json/gk-block-api/v1/posts/${postId}/blocks/${blockIndex}`;
+
+  const response = await axios.patch(
+    url,
+    {
+      attributes: { content: `Rate-limit write ${suffix}`, level: 2 },
+      innerHTML: `<h2 class="wp-block-heading">Rate-limit write ${suffix}</h2>`,
+    },
+    {
+      headers: {
+        Authorization: `Basic ${credentials}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 15_000,
+      validateStatus: () => true,
+    }
+  );
+
+  const body = response.data as Record<string, unknown> | undefined;
+  return {
+    status: response.status,
+    code: typeof body?.code === 'string' ? body.code : undefined,
+  };
+}
+
+describe.skipIf(skip)('rate-limit enforcement (integration)', () => {
+  it(`fires rate_limit_exceeded (429) after ${RATE_LIMIT} writes in 60 seconds`, async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+      const headingIndex = heading!.index;
+
+      // Fire RATE_LIMIT writes via raw axios (no retry layer).
+      // We expect all of them to succeed (200).
+      for (let i = 1; i <= RATE_LIMIT; i++) {
+        const result = await rawPatch(postId, headingIndex, i);
+        expect(result.status, `Write #${i} should succeed`).toBe(200);
+      }
+
+      // The (RATE_LIMIT + 1)-th write must hit the cap.
+      const overflow = await rawPatch(postId, headingIndex, RATE_LIMIT + 1);
+      expect(overflow.status).toBe(429);
+      expect(overflow.code).toBe('rate_limit_exceeded');
+    });
+  // Allow generous time: RATE_LIMIT sequential network round-trips + margin.
+  }, 120_000);
+});

package/src/__tests__/integration/read-edit-read.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Integration: read → edit → read verification (happy path)
+ *
+ * Creates a throwaway post, reads its blocks, mutates the heading, reads
+ * again, and asserts that:
+ *   - The write succeeds (200, success: true).
+ *   - revision_id advances after the write.
+ *   - The heading content attribute reflects the new value on re-read.
+ *   - If the plugin assigns gk_refs, the ref is stable across the edit.
+ *   - If the plugin returns a `saved` snapshot, it matches the re-read.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { makeLiveClient, skipUnlessLive, withTestPost, hasRoute } from './setup.js';
+
+const skip = skipUnlessLive();
+
+describe.skipIf(skip)('read → edit → read (integration)', () => {
+  it('updates a heading block and verifies the change persists via get_page_blocks', async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      // ── Step 1: initial read ───────────────────────────────────────
+      const before = await client.getPageBlocks(postId);
+      expect(before.blocks.length).toBeGreaterThanOrEqual(1);
+
+      const heading = before.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+
+      const headingIndex = heading!.index;
+      const headingRef = heading!.ref; // may be undefined on older plugin builds
+
+      // ── Step 2: mutate the heading ─────────────────────────────────
+      const updated = await client.updateBlock(postId, headingIndex, {
+        attributes: { content: 'Updated by integration test', level: 2 },
+        innerHTML: '<h2 class="wp-block-heading">Updated by integration test</h2>',
+      });
+
+      expect(updated.success).toBe(true);
+      expect(updated.revision_id).toBeGreaterThan(0);
+      // revision_id must advance IF a real save happened (before_revision_id = 0
+      // on posts with no prior revisions is valid on some WP configs).
+      if (updated.before_revision_id > 0) {
+        expect(updated.revision_id).toBeGreaterThan(updated.before_revision_id);
+      }
+
+      // If this plugin build returns a `saved` snapshot, validate it.
+      if (updated.saved) {
+        expect(updated.saved.inner_html).toContain('Updated by integration test');
+        expect(updated.saved.block_name).toBe('core/heading');
+        // Ref stability: if a ref was present before and the plugin returns
+        // saved.ref, they must match.
+        if (headingRef && updated.saved.ref) {
+          expect(updated.saved.ref).toBe(headingRef);
+        }
+      }
+
+      // ── Step 3: re-read and verify the change landed on disk ───────
+      const after = await client.getPageBlocks(postId);
+      const updatedHeading = after.blocks.find((b) => b.name === 'core/heading');
+      expect(updatedHeading).toBeDefined();
+      // Content attribute must match what we wrote.
+      expect(updatedHeading!.attributes.content).toBe('Updated by integration test');
+
+      // If refs are present on both the before and after blocks, they must match.
+      if (headingRef && updatedHeading!.ref) {
+        expect(updatedHeading!.ref).toBe(headingRef);
+      }
+
+      // If the write response carried a saved snapshot, the flat_index must
+      // point at the same block we see in the re-read.
+      if (updated.saved) {
+        expect(updatedHeading!.index).toBe(updated.saved.flat_index);
+      }
+    });
+  }, 30_000);
+
+  it('get_block(ref) returns current snapshot for a block that has a ref', async () => {
+    // Only run this sub-test when the single-block fetch route exists.
+    // The single-block fetch endpoint is /posts/{id}/block (no trailing 's').
+    // Use the anchored regex form to avoid matching /posts/{id}/blocks.
+    const singleBlockRouteExists = await hasRoute('/block$');
+    if (!singleBlockRouteExists) {
+      console.log('[integration] /block single-fetch route not present — skipping get_block sub-test');
+      return;
+    }
+
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      // Read to get the heading.
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+
+      // Write an update.
+      await client.updateBlock(postId, heading!.index, {
+        attributes: { content: 'Ref-verified heading', level: 2 },
+        innerHTML: '<h2 class="wp-block-heading">Ref-verified heading</h2>',
+      });
+
+      // Use get_block by flat index (always available even without ref support).
+      const single = await client.getBlock(postId, { flatIndex: heading!.index });
+      expect(single.success).toBe(true);
+      expect(single.saved.inner_html).toContain('Ref-verified heading');
+    });
+  }, 30_000);
+
+  it('get_block(ref) works when the block has a stable ref', async () => {
+    const singleBlockRouteExists = await hasRoute('/block$');
+    if (!singleBlockRouteExists) {
+      console.log('[integration] /block single-fetch route not present — skipping ref sub-test');
+      return;
+    }
+
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+
+      // If this plugin version assigns refs, verify ref-based fetch.
+      if (!heading!.ref) {
+        console.log('[integration] Block has no ref on this plugin build — skipping ref fetch');
+        return;
+      }
+
+      const ref = heading!.ref;
+      await client.updateBlockByRef(postId, ref, {
+        attributes: { content: 'Ref-verified heading', level: 2 },
+        innerHTML: '<h2 class="wp-block-heading">Ref-verified heading</h2>',
+      });
+
+      const single = await client.getBlock(postId, { ref });
+      expect(single.success).toBe(true);
+      expect(single.saved.inner_html).toContain('Ref-verified heading');
+      expect(single.saved.ref).toBe(ref);
+    });
+  }, 30_000);
+});