@dreamlake/dockit 0.2.13 → 0.2.15

package/dist/components/SearchPalette.js

@@ -1,9 +1,21 @@
 import { jsxs, Fragment, jsx } from "react/jsx-runtime";
+import { loadSearchPreview } from "../lib/search-preview.js";
 import { useState, useRef, useEffect } from "react";
 import { defaultResults, searchPages } from "../lib/pagefind-search.js";
 import { useMediaQuery } from "../lib/use-media-query.js";
 import { useSearchResize, SearchResizeHandles } from "./SearchResize.js";
 import { useHiddenToggle } from "../lib/use-hidden-toggle.js";
+import { Chip } from "./Chip.js";
+function SourceBadge({ label }) {
+  return /* @__PURE__ */ jsx(
+    Chip,
+    {
+      variant: "accent",
+      style: { fontSize: 8.5, padding: "0px 5px", letterSpacing: "0.06em", flexShrink: 0 },
+      children: label
+    }
+  );
+}
 const PAL_MAX_W = 860;
 const PAL_GUTTER = 24;
 const PAL_INSET = `max(${PAL_GUTTER}px, calc((100vw - ${PAL_MAX_W}px) / 2))`;
@@ -65,20 +77,13 @@ function SearchPalette({ open, onClose, query }) {
   const [pageHtml, setPageHtml] = useState("");
   const pageCacheRef = useRef(/* @__PURE__ */ new Map());
   const activePath = hits[active]?.path;
-  useEffect(() => {
-    if (!activePath || isSingleCol) {
-      setPageHtml("");
-      return;
-    }
-    const cached = pageCacheRef.current.get(activePath);
-    if (cached !== void 0) {
-      setPageHtml(cached);
-      return;
-    }
-    setPageHtml("");
-    let cancelled = false;
-    fetch(activePath).then((r) => r.ok ? r.text() : "").then((html) => {
-      if (cancelled) return;
+  useEffect(() => loadSearchPreview({
+    open,
+    path: activePath,
+    singleColumn: isSingleCol,
+    cache: pageCacheRef.current,
+    onPreview: setPageHtml,
+    extract: (html) => {
       const doc = new DOMParser().parseFromString(html, "text/html");
       const main = doc.querySelector("[data-pagefind-body]");
       main?.querySelectorAll("[data-pagefind-ignore], script, style").forEach((el) => el.remove());
@@ -88,16 +93,9 @@ function SearchPalette({ open, onClose, query }) {
         el.removeAttribute("style");
         el.removeAttribute("class");
       });
-      const content = main?.innerHTML ?? "";
-      pageCacheRef.current.set(activePath, content);
-      setPageHtml(content);
-    }).catch(() => {
-      if (!cancelled) setPageHtml("");
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [active, activePath, isSingleCol]);
+      return main?.innerHTML ?? "";
+    }
+  }), [open, activePath, isSingleCol]);
   useEffect(() => {
     if (!open) return;
     setActive(0);
@@ -341,6 +339,7 @@ function SearchPalette({ open, onClose, query }) {
                                 textOverflow: "ellipsis"
                               },
                               children: [
+                                hit.sourceLabel && /* @__PURE__ */ jsx("span", { style: { marginRight: 5 }, children: /* @__PURE__ */ jsx(SourceBadge, { label: hit.sourceLabel }) }),
                                 hit.section && /* @__PURE__ */ jsxs(
                                   "span",
                                   {
@@ -379,19 +378,23 @@ function SearchPalette({ open, onClose, query }) {
                             }
                           )
                         ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
-                          /* @__PURE__ */ jsx(
-                            "span",
-                            {
-                              className: "text-doc-template-ink",
-                              style: {
-                                fontWeight: 500,
-                                whiteSpace: "nowrap",
-                                overflow: "hidden",
-                                textOverflow: "ellipsis"
-                              },
-                              children: highlight(hit.title, query)
-                            }
-                          ),
+                          /* @__PURE__ */ jsxs("span", { className: "flex items-center", style: { gap: 6, minWidth: 0 }, children: [
+                            /* @__PURE__ */ jsx(
+                              "span",
+                              {
+                                className: "text-doc-template-ink",
+                                style: {
+                                  fontWeight: 500,
+                                  whiteSpace: "nowrap",
+                                  overflow: "hidden",
+                                  textOverflow: "ellipsis",
+                                  minWidth: 0
+                                },
+                                children: highlight(hit.title, query)
+                              }
+                            ),
+                            hit.sourceLabel && /* @__PURE__ */ jsx(SourceBadge, { label: hit.sourceLabel })
+                          ] }),
                           hit.section && /* @__PURE__ */ jsx(
                             "span",
                             {
@@ -497,7 +500,7 @@ function SearchPalette({ open, onClose, query }) {
                           letterSpacing: "0.05em",
                           marginBottom: 6
                         },
-                        children: previewHit.section || "—"
+                        children: previewHit.section || previewHit.sourceLabel || "—"
                       }
                     ),
                     /* @__PURE__ */ jsx(

package/dist/components/Sidebar.js

@@ -51,7 +51,7 @@ function Sidebar() {
     "aside",
     {
       "aria-label": "Sections",
-      className: "hidden md:flex sticky overflow-y-auto flex-col",
+      className: "doc-sidebar hidden md:flex sticky overflow-y-auto flex-col",
       style: { top: 40, height: "calc(100vh - 40px)", padding: "22px 12px 32px 18px", gap: 2 },
       children: groups.map((group) => {
         const soleSection = groups.length === 1;
@@ -65,7 +65,7 @@ function Sidebar() {
               className: "group sidebar-section",
               "data-folded": isFolded || void 0,
               children: [
-                /* @__PURE__ */ jsx("span", { children: group.label }),
+                /* @__PURE__ */ jsx("span", { title: group.label, children: group.label }),
                 /* @__PURE__ */ jsx(
                   "span",
                   {

package/dist/components/TabStrip.js

@@ -1,11 +1,14 @@
 import { jsxs, jsx } from "react/jsx-runtime";
 import { useMemo, useRef, useState, useLayoutEffect } from "react";
 import { usePageContext } from "vike-react/usePageContext";
-import { tabForUrl, TABS, urlInTab } from "../lib/tabs.js";
+import { tabForUrl, TABS, isExternalTab, urlInTab } from "../lib/tabs.js";
 import { pages } from "../lib/navigation.js";
 import { useHiddenToggle } from "../lib/use-hidden-toggle.js";
 const SPRING = "cubic-bezier(0.4, 0.7, 0.3, 1)";
 const SSR_BAR_BOTTOM = -13;
+function tabKey(tab) {
+  return isExternalTab(tab) ? `ext:${tab.href}` : tab.id;
+}
 function TabStrip() {
   const { urlPathname } = usePageContext();
   const activeTab = tabForUrl(urlPathname);
@@ -13,7 +16,7 @@ function TabStrip() {
   const visibleTabs = useMemo(() => {
     if (showHidden) return TABS;
     return TABS.filter(
-      (tab) => tab.id === activeTab || pages.some((p) => !p.hidden && urlInTab(p.path, tab.id))
+      (tab) => isExternalTab(tab) || tab.id === activeTab || pages.some((p) => !p.hidden && urlInTab(p.path, tab.id))
     );
   }, [showHidden, activeTab]);
   const containerRef = useRef(null);
@@ -75,19 +78,22 @@ function TabStrip() {
       onMouseLeave: () => setHovered(null),
       children: [
         visibleTabs.map((tab) => {
-          const isActive = tab.id === activeTab;
+          const key = tabKey(tab);
+          const external = isExternalTab(tab);
+          const isActive = !external && tab.id === activeTab;
           return /* @__PURE__ */ jsx(
             "li",
             {
               className: "flex items-stretch shrink-0",
-              onMouseEnter: () => setHovered(tab.id),
-              children: /* @__PURE__ */ jsx(
+              onMouseEnter: () => setHovered(key),
+              children: /* @__PURE__ */ jsxs(
                 "a",
                 {
                   ref: (el) => {
-                    linkRefs.current[tab.id] = el;
+                    linkRefs.current[key] = el;
                   },
-                  href: tab.landing,
+                  href: external ? tab.href : tab.landing,
+                  ...external ? { target: "_blank", rel: "noreferrer" } : {},
                   "aria-current": isActive ? "page" : void 0,
                   className: "flex items-center no-underline px-1.5 md:px-2.5",
                   style: {
@@ -97,15 +103,36 @@ function TabStrip() {
                     letterSpacing: "0.12em",
                     textTransform: "uppercase",
                     whiteSpace: "nowrap",
-                    color: isActive || hovered === tab.id ? "var(--color-doc-template-ink)" : "var(--color-doc-template-muted)",
+                    color: isActive || hovered === key ? "var(--color-doc-template-ink)" : "var(--color-doc-template-muted)",
                     cursor: "pointer",
                     transition: "color 0.18s ease"
                   },
-                  children: tab.label
+                  children: [
+                    tab.label,
+                    external && // ↗ affordance — drawn, not the glyph, so its weight and
+                    // optical size stay consistent across the mono font stack.
+                    /* @__PURE__ */ jsxs(
+                      "svg",
+                      {
+                        viewBox: "0 0 24 24",
+                        fill: "none",
+                        stroke: "currentColor",
+                        strokeWidth: "2.5",
+                        strokeLinecap: "round",
+                        strokeLinejoin: "round",
+                        "aria-hidden": true,
+                        style: { width: 9, height: 9, marginLeft: 4, opacity: 0.8, flexShrink: 0 },
+                        children: [
+                          /* @__PURE__ */ jsx("path", { d: "M7 17L17 7" }),
+                          /* @__PURE__ */ jsx("path", { d: "M8 7h9v9" })
+                        ]
+                      }
+                    )
+                  ]
                 }
               )
             },
-            tab.id
+            key
           );
         }),
         /* @__PURE__ */ jsx(

package/dist/components/Topbar.js

@@ -10,7 +10,7 @@ import { ThemeToggle } from "./ThemeToggle.js";
 import { VersionBadge } from "./VersionBadge.js";
 import { useMerge } from "../renderer/Layout.js";
 import { TabStrip } from "./TabStrip.js";
-import { TABS, tabForUrl } from "../lib/tabs.js";
+import { internalTabs, tabForUrl } from "../lib/tabs.js";
 function HiddenRevealChip() {
   const [show, setShow] = useHiddenToggle();
   if (!show) return null;
@@ -38,7 +38,7 @@ const SEARCH_INSET = `max(${SEARCH_GUTTER}px, calc((100vw - ${SEARCH_MAX_W}px) /
 function Topbar({ searchOpen, onOpenSearch, onCloseSearch, query, setQuery }) {
   const { urlPathname } = usePageContext();
   const current = findPage(urlPathname);
-  const activeTab = TABS.find((t) => t.id === tabForUrl(urlPathname));
+  const activeTab = internalTabs().find((t) => t.id === tabForUrl(urlPathname));
   const versionChips = activeTab?.versionChips ?? siteConfig.versionChips ?? [];
   const inputRef = useRef(null);
   const labelRef = useRef(null);
@@ -342,7 +342,9 @@ function Topbar({ searchOpen, onOpenSearch, onCloseSearch, query, setQuery }) {
                   label: chip.label,
                   version: chip.version,
                   collapsed: merged,
-                  dropdown: chip.dropdown
+                  dropdown: chip.dropdown,
+                  prefix: chip.prefix,
+                  manifestUrl: chip.manifestUrl
                 },
                 chip.label
               )),

package/dist/components/VersionBadge.d.ts

@@ -1,7 +1,7 @@
 export interface VersionBadgeProps {
     /** Left segment text (e.g. the package name). */
     label: string;
-    /** Build-time version shown in the right segment (may be overridden on
+    /** Build-time version shown in the right segment (with dropdown enabled, may be overridden on
      *  the client from the hostname / manifest — see below). */
     version: string;
     /** Collapse to width 0 (the Topbar drives this from its merged state).
@@ -10,6 +10,10 @@ export interface VersionBadgeProps {
     /** Turn the version segment into a popover listing the deploys from
      *  `/versions.json`. */
     dropdown?: boolean;
+    /** Text before versions; defaults to 'v'. Use '' for commit previews. */
+    prefix?: string;
+    /** Manifest path or absolute URL; defaults to '/versions.json'. */
+    manifestUrl?: string;
 }
 /**
  * Two-segment version chip: `[ label | v<version> ]`.
@@ -33,4 +37,4 @@ export interface VersionBadgeProps {
  * radius, hairline border. The two-segment (label | version) layout is
  * bespoke, so this component does not compose `Chip` internally.
  */
-export declare function VersionBadge({ label, version, collapsed, dropdown, }: VersionBadgeProps): import("react").JSX.Element;
+export declare function VersionBadge({ label, version, collapsed, dropdown, prefix, manifestUrl, }: VersionBadgeProps): import("react").JSX.Element;

package/dist/components/VersionBadge.js

@@ -1,46 +1,39 @@
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
 import { useState, useRef, useEffect } from "react";
 import { siteConfig } from "../site-config.js";
+import { badgeScope, manifestForScope, resolveBadgeVersion, loadVersionManifest } from "../lib/version-badge.js";
 const SPRING = "cubic-bezier(0.4, 0.7, 0.3, 1)";
 function VersionBadge({
   label,
   version,
   collapsed = false,
-  dropdown = false
+  dropdown = false,
+  prefix = "v",
+  manifestUrl = "/versions.json"
 }) {
   const transition = `opacity 0.4s ease, transform 0.4s ${SPRING}, width 0.4s ${SPRING}, margin 0.4s ${SPRING}, padding 0.4s ${SPRING}`;
   const [open, setOpen] = useState(false);
-  const [manifest, setManifest] = useState(null);
-  const [displayVersion, setDisplayVersion] = useState(version);
+  const [manifestState, setManifestState] = useState(null);
+  const [hostname, setHostname] = useState("");
+  const scope = badgeScope(label, version, dropdown, manifestUrl);
+  const manifest = manifestForScope(manifestState, scope);
+  const displayVersion = resolveBadgeVersion(version, dropdown, hostname, manifest, manifestUrl);
   const wrapperRef = useRef(null);
   useEffect(() => {
+    setHostname(window.location.hostname);
+  }, []);
+  useEffect(() => {
+    setOpen(false);
+    setManifestState(null);
     if (!dropdown) return;
     let cancelled = false;
-    const origin = (siteConfig.url || "").replace(/\/+$/, "");
-    const isLocal = typeof window !== "undefined" && /^(localhost|127\.|0\.0\.0\.0)/.test(window.location.hostname);
-    const sameOrigin = () => fetch("/versions.json").then((r) => r.ok ? r.json() : null);
-    const fromOrigin = () => fetch(`${origin}/versions.json`).then((r) => r.ok ? r.json() : Promise.reject(new Error(String(r.status))));
-    const load = !origin ? sameOrigin() : isLocal ? sameOrigin().then((m) => m ?? fromOrigin().catch(() => null)) : fromOrigin().catch(sameOrigin);
-    load.then((m) => {
-      if (!cancelled && m) setManifest(m);
-    }).catch(() => {
+    loadVersionManifest(manifestUrl, siteConfig.url || "", window.location.hostname).then((manifest2) => {
+      if (!cancelled && manifest2) setManifestState({ scope, manifest: manifest2 });
     });
     return () => {
       cancelled = true;
     };
-  }, [dropdown]);
-  useEffect(() => {
-    if (typeof window === "undefined") return;
-    const host = window.location.hostname;
-    const m = host.match(/^v(\d+(?:-\d+)+(?:[a-z]+\d+)?)\./i);
-    if (m) {
-      setDisplayVersion(m[1].replace(/-/g, "."));
-    } else if (host.startsWith("stable.") && manifest?.stable) {
-      setDisplayVersion(manifest.stable);
-    } else if (manifest?.current) {
-      setDisplayVersion(manifest.current);
-    }
-  }, [manifest]);
+  }, [scope, dropdown, manifestUrl]);
   useEffect(() => {
     if (!open) return;
     function onDown(e) {
@@ -144,11 +137,11 @@ function VersionBadge({
             },
             "aria-haspopup": "listbox",
             "aria-expanded": open,
-            title: `Switch ${label} version (current v${displayVersion})`,
+            title: `Switch ${label} version (current ${prefix}${displayVersion})`,
             className: "text-doc-template-ink hover:bg-doc-template-search",
             style: versionSegStyle,
             children: [
-              "v",
+              prefix,
               displayVersion,
               chevron
             ]
@@ -159,7 +152,7 @@ function VersionBadge({
             className: "inline-flex items-center text-doc-template-ink",
             style: versionSegStyle,
             children: [
-              "v",
+              prefix,
               displayVersion
             ]
           }
@@ -250,11 +243,11 @@ function VersionBadge({
                       children: [
                         name,
                         name === "stable" && manifest.stable && /* @__PURE__ */ jsxs("span", { style: { opacity: 0.5, marginLeft: 6 }, children: [
-                          "v",
+                          prefix,
                           manifest.stable
                         ] }),
                         name === "latest" && manifest.current && /* @__PURE__ */ jsxs("span", { style: { opacity: 0.5, marginLeft: 6 }, children: [
-                          "v",
+                          prefix,
                           manifest.current
                         ] })
                       ]
@@ -293,7 +286,7 @@ function VersionBadge({
                         },
                         children: [
                           /* @__PURE__ */ jsxs("span", { children: [
-                            "v",
+                            prefix,
                             v.version,
                             isCurrent && /* @__PURE__ */ jsx("span", { style: { opacity: 0.55, marginLeft: 6 }, children: "current" })
                           ] }),

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { SiteConfig as _SiteConfig } from './site-config';
+import { SiteConfig as _SiteConfig, SearchConfig as _SearchConfig } from './site-config';
 import { PageFrontmatter as _PageFrontmatter } from './lib/navigation';
-import { TabDef as _TabDef } from './lib/tabs';
+import { TabEntry as _TabEntry } from './lib/tabs';
 /**
  * @dreamlake/dockit — the DreamLake documentation shell as a library.
  *
@@ -11,17 +11,17 @@ import { TabDef as _TabDef } from './lib/tabs';
  *
  *   initDocs({
  *     site: { brand: 'DreamLake', subtitle: 'Dockit', … },
- *     pages: import.meta.glob('./pages/** /+Page.mdx', { eager: true }),
- *     rawPages: import.meta.glob('./pages/** /+Page.mdx', { eager: true, query: '?raw', import: 'default' }),
+ *     pageMetadata: import.meta.glob('./pages/** /+Page.mdx', { eager: true, query: '?frontmatter', import: 'default' }),
+ *     rawPages: import.meta.env.DEV ? import.meta.glob('./pages/** /+Page.mdx', { eager: true, query: '?raw', import: 'default' }) : undefined,
  *     sectionOrder: ['Getting started', 'Reference'],
  *     tabs: [{ id: 'overview', label: 'Get Started', numeral: 'I', landing: '/', urlPrefix: '/get-started' }],
  *   })
  */
-export { siteConfig, defineSiteConfig, type SiteConfig, type VersionChip, } from './site-config';
+export { siteConfig, defineSiteConfig, type SiteConfig, type VersionChip, type SearchConfig, type MergeIndexDef, } from './site-config';
 export { pages, groupedPages, groupedVisiblePages, initNavigation, getAdjacentPages, normalizePath, findPage, type PageMeta, type PageFrontmatter, type PageModule, type NavGroup, } from './lib/navigation';
 export { searchIndex, rawMarkdown, initSearchIndex, search, type SearchEntry, type SearchHit, } from './lib/search-index';
 export { searchPages, defaultResults, type SearchResult, type SubResult, } from './lib/pagefind-search';
-export { TABS, initTabs, tabForUrl, urlInTab, type TabDef } from './lib/tabs';
+export { TABS, initTabs, tabForUrl, urlInTab, isExternalTab, internalTabs, type TabDef, type ExternalTabDef, type TabEntry, } from './lib/tabs';
 export { useHiddenToggle } from './lib/use-hidden-toggle';
 export { useLineNumbers } from './lib/use-line-numbers';
 export { useLocalStorage, DOC_PREFIX, docKey } from './lib/use-local-storage';
@@ -47,17 +47,28 @@ export { Layout, useMerge } from './renderer/Layout';
 export interface InitDocsOptions {
     /** Site branding, URLs, version chips, git hash. */
     site: Partial<_SiteConfig>;
-    /** Eager glob of every `+Page.mdx` module (frontmatter drives nav). */
-    pages: Record<string, {
+    /** Metadata-only glob: `{ eager: true, query: '?frontmatter', import: 'default' }`.
+     *  Keeps compiled page bodies out of the shared startup bundle.
+     *  Use this or `pages`, not both. */
+    pageMetadata?: Record<string, _PageFrontmatter>;
+    /** Backward-compatible module map. Prefer `pageMetadata` for large sites. */
+    pages?: Record<string, {
         frontmatter?: _PageFrontmatter;
     }>;
-    /** Eager `?raw` glob of the same pages — feeds the dev search index and
-     *  the palette's markdown preview. Optional but recommended. */
+    /** Raw sources for fallback/dev search. Usually pass a `?raw` glob only
+     *  when `import.meta.env.DEV`; production Pagefind searches built HTML.
+     *  Omitting this retains title/description search if Pagefind is unavailable. */
     rawPages?: Record<string, string>;
     /** Authored sidebar section order; unknown sections fall to the end. */
     sectionOrder?: string[];
-    /** Topbar tab lenses. Omit (or pass []) for a tabless site. */
-    tabs?: _TabDef[];
+    /** Topbar tab lenses, plus optional external-link entries
+     *  (`{ label, href, external: true }`). Omit (or pass []) for a
+     *  tabless site. */
+    tabs?: _TabEntry[];
+    /** Search-layer options — e.g. `mergeIndexes` to merge remote Pagefind
+     *  indexes into the palette. Equivalent to `site.search`; this
+     *  top-level key wins when both are given. */
+    search?: _SearchConfig;
 }
 /** One call wires the whole shell: site config, navigation, search, tabs. */
 export declare function initDocs(opts: InitDocsOptions): void;

package/dist/index.js

@@ -6,7 +6,7 @@ import { initSearchIndex } from "./lib/search-index.js";
 import { rawMarkdown, search, searchIndex } from "./lib/search-index.js";
 import { defaultResults, searchPages } from "./lib/pagefind-search.js";
 import { initTabs } from "./lib/tabs.js";
-import { TABS, tabForUrl, urlInTab } from "./lib/tabs.js";
+import { TABS, internalTabs, isExternalTab, tabForUrl, urlInTab } from "./lib/tabs.js";
 import { useHiddenToggle } from "./lib/use-hidden-toggle.js";
 import { useLineNumbers } from "./lib/use-line-numbers.js";
 import { DOC_PREFIX, docKey, useLocalStorage } from "./lib/use-local-storage.js";
@@ -30,8 +30,13 @@ import { Topbar } from "./components/Topbar.js";
 import { VersionBadge } from "./components/VersionBadge.js";
 import { Layout, useMerge } from "./renderer/Layout.js";
 function initDocs(opts) {
-  defineSiteConfig(opts.site);
-  initNavigation(opts.pages, opts.sectionOrder ?? []);
+  if (opts.pages && opts.pageMetadata) {
+    throw new Error("initDocs: provide pageMetadata or pages, not both");
+  }
+  const modules = opts.pageMetadata ? Object.fromEntries(Object.entries(opts.pageMetadata).map(([file, frontmatter]) => [file, { frontmatter }])) : opts.pages;
+  if (!modules) throw new Error("initDocs: pageMetadata or pages is required");
+  defineSiteConfig(opts.search ? { ...opts.site, search: opts.search } : opts.site);
+  initNavigation(modules, opts.sectionOrder ?? []);
   initSearchIndex(opts.rawPages ?? {});
   initTabs(opts.tabs ?? []);
 }
@@ -67,6 +72,8 @@ export {
   initNavigation,
   initSearchIndex,
   initTabs,
+  internalTabs,
+  isExternalTab,
   mdxComponents,
   normalizePath,
   pages,

package/dist/lib/mdx-frontmatter-loader.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from 'vite';
+/** Load only YAML metadata, without importing or compiling the MDX body. */
+export declare function mdxFrontmatterLoader(): Plugin;

package/dist/lib/mdx-frontmatter-loader.js

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+function mdxFrontmatterLoader() {
+  const prefix = "\0dockit-frontmatter:";
+  return {
+    name: "dockit-frontmatter",
+    enforce: "pre",
+    async resolveId(id, importer) {
+      if (!id.endsWith(".mdx?frontmatter")) return null;
+      const resolved = await this.resolve(id.slice(0, -"?frontmatter".length), importer, { skipSelf: true });
+      return resolved ? prefix + resolved.id : null;
+    },
+    async load(id) {
+      if (!id.startsWith(prefix)) return null;
+      const file = id.slice(prefix.length);
+      this.addWatchFile(file);
+      const source = await readFile(file, "utf8");
+      const match = source.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)(?:\r?\n|$)/);
+      const metadata = match ? parse(match[1]) ?? {} : {};
+      if (typeof metadata !== "object" || Array.isArray(metadata)) {
+        throw new Error(`Expected a YAML frontmatter mapping in ${file}`);
+      }
+      return `export default ${JSON.stringify(metadata)};`;
+    }
+  };
+}
+export {
+  mdxFrontmatterLoader
+};

package/dist/lib/pagefind-search.d.ts

@@ -13,6 +13,10 @@ export interface SearchResult {
     excerptHtml: string;
     subResults: SubResult[];
     score: number;
+    /** Label of the merged remote index this result came from (see
+     *  `search.mergeIndexes` in the site config). Unset for local results.
+     *  Remote results carry absolute `path`/sub-result URLs on that site. */
+    sourceLabel?: string;
 }
 /** Default (empty-query) results — computed lazily because the
  *  `searchIndex` singleton is only populated once the consuming site's

package/dist/lib/pagefind-search.js

@@ -1,7 +1,9 @@
 import { searchIndex, search } from "./search-index.js";
 import { pages } from "./navigation.js";
+import { siteConfig } from "../site-config.js";
 let pagefind = null;
 let initPromise = null;
+const mergedOriginLabels = /* @__PURE__ */ new Map();
 async function getPagefind() {
   if (pagefind) return pagefind;
   if (initPromise) return initPromise;
@@ -13,6 +15,14 @@ async function getPagefind() {
         path
       );
       await pf.options({ excerptLength: 200 });
+      for (const idx of siteConfig.search?.mergeIndexes ?? []) {
+        try {
+          const origin = new URL(idx.url).origin;
+          await pf.mergeIndex(idx.url, { baseUrl: `${origin}/` });
+          mergedOriginLabels.set(origin, idx.label);
+        } catch {
+        }
+      }
       pagefind = pf;
       return pf;
     } catch {
@@ -21,6 +31,14 @@ async function getPagefind() {
   })();
   return initPromise;
 }
+function sourceLabelFor(url) {
+  if (!/^https?:\/\//.test(url)) return void 0;
+  try {
+    return mergedOriginLabels.get(new URL(url).origin);
+  } catch {
+    return void 0;
+  }
+}
 const STOP_WORDS = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -189,7 +207,8 @@ async function searchPages(query, limit = 30, showHidden = false) {
       snippet: r.excerpt?.replace(/<[^>]+>/g, "").trim() ?? "",
       excerptHtml: r.excerpt ?? "",
       subResults,
-      score
+      score,
+      sourceLabel: sourceLabelFor(path)
     };
   });
   mapped.sort((a, b) => b.score - a.score);

package/dist/lib/search-preview.d.ts

@@ -0,0 +1,10 @@
+/** Start one visible search preview; return the React effect cleanup. */
+export declare function loadSearchPreview({ open, path, singleColumn, cache, onPreview, extract, request, }: {
+    open: boolean;
+    path?: string;
+    singleColumn: boolean;
+    cache: Map<string, string>;
+    onPreview: (html: string) => void;
+    extract: (html: string) => string;
+    request?: typeof fetch;
+}): (() => void) | undefined;

package/dist/lib/search-preview.js

@@ -0,0 +1,33 @@
+function loadSearchPreview({
+  open,
+  path,
+  singleColumn,
+  cache,
+  onPreview,
+  extract,
+  request = fetch
+}) {
+  if (!open || !path || singleColumn || /^https?:\/\//.test(path)) {
+    onPreview("");
+    return;
+  }
+  const cached = cache.get(path);
+  if (cached !== void 0) {
+    onPreview(cached);
+    return;
+  }
+  onPreview("");
+  const controller = new AbortController();
+  request(path, { signal: controller.signal }).then((response) => response.ok ? response.text() : "").then((html) => {
+    if (controller.signal.aborted) return;
+    const content = extract(html);
+    cache.set(path, content);
+    onPreview(content);
+  }).catch(() => {
+    if (!controller.signal.aborted) onPreview("");
+  });
+  return () => controller.abort();
+}
+export {
+  loadSearchPreview
+};

package/dist/lib/tabs.d.ts

@@ -13,11 +13,26 @@ export interface TabDef {
      *  chips; set to `[]` to show none on this tab. */
     versionChips?: VersionChip[];
 }
+/** An external-link entry in the tab strip — renders alongside the tab
+ *  lenses with an ↗ affordance, but is a plain link out to another site
+ *  (e.g. a sibling docs property). It scopes no pages, is never "active",
+ *  and does not participate in `tabForUrl`. */
+export interface ExternalTabDef {
+    label: string;
+    /** Absolute URL the tab links out to (e.g. "https://cli.dreamlake.ai"). */
+    href: string;
+    external: true;
+}
+export type TabEntry = TabDef | ExternalTabDef;
+export declare function isExternalTab(tab: TabEntry): tab is ExternalTabDef;
 /** Module-level singleton, populated by `initTabs()`. Mutated in place —
  *  never reassigned — so importing components keep a live reference. */
-export declare const TABS: TabDef[];
+export declare const TABS: TabEntry[];
 /** Populate the tab singleton from the consuming site. */
-export declare function initTabs(tabs: TabDef[]): void;
+export declare function initTabs(tabs: TabEntry[]): void;
+/** The page-scoping (non-external) tabs, in order. All URL→tab logic
+ *  runs over this list — external entries are chrome, not lenses. */
+export declare function internalTabs(): TabDef[];
 /** Derive active tab from a page URL. The site root `/` resolves to the
  *  first tab. Unknown prefixes also fall back to the first tab so orphan
  *  pages never leave the sidebar empty. With no tabs registered, always

package/dist/lib/tabs.js

@@ -1,8 +1,14 @@
+function isExternalTab(tab) {
+  return tab.external === true;
+}
 const TABS = [];
 function initTabs(tabs) {
   TABS.length = 0;
   TABS.push(...tabs);
 }
+function internalTabs() {
+  return TABS.filter((t) => !isExternalTab(t));
+}
 function firstSegment(url) {
   const path = url.split(/[?#]/)[0];
   const trimmed = path.replace(/^\/+/, "").replace(/\/+$/, "");
@@ -10,14 +16,15 @@ function firstSegment(url) {
   return trimmed.split("/")[0];
 }
 function tabForUrl(url) {
-  if (TABS.length === 0) return "";
-  if (!url) return TABS[0].id;
+  const tabs = internalTabs();
+  if (tabs.length === 0) return "";
+  if (!url) return tabs[0].id;
   const seg = firstSegment(url);
-  if (!seg) return TABS[0].id;
-  for (const tab of TABS) {
+  if (!seg) return tabs[0].id;
+  for (const tab of tabs) {
     if (tab.urlPrefix === `/${seg}`) return tab.id;
   }
-  return TABS[0].id;
+  return tabs[0].id;
 }
 function urlInTab(url, tabId) {
   return tabForUrl(url) === tabId;
@@ -25,6 +32,8 @@ function urlInTab(url, tabId) {
 export {
   TABS,
   initTabs,
+  internalTabs,
+  isExternalTab,
   tabForUrl,
   urlInTab
 };

package/dist/lib/version-badge.d.ts

@@ -0,0 +1,22 @@
+/** State and resolution helpers shared by independently scoped version badges. */
+export interface VersionEntry {
+    version: string;
+    url: string;
+    date?: string;
+}
+export interface VersionManifest {
+    current?: string;
+    stable?: string;
+    aliases?: Record<string, string>;
+    versions?: VersionEntry[];
+}
+export interface BadgeManifestState {
+    scope: string;
+    manifest: VersionManifest;
+}
+export declare function badgeScope(label: string, version: string, dropdown: boolean, manifestUrl: string): string;
+/** Never render a previous tab's manifest, even before effects have run. */
+export declare function manifestForScope(state: BadgeManifestState | null, scope: string): VersionManifest | null;
+export declare function resolveBadgeVersion(version: string, dropdown: boolean, hostname: string, manifest: VersionManifest | null, manifestUrl?: string): string;
+/** Production first, with a same-origin fallback; local development reverses it. */
+export declare function loadVersionManifest(manifestUrl: string, origin: string, hostname: string, request?: typeof fetch): Promise<VersionManifest | null>;

package/dist/lib/version-badge.js

@@ -0,0 +1,44 @@
+function badgeScope(label, version, dropdown, manifestUrl) {
+  return JSON.stringify([label, version, dropdown, manifestUrl]);
+}
+function manifestForScope(state, scope) {
+  return state?.scope === scope ? state.manifest : null;
+}
+function resolveBadgeVersion(version, dropdown, hostname, manifest, manifestUrl = "/versions.json") {
+  if (!dropdown) return version;
+  const match = hostname.match(/^v(\d+(?:-\d+)+(?:[a-z]+\d+)?)\./i);
+  if (match) {
+    const fromHost = match[1].replace(/-/g, ".");
+    if (manifestUrl === "/versions.json" || manifest?.versions?.some((entry) => entry.version === fromHost)) {
+      return fromHost;
+    }
+  }
+  if (hostname.startsWith("stable.") && manifest?.stable) return manifest.stable;
+  return manifest?.current || version;
+}
+async function loadVersionManifest(manifestUrl, origin, hostname, request = fetch) {
+  const read = async (url) => {
+    try {
+      const response = await request(url);
+      return response.ok ? await response.json() : null;
+    } catch {
+      return null;
+    }
+  };
+  if (/^(?:https?:)?\/\//.test(manifestUrl)) return read(manifestUrl);
+  const localUrl = `/${manifestUrl.replace(/^\/+/, "")}`;
+  const productionUrl = origin ? `${origin.replace(/\/+$/, "")}${localUrl}` : localUrl;
+  const local = /^(localhost|127\.|0\.0\.0\.0)/.test(hostname);
+  const urls = [...new Set(local ? [localUrl, productionUrl] : [productionUrl, localUrl])];
+  for (const url of urls) {
+    const manifest = await read(url);
+    if (manifest) return manifest;
+  }
+  return null;
+}
+export {
+  badgeScope,
+  loadVersionManifest,
+  manifestForScope,
+  resolveBadgeVersion
+};

package/dist/renderer/Layout.js

@@ -138,7 +138,7 @@ function Layout({ children }) {
     /* @__PURE__ */ jsxs(
       "div",
       {
-        className: isFullscreen ? "grid items-start mx-auto grid-cols-[minmax(0,1fr)] md:grid-cols-[240px_minmax(0,1fr)]" : "grid items-start mx-auto min-h-screen grid-cols-[minmax(0,1fr)] md:grid-cols-[240px_minmax(0,1fr)] lg:grid-cols-[240px_minmax(0,1fr)_240px]",
+        className: isFullscreen ? "grid items-start mx-auto grid-cols-[minmax(0,1fr)] md:grid-cols-[var(--doc-sidebar-width,280px)_minmax(0,1fr)]" : "grid items-start mx-auto min-h-screen grid-cols-[minmax(0,1fr)] md:grid-cols-[var(--doc-sidebar-width,280px)_minmax(0,1fr)] lg:grid-cols-[var(--doc-sidebar-width,280px)_minmax(0,1fr)_var(--doc-toc-width,280px)]",
         style: isFullscreen ? { height: "calc(100vh - 40px)" } : { maxWidth: 1320 },
         children: [
           /* @__PURE__ */ jsx(Sidebar, {}),

package/dist/renderer/onRenderClient.js

@@ -8,7 +8,7 @@ async function onRenderClient(pageContext) {
   const container = document.getElementById("root");
   const tree = /* @__PURE__ */ jsx(PageContextProvider, { pageContext, children: /* @__PURE__ */ jsx(Layout, { children: /* @__PURE__ */ jsx(Page, { ...pageProps }) }) });
   if (!root) {
-    if (container.innerHTML !== "") {
+    if (pageContext.isHydration && container.innerHTML !== "") {
       root = ReactDOM.hydrateRoot(container, tree);
     } else {
       root = ReactDOM.createRoot(container);

package/dist/site-config.d.ts

@@ -16,6 +16,28 @@ export interface VersionChip {
     label: string;
     version: string;
     dropdown?: boolean;
+    /** Version prefix; defaults to 'v'. Use '' for commit previews. */
+    prefix?: string;
+    /** Product-specific manifest path or URL; defaults to '/versions.json'. */
+    manifestUrl?: string;
+}
+/** One remote Pagefind index merged into the site's own search via
+ *  `pagefind.mergeIndex()` — Pagefind's first-class multisite API. The
+ *  remote site must serve its `/pagefind/` bundle with CORS
+ *  (`Access-Control-Allow-Origin`) and a compatible index format (same
+ *  Pagefind 1.x major). An index that fails to load degrades silently to
+ *  local-only search. */
+export interface MergeIndexDef {
+    /** Absolute URL of the remote bundle directory, e.g.
+     *  "https://cli.dreamlake.ai/pagefind/". */
+    url: string;
+    /** Badge label shown on results from this index (e.g. "CLI"). */
+    label: string;
+}
+/** Search-layer options (runtime Pagefind behavior). */
+export interface SearchConfig {
+    /** Remote Pagefind indexes to merge into the palette's results. */
+    mergeIndexes?: MergeIndexDef[];
 }
 export interface SiteConfig {
     /** Brand name in the top-left of the shell (e.g. "DreamLake"). */
@@ -72,6 +94,10 @@ export interface SiteConfig {
      *  — http(s), protocol-relative, or absolute-path; anything else is
      *  silently dropped. */
     headScripts?: string[];
+    /** Runtime search options — e.g. remote Pagefind indexes to merge into
+     *  the palette (`search.mergeIndexes`). Also settable via the top-level
+     *  `search` key of `initDocs()`. */
+    search?: SearchConfig;
     /** Search-engine visibility. DEFAULT FALSE per org policy: every page
      *  gets `<meta name="robots" content="noindex, nofollow">` unless a site
      *  explicitly opts in with `indexable: true`. Page-level `noindex`

package/dist/styles.css

@@ -308,3 +308,10 @@
   from { opacity: 0; transform: scale(0.6) rotate(-90deg); }
   to   { opacity: 1; transform: scale(1)   rotate(0deg); }
 }
+
+/* Stable, narrow scrollbar space keeps section labels from reflowing on overflow. */
+.doc-sidebar { min-width: 0; scrollbar-width: thin; scrollbar-gutter: stable; }
+.doc-sidebar::-webkit-scrollbar { width: 6px; }
+.doc-sidebar::-webkit-scrollbar-thumb { background: var(--color-doc-template-faint-strong); border-radius: 3px; }
+.doc-sidebar .sidebar-section > span:first-child { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.doc-sidebar .sidebar-section > span:last-child { flex-shrink: 0; white-space: nowrap; }

package/dist/vike.d.ts

@@ -7,6 +7,7 @@
 declare const _default: {
     passToClient: string[];
     clientRouting: boolean;
+    hydrationCanBeAborted: boolean;
     prerender: boolean;
 };
 export default _default;

package/dist/vike.js

@@ -1,6 +1,8 @@
 const vike = {
   passToClient: ["pageProps", "urlPathname"],
   clientRouting: true,
+  // React can supersede hydration when a reader follows a link immediately.
+  hydrationCanBeAborted: true,
   prerender: true
 };
 export {

package/dist/vite.js

@@ -1,3 +1,4 @@
+import { mdxFrontmatterLoader } from "./lib/mdx-frontmatter-loader.js";
 import { readFile } from "node:fs/promises";
 import react from "@vitejs/plugin-react";
 import vike from "vike/plugin";
@@ -31,6 +32,7 @@ function dockit() {
   return [
     tailwindcss(),
     mdxRawLoader(),
+    mdxFrontmatterLoader(),
     {
       enforce: "pre",
       ...mdx({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamlake/dockit",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "The DreamLake documentation shell — Vike + React + Tailwind v4 + MDX docs framework with sidebar, TOC, search, and theming",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,8 @@
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
     "remark-mdx-frontmatter": "^5.2.0",
-    "shiki": "^1.24.0"
+    "shiki": "^1.24.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@mdx-js/react": "^3.1.0",
@@ -78,6 +79,7 @@
   },
   "scripts": {
     "build": "vite build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs"
   }
 }