blume 0.6.1 → 0.6.2

package/dist/types/core/config-input.d.ts

@@ -592,17 +592,12 @@ export interface GithubConfig {
 export interface CodeConfig {
     /** Show a brand language icon in the code-block header. Defaults to `true`. */
     icons?: boolean;
-    /**
-     * Syntax-highlight inline `` `code{:lang}` `` snippets. Defaults to `false`;
-     * opt a snippet in with a trailing `{:lang}` marker.
-     */
-    inline?: boolean;
     /** Wrap long lines instead of scrolling horizontally. Defaults to `false`. */
     wrap?: boolean;
 }
 /** Markdown / MDX rendering behavior. */
 export interface MarkdownConfig {
-    /** Code-block rendering: language icons, inline highlighting, line wrap. */
+    /** Code-block rendering: language icons, line wrap. */
     code?: CodeConfig;
     /** Syntax-highlighting themes for fenced code blocks. */
     codeBlocks?: {
@@ -621,11 +616,6 @@ export interface MarkdownConfig {
     headingAnchors?: boolean;
     /** Make content images click-to-zoom (lightbox). Defaults to `true`. */
     imageZoom?: boolean;
-    /**
-     * Enable LaTeX math (`$…$` inline, `$$…$$` block) via KaTeX. Defaults to
-     * `false` since `$` is common in prose and shell. MDX only.
-     */
-    math?: boolean;
 }
 /**
  * OpenAPI reference. By default (`renderer: "blume"`) Blume renders its own UI:

package/dist/types/core/schema.d.ts

@@ -112,9 +112,8 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     }>>;
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
-    type: z.ZodDefault<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    type: string;
     search: {
         exclude: boolean;
         boost?: number | undefined;
@@ -138,6 +137,7 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         badge?: string | undefined;
         order?: number | undefined;
     };
+    type?: string | undefined;
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
@@ -317,9 +317,8 @@ export declare const pageMetaSchema: z.ZodObject<{
     }>>;
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
-    type: z.ZodDefault<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    type: string;
     search: {
         exclude: boolean;
         boost?: number | undefined;
@@ -343,6 +342,7 @@ export declare const pageMetaSchema: z.ZodObject<{
         badge?: string | undefined;
         order?: number | undefined;
     };
+    type?: string | undefined;
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;

package/dist/types/core/sources/types.d.ts

@@ -83,6 +83,12 @@ export interface ContentSource {
     readonly staged: boolean;
     /** Optional route prefix; the source's routes namespace under `/<prefix>/`. */
     readonly prefix?: string;
+    /**
+     * Resolved on-disk root, set by filesystem-backed sources only. Drives
+     * folder-meta discovery (scan under this root) and the docs-collection base;
+     * omitted by remote/CMS/staged sources that have no local tree.
+     */
+    readonly contentRoot?: string;
     /** Pull every entry. Called once per scan. */
     load: () => Promise<SourceLoadResult>;
     /** Validate the source is usable; throws a BlumeError when not. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -33,6 +33,7 @@ import { validateNavTargets } from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
@@ -742,10 +743,14 @@ interface McpPlan {
 
 /**
  * Decide whether (and how) to generate the MCP server. Skipped — with a
- * warning — when a content page already occupies its route, so the user's page
- * keeps working.
+ * warning — when a content page or a custom `.astro` page already occupies its
+ * route, so the user's page keeps working instead of colliding.
  */
-const planMcp = (project: BlumeProject, srcDir: string): McpPlan => {
+const planMcp = (
+  project: BlumeProject,
+  srcDir: string,
+  userPages: { pattern: string }[]
+): McpPlan => {
   const { config } = project;
   const { route } = config.mcp;
   const dir = join(srcDir, "blume-mcp");
@@ -760,11 +765,11 @@ const planMcp = (project: BlumeProject, srcDir: string): McpPlan => {
   if (!config.mcp.enabled) {
     return base;
   }
-  if (project.graph.pages.some((page) => page.route === route)) {
+  if (routeIsTaken(userPages, project.graph.pages, route)) {
     return {
       ...base,
       warnings: [
-        `MCP server route "${route}" is already used by a content page; the MCP server was not generated. Set a different "mcp.route" in blume.config.ts.`,
+        `MCP server route "${route}" is already used by a content or custom page; the MCP server was not generated. Set a different "mcp.route" in blume.config.ts.`,
       ],
     };
   }
@@ -878,9 +883,13 @@ export interface GenerateResult {
  * `type: changelog` entries — or when a release-backed changelog source is
  * configured, so its route (and any nav tab pointing at it) still resolves to an
  * empty timeline on a build where the source could not be fetched (e.g. CI
- * without a token). Skipped when a user content page already owns `/changelog`.
+ * without a token). Skipped when a user content page or a custom `.astro` page
+ * already owns `/changelog`.
  */
-const shouldGenerateChangelog = (project: BlumeProject): boolean => {
+const shouldGenerateChangelog = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean => {
   const hasChangelog = project.graph.pages.some(
     (page) =>
       page.contentType === "changelog" &&
@@ -889,10 +898,10 @@ const shouldGenerateChangelog = (project: BlumeProject): boolean => {
   const hasChangelogSource = (project.config.content.sources ?? []).some(
     (source) => source.type === "github-releases"
   );
-  const changelogRouteTaken = project.graph.pages.some(
-    (page) => page.route === "/changelog"
+  return (
+    (hasChangelog || hasChangelogSource) &&
+    !routeIsTaken(userPages, project.graph.pages, "/changelog")
   );
-  return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
 };
 
 /**
@@ -998,7 +1007,7 @@ export const generateRuntime = async (
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
   // normal (server-rendered) page written by `writeMcpFiles`.
-  const mcp = planMcp(project, srcDir);
+  const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
   // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
@@ -1041,6 +1050,7 @@ export const generateRuntime = async (
     write(
       join(srcDir, "content.config.ts"),
       contentConfigTemplate({
+        collection: resolveDocsCollection(config, context),
         config,
         context,
         filesystem: hasFilesystemSource,
@@ -1132,7 +1142,7 @@ export const generateRuntime = async (
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (shouldGenerateChangelog(project)) {
+  if (shouldGenerateChangelog(project, pages)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1226,7 +1236,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path),
   ]);
-  if (shouldGenerateChangelog(project)) {
+  if (shouldGenerateChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(

package/src/astro/markdown-negotiation.ts

@@ -72,11 +72,20 @@ export const markdownVariantUrl = (
     }
   }
 
-  const pathname =
-    path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  const trimmed = path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
+  // Requests arrive percent-encoded while routes are stored decoded, so a
+  // non-ASCII route (`/ja/はじめに` requested as `/ja/%E3%81%AF…`) must be
+  // decoded before the lookup. Malformed sequences stay verbatim.
+  let pathname = trimmed;
+  try {
+    pathname = decodeURIComponent(trimmed);
+  } catch {
+    // Keep the raw path; it simply won't match a content route.
+  }
   if (!routes.has(pathname)) {
     return null;
   }
   const target = pathname === "/" ? "/index" : pathname;
-  return `${prefix}${target}.md${query}`;
+  // Re-encode: the variant URL goes back into the request pipeline.
+  return `${prefix}${encodeURI(target)}.md${query}`;
 };

package/src/astro/templates.ts

@@ -404,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
@@ -413,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}/**`]
@@ -436,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 —
@@ -472,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,
   }),
 });
@@ -1093,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);
@@ -1538,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/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/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
             }

package/src/components/layout/NavSelector.astro

@@ -5,6 +5,7 @@
 // <details>/<summary> like the language switcher.
 import type { NavSelector } from "../../core/types.ts";
 import Icon from "../Icon.astro";
+import { isUnderPath } from "./nav-utils.ts";
 
 interface Props {
   selector: NavSelector;
@@ -13,12 +14,13 @@ interface Props {
 
 const { selector, route } = Astro.props;
 
-// The active item is the deepest path that prefixes the current route, falling
-// back to the first item so the summary always shows something meaningful.
+// The active item is the deepest path the current route sits under (on a path
+// boundary, so `/api` never claims `/api-reference` routes), falling back to
+// the first item so the summary always shows something meaningful.
 const active =
   selector.items.find((item) => item.path === route) ??
   selector.items
-    .filter((item) => route.startsWith(item.path))
+    .filter((item) => isUnderPath(route, item.path))
     .toSorted((a, b) => b.path.length - a.path.length)[0] ??
   selector.items[0];