blume 0.6.0 → 0.6.2

package/src/astro/templates.ts

@@ -300,8 +300,6 @@ export const astroConfigTemplate = (options: {
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
       headingAnchors: config.markdown.headingAnchors,
-      inline: config.markdown.code.inline,
-      math: config.markdown.math,
     })}) })`,
   ];
   if (needsReact) {
@@ -335,7 +333,6 @@ export default defineConfig({
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
       headingAnchors: config.markdown.headingAnchors,
-      inline: config.markdown.code.inline,
     })}),
     shikiConfig: {
       themes: {
@@ -407,6 +404,13 @@ export const contentConfigTemplate = (options: {
   staged?: boolean;
   /** Base dir for the staged collection; defaults to `<outDir>/content`. */
   stagedBase?: string;
+  /**
+   * The `docs` collection's base + include/exclude globs. Defaults to
+   * `content.root` and the top-level content globs; a single filesystem source
+   * roots the collection at *its* root so entry ids resolve (see
+   * `resolveDocsCollection`).
+   */
+  collection?: { base: string; include: string[]; exclude: string[] };
   /**
    * Whether any filesystem (non-staged) source feeds the `docs` collection.
    * When false (e.g. an all-staged project where every page is materialized by
@@ -416,12 +420,15 @@ export const contentConfigTemplate = (options: {
 }): string => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
+  const collectionBase = options.collection?.base ?? context.contentRoot;
+  const includeGlobs = options.collection?.include ?? config.content.include;
+  const excludeGlobs = options.collection?.exclude ?? config.content.exclude;
 
   // Fold the content excludes into the glob as negative patterns so the `docs`
   // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
   // staged bodies under `.blume/content`, …) as entries. This matters when
-  // `content.root` is the project root (a migrated `.`-rooted project).
-  const outDirRel = relative(context.contentRoot, context.outDir);
+  // the collection base is the project root (a migrated `.`-rooted project).
+  const outDirRel = relative(collectionBase, context.outDir);
   const outDirIgnore =
     outDirRel && !outDirRel.startsWith("..") && !isAbsolute(outDirRel)
       ? [`!${outDirRel}/**`]
@@ -439,8 +446,8 @@ export const contentConfigTemplate = (options: {
   const filesystem = options.filesystem ?? true;
   const docsPattern = filesystem
     ? [
-        ...config.content.include,
-        ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
+        ...includeGlobs,
+        ...(excludeGlobs ?? []).map((pattern) => `!${pattern}`),
         // Mirror the filesystem scan's baseline ignores (see BLUME_IGNORE_DIRS):
         // Astro's content layer roots at the project dir, so a `.`-wide content
         // root would otherwise re-ingest dependency trees and build output —
@@ -475,7 +482,7 @@ import { glob } from "astro/loaders";
 const docs = defineCollection({
   loader: glob({
     pattern: ${JSON.stringify(docsPattern)},
-    base: ${JSON.stringify(context.contentRoot)},
+    base: ${JSON.stringify(collectionBase)},
     generateId: ({ entry }) => entry,
   }),
 });
@@ -1096,7 +1103,10 @@ const ogPath = data.config.og.enabled
   ? \`/og/\${route === "/" ? "index" : route.slice(1)}.png\`
   : null;
 const ogRel = seo.image ?? ogPath;
-const ogImage = ogRel && base ? \`\${base}\${ogRel}\` : ogRel;
+// Only absolutize root-relative paths: \`seo.image\` may be an external URL,
+// which must pass through verbatim (mirrors PageLayout's absolutizeOgImage).
+const ogImage =
+  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${ogRel}\` : ogRel;
 
 const canonical =
   seo.canonical ?? (base ? \`\${base}\${route === "/" ? "" : route}\` : null);
@@ -1278,6 +1288,20 @@ const slugify = (text) =>
   text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ||
   "update";
 
+// The major of a version's embedded semver (\`1.2.3\` -> 1, \`pkg@2.0.0\` -> 2), or
+// null when there is no full major.minor.patch to key on. Drives the changelog's
+// group-by-major pagination, so it tolerates the scoped tags monorepos publish.
+const majorVersion = (version) => {
+  const match = /(\\d+)\\.\\d+\\.\\d+/.exec(String(version ?? ""));
+  return match ? Number(match[1]) : null;
+};
+
+// Map each entry to its own generated page so the timeline heading can deep-link
+// to it. The collection entry id matches the route manifest's \`entryId\`.
+const routeByEntry = new Map(
+  data.routes.map((route) => [route.entryId, route.path])
+);
+
 const changelogEntries = [
   ...(await getCollection("docs")),${stagedSpread}
 ]
@@ -1299,8 +1323,10 @@ const items = await Promise.all(
     return {
       Content: (await render(entry)).Content,
       date: formatDate(entryDate(entry)),
+      href: routeByEntry.get(entry.id) ?? null,
       id: slugify(label),
       label,
+      major: majorVersion(entry.data.changelog?.version),
       tags: entry.data.changelog?.category
         ? [entry.data.changelog.category]
         : [],
@@ -1308,6 +1334,19 @@ const items = await Promise.all(
   })
 );
 
+// A changelog is semver-paginated only when every visible release parses as
+// semver and they span more than one major line. Older majors then collapse
+// into groups the reader reveals one at a time; otherwise the timeline is flat.
+const majors = items.every((item) => item.major !== null)
+  ? [...new Set(items.map((item) => item.major))].toSorted((a, b) => b - a)
+  : [];
+const paginate = majors.length > 1;
+const majorGroups = majors.map((major) => ({
+  items: items.filter((item) => item.major === major),
+  label: major + ".x",
+  major,
+}));
+
 const headings = items.map((item) => ({
   depth: 2,
   slug: item.id,
@@ -1339,6 +1378,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   }}
   headings={headings}
   toc={data.config.toc}
+  contentLayout="bare"
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1357,16 +1397,50 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   {
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
+    ) : paginate ? (
+      <blume-changelog class="not-prose mt-8 block">
+        {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
+          <Update description={date} href={href} id={id} label={label} tags={tags}>
+            <Content />
+          </Update>
+        ))}
+        {majorGroups.slice(1).map((group) => (
+          <section
+            aria-label={group.label + " releases"}
+            data-changelog-label={group.label}
+            data-changelog-major={group.major}
+          >
+            {group.items.map(({ Content, href, id, label, date, tags }) => (
+              <Update description={date} href={href} id={id} label={label} tags={tags}>
+                <Content />
+              </Update>
+            ))}
+          </section>
+        ))}
+        <div class="mt-10 flex justify-center">
+          <button
+            class="inline-flex items-center gap-2 rounded-full border border-border bg-background px-4 py-2 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground"
+            data-changelog-more
+            hidden
+            type="button"
+          >
+            Show older releases
+          </button>
+        </div>
+      </blume-changelog>
     ) : (
       <div class="not-prose mt-8">
-        {items.map(({ Content, id, label, date, tags }) => (
-          <Update description={date} id={id} label={label} tags={tags}>
+        {items.map(({ Content, href, id, label, date, tags }) => (
+          <Update description={date} href={href} id={id} label={label} tags={tags}>
             <Content />
           </Update>
         ))}
       </div>
     )
   }
+  <script>
+    import "blume/components/content/changelog-element.ts";
+  </script>
 </LayoutComponent>
 `;
 };
@@ -1477,8 +1551,16 @@ const exampleDirective = (spec: ExampleSpec): string => {
 };
 
 /** Filesystem-safe slug for an example's generated wrapper file. */
+/**
+ * A filesystem-safe, injective token for an example path. Distinct paths must
+ * never share a wrapper file (`button.demo` vs `button-demo` used to collide),
+ * so every non-alphanumeric character is hex-escaped rather than collapsed.
+ */
 export const exampleSlug = (path: string): string =>
-  path.replaceAll("/", "__").replaceAll(/[^a-zA-Z0-9_]+/gu, "-");
+  path.replaceAll(
+    /[^a-zA-Z0-9]/gu,
+    (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`
+  );
 
 /**
  * Generate `.blume/src/generated/examples/<slug>.astro` — a wrapper that renders

package/src/cli/commands/build.ts

@@ -11,6 +11,10 @@ import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
+import {
+  deployStaticDir,
+  surfaceAdapterOutput,
+} from "../../deploy/adapter-output.ts";
 import {
   buildNetlifyRedirects,
   buildRedirectManifest,
@@ -365,6 +369,27 @@ export const buildCommand = defineCommand({
       return;
     }
 
-    await publishBuildArtifacts(project, distDir, args);
+    // A server adapter (Vercel/Netlify) writes its deploy bundle relative to the
+    // Astro root — which Blume points at the hidden `.blume` runtime — so the
+    // bundle lands where the deploy platform never looks. Surface it up to the
+    // project root before publishing artifacts into the served static dir.
+    const surfaced = await surfaceAdapterOutput(
+      project.config,
+      project.context
+    );
+    if (surfaced.moved) {
+      logger.success(
+        `Surfaced ${project.config.deployment.adapter} output to ${surfaced.to}`
+      );
+      // The surfaced bundle is a build artifact — keep it out of version control
+      // (Vercel's own CLI ignores `.vercel/` for the same reason).
+      await ensureGitignore(root, [surfaced.ignore]);
+    }
+
+    await publishBuildArtifacts(
+      project,
+      deployStaticDir(project.config, project.context),
+      args
+    );
   },
 });

package/src/cli/commands/dev.ts

@@ -12,7 +12,7 @@ import { coalescedRunner } from "../coalesce.ts";
 import {
   acquireDevLock,
   describeDevLock,
-  readDevLock,
+  DevLockHeldError,
   updateDevLockPort,
 } from "../dev-lock.ts";
 import { logger } from "../log.ts";
@@ -52,22 +52,27 @@ export const devCommand = defineCommand({
     // (OG images, canonicals, sitemap) work locally without configuring a site.
     const explicitPort = parsePort(args.port);
     const port = explicitPort ?? 4321;
-    const devServerUrl = `http://localhost:${port}`;
+    let devServerUrl = `http://localhost:${port}`;
 
     // Claim the shared `.blume` dir BEFORE preparing: `prepareProject`
     // regenerates the runtime, so even a refused second dev server would
     // otherwise clobber the running one's generated tree (with this
-    // invocation's port baked in) on its way out. Dev never relocates the
-    // runtime dir, so the lock always lives at `<root>/.blume`.
+    // invocation's port baked in) on its way out. The claim is atomic, so two
+    // simultaneous starts can't both win. Dev never relocates the runtime dir,
+    // so the lock always lives at `<root>/.blume`.
     const outDir = resolveRuntimeDir(root);
-    const running = readDevLock(outDir);
-    if (running) {
-      logger.error(
-        `A \`blume dev\` server is already running${describeDevLock(running)} in this project. Reuse that server instead of starting a second one — two dev servers would corrupt the shared .blume dir. If it crashed, delete .blume/dev.lock.`
-      );
-      process.exit(1);
+    let releaseLock: () => void;
+    try {
+      releaseLock = acquireDevLock(outDir, port);
+    } catch (error) {
+      if (error instanceof DevLockHeldError) {
+        logger.error(
+          `A \`blume dev\` server is already running${describeDevLock(error.lock)} in this project. Reuse that server instead of starting a second one — two dev servers would corrupt the shared .blume dir. If it crashed, delete .blume/dev.lock.`
+        );
+        process.exit(1);
+      }
+      throw error;
     }
-    const releaseLock = acquireDevLock(outDir, port);
     process.on("exit", releaseLock);
 
     const project = await prepareProject({
@@ -91,9 +96,13 @@ export const devCommand = defineCommand({
 
     // Vite bumps to the next free port when the default is taken, so record
     // the port the server actually bound — the lock's URL is what a refused
-    // second invocation tells its caller to reuse.
-    if (server.address.port !== port) {
-      updateDevLockPort(outDir, server.address.port);
+    // second invocation tells its caller to reuse. The site fallback baked
+    // into the runtime also carries the port, so it must follow suit (below,
+    // once the regeneration closure exists).
+    const boundPort = server.address.port;
+    if (boundPort !== port) {
+      updateDevLockPort(outDir, boundPort);
+      devServerUrl = `http://localhost:${boundPort}`;
     }
 
     // Mirror any initial diagnostics into the browser overlay now the server
@@ -129,6 +138,13 @@ export const devCommand = defineCommand({
       timer = setTimeout(runRegenerate, 80);
     };
 
+    // The runtime prepared above baked the *requested* port into the site
+    // fallback; if Vite bumped it, regenerate so OG images, canonicals, and
+    // other site-gated URLs point at the port actually serving.
+    if (boundPort !== port) {
+      void runRegenerate();
+    }
+
     // Content is watched per source (filesystem uses fs.watch; remote sources
     // are frozen for the session). The remaining project inputs — user pages,
     // config, theme, and component overrides — are watched directly.

package/src/cli/commands/doctor.ts

@@ -1,6 +1,10 @@
+import { readFileSync } from "node:fs";
+
 import { defineCommand } from "citty";
+import { join } from "pathe";
 
 import { BlumeError } from "../../core/diagnostics.ts";
+import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
@@ -12,7 +16,34 @@ import {
   reportDiagnosticsJson,
 } from "../log.ts";
 
-const MIN_NODE_MAJOR = 20;
+const FALLBACK_MIN_NODE = "22.12.0";
+const LEADING_RANGE = /^[^\d]*/u;
+
+/** The minimum Node version, read from the package's own `engines` field so
+ * doctor can never drift from what the package actually declares. */
+const minSupportedNode = (): string => {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(packageRoot(), "package.json"), "utf-8")
+    ) as { engines?: { node?: string } };
+    const range = pkg.engines?.node ?? "";
+    return range.replace(LEADING_RANGE, "") || FALLBACK_MIN_NODE;
+  } catch {
+    return FALLBACK_MIN_NODE;
+  }
+};
+
+const versionBelow = (current: string, minimum: string): boolean => {
+  const a = current.split(".").map((part) => Number.parseInt(part, 10));
+  const b = minimum.split(".").map((part) => Number.parseInt(part, 10));
+  for (let i = 0; i < 3; i += 1) {
+    const delta = (a[i] ?? 0) - (b[i] ?? 0);
+    if (delta !== 0) {
+      return delta < 0;
+    }
+  }
+  return false;
+};
 
 export const doctorCommand = defineCommand({
   args: {
@@ -29,14 +60,11 @@ export const doctorCommand = defineCommand({
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];
 
-    const nodeMajor = Number.parseInt(
-      process.versions.node.split(".")[0] ?? "0",
-      10
-    );
-    if (nodeMajor < MIN_NODE_MAJOR) {
+    const minNode = minSupportedNode();
+    if (versionBelow(process.versions.node, minNode)) {
       diagnostics.push({
         code: "BLUME_NODE_VERSION",
-        message: `Node ${process.versions.node} is below the supported minimum (${MIN_NODE_MAJOR}).`,
+        message: `Node ${process.versions.node} is below the supported minimum (${minNode}).`,
         severity: "warning",
       });
     }

package/src/cli/commands/sync.ts

@@ -4,7 +4,11 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { loadConfig } from "../../core/config.ts";
-import { resolveProjectContext } from "../../core/project.ts";
+import {
+  resolveProjectContext,
+  resolveRuntimeDir,
+} from "../../core/project.ts";
+import { readDevLock } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -38,8 +42,16 @@ export const syncCommand = defineCommand({
 
     // Dev mode keeps drafts and skips the static-build gate; `refresh` forces
     // remote sources to re-fetch rather than serve their cached snapshot. A
-    // running dev server hot-reloads from the regenerated runtime.
+    // running dev server hot-reloads from the regenerated runtime — so when one
+    // is live, regenerate with the same site fallback (its URL) it used, else
+    // its astro.config loses `site` (dropping OG and canonicals) and Astro
+    // restarts cold.
+    const lock = readDevLock(resolveRuntimeDir(root));
+    const devServerUrl = lock?.port
+      ? `http://localhost:${lock.port}`
+      : undefined;
     await prepareProject({
+      devServerUrl,
       mode: "dev",
       preview: args.preview,
       refresh: true,

package/src/cli/dev-lock.ts

@@ -84,16 +84,27 @@ export const readDevLock = (outDir: string): DevLockInfo | null => {
 export const isDevLocked = (outDir: string): boolean =>
   readDevLock(outDir) !== null;
 
+const lockPayload = (port?: number): string =>
+  JSON.stringify({
+    pid: process.pid,
+    ...(port === undefined ? {} : { port }),
+  });
+
 const writeLock = (outDir: string, port?: number): void => {
-  writeFileSync(
-    lockPath(outDir),
-    JSON.stringify({
-      pid: process.pid,
-      ...(port === undefined ? {} : { port }),
-    })
-  );
+  writeFileSync(lockPath(outDir), lockPayload(port));
 };
 
+/** Thrown when another live `blume dev` already holds the lock. */
+export class DevLockHeldError extends Error {
+  readonly lock: DevLockInfo;
+
+  constructor(lock: DevLockInfo) {
+    super(`A blume dev server (pid ${lock.pid}) already holds the lock.`);
+    this.name = "DevLockHeldError";
+    this.lock = lock;
+  }
+}
+
 const ownsLock = (outDir: string): boolean => {
   const path = lockPath(outDir);
   if (!existsSync(path)) {
@@ -108,12 +119,31 @@ const ownsLock = (outDir: string): boolean => {
 
 /**
  * Write the current process's dev lock into `outDir` and return a release
- * function. The release only removes the file if it's still ours, so a newer
- * dev server's lock is never clobbered.
+ * function. The claim is atomic (`wx`): two `blume dev` processes racing the
+ * same dir can't both pass a check-then-write — the loser gets a
+ * {@link DevLockHeldError} naming the live holder. A stale lock (dead pid) or
+ * this process's own leftover is cleared and re-claimed. The release only
+ * removes the file if it's still ours, so a newer dev server's lock is never
+ * clobbered.
  */
 export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  writeLock(outDir, port);
+  for (;;) {
+    try {
+      writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      const existing = readDevLock(outDir);
+      if (existing && existing.pid !== process.pid) {
+        throw new DevLockHeldError(existing);
+      }
+      // Stale or our own leftover: clear it and race for the claim again.
+      rmSync(lockPath(outDir), { force: true });
+    }
+  }
   let released = false;
   return () => {
     if (released) {

package/src/cli/env.ts

@@ -27,7 +27,11 @@ const unquote = (raw: string): string => {
   if (single !== undefined) {
     return single;
   }
-  return raw;
+  // dotenv/Vite treat an unquoted `#` as the start of an inline comment (a
+  // value containing `#` must be quoted) — keeping the comment would hand
+  // consumers a silently corrupted value.
+  const hash = raw.indexOf("#");
+  return (hash === -1 ? raw : raw.slice(0, hash)).trim();
 };
 
 /** Parse `.env` text into key/value pairs, skipping blanks and `#` comments. */

package/src/components/content/Update.astro

@@ -6,6 +6,8 @@ interface RssMetadata {
 
 interface Props {
   description?: string;
+  /** Link the heading to a dedicated page; falls back to the in-page anchor. */
+  href?: string;
   id?: string;
   label?: string;
   rss?: RssMetadata;
@@ -13,7 +15,15 @@ interface Props {
   title?: string;
 }
 
-const { description, id: providedId, label, rss, tags, title } = Astro.props;
+const {
+  description,
+  href,
+  id: providedId,
+  label,
+  rss,
+  tags,
+  title,
+} = Astro.props;
 const slugify = (text: string): string =>
   text
     .toLowerCase()
@@ -37,7 +47,7 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
   <header class="md:border-border md:border-e md:pe-4">
     <a
       class="font-semibold text-foreground text-sm no-underline hover:text-accent"
-      href={`#${id}`}
+      href={href ?? `#${id}`}
     >
       {updateLabel}
     </a>

package/src/components/content/changelog-element.ts

@@ -0,0 +1,62 @@
+/**
+ * Client behaviour for the `<blume-changelog>` custom element wrapping the
+ * generated changelog timeline when its releases are semver-versioned. The
+ * newest major line stays visible; every older major is collapsed into a group
+ * revealed one major at a time by the "Show N.x releases" button at the bottom.
+ *
+ * Pure progressive enhancement: the server renders every release in document
+ * order, and this element hides the older-major groups on connect — so a no-JS
+ * visitor (or a crawler) still sees the complete history, and the button does
+ * nothing until the script upgrades it.
+ *
+ * Imported for its side effect (registers the element) from the changelog page.
+ */
+
+class BlumeChangelog extends HTMLElement {
+  connectedCallback() {
+    const groups = [
+      ...this.querySelectorAll<HTMLElement>("[data-changelog-major]"),
+    ];
+    const button = this.querySelector<HTMLButtonElement>(
+      "[data-changelog-more]"
+    );
+    if (groups.length === 0 || !button) {
+      return;
+    }
+
+    for (const group of groups) {
+      group.hidden = true;
+      // Focusable only programmatically, so revealing a group can move focus to
+      // it for keyboard and screen-reader users without adding a tab stop.
+      group.tabIndex = -1;
+    }
+
+    let revealed = 0;
+    const sync = () => {
+      const next = groups[revealed];
+      if (next) {
+        button.textContent = `Show ${next.dataset.changelogLabel} releases`;
+        button.hidden = false;
+      } else {
+        button.hidden = true;
+      }
+    };
+
+    button.addEventListener("click", () => {
+      const next = groups[revealed];
+      if (!next) {
+        return;
+      }
+      next.hidden = false;
+      revealed += 1;
+      sync();
+      next.focus();
+    });
+
+    sync();
+  }
+}
+
+if (!customElements.get("blume-changelog")) {
+  customElements.define("blume-changelog", BlumeChangelog);
+}

package/src/components/islands/ask-ai.tsx

@@ -217,7 +217,9 @@ const AskAI = ({
         const chunk = await reader.read();
         ({ done } = chunk);
         if (chunk.value) {
-          assistant.content += decoder.decode(chunk.value);
+          // Streaming mode: a multi-byte UTF-8 sequence split across chunks
+          // must not flush as U+FFFD garbage.
+          assistant.content += decoder.decode(chunk.value, { stream: true });
           setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
         }
       }

package/src/components/islands/hooks.ts

@@ -171,7 +171,11 @@ export const useAskAI = (): UseAskAI => {
             const chunk = await reader.read();
             ({ done } = chunk);
             if (chunk.value) {
-              assistant.content += decoder.decode(chunk.value);
+              // Streaming mode: a multi-byte UTF-8 sequence split across
+              // chunks must not flush as U+FFFD garbage.
+              assistant.content += decoder.decode(chunk.value, {
+                stream: true,
+              });
               setMessages((current) => [
                 ...current.slice(0, -1),
                 { ...assistant },

package/src/components/layout/Header.astro

@@ -6,6 +6,7 @@ import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
 import Logo from "./Logo.astro";
+import { isUnderPath } from "./nav-utils.ts";
 import NavSelector from "./NavSelector.astro";
 import { resolveSlot } from "./overrides.ts";
 import Search from "./Search.astro";
@@ -27,6 +28,12 @@ interface Props {
   // The mobile menu button toggles the docs sidebar drawer; custom pages
   // without a sidebar (e.g. a landing page) pass `false` to hide it.
   hasSidebar?: boolean;
+  /**
+   * Whether the layout renders a drawer for the nav toggle to open. A shell
+   * with no drawer at all (the Scalar reference layout) passes `false`, else
+   * the hamburger would lock page scroll with nothing appearing.
+   */
+  hasDrawer?: boolean;
   searchStrings?: UIStrings["search"];
   switcherStrings?: UIStrings["languageSwitcher"];
   localeSwitch?: LocaleSwitchOption[];
@@ -48,6 +55,7 @@ const {
   searchEnabled,
   askEnabled = false,
   hasSidebar = true,
+  hasDrawer = true,
   searchStrings,
   switcherStrings,
   localeSwitch,
@@ -62,7 +70,7 @@ const SearchSlot = resolveSlot(layout.Search, Search);
 // is the sidebar tree (`hasSidebar`); on chrome-only pages (a landing page via
 // PageLayout) it's a tabs-only drawer the layout renders — so the button is also
 // needed whenever there are tabs to reveal.
-const showNavToggle = hasSidebar || navigation.tabs.length > 0;
+const showNavToggle = hasDrawer && (hasSidebar || navigation.tabs.length > 0);
 // Where the header's inline tab bar appears. With a sidebar it shares the `md`
 // breakpoint with the docs drawer; without one, the tabs-only drawer is the sole
 // mobile nav below `lg`, so the inline tabs wait until `lg` to avoid duplicating
@@ -126,7 +134,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
           <a
             aria-current={
               route === tab.path ||
-              (tab.path !== "/" && route.startsWith(tab.path))
+              (tab.path !== "/" && isUnderPath(route, tab.path))
                 ? "page"
                 : undefined
             }