blume 1.1.3 → 1.1.4

package/src/audit/checks/sitemap.ts

@@ -3,7 +3,7 @@ import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
-import { normalizePath, siteOrigin } from "../url.ts";
+import { decodePath, normalizePath, siteOrigin } from "../url.ts";
 
 const MAX_SITEMAP_BYTES = 50 * 1024 * 1024;
 const MAX_SITEMAP_URLS = 50_000;
@@ -18,12 +18,24 @@ const LASTMOD_SLACK_MS = 24 * 60 * 60 * 1000;
 /** Error routes are never crawlable destinations, so they belong out of the sitemap. */
 const ERROR_ROUTES = new Set(["/404", "/500"]);
 
-/** Site paths listed in the sitemap, normalized for comparison against page URLs. */
-const sitemapPaths = (context: AuditContext): Map<string, string> => {
+/**
+ * Site paths listed in the sitemap, normalized for comparison against page
+ * URLs. `<loc>`s carry the deployment base and are `encodeURI`'d; page URLs
+ * (from the file tree) carry neither, so both are undone here.
+ */
+const sitemapPaths = (
+  context: AuditContext,
+  deployBase: string
+): Map<string, string> => {
   const paths = new Map<string, string>();
   for (const loc of context.sitemap?.urls ?? []) {
     try {
-      paths.set(normalizePath(new URL(loc).pathname), loc);
+      paths.set(
+        normalizePath(
+          stripBasePath(deployBase, decodePath(new URL(loc).pathname))
+        ),
+        loc
+      );
     } catch {
       // A malformed <loc> is reported by SITEMAP_INVALID, not here.
     }
@@ -31,10 +43,20 @@ const sitemapPaths = (context: AuditContext): Map<string, string> => {
   return paths;
 };
 
-/** The path of a canonical URL, or null when it isn't parseable (CANONICAL_BAD_TARGET reports that). */
-const canonicalPath = (canonical: string): string | null => {
+/**
+ * The path of a canonical URL, or null when it isn't parseable
+ * (CANONICAL_BAD_TARGET reports that). Canonicals are emitted as
+ * `site + base + route`, so the deployment base is stripped to keep the result
+ * comparable against base-less page URLs.
+ */
+const canonicalPath = (
+  canonical: string,
+  deployBase: string
+): string | null => {
   try {
-    return normalizePath(new URL(canonical).pathname);
+    return normalizePath(
+      stripBasePath(deployBase, decodePath(new URL(canonical).pathname))
+    );
   } catch {
     return null;
   }
@@ -45,7 +67,8 @@ const checkListedUrl = (
   context: AuditContext,
   loc: string,
   origin: string | null,
-  file: string
+  file: string,
+  deployBase: string
 ): Diagnostic[] => {
   let parsed: URL;
   try {
@@ -70,12 +93,10 @@ const checkListedUrl = (
     ];
   }
 
-  // `<loc>`s carry the deployment base; page URLs (from the file tree) don't.
+  // `<loc>`s carry the deployment base and are `encodeURI`'d; page URLs (from
+  // the file tree) are neither.
   const path = normalizePath(
-    stripBasePath(
-      normalizeBasePath(context.project.config.deployment.base),
-      parsed.pathname
-    )
+    stripBasePath(deployBase, decodePath(parsed.pathname))
   );
   const page = context.byUrl.get(path);
   if (!page) {
@@ -104,7 +125,7 @@ const checkListedUrl = (
     );
   }
 
-  const canonical = page.canonical && canonicalPath(page.canonical);
+  const canonical = page.canonical && canonicalPath(page.canonical, deployBase);
   if (canonical && canonical !== path) {
     found.push(
       finding(
@@ -198,10 +219,15 @@ export const sitemapChecks: CheckModule = {
     }
 
     const origin = siteOrigin(site);
-    const listed = sitemapPaths(context);
+    const deployBase = normalizeBasePath(
+      context.project.config.deployment.base
+    );
+    const listed = sitemapPaths(context, deployBase);
 
     for (const loc of sitemap.urls) {
-      found.push(...checkListedUrl(context, loc, origin, sitemap.file));
+      found.push(
+        ...checkListedUrl(context, loc, origin, sitemap.file, deployBase)
+      );
     }
 
     // The other direction: a page that was built, is indexable, and should be

package/src/audit/redirects.ts

@@ -19,6 +19,17 @@ interface ConfiguredRedirect {
  * An external destination (`https://…`) is always `ok`: it's outside the site,
  * so there's no local page to check it against.
  */
+/**
+ * A destination's page path: the part before any query string or fragment. A
+ * redirect to `/guide#setup` or `/search?q=x` lands on the `/guide` / `/search`
+ * page — the suffix belongs to the browser, not the file tree, so keeping it
+ * would report a working redirect as broken.
+ */
+const pathOnly = (value: string): string => {
+  const cut = value.search(/[?#]/u);
+  return cut === -1 ? value : value.slice(0, cut);
+};
+
 export const resolveRedirects = (
   redirects: readonly ConfiguredRedirect[],
   pageUrls: ReadonlySet<string>
@@ -40,7 +51,7 @@ export const resolveRedirects = (
         chain.push(current);
         break;
       }
-      const next = normalizePath(current);
+      const next = normalizePath(pathOnly(current));
       if (seen.has(next)) {
         chain.push(next);
         return {

package/src/audit/run.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 
-import { normalizeBasePath } from "../core/base-path.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { deployStaticDir } from "../deploy/adapter-output.ts";
@@ -123,9 +123,10 @@ const matches = (id: CheckId, terms: string[]): boolean => {
 export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
   const { project } = options;
   const staticDir = deployStaticDir(project.config, project.context);
+  const basePath = normalizeBasePath(project.config.basePath);
 
   const crawl = await crawlStaticDir({
-    basePath: normalizeBasePath(project.config.basePath),
+    basePath,
     manifest: project.manifest,
     staticDir,
   });
@@ -148,7 +149,16 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
     pages: crawl.pages,
     project,
     redirects: resolveRedirects(
-      project.config.redirects,
+      // Redirects are authored as if mounted at root; the built page URLs they
+      // are checked against carry `basePath` (it's a real directory in the
+      // build), so both sides gain it here — mirroring what
+      // `applyBaseToAstroRedirects` does at build time. `withBasePath` is
+      // idempotent and leaves external `to` URLs untouched.
+      project.config.redirects.map((redirect) => ({
+        ...redirect,
+        from: withBasePath(basePath, redirect.from),
+        to: withBasePath(basePath, redirect.to),
+      })),
       // Pages and static files both: a redirect may legitimately land on a
       // served asset (`/old-whitepaper` -> `/files/whitepaper.pdf`).
       new Set(

package/src/audit/url.ts

@@ -22,6 +22,21 @@ export const normalizePath = (path: string): string => {
   return trimmed === "" ? "/" : trimmed;
 };
 
+/**
+ * Percent-decode a pathname for comparison against the built file tree. Page
+ * URLs and file-index keys come from raw on-disk names, while `URL#pathname`
+ * (and the `encodeURI`'d sitemap `<loc>`s) are percent-encoded — a Japanese
+ * route would never match its own page without this. Malformed sequences are
+ * kept as-is: they can't have come from our own encoder.
+ */
+export const decodePath = (path: string): string => {
+  try {
+    return decodeURI(path);
+  } catch {
+    return path;
+  }
+};
+
 /** The origin of `deployment.site`, or null when no site is configured. */
 export const siteOrigin = (site?: string): string | null => {
   if (!site) {
@@ -73,7 +88,9 @@ export const resolveHref = (
       return {
         hash: parsed.hash.slice(1),
         kind: "self-origin",
-        path: normalizePath(stripBasePath(deployBase, parsed.pathname)),
+        path: normalizePath(
+          stripBasePath(deployBase, decodePath(parsed.pathname))
+        ),
       };
     }
     return { kind: "external", url: parsed.toString() };
@@ -98,6 +115,8 @@ export const resolveHref = (
   return {
     hash: resolved.hash.slice(1),
     kind: "internal",
-    path: normalizePath(stripBasePath(deployBase, resolved.pathname)),
+    path: normalizePath(
+      stripBasePath(deployBase, decodePath(resolved.pathname))
+    ),
   };
 };

package/src/cli/commands/audit.ts

@@ -40,6 +40,26 @@ export const shouldFail = (
   return result.diagnostics.some((d) => failing.has(d.severity));
 };
 
+/**
+ * Launch the agent CLI, translating a missing executable into the Windows
+ * not-found sentinel. Only `ENOENT` means "not installed" — any other spawn
+ * failure (`EACCES`, `EMFILE`, …) must surface as itself, not be masked by an
+ * irrelevant install hint.
+ */
+const launchAgentCode = async (
+  bin: string,
+  prompt: string
+): Promise<number> => {
+  try {
+    return await launchAgent(bin, prompt);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      throw error;
+    }
+    return WINDOWS_COMMAND_NOT_FOUND;
+  }
+};
+
 export const auditCommand = defineCommand({
   args: {
     claude: {
@@ -163,12 +183,7 @@ export const auditCommand = defineCommand({
       process.stderr.write(
         `  Handing ${count} finding${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
       );
-      let code: number;
-      try {
-        code = await launchAgent(cli.bin, fixPrompt(report));
-      } catch {
-        code = WINDOWS_COMMAND_NOT_FOUND;
-      }
+      const code = await launchAgentCode(cli.bin, fixPrompt(report));
       // A POSIX spawn rejects on a missing executable; the Windows shell
       // launch reports it through cmd.exe's 9009 instead. Same diagnosis.
       if (code === WINDOWS_COMMAND_NOT_FOUND) {

package/src/cli/commands/dev.ts

@@ -2,6 +2,7 @@ import { watch } from "node:fs";
 
 import { dev } from "astro";
 import { defineCommand } from "citty";
+import { basename, dirname } from "pathe";
 
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
@@ -202,8 +203,10 @@ export const devCommand = defineCommand({
     // 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.
+    const dirTargets = [project.context.pagesRoot].filter(
+      (target) => target !== null
+    );
     const fileTargets = [
-      project.context.pagesRoot,
       project.context.configFile,
       project.context.themeFile,
       project.context.componentsFile,
@@ -211,10 +214,24 @@ export const devCommand = defineCommand({
 
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      ...fileTargets.map((target) => {
+      ...dirTargets.map((target) => {
         const watcher = watch(target, { recursive: true }, regenerate);
         return () => watcher.close();
       }),
+      // Single files are watched via their parent directory: fs.watch on the
+      // file itself tracks the inode, so a rename-replace save (vim and most
+      // "atomic save" editors) orphans the watcher after the first write and
+      // every later edit is silently ignored.
+      ...fileTargets.map((target) => {
+        const name = basename(target);
+        const watcher = watch(dirname(target), (_event, filename) => {
+          // A null filename (some platforms) can't be filtered — regenerate.
+          if (!filename || filename === name) {
+            regenerate();
+          }
+        });
+        return () => watcher.close();
+      }),
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {

package/src/components/content/Frame.astro

@@ -13,7 +13,10 @@ const escapeRawHtml = (value: string): string =>
 
 const unwrapParagraph = (html: string): string => {
   const trimmed = html.trim();
-  const match = trimmed.match(/^<p>(?<content>[\s\S]*)<\/p>$/u);
+  // Only a *single* paragraph is unwrapped: the content must not contain its
+  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
+  // unbalanced HTML injected via set:html.
+  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
   return match?.groups?.content ?? trimmed;
 };
 

package/src/components/content/Prompt.astro

@@ -13,7 +13,10 @@ const escapeRawHtml = (value: string): string =>
 
 const unwrapParagraph = (html: string): string => {
   const trimmed = html.trim();
-  const match = trimmed.match(/^<p>(?<content>[\s\S]*)<\/p>$/u);
+  // Only a *single* paragraph is unwrapped: the content must not contain its
+  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
+  // unbalanced HTML injected via set:html.
+  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
   return match?.groups?.content ?? trimmed;
 };
 

package/src/components/content/Tooltip.astro

@@ -16,7 +16,10 @@ const external = href?.startsWith("http");
 
 const unwrapParagraph = (html: string): string => {
   const trimmed = html.trim();
-  const match = trimmed.match(/^<p>(?<content>[\s\S]*)<\/p>$/u);
+  // Only a *single* paragraph is unwrapped: the content must not contain its
+  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
+  // unbalanced HTML injected via set:html.
+  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
   return match?.groups?.content ?? trimmed;
 };
 

package/src/components/content/Update.astro

@@ -81,3 +81,48 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
     <slot />
   </div>
 </article>
+
+<script>
+  const state = window as Window & { __blumeUpdateIds?: boolean };
+  if (!state.__blumeUpdateIds) {
+    state.__blumeUpdateIds = true;
+
+    // Repeated labels slug to the same id (two "Bug fixes" entries on one
+    // changelog page); suffix the later ones so ids stay unique and each
+    // entry's self-anchor jumps to itself, not the first duplicate. The first
+    // keeps the plain slug, so hash deep-links stay stable. Mirrors the
+    // accordion id dedupe in `AccordionItem.astro`.
+    const dedupeUpdateIds = () => {
+      const seen = new Map<string, number>();
+      for (const update of document.querySelectorAll<HTMLElement>(
+        "[data-blume-update][id]"
+      )) {
+        const previous = update.id;
+        const count = seen.get(previous) ?? 0;
+        seen.set(previous, count + 1);
+        if (count === 0) {
+          continue;
+        }
+        update.id = `${previous}-${count + 1}`;
+        // Re-point the entry's own header anchor when it targets the old id;
+        // an explicit `href` prop (an external permalink) is left alone.
+        const anchor = update.querySelector<HTMLAnchorElement>("header a[href]");
+        const href = anchor?.getAttribute("href");
+        if (anchor && href?.endsWith(`#${previous}`)) {
+          anchor.setAttribute(
+            "href",
+            `${href.slice(0, -previous.length)}${update.id}`
+          );
+        }
+      }
+    };
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", dedupeUpdateIds, {
+        once: true,
+      });
+    } else {
+      dedupeUpdateIds();
+    }
+  }
+</script>

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

@@ -180,13 +180,30 @@ const AskAI = ({
     return () => window.removeEventListener("blume:open-ask-ai", handler);
   }, []);
 
-  // ⌘I / Ctrl+I toggles the panel; Escape closes it.
+  // ⌘I / Ctrl+I toggles the panel; Escape closes it. Shift/Alt chords are
+  // left alone — Ctrl+Shift+I is the browser's DevTools shortcut, and
+  // capturing it would flap the panel open alongside them.
   useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
-      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "i") {
+      if (
+        (event.metaKey || event.ctrlKey) &&
+        !event.shiftKey &&
+        !event.altKey &&
+        event.key.toLowerCase() === "i"
+      ) {
         event.preventDefault();
         setOpen((value) => !value);
       } else if (event.key === "Escape" && open) {
+        // 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")) {
+          return;
+        }
         setOpen(false);
       }
     };

package/src/components/islands/hooks.ts

@@ -155,6 +155,13 @@ const currentPath = (): string =>
 export const useAskAI = (): UseAskAI => {
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
+  // The stream writes into the conversation via state updates, so `reset()`
+  // mid-answer must revoke the in-flight request's right to write — otherwise
+  // its next chunk re-appends the assistant bubble onto the emptied list, and
+  // its error path resurrects the entire pre-reset history. Mirrors the
+  // built-in island's generation/abort guard.
+  const generation = useRef(0);
+  const abortRef = useRef<AbortController | null>(null);
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
   // preserves a stable `ask` identity for consumers that depend on it. With the
@@ -166,6 +173,11 @@ export const useAskAI = (): UseAskAI => {
       if (!trimmed || loading) {
         return;
       }
+      generation.current += 1;
+      const { current } = generation;
+      const controller = new AbortController();
+      abortRef.current = controller;
+      const live = () => current === generation.current;
       const history: AskMessage[] = [
         ...messages,
         { content: trimmed, role: "user" },
@@ -181,30 +193,33 @@ export const useAskAI = (): UseAskAI => {
           }),
           headers: { "content-type": "application/json" },
           method: "POST",
+          signal: controller.signal,
         });
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
-          assistant.content = ASK_ERROR;
-          setMessages([...history, { ...assistant }]);
+          if (live()) {
+            assistant.content = ASK_ERROR;
+            setMessages([...history, { ...assistant }]);
+          }
           return;
         }
         const reader = response.body?.getReader();
         const decoder = new TextDecoder();
         if (reader) {
           let done = false;
-          while (!done) {
+          while (!done && live()) {
             // oxlint-disable-next-line no-await-in-loop, react-doctor/async-await-in-loop -- sequential stream consumption; iterations are not independent
             const chunk = await reader.read();
             ({ done } = chunk);
-            if (chunk.value) {
+            if (chunk.value && live()) {
               // 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),
+              setMessages((currentMessages) => [
+                ...currentMessages.slice(0, -1),
                 { ...assistant },
               ]);
             }
@@ -212,11 +227,16 @@ export const useAskAI = (): UseAskAI => {
         }
       } catch {
         // A thrown fetch (offline, DNS failure, CORS) must not strand the
-        // pre-appended empty assistant message as a stuck placeholder.
-        assistant.content = ASK_ERROR;
-        setMessages([...history, { ...assistant }]);
+        // pre-appended empty assistant message as a stuck placeholder. A
+        // reset's abort lands here too — the guard keeps it silent.
+        if (live()) {
+          assistant.content = ASK_ERROR;
+          setMessages([...history, { ...assistant }]);
+        }
       } finally {
-        setLoading(false);
+        if (live()) {
+          setLoading(false);
+        }
       }
     },
     [loading, messages]
@@ -225,7 +245,14 @@ export const useAskAI = (): UseAskAI => {
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
   // keeps a stable `reset` identity. With the compiler on it's redundant but inert.
   // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
-  const reset = useCallback(() => setMessages([]), []);
+  const reset = useCallback(() => {
+    generation.current += 1;
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setMessages([]);
+    // The in-flight `ask`'s finally is now stale and won't clear this.
+    setLoading(false);
+  }, []);
 
   return { ask, loading, messages, reset };
 };

package/src/components/layout/RootLayout.astro

@@ -25,7 +25,11 @@ import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
+import {
+  BANNER_INIT_SCRIPT,
+  SIDEBAR_SCROLL_INIT_SCRIPT,
+  THEME_INIT_SCRIPT,
+} from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
@@ -558,7 +562,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             </nav>
           )
         }
-        <nav>
+        <nav data-blume-nav-tree>
           {
             MobileNavSlot ? (
               <>
@@ -587,6 +591,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           }
         </nav>
       </aside>
+      <script is:inline set:html={SIDEBAR_SCROLL_INIT_SCRIPT} />
       <main class="px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
         <BreadcrumbsSlot
           crumbs={crumbs}
@@ -896,6 +901,12 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         };
 
         for (const image of zoomTargets) {
+          // An image that is itself a link navigates on click — binding zoom
+          // to it would flash a zoom overlay in the instant before navigation
+          // and advertise (via the cursor) a zoom that never happens.
+          if (image.closest("a")) {
+            continue;
+          }
           image.classList.add("cursor-zoom-in");
           image.addEventListener("click", () => openZoom(image));
         }

package/src/components/layout/Search.astro

@@ -325,7 +325,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         document.addEventListener("keydown", (event) => {
           if (
             (event.key === "k" || event.key === "K") &&
-            (event.metaKey || event.ctrlKey)
+            (event.metaKey || event.ctrlKey) &&
+            // Ctrl+Shift+K is Firefox's web console; a shifted or alted chord
+            // belongs to the browser, not the search dialog.
+            !event.shiftKey &&
+            !event.altKey
           ) {
             // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
             // the dialog open must close it, not re-showModal an open dialog

package/src/components/layout/head-scripts.ts

@@ -1,11 +1,12 @@
 /**
  * Pre-paint inline scripts shared by the document layouts (`RootLayout`,
- * `PageLayout`, `ReferenceLayout`). They run synchronously in `<head>`, before
- * first paint, so the page never flashes the wrong theme or a since-dismissed
- * banner. Kept in one place so the layouts can't drift on this timing-critical
- * logic.
+ * `PageLayout`, `ReferenceLayout`). They run synchronously — in `<head>`, or
+ * immediately after the markup they act on — before that content paints, so the
+ * page never flashes the wrong theme, a since-dismissed banner, or a sidebar
+ * scrolled away from the current page. Kept in one place so the layouts can't
+ * drift on this timing-critical logic.
  *
- * Both are constants, never built by interpolating config into source text: the
+ * All are constants, never built by interpolating config into source text: any
  * values they need ride in as `data-*` attributes on the script tag and are read
  * back through `document.currentScript`. Baking a config string into JS — even
  * via `JSON.stringify` — is code construction, and JSON escaping does not cover
@@ -27,3 +28,19 @@ export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.
  * Reads `data-key` — the banner's dismissal key.
  */
 export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(k&&localStorage.getItem("blume-banner:"+k))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;
+
+/**
+ * Center the current page's sidebar link before the sidebar paints. Every
+ * navigation is a full page load, and the sidebar is its own scroll container,
+ * so without this it is reborn scrolled to the top on every click — on a long
+ * sidebar the viewport visibly jumps away from the link you just clicked.
+ *
+ * Runs inline immediately after the sidebar `<aside>` (not in `<head>`: it
+ * needs that markup parsed). The lookup is scoped to the page tree
+ * (`data-blume-nav-tree`) because the drawer also holds the mobile tabs list,
+ * whose active tab is `aria-current` too. `getClientRects()` skips links that
+ * aren't rendered — `hidden` drill-in panels and breakpoint-hidden duplicates —
+ * and the script no-ops when the active link is already inside the visible
+ * scroll area, so a short sidebar never moves.
+ */
+export const SIDEBAR_SCROLL_INIT_SCRIPT = `(()=>{const n=document.querySelector("[data-blume-nav-drawer]");const s=n&&(n.querySelector("[data-blume-nav-tree]")||n);if(!s)return;let l=null;for(const a of s.querySelectorAll('a[aria-current="page"]')){if(a.getClientRects().length){l=a;break;}}if(!l)return;const r=n.getBoundingClientRect();const t=l.getBoundingClientRect();if(t.top>=r.top&&t.bottom<=r.bottom)return;n.scrollTop+=t.top-r.top-(n.clientHeight-t.height)/2;})();`;

package/src/core/data.ts

@@ -104,6 +104,8 @@ export interface BlumeDataConfig {
   codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
+  /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
+  dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
   favicon: BlumeFavicon;
   feedback: boolean;

package/src/core/deployment-env.ts

@@ -30,12 +30,17 @@ const PLATFORMS: Platform[] = [
   {
     adapter: "vercel",
     detect: (env) => Boolean(env.VERCEL),
-    site: (env) => toUrl(env.VERCEL_PROJECT_PRODUCTION_URL ?? env.VERCEL_URL),
+    // Fall through per *resolved* value, not per variable — a platform can set
+    // a var to the empty string, which `??` on the raw values treats as
+    // present, dead-ending the chain and silently losing the site URL.
+    site: (env) =>
+      toUrl(env.VERCEL_PROJECT_PRODUCTION_URL) ?? toUrl(env.VERCEL_URL),
   },
   {
     adapter: "netlify",
     detect: (env) => Boolean(env.NETLIFY),
-    site: (env) => toUrl(env.URL ?? env.DEPLOY_PRIME_URL ?? env.DEPLOY_URL),
+    site: (env) =>
+      toUrl(env.URL) ?? toUrl(env.DEPLOY_PRIME_URL) ?? toUrl(env.DEPLOY_URL),
   },
   {
     adapter: "cloudflare",