blume 1.5.0 → 1.5.2

package/src/components/openapi/ws-client.ts

@@ -0,0 +1,194 @@
+/**
+ * WebSocket state machine behind the AsyncAPI message composer's live connect,
+ * used only for operations whose channel has a `ws`/`wss` server. Framework-
+ * free and dependency-free like the rest of the playground client code, and it
+ * never touches the `WebSocket` global at import time — the constructor is
+ * reached solely inside the default factory, so this module imports cleanly in
+ * the test runner and on the server during the Astro build.
+ *
+ * The socket factory and the clock are injectable because both are the parts a
+ * test cannot afford to use for real: `create` lets a suite drive open/message/
+ * error/close by hand instead of dialing a network, and `now` makes frame
+ * timestamps deterministic instead of wall-clock noise.
+ *
+ * v1 deliberately has no reconnect, no send queue, and no timers. A docs reader
+ * connecting to a demo broker wants to see exactly what the socket did — a
+ * silent retry loop would hide the very close code they are debugging, and
+ * reconnect policy belongs to the API's own client library, not to a docs page.
+ */
+
+// `typeof` checks live in named predicates (the form the oxlint anti-slop
+// config sanctions); generic so each DOM-event field keeps its own narrowing.
+const isString = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+const isNumber = <Value>(value: Value): value is Value & number =>
+  typeof value === "number";
+
+export type WsState = "idle" | "connecting" | "open" | "closed" | "error";
+
+export interface WsFrame {
+  /** Wall-clock ms when the frame was logged. */
+  at: number;
+  direction: "received" | "sent";
+  text: string;
+}
+
+/** One socket event, reduced to the fields the client reads. */
+export interface SocketEvent {
+  code?: number;
+  data?: unknown;
+  reason?: string;
+}
+
+/** The subset of WebSocket the client drives; lets tests inject a fake. */
+export interface SocketLike {
+  addEventListener: (
+    type: string,
+    listener: (event: SocketEvent) => void
+  ) => void;
+  close: () => void;
+  send: (data: string) => void;
+}
+
+export interface WsClientOptions {
+  /** Socket factory; defaults to `new WebSocket(url)`. */
+  create?: (url: string) => SocketLike;
+  /** Clock for frame timestamps; defaults to `Date.now`. */
+  now?: () => number;
+  onFrame: (frame: WsFrame) => void;
+  /** State transitions, with an optional human detail (close reason/code). */
+  onState: (state: WsState, detail?: string) => void;
+}
+
+export interface WsClient {
+  /** Open a socket. A no-op while `connecting` or `open`. */
+  connect: (url: string) => void;
+  /** Close the socket if any; state goes to `closed`. */
+  disconnect: () => void;
+  /** Send text; false when the socket is not open (nothing is logged then). */
+  send: (text: string) => boolean;
+  state: () => WsState;
+}
+
+/**
+ * Adapt a real `WebSocket` to `SocketLike`. Each DOM event is reduced to the
+ * three fields the client reads, discovered with `in`/`typeof` guards: the DOM
+ * types would need a cast to reach `code`/`data`/`reason` off a bare `Event`,
+ * and a cast here would let the rest of the module drift onto browser-only
+ * surface it has no business using.
+ */
+const defaultCreate = (url: string): SocketLike => {
+  const socket = new WebSocket(url);
+  return {
+    addEventListener: (type, listener) => {
+      socket.addEventListener(type, (event) => {
+        const reduced: SocketEvent = {};
+        if ("code" in event && isNumber(event.code)) {
+          reduced.code = event.code;
+        }
+        if ("data" in event) {
+          reduced.data = event.data;
+        }
+        if ("reason" in event && isString(event.reason)) {
+          reduced.reason = event.reason;
+        }
+        listener(reduced);
+      });
+    },
+    close: () => {
+      socket.close();
+    },
+    send: (data) => {
+      socket.send(data);
+    },
+  };
+};
+
+/**
+ * Create the client. Nothing happens until `connect` — constructing one during
+ * page setup must not dial anything, since most readers never press Connect.
+ */
+export const createWsClient = (options: WsClientOptions): WsClient => {
+  const create = options.create ?? defaultCreate;
+  const now = options.now ?? Date.now;
+  let socket: SocketLike | null = null;
+  let state: WsState = "idle";
+
+  const transition = (next: WsState, detail?: string): void => {
+    state = next;
+    options.onState(next, detail);
+  };
+
+  const connect = (url: string): void => {
+    if (state === "connecting" || state === "open") {
+      return;
+    }
+    transition("connecting");
+    const next = create(url);
+    socket = next;
+    // Every listener below is scoped to the socket it was wired for: a browser
+    // can deliver a discarded socket's error/close/message after `disconnect`
+    // or after the reader reconnected, and replaying those would report the
+    // dead connection's fate as the live one's.
+    const stale = (): boolean => socket !== next;
+    next.addEventListener("open", () => {
+      if (stale()) {
+        return;
+      }
+      transition("open");
+    });
+    next.addEventListener("message", (event) => {
+      if (stale()) {
+        return;
+      }
+      options.onFrame({
+        at: now(),
+        direction: "received",
+        // Binary frames arrive as Blob/ArrayBuffer; showing their stringified
+        // form beats showing nothing while the reader debugs a payload.
+        text: isString(event.data) ? event.data : String(event.data),
+      });
+    });
+    next.addEventListener("error", () => {
+      if (stale()) {
+        return;
+      }
+      transition("error");
+    });
+    next.addEventListener("close", (event) => {
+      // Once settled, stay settled: browsers always follow an error event with
+      // a close event, and the error is the message worth keeping. A close that
+      // answers our own `disconnect` has been reported already.
+      if (stale() || state === "error" || state === "closed") {
+        return;
+      }
+      // Code plus the reason when the server bothered to send one; a bare
+      // close stays blank so the UI says just "closed", not a meaningless "0".
+      const detail = [event.code, event.reason].filter(
+        (part) => part !== undefined && part !== ""
+      );
+      transition("closed", detail.length > 0 ? detail.join(" ") : undefined);
+    });
+  };
+
+  const disconnect = (): void => {
+    if (!socket) {
+      return;
+    }
+    socket.close();
+    socket = null;
+    transition("closed");
+  };
+
+  const send = (text: string): boolean => {
+    if (state !== "open") {
+      return false;
+    }
+    socket?.send(text);
+    options.onFrame({ at: now(), direction: "sent", text });
+    return true;
+  };
+
+  return { connect, disconnect, send, state: () => state };
+};

package/src/core/config-input.ts

@@ -1,12 +1,14 @@
 import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
+import type { AskRetrievalOptions } from "../ai/ask-context.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
   OpenApiSource,
+  OpenInChatProvider,
   SearchProvider,
   SidebarDisplay,
   SidebarItemConfig,
@@ -510,7 +512,7 @@ export type FontInput =
 export interface FontsConfig {
   /** Body / prose font. Defaults to `inter`. */
   body?: FontInput;
-  /** Display / heading font. Defaults to `inter-tight`. */
+  /** Display / heading font. Defaults to `inter` (shared with the body). */
   display?: FontInput;
   /** Monospace / code font. Defaults to `ibm-plex-mono`. */
   mono?: FontInput;
@@ -636,6 +638,28 @@ export interface AskSuggestion {
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
 
+/** How much retrieved documentation each Ask AI question carries. */
+export interface AskRetrievalConfig {
+  /**
+   * Total injected documentation characters, across all excerpts. Defaults to
+   * `10000`. The single biggest lever on time-to-first-token — the model reads
+   * every injected character before it emits a token.
+   */
+  contextBudget?: number;
+  /**
+   * Characters kept per excerpt. Defaults to `2000`. Raise it when one long
+   * page holds the whole answer (a table the excerpt cuts in half); the
+   * `contextBudget` still caps the total.
+   */
+  excerptChars?: number;
+  /**
+   * Documents retrieved per question. Defaults to `6`. The page the reader is
+   * viewing is injected on top of the retrieved ones, so an answer can cite up
+   * to one page more than this.
+   */
+  maxResults?: number;
+}
+
 export interface AskConfig {
   /**
    * Name of the env var holding the provider API key. Each provider has a
@@ -665,6 +689,12 @@ export interface AskConfig {
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
   provider?: AskProvider;
+  /**
+   * How much documentation each question carries into the model's prompt.
+   * Lower values cut time-to-first-token — which dominates on a self-hosted
+   * backend — at the cost of recall. Defaults keep the built-in behavior.
+   */
+  retrieval?: AskRetrievalConfig;
   /** Starter prompts shown before the first question. */
   suggestions?: AskSuggestion[];
 }
@@ -728,6 +758,19 @@ export interface AiConfig {
   markdownComponents?: Record<string, ComponentMarkdown>;
   /** Expose the docs as an MCP server for agents. */
   mcp?: McpConfig;
+  /**
+   * The "Open in chat" page action, which opens the current page in an AI
+   * assistant pre-filled with a prompt pointing at its raw Markdown.
+   * Defaults to `true` (every provider). Set `false` to hide the action, or
+   * list a subset of providers to show, in order.
+   *
+   * ```ts
+   * ai: {
+   *   openInChat: ["claude", "chatgpt", "cursor"],
+   * }
+   * ```
+   */
+  openInChat?: boolean | OpenInChatProvider[];
   /**
    * Publish Agent Skills for discovery: a directory (resolved against the
    * project root) whose subdirectories each hold a `SKILL.md`. Skills are
@@ -1175,6 +1218,15 @@ interface ReferenceConfig {
   enabled?: boolean;
   /** Start nested schema rows expanded (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
+  /**
+   * The interactive "Try it" panel on operation pages (Blume renderer). On by
+   * default; `false` hides it. `proxy` is the CORS escape hatch the OpenAPI
+   * Send button routes requests through: a proxy URL, or `true` for the
+   * built-in `/_api-proxy` endpoint (which requires
+   * `deployment.output: "server"`). `proxy` is OpenAPI-only — an event
+   * composer's WebSocket connect is direct.
+   */
+  playground?: boolean | { enabled?: boolean; proxy?: boolean | string };
   /** Who renders the reference. Defaults to `blume`. */
   renderer?: "blume" | "scalar";
   /**
@@ -1465,3 +1517,17 @@ type _NoExtraOrMissingKeys = AssertExtends<
   | Exclude<keyof SchemaInput, keyof BlumeConfig>,
   never
 >;
+// The retrieval shape lives in three places: this documented config interface,
+// the schema, and the runtime `AskRetrievalOptions` that `createAskContext`
+// reads (all-optional, so plain assignability is a weak-type check that a
+// renamed field slips through — the value would be baked into the generated
+// endpoint and silently ignored at request time). `Required` makes a rename in
+// either copy a missing property, which stops compiling.
+type _AskRetrievalMatchesRuntime = AssertExtends<
+  Required<AskRetrievalConfig>,
+  Required<AskRetrievalOptions>
+>;
+type _AskRuntimeMatchesRetrieval = AssertExtends<
+  Required<AskRetrievalOptions>,
+  Required<AskRetrievalConfig>
+>;

package/src/core/content-assets.ts

@@ -1,7 +1,14 @@
-import { existsSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import { dirname, extname, relative, resolve } from "pathe";
+import {
+  basename,
+  dirname,
+  extname,
+  normalize,
+  relative,
+  resolve,
+} from "pathe";
 
 import { normalizeBasePath } from "./base-path.ts";
 import { hashText } from "./sources/cache.ts";
@@ -65,30 +72,74 @@ export const contentAssetParam = (
   return rel;
 };
 
+/** Percent-decode an image target; malformed escapes stay verbatim. */
+const decodeTarget = (target: string): string => {
+  try {
+    return decodeURI(target);
+  } catch {
+    return target;
+  }
+};
+
+/**
+ * Whether a target is *shaped* like a colocated image reference: a relative
+ * filesystem path with an image extension. Exported so link validation can
+ * tell "not a colocated candidate" apart from "a candidate that resolves
+ * nowhere" — the former falls through to the public-dir probe, the latter is
+ * a broken reference beside the page source.
+ */
+export const isRelativeImageTarget = (target: string): boolean =>
+  isRelativeTarget(target) &&
+  IMAGE_EXTENSIONS.has(extname(decodeTarget(target)).toLowerCase());
+
+/**
+ * Whether `abs` is a file whose trailing `segments` names match the on-disk
+ * entries exactly. A bare `existsSync` accepts `./Diagram.PNG` for
+ * `diagram.png` (or a directory named like an image) on a case-insensitive
+ * filesystem — the reference then validates and serves locally but breaks on
+ * the case-sensitive Linux build.
+ */
+const existsAsWritten = (abs: string, segments: number): boolean => {
+  let current = abs;
+  for (let i = 0; i < segments; i += 1) {
+    const parent = dirname(current);
+    let entries: string[];
+    try {
+      entries = readdirSync(parent);
+    } catch {
+      return false;
+    }
+    if (!entries.includes(basename(current))) {
+      return false;
+    }
+    current = parent;
+  }
+  const stat = statSync(abs, { throwIfNoEntry: false });
+  return stat !== undefined && stat.isFile();
+};
+
 /**
  * Resolve one image target against its page's directory. Returns the absolute
  * file path when the target is relative, is an image, and exists on disk —
  * anything else (remote URLs, `public/` absolutes, broken refs, code-block
- * examples that happen to look like paths) is null and left untouched.
+ * examples that happen to look like paths) is null and left untouched. Shared
+ * with link validation, so what counts as a colocated image is decided once.
  */
-const resolveRelativeImage = (
+export const resolveRelativeImage = (
   sourceDir: string,
   target: string
 ): string | null => {
-  if (!isRelativeTarget(target)) {
-    return null;
-  }
-  let decoded = target;
-  try {
-    decoded = decodeURI(target);
-  } catch {
-    // Malformed escapes — try the raw text.
-  }
-  if (!IMAGE_EXTENSIONS.has(extname(decoded).toLowerCase())) {
+  if (!isRelativeImageTarget(target)) {
     return null;
   }
+  const decoded = decodeTarget(target);
+  // Only the segments the author wrote are checked against on-disk names;
+  // `sourceDir`'s own casing is the filesystem's business, not the target's.
+  const segments = normalize(decoded)
+    .split("/")
+    .filter((part) => part !== "" && part !== "..").length;
   const abs = resolve(sourceDir, decoded);
-  return existsSync(abs) ? abs : null;
+  return existsAsWritten(abs, segments) ? abs : null;
 };
 
 /** Encode an endpoint param for use in a Markdown URL, keeping `/` separators. */

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
@@ -29,6 +30,14 @@ export interface BlumeLogo {
 export interface BlumeFavicon {
   href: string;
   type?: string;
+  /**
+   * Dark-scheme variant: the `-dark` sibling of the resolved icon file (e.g.
+   * `icon.svg` → `icon-dark.svg`), or the bundled default pair. When set, the
+   * layout emits an unconditional light link plus both icons behind
+   * `media="(prefers-color-scheme: …)"` so a dark mark doesn't vanish against
+   * dark browser chrome.
+   */
+  dark?: { href: string; type?: string };
 }
 
 /** Announcement banner, normalized from its config (string shorthand or object). */
@@ -150,6 +159,11 @@ export interface BlumeDataConfig {
      */
     site?: string;
   };
+  /**
+   * "Open in chat" page-action providers (`ai.openInChat`), in display order;
+   * empty hides the action.
+   */
+  openInChat: ResolvedConfig["ai"]["openInChat"];
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
   search: {
@@ -192,8 +206,8 @@ export interface BlumeClientData {
 export interface BlumeData {
   config: BlumeDataConfig;
   feeds: BlumeFeed[];
-  /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
-  fontCssVars: string[];
+  /** Configured fonts for the head: CSS variable + preload weights per family. */
+  fontCssVars: FontHead[];
   /** Sidebar + tab tree for the default locale. */
   navigation: Navigation;
   /** Per-locale navigation trees, keyed by locale code (empty without i18n). */

package/src/core/last-modified.ts

@@ -2,12 +2,35 @@ import { execFileSync } from "node:child_process";
 
 import { relative } from "pathe";
 
+import type { Diagnostic } from "./types.ts";
+
 /** Normalized form of the `lastModified` config. */
 export interface ResolvedLastModified {
   enabled: boolean;
   source: "git" | "frontmatter";
 }
 
+/**
+ * Env for git invocations, with the repo-locating GIT_* variables stripped. A
+ * parent git process exports an absolute GIT_DIR (and friends) to its hooks —
+ * husky pre-commit in a linked worktree, post-merge, CI wrappers — and an
+ * inherited GIT_DIR overrides `-C` discovery, silently pointing every call at
+ * the parent's repository instead of the project's.
+ */
+const GIT_LOCATION_VARS = new Set([
+  "GIT_COMMON_DIR",
+  "GIT_DIR",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_PREFIX",
+  "GIT_WORK_TREE",
+]);
+
+const gitEnv = (): NodeJS.ProcessEnv =>
+  Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !GIT_LOCATION_VARS.has(key))
+  );
+
 /** Normalize the `lastModified` config union into `{ enabled, source }`. */
 export const resolveLastModifiedConfig = (
   value: boolean | { type: "git" | "frontmatter" }
@@ -64,7 +87,7 @@ export const gitLastModifiedTimes = (
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
       "git",
       ["-C", root, "rev-parse", "--show-toplevel"],
-      { encoding: "utf-8" }
+      { encoding: "utf-8", env: gitEnv() }
     ).trim();
     const output = execFileSync(
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
@@ -80,7 +103,7 @@ export const gitLastModifiedTimes = (
         "--",
         ...contentRoots,
       ],
-      { encoding: "utf-8", maxBuffer: 256 * 1024 * 1024 }
+      { encoding: "utf-8", env: gitEnv(), maxBuffer: 256 * 1024 * 1024 }
     );
     const byRepoPath = parseGitLog(output);
     const result = new Map<string, string>();
@@ -95,3 +118,54 @@ export const gitLastModifiedTimes = (
     return new Map();
   }
 };
+
+/**
+ * Whether the repository containing `root` is a shallow clone. Returns false
+ * when git is unavailable or the project isn't a repo — those cases already
+ * yield no dates at all, and the shallow warning would only mislead.
+ */
+export const isShallowGitRepository = (root: string): boolean => {
+  try {
+    return (
+      execFileSync(
+        // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
+        "git",
+        ["-C", root, "rev-parse", "--is-shallow-repository"],
+        // stderr silenced: outside a repository the probe fails by design.
+        {
+          encoding: "utf-8",
+          env: gitEnv(),
+          stdio: ["ignore", "pipe", "ignore"],
+        }
+      ).trim() === "true"
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A warning for git-derived dates silently missing because the build ran in a
+ * shallow clone — the default on Vercel and `actions/checkout`, where `git log`
+ * only sees the last few commits, so most pages get no date and the sitemap's
+ * `<lastmod>` / "Last updated" stamps quietly disappear in production while
+ * working locally. Empty when every page got a date or the clone isn't
+ * shallow.
+ */
+export const lastModifiedShallowWarning = (
+  root: string,
+  undatedCount: number
+): Diagnostic[] => {
+  if (undatedCount === 0 || !isShallowGitRepository(root)) {
+    return [];
+  }
+  return [
+    {
+      code: "BLUME_SHALLOW_GIT_HISTORY",
+      message: `lastModified is on, but this build runs in a shallow git clone, so ${undatedCount} page(s) have no git-derived date — their sitemap <lastmod> and "Last updated" stamps are omitted.`,
+      severity: "warning",
+      suggestion:
+        "Fetch full history in CI: set the VERCEL_DEEP_CLONE=true environment variable on Vercel, or fetch-depth: 0 for actions/checkout.",
+    },
+  ];
+};

package/src/core/links.ts

@@ -1,8 +1,12 @@
 import { existsSync } from "node:fs";
 
-import { basename, join } from "pathe";
+import { basename, dirname, join } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
+import {
+  isRelativeImageTarget,
+  resolveRelativeImage,
+} from "./content-assets.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
@@ -154,7 +158,8 @@ const checkAnchor = (
 const checkPathLink = (
   resolved: string,
   fragment: string,
-  target: string,
+  page: PageRecord,
+  link: PageLink,
   site: LinkSite,
   ctx: LinkContext
 ): LinkResult => {
@@ -186,6 +191,27 @@ const checkPathLink = (
     if (assetIsPresent(assetPath, ctx)) {
       return null;
     }
+    // A colocated image embed (`![](./diagram.png)`) is resolved from beside
+    // the page source and emitted to `_astro/` by the image pipeline, so it
+    // never lands in `public/`. The *raw* target goes through the same
+    // resolver that decides what the `/blume-assets/content` endpoint serves,
+    // so a reference the rewriter skips (a `?v=2` suffix, a double-encoded
+    // name) is reported here, not accepted. Plain links to the same path stay
+    // on the public-dir probe — an href resolves as a site route, and only
+    // image nodes are rewritten.
+    if (link.image && page.sourcePath && isRelativeImageTarget(link.target)) {
+      if (resolveRelativeImage(dirname(page.sourcePath), link.target)) {
+        return null;
+      }
+      return {
+        ...site,
+        code: "BLUME_BROKEN_ASSET",
+        message: `Image ${link.target} was not found next to ${basename(page.sourcePath)}.`,
+        severity: "warning",
+        suggestion:
+          "Add the file next to the page source or fix the reference.",
+      };
+    }
     // Nowhere to look: no `public/` directory.
     if (ctx.publicDir === null) {
       return "asset-unchecked";
@@ -202,7 +228,7 @@ const checkPathLink = (
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
-    message: `Broken link to ${target}: no page resolves to ${route}.`,
+    message: `Broken link to ${link.target}: no page resolves to ${route}.`,
     severity: "error",
     suggestion: "Check the path, or create the target page.",
   };
@@ -279,7 +305,7 @@ const classifyLink = (
   const resolved = rawPath.startsWith("/")
     ? rawPath
     : resolveRelative(page.route, rawPath, isIndexPage(page));
-  return checkPathLink(resolved, fragment, target, site, ctx);
+  return checkPathLink(resolved, fragment, page, link, site, ctx);
 };
 
 /**

package/src/core/navigation.ts

@@ -20,6 +20,28 @@ const NUMERIC_PREFIX = /^(?<order>\d+)[-_.]/u;
 const GROUP_FOLDER = /^\((?<label>.+)\)$/u;
 const WORD_SPLIT = /[-_]/u;
 
+/**
+ * Whether `route` is the section root `base` or nested beneath it. Requires a
+ * path boundary, so `/api-reference` is not under `/api`. The root `/` spans
+ * every route.
+ */
+export const isUnderPath = (route: string, base: string): boolean =>
+  base === "/" || route === base || route.startsWith(`${base}/`);
+
+/**
+ * Whether `tab` is the root tab of the tree rooted at `root` — the tab that
+ * spans the whole sidebar rather than one section. Tab paths and the root
+ * normally share one path space, so the root tab sits at `root` exactly (`/`,
+ * `/en`, `/docs`); in an archived version tree the root is versionized
+ * (`/v1.0`, `/docs/v1.0`) while tab paths stay in current-docs space, so the
+ * root tab is any tab the whole root sits under. The one definition shared by
+ * sidebar scoping, tab-section hoisting, and the header's current-tab state —
+ * consumers that disagree on which tab is the root tab prune an archived
+ * sidebar or highlight the wrong tab over it.
+ */
+export const isRootTab = (tab: NavTab, root: string): boolean =>
+  isUnderPath(root, tab.path);
+
 const humanize = (segment: string): string =>
   segment
     .replace(NUMERIC_PREFIX, "")
@@ -896,6 +918,9 @@ export const buildNavigation = (
   // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
   // under a base, falsely scope a group named like the prefix). Carried on the
   // returned navigation so render-time scoping compares in the same space too.
+  // In a version snapshot the root arrives versionized (`/v1.0`) while tab
+  // paths stay in current-docs space, so root-tab checks use `isRootTab`
+  // containment, not equality.
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
 
   // Emitted here, before the sidebar-mode branch: an explicit config sidebar
@@ -930,7 +955,7 @@ export const buildNavigation = (
     sharedMetaPrefix,
     display,
     new Set(
-      tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+      tabs.flatMap((tab) => (isRootTab(tab, rootTabPath) ? [] : [tab.path]))
     ),
     diagnostics
   );