@@ -25,8 +25,17 @@ interface PreProps {
 function Pre({ children, filename }: PreProps) {
   const codeProps = children.props;
   const raw = typeof codeProps.children === "string" ? codeProps.children : "";
+  // Threaded explicitly rather than sniffed off the DOM downstream: the
+  // language is a prop of the compiled `<code>` node right here, and
+  // `CodeSurface` should not have to reach into its own children to find the
+  // identity it renders. It is the fallback when the fence carries no
+  // `title=` — see `CodeBlock`.
   return (
-    <CodeBlock raw={raw} filename={filename}>
+    <CodeBlock
+      raw={raw}
+      filename={filename}
+      language={codeProps["data-language"]}
+    >
       {children}
     </CodeBlock>
   );
 
@@ -45,15 +45,29 @@ describe("docsMdxComponents (fence rendering)", () => {
     expect(document.querySelectorAll("figure")).toHaveLength(1);
   });
 
-  it("renders a header with no identity text — but still a Copy button — for an untitled fence", async () => {
-    const { container } = await renderFence(
-      ["```css", ":root { --y: 2; }", "```"].join("\n"),
-    );
+  it("falls back to the fence's own language when there is no title=", async () => {
+    // End-to-end through the real compile pipeline, which is the only thing
+    // that proves `data-language` is actually present on the compiled
+    // `<code>` for `Pre` to thread through — a hand-built element tree would
+    // just assert our own assumption back at us.
+    await renderFence(["```css", ":root { --y: 2; }", "```"].join("\n"));
     expect(screen.getByRole("button", { name: /copy/i })).toBeInTheDocument();
     expect(document.querySelectorAll("figure")).toHaveLength(1);
-    // No bare language tag anywhere — the exact "shows nothing worth its
-    // space" case the design doc forbids.
-    expect(container.textContent).not.toMatch(/^(CSS|TS|TSX|JS|JSX|BASH)$/i);
+    const header = screen
+      .getByRole("button", { name: /copy/i })
+      .closest("div")!;
+    expect(header).toHaveTextContent(/^css/i);
+  });
+
+  it("prefers a fence's title= over its language", async () => {
+    await renderFence(
+      ['```css title="brand.css"', ":root { --x: 1; }", "```"].join("\n"),
+    );
+    const header = screen
+      .getByRole("button", { name: /copy/i })
+      .closest("div")!;
+    expect(header).toHaveTextContent(/^brand\.css/);
+    expect(header.textContent).not.toMatch(/brand\.css\s*css/i);
   });
 
   it("highlights the fence's actual code", async () => {
 
@@ -5,18 +5,33 @@ import { CodeSurface } from "./CodeSurface";
 export interface CodeBlockProps {
   children: ReactNode;
   raw: string;
+  /** From the fence's `title="…"` meta, threaded by `MdxRenderer`'s `Figure`. */
   filename?: string;
+  /** From rehype-pretty-code's `data-language`, threaded by `MdxRenderer`'s `Pre`. */
+  language?: string;
 }
 
-// No `lang` prop: with the header now showing a real filename when one is
-// authored (via fence `title="…"` meta — see MdxRenderer's `Figure`), a bare
-// language tag left the bar saying nothing a reader couldn't already see
-// from the syntax highlighting. See the design doc's "one shared code
-// surface" decision.
-export function CodeBlock({ children, raw, filename }: CodeBlockProps) {
+// Titles where practicable, falling back to the language tag. The original
+// call was to show nothing rather than a lone language tag — but that assumed
+// some fences would be titled, and none were: all 139 carried a language and
+// zero carried a title, so every fence header rendered as a blank band with a
+// Copy button floated at its right. A quiet language label is worth more than
+// an empty bar. See the design doc's "identity in the header" decision.
+export function CodeBlock({
+  children,
+  raw,
+  filename,
+  language,
+}: CodeBlockProps) {
   return (
     <figure className="my-6 overflow-hidden rounded-md border border-rule bg-bg-card">
-      <CodeSurface filename={filename} raw={raw} variant="fence" showCopy>
+      <CodeSurface
+        filename={filename}
+        language={language}
+        raw={raw}
+        variant="fence"
+        showCopy
+      >
         {children}
       </CodeSurface>
     </figure>
 
@@ -8,14 +8,28 @@ import {
   type ReactNode,
 } from "react";
 
+/**
+ * Languages whose tag would say nothing a reader can't already see. A `text`
+ * fence names no language, so uppercasing it into "TEXT" would recreate the
+ * empty-bar problem with extra ink. Everything else — ts, tsx, css, html,
+ * bash, diff — names something real.
+ */
+const UNINFORMATIVE_LANGUAGES = new Set(["text", "plaintext", "plain", "txt"]);
+
 export interface CodeSurfaceProps {
   /**
-   * Shown on the left of the header. Omitted (a fence with no `title=` meta)
-   * leaves that side blank — the bar still renders, because it still hosts
-   * the actions on the right; it just never renders a lone language tag.
+   * Identity shown on the left of the header. A fence gets it from `title="…"`
+   * fence meta; an example passes its file path only when there is no file-tab
+   * strip to name it (see `ExampleShell`), since the tabs already do.
    */
   filename?: string;
-  /** Full source text. Used for the Copy action and the "N lines" label. */
+  /**
+   * Fallback identity for a fence carrying no `title=`: the fence's own
+   * language, drawn as a quiet uppercase label rather than a heading. Ignored
+   * whenever `filename` is set — a real name always beats a language.
+   */
+  language?: string;
+  /** Full source text. Used for the Copy action. */
   raw: string;
   /**
    * A fence renders its own padding and type-scale class on the code
@@ -34,38 +48,48 @@ export interface CodeSurfaceProps {
   showCopy?: boolean;
   /**
    * Fixed collapsed height, in px, for the code region below the header.
-   * Omitted renders the surface unconstrained — no fade, no line count, no
-   * expand control. That's the fence path: fences have never had a height
-   * problem, only examples do (48-252 line sources against a ~480px pane).
+   * Omitted renders the surface unconstrained — no clamp, no fade. That's the
+   * fence path: fences have never had a height problem, only examples do
+   * (48-252 line sources against a ~480px pane).
    */
   height?: number;
-  /** Controlled: whether the surface is currently expanded past `height`. */
+  /**
+   * Controlled: whether the surface is currently expanded past `height`. The
+   * control that flips it lives in the caller's own toolbar, not in this
+   * header — see `ExampleShell`.
+   */
   expanded?: boolean;
-  onToggleExpand?: () => void;
   /**
    * Fires whenever overflow status or the content's natural (unclamped)
    * height changes. The natural height is `header height + content
    * scrollHeight` — what the caller needs to grow an ancestor pane to when
-   * the reader expands.
+   * the reader expands. `overflowing` is what tells the caller whether to
+   * offer an expand control at all.
    */
   onOverflowChange?: (overflowing: boolean, naturalHeight: number) => void;
   children: ReactNode;
 }
 
 /**
  * The one code surface shared by a fenced block (`CodeBlock`) and an
- * `<Example>`'s Code pane (`ExampleShell`): a header bar with file identity
- * on the left and actions on the right, then the code. See
+ * `<Example>`'s Code pane (`ExampleShell`): identity on the left of a header
+ * bar, Copy on the right, then the code. See
  * docs/superpowers/specs/2026-08-14-docs-code-surface-design.md.
+ *
+ * The header is conditional, not decorative furniture — it appears only when
+ * it has something to say (an identity, or a Copy button). Everything an
+ * example wraps around this surface (its own tabs, its own toolbar, its own
+ * expand control) stays in `ExampleShell`, so this component never has to
+ * know how many files it is one of.
  */
 export function CodeSurface({
   filename,
+  language,
   raw,
   variant,
   showCopy = false,
   height,
   expanded = false,
-  onToggleExpand,
   onOverflowChange,
   children,
 }: CodeSurfaceProps) {
@@ -112,53 +136,50 @@ export function CodeSurface({
     return () => ro.disconnect();
   }, [height, raw, onOverflowChange]);
 
-  const lineCount = raw.split("\n").length;
-  // Once expanded, the scroll region's own box grows to fit its content —
-  // `overflowing` alone would flip back to false at that point (nothing left
-  // to scroll to), which would yank the "Show less" control out from under
-  // an expanded reader. `expanded` keeps both the label and the line count
-  // in place for as long as the reader is looking at the expanded pane.
-  const truncatable = height != null && (overflowing || expanded);
-  const showLineCount = truncatable;
   const showFade = height != null && overflowing && !expanded;
-  const showExpand = truncatable;
 
-  const actionButtonClass =
-    "whitespace-nowrap rounded-[3px] border border-rule bg-bg-card px-2 py-1 font-mono text-[10px] text-text-secondary hover:text-text-primary";
+  const languageTag =
+    language && !UNINFORMATIVE_LANGUAGES.has(language.toLowerCase())
+      ? language
+      : undefined;
+  // A name always wins; the language is only the fallback. Drawing them
+  // differently is the point: a filename is the thing's identity and reads as
+  // written, while the language is a classification, so it gets the small
+  // uppercase treatment this codebase already uses for quiet labels (see the
+  // view tabs in ExampleShell) — a label on the bar, not a heading over the
+  // code.
+  const identity = filename ? (
+    <span className="truncate">{filename}</span>
+  ) : languageTag ? (
+    <span className="truncate text-[10px] uppercase tracking-[0.12em]">
+      {languageTag}
+    </span>
+  ) : null;
+
+  // No identity and no actions means an empty bar, and an empty bar is pure
+  // cost: it was ~31px of border and background saying nothing above every
+  // multi-file example's code. Render nothing instead. A fence always has at
+  // least Copy, so a fence always keeps its bar.
+  const hasHeader = identity != null || showCopy;
 
-  const header = (
+  const header = hasHeader ? (
     <div
       ref={headerRef}
-      className="flex shrink-0 items-center justify-between gap-2 border-b border-rule px-3 py-1.5 font-mono text-[11px] text-text-dim"
+      className="flex shrink-0 items-center gap-2 border-b border-rule px-3 py-1.5 font-mono text-[11px] text-text-dim"
     >
-      <span className="truncate">
-        {filename}
-        {filename && showLineCount ? " · " : ""}
-        {showLineCount ? `${lineCount} lines` : ""}
-      </span>
-      <span className="ml-2 flex shrink-0 items-center gap-1.5">
-        {showCopy && (
-          <button
-            type="button"
-            aria-label="Copy code"
-            onClick={onCopy}
-            className={actionButtonClass}
-          >
-            {copied ? "Copied" : "Copy"}
-          </button>
-        )}
-        {showExpand && (
-          <button
-            type="button"
-            onClick={onToggleExpand}
-            className={actionButtonClass}
-          >
-            {expanded ? "Show less" : "Expand"}
-          </button>
-        )}
-      </span>
+      {identity}
+      {showCopy && (
+        <button
+          type="button"
+          aria-label="Copy code"
+          onClick={onCopy}
+          className="ml-auto shrink-0 whitespace-nowrap rounded-[3px] border border-rule bg-bg-card px-2 py-1 font-mono text-[10px] text-text-secondary hover:text-text-primary"
+        >
+          {copied ? "Copied" : "Copy"}
+        </button>
+      )}
     </div>
-  );
+  ) : null;
 
   // The `<pre>` is load-bearing, not decorative. `MdxRenderer`'s `Pre` mapping
   // hands this surface rehype-pretty-code's `<code>` and drops the `<pre>` that
 
@@ -79,11 +79,13 @@ export function ExampleShell({
   // — reported via `onOverflowChange` — and is what the pane grows to.
   const [expanded, setExpanded] = useState(false);
   const [naturalHeight, setNaturalHeight] = useState(0);
+  const [overflowing, setOverflowing] = useState(false);
   // Stable identity: CodeSurface re-subscribes its ResizeObserver whenever
   // this callback's identity changes, so an inline arrow here would tear
   // down and recreate the observer on every ExampleShell render.
   const handleOverflowChange = useCallback(
-    (_overflowing: boolean, natural: number) => {
+    (isOverflowing: boolean, natural: number) => {
+      setOverflowing(isOverflowing);
       setNaturalHeight(natural);
     },
     [],
@@ -108,6 +110,19 @@ export function ExampleShell({
     : (["code"] as const);
 
   const file = files[active];
+  // The file-tab strip names every file and marks the active one. When it
+  // renders, the code surface below must NOT also print the active file's
+  // path: that put two bars one row apart both reading
+  // `CellPresentationsGrid.tsx`. A single-file example has no strip, so there
+  // the surface header is the pane's only identity and keeps the name.
+  const hasFileTabs = files.length > 1;
+  const lineCount = file.source.split("\n").length;
+  // Once expanded, the code's own box grows to fit its content, so
+  // `overflowing` flips back to false (nothing left to scroll to) — which
+  // alone would yank "Show less" out from under an expanded reader. The
+  // `expanded` term keeps the control in place for as long as the reader is
+  // looking at the expanded pane.
+  const truncatable = overflowing || expanded;
 
   useEffect(() => {
     return () => {
@@ -250,6 +265,26 @@ export function ExampleShell({
           </button>
         </div>
 
+        {/*
+          The shape of the code, and the control that changes it, sit beside
+          the tabs rather than in the surface's own header one row down. That
+          header existed only to carry these two things for a multi-file
+          example — the file name beside them was a duplicate of the tab
+          already showing it — so hosting them here retires a whole bar.
+        */}
+        {view === "code" && truncatable && (
+          <div className="ml-3 flex shrink-0 flex-nowrap items-center gap-2 font-mono text-[11px] text-text-dim">
+            <span className="whitespace-nowrap">{lineCount} lines</span>
+            <button
+              type="button"
+              onClick={() => setExpanded((e) => !e)}
+              className="whitespace-nowrap rounded-[3px] border border-rule px-2 py-1 text-[10px] text-text-secondary hover:text-text-primary"
+            >
+              {expanded ? "Show less" : "Expand"}
+            </button>
+          </div>
+        )}
+
         <div className="ml-auto flex shrink-0 flex-nowrap items-center gap-1.5 py-1.5">
           {view === "code" && (
             <button
@@ -276,7 +311,7 @@ export function ExampleShell({
         </div>
       </div>
 
-      {view === "code" && files.length > 1 && (
+      {view === "code" && hasFileTabs && (
         <div
           role="tablist"
           aria-label="Example files"
@@ -376,12 +411,11 @@ export function ExampleShell({
           */}
           <CodeSurface
             key={file.path}
-            filename={file.path}
+            filename={hasFileTabs ? undefined : file.path}
             raw={file.source}
             variant="example"
             height={height}
             expanded={expanded}
-            onToggleExpand={() => setExpanded((e) => !e)}
             onOverflowChange={handleOverflowChange}
           >
             <div dangerouslySetInnerHTML={{ __html: file.html }} />