@@ -160,10 +160,17 @@ export function CodeSurface({
     </div>
   );
 
+  // The `<pre>` is load-bearing, not decorative. `MdxRenderer`'s `Pre` mapping
+  // hands this surface rehype-pretty-code's `<code>` and drops the `<pre>` that
+  // wrapped it, so nothing downstream supplies `white-space: pre` — every
+  // fence rendered with its leading indentation collapsed, because the `<code>`
+  // is `display: grid` (one row per line), so lines still broke correctly and
+  // only the indent silently vanished. An example's `children` is already a
+  // full `<pre>`, which is why examples were never affected.
   const code =
     variant === "fence" ? (
-      <div className="docs-code-type overflow-x-auto px-4 py-3 font-mono">
-        {children}
+      <div className="overflow-x-auto">
+        <pre className="docs-code-type m-0 px-4 py-3 font-mono">{children}</pre>
       </div>
     ) : (
       children
 
@@ -30,6 +30,27 @@ describe("CodeBlock", () => {
     expect(writeText).toHaveBeenCalledWith("hello");
   });
 
+  it("wraps the code in a <pre>, so indentation survives", () => {
+    // `MdxRenderer`'s `Pre` mapping drops rehype-pretty-code's `<pre>` and
+    // hands `CodeBlock` the bare `<code>`. Nothing else supplies
+    // `white-space: pre`, and because that `<code>` is `display: grid` the
+    // lines still break — so a collapsed indent is invisible to any assertion
+    // about line count or text content. Assert the element itself.
+    //
+    // jsdom applies no UA stylesheet arithmetic worth trusting here, so this
+    // deliberately checks the TAG rather than a computed style: the tag is
+    // what carries `white-space: pre` in a real browser, and it is the thing
+    // that regressed. `apps/website/e2e` covers the rendered geometry.
+    const { container } = render(
+      <CodeBlock raw={"const a = 1;\n  const b = 2;"}>
+        <code>{"const a = 1;\n  const b = 2;"}</code>
+      </CodeBlock>,
+    );
+    const pre = container.querySelector("pre");
+    expect(pre).not.toBeNull();
+    expect(pre?.querySelector("code")).not.toBeNull();
+  });
+
   it("shows the filename in the header when one is supplied", () => {
     render(
       <CodeBlock raw="const x = 1;" filename="brand.css">
 
@@ -0,0 +1,80 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Fenced code blocks must render their leading indentation.
+ *
+ * `MdxRenderer`'s `Pre` mapping hands `CodeSurface` rehype-pretty-code's
+ * `<code>` and drops the `<pre>` that wrapped it. Without a `<pre>` nothing
+ * supplies `white-space: pre`, so every leading space collapsed — and because
+ * that `<code>` is `display: grid` (one grid row per line), the lines still
+ * broke in the right places. Only the indent vanished, which is why nothing
+ * caught it: line counts, text content and `toContainText` all still passed.
+ *
+ * So assert GEOMETRY, not markup. A line whose text starts with whitespace has
+ * to paint further right than a line that starts at column zero. That is the
+ * only form of this assertion that a collapsed indent can fail.
+ *
+ * Measure the first non-space GLYPH, not the line element's box. Every
+ * `span[data-line]` is a grid item in the same grid column, so its own left
+ * edge is identical on every line whether or not the indent renders — an
+ * earlier version of this test compared line boxes and reported the bug as
+ * still broken after it was fixed. Walk to the first non-whitespace character
+ * and measure a Range around it.
+ */
+const PAGE = "/docs/headless/getting-started";
+
+test("fenced code blocks preserve leading indentation", async ({ page }) => {
+  await page.goto(PAGE, { waitUntil: "domcontentloaded" });
+
+  // Fences, not examples: an `<Example>`'s Code pane always had a real `<pre>`
+  // and was never affected, so including it would let a passing example mask a
+  // broken fence.
+  const fences = page
+    .locator("figure")
+    .filter({ hasNot: page.getByRole("tablist", { name: "Example view" }) });
+
+  const count = await fences.count();
+  expect(count, `${PAGE} should render fenced code blocks`).toBeGreaterThan(0);
+
+  let checked = 0;
+  for (let i = 0; i < count; i++) {
+    const offsets = await fences.nth(i).evaluate((fig) => {
+      const glyphLeft = (line: Element): number | null => {
+        const walker = document.createTreeWalker(line, NodeFilter.SHOW_TEXT);
+        let node: Node | null;
+        while ((node = walker.nextNode())) {
+          const at = (node.textContent ?? "").search(/\S/);
+          if (at < 0) continue;
+          const range = document.createRange();
+          range.setStart(node, at);
+          range.setEnd(node, at + 1);
+          return range.getBoundingClientRect().left;
+        }
+        return null;
+      };
+      const lines = [...fig.querySelectorAll("span[data-line]")];
+      const flat = lines.find((l) => /^\S/.test(l.textContent ?? ""));
+      const indented = lines.find((l) => /^[ \t]+\S/.test(l.textContent ?? ""));
+      if (!flat || !indented) return null;
+      const a = glyphLeft(flat);
+      const b = glyphLeft(indented);
+      if (a === null || b === null) return null;
+      return { flat: a, indented: b };
+    });
+    if (!offsets) continue;
+    checked++;
+    expect(
+      offsets.indented,
+      `fence #${i}: an indented line must paint right of a column-zero line`,
+    ).toBeGreaterThan(offsets.flat);
+  }
+
+  // Guard the guard: if no fence on this page happens to contain both a
+  // column-zero line and an indented one, the loop above asserts nothing and
+  // this test would pass vacuously forever.
+  expect(
+    checked,
+    `${PAGE} no longer has a fence mixing indented and unindented lines — ` +
+      `this test needs a different page, it is not passing on merit`,
+  ).toBeGreaterThan(0);
+});