blume 0.2.0 → 0.4.0

package/src/components/layout/Empty.astro

@@ -0,0 +1,6 @@
+---
+// A no-op layout slot: renders nothing regardless of props. Used as the built-in
+// fallback for the content-injection slots (Footer, PageHeader, PageFooter) that
+// have no default, so an unconfigured slot renders empty while `resolveSlot`
+// still returns a valid component and the generated pages stay type-safe.
+---

package/src/components/layout/Header.astro

@@ -1,9 +1,13 @@
 ---
+import type { ComponentOverride } from "../../core/define-components.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
+import Logo from "./Logo.astro";
+import NavSelector from "./NavSelector.astro";
+import { resolveSlot } from "./overrides.ts";
 import Search from "./Search.astro";
 
 interface Props {
@@ -27,6 +31,12 @@ interface Props {
   localeSwitch?: LocaleSwitchOption[];
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
+  /**
+   * Layout-slot overrides forwarded from the root layout. The header honors
+   * `Logo` and `Search` here so those pieces can be replaced without swapping
+   * the whole header.
+   */
+  layout?: Record<string, ComponentOverride>;
 }
 
 const {
@@ -41,15 +51,11 @@ const {
   switcherStrings,
   localeSwitch,
   searchLocale,
+  layout = {},
 } = Astro.props;
 
-// The logo is resolved upstream: an inline `svg` (so a currentColor mark
-// follows the theme) or image URL(s) for an <img>.
-const logoSvg = logo?.svg;
-const logoLight = logo?.light;
-const logoDark = logo?.dark ?? logo?.light;
-const logoAlt = logo?.alt ?? "";
-const brandHref = logo?.href ?? "/";
+const LogoSlot = resolveSlot(layout.Logo, Logo);
+const SearchSlot = resolveSlot(layout.Search, Search);
 
 const iconButton =
   "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
@@ -80,37 +86,16 @@ const clickScript = `document.addEventListener("click",(e)=>{const t=e.target.cl
       </button>
     )
   }
-  <a
-    class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
-    href={brandHref}
-  >
-    {
-      logoSvg && (
-        <span
-          aria-hidden="true"
-          class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
-          set:html={logoSvg}
-        />
-      )
-    }
-    {
-      !logoSvg &&
-        logoLight &&
-        (logoLight === logoDark ? (
-          <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
-        ) : (
-          <>
-            <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
-            <img
-              alt={logoAlt}
-              class="hidden h-5 w-auto dark:block"
-              src={logoDark}
-            />
-          </>
-        ))
-    }
-    {site.title}
-  </a>
+  <LogoSlot logo={logo} site={site} />
+  {
+    navigation.selectors.length > 0 && (
+      <div class="flex items-center gap-1.5">
+        {navigation.selectors.map((selector) => (
+          <NavSelector route={route} selector={selector} />
+        ))}
+      </div>
+    )
+  }
   {
     navigation.tabs.length > 0 && (
       <nav aria-label="Sections" class="hidden gap-1 md:flex">
@@ -144,7 +129,7 @@ const clickScript = `document.addEventListener("click",(e)=>{const t=e.target.cl
   }
   {
     searchEnabled && (
-      <Search
+      <SearchSlot
         askEnabled={askEnabled}
         locale={searchLocale}
         navigation={navigation}

package/src/components/layout/Logo.astro

@@ -0,0 +1,50 @@
+---
+// 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
+// its own through the `Logo` layout slot (`defineComponents({ layout: { Logo } })`).
+import type { BlumeLogo } from "../../core/data.ts";
+
+interface Props {
+  site: { title: string };
+  logo?: BlumeLogo | null;
+}
+
+const { site, logo } = Astro.props;
+
+// The logo is resolved upstream: an inline `svg` (so a currentColor mark follows
+// the theme) or image URL(s) for an <img>.
+const logoSvg = logo?.svg;
+const logoLight = logo?.light;
+const logoDark = logo?.dark ?? logo?.light;
+const logoAlt = logo?.alt ?? "";
+const brandHref = logo?.href ?? "/";
+---
+
+<a
+  class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
+  href={brandHref}
+>
+  {
+    logoSvg && (
+      <span
+        aria-hidden="true"
+        class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
+        set:html={logoSvg}
+      />
+    )
+  }
+  {
+    !logoSvg &&
+      logoLight &&
+      (logoLight === logoDark ? (
+        <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
+      ) : (
+        <>
+          <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
+          <img alt={logoAlt} class="hidden h-5 w-auto dark:block" src={logoDark} />
+        </>
+      ))
+  }
+  {site.title}
+</a>

package/src/components/layout/NavSelector.astro

@@ -0,0 +1,75 @@
+---
+// A top-level navigation selector (Mintlify-style): 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
+// <details>/<summary> like the language switcher.
+import type { NavSelector } from "../../core/types.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  selector: NavSelector;
+  route: string;
+}
+
+const { selector, route } = Astro.props;
+
+// The active item is the deepest path that prefixes the current route, falling
+// back to the first item so the summary always shows something meaningful.
+const active =
+  selector.items.find((item) => item.path === route) ??
+  selector.items
+    .filter((item) => route.startsWith(item.path))
+    .toSorted((a, b) => b.path.length - a.path.length)[0] ??
+  selector.items[0];
+
+const iconButton =
+  "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
+const menuRowClass =
+  "flex w-full items-start gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=true]:text-foreground";
+---
+
+{
+  selector.items.length > 0 && (
+    <details class="group relative">
+      <summary
+        aria-label={selector.label}
+        class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
+      >
+        {active?.icon && <Icon name={active.icon} size={16} />}
+        <span class="max-sm:hidden">{active?.label ?? selector.label}</span>
+        <Icon
+          class="transition-transform group-open:rotate-180"
+          name="chevron-down"
+          size={14}
+        />
+      </summary>
+      <div class="absolute start-0 z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl">
+        {selector.items.map((item) => (
+          <a
+            aria-current={item.path === active?.path ? "true" : undefined}
+            class={menuRowClass}
+            href={item.path}
+          >
+            {item.icon && <Icon class="mt-0.5" name={item.icon} size={16} />}
+            <span class="flex-1">
+              <span class="flex items-center gap-2">
+                {item.label}
+                {item.tag && (
+                  <span class="rounded-full bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
+                    {item.tag}
+                  </span>
+                )}
+              </span>
+              {item.description && (
+                <span class="mt-0.5 block text-muted-foreground text-xs">
+                  {item.description}
+                </span>
+              )}
+            </span>
+            {item.path === active?.path && <Icon name="check" size={14} />}
+          </a>
+        ))}
+      </div>
+    </details>
+  )
+}

package/src/components/layout/PageLayout.astro

@@ -17,6 +17,7 @@
 //   </PageLayout>
 import type {
   BlumeBanner,
+  BlumeClientData,
   BlumeDataConfig,
   BlumeFavicon,
   BlumeLogo,
@@ -69,6 +70,12 @@ interface Props {
   ui?: UIStrings;
   /** Language-switcher entries for the header. */
   localeSwitch?: LocaleSwitchOption[];
+  /**
+   * Snapshot for React island hooks (`blume/hooks`). Pass it when a custom page
+   * hosts islands that read `useBlume()`/`usePage()`:
+   * `clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title } }}`.
+   */
+  clientData?: BlumeClientData | null;
 }
 
 const {
@@ -93,8 +100,13 @@ const {
   dir = "ltr",
   ui,
   localeSwitch,
+  clientData,
 } = Astro.props;
 
+const clientDataJson = clientData
+  ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
+  : null;
+
 const strings = ui ?? EN_UI;
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
@@ -110,8 +122,17 @@ const route = page?.route ?? "/";
 const ogSlug = route === "/" ? "index" : route.slice(1);
 const resolvedCanonical =
   canonical ?? (siteUrl ? `${siteUrl}${route === "/" ? "" : route}` : null);
-const resolvedOgImage =
-  ogImage ?? (ogEnabled && siteUrl ? `${siteUrl}/og/${ogSlug}.png` : 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
+// back to the generated OG card for this route.
+const absolutizeOgImage = (value: string): string =>
+  value.startsWith("/") && siteUrl ? `${siteUrl}${value}` : value;
+const resolvedOgImage = ogImage
+  ? absolutizeOgImage(ogImage)
+  : ogEnabled && siteUrl
+    ? `${siteUrl}/og/${ogSlug}.png`
+    : null;
 
 const initialThemeScript = themeInitScript(themeMode);
 const bannerScript = banner?.dismissible
@@ -169,5 +190,20 @@ const bannerScript = banner?.dismissible
     </Header>
     <main id="blume-content"><slot /></main>
     <slot name="footer" />
+    {
+      clientDataJson && (
+        <script
+          id="blume-client-data"
+          is:inline
+          set:html={clientDataJson}
+          type="application/json"
+        />
+      )
+    }
+    <script>
+      // Dev-only: friendly hint after a React island hydration mismatch;
+      // tree-shaken out of production builds.
+      import "./hydration-hint.ts";
+    </script>
   </body>
 </html>

package/src/components/layout/RootLayout.astro

@@ -1,6 +1,7 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { BlumeClientData } from "../../core/data.ts";
 import type {
   Heading,
   LocaleSwitchOption,
@@ -12,6 +13,7 @@ import { buildStructuredData } from "../../seo/jsonld.ts";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Breadcrumbs from "./Breadcrumbs.astro";
+import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
@@ -108,9 +110,20 @@ interface Props {
   /**
    * User layout-slot overrides from `components.ts` (`defineComponents`). Each
    * key replaces the matching built-in; unknown keys are ignored. Wired slots:
-   * `Header`, `Sidebar`, `Breadcrumbs`, `TableOfContents`, `Pagination`.
+   * `Header`, `Logo`, `Search`, `Sidebar`, `MobileNav`, `Breadcrumbs`,
+   * `TableOfContents`, `Pagination`, `Feedback`, plus the content-injection slots
+   * `PageHeader`, `PageFooter`, and `Footer` (which have no built-in and render
+   * only when overridden). `Layout` (replacing this whole component) is wired in
+   * the generated page templates, not here.
    */
   layout?: Record<string, ComponentOverride>;
+  /**
+   * Snapshot serialized for React island hooks (`blume/hooks`). Rendered into a
+   * JSON `<script>` when present; omitted for zero-JS pages that need no islands.
+   */
+  clientData?: BlumeClientData | null;
+  /** Table-of-contents settings (`toc` config): visibility + heading range. */
+  toc?: { enabled: boolean; maxLevel: number; minLevel: number };
 }
 
 const {
@@ -152,21 +165,44 @@ const {
   xDefault,
   localeSwitch,
   layout = {},
+  clientData,
+  toc = { enabled: true, maxLevel: 3, minLevel: 2 },
 } = Astro.props;
 
+// Serialized once for island hooks; `<` escaped so content can't break the tag.
+const clientDataJson = clientData
+  ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
+  : null;
+
 // Layout-slot overrides: render the user's component when configured, else the
 // built-in. Each override receives the same props as the component it replaces.
+// `Logo` and `Search` are resolved inside the header (forwarded via `layout`).
 const HeaderSlot = resolveSlot(layout.Header, Header);
 const SidebarSlot = resolveSlot(layout.Sidebar, NavTree);
 const BreadcrumbsSlot = resolveSlot(layout.Breadcrumbs, Breadcrumbs);
 const TableOfContentsSlot = resolveSlot(layout.TableOfContents, TableOfContents);
 const PaginationSlot = resolveSlot(layout.Pagination, Pagination);
+// The mobile drawer reuses the sidebar unless a distinct `MobileNav` is given.
+const MobileNavSlot = layout.MobileNav
+  ? resolveSlot(layout.MobileNav, NavTree)
+  : null;
+// Content-injection slots with no built-in: the `Empty` fallback renders nothing
+// when unconfigured, so these are safe to render unconditionally.
+const FooterSlot = resolveSlot(layout.Footer, Empty);
+const PageHeaderSlot = resolveSlot(layout.PageHeader, Empty);
+const PageFooterSlot = resolveSlot(layout.PageFooter, Empty);
+// The "Was this page helpful?" rating (rendered only when `feedback` is on).
+const FeedbackSlot = resolveSlot(layout.Feedback, PageFeedback);
 
 const strings = ui ?? EN_UI;
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
   localeSwitch && localeSwitch.length > 1 ? locale : undefined;
-const tocHeadings = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+// TOC entries: the configured heading range, or none when the TOC is disabled
+// (an empty list makes TableOfContents render nothing).
+const tocHeadings = toc.enabled
+  ? headings.filter((h) => h.depth >= toc.minLevel && h.depth <= toc.maxLevel)
+  : [];
 const pageTitle = page.title ? `${page.title} - ${site.title}` : site.title;
 const description = page.description ?? site.description;
 
@@ -282,6 +318,7 @@ const bannerScript = banner?.dismissible
     <Banner banner={banner} />
     <HeaderSlot
       askEnabled={askEnabled}
+      layout={layout}
       localeSwitch={localeSwitch}
       logo={logo}
       navigation={navigation}
@@ -300,7 +337,20 @@ const bannerScript = banner?.dismissible
         class="fixed top-16 start-0 z-[35] h-[calc(100dvh-4rem)] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:z-auto lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
       >
         <nav>
-          <SidebarSlot currentRoute={page.route} items={sidebar} />
+          {
+            MobileNavSlot ? (
+              <>
+                <div class="lg:hidden">
+                  <MobileNavSlot currentRoute={page.route} items={sidebar} />
+                </div>
+                <div class="hidden lg:block">
+                  <SidebarSlot currentRoute={page.route} items={sidebar} />
+                </div>
+              </>
+            ) : (
+              <SidebarSlot currentRoute={page.route} items={sidebar} />
+            )
+          }
         </nav>
       </aside>
       <main class="min-w-0 px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
@@ -310,9 +360,11 @@ const bannerScript = banner?.dismissible
           title={strings.toc.title}
           variant="mobile"
         />
+        <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
         <article class="prose mx-auto max-w-[42rem]" dir={contentDir}>
           <slot />
         </article>
+        <PageFooterSlot headings={tocHeadings} page={page} route={page.route} />
         {
           formattedLastModified && (
             <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
@@ -320,7 +372,7 @@ const bannerScript = banner?.dismissible
             </p>
           )
         }
-        {feedback && <PageFeedback strings={strings.feedback} />}
+        {feedback && <FeedbackSlot strings={strings.feedback} />}
         <PaginationSlot next={next} prev={prev} strings={strings.page} />
       </main>
       <aside
@@ -344,6 +396,17 @@ const bannerScript = banner?.dismissible
         />
       </aside>
     </div>
+    <FooterSlot navigation={navigation} site={site} ui={strings} />
+    {
+      clientDataJson && (
+        <script
+          id="blume-client-data"
+          is:inline
+          set:html={clientDataJson}
+          type="application/json"
+        />
+      )
+    }
     <button
       aria-label="Close navigation"
       class="fixed inset-0 z-[30] hidden cursor-pointer border-0 bg-black/40 [:where([data-blume-nav-open])_&]:block lg:hidden"
@@ -358,6 +421,9 @@ const bannerScript = banner?.dismissible
       // Registers the <blume-toc> custom element: scrollspy for the table of
       // contents, highlighting the section currently in view as you scroll.
       import "./toc-element.ts";
+      // Dev-only: adds a friendly hint after a React island hydration mismatch.
+      // Tree-shaken out of production builds.
+      import "./hydration-hint.ts";
 
       const svg = (name: string) =>
         `<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${icons[name]}</svg>`;

package/src/components/layout/hydration-hint.ts

@@ -0,0 +1,30 @@
+// Dev-only: when React reports a hydration mismatch for an island, follow it
+// with a friendly Blume hint pointing at the islands guide. Guarded by
+// `import.meta.env.DEV`, so the whole block is tree-shaken out of production
+// builds (the module ships no runtime code there).
+
+const HINT =
+  "[blume] A hydration mismatch was detected in an island. Make sure props passed from `.astro`/MDX are serializable and the component renders the same output on the server and client (avoid `Date.now()`, `Math.random()`, `window` at render time). See https://useblume.dev/docs/content/islands";
+
+const PATTERNS = [
+  /hydrat/iu,
+  /did not match/iu,
+  /server-rendered html/iu,
+  /server rendered html/iu,
+];
+
+if (import.meta.env.DEV && typeof window !== "undefined") {
+  const original = console.error.bind(console);
+  let shown = false;
+  console.error = (...args: unknown[]) => {
+    original(...args);
+    if (shown) {
+      return;
+    }
+    const text = args.map(String).join(" ");
+    if (PATTERNS.some((pattern) => pattern.test(text))) {
+      shown = true;
+      original(HINT);
+    }
+  };
+}

package/src/components/layout/overrides.ts

@@ -4,10 +4,12 @@ import type { ComponentOverride } from "../../core/define-components.ts";
  * Resolve a layout-slot override to the component Astro should render, falling
  * back to Blume's built-in when no usable override is configured.
  *
- * An override may be a bare component reference or an `IslandDescriptor`
- * (`{ component, client }`); only the component is used here. String-path
- * overrides can't be imported at render time, so they fall back to the built-in
- * for now (imported components are the recommended, type-safe form).
+ * By the time values reach here, the generated `components.ts` has already turned
+ * path strings and hydrated (`client:*`) overrides into imported components /
+ * wrappers, so the runtime map holds real components. This handles the remaining
+ * cases: a bare component reference, an `IslandDescriptor` (`{ component }`,
+ * unwrapped to its component), and — as a safety net for overrides that couldn't
+ * be resolved at build time — a leftover string, which falls back to the built-in.
  */
 export const resolveSlot = <T>(
   override: ComponentOverride | undefined,

package/src/components/props.ts

@@ -0,0 +1,71 @@
+// Public prop types for Blume's built-in components, so users can type their
+// overrides and wrappers: `import type { CalloutProps } from "blume/components"`.
+//
+// Each type is derived straight from the component with Astro's `ComponentProps`,
+// so it can never drift from the real props. `typeof import(...)` keeps these
+// type-only (no runtime import); the file-level disable is because that syntax is
+// the only way to reference an `.astro` component's type without a value import.
+// oxlint-disable typescript/consistent-type-imports
+import type { ComponentProps } from "astro/types";
+
+export type AccordionProps = ComponentProps<
+  typeof import("./content/Accordion.astro").default
+>;
+export type AccordionItemProps = ComponentProps<
+  typeof import("./content/AccordionItem.astro").default
+>;
+export type BadgeProps = ComponentProps<
+  typeof import("./content/Badge.astro").default
+>;
+export type CalloutProps = ComponentProps<
+  typeof import("./content/Callout.astro").default
+>;
+export type CardProps = ComponentProps<
+  typeof import("./content/Card.astro").default
+>;
+export type CardGroupProps = ComponentProps<
+  typeof import("./content/CardGroup.astro").default
+>;
+export type CodeGroupProps = ComponentProps<
+  typeof import("./content/CodeGroup.astro").default
+>;
+export type ColumnProps = ComponentProps<
+  typeof import("./content/Column.astro").default
+>;
+export type ColumnsProps = ComponentProps<
+  typeof import("./content/Columns.astro").default
+>;
+export type ExpandableProps = ComponentProps<
+  typeof import("./content/Expandable.astro").default
+>;
+export type FrameProps = ComponentProps<
+  typeof import("./content/Frame.astro").default
+>;
+export type PanelProps = ComponentProps<
+  typeof import("./content/Panel.astro").default
+>;
+export type PromptProps = ComponentProps<
+  typeof import("./content/Prompt.astro").default
+>;
+export type StepProps = ComponentProps<
+  typeof import("./content/Step.astro").default
+>;
+export type StepsProps = ComponentProps<
+  typeof import("./content/Steps.astro").default
+>;
+export type TabProps = ComponentProps<
+  typeof import("./content/Tab.astro").default
+>;
+export type TabsProps = ComponentProps<
+  typeof import("./content/Tabs.astro").default
+>;
+export type TileProps = ComponentProps<
+  typeof import("./content/Tile.astro").default
+>;
+export type TooltipProps = ComponentProps<
+  typeof import("./content/Tooltip.astro").default
+>;
+export type YouTubeProps = ComponentProps<
+  typeof import("./content/YouTube.astro").default
+>;
+export type IconProps = ComponentProps<typeof import("./Icon.astro").default>;

package/src/core/assets.ts

@@ -0,0 +1,31 @@
+import { join } from "pathe";
+
+/** A static directory served at a URL prefix, in addition to `public/`. */
+export interface AssetMount {
+  /** Absolute filesystem path to the source directory (or file). */
+  dir: string;
+  /** URL path prefix the source is served at, e.g. `/images`. */
+  url: string;
+}
+
+/**
+ * Resolve `content.assets` entries (top-level dirs served at the site root,
+ * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
+ * runtime (dev middleware + build copy) and by link validation, so all three
+ * agree on where a `/images/foo.png` reference resolves on disk.
+ *
+ * Each entry is normalized to a leading-slash URL and joined to the project
+ * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
+ * escape the root or collide with the site's own routing prefix.
+ */
+export const resolveAssetMounts = (
+  root: string,
+  assets: string[]
+): AssetMount[] =>
+  assets.map((entry) => {
+    const rel = entry
+      .replace(/^[./]+/u, "")
+      .replaceAll(/\.\.\/?/gu, "")
+      .replace(/\/+$/u, "");
+    return { dir: join(root, rel), url: `/${rel}` };
+  });

package/src/core/bridge.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 
 import { join } from "pathe";
 
+import { assetSegments } from "../migrate/mintlify/assets.ts";
 import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
 import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
 import type { BlumeConfig } from "./schema.ts";
@@ -64,11 +65,20 @@ export const detectMintlifyBridge = async (
   const root_ = config.content?.root ?? ".";
   const exclude = config.content?.exclude ?? [];
 
+  // Mintlify serves assets from the project root; the bridge never moves files,
+  // so referenced root-level asset folders (e.g. `images/`) are served in place
+  // via `content.assets` instead. This is the read-only twin of the migrator's
+  // relocation — same referenced segments, just no `public/` move.
+  const assets = assetSegments(config).filter(
+    (segment) => segment !== "public" && existsSync(join(root, segment))
+  );
+
   return {
     configFile,
     raw: {
       ...config,
       content: {
+        assets,
         // Mirror the excludes onto `content.exclude` too: the generated Astro
         // `docs` collection globs `content.root` (here the project root) and
         // must skip node_modules/snippets just like the source does.