blume 0.8.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -128,6 +128,8 @@
     "@ai-sdk/openai-compatible": "^1.0.41",
     "@astrojs/cloudflare": "^14.0.0",
     "@astrojs/netlify": "^8.0.0",
+    "@astrojs/svelte": "^9.0.0",
+    "@astrojs/vue": "^7.0.0",
     "@mixedbread/sdk": "^0.76.0",
     "@notionhq/client": "^2.2.15",
     "@openrouter/ai-sdk-provider": "^1.5.4",
@@ -147,6 +149,12 @@
     "@astrojs/netlify": {
       "optional": true
     },
+    "@astrojs/svelte": {
+      "optional": true
+    },
+    "@astrojs/vue": {
+      "optional": true
+    },
     "@mixedbread/sdk": {
       "optional": true
     },

package/src/ai/mcp/tools.ts

@@ -26,7 +26,7 @@ export const MCP_TOOLS: McpToolMeta[] = [
   {
     annotations: READ_ONLY,
     description:
-      "Fetch a single documentation page as its original Markdown source (frontmatter included). Pass a route from `search_docs` or `list_pages`, e.g. `/guides/install`.",
+      "Fetch a single documentation page as agent-optimized Markdown (frontmatter included, components downleveled to plain Markdown). Pass a route from `search_docs` or `list_pages`, e.g. `/guides/install`.",
     name: "get_page",
     title: "Get page Markdown",
   },

package/src/astro/generate.ts

@@ -881,6 +881,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      x: config.seo.x,
     },
     feeds: buildRssFeeds(project).map((feed) => ({
       href: feed.path,

package/src/astro/templates.ts

@@ -187,18 +187,31 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * Excludes Vite's pre-bundled dep cache from @vitejs/plugin-react. Astro's
+ * react() replaces the plugin's default `/node_modules/` exclude with just
+ * `/\.astro$/`, so without this Babel re-parses every optimized dep chunk
+ * served from `.vite/deps` — a 500KB+ vendor bundle per chunk, re-done on each
+ * re-optimization. A blanket `/node_modules/` exclude would instead switch the
+ * React Compiler off for Blume's own components in published installs (they
+ * resolve under `node_modules/blume/src`, and exclude beats include in the
+ * plugin's filter), so only the pre-bundle cache is excluded.
+ */
+const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//]`;
+
 /**
  * The `react()` integration call. When `compilerPath` is set (the resolved
  * absolute path to `babel-plugin-react-compiler`), react() carries the compiler
  * as the first babel plugin — an absolute path, because @vitejs/plugin-react
  * resolves babel plugins from the *project* root, not `.blume/`, so a bare
  * specifier wouldn't resolve in a user project. `target: "19"` matches Blume's
- * React pin. `null`/`undefined` (compiler off or unresolvable) emits bare react().
+ * React pin. `null`/`undefined` (compiler off or unresolvable) omits the babel
+ * block. Both variants carry the pre-bundle exclude above.
  */
 const reactIntegration = (compilerPath: string | null | undefined): string =>
   compilerPath
-    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] } })`
-    : "react()";
+    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })`
+    : `react({ ${REACT_EXCLUDE} })`;
 
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
@@ -1023,12 +1036,24 @@ import data from ${JSON.stringify(options.dataImport)};
 export const prerender = true;
 
 const configuration = ${JSON.stringify(options.configuration, null, 2)};
+
+// The reference is an unlocalized route, so its chrome renders in the default
+// locale's language and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the changelog index's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 ---
 
 <ReferenceLayout
   analytics={data.config.analytics}
   banner={data.config.banner}
+  dir={dir}
   fontCssVars={data.fontCssVars}
+  locale={htmlLang}
   logo={data.config.logo}
   favicon={data.config.favicon}
   appleIcon={data.config.appleIcon}
@@ -1202,6 +1227,13 @@ const ogRel = seo.image ?? ogPath;
 // an external URL, which passes through verbatim (mirrors PageLayout).
 const ogImage =
   ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
+// Blume's generated card has known dimensions the layout can declare; a user's
+// \`seo.image\` could be any size or format, so it gets none.
+const ogGenerated = !seo.image && Boolean(ogPath);
+
+// X attribution: the site's account, plus a creator the page can claim for
+// itself (a guest post crediting its own author) over the configured default.
+const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
 const basedRoute = withBase(route);
 const canonical =
@@ -1298,6 +1330,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={indexable}
   ogImage={ogImage}
+  ogGenerated={ogGenerated}
+  x={x}
   canonical={canonical}
   editUrl={editUrl}
   feedback={data.config.feedback}
@@ -1341,7 +1375,7 @@ export const changelogIndexTemplate = (options: {
     ? '\n  <AskAI slot="ask" strings={data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
     : "";
   const clientData = options.needsReact
-    ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: data.config.title + " changelog" } }}'
+    ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: pageTitle } }}'
     : "";
   // Staged sources (e.g. GitHub Releases) render through a parallel collection,
   // so fold them in alongside filesystem entries when one exists.
@@ -1484,6 +1518,15 @@ const localeMeta = i18n
 const dir = localeMeta?.dir ?? "ltr";
 const htmlLang = i18n ? i18n.defaultLocale : "en";
 
+// The page chrome (h1, title, description) comes from the same translatable
+// \`changelog\` group as the reveal button; optional chaining tolerates a
+// not-yet-regenerated data snapshot from before these keys existed.
+const changelogTitle = data.ui.changelog?.title ?? "Changelog";
+const changelogDescription =
+  data.ui.changelog?.description ??
+  "Product updates, new features, and fixes from every release.";
+const pageTitle = data.config.title + " " + changelogTitle;
+
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
 
@@ -1503,8 +1546,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   dir={dir}
   ui={data.ui}
   page={{
-    title: data.config.title + " changelog",
-    description: "Product updates and release notes.",
+    title: pageTitle,
+    description: changelogDescription,
     route: "/changelog",
   }}
   headings={headings}
@@ -1515,6 +1558,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={true}
   ogImage={null}
+  x={data.config.x}
   canonical={canonical}
   askEnabled={${options.askEnabled}}
   exportPdf={${options.exportPdf}}
@@ -1524,7 +1568,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   noindex={false}
   structuredDataEnabled={data.config.structuredData}
 >${askSlot}
-  <h1>Changelog</h1>
+  <h1>{changelogTitle}</h1>
   {
     items.length === 0 ? (
       <p>No changelog entries yet.</p>

package/src/cli/commands/build.ts

@@ -64,7 +64,10 @@ const validateBudgetFlags = (args: BudgetArgs): void => {
 /**
  * Emit platform redirect files for a static build (adapters wire redirects
  * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
- * when the user hasn't shipped one via public/.
+ * when the user hasn't shipped one via public/. Note that Vercel's
+ * git-integration builds read `vercel.json` from the repository root only —
+ * the copy emitted here takes effect when the dist folder itself is deployed
+ * directly via the Vercel CLI.
  */
 const emitRedirectFiles = async (
   config: ResolvedConfig,
@@ -209,6 +212,22 @@ export const runClientAssetChecks = async (
   }
 };
 
+/**
+ * Root of an isolated build's output. The runtime-local `dist/`, except for a
+ * Vercel server build, whose deploy bundle lands at `<runtime>/.vercel/output`
+ * and is never surfaced to the project root.
+ */
+export const isolatedOutputDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.outDir, ".vercel", "output");
+  }
+  return context.distDir ?? join(context.outDir, "dist");
+};
+
 /**
  * Directory holding an isolated build's client `_astro/` assets. Mirrors
  * `deployStaticDir`, except that an isolated build never surfaces the adapter
@@ -221,14 +240,14 @@ export const isolatedStaticDir = (
   context: ProjectContext
 ): string => {
   const { adapter, output } = config.deployment;
+  const outputDir = isolatedOutputDir(config, context);
   if (output === "server" && adapter === "vercel") {
-    return join(context.outDir, ".vercel", "output", "static");
+    return join(outputDir, "static");
   }
-  const dist = context.distDir ?? join(context.outDir, "dist");
   if (output === "server" && adapter === "node") {
-    return join(dist, "client");
+    return join(outputDir, "client");
   }
-  return dist;
+  return outputDir;
 };
 
 /**
@@ -442,8 +461,6 @@ export const buildCommand = defineCommand({
       root: project.context.outDir,
     });
 
-    const distDir = project.context.distDir ?? join(root, "dist");
-
     // An isolated build is a throwaway verify: it only needs to confirm the site
     // compiles and renders. Skip the network post-steps (search sync) and
     // deploy artifacts (index/llms/sitemap/robots/redirects) that only matter
@@ -457,7 +474,7 @@ export const buildCommand = defineCommand({
         args
       );
       logger.success(
-        `Isolated build OK — output at ${distDir} (not published).`
+        `Isolated build OK — output at ${isolatedOutputDir(project.config, project.context)} (not published).`
       );
       return;
     }

package/src/cli/internal-error.ts

@@ -8,9 +8,14 @@ const RESET = `${ESC}[0m`;
 
 const ISSUES_URL = "https://github.com/haydenbleasel/blume/issues";
 
-// Absolute paths into the hidden generated runtime (`…/.blume/…`), including any
-// trailing `:line:col`, stopping at whitespace or a closing paren.
-const BLUME_FRAME = /(?<abs>\/[^\s()]*\/\.blume\/[^\s()]*)/gu;
+// Absolute paths into the hidden generated runtime — POSIX (`…/.blume/…`) or
+// Windows drive-letter (`C:\…\.blume\…`) — including any trailing `:line:col`,
+// stopping at whitespace or a closing paren.
+const BLUME_FRAME =
+  /(?<abs>(?:\/[^\s()]*\/|[A-Za-z]:\\[^\s()]*\\)\.blume[/\\][^\s()]*)/gu;
+
+// The separator immediately before `.blume/` (or `.blume\`) in a matched path.
+const BLUME_MARKER = /[/\\]\.blume[/\\]/u;
 
 /**
  * Rewrite `.blume/` frames in a stack so the generated runtime reads clearly:
@@ -22,7 +27,7 @@ const BLUME_FRAME = /(?<abs>\/[^\s()]*\/\.blume\/[^\s()]*)/gu;
  */
 export const remapBlumeStack = (stack: string): string =>
   stack.replaceAll(BLUME_FRAME, (match) => {
-    const marker = match.indexOf("/.blume/");
+    const marker = match.search(BLUME_MARKER);
     return `${match.slice(marker + 1)} (generated)`;
   });
 

package/src/cli/prepare.ts

@@ -35,8 +35,9 @@ export interface PrepareOptions {
 export const prepareProject = async (
   options: PrepareOptions
 ): Promise<BlumeProject> => {
-  // Honor a `--root` that differs from cwd: remote sources read env during the
-  // scan below, and `loadEnvFiles` is a no-op for vars already set (cwd load).
+  // Load `.env` files from the project root before the scan: remote sources
+  // read their tokens from `process.env` during `scanProject`, and
+  // `loadEnvFiles` never overrides variables that are already set.
   loadEnvFiles(options.root);
 
   let project: BlumeProject;

package/src/components/Icon.astro

@@ -1,5 +1,6 @@
 ---
 import { resolveIcon } from "../theme/icons.ts";
+import { withBase } from "./islands/base-path.ts";
 
 interface Props {
   name?: unknown;
@@ -69,7 +70,7 @@ const style = color ? `color:${color}` : undefined;
       aria-hidden={label ? undefined : "true"}
       class={resolvedClass}
       height={size}
-      src={imageSrc}
+      src={withBase(imageSrc)}
       width={size}
     />
   ) : (

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

@@ -154,6 +154,13 @@ const AskAI = ({
   const triggerRef = useRef<HTMLButtonElement>(null);
   // Where focus came from when the panel opened, restored on close.
   const returnFocusRef = useRef<HTMLElement | null>(null);
+  // The stream writes into the conversation via functional updates, so "Clear
+  // conversation" mid-answer must revoke the in-flight stream's right to write
+  // — otherwise its next chunk re-appends the assistant bubble onto the
+  // emptied list as an orphaned answer. Clearing bumps the generation (stale
+  // streams stop writing) and aborts the request (the stream stops arriving).
+  const abortRef = useRef<AbortController | null>(null);
+  const generationRef = useRef(0);
 
   // Portal target (document.body) only exists after mount; guards SSR. The
   // one-time false→true flip is deliberate, so the initial `false` is required.
@@ -239,6 +246,9 @@ const AskAI = ({
     setMessages([...history, assistant]);
     setInput("");
     setBusy(true);
+    const generation = generationRef.current;
+    const controller = new AbortController();
+    abortRef.current = controller;
 
     try {
       const response = await fetch(ASK_ENDPOINT, {
@@ -248,6 +258,7 @@ const AskAI = ({
         }),
         headers: { "content-type": "application/json" },
         method: "POST",
+        signal: controller.signal,
       });
       // A 4xx/5xx still has a body; without this guard its error text would be
       // decoded and shown as the assistant's answer instead of the error notice.
@@ -266,18 +277,32 @@ const AskAI = ({
           // 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 }]);
+          if (generationRef.current === generation) {
+            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 }]);
+      // A cleared (aborted) stream must not resurrect its bubble as an error.
+      if (generationRef.current === generation) {
+        // 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 {
       setBusy(false);
     }
   };
 
+  const clearConversation = () => {
+    generationRef.current += 1;
+    abortRef.current?.abort();
+    setMessages([]);
+  };
+
   const onSubmit = (event: FormEvent) => {
     event.preventDefault();
     void runQuestion(input);
@@ -332,7 +357,7 @@ const AskAI = ({
             aria-label={t.clear}
             className={ICON_BUTTON_CLASS}
             disabled={!hasMessages}
-            onClick={() => setMessages([])}
+            onClick={clearConversation}
             type="button"
           >
             <Glyph path={icons.clear} />

package/src/components/layout/Breadcrumbs.astro

@@ -1,15 +1,24 @@
 ---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
 import { withBase } from "../islands/base-path.ts";
 import type { Crumb } from "./nav-utils.ts";
 
 interface Props {
   /** Full breadcrumb trail from the site root to the current page. */
   crumbs: Crumb[];
+  /** Localized nav labels (the landmark's `aria-label`); English when omitted. */
+  strings?: UIStrings["nav"];
   /** Left-align full width (for the wide API layout) instead of the prose measure. */
   wide?: boolean;
 }
 
-const { crumbs, wide = false } = Astro.props;
+const { crumbs, strings, wide = false } = Astro.props;
+
+// Merge over the English defaults so a label missing from a translation (or
+// from a not-yet-regenerated snapshot) still renders instead of coming out
+// blank — the PageActions pattern.
+const n = { ...EN_UI.nav, ...strings };
 
 // The built-in shows a single "eyebrow" crumb — the parent group — rather than
 // the whole trail. An override receives the complete list and can render more.
@@ -19,7 +28,7 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
 {
   eyebrowCrumb && (
     <nav
-      aria-label="Breadcrumb"
+      aria-label={n.breadcrumb}
       class:list={[
         "mb-2 text-muted-foreground text-sm",
         wide ? "max-w-none" : "mx-auto max-w-[42rem]",

package/src/components/layout/NavTree.astro

@@ -136,7 +136,7 @@ const initialId =
               data-nav-back={panel.parentId}
               type="button"
             >
-              <Icon name="arrow-left" size={16} />
+              <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
             </button>
             {panel.route ? (
               <a
@@ -219,7 +219,7 @@ const initialId =
                 <span class="flex-1 truncate">{item.label}</span>
                 {item.badge && <span class={badgeClassFor(item.badge)}>{item.badge}</span>}
                 <Icon
-                  class="shrink-0 text-muted-foreground"
+                  class="shrink-0 text-muted-foreground rtl:-scale-x-100"
                   name="chevron-right"
                   size={14}
                 />

package/src/components/layout/PageLayout.astro

@@ -25,6 +25,12 @@ import type {
 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 {
+  OG_IMAGE_HEIGHT,
+  OG_IMAGE_TYPE,
+  OG_IMAGE_WIDTH,
+} from "../../og/dimensions.ts";
+import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import "blume:theme";
 import Analytics from "./Analytics.astro";
@@ -64,6 +70,11 @@ interface Props {
   /** SEO overrides; a marketing page often sets its own canonical/og image. */
   ogImage?: string | null;
   canonical?: string | null;
+  /**
+   * X (Twitter) attribution (`data.config.x`): the site's account and an author
+   * handle, emitted as `twitter:site`/`twitter:creator`.
+   */
+  x?: { creator?: string; handle?: string };
   noindex?: boolean;
   /** Active locale + direction for `<html lang>`/`<html dir>`. */
   locale?: string;
@@ -97,6 +108,7 @@ const {
   ogEnabled,
   ogImage,
   canonical,
+  x,
   noindex,
   locale = "en",
   dir = "ltr",
@@ -147,6 +159,15 @@ const resolvedOgImage = ogImage
   : ogEnabled && siteBase
     ? `${siteBase}${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.
+const ogGenerated = !ogImage && Boolean(resolvedOgImage);
+// A page with no image still gets a card on X — the compact `summary` variant
+// — rather than rendering as a bare link.
+const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
+// A custom page passes these in by hand, so normalize rather than trust the `@`.
+const xSite = normalizeXHandle(x?.handle);
+const xCreator = normalizeXHandle(x?.creator);
 
 const initialThemeScript = themeInitScript(themeMode);
 const bannerScript = banner?.dismissible
@@ -166,17 +187,35 @@ const bannerScript = banner?.dismissible
     {noindex && <meta content="noindex" name="robots" />}
     {description && <meta content={description} name="description" />}
     <meta content="website" property="og:type" />
+    <meta content={site.title} property="og:site_name" />
     <meta content={pageTitle} property="og:title" />
     {description && <meta content={description} property="og:description" />}
+    {resolvedCanonical && <meta content={resolvedCanonical} property="og:url" />}
     {
       resolvedOgImage && (
         <>
           <meta content={resolvedOgImage} property="og:image" />
+          {ogGenerated && (
+            <>
+              <meta content={OG_IMAGE_TYPE} property="og:image:type" />
+              <meta content={String(OG_IMAGE_WIDTH)} property="og:image:width" />
+              <meta
+                content={String(OG_IMAGE_HEIGHT)}
+                property="og:image:height"
+              />
+              <meta content={pageTitle} property="og:image:alt" />
+            </>
+          )}
           <meta content={resolvedOgImage} name="twitter:image" />
-          <meta content="summary_large_image" name="twitter:card" />
+          {ogGenerated && <meta content={pageTitle} name="twitter:image:alt" />}
         </>
       )
     }
+    <meta content={twitterCard} name="twitter:card" />
+    <meta content={pageTitle} name="twitter:title" />
+    {description && <meta content={description} name="twitter:description" />}
+    {xSite && <meta content={xSite} name="twitter:site" />}
+    {xCreator && <meta content={xCreator} name="twitter:creator" />}
     {bannerScript && <script is:inline set:html={bannerScript} />}
     <script is:inline set:html={initialThemeScript} />
     <Analytics analytics={analytics} />

package/src/components/layout/Pagination.astro

@@ -1,5 +1,6 @@
 ---
 import { withBase } from "../islands/base-path.ts";
+import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { FlatPage } from "./nav-utils.ts";
 import Icon from "../Icon.astro";
@@ -9,17 +10,22 @@ interface Props {
   prev: FlatPage | null;
   /** Next page in reading order, or `null` at the end. */
   next: FlatPage | null;
-  /** Localized page-level strings (`previous`, `next`). */
+  /** Localized page-level strings (`previous`, `next`, the landmark label). */
   strings: UIStrings["page"];
 }
 
 const { prev, next, strings } = Astro.props;
+
+// Merge over the English defaults so a label missing from a translation (or
+// from a not-yet-regenerated snapshot) still renders instead of coming out
+// blank — the PageActions pattern.
+const s = { ...EN_UI.page, ...strings };
 ---
 
 {
   (prev || next) && (
     <nav
-      aria-label="Pagination"
+      aria-label={s.pagination}
       class="mx-auto mt-12 flex max-w-[42rem] justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
     >
       {prev ? (
@@ -30,7 +36,7 @@ const { prev, next, strings } = Astro.props;
           <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
           <span>
             <span class="block text-muted-foreground text-xs max-md:hidden">
-              {strings.previous}
+              {s.previous}
             </span>
             <span class="block font-medium">{prev.label}</span>
           </span>
@@ -45,7 +51,7 @@ const { prev, next, strings } = Astro.props;
         >
           <span>
             <span class="block text-muted-foreground text-xs max-md:hidden">
-              {strings.next}
+              {s.next}
             </span>
             <span class="block font-medium">{next.label}</span>
           </span>

package/src/components/layout/ReferenceLayout.astro

@@ -52,6 +52,10 @@ interface Props {
   fontCssVars?: string[];
   searchEnabled: boolean;
   pageTitle: string;
+  /** Active locale code for `<html lang>` (defaults to `en`). */
+  locale?: string;
+  /** Text direction for `<html dir>` (defaults to `ltr`). */
+  dir?: "ltr" | "rtl";
   /** Resolved UI dictionary; English baseline when omitted. */
   ui?: UIStrings;
 }
@@ -69,6 +73,8 @@ const {
   fontCssVars,
   searchEnabled,
   pageTitle,
+  locale = "en",
+  dir = "ltr",
   ui,
 } = Astro.props;
 
@@ -85,7 +91,7 @@ const bannerScript = banner?.dismissible
 ---
 
 <!doctype html>
-<html lang="en">
+<html dir={dir} lang={locale}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -97,6 +103,10 @@ const bannerScript = banner?.dismissible
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
+    <a
+      class="absolute start-[-999px] top-0 z-[100] bg-accent px-4 py-2 text-accent-foreground focus:start-0"
+      href="#blume-content">{strings.page.skipToContent}</a
+    >
     <Banner banner={banner} strings={strings.banner} />
     <Header
       hasDrawer={false}
@@ -109,6 +119,7 @@ const bannerScript = banner?.dismissible
     />
     <div
       class="h-[calc(100dvh-4rem)] overflow-auto border-border border-t [&>[data-scalar-client]]:h-full"
+      id="blume-content"
     >
       <slot />
     </div>