blume 1.4.3 → 1.5.0

package/src/cli/dev-lock.ts

@@ -29,15 +29,32 @@ export interface DevLockInfo {
 
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
-const isValidPid = (pid: unknown): pid is number =>
+/** What `JSON.parse` can yield for a lock file body. */
+type LockFileValue =
+  | string
+  | number
+  | boolean
+  | null
+  | LockFileValue[]
+  | { [key: string]: LockFileValue };
+
+const isValidPid = (pid: LockFileValue | undefined): pid is number =>
   typeof pid === "number" && Number.isInteger(pid) && pid > 0;
 
+const isPortNumber = (port: LockFileValue | undefined): port is number =>
+  typeof port === "number";
+
+const isLockRecord = (
+  data: LockFileValue
+): data is { pid?: LockFileValue; port?: LockFileValue } =>
+  typeof data === "object" && data !== null;
+
 /**
  * Parse a lock file body. Current locks are JSON (`{"pid":123,"port":3001}`);
  * a bare integer (the pre-port format) still parses as a pid-only lock.
  */
 const parseLock = (raw: string): DevLockInfo | null => {
-  let data: unknown;
+  let data: LockFileValue;
   try {
     data = JSON.parse(raw.trim());
   } catch {
@@ -46,10 +63,10 @@ const parseLock = (raw: string): DevLockInfo | null => {
   if (isValidPid(data)) {
     return { pid: data };
   }
-  if (typeof data === "object" && data !== null) {
-    const { pid, port } = data as { pid?: unknown; port?: unknown };
+  if (isLockRecord(data)) {
+    const { pid, port } = data;
     if (isValidPid(pid)) {
-      return typeof port === "number" ? { pid, port } : { pid };
+      return isPortNumber(port) ? { pid, port } : { pid };
     }
   }
   return null;
@@ -63,6 +80,7 @@ const isProcessAlive = (pid: number): boolean => {
   } catch (error) {
     // EPERM means the process exists but belongs to another user — still
     // live, so the lock must hold (only ESRCH proves it's gone).
+    // SAFETY: `process.kill` failures are errno exceptions.
     return (error as NodeJS.ErrnoException).code === "EPERM";
   }
 };
@@ -84,11 +102,13 @@ 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 lockPayload = (port?: number): string => {
+  const info: DevLockInfo = { pid: process.pid };
+  if (port !== undefined) {
+    info.port = port;
+  }
+  return JSON.stringify(info);
+};
 
 const writeLock = (outDir: string, port?: number): void => {
   writeFileSync(lockPath(outDir), lockPayload(port));
@@ -128,6 +148,7 @@ const tryClaimLock = (outDir: string, port?: number): boolean => {
     writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
     return true;
   } catch (error) {
+    // SAFETY: `writeFileSync` failures are errno exceptions.
     if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
       throw error;
     }

package/src/cli/eject-scripts.ts

@@ -5,6 +5,21 @@ import { join } from "pathe";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 
+/** A JSON value, as `JSON.parse` of a manifest can return. */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** The slice of package.json the rewrite touches; the rest rides along. */
+interface PackageManifest {
+  [key: string]: JsonValue | undefined;
+  scripts?: Record<string, string>;
+}
+
 /**
  * The `blume build`-only artifacts this project's config actually produces, as
  * notice lines for the eject command. After an eject the build script runs
@@ -55,13 +70,13 @@ export const droppedArtifactNotices = (config: ResolvedConfig): string[] => {
  */
 export const updatePackageScripts = async (root: string): Promise<void> => {
   const pkgPath = join(root, "package.json");
-  let pkg: Record<string, unknown>;
+  let pkg: PackageManifest;
   try {
     pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
   } catch {
     return;
   }
-  const scripts = (pkg.scripts ?? {}) as Record<string, string>;
+  const scripts = pkg.scripts ?? {};
   pkg.scripts = {
     ...scripts,
     build: "astro build",

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
 import { translateCommand } from "./commands/translate.ts";
 import { validateCommand } from "./commands/validate.ts";
+import { versionCommand } from "./commands/version.ts";
 import { loadEnvFiles } from "./env.ts";
 import { reportInternalError } from "./internal-error.ts";
 
@@ -39,6 +40,7 @@ const main = defineCommand({
     sync: syncCommand,
     translate: translateCommand,
     validate: validateCommand,
+    version: versionCommand,
   },
 });
 

package/src/cli/init/questions.ts

@@ -52,7 +52,7 @@ export interface InitFlags {
   template?: Template;
 }
 
-const cancelled = (value: unknown): value is symbol =>
+const cancelled = (value: string | string[] | symbol): value is symbol =>
   typeof value === "symbol";
 
 /**

package/src/cli/init/scaffold.ts

@@ -54,7 +54,7 @@ interface Starter {
 const page = (title: string, description: string, body: string): string =>
   `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
 
-export const STARTERS: Record<Template, Starter> = {
+export const STARTERS = {
   api: {
     configExtra: `
   openapi: {
@@ -135,16 +135,14 @@ export const STARTERS: Record<Template, Starter> = {
       },
     ],
   },
-};
+} satisfies Record<Template, Starter>;
 
 /**
  * Install + dev commands to print for the chosen package manager, plus the
  * prefix that runs a locally installed bin (`exec`, e.g. `npx blume eject`) —
  * dependency bins aren't on PATH, so a bare `blume …` hint would not run.
  */
-export const commandsFor = (
-  pm: PackageManager
-): { build: string; dev: string; exec: string; install: string } => ({
+export const commandsFor = (pm: PackageManager) => ({
   // `bun build` invokes Bun's bundler, not the package.json `build` script —
   // unlike `bun dev`, the script name is shadowed by a builtin subcommand.
   build: pm === "npm" || pm === "bun" ? `${pm} run build` : `${pm} build`,
@@ -153,6 +151,9 @@ export const commandsFor = (
   install: `${pm} install`,
 });
 
+const isPackageManager = (value: string): value is PackageManager =>
+  PACKAGE_MANAGERS.some((pm) => pm === value);
+
 /**
  * Derive the package manager from an npm user-agent string (the first
  * `name/version` token of `npm_config_user_agent`), falling back to npm.
@@ -160,8 +161,8 @@ export const commandsFor = (
  * runner is the only signal.
  */
 export const detectPackageManager = (userAgent?: string): PackageManager => {
-  const name = userAgent?.split("/")[0] as PackageManager | undefined;
-  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : "npm";
+  const name = userAgent?.split("/")[0];
+  return name !== undefined && isPackageManager(name) ? name : "npm";
 };
 
 /**
@@ -176,8 +177,8 @@ export const detectProjectPackageManager = async (
   root: string
 ): Promise<PackageManager> => {
   const detected = await detect({ cwd: root });
-  const name = detected?.name as PackageManager | undefined;
-  return name !== undefined && PACKAGE_MANAGERS.includes(name)
+  const name = detected?.name;
+  return name !== undefined && isPackageManager(name)
     ? name
     : detectPackageManager(process.env.npm_config_user_agent);
 };
@@ -216,7 +217,7 @@ const hasRemoteSource = (sources: SourceKind[]): boolean =>
  * Config snippets for each remote source kind, with placeholder values to
  * replace and comments naming the env var each source authenticates with.
  */
-const SOURCE_SNIPPETS: Record<Exclude<SourceKind, "filesystem">, string> = {
+const SOURCE_SNIPPETS = {
   "github-releases": `      // Changelog entries from GitHub Releases. Private repos read
       // GITHUB_TOKEN from the environment.
       {
@@ -247,7 +248,7 @@ const SOURCE_SNIPPETS: Record<Exclude<SourceKind, "filesystem">, string> = {
         query: \`*[_type == "doc"]\`,
         prefix: "sanity",
       },`,
-};
+} satisfies Record<Exclude<SourceKind, "filesystem">, string>;
 
 /**
  * The `content` block for the generated config, or an empty string when the
@@ -293,10 +294,16 @@ export default defineConfig({
 `;
 
 /** SDK dependencies required by the selected remote sources. */
-const extraDepsFor = (sources: SourceKind[]): Record<string, string> => ({
-  ...(sources.includes("notion") && { "@notionhq/client": "^2.2.15" }),
-  ...(sources.includes("sanity") && { "@sanity/client": "^7.25.0" }),
-});
+const extraDepsFor = (sources: SourceKind[]) => {
+  const deps: Record<string, string> = {};
+  if (sources.includes("notion")) {
+    deps["@notionhq/client"] = "^2.2.15";
+  }
+  if (sources.includes("sanity")) {
+    deps["@sanity/client"] = "^7.25.0";
+  }
+  return deps;
+};
 
 /** Every file `init` should write for the given answers, package.json first. */
 export const buildPlan = (

package/src/cli/internal-error.ts

@@ -33,6 +33,7 @@ export const remapBlumeStack = (stack: string): string =>
  * message, a trimmed stack, and an environment dump for bug reports. Callers
  * exit after this — it doesn't exit itself, so it's testable.
  */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- last-resort handler for whatever a catch clause caught; anything narrower would force casts at every call site
 export const reportInternalError = (error: unknown): void => {
   const err = error instanceof Error ? error : new Error(String(error));
   const lines = [

package/src/components/content/auto-type-table.ts

@@ -75,6 +75,9 @@ export const extractTypeTable = async (
 ): Promise<TypeTableProperty[]> => {
   const { name, path, root = process.cwd(), source } = options;
   const tsModule = await import("typescript");
+  // SAFETY: CJS/ESM interop — the typescript package exposes its API namespace
+  // either directly or under `default` depending on the loader; both are the
+  // same object, which TypeScriptApi models structurally.
   const ts = (tsModule.default ?? tsModule) as TypeScriptApi;
 
   const compilerOptions: CompilerOptions = {

package/src/components/content/diff.ts

@@ -62,8 +62,11 @@ const registeredDiffThemeNames = new Set<string>();
  * shared between both modes must not hand light mode the dark-typed
  * registration.
  */
+const isThemeName = (theme: CodeTheme): theme is string =>
+  typeof theme === "string";
+
 const diffThemeName = (theme: CodeTheme, mode: "dark" | "light"): string => {
-  if (typeof theme === "string") {
+  if (isThemeName(theme)) {
     return theme;
   }
   const type = theme.type ?? mode;
@@ -90,7 +93,7 @@ const diffThemeName = (theme: CodeTheme, mode: "dark" | "light"): string => {
   return name;
 };
 
-const diffThemes = (themes: CodeThemes): { dark: string; light: string } => ({
+const diffThemes = (themes: CodeThemes) => ({
   dark: diffThemeName(themes.dark, "dark"),
   light: diffThemeName(themes.light, "light"),
 });
@@ -113,11 +116,12 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     theme = DEFAULT_CODE_THEMES,
   } = options;
 
-  if (patch !== undefined || src !== undefined) {
-    const text = patch ?? (await readText(src as string, root));
+  const patchText =
+    patch ?? (src === undefined ? undefined : await readText(src, root));
+  if (patchText !== undefined) {
     const result = await preloadPatchDiff({
       options: { theme: diffThemes(theme) },
-      patch: text,
+      patch: patchText,
     });
     return result.prerenderedHTML;
   }

package/src/components/content/github-info.ts

@@ -41,6 +41,8 @@ const load = async (
     return null;
   }
 
+  // SAFETY: GitHub's `GET /repos/{owner}/{repo}` contract carries these three
+  // fields on every 2xx response; a malformed body rejects into `loadSafe`.
   const data = (await response.json()) as {
     description: string | null;
     forks_count: number;

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

@@ -100,12 +100,21 @@ const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
 const EMPTY_SUGGESTIONS: Suggestion[] = [];
 
 // The toggle shortcut accepts both ⌘I and Ctrl+I; show the right modifier per
-// platform (same detection Search.astro uses for its ⌘K hint). Guarded so the
-// island still server-renders, where `navigator` doesn't exist; the hint itself
-// only renders client-side, inside the portaled panel.
+// platform (same detection Search.astro uses for its ⌘K hint). Guarded via
+// `globalThis` so the island still server-renders where `navigator` doesn't
+// exist; the hint itself only renders client-side, inside the portaled panel.
 const IS_APPLE =
-  typeof navigator !== "undefined" &&
-  /mac|iphone|ipad|ipod/iu.test(navigator.platform);
+  globalThis.navigator !== undefined &&
+  /mac|iphone|ipad|ipod/iu.test(globalThis.navigator.platform);
+
+// Duck-typed (`closest` presence) rather than `instanceof Element`, which
+// needs a DOM global the test environment doesn't provide.
+const isElementLike = (target: EventTarget | null): target is Element => {
+  // SAFETY: the cast only names the probed surface; `closest` is verified to
+  // exist before the caller uses it.
+  const candidate = target as Partial<Element> | null;
+  return typeof candidate?.closest === "function";
+};
 
 // Ghost icon button, matching the header's theme toggle and repo link.
 const TRIGGER_CLASS =
@@ -163,6 +172,8 @@ const AskAI = ({
   // The search modal forwards its query so "Ask AI: <query>" carries straight in.
   useEffect(() => {
     const handler = (event: Event) => {
+      // SAFETY: `blume:open-ask-ai` is only ever dispatched as a CustomEvent
+      // whose optional detail carries the search query.
       const query = (event as CustomEvent<{ query?: string }>).detail?.query;
       if (query) {
         setInput(query);
@@ -190,11 +201,8 @@ const AskAI = ({
         // An Escape aimed at a modal surface stacked on top (the search
         // dialog traps focus inside itself) dismisses that surface only —
         // this window listener still fires for it, and closing the panel
-        // underneath too would eat the user's conversation view. Duck-typed
-        // (`closest` presence) rather than `instanceof Element`, which needs
-        // a DOM global the test environment doesn't provide.
-        const target = event.target as Partial<Element> | null;
-        if (typeof target?.closest === "function" && target.closest("dialog")) {
+        // underneath too would eat the user's conversation view.
+        if (isElementLike(event.target) && event.target.closest("dialog")) {
           return;
         }
         setOpen(false);
@@ -346,12 +354,12 @@ const AskAI = ({
       // The closed panel is only translated off-screen; `inert` drops its
       // buttons/textarea from the tab order and the accessibility tree.
       inert={!open}
-      className={`fixed inset-y-0 end-0 z-[60] flex w-[var(--blume-ask-width)] flex-col border-border border-s bg-background shadow-2xl transition-transform duration-200 ease-out ${
+      className={`border-border bg-background fixed inset-y-0 end-0 z-[60] flex w-[var(--blume-ask-width)] flex-col border-s shadow-2xl transition-transform duration-200 ease-out ${
         open ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"
       }`}
     >
-      <header className="flex h-16 shrink-0 items-center justify-between gap-2 border-border border-b px-4">
-        <span className="font-semibold text-foreground">{t.title}</span>
+      <header className="border-border flex h-16 shrink-0 items-center justify-between gap-2 border-b px-4">
+        <span className="text-foreground font-semibold">{t.title}</span>
         <div className="flex items-center gap-0.5">
           <button
             aria-label={t.copy}
@@ -383,7 +391,7 @@ const AskAI = ({
       </header>
 
       <div
-        className="flex flex-1 flex-col scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto"
+        className="scrollbar-thumb-border flex flex-1 scrollbar-thin scrollbar-track-transparent flex-col overflow-y-auto"
         ref={scrollRef}
       >
         {hasMessages ? (
@@ -393,7 +401,7 @@ const AskAI = ({
             {messages.map((message, index) =>
               message.role === "user" ? (
                 <div
-                  className="max-w-[85%] self-end whitespace-pre-wrap rounded-blume bg-muted px-3 py-2 text-foreground text-sm"
+                  className="rounded-blume bg-muted text-foreground max-w-[85%] self-end px-3 py-2 text-sm whitespace-pre-wrap"
                   // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
                   key={index}
                 >
@@ -412,7 +420,7 @@ const AskAI = ({
                       }}
                     />
                   ) : (
-                    <span className="animate-pulse text-muted-foreground">
+                    <span className="text-muted-foreground animate-pulse">
                       …
                     </span>
                   )}
@@ -423,18 +431,18 @@ const AskAI = ({
         ) : (
           <div className="mt-auto flex flex-col gap-0.5 p-4">
             {suggestions.length === 0 && (
-              <p className="px-2 text-muted-foreground text-sm">{t.empty}</p>
+              <p className="text-muted-foreground px-2 text-sm">{t.empty}</p>
             )}
             {suggestions.map((suggestion) => (
               <button
-                className="flex cursor-pointer items-center gap-2.5 rounded-blume px-2 py-2 text-start text-foreground text-sm transition-colors hover:bg-muted"
+                className="rounded-blume text-foreground hover:bg-muted flex cursor-pointer items-center gap-2.5 px-2 py-2 text-start text-sm transition-colors"
                 key={suggestion.label}
                 onClick={() => runQuestion(suggestion.label)}
                 type="button"
               >
                 {suggestion.icon && (
                   <span
-                    className="shrink-0 text-muted-foreground [&_svg]:h-[18px] [&_svg]:w-[18px]"
+                    className="text-muted-foreground shrink-0 [&_svg]:h-[18px] [&_svg]:w-[18px]"
                     // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
                     dangerouslySetInnerHTML={{ __html: suggestion.icon }}
                   />
@@ -442,12 +450,12 @@ const AskAI = ({
                 <span>{suggestion.label}</span>
               </button>
             ))}
-            <p className="mt-3 flex items-center gap-1.5 px-2 text-muted-foreground text-sm">
+            <p className="text-muted-foreground mt-3 flex items-center gap-1.5 px-2 text-sm">
               {t.tip}
-              <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
+              <kbd className="border-border bg-muted rounded border px-1.5 py-0.5 font-sans text-xs">
                 {IS_APPLE ? "⌘" : "Ctrl"}
               </kbd>
-              <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
+              <kbd className="border-border bg-muted rounded border px-1.5 py-0.5 font-sans text-xs">
                 I
               </kbd>
             </p>
@@ -456,12 +464,12 @@ const AskAI = ({
       </div>
 
       <form
-        className="relative shrink-0 border-border border-t"
+        className="border-border relative shrink-0 border-t"
         onSubmit={onSubmit}
       >
         <textarea
           aria-label={t.label}
-          className="max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-foreground text-sm pointer-coarse:text-base outline-none placeholder:text-muted-foreground"
+          className="text-foreground placeholder:text-muted-foreground max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-sm outline-none pointer-coarse:text-base"
           onChange={(event) => setInput(event.target.value)}
           onKeyDown={onInputKeyDown}
           placeholder={t.placeholder}
@@ -471,7 +479,7 @@ const AskAI = ({
         />
         <button
           aria-label={t.send}
-          className="absolute end-3 bottom-3 inline-flex h-8 w-8 cursor-pointer items-center justify-center rounded-blume bg-foreground text-background transition-opacity disabled:cursor-not-allowed disabled:opacity-40"
+          className="rounded-blume bg-foreground text-background absolute end-3 bottom-3 inline-flex h-8 w-8 cursor-pointer items-center justify-center transition-opacity disabled:cursor-not-allowed disabled:opacity-40"
           disabled={busy || input.trim().length === 0}
           type="submit"
         >

package/src/components/islands/hooks.ts

@@ -29,7 +29,9 @@ const readClientData = (): BlumeClientData | null => {
   if (cachedData) {
     return cachedData;
   }
-  if (typeof document === "undefined") {
+  // `document` is undeclared on the server; probing `globalThis` avoids both
+  // the bare-reference ReferenceError and a `typeof` sniff.
+  if (!("document" in globalThis)) {
     return null;
   }
   const element = document.querySelector("#blume-client-data");
@@ -37,6 +39,8 @@ const readClientData = (): BlumeClientData | null => {
     return null;
   }
   try {
+    // SAFETY: the layout serialized this script tag's JSON from the same
+    // `BlumeClientData` snapshot this reads back.
     cachedData = JSON.parse(element.textContent) as BlumeClientData;
     return cachedData;
   } catch {

package/src/components/islands/webmcp.ts

@@ -16,11 +16,36 @@ interface WebMcpResult {
   isError?: boolean;
 }
 
+/** A JSON value as a WebMCP agent may supply it in a tool call. */
+export type WebMcpJsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | WebMcpJsonValue[]
+  | { [key: string]: WebMcpJsonValue };
+
+/**
+ * Tool arguments exactly as the calling agent supplied them. WebMCP doesn't
+ * guarantee schema validation, so each tool checks its own fields at runtime.
+ */
+export interface WebMcpToolArgs {
+  query?: WebMcpJsonValue;
+  route?: WebMcpJsonValue;
+}
+
+/** The JSON Schema subset these string-argument tools declare. */
+export interface WebMcpInputSchema {
+  properties: Record<string, { description: string; type: "string" }>;
+  required?: string[];
+  type: "object";
+}
+
 export interface WebMcpTool {
   annotations: { openWorldHint: boolean; readOnlyHint: boolean };
   description: string;
-  execute: (input: Record<string, unknown>) => Promise<WebMcpResult>;
-  inputSchema: Record<string, unknown>;
+  execute: (input: WebMcpToolArgs) => Promise<WebMcpResult>;
+  inputSchema: WebMcpInputSchema;
   name: string;
 }
 
@@ -31,14 +56,26 @@ export interface WebMcpTool {
  * individually via `registerTool`.
  */
 export interface ModelContext {
-  provideContext?: (context: { tools: WebMcpTool[] }) => unknown;
-  registerTool?: (tool: WebMcpTool) => unknown;
+  provideContext?: (context: { tools: WebMcpTool[] }) => void;
+  registerTool?: (tool: WebMcpTool) => void;
 }
 
-const text = (value: string, isError = false): WebMcpResult => ({
-  content: [{ text: value, type: "text" }],
-  ...(isError ? { isError: true } : {}),
-});
+const text = (value: string, isError = false): WebMcpResult => {
+  const result: WebMcpResult = { content: [{ text: value, type: "text" }] };
+  if (isError) {
+    result.isError = true;
+  }
+  return result;
+};
+
+/** Validates an agent-supplied tool argument before it is used as a string. */
+const isString = (value: WebMcpJsonValue | undefined): value is string =>
+  typeof value === "string";
+
+/** Detects which registration surface a model context actually implements. */
+const isCallable = <T extends (...args: never[]) => void>(
+  value: T | undefined
+): value is T => typeof value === "function";
 
 const TAG = /<[^>]*>?/gu;
 
@@ -89,7 +126,7 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
       description:
         "Full-text search across this documentation site. Returns matching pages with their title, URL, and a short excerpt.",
       async execute(input) {
-        const query = typeof input.query === "string" ? input.query : "";
+        const query = isString(input.query) ? input.query : "";
         if (!query.trim()) {
           return text("Provide a non-empty `query` string.", true);
         }
@@ -128,7 +165,7 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
     description:
       "Fetch a page of this site as plain Markdown. Pass the page's root-relative route, e.g. `/quickstart`.",
     async execute(input) {
-      const route = typeof input.route === "string" ? input.route : "";
+      const route = isString(input.route) ? input.route : "";
       if (!route.startsWith("/")) {
         return text("Pass a root-relative route, e.g. `/quickstart`.", true);
       }
@@ -189,11 +226,11 @@ export const registerWebMcpTools = (
   if (!context) {
     return false;
   }
-  if (typeof context.provideContext === "function") {
+  if (isCallable(context.provideContext)) {
     context.provideContext({ tools });
     return true;
   }
-  if (typeof context.registerTool === "function") {
+  if (isCallable(context.registerTool)) {
     for (const tool of tools) {
       context.registerTool(tool);
     }

package/src/components/layout/Header.astro

@@ -5,7 +5,11 @@ import { withBase } from "../islands/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
-import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
+import type {
+  LocaleSwitchOption,
+  Navigation,
+  NavSelector as NavSelectorConfig,
+} from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
@@ -50,8 +54,16 @@ interface Props {
   /** Localized chrome labels (nav toggle, sections, GitHub, theme toggle). */
   navStrings?: UIStrings["nav"];
   localeSwitch?: LocaleSwitchOption[];
+  /**
+   * Auto-populated version switcher, rendered ahead of the configured
+   * selectors. `null`/absent when versioning is off — or when the user
+   * declares their own `kind: "version"` selector, which then owns the UI.
+   */
+  versionSelector?: NavSelectorConfig | null;
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
+  /** Viewed docs version for search filtering (`""` = current; `null`/absent = off). */
+  searchVersion?: string | null;
   /**
    * Layout-slot overrides forwarded from the root layout. The header honors
    * `Logo` and `Search` here so those pieces can be replaced without swapping
@@ -77,7 +89,9 @@ const {
   switcherStrings,
   navStrings,
   localeSwitch,
+  versionSelector,
   searchLocale,
+  searchVersion = null,
   layout = {},
 } = Astro.props;
 
@@ -167,6 +181,15 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     )
   }
   <div class="flex-1"></div>
+  {
+    /* Right-aligned next to the language switcher: the spacer absorbs its
+       width, so pages without a version selector (blog, generated references)
+       keep the logo, tabs, and the rest of this cluster in place — no layout
+       shift when crossing into the docs. */
+    versionSelector && (
+      <NavSelector align="end" route={route} selector={versionSelector} />
+    )
+  }
   {
     localeSwitch && localeSwitch.length > 1 && (
       <LanguageSwitcher
@@ -184,6 +207,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
         navigation={navigation}
         popularPages={data.config.search.popular}
         strings={searchStrings}
+        version={searchVersion}
       />
     )
   }