blume 1.6.2 → 1.6.4

package/src/ai/openapi-components.ts

@@ -0,0 +1,123 @@
+import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
+import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
+import { operationSignature } from "../openapi/signature.ts";
+import type {
+  ComponentMarkdown,
+  EvaluatedValue,
+} from "./component-markdown.ts";
+import { inlineCode, isString, linkDestination } from "./component-markdown.ts";
+
+/**
+ * Spec-authored prose as one line of inline Markdown. Unlike the props the
+ * other serializers pass through, a summary is written by whoever wrote the
+ * spec, not by the docs author, so the characters CommonMark would read as
+ * markup — `<user>` as inline HTML, `*only*` as emphasis — are escaped.
+ */
+const inlineText = (text: string): string =>
+  text
+    .trim()
+    .replaceAll(/\s+/gu, " ")
+    .replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
+
+/** One operation as a link, for the tag listings. */
+const listItem = (
+  signature: string,
+  operation: Pick<ApiOperationRef, "deprecated" | "route" | "summary">
+): string => {
+  const tail = [
+    inlineText(operation.summary),
+    operation.deprecated ? "Deprecated." : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return `- [${inlineCode(signature)}](${linkDestination(operation.route)})${tail ? ` — ${tail}` : ""}`;
+};
+
+/**
+ * Agent-facing Markdown for the components a generated reference page is made
+ * of: `<Operation>`, `<ApiTagOperations>` and `<ApiOverview>`.
+ *
+ * `render-mdx.ts` builds each reference page as the operation's description in
+ * the body plus one of these components, deliberately: the structured UI is the
+ * component's job, and the prose stays Markdown so it indexes. That split is
+ * right for the rendered page and lossy everywhere else — `<route>.md`,
+ * llms-full.txt, MCP `get_page` and the Ask AI corpus all downlevel components
+ * to Markdown, and these three had no serializer, so an operation page reached
+ * an agent as its description followed by a bare tag. On a site whose reference
+ * is most of the corpus, that is most of the corpus: measured on one 449-page
+ * site, 266 pages and 266 raw `<Operation>` in llms-full.txt, so "which
+ * endpoint do I call?" had no answer anywhere in the agent surface.
+ *
+ * Each serializer emits what its component renders and no more: the endpoint
+ * in the spec kind's own notation ({@link operationSignature}), the version and
+ * addresses the overview shows ({@link specAddresses}), the linked list a tag
+ * section shows. Parameters, schemas and responses are deliberately left out:
+ * those are `operation-model.ts` plus each component's own preparation, and a
+ * second implementation here would be free to disagree with the page. The
+ * endpoint and what it does is the part that was missing altogether.
+ *
+ * `specs` is the parsed `blume:openapi` data — empty when the project has no
+ * API reference, in which case every serializer declines.
+ */
+export const openapiComponentSerializers = (specs: OpenApiData) => {
+  const spec = (source: EvaluatedValue) =>
+    isString(source) ? specOf(specs, source) : undefined;
+
+  return {
+    /**
+     * The spec-level block at the top of the overview page: its version and
+     * where the API lives. The tag sections that follow are real Markdown
+     * headings over `<ApiTagOperations>`, so they downlevel on their own.
+     */
+    ApiOverview: ({ props }) => {
+      const data = spec(props.source);
+      if (!data) {
+        return null;
+      }
+      const { addresses, label } = specAddresses(data);
+      const lines = [
+        data.version ? `Version ${inlineText(data.version)}` : "",
+        addresses.length > 0
+          ? `${label}: ${addresses.map(inlineCode).join(", ")}`
+          : "",
+      ].filter(Boolean);
+      return lines.length > 0 ? lines.join("\n\n") : null;
+    },
+
+    /** One tag's operations, mirroring the list the rendered page shows. */
+    ApiTagOperations: ({ props }) => {
+      const { tag } = props;
+      const data = spec(props.source);
+      if (!(data && isString(tag))) {
+        return null;
+      }
+      const items = Object.values(data.operations)
+        .filter((operation) => operation.tagSlug === tag)
+        .map((operation) =>
+          listItem(operationSignature(data, operation), operation)
+        );
+      return items.length > 0 ? items.join("\n") : null;
+    },
+
+    /**
+     * One operation. Declines when the spec carries no such key — Blume's own
+     * fallback, which leaves the JSX visible rather than publishing a page that
+     * silently lost its endpoint.
+     */
+    Operation: ({ props }) => {
+      const { id } = props;
+      const data = spec(props.source);
+      if (!(data && isString(id))) {
+        return null;
+      }
+      const operation = operationOf(data, id);
+      if (!operation) {
+        return null;
+      }
+      const signature = inlineCode(operationSignature(data, operation));
+      return operation.deprecated
+        ? `${signature}\n\n**Deprecated.**`
+        : signature;
+    },
+  } satisfies Record<string, ComponentMarkdown>;
+};

package/src/ai/serializers.ts

@@ -0,0 +1,24 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import { isOpenApiSource } from "../openapi/source.ts";
+import type { ComponentMarkdown } from "./component-markdown.ts";
+import { exampleComponentSerializers } from "./component-markdown.ts";
+import { openapiComponentSerializers } from "./openapi-components.ts";
+
+/**
+ * Every serializer a project brings to a downlevel pass, layered once for all
+ * the agent surfaces (`<route>.md`, llms-full.txt, the search and Ask AI
+ * corpora): the built-in families that read project data — examples, then the
+ * API reference — under the user's `ai.markdownComponents`, which is spread
+ * last so an entry of the same name still wins. One layering, so a new family
+ * or a new surface cannot leave one consumer printing raw JSX.
+ */
+export const projectComponentSerializers = (
+  project: Pick<BlumeProject, "config" | "examples" | "sources">
+) =>
+  ({
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...openapiComponentSerializers(
+      project.sources.find(isOpenApiSource)?.openApiData() ?? {}
+    ),
+    ...project.config.ai.markdownComponents,
+  }) satisfies Record<string, ComponentMarkdown>;

package/src/astro/templates.ts

@@ -1753,6 +1753,7 @@ import { getEntry, render } from "astro:content";
 import type { CollectionKey } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
+import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
@@ -1789,6 +1790,7 @@ import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
 import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
+import LocaleLinks from "blume/components/layout/LocaleLinks.astro";
 import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
@@ -1976,7 +1978,22 @@ const localeAlternates =
 const defaultAlt = i18n ? (alternates ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
 const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 
-const logicalRoute = i18n ? stripLocale(route, locale) : route;
+// \`route\` arrives with \`basePath\` already applied, so the locale segment it
+// carries sits *after* the base (\`/docs/ja/guide\`), while \`localePrefix\` is
+// base-less (\`/ja\`). Stripping and re-adding a locale therefore happen in
+// base-less space, with the base re-applied at the end — the same
+// \`withBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
+// build every real route. Done in based space, \`stripLocale\` matches nothing
+// and \`localizeRoute\` prepends a second prefix (\`/ja/docs/ja/guide\`). Only a
+// switcher entry for a locale with no real translation reaches this fallback:
+// a partially translated hand-written page for its missing locales, or a
+// generated reference (which has no \`alternates\` at all) for every locale
+// but its own.
+const mountLocalized = (logical: string, codeArg: string) =>
+  withBasePath(data.config.basePath, localizeRoute(logical, codeArg));
+const logicalRoute = i18n
+  ? stripLocale(stripBasePath(data.config.basePath, route), locale)
+  : route;
 const localeSwitch = i18n
   ? i18n.locales.map((l) => {
       const alt = (alternates ?? []).find((x) => x.locale === l.code);
@@ -1984,7 +2001,7 @@ const localeSwitch = i18n
         code: l.code,
         current: l.code === locale,
         dir: l.dir,
-        href: alt ? alt.path : localizeRoute(logicalRoute, l.code),
+        href: alt ? alt.path : mountLocalized(logicalRoute, l.code),
         label: l.label,
         untranslated: !alt,
       };
@@ -1998,12 +2015,9 @@ const localeSwitch = i18n
 // (manifest \`versionAlternates\` paths arrive with the base already applied).
 const versionRootFor = (id: string) => {
   const logical = id ? \`/\${id}\` : "/";
-  const localized = i18n ? localizeRoute(logical, locale) : logical;
-  const mount = data.config.basePath;
-  if (!mount) {
-    return localized;
-  }
-  return localized === "/" ? mount : \`\${mount}\${localized}\`;
+  return i18n
+    ? mountLocalized(logical, locale)
+    : withBasePath(data.config.basePath, logical);
 };
 const samePageSwitch = versionsConfig
   ? versionsConfig.switcher.redirect === "same-page"
@@ -2112,7 +2126,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 >
   <h1>{title}</h1>
   {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
-  <Content components={components} />
+  <LocaleLinks locale={locale}>
+    <Content components={components} />
+  </LocaleLinks>
 </LayoutComponent>
 `;
 };
@@ -2912,7 +2928,9 @@ ${entries}
  * (`blume:example-height` via postMessage) so the docs page can size the
  * preview pane to the content instead of guessing from the source line count.
  * A ResizeObserver keeps the report live, so examples that grow or shrink
- * after load (chat threads, accordions) stay in sync.
+ * after load (chat threads, accordions) stay in sync, and the frame re-reports
+ * on request (`blume:example-height-request`) so a report posted before the
+ * docs page's listener registered isn't lost.
  */
 export const examplesPageTemplate = (): string =>
   `---
@@ -2991,7 +3009,7 @@ const Example = entry.Component;
         const bodyStyle = getComputedStyle(document.body);
         const paddingPx =
           parseFloat(bodyStyle.paddingTop) + parseFloat(bodyStyle.paddingBottom);
-        new ResizeObserver(() => {
+        const report = () => {
           window.parent.postMessage(
             {
               height:
@@ -3000,7 +3018,19 @@ const Example = entry.Component;
             },
             window.location.origin
           );
-        }).observe(wrapper);
+        };
+        new ResizeObserver(report).observe(wrapper);
+        // The parent asks for a fresh report when its listener comes up, in
+        // case the first one above was posted before anyone was listening.
+        window.addEventListener("message", (event) => {
+          if (
+            event.source === window.parent &&
+            event.origin === window.location.origin &&
+            event.data?.type === "blume:example-height-request"
+          ) {
+            report();
+          }
+        });
       })();
     </script>
   </body>

package/src/audit/checks/links.ts

@@ -9,14 +9,7 @@ import type {
   PageSnapshot,
   SnapshotLink,
 } from "../types.ts";
-import { normalizePath, resolveHref, siteOrigin } from "../url.ts";
-
-/** Whether a path is served by the build — as a page, or as a static file. */
-const isServed = (context: AuditContext, path: string): boolean =>
-  context.byUrl.has(path) ||
-  context.files.has(path) ||
-  // Astro's directory format serves `/docs/api` from `/docs/api/index.html`.
-  context.files.has(`${path}/index.html`);
+import { isServed, normalizePath, resolveHref, siteOrigin } from "../url.ts";
 
 /** Browser-magic fragments that scroll without needing a matching id. */
 const MAGIC_FRAGMENTS = new Set(["", "top"]);

package/src/audit/checks/llms.ts

@@ -4,7 +4,7 @@ import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
-import { normalizePath, siteOrigin } from "../url.ts";
+import { isServed, normalizePath, siteOrigin } from "../url.ts";
 
 /** The object form of `ai.llmsTxt`. The schema always emits it, but hand-built
  * audit contexts (tests, partial configs) may still carry the raw boolean. */
@@ -97,9 +97,10 @@ export const llmsChecks: CheckModule = {
       }
       listed.add(path);
       // A listed target may be a served asset rather than a page — Blume's own
-      // llms.txt links the changelog RSS feed — so the file index vouches for
-      // it too, the same way redirect targets may land on a served asset.
-      if (!context.byUrl.has(path) && !context.files.has(path)) {
+      // llms.txt links the changelog RSS feed — or a route the server answers
+      // rather than a file the build writes, like the MCP endpoint. `isServed`
+      // vouches for all three, the same way it does for links and redirects.
+      if (!isServed(context, path)) {
         found.push(
           finding(
             "BLUME_AUDIT_LLMS_TXT_STALE_ENTRY",

package/src/audit/redirects.ts

@@ -12,7 +12,7 @@ interface ConfiguredRedirect {
  * it lands on.
  *
  * - `loop`   — the chain revisits a hop it has already been to. Never resolves.
- * - `broken` — the chain ends somewhere that isn't a built page.
+ * - `broken` — the chain ends somewhere the build does not serve.
  * - `chain`  — it resolves, but through at least one intermediate redirect.
  * - `ok`     — one hop, straight to a real page.
  *
@@ -32,7 +32,8 @@ const pathOnly = (value: string): string => {
 
 export const resolveRedirects = (
   redirects: readonly ConfiguredRedirect[],
-  pageUrls: ReadonlySet<string>
+  /** Whether the build serves a normalized path — see `isServed`. */
+  served: (path: string) => boolean
 ): RedirectResolution[] => {
   const byFrom = new Map<string, ConfiguredRedirect>();
   for (const redirect of redirects) {
@@ -71,7 +72,7 @@ export const resolveRedirects = (
 
     const destination = chain.at(-1) ?? from;
     const external = /^https?:\/\//iu.test(destination);
-    if (!(external || pageUrls.has(destination))) {
+    if (!(external || served(destination))) {
       return { ...redirect, chain, outcome: "broken" as const };
     }
     // `chain` is [from, …hops, destination]; more than two entries means at

package/src/audit/run.ts

@@ -36,7 +36,7 @@ import type {
   CheckModule,
   PageSnapshot,
 } from "./types.ts";
-import { normalizePath, siteOrigin } from "./url.ts";
+import { isServed, siteOrigin } from "./url.ts";
 
 const MODULES: CheckModule[] = [
   contentChecks,
@@ -168,13 +168,11 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
         from: withBasePath(basePath, redirect.from),
         to: withBasePath(basePath, redirect.to),
       })),
-      // Pages and static files both: a redirect may legitimately land on a
-      // served asset (`/old-whitepaper` -> `/files/whitepaper.pdf`).
-      new Set(
-        [...byUrl.keys(), ...crawl.files.keys()].map((path) =>
-          normalizePath(path)
-        )
-      )
+      // Pages, static files, and server routes alike: a redirect may
+      // legitimately land on a served asset (`/old-whitepaper` ->
+      // `/files/whitepaper.pdf`), and the same predicate the link and llms.txt
+      // checks use decides what counts.
+      (path) => isServed({ byUrl, files: crawl.files, project }, path)
     ),
     robots: crawl.robots,
     sitemap: crawl.sitemap,

package/src/audit/url.ts

@@ -1,9 +1,42 @@
 import { normalizePath, stripBasePath } from "../core/base-path.ts";
+import type { AuditContext } from "./types.ts";
 
 // Re-exported from its home next to the other path helpers; the audit checks
 // (and their tests) import it from here.
 export { normalizePath } from "../core/base-path.ts";
 
+/** The slice of an audit context that says what the build serves. */
+export type ServedContext = Pick<AuditContext, "byUrl" | "files" | "project">;
+
+/**
+ * Routes the server answers that the build writes no file for.
+ *
+ * The MCP endpoint is streamable HTTP: llms.txt advertises `ai.mcp.route`
+ * whenever the server is enabled, but it appears in neither the page snapshots
+ * nor the static file index, so a check that only consults those reads the
+ * site's own index as broken. The exemption is the configured route while the
+ * server is on, and nothing wider — with `ai.mcp` off, a listed `/mcp` is as
+ * dead as any other missing target. Any future server route (a search API, a
+ * playground proxy) belongs here too, so every check recognizes it at once.
+ */
+const serverRoutes = (context: ServedContext): string[] => {
+  const mcp = context.project.config.ai?.mcp;
+  return mcp?.enabled ? [normalizePath(mcp.route)] : [];
+};
+
+/**
+ * Whether a normalized path is served by the build — as a page, as a static
+ * file, or as a route the server answers. The one definition of "served" for
+ * the link, llms.txt, and redirect checks, so they can never disagree about
+ * the same target.
+ */
+export const isServed = (context: ServedContext, path: string): boolean =>
+  context.byUrl.has(path) ||
+  context.files.has(path) ||
+  // Astro's directory format serves `/docs/api` from `/docs/api/index.html`.
+  context.files.has(`${path}/index.html`) ||
+  serverRoutes(context).includes(path);
+
 /** What an `href` in built HTML turned out to point at. */
 export type ResolvedHref =
   /** A path on this site. */

package/src/cli/commands/validate.ts

@@ -84,6 +84,7 @@ export const validateCommand = defineCommand({
           basePath: project.config.basePath,
           checkExternal: Boolean(args.external),
           extraRoutes,
+          i18n: project.config.i18n,
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
         }))

package/src/components/content/Component.astro

@@ -10,13 +10,11 @@
 // examples are all supported. The source is highlighted with the same Shiki
 // setup as ordinary code fences.
 import data from "blume:data";
-import {
-  CODE_PADDING_BLOCK_REM,
-  FLUSH_CODE_PADDING_TOP_REM,
-} from "../../theme/code-block-padding.ts";
+import { CODE_PADDING_BLOCK_REM } from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { withBase } from "../islands/base-path.ts";
+import { EXAMPLE_PANE_MIN_PX } from "./example-pane.ts";
 import Tab from "./Tab.astro";
 import Tabs from "./Tabs.astro";
 // Generated per project; resolves to an empty map when there are no examples.
@@ -56,31 +54,45 @@ const codeHtml = entry
 // only the initial SSR/no-JS height: once the frame loads it reports its
 // rendered height (see the script below) and both panes follow it, so
 // previews fit the example — including ones that grow or shrink after load.
-// The measured height is never ceilinged — the code tab scrolls inside
-// whatever height it's given (`pre.blume-source`) — but the estimate is:
-// a long source would otherwise render a thousands-of-pixels placeholder
+// The measured height is never ceilinged by the script — the code tab scrolls
+// inside whatever height it's given (`pre.blume-source`) — but the estimate
+// is: a long source would otherwise render a thousands-of-pixels placeholder
 // whose collapse to the measured height no transition could hide. No-JS
 // readers aren't hurt by the cap, since the source scrolls at any height.
 const LINE_PX = 21;
 const REM_PX = 16;
-// The pre's vertical padding, from the same constants the theme emits: the
-// copy-button strip on top (the pane is a flush block inside tabs) and the
-// plain inset below. The tab panel and the pre carry no border of their own.
-const PADDING_PX =
-  (FLUSH_CODE_PADDING_TOP_REM + CODE_PADDING_BLOCK_REM) * REM_PX;
+// The pre's vertical padding, from the same constant the theme emits: the
+// plain inset above and below (the pane is a flush block inside tabs, with no
+// language bar). The tab panel and the pre carry no border of their own.
+const PADDING_PX = 2 * CODE_PADDING_BLOCK_REM * REM_PX;
 const ESTIMATE_MAX_PX = 400;
-// The floor also clamps the measured height client-side; it rides along on the
-// iframe as `data-blume-min-pane` so the script and this estimate can't drift.
-const MIN_PANE_PX = 288;
 const lineCount = entry ? entry.code.replace(/\n+$/u, "").split("\n").length : 0;
 const paneHeight = Math.min(
   ESTIMATE_MAX_PX,
-  Math.max(MIN_PANE_PX, lineCount * LINE_PX + PADDING_PX)
+  Math.max(EXAMPLE_PANE_MIN_PX, lineCount * LINE_PX + PADDING_PX)
 );
 const paneStyle = `height:${paneHeight}px`;
 // Animate the settle from the estimate to the measured height so the lazy
 // frame's load doesn't snap the layout.
-const paneClass = "motion-safe:transition-[height] motion-safe:duration-200";
+//
+// `max-h-lvh` refuses growth beyond the viewport. An example that sizes itself
+// to the frame's viewport (h-screen/100svh) tracks whatever height the script
+// sets, so each report would come back as the pane height plus the frame
+// padding — unbounded growth. Capping at the viewport parks that cycle: once
+// the pane reaches it, the frame's content stops changing size and the
+// observer goes quiet. Genuinely tall examples scroll inside the frame past
+// this point, which a taller-than-screen pane wouldn't have spared them
+// anyway. It's a CSS cap rather than a clamp in the script so it follows the
+// window on its own — a pane capped by a small viewport grows back when the
+// window does, with no resize listener — and it's the *large* viewport unit
+// on purpose: `lvh` holds still while a mobile browser's toolbar collapses
+// and expands during scroll, where `innerHeight` (and `svh`/`dvh`) move by
+// the toolbar's height on every direction change and would animate the pane
+// under the reader's finger. `max-height` isn't transitioned, so the cap
+// applies instantly during a live resize drag instead of retargeting the
+// settle tween every frame.
+const paneClass =
+  "max-h-lvh motion-safe:transition-[height] motion-safe:duration-200";
 ---
 
 {
@@ -96,7 +108,6 @@ const paneClass = "motion-safe:transition-[height] motion-safe:duration-200";
         <iframe
           class="h-full w-full"
           data-blume-example-frame
-          data-blume-min-pane={MIN_PANE_PX}
           loading="lazy"
           src={previewSrc}
           title={`Preview of ${path}`}
@@ -115,75 +126,61 @@ const paneClass = "motion-safe:transition-[height] motion-safe:duration-200";
 }
 
 <script>
+  import { EXAMPLE_PANE_MIN_PX } from "./example-pane.ts";
+
   // Preview frames measure their rendered example and report the height (see
   // `examplesPageTemplate`). One listener serves every <Component> on the
   // page; the sender is matched to its iframe through `event.source`. The
   // measured height replaces the server's line-count estimate on both tab
   // panels together, preserving the shared-height invariant that keeps
-  // Preview/Code toggles from shifting the layout. The floor comes from the
-  // iframe's `data-blume-min-pane` (written next to the server estimate) so
-  // there is one source of truth for it.
+  // Preview/Code toggles from shifting the layout. The viewport cap is CSS
+  // (`max-h-lvh` on the panels — see the frontmatter), so the script only
+  // applies the floor.
+  const HEIGHT_REPORT = "blume:example-height";
+  const HEIGHT_REQUEST = "blume:example-height-request";
 
-  // Refuse growth beyond the viewport. An example that sizes itself to the
-  // frame's viewport (h-screen/100svh) tracks whatever height this listener
-  // sets, so each report would come back as the pane height plus the frame
-  // padding — unbounded growth. Clamping to the viewport parks that cycle:
-  // once the pane reaches it, the frame's content stops changing size and
-  // the observer goes quiet. Genuinely tall examples scroll inside the
-  // frame past this point, which a taller-than-screen pane wouldn't have
-  // spared them anyway.
-  const applyMeasuredHeight = (frame: HTMLIFrameElement) => {
-    const tabs = frame.closest("blume-tabs");
-    const reported = Number(frame.dataset.blumeReportedHeight);
-    if (!tabs || !Number.isFinite(reported)) {
-      return;
-    }
-    const height = `${Math.max(
-      Number(frame.dataset.blumeMinPane) || 0,
-      Math.min(reported, window.innerHeight)
-    )}px`;
-    for (const panel of tabs.querySelectorAll<HTMLElement>(
-      "[data-blume-tab-panel]"
-    )) {
-      panel.style.height = height;
-    }
-  };
+  const frames = () =>
+    document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-blume-example-frame]"
+    );
 
   window.addEventListener("message", (event) => {
     if (
       event.origin !== window.location.origin ||
-      event.data?.type !== "blume:example-height" ||
+      event.data?.type !== HEIGHT_REPORT ||
       !Number.isFinite(event.data.height)
     ) {
       return;
     }
-    const frames = document.querySelectorAll<HTMLIFrameElement>(
-      "iframe[data-blume-example-frame]"
-    );
-    const frame = Array.from(frames).find(
+    const frame = Array.from(frames()).find(
       (candidate) => candidate.contentWindow === event.source
     );
-    if (!frame) {
+    const tabs = frame?.closest("blume-tabs");
+    if (!frame || !tabs) {
       return;
     }
-    // Keep the raw report around so the viewport clamp can be recomputed
-    // when the window resizes, not only when the frame next reports.
+    // Recorded on the frame as a marker that its report arrived (the e2e
+    // suite asserts on it); the panels carry the applied height.
     frame.dataset.blumeReportedHeight = String(event.data.height);
-    applyMeasuredHeight(frame);
+    const height = `${Math.max(EXAMPLE_PANE_MIN_PX, event.data.height)}px`;
+    for (const panel of tabs.querySelectorAll<HTMLElement>(
+      "[data-blume-tab-panel]"
+    )) {
+      panel.style.height = height;
+    }
   });
 
-  // A pane capped by a small viewport would otherwise stay small after the
-  // window grows: the frame's content stopped changing size, so its observer
-  // has nothing new to report. rAF-coalesced so a live resize drag runs the
-  // read-then-write pass once per frame, not once per event.
-  window.addEventListener(
-    "resize",
-    rafThrottle(() => {
-      for (const frame of document.querySelectorAll<HTMLIFrameElement>(
-        "iframe[data-blume-example-frame][data-blume-reported-height]"
-      )) {
-        applyMeasuredHeight(frame);
-      }
-    })
-  );
+  // A frame reports once its observer first fires, and nothing re-sends it.
+  // Whether this module runs before that report depends on how the bundle
+  // ships it (inlined in the document, or as a fetched chunk when it shares
+  // code with another script) and on the client router's swap timing, so
+  // don't rely on winning the race: ask every frame that's already loaded to
+  // report again. A frame still loading ignores the ping (it lands on the
+  // initial blank document) and reports on its own once it renders.
+  for (const frame of frames()) {
+    frame.contentWindow?.postMessage(
+      { type: HEIGHT_REQUEST },
+      window.location.origin
+    );
+  }
 </script>

package/src/components/content/Tabs.astro

@@ -62,19 +62,34 @@ const useDropdown = dropdown && !inline;
   data-sync={sync ? "true" : "false"}
   data-sync-key={syncKey}
 >
-  <div
-    class:list={[
-      inline ? "not-prose" : "",
-      useDropdown ? "" : "overflow-x-auto",
-    ]}
-  >
+  {/*
+    Header row: the scrolling tab strip (or the dropdown) grows, and an
+    actions slot sits fixed at the inline end, outside the scroller so it
+    never rides along with an overflowing strip. The docs layout fills it
+    with one copy button when every panel is a bare code block (CodeGroup,
+    ts2js pairs) — the strip is that group's chrome, so the button belongs
+    there rather than painted over the first line of each block. Empty
+    otherwise, and hidden so it adds no padding.
+  */}
+  <div class:list={["flex", inline ? "not-prose" : ""]}>
+    <div class:list={["min-w-0 grow", useDropdown ? "" : "overflow-x-auto"]}>
+      <div
+        class:list={[
+          useDropdown || borderBottom ? "border-border border-b" : "",
+          useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
+        ]}
+        data-blume-tablist
+        role={useDropdown ? undefined : "tablist"}
+      >
+      </div>
+    </div>
     <div
       class:list={[
+        "flex shrink-0 items-center gap-2 ps-2 empty:hidden",
+        inline ? "" : "pe-3",
         useDropdown || borderBottom ? "border-border border-b" : "",
-        useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
       ]}
-      data-blume-tablist
-      role={useDropdown ? undefined : "tablist"}
+      data-blume-tab-actions
     >
     </div>
   </div>