blume 1.4.2 → 1.4.3

package/src/components/layout/PageActions.astro

@@ -224,7 +224,9 @@ const menuRowClass =
 </div>
 
 <script>
+  import { copyText, flashLabel } from "../copy-feedback.ts";
   import { prefixBase } from "../islands/base-path.ts";
+  import { rafThrottle } from "../raf-throttle.ts";
 
   const CHAT_URLS: Record<string, (q: string) => string> = {
     chatgpt: (q) => `https://chatgpt.com/?hints=search&prompt=${q}`,
@@ -318,12 +320,17 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         placeMenu(details);
       });
     }
-    window.addEventListener("resize", () => {
-      const open = dropdowns.find((details) => details.open);
-      if (open) {
-        placeMenu(open);
-      }
-    });
+    // rAF-coalesced so a live resize drag re-reads layout once per frame,
+    // not once per event, while the open menu still tracks the viewport.
+    window.addEventListener(
+      "resize",
+      rafThrottle(() => {
+        const open = dropdowns.find((details) => details.open);
+        if (open) {
+          placeMenu(open);
+        }
+      })
+    );
 
     // `data-md` is the base-less logical route; the raw-markdown endpoint is a
     // generated page route, so it's served under the deployment base like any
@@ -376,24 +383,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: id, type: "http", url: mcpUrl }))}`
         );
 
-      const flash = (el: Element | null, text: string) => {
-        if (!(el instanceof HTMLElement)) {
-          return;
-        }
-        // Remember the element's own (localized) label once — capturing it at
-        // click time would capture "Copied!" on a double-click and stick.
-        el.dataset.blumeLabel ??= el.textContent ?? "";
-        el.textContent = text;
-        setTimeout(() => {
-          el.textContent = el.dataset.blumeLabel ?? "";
-        }, 1500);
-      };
       const copy = async (value: string, el: Element | null) => {
-        try {
-          await navigator.clipboard.writeText(value);
-          flash(el, copiedLabel);
-        } catch {
-          // Clipboard unavailable; nothing to do.
+        if ((await copyText(value)) && el instanceof HTMLElement) {
+          flashLabel(el, copiedLabel);
         }
       };
       root
@@ -420,9 +412,6 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     }
 
     const label = root.querySelector("[data-blume-copy-label]");
-    // Captured once — inside the handler a double-click would capture and
-    // permanently restore "Copied!".
-    const original = label?.textContent ?? "";
     root
       .querySelector("[data-blume-copy-page]")
       ?.addEventListener("click", async () => {
@@ -431,12 +420,11 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           if (!response.ok) {
             throw new Error(`Fetching ${md} failed (${response.status})`);
           }
-          await navigator.clipboard.writeText(await response.text());
-          if (label) {
-            label.textContent = copiedLabel;
-            setTimeout(() => {
-              label.textContent = original;
-            }, 1500);
+          if (
+            (await copyText(await response.text())) &&
+            label instanceof HTMLElement
+          ) {
+            flashLabel(label, copiedLabel);
           }
         } catch (error) {
           // Clipboard or fetch unavailable; don't flash "Copied!" untruthfully.

package/src/components/layout/PageLayout.astro

@@ -152,9 +152,13 @@ const basedRoute = withBase(route);
 // strip it before joining with the root-relative route so canonical/og URLs
 // don't come out double-slashed — the catch-all strips it the same way.
 const siteBase = siteUrl ? siteUrl.replace(/\/$/u, "") : null;
+// The route-derived part is percent-encoded (the sitemap convention) so a
+// Unicode route slug yields a legal URI that byte-matches the sitemap <loc>.
 const resolvedCanonical =
   canonical ??
-  (siteBase ? `${siteBase}${basedRoute === "/" ? "" : basedRoute}` : null);
+  (siteBase
+    ? `${siteBase}${basedRoute === "/" ? "" : encodeURI(basedRoute)}`
+    : null);
 // An explicit `ogImage` wins. A root-relative path (e.g. an image dropped in
 // `public/`) is resolved against the site URL so crawlers get an absolute
 // `og:image`; an already-absolute URL passes through untouched. Otherwise fall
@@ -164,7 +168,7 @@ const absolutizeOgImage = (value: string): string =>
 const resolvedOgImage = ogImage
   ? absolutizeOgImage(ogImage)
   : ogEnabled && siteBase
-    ? `${siteBase}${withBase(`/og/${ogSlug}.png`)}`
+    ? `${siteBase}${encodeURI(withBase(`/og/${ogSlug}.png`))}`
     : null;
 // Only the generated card has a known size and format, so its dimensions are
 // declared for crawlers; a user-supplied `ogImage` could be any image.
@@ -305,36 +309,12 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       )
     }
     <script>
+      import { syncDrawerInert } from "./drawer-inert.ts";
       // Dev-only: friendly hint after a React island hydration mismatch;
       // tree-shaken out of production builds.
       import "./hydration-hint.ts";
 
-      // The closed tabs drawer is only translated off-canvas, so its links
-      // would stay in the tab order. Mirror the header's `data-blume-nav-open`
-      // toggle into `inert`/`aria-hidden` below `lg` (64rem), matching the
-      // breakpoint where the drawer is display-hidden anyway.
-      const drawer = document.querySelector<HTMLElement>(
-        "[data-blume-nav-drawer]"
-      );
-      if (drawer) {
-        const desktop = window.matchMedia("(min-width: 64rem)");
-        const syncDrawer = () => {
-          const hidden =
-            !desktop.matches &&
-            !document.documentElement.hasAttribute("data-blume-nav-open");
-          drawer.inert = hidden;
-          if (hidden) {
-            drawer.setAttribute("aria-hidden", "true");
-          } else {
-            drawer.removeAttribute("aria-hidden");
-          }
-        };
-        syncDrawer();
-        desktop.addEventListener("change", syncDrawer);
-        new MutationObserver(syncDrawer).observe(document.documentElement, {
-          attributeFilter: ["data-blume-nav-open"],
-        });
-      }
+      syncDrawerInert();
     </script>
   </body>
 </html>

package/src/components/layout/RootLayout.astro

@@ -712,6 +712,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       type="button"
     ></button>
     <script>
+      import { copyText, createCopyFlash } from "../copy-feedback.ts";
+      import { syncDrawerInert } from "./drawer-inert.ts";
       import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
       // Registers the <blume-mermaid> custom element (emitted by ```mermaid
       // fences). Mermaid itself is lazy-loaded only on pages that use a diagram.
@@ -723,32 +725,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       // Tree-shaken out of production builds.
       import "./hydration-hint.ts";
 
-      // The closed mobile drawer is only translated off-canvas, so its links
-      // would stay in the tab order on every page. Mirror the header's
-      // `data-blume-nav-open` toggle into `inert`/`aria-hidden` — but only
-      // below `lg` (64rem), where the same element isn't the static sidebar.
-      const drawer = document.querySelector<HTMLElement>(
-        "[data-blume-nav-drawer]"
-      );
-      if (drawer) {
-        const desktop = window.matchMedia("(min-width: 64rem)");
-        const syncDrawer = () => {
-          const hidden =
-            !desktop.matches &&
-            !document.documentElement.hasAttribute("data-blume-nav-open");
-          drawer.inert = hidden;
-          if (hidden) {
-            drawer.setAttribute("aria-hidden", "true");
-          } else {
-            drawer.removeAttribute("aria-hidden");
-          }
-        };
-        syncDrawer();
-        desktop.addEventListener("change", syncDrawer);
-        new MutationObserver(syncDrawer).observe(document.documentElement, {
-          attributeFilter: ["data-blume-nav-open"],
-        });
-      }
+      syncDrawerInert();
 
       const svg = (name: string, cls = "") =>
         `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${cls ? ` class="${cls}"` : ""}>${icons[name]}</svg>`;
@@ -767,14 +744,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       const copiedLabel =
         document.body.getAttribute("data-i18n-copied") || "Copied!";
 
-      // Shared polite live region: the icon swap is invisible to screen
-      // readers, so copy success is announced here. Cleared when a button's
-      // checked state resets so the next copy re-announces.
-      const copyStatus = document.createElement("span");
-      copyStatus.className = "sr-only";
-      copyStatus.setAttribute("aria-live", "polite");
-      document.body.appendChild(copyStatus);
-
       const languageLabels: Record<string, string> = {
         astro: "Astro",
         bash: "Bash",
@@ -854,7 +823,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             button.classList.toggle(cls, !checked);
           }
         };
-        let resetTimeout: number | undefined;
+        const flash = createCopyFlash(setChecked, copiedLabel);
         button.addEventListener("click", async () => {
           const code = pre.querySelector("code");
           let text = code?.textContent ?? "";
@@ -870,20 +839,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             }
             text = clone.textContent ?? "";
           }
-          try {
-            await navigator.clipboard.writeText(text);
-          } catch {
-            return;
-          }
-          if (resetTimeout) {
-            window.clearTimeout(resetTimeout);
+          if (await copyText(text)) {
+            flash();
           }
-          setChecked(true);
-          copyStatus.textContent = copiedLabel;
-          resetTimeout = window.setTimeout(() => {
-            setChecked(false);
-            copyStatus.textContent = "";
-          }, 1500);
         });
         pre.appendChild(button);
       }

package/src/components/layout/Search.astro

@@ -86,11 +86,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     >
       <Icon name="search" size={18} />
       <input
+        aria-autocomplete="list"
+        aria-controls="blume-search-listbox"
+        aria-expanded="false"
         aria-label={s.label}
         autocomplete="off"
         class="flex-1 border-0 bg-transparent text-foreground text-sm pointer-coarse:text-base focus:outline-none [&::-webkit-search-cancel-button]:appearance-none"
         data-blume-search-input
         placeholder={s.placeholder}
+        role="combobox"
         type="search"
       />
       <kbd class={`${kbd} text-[0.7rem]`}>Esc</kbd>
@@ -107,8 +111,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         >
         </div>
         <div
+          aria-label={s.label}
           class="min-h-0 flex-1 scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto p-2"
           data-blume-search-results
+          id="blume-search-listbox"
+          role="listbox"
         >
         </div>
         <p
@@ -207,6 +214,26 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     const svg = (name: string, size = 16): string =>
       `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${icons[name] ?? ""}</svg>`;
 
+    // localStorage access throws SecurityError when storage is blocked (Safari
+    // "Block All Cookies", some embedded webviews). These guards make blocked
+    // storage degrade to session-default preferences instead of throwing inside
+    // connectedCallback before the open/keyboard listeners are attached — which
+    // would leave search completely dead.
+    const readStorage = (key: string): string | null => {
+      try {
+        return localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+    const writeStorage = (key: string, value: string): void => {
+      try {
+        localStorage.setItem(key, value);
+      } catch {
+        // Preference simply isn't remembered.
+      }
+    };
+
     class BlumeSearch extends HTMLElement {
       dialog!: HTMLDialogElement;
       input!: HTMLInputElement;
@@ -226,6 +253,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       selectedIndex = -1;
       activeSection: string | null = null;
       renderGeneration = 0;
+      /** Monotonic id source for option rows (aria-activedescendant). */
+      optionSeq = 0;
       previewOn = true;
       devOnlyMsg = "Search is available in the production build.";
       noResultsMsg = "No results found.";
@@ -273,8 +302,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.popular = [];
         }
 
-        this.previewOn =
-          localStorage.getItem("blume-search-preview") !== "0";
+        this.previewOn = readStorage("blume-search-preview") !== "0";
         this.applyPreviewState();
 
         // Per-language filtering: default to the active locale, with an opt-in
@@ -283,12 +311,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           "[data-blume-search-all-locales]"
         );
         if (allToggle) {
-          this.allLocales =
-            localStorage.getItem("blume-search-all-locales") === "1";
+          this.allLocales = readStorage("blume-search-all-locales") === "1";
           allToggle.checked = this.allLocales;
           allToggle.addEventListener("change", () => {
             this.allLocales = allToggle.checked;
-            localStorage.setItem(
+            writeStorage(
               "blume-search-all-locales",
               this.allLocales ? "1" : "0"
             );
@@ -568,7 +595,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         header.className =
           "m-0 px-2.5 pt-3 pb-1 font-normal text-muted-foreground text-xs";
         header.textContent = label;
+        // The listbox tree allows only group/option descendants: the group
+        // carries the label for assistive tech, the visual header is
+        // decoration.
+        header.setAttribute("aria-hidden", "true");
         const container = document.createElement("div");
+        container.setAttribute("role", "group");
+        container.setAttribute("aria-label", label);
         this.results.append(header, container);
         return container;
       }
@@ -632,6 +665,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       }
 
       bindRow(item: Selectable) {
+        // Options for the combobox pattern: selection is announced through
+        // aria-activedescendant on the input (focus never leaves it), so
+        // every row needs a stable id and an aria-selected to flip.
+        item.el.setAttribute("role", "option");
+        item.el.setAttribute("aria-selected", "false");
+        this.optionSeq += 1;
+        item.el.id = `blume-search-option-${this.optionSeq}`;
         item.el.addEventListener("mouseenter", () => {
           this.selectIndex(this.selectables.indexOf(item));
         });
@@ -644,9 +684,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       }
 
       finishRender() {
+        this.input.setAttribute(
+          "aria-expanded",
+          String(this.selectables.length > 0)
+        );
         if (this.selectables.length > 0) {
           this.selectIndex(0);
         } else {
+          this.input.removeAttribute("aria-activedescendant");
           this.clearPreview();
         }
       }
@@ -659,11 +704,16 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (current) {
           current.el.classList.remove(...ROW_ON);
           current.el.classList.add(...ROW_OFF);
+          current.el.setAttribute("aria-selected", "false");
         }
         this.selectedIndex = index;
         const next = this.selectables[index];
         next.el.classList.remove(...ROW_OFF);
         next.el.classList.add(...ROW_ON);
+        next.el.setAttribute("aria-selected", "true");
+        // Focus stays on the input; the selection is surfaced to assistive
+        // tech through the active descendant.
+        this.input.setAttribute("aria-activedescendant", next.el.id);
         next.el.scrollIntoView({ block: "nearest" });
         this.updatePreview();
       }
@@ -714,10 +764,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       togglePreview() {
         this.previewOn = !this.previewOn;
-        localStorage.setItem(
-          "blume-search-preview",
-          this.previewOn ? "1" : "0"
-        );
+        writeStorage("blume-search-preview", this.previewOn ? "1" : "0");
         this.applyPreviewState();
         this.updatePreview();
       }

package/src/components/layout/drawer-inert.ts

@@ -0,0 +1,31 @@
+/**
+ * Keep the mobile nav drawer out of the tab order while it is closed. The
+ * closed drawer is only translated off-canvas, so its links would otherwise
+ * stay focusable on every page. Mirrors the header's `data-blume-nav-open`
+ * toggle into `inert`/`aria-hidden` — but only below `lg` (64rem), where the
+ * same element isn't the static sidebar (RootLayout) or is display-hidden
+ * anyway (PageLayout). Shared by both layouts' inline scripts.
+ */
+export const syncDrawerInert = (): void => {
+  const drawer = document.querySelector<HTMLElement>("[data-blume-nav-drawer]");
+  if (!drawer) {
+    return;
+  }
+  const desktop = window.matchMedia("(min-width: 64rem)");
+  const sync = () => {
+    const hidden =
+      !desktop.matches &&
+      !Object.hasOwn(document.documentElement.dataset, "blumeNavOpen");
+    drawer.inert = hidden;
+    if (hidden) {
+      drawer.setAttribute("aria-hidden", "true");
+    } else {
+      drawer.removeAttribute("aria-hidden");
+    }
+  };
+  sync();
+  desktop.addEventListener("change", sync);
+  new MutationObserver(sync).observe(document.documentElement, {
+    attributeFilter: ["data-blume-nav-open"],
+  });
+};

package/src/components/layout/search/pagefind.ts

@@ -1,4 +1,4 @@
-import { highlight, SEARCH_LIMIT } from "./types.ts";
+import { highlight, sanitizeExcerpt, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
 interface PagefindResult {
@@ -28,16 +28,17 @@ export const createSearch = async (opts: {
     /* @vite-ignore */
     opts.url
   )) as PagefindModule;
-  // Pagefind builds its own marked-up excerpt; we keep that and only highlight
-  // the title. It carries no section/breadcrumb data, so pills stay hidden and
-  // the preview pane falls back to the excerpt.
+  // Pagefind builds its own marked-up excerpt; we keep its `<mark>` highlights
+  // (dropping any other markup — the excerpt is rendered via innerHTML) and
+  // only highlight the title ourselves. It carries no section/breadcrumb data,
+  // so pills stay hidden and the preview pane falls back to the excerpt.
   return async (query) => {
     const response = await pagefind.search(query);
     const docs = await Promise.all(
       response.results.slice(0, SEARCH_LIMIT).map((result) => result.data())
     );
     const hits = docs.map((doc) => ({
-      excerpt: doc.excerpt,
+      excerpt: sanitizeExcerpt(doc.excerpt),
       title: highlight(doc.meta?.title ?? doc.url, query),
       url: doc.url,
     }));

package/src/components/layout/search/types.ts

@@ -84,6 +84,38 @@ export const highlight = (text: string, query: string): string => {
     .join("");
 };
 
+// Either a tag-shaped run — an opening `<` with a letter or `/` after it,
+// through the closing `>` (or end of string for an unterminated tag) — or a
+// lone `<`. A run can't span a later `<` (`[^<>]`), so between the two
+// alternatives every `<` in the input lands inside a captured run.
+const ANGLE_RUN = /(?<run><\/?[a-z][^<>]*>?|<)/iu;
+const BARE_MARK = /^<\/?mark>$/iu;
+
+/**
+ * Reduce provider-supplied excerpt markup to the `<mark>` highlighting the
+ * dialog expects. Remote excerpts (Pagefind's index, hosted engines) are
+ * rendered via `innerHTML`, so the output alphabet is pinned: bare
+ * `<mark>`/`</mark>` tags (attributes make even a mark untrusted), text, and
+ * entities. Tag-shaped runs are dropped; every other `<` is escaped, which
+ * renders identically but can't be parsed as markup (`<!--` would otherwise
+ * open a comment in `innerHTML` and swallow the rest of the excerpt). Split on
+ * runs covering every `<` rather than deleting tags in place: a deletion can
+ * splice the text around it into a fresh tag (`<<b>script>` → `<script>`),
+ * while here no `<` survives outside a run, so the only ones emitted are the
+ * bare mark tags. String-level on purpose: this also runs under DOM-less
+ * tests, where DOMPurify/DOMParser don't exist.
+ */
+export const sanitizeExcerpt = (html: string): string =>
+  html
+    .split(ANGLE_RUN)
+    .map((part, index) => {
+      if (index % 2 === 0 || BARE_MARK.test(part)) {
+        return part;
+      }
+      return part === "<" ? "&lt;" : "";
+    })
+    .join("");
+
 /** First index in `text` where any query token matches (case-insensitive). */
 const matchIndex = (text: string, query: string): number => {
   const tokens = queryTokens(query);

package/src/components/openapi/panel.ts

@@ -6,6 +6,8 @@
  * theme.
  */
 
+import { copyText, createCopyFlash } from "../copy-feedback.ts";
+
 class BlumePanelTabs extends HTMLElement {
   connectedCallback() {
     const tabs = [
@@ -36,18 +38,19 @@ class BlumePanelTabs extends HTMLElement {
     }
 
     if (copy) {
+      const flash = createCopyFlash((copied) => {
+        if (copied) {
+          copy.dataset.copied = "true";
+        } else {
+          delete copy.dataset.copied;
+        }
+      }, "Copied");
       copy.addEventListener("click", async () => {
         const active = panels.find(
           (panel) => !panel.classList.contains("hidden")
         );
-        try {
-          await navigator.clipboard.writeText(active?.textContent ?? "");
-          copy.dataset.copied = "true";
-          setTimeout(() => {
-            delete copy.dataset.copied;
-          }, 1500);
-        } catch {
-          // Clipboard unavailable (insecure context); silently ignore.
+        if (await copyText(active?.textContent ?? "")) {
+          flash();
         }
       });
     }

package/src/components/raf-throttle.ts

@@ -0,0 +1,21 @@
+/**
+ * Coalesce a high-frequency event handler (resize, scroll) into at most one
+ * call per animation frame — the toc-element scroll pattern, shared. Calls
+ * landing while a frame is pending are dropped; the handler runs once on the
+ * next frame with the latest state. Layout reads inside `fn` then happen once
+ * per frame instead of once per event, without the settle lag a debounce
+ * would add to position-tracking handlers.
+ */
+export const rafThrottle = (fn: () => void): (() => void) => {
+  let ticking = false;
+  return () => {
+    if (ticking) {
+      return;
+    }
+    ticking = true;
+    requestAnimationFrame(() => {
+      ticking = false;
+      fn();
+    });
+  };
+};

package/src/components/slug.ts

@@ -0,0 +1,14 @@
+import { slug } from "github-slugger";
+
+/**
+ * Slug a component's title into a DOM id (accordions, tabs, changelog
+ * updates), replacing three identical per-component copies. github-slugger —
+ * already what heading anchors use, both here and in Satteri's own
+ * heading-ids — so a component id slugs exactly like a heading with the same
+ * text (unicode letters kept, `user_id` keeps its underscore, `C#` keeps
+ * nothing extra dropped). Stateless on purpose: components render across many
+ * pages in one build process, so a stateful slugger would leak duplicate
+ * suffixes between pages — same-page duplicates are de-duplicated client-side
+ * by each component's own script.
+ */
+export const componentSlug = (value: string): string => slug(value);

package/src/core/base-path.ts

@@ -12,6 +12,8 @@
  * `components/islands/base-path.ts` and serves `deployment.base` via `BASE_URL`.
  */
 
+import { trimEnd } from "./trim.ts";
+
 /**
  * Canonicalize a configured base path to either `""` (none) or `/seg[/seg…]`
  * (leading slash, no trailing slash, collapsed inner slashes). A blank value or
@@ -33,10 +35,25 @@ export const normalizeBasePath = (input?: string): string => {
  * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
  */
 export const normalizePath = (path: string): string => {
-  const trimmed = path.replace(/\/+$/u, "");
+  const trimmed = trimEnd(path, "/");
   return trimmed === "" ? "/" : trimmed;
 };
 
+/**
+ * Canonicalize a route-ish string (a configured route, a page path, an agent-
+ * supplied route) to `/` or `/seg[/seg…]`: trimmed, exactly one leading slash,
+ * no trailing slash. The shared spelling of what openapi/references,
+ * ai/ask-context, and ai/mcp/server each hand-rolled with slightly different
+ * regexes.
+ */
+export const normalizeRoute = (input: string): string => {
+  const trimmed = trimEnd(input.trim(), "/");
+  if (trimmed === "") {
+    return "/";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+};
+
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/src/core/config-input.ts

@@ -205,6 +205,8 @@ export interface SanitySource {
 /** A Notion database; pages become entries, blocks become MDX. */
 export interface NotionSource {
   type: "notion";
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency?: number;
   /** Notion database id. */
   database: string;
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
@@ -653,6 +655,12 @@ export interface AskConfig {
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
   endpoint?: string;
+  /**
+   * Extra system-prompt text appended to the built-in instructions — use it
+   * for identity, language, or tone. The built-in grounding behavior (answer
+   * from the retrieved excerpts, cite pages as Markdown links) is preserved.
+   */
+  instructions?: string;
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */