blume 0.6.7 → 0.7.0

package/src/cli/required-secrets.ts

@@ -15,9 +15,10 @@ export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
     if (process.env[env]) {
       return;
     }
+    const noteSuffix = note ? ` (${note})` : "";
     diagnostics.push({
       code: "BLUME_MISSING_SECRET",
-      message: `${feature} is enabled but ${env} is not set${note ? ` (${note})` : ""}.`,
+      message: `${feature} is enabled but ${env} is not set${noteSuffix}.`,
       severity: "warning",
       suggestion: `Set ${env} in .env.local for local dev, or in your host's environment for production.`,
     });

package/src/components/content/CodeBlock.astro

@@ -10,6 +10,8 @@
 // `.prose` container (`max-w-none` so it fills its own column rather than the
 // prose reading measure); that's what makes the light/dark swap work on a bare
 // page without the manual `[data-theme]` CSS it would otherwise need.
+import data from "blume:data";
+
 import { highlightCode } from "../../markdown/index.ts";
 
 interface Props {
@@ -26,6 +28,7 @@ interface Props {
 const { code, lang = "txt", icons, title } = Astro.props;
 const html = await highlightCode(code.replace(/\n+$/u, ""), lang, {
   icons,
+  themes: data.config.codeThemes,
   title,
 });
 ---

package/src/components/content/Component.astro

@@ -5,14 +5,18 @@
 // `<Component path="forms/login" />` for `examples/forms/login.tsx`.
 //
 // Blume discovers `examples/` at build time and generates `blume:examples`: a
-// map of path → { Component (a static hydration wrapper), code, lang }. React,
-// Vue, Svelte, and Astro examples are all supported. The source is highlighted
-// with the same Shiki setup as ordinary code fences.
+// map of path → { Component (a static hydration wrapper), code, lang } plus
+// the route base preview frames live under. React, Vue, Svelte, and Astro
+// examples are all supported. The source is highlighted with the same Shiki
+// setup as ordinary code fences.
+import data from "blume:data";
+
 import { highlightCode } from "../../markdown/index.ts";
+import { withBase } from "../islands/base-path.ts";
 import Tab from "./Tab.astro";
 import Tabs from "./Tabs.astro";
 // Generated per project; resolves to an empty map when there are no examples.
-import { examples } from "blume:examples";
+import { examples, examplesBase } from "blume:examples";
 
 interface Props {
   path: string;
@@ -20,14 +24,27 @@ interface Props {
 
 const { path } = Astro.props;
 const entry = examples[path];
-const Preview = entry?.Component;
+
+// The live preview renders in its own generated route, embedded as an iframe:
+// the frame boundary is what keeps the docs CSS (prose typography, component
+// chrome) out of the example entirely, so users can preview components styled
+// by their own design system (e.g. shadcn, via the configured `examples.css`).
+// The frame syncs its theme with this document before first paint.
+const previewSrc = entry
+  ? withBase(
+      `${examplesBase}/${path.split("/").map(encodeURIComponent).join("/")}`
+    )
+  : undefined;
 
 // Highlight the source with the shared helper so it matches Markdown fences.
 // `blume-source` makes the inner `<code>` (not the `<pre>`) the scroll/height-
 // capped box — see the theme entry — so the copy button, pinned to the `<pre>`,
 // stays put. This pane already lives inside `.prose`, so the theme styles it.
 const codeHtml = entry
-  ? await highlightCode(entry.code, entry.lang, { className: "blume-source" })
+  ? await highlightCode(entry.code, entry.lang, {
+      className: "blume-source",
+      themes: data.config.codeThemes,
+    })
   : undefined;
 
 // Both tabs share one height so toggling them never shifts the layout. Size it
@@ -45,16 +62,13 @@ const paneStyle = `height:${paneHeight}px`;
     // `sync={false}`: each preview's Preview/Code tabs are independent — unlike
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
-      <Tab
-        // `not-prose`: the preview lives inside the page's `.prose` wrapper, so
-        // without this the typography styles bleed into the live component
-        // (headings, links, lists, spacing). The Code pane below keeps prose on
-        // purpose — that's what styles the highlighted source.
-        class="not-prose flex items-center justify-center overflow-auto"
-        style={paneStyle}
-        title="Preview"
-      >
-        <Preview />
+      <Tab class="overflow-hidden p-0!" style={paneStyle} title="Preview">
+        <iframe
+          class="h-full w-full"
+          loading="lazy"
+          src={previewSrc}
+          title={`Preview of ${path}`}
+        />
       </Tab>
       <Tab class="overflow-hidden" style={paneStyle} title="Code">
         <Fragment set:html={codeHtml} />

package/src/components/content/Diff.astro

@@ -6,6 +6,8 @@
 //
 // Inputs (one of): `patch`/`src` (unified patch), `before`+`after` (file paths),
 // or `old`+`new` (inline strings, with optional `lang`).
+import data from "blume:data";
+
 import { renderDiff } from "./diff.ts";
 
 interface Props {
@@ -22,7 +24,7 @@ let html: string | undefined;
 let error: string | undefined;
 
 try {
-  html = await renderDiff(Astro.props);
+  html = await renderDiff({ ...Astro.props, theme: data.config.codeThemes });
 } catch (cause) {
   error = cause instanceof Error ? cause.message : String(cause);
 }

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

@@ -9,7 +9,17 @@
  */
 import nodePath from "node:path";
 
-import type * as TypeScriptApi from "typescript";
+import type {
+  CompilerHost,
+  CompilerOptions,
+  DeclarationStatement,
+  Program,
+} from "typescript";
+
+// `typeof import(...)` is the only way to name the whole lazily-imported
+// `typescript` module without a value import (see components/props.ts).
+// oxlint-disable-next-line typescript/consistent-type-imports
+type TypeScriptApi = typeof import("typescript");
 
 /** A single documented property — one generated row of a type table. */
 export interface TypeTableProperty {
@@ -36,10 +46,10 @@ const VIRTUAL_FILE = "__blume_auto_type_table__.ts";
 
 /** Build a compiler host that serves a single in-memory file plus the real libs. */
 const inMemoryHost = (
-  ts: typeof TypeScriptApi,
-  options: TypeScriptApi.CompilerOptions,
+  ts: TypeScriptApi,
+  options: CompilerOptions,
   source: string
-): TypeScriptApi.CompilerHost => {
+): CompilerHost => {
   const host = ts.createCompilerHost(options, true);
   const getSourceFile = host.getSourceFile.bind(host);
   host.getSourceFile = (requested, languageVersion, onError, shouldCreate) =>
@@ -65,9 +75,9 @@ export const extractTypeTable = async (
 ): Promise<TypeTableProperty[]> => {
   const { name, path, root = process.cwd(), source } = options;
   const tsModule = await import("typescript");
-  const ts = (tsModule.default ?? tsModule) as typeof TypeScriptApi;
+  const ts = (tsModule.default ?? tsModule) as TypeScriptApi;
 
-  const compilerOptions: TypeScriptApi.CompilerOptions = {
+  const compilerOptions: CompilerOptions = {
     allowJs: true,
     module: ts.ModuleKind.ESNext,
     moduleResolution: ts.ModuleResolutionKind.Bundler,
@@ -78,7 +88,7 @@ export const extractTypeTable = async (
   };
 
   let fileName: string;
-  let program: TypeScriptApi.Program;
+  let program: Program;
   if (source === undefined) {
     if (path === undefined) {
       throw new Error("AutoTypeTable needs a `path` or inline `type` source.");
@@ -100,7 +110,7 @@ export const extractTypeTable = async (
   }
 
   const declaration = sourceFile.statements.find(
-    (statement): statement is TypeScriptApi.DeclarationStatement =>
+    (statement): statement is DeclarationStatement =>
       (ts.isInterfaceDeclaration(statement) ||
         ts.isTypeAliasDeclaration(statement)) &&
       statement.name?.text === name

package/src/components/content/diff.ts

@@ -13,6 +13,9 @@ import { readFile } from "node:fs/promises";
 import { preloadDiffHTML, preloadPatchDiff } from "@pierre/diffs/ssr";
 import { isAbsolute, join } from "pathe";
 
+import { DEFAULT_CODE_THEMES } from "../../markdown/themes.ts";
+import type { CodeThemes } from "../../markdown/themes.ts";
+
 export interface DiffOptions {
   /** Path to the "after" file, resolved relative to {@link DiffOptions.root}. */
   after?: string;
@@ -30,11 +33,13 @@ export interface DiffOptions {
   root?: string;
   /** Path to a `.patch`/`.diff` file, resolved relative to {@link DiffOptions.root}. */
   src?: string;
+  /**
+   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * github pair Blume's code blocks use, keeping diffs in lockstep.
+   */
+  theme?: CodeThemes;
 }
 
-/** Dual-theme config mirroring Blume's Shiki convention (see `templates.ts`). */
-const THEME = { dark: "github-dark", light: "github-light" } as const;
-
 const resolvePath = (path: string, root: string): string =>
   isAbsolute(path) ? path : join(root, path);
 
@@ -56,12 +61,13 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     patch,
     root = process.cwd(),
     src,
+    theme = DEFAULT_CODE_THEMES,
   } = options;
 
   if (patch !== undefined || src !== undefined) {
     const text = patch ?? (await readText(src as string, root));
     const result = await preloadPatchDiff({
-      options: { theme: THEME },
+      options: { theme },
       patch: text,
     });
     return result.prerenderedHTML;
@@ -74,7 +80,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: await readText(after, root), name: after },
       oldFile: { contents: await readText(before, root), name: before },
-      options: { theme: THEME },
+      options: { theme },
     });
   }
 
@@ -85,7 +91,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: newText, lang, name: "snippet" },
       oldFile: { contents: old, lang, name: "snippet" },
-      options: { disableFileHeader: true, theme: THEME },
+      options: { disableFileHeader: true, theme },
     });
   }
 

package/src/components/content/mermaid-element.ts

@@ -55,6 +55,9 @@ class BlumeMermaid extends HTMLElement {
         // A newer render (rapid theme toggles) superseded this one — dropping
         // the stale result keeps the diagram in the latest theme.
         if (token === this.#renderToken) {
+          // Mermaid's own render output is SVG markup; it must be injected as
+          // HTML, not text. securityLevel "strict" (see initialize) sanitizes it.
+          // oxlint-disable-next-line github/no-inner-html -- Mermaid-generated SVG must be injected as HTML
           output.innerHTML = svg;
         }
       } catch {

package/src/components/index.ts

@@ -11,4 +11,26 @@ export type {
   IslandDescriptor,
 } from "../core/define-components.ts";
 export type { HydrationMode } from "../core/schema.ts";
-export type * from "./props.ts";
+export type {
+  AccordionItemProps,
+  AccordionProps,
+  BadgeProps,
+  CalloutProps,
+  CardGroupProps,
+  CardProps,
+  CodeGroupProps,
+  ColumnProps,
+  ColumnsProps,
+  ExpandableProps,
+  FrameProps,
+  IconProps,
+  PanelProps,
+  PromptProps,
+  StepProps,
+  StepsProps,
+  TabProps,
+  TabsProps,
+  TileProps,
+  TooltipProps,
+  YouTubeProps,
+} from "./props.ts";

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

@@ -78,6 +78,9 @@ const renderMarkdown = (content: string): string =>
 const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
   <svg
     aria-hidden="true"
+    // `path` is a trusted, server-resolved Lucide glyph body (inline SVG),
+    // not user content; it must be injected as markup to render the icon.
+    // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
     dangerouslySetInnerHTML={{ __html: path }}
     fill="none"
     height={size}
@@ -126,7 +129,9 @@ const AskAI = ({
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
 
-  // Portal target (document.body) only exists after mount; guards SSR.
+  // Portal target (document.body) only exists after mount; guards SSR. The
+  // one-time false→true flip is deliberate, so the initial `false` is required.
+  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate post-mount portal guard
   useEffect(() => setMounted(true), []);
 
   // The search modal forwards its query so "Ask AI: <query>" carries straight in.
@@ -213,17 +218,19 @@ const AskAI = ({
       const decoder = new TextDecoder();
       let done = false;
       while (!done) {
-        // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+        // 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) {
           // Streaming mode: a multi-byte UTF-8 sequence split across chunks
           // must not flush as U+FFFD garbage.
+          // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
           assistant.content += decoder.decode(chunk.value, { stream: true });
           setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
         }
       }
     } catch {
+      // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
       assistant.content = t.error;
       setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
     } finally {
@@ -268,7 +275,6 @@ const AskAI = ({
             className={ICON_BUTTON_CLASS}
             disabled={!hasMessages}
             onClick={copyConversation}
-            title={t.copy}
             type="button"
           >
             <Glyph path={icons.copy} />
@@ -278,7 +284,6 @@ const AskAI = ({
             className={ICON_BUTTON_CLASS}
             disabled={!hasMessages}
             onClick={() => setMessages([])}
-            title={t.clear}
             type="button"
           >
             <Glyph path={icons.clear} />
@@ -287,7 +292,6 @@ const AskAI = ({
             aria-label={t.close}
             className={ICON_BUTTON_CLASS}
             onClick={() => setOpen(false)}
-            title={t.close}
             type="button"
           >
             <Glyph path={icons.close} size={18} />
@@ -311,6 +315,8 @@ const AskAI = ({
                   {message.content ? (
                     // biome-ignore lint/security/noDangerouslySetInnerHtml: sanitized above
                     <div
+                      // renderMarkdown runs marked output through DOMPurify.sanitize.
+                      // oxlint-disable-next-line react/no-danger -- sanitized (DOMPurify) rendered-markdown output
                       dangerouslySetInnerHTML={{
                         __html: renderMarkdown(message.content),
                       }}
@@ -339,6 +345,7 @@ const AskAI = ({
                 {suggestion.icon && (
                   <span
                     className="shrink-0 text-muted-foreground [&_svg]:h-[18px] [&_svg]:w-[18px]"
+                    // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
                     dangerouslySetInnerHTML={{ __html: suggestion.icon }}
                   />
                 )}
@@ -391,7 +398,6 @@ const AskAI = ({
         aria-label={t.title}
         className={TRIGGER_CLASS}
         onClick={() => setOpen((value) => !value)}
-        title={t.title}
         type="button"
       >
         <Glyph path={icons.chat} size={18} />

package/src/components/islands/base-path.ts

@@ -13,6 +13,34 @@ export const withTrailingSlash = (base: string): string =>
 export const joinBase = (base: string, path: string): string =>
   `${withTrailingSlash(base)}${path}`;
 
+/**
+ * Prefix a root-relative internal route with the deployment base
+ * (`/guide` under base `/sub` -> `/sub/guide`), so a rendered link points at the
+ * page's real served URL. External URLs, protocol-relative URLs, and fragments
+ * pass through untouched, and it's idempotent (a route already under the base is
+ * returned unchanged). This is applied only where a URL is *emitted* — the
+ * navigation model and active-route matching stay in base-less logical space.
+ */
+export const prefixBase = (base: string, route: string): string => {
+  if (!route.startsWith("/") || route.startsWith("//")) {
+    return route;
+  }
+  const trimmed = base.replace(/\/+$/u, "");
+  if (!trimmed || route === trimmed || route.startsWith(`${trimmed}/`)) {
+    return route;
+  }
+  return route === "/" ? trimmed : `${trimmed}${route}`;
+};
+
+/**
+ * {@link prefixBase} bound to the build-time `BASE_URL` (the resolved
+ * `deployment.base`). The ergonomic form for `.astro` templates — `href={
+ * withBase(route)}` — since `BASE_URL` is inlined by Vite wherever this module
+ * is bundled into the site.
+ */
+export const withBase = (route: string): string =>
+  prefixBase(import.meta.env.BASE_URL ?? "/", route);
+
 /**
  * A pathname with the deployment base stripped (`/docs/guide` -> `/guide`),
  * for page-context lookups against base-less document routes.

package/src/components/islands/hooks.ts

@@ -50,6 +50,10 @@ const readClientData = (): BlumeClientData | null => {
  */
 const useClientData = (): BlumeClientData | null => {
   const [data, setData] = useState<BlumeClientData | null>(null);
+  // Intentional post-mount hydration guard: `null` on the server and first
+  // client render so hydration matches, then the snapshot once mounted. The
+  // extra render is required; do not seed the initial value from the DOM.
+  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate SSR hydration guard
   useEffect(() => setData(readClientData()), []);
   return data;
 };
@@ -86,6 +90,10 @@ export const useSearch = (): UseSearch => {
   const [loading, setLoading] = useState(false);
   const searchFn = useRef<SearchFn | null>(null);
 
+  // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
+  // this useCallback keeps a stable `search` identity for consumers that use it
+  // as an effect/memo dependency. With the compiler on it's redundant but inert.
+  // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
   const search = useCallback<UseSearch["search"]>(async (query, options) => {
     if (!searchFn.current) {
       const { createSearch } = await import("blume:search-client");
@@ -132,6 +140,10 @@ export const useAskAI = (): UseAskAI => {
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
 
+  // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
+  // preserves a stable `ask` identity for consumers that depend on it. With the
+  // compiler on it's redundant but inert.
+  // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
   const ask = useCallback<UseAskAI["ask"]>(
     async (question) => {
       const trimmed = question.trim();
@@ -167,7 +179,7 @@ export const useAskAI = (): UseAskAI => {
         if (reader) {
           let done = false;
           while (!done) {
-            // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+            // 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) {
@@ -190,6 +202,9 @@ export const useAskAI = (): UseAskAI => {
     [loading, messages]
   );
 
+  // 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([]), []);
 
   return { ask, loading, messages, reset };

package/src/components/layout/Banner.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
 // The site-wide announcement banner, shared by RootLayout and ReferenceLayout so
@@ -29,7 +30,7 @@ const { banner } = Astro.props;
       {banner.link && (
         <a
           class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
-          href={banner.link.href}
+          href={withBase(banner.link.href)}
         >
           {banner.link.text}
           <Icon name="arrow-right" size={14} />

package/src/components/layout/Breadcrumbs.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { Crumb } from "./nav-utils.ts";
 
 interface Props {
@@ -25,7 +26,7 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       ]}
     >
       {eyebrowCrumb.route ? (
-        <a class="hover:text-foreground" href={eyebrowCrumb.route}>
+        <a class="hover:text-foreground" href={withBase(eyebrowCrumb.route)}>
           {eyebrowCrumb.label}
         </a>
       ) : (

package/src/components/layout/Favicon.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // Emits the icon <link>s for the document <head>: the favicon (rel="icon") and,
 // when the project ships one, the Apple touch icon (rel="apple-touch-icon").
 // Each href is either a URL to a file the project ships in public/, or a data
@@ -18,5 +19,5 @@ interface Props {
 const { appleIcon, favicon } = Astro.props;
 ---
 
-{favicon && <link href={favicon.href} rel="icon" type={favicon.type} />}
-{appleIcon && <link href={appleIcon.href} rel="apple-touch-icon" />}
+{favicon && <link href={withBase(favicon.href)} rel="icon" type={favicon.type} />}
+{appleIcon && <link href={withBase(appleIcon.href)} rel="apple-touch-icon" />}

package/src/components/layout/Header.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
@@ -139,7 +140,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
                 : undefined
             }
             class="rounded-full px-3 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:text-foreground"
-            href={tab.path}
+            href={withBase(tab.path)}
           >
             {tab.label}
           </a>

package/src/components/layout/LanguageSwitcher.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { LocaleSwitchOption } from "../../core/types.ts";
 import Icon from "../Icon.astro";
 
@@ -37,7 +38,7 @@ const menuRowClass =
           <a
             aria-current={option.current ? "true" : undefined}
             class={menuRowClass}
-            href={option.href}
+            href={withBase(option.href)}
             hreflang={option.code}
             lang={option.code}
           >

package/src/components/layout/Logo.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // The site brand: the logo mark (inline SVG so a `currentColor` mark follows the
 // theme, or light/dark `<img>` variants) followed by the site title, wrapped in
 // a link to the brand href. Extracted from the header so it can be replaced on
@@ -27,7 +28,7 @@ const brandText = logo?.text ?? site.title;
 
 <a
   class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
-  href={brandHref}
+  href={withBase(brandHref)}
 >
   {
     logoSvg && (

package/src/components/layout/NavSelector.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // A top-level navigation selector: a dropdown that switches
 // between partitions of the site — a product, a version, or any grouped set of
 // destinations (`navigation.selectors` in the config). Zero-JS, built on
@@ -50,7 +51,7 @@ const menuRowClass =
           <a
             aria-current={item.path === active?.path ? "true" : undefined}
             class={menuRowClass}
-            href={item.path}
+            href={withBase(item.path)}
           >
             {item.icon && <Icon class="mt-0.5" name={item.icon} size={16} />}
             <span class="flex-1">

package/src/components/layout/NavTree.astro

@@ -1,6 +1,7 @@
 ---
 import type { NavNode } from "../../core/types.ts";
 import Icon from "../Icon.astro";
+import { withBase } from "../islands/base-path.ts";
 import Self from "./NavTree.astro";
 
 interface PagePanel {
@@ -130,7 +131,7 @@ const initialId =
               <a
                 aria-current={panel.route === currentRoute ? "page" : undefined}
                 class="flex-1 truncate font-semibold text-foreground text-sm hover:underline"
-                href={panel.route}
+                href={withBase(panel.route)}
               >
                 {panel.label}
               </a>
@@ -159,7 +160,7 @@ const initialId =
               <a
                 aria-current={item.route === currentRoute ? "page" : undefined}
                 class="block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground"
-                href={item.route}
+                href={withBase(item.route)}
               >
                 <span class="flex items-center gap-2">
                   {item.icon && (
@@ -231,7 +232,7 @@ const initialId =
                         item.route === currentRoute ? "page" : undefined
                       }
                       class="-my-1 flex flex-1 items-center gap-1.5 rounded py-1 transition-colors aria-[current=page]:text-foreground aria-[current=page]:font-semibold"
-                      href={item.route}
+                      href={withBase(item.route)}
                     >
                       {item.icon && (
                         <Icon
@@ -286,7 +287,7 @@ const initialId =
                 <a
                   aria-current={item.route === currentRoute ? "page" : undefined}
                   class="-ml-1 flex flex-1 items-center gap-1.5 rounded px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted"
-                  href={item.route}
+                  href={withBase(item.route)}
                 >
                   {item.icon && (
                     <Icon

package/src/components/layout/PageFeedback.astro

@@ -9,7 +9,10 @@ interface Props {
 }
 
 const { strings } = Astro.props;
-const f = strings ?? EN_UI.feedback;
+// Merge over the English baseline per key (rather than `strings ?? …`) so a
+// partial — or empty `{}` — strings object still resolves every label to a
+// default, matching the pattern PageActions and Search use.
+const f = { ...EN_UI.feedback, ...strings };
 
 const buttonClass =
   "inline-flex items-center gap-2 rounded-full border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";