blume 1.1.0 → 1.1.2

package/src/astro/generate.ts

@@ -3,6 +3,7 @@ import {
   lstat,
   mkdir,
   readFile,
+  realpath,
   rename,
   rm,
   symlink,
@@ -185,6 +186,29 @@ const resolvedAstroPath = (fromDir: string): string | null => {
   }
 };
 
+/**
+ * The two places an installer can put Blume's dependencies:
+ *   - `<blume>/node_modules` — deps nested under the package (workspace source,
+ *     or npm nesting them away from a conflicting hoisted copy)
+ *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ *
+ * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
+ * install symlink), so its parent is the store's package directory where the
+ * isolated linker places the siblings.
+ */
+const depsCandidates = (pkgDir: string): string[] => [
+  join(pkgDir, "node_modules"),
+  dirname(pkgDir),
+];
+
+/** First dependency candidate containing the package dir `segments`, or null. */
+const candidateHolding = (
+  pkgDir: string,
+  ...segments: string[]
+): string | null =>
+  depsCandidates(pkgDir).find((dir) => existsSync(join(dir, ...segments))) ??
+  null;
+
 /**
  * Locate the directory that holds Blume's installed dependencies (Astro and its
  * integrations).
@@ -194,19 +218,28 @@ const resolvedAstroPath = (fromDir: string): string | null => {
  * short-circuits before we need it. But under isolated linkers (Bun's
  * `isolated` mode, pnpm) Blume's deps are NOT hoisted into the project; they
  * live beside the Blume package in a virtual store, invisible to the upward
- * walk from `.blume/`. Two layouts are possible, so probe for `astro`:
- *   - `<blume>/node_modules` — deps nested under the package (workspace source)
- *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ * walk from `.blume/` — so probe the {@link depsCandidates}.
  *
- * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
- * install symlink), so its parent is the store's package directory where the
- * isolated linker places the siblings. The previous fixed
- * `packageRoot()/node_modules` assumption missed the sibling layout entirely,
- * which is why isolated-linker projects had to redeclare Blume's deps by hand.
+ * Astro alone is a bad probe: an npm split install (an `overrides` pin plus an
+ * incremental install) hoists `astro` to the project root while Blume's other
+ * deps stay nested, and probing for astro then picks the root directory — one
+ * that holds none of them. Prefer a candidate with the full set (astro beside
+ * `@astrojs/mdx`, the integration every generated runtime declares), then one
+ * with the integrations (astro hoisted away — the rest of Blume's deps sit
+ * there too), then one with astro alone.
  */
+const holdsAstro = (dir: string): boolean => existsSync(join(dir, "astro"));
+const holdsMdx = (dir: string): boolean =>
+  existsSync(join(dir, "@astrojs", "mdx"));
+
 export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
-  const candidates = [join(pkgDir, "node_modules"), dirname(pkgDir)];
-  return candidates.find((dir) => existsSync(join(dir, "astro"))) ?? null;
+  const candidates = depsCandidates(pkgDir);
+  return (
+    candidates.find((dir) => holdsAstro(dir) && holdsMdx(dir)) ??
+    candidates.find(holdsMdx) ??
+    candidates.find(holdsAstro) ??
+    null
+  );
 };
 
 /**
@@ -269,9 +302,50 @@ const astroConflictWarning = (
   return `Astro version conflict: another dependency hoisted ${versions} to the project root, so @astrojs/mdx binds to the wrong copy and the build fails on a missing export (e.g. "chunkToString"). A single symlink can't reconcile a split install — pin Blume's Astro by adding a package.json "overrides" (npm/bun/pnpm) or "resolutions" (yarn) entry { "astro": "${pin}" }, then reinstall. Run \`npm ls astro\` to find the dependency pulling the older copy.`;
 };
 
+/**
+ * Drop a `.blume/node_modules` junction that resolves a *different* Blume than
+ * the one running. A restored build cache (e.g. Vercel's) can resurrect the
+ * junction pointing into a superseded store directory — blume@1.1.0's isolated
+ * deps dir after 1.1.1 was installed. Releases rarely bump Astro, so the stale
+ * target still resolves the very same astro and every astro-based probe in
+ * {@link ensureDepsLink} passes through the link — while the `blume/*` imports
+ * in the freshly generated config load the previous release, crashing on any
+ * export added since. Staleness is judged by realpath: the link is stale
+ * exactly when the directory behind it holds a `blume` that isn't `pkgDir`.
+ * A target with no `blume` entry (the workspace layout links
+ * `packages/blume/node_modules`, which holds only the deps) resolves Blume
+ * through the normal ancestor walk and stays. Real directories stay too,
+ * mirroring {@link linkDepsJunction} — we only ever remove a link we own.
+ */
+const dropStaleDepsLink = async (
+  link: string,
+  pkgDir: string
+): Promise<void> => {
+  let existing: Awaited<ReturnType<typeof lstat>>;
+  try {
+    existing = await lstat(link);
+  } catch {
+    return;
+  }
+  if (!existing.isSymbolicLink()) {
+    return;
+  }
+  let linkedBlume: string;
+  let runningBlume: string;
+  try {
+    linkedBlume = await realpath(join(link, "blume"));
+    runningBlume = await realpath(pkgDir);
+  } catch {
+    return;
+  }
+  if (linkedBlume !== runningBlume) {
+    await rm(link, { force: true });
+  }
+};
+
 /**
  * Make the generated runtime resolve Astro and its integrations against Blume's
- * own dependency set. Two failure modes this repairs:
+ * own dependency set. Three failure modes this repairs:
  *
  *   - Astro is *unreachable* from `.blume/` (workspaces under isolated linkers,
  *     pnpm) — the deps live in a store the upward walk can't see.
@@ -280,38 +354,53 @@ const astroConflictWarning = (
  *     `astro@7`, so `@astrojs/mdx@7` binds to it and crashes the build on a
  *     missing export. Resolving merely *an* astro isn't enough; it must be the
  *     same one Blume uses.
+ *   - The *integrations* are unreachable while astro is fine — npm's split
+ *     install. An `overrides` pin plus an incremental `npm install` hoists
+ *     astro to the project root (deleting Blume's nested copy) but leaves
+ *     `@astrojs/mdx` and friends nested under `blume/node_modules`, where the
+ *     upward walk from `.blume/` can't see them.
  *
- * In both cases we symlink Blume's dependency directory in as
+ * The repair is the same symlink: Blume's dependency directory linked in as
  * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
- * `@astrojs/mdx`, …) bind to the matching set. We only do this when those deps
- * are a *co-located, consistent* set (astro beside the `@astrojs/mdx` that binds
- * to it). A split layout — an integration hoisted away from a conflicting astro
- * — can't be made consistent by a single symlink and needs a root `overrides`/
- * `resolutions` pin instead. We can't fix that from `.blume/`, so we return a
- * diagnostic naming the conflict rather than silently shipping a runtime that
- * crashes downstream. Returns the warning, or null when nothing needs saying.
+ * `@astrojs/mdx`, …) bind to a consistent set. That's safe when the linked
+ * directory holds the full set, or when it holds only the integrations but the
+ * runtime already resolves Blume's astro — the junction has no `astro` entry,
+ * so astro lookups fall through to the hoisted copy the integrations bind to
+ * anyway. What it can't fix is the inverse split: Blume's astro nested under a
+ * *conflicting* hoisted astro with the integrations hoisted away from it. No
+ * single directory yields a consistent set there; only a root `overrides`/
+ * `resolutions` pin does, so we return a diagnostic naming the conflict rather
+ * than silently shipping a runtime that crashes downstream. Returns the
+ * warning, or null when nothing needs saying.
  */
 export const ensureDepsLink = async (
   outDir: string,
   pkgDir: string = packageRoot()
 ): Promise<string | null> => {
-  const depsDir = blumeDepsDir(pkgDir);
-  if (!depsDir) {
+  const astroDir = candidateHolding(pkgDir, "astro");
+  if (!astroDir) {
     return null;
   }
-  // Already correct when `.blume/` resolves the very same astro Blume's deps
-  // provide — the clean hoisted case, nothing to do.
-  const blumeAstro = resolveAstroPackageJson(depsDir);
+  const mdxDir = candidateHolding(pkgDir, "@astrojs", "mdx");
+  const blumeAstro = resolveAstroPackageJson(astroDir);
+  // Before probing what `.blume/` resolves, drop a cache-restored junction
+  // that binds it to a superseded Blume — the probes below would otherwise
+  // pass right through it (same astro, older blume) and leave it in place.
+  await dropStaleDepsLink(join(outDir, "node_modules"), pkgDir);
   const outDirAstro = resolvedAstroPath(outDir);
-  if (blumeAstro && outDirAstro === blumeAstro) {
+  // `.blume/` resolves the very same astro Blume's deps provide.
+  const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;
+  // Clean hoisted install: astro is correct and the integrations sit beside
+  // it, so they resolve through the same walk — nothing to do.
+  if (astroCorrect && mdxDir === astroDir) {
     return null;
   }
-  // A co-located, consistent set (astro beside the @astrojs/mdx that binds to
-  // it) can be linked in wholesale; this repairs the unreachable and the
-  // repairable-conflict cases. Any existing link here is stale and gets
-  // replaced.
-  if (existsSync(join(depsDir, "@astrojs", "mdx"))) {
-    await linkDepsJunction(join(outDir, "node_modules"), depsDir);
+  // Linking the integrations' directory yields a consistent set when it also
+  // holds Blume's astro (the unreachable and repairable-conflict cases) or
+  // when the correct astro is reachable without it (the npm split install).
+  // Any existing link here is stale and gets replaced.
+  if (mdxDir && (mdxDir === astroDir || astroCorrect)) {
+    await linkDepsJunction(join(outDir, "node_modules"), mdxDir);
     return null;
   }
   // Split layout: Blume's astro is nested (a conflicting astro took the root
@@ -1269,7 +1358,7 @@ export const generateRuntime = async (
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
   // private and filtered out anyway, but the intent is the user's pages.
-  const ogRoutes = customOgRoutes(pages, config.title);
+  const ogRoutes = customOgRoutes(pages, config.title, config.seo.og.titles);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a

package/src/astro/pages.ts

@@ -149,14 +149,25 @@ const humanizeSegment = (segment: string): string =>
  * — most importantly the landing `/`, the most-shared URL — would have no card.
  *
  * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
- * are skipped: they aren't shareable pages. The home is titled with the site
- * title; a deeper page is titled from its last path segment. The card's brand
- * lockup, description, and footer come from the resolved config at render time.
+ * are skipped: they aren't shareable pages. A `titles` entry (`seo.og.titles`,
+ * keyed by route) names a card outright — the only way to say "CLI" when the
+ * segment humanizes to "Cli". Otherwise the home is titled with the site title
+ * and a deeper page from its last path segment. The card's brand lockup,
+ * description, and footer come from the resolved config at render time.
  */
 export const customOgRoutes = (
   pages: BlumePageRoute[],
-  siteTitle: string
+  siteTitle: string,
+  titles: Record<string, string> = {}
 ): OgCustomRoute[] => {
+  // Keys normalized to `/`-joined segments so `cli`, `/cli`, and `/cli/` all
+  // address the page served at `/cli` (and `/` addresses the home).
+  const overrides = new Map(
+    Object.entries(titles).map(([route, title]) => [
+      `/${route.split("/").filter(Boolean).join("/")}`,
+      title,
+    ])
+  );
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
   // Extracted so the skip paths become early `return`s (one `continue` budget
@@ -172,7 +183,12 @@ export const customOgRoutes = (
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
+    routes.push({
+      slug,
+      title:
+        overrides.get(`/${segments.join("/")}`) ??
+        (last ? humanizeSegment(last) : siteTitle),
+    });
   };
   for (const { pattern } of pages) {
     collectRoute(pattern);

package/src/astro/templates.ts

@@ -410,9 +410,10 @@ export const astroConfigTemplate = (options: {
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
   // no config flag; the TypeScript compiler only spins up when a block uses it.
-  const twoslashImport = `import { transformerTwoslash } from "@shikijs/twoslash";\n`;
-  const twoslashTransformer =
-    "transformerTwoslash({ explicitTrigger: true }), ";
+  // Blume's preconfigured transformer compiles with the package's own pinned
+  // classic TypeScript, so the user's project can be on any version (see
+  // markdown/twoslash.ts).
+  const twoslashTransformer = "blumeTwoslashTransformer(), ";
 
   // Content links are rewritten to their real served URL: the `deployment.base`
   // subdirectory (Astro doesn't rewrite `<a href>`) layered over the site-wide
@@ -449,8 +450,8 @@ export const astroConfigTemplate = (options: {
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
 import tailwindcss from "@tailwindcss/vite";
-import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers } from "blume/markdown";
-${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
+import { blumeMarkdownProcessor, blumeMdxProcessor, blumeShikiTransformers, blumeTwoslashTransformer } from "blume/markdown";
+${reactImport}${vueImport}${svelteImport}${blumeImport}${adapterImport}
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
@@ -1077,7 +1078,9 @@ import data from "blume:data";
 export const prerender = true;
 
 // Custom (non-content) pages opted into a generated card, baked in at build.
-const customRoutes = ${JSON.stringify(customRoutes)};
+// The annotation keeps the empty-array case from being an implicit any[]
+// (ts(7034)) under a strict tsconfig.
+const customRoutes: { slug: string; title: string }[] = ${JSON.stringify(customRoutes)};
 
 export function getStaticPaths() {
   const seen = new Set<string>();
@@ -1803,6 +1806,23 @@ const islandDirective = (spec: IslandSpec): string =>
     ? `client:only="${spec.framework}"`
     : `client:${spec.client}`;
 
+/**
+ * Frontmatter `Props` alias mirroring the wrapped component's own props, so
+ * `{...Astro.props}` satisfies required props under `astro check` (the spread
+ * of an untyped `Astro.props` contributes nothing to the JSX props type).
+ * `infer P extends object` rather than `Record<string, unknown>` because
+ * interfaces have no implicit index signature and would miss the narrower
+ * constraint. Non-function component types (Vue/Svelte ambient modules) fall
+ * back to an open record, keeping the untyped permissiveness they had.
+ */
+const wrapperPropsType = (name: string): string =>
+  `type Props = typeof ${name} extends (
+  props: infer P extends object,
+  ...rest: never[]
+) => unknown
+  ? P
+  : Record<string, unknown>;`;
+
 /**
  * Generate `.blume/src/generated/islands/<Name>.astro` — a wrapper that renders
  * a convention island with its hydration directive applied. Astro client
@@ -1813,6 +1833,7 @@ export const islandWrapperTemplate = (spec: IslandSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Island from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Island")}
 ---
 <Island ${islandDirective(spec)} {...Astro.props}><slot /></Island>
 `;
@@ -1875,6 +1896,7 @@ export const exampleWrapperTemplate = (spec: ExampleSpec): string =>
   `---
 // Generated by Blume. Do not edit.
 import Example from ${JSON.stringify(spec.file)};
+${wrapperPropsType("Example")}
 ---
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
 `;
@@ -1944,6 +1966,12 @@ ${entries}
  * live toggles — and sets both `data-theme` and a `dark` class so either
  * dark-mode convention works in user CSS. When the page is opened directly
  * (no parent), it falls back to the stored preference, then the OS setting.
+ *
+ * A second script reports the example's rendered height to the parent
+ * (`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.
  */
 export const examplesPageTemplate = (): string =>
   `---
@@ -1998,7 +2026,42 @@ const Example = entry.Component;
   <!-- Flex + margin:auto centers the example and, unlike place-items, keeps
        the top edge reachable when the example outgrows the frame. -->
   <body style="display:flex;min-height:100svh;padding:1.5rem">
-    <div style="margin:auto"><Example /></div>
+    <div data-blume-example style="margin:auto"><Example /></div>
+    <script is:inline>
+      (() => {
+        // Report the example's rendered height so the embedding docs page can
+        // size the preview pane to the content. The wrapper is observed rather
+        // than the body: the body stretches to the frame's own height, so it
+        // would only echo the pane back. Direct opens have no distinct parent
+        // and skip out; the frame is same-origin with the docs page (see the
+        // theme sync above), so the origin is pinned on both ends.
+        if (window.parent === window) {
+          return;
+        }
+        const wrapper = document.querySelector("[data-blume-example]");
+        if (!wrapper) {
+          return;
+        }
+        // The body's padding frames the example; fold it into the report so
+        // the parent can apply the number as-is. Read from the live value —
+        // the user's examples.css is injected after Blume's defaults precisely
+        // so their tokens win, so a root font-size override must be honored
+        // rather than assuming 1.5rem is 48px.
+        const bodyStyle = getComputedStyle(document.body);
+        const paddingPx =
+          parseFloat(bodyStyle.paddingTop) + parseFloat(bodyStyle.paddingBottom);
+        new ResizeObserver(() => {
+          window.parent.postMessage(
+            {
+              height:
+                Math.ceil(wrapper.getBoundingClientRect().height) + paddingPx,
+              type: "blume:example-height",
+            },
+            window.location.origin
+          );
+        }).observe(wrapper);
+      })();
+    </script>
   </body>
 </html>
 `;

package/src/audit/checks/llms.ts

@@ -91,7 +91,10 @@ export const llmsChecks: CheckModule = {
         continue;
       }
       listed.add(path);
-      if (!context.byUrl.has(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)) {
         found.push(
           finding(
             "BLUME_AUDIT_LLMS_TXT_STALE_ENTRY",

package/src/cli/commands/build.ts

@@ -402,6 +402,13 @@ const publishBuildArtifacts = async (
 
   await runClientAssetChecks(distDir, args);
 
+  // Only reachable with --no-strict (strict aborts earlier): repeat the missing
+  // count next to the success banner so it can't scroll away unseen.
+  if (project.droppedPages > 0) {
+    logger.warn(
+      `${project.droppedPages} page(s) failed frontmatter validation and are missing from this build.`
+    );
+  }
   logger.success(`Built to ${distDir}`);
 };
 
@@ -440,7 +447,12 @@ export const buildCommand = defineCommand({
       description: "Include drafts and unpublished CMS content.",
       type: "boolean",
     },
-    strict: { description: "Fail on diagnostics.", type: "boolean" },
+    strict: {
+      default: true,
+      description:
+        "Fail on error diagnostics (default; pass --no-strict to build anyway, dropping pages that fail validation).",
+      type: "boolean",
+    },
   },
   meta: {
     description: "Build the docs site for production.",

package/src/cli/prepare.ts

@@ -83,12 +83,20 @@ export const prepareProject = async (
   }
 
   const hadErrors = reportDiagnostics(project.diagnostics, options.root);
+  const dropped =
+    project.droppedPages > 0
+      ? `${project.droppedPages} page(s) failed frontmatter validation and were dropped from the site. `
+      : "";
   if (hadErrors && options.strict) {
-    logger.error("Aborting due to errors (strict mode).");
+    logger.error(
+      `Aborting due to errors. ${dropped}Fix the diagnostics above, or pass --no-strict to continue despite them.`
+    );
     process.exit(1);
   }
   if (hasErrors(project.diagnostics) && !options.strict) {
-    logger.warn("Continuing despite errors. Use --strict to fail the build.");
+    logger.warn(
+      `Continuing despite errors. ${dropped}Use --strict to fail instead.`
+    );
   }
 
   const { warnings } = await generateRuntime(project);

package/src/components/content/Component.astro

@@ -47,14 +47,31 @@ const codeHtml = entry
     })
   : undefined;
 
-// Both tabs share one height so toggling them never shifts the layout. Size it
-// to the source (≈21px/line + padding), clamped to a comfortable 18rem floor and
-// a 400px ceiling — taller sources scroll inside the pane.
+// Both tabs share one height so toggling them never shifts the layout. The
+// line-count estimate (≈21px/line + padding, 18rem floor, 25rem ceiling) is
+// 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
+// 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 PADDING_PX = 36;
+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(400, Math.max(288, lineCount * LINE_PX + PADDING_PX));
+const paneHeight = Math.min(
+  ESTIMATE_MAX_PX,
+  Math.max(MIN_PANE_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";
 ---
 
 {
@@ -62,15 +79,21 @@ const paneStyle = `height:${paneHeight}px`;
     // `sync={false}`: each preview's Preview/Code tabs are independent — unlike
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
-      <Tab class="overflow-hidden p-0!" style={paneStyle} title="Preview">
+      <Tab
+        class={`overflow-hidden p-0! ${paneClass}`}
+        style={paneStyle}
+        title="Preview"
+      >
         <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}`}
         />
       </Tab>
-      <Tab class="overflow-hidden" style={paneStyle} title="Code">
+      <Tab class={`overflow-hidden ${paneClass}`} style={paneStyle} title="Code">
         <Fragment set:html={codeHtml} />
       </Tab>
     </Tabs>
@@ -81,3 +104,73 @@ const paneStyle = `height:${paneHeight}px`;
     </div>
   )
 }
+
+<script>
+  // 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.
+
+  // 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;
+    }
+  };
+
+  window.addEventListener("message", (event) => {
+    if (
+      event.origin !== window.location.origin ||
+      event.data?.type !== "blume:example-height" ||
+      !Number.isFinite(event.data.height)
+    ) {
+      return;
+    }
+    const frames = document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-blume-example-frame]"
+    );
+    const frame = Array.from(frames).find(
+      (candidate) => candidate.contentWindow === event.source
+    );
+    if (!frame) {
+      return;
+    }
+    // Keep the raw report around so the viewport clamp can be recomputed
+    // when the window resizes, not only when the frame next reports.
+    frame.dataset.blumeReportedHeight = String(event.data.height);
+    applyMeasuredHeight(frame);
+  });
+
+  // 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.
+  window.addEventListener("resize", () => {
+    for (const frame of document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-blume-example-frame][data-blume-reported-height]"
+    )) {
+      applyMeasuredHeight(frame);
+    }
+  });
+</script>