@takazudo/zudo-doc 5.5.2 → 5.6.0

package/dist/search-widget-script/index.js

@@ -1,446 +1,4 @@
-import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
-import { prepareLc, scoreEntry } from "./scoring.js";
-const SEARCH_WIDGET_SCRIPT = (
-  /* javascript */
-  `(function () {
-  if (customElements.get("site-search")) return; // guard double-registration
-
-  var PAGE_SIZE = 10;
-
-  // Allowlist-based href sanitizer: only relative paths and http(s) URLs are
-  // permitted. Anything else (e.g. javascript:, data:) falls back to "#" so a
-  // malicious entry in search-index.json cannot turn a result link into a
-  // script-injection vector.
-  function safeHref(url) {
-    if (!url) return "#";
-    var s = String(url);
-    if (s.startsWith("/") || s.startsWith("http://") || s.startsWith("https://")) {
-      return s;
-    }
-    return "#";
-  }
-
-  function escapeHtml(text) {
-    return String(text)
-      .replace(/&/g, "&")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;")
-      .replace(/'/g, "&#39;");
-  }
-
-  function escapeRegExp(text) {
-    return text.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&");
-  }
-
-  function parseTerms(query) {
-    return query.trim().split(/\\s+/).filter(Boolean);
-  }
-
-  // scoreEntry / prepareLc: embedded verbatim (via Function.prototype.toString())
-  // from the real, unit-tested implementation in ./scoring.ts \u2014 see the module
-  // header comment there and search-widget-script/__tests__/scoring.test.ts.
-  // This keeps the shipped inline script and the tested source identical by
-  // construction instead of relying on a hand-copied mirror staying in sync.
-  ${prepareLc.toString()}
-
-  ${scoreEntry.toString()}
-
-  function highlightTerms(text, terms) {
-    if (!terms.length) return escapeHtml(text);
-    var escaped = terms.map(function(t) { return escapeRegExp(t); });
-    var pattern = new RegExp("(" + escaped.join("|") + ")", "gi");
-    return text.split(pattern).map(function(seg, i) {
-      return i % 2 === 1
-        ? "<mark>" + escapeHtml(seg) + "</mark>"
-        : escapeHtml(seg);
-    }).join("");
-  }
-
-  function truncate(text, query, max) {
-    max = max || 200;
-    if (text.length <= max) return text;
-    var terms = parseTerms(query);
-    var lower = text.toLowerCase();
-    var best = -1;
-    for (var i = 0; i < terms.length; i++) {
-      var idx = lower.indexOf(terms[i].toLowerCase());
-      if (idx !== -1 && (best === -1 || idx < best)) best = idx;
-    }
-    if (best === -1) return text.slice(0, max) + "\\u2026";
-    var half = Math.floor(max / 2);
-    var start = Math.max(0, best - half);
-    var end = start + max;
-    if (end > text.length) { end = text.length; start = Math.max(0, end - max); }
-    var result = text.slice(start, end);
-    if (start > 0) result = "\\u2026" + result;
-    if (end < text.length) result += "\\u2026";
-    return result;
-  }
-
-  customElements.define("site-search", class SiteSearch extends HTMLElement {
-    constructor() {
-      super();
-      this._dialog = null;
-      this._openBtn = null;
-      this._closeBtn = null;
-      this._input = null;
-      this._results = null;
-      this._countWide = null;
-      this._countNarrow = null;
-      this._entries = null;
-      this._loading = false;
-      this._indexUnavailable = false;
-      this._debounce = null;
-      this._currentQuery = "";
-      this._allResults = [];
-      this._shownCount = 0;
-      this._shortcut = "";
-      this._resultCountTemplate = "";
-      // Locale-aware status strings (threaded from the SSR component via
-      // data-* attributes, same mechanism as _resultCountTemplate). English
-      // literals below in connectedCallback are fallbacks only.
-      this._searchUnavailable = "";
-      this._loadingIndex = "";
-      this._noResults = "";
-      this._keydownHandler = null;
-      // Delegated click handler on the results container: closing the dialog
-      // when a result link is activated (epic #2148). Held so disconnectedCallback
-      // can detach it on body swap.
-      this._resultsClickHandler = null;
-      this._observer = null;
-      this._sentinel = null;
-      this._isLoadingBatch = false;
-      // Snapshot of the initial results-area HTML (includes SSR placeholder).
-      // Captured in connectedCallback so we can restore it on input-clear
-      // without re-querying the DOM (the placeholder node is replaced once
-      // search results are rendered).
-      this._placeholderHtml = "";
-      // Held so we can remove the document-level after-navigate listener
-      // in disconnectedCallback. zudolab/zudo-doc#1523 \u2014 under Strategy B
-      // SPA navigation a non-persisted <site-search> element would leak
-      // one document listener per nav without this hook.
-      this._afterNavHandler = null;
-    }
-
-    connectedCallback() {
-      this._dialog = this.querySelector("[data-search-dialog]");
-      this._openBtn = this.querySelector("[data-open-search]");
-      this._closeBtn = this.querySelector("[data-close-search]");
-      this._input = this.querySelector("[data-search-input]");
-      this._results = this.querySelector("[data-search-results]");
-      this._countWide = this.querySelector("[data-search-count]");
-      this._countNarrow = this.querySelector("[data-search-count-narrow]");
-      this._resultCountTemplate = this.dataset.resultCountTemplate || "{count} results";
-      this._searchUnavailable = this.dataset.searchUnavailable || "Search unavailable";
-      this._loadingIndex = this.dataset.loadingIndex || "Loading search index\\u2026";
-      this._noResults = this.dataset.noResults || "No results found.";
-      // Snapshot the placeholder HTML before any search renders overwrite it.
-      this._placeholderHtml = this._results ? this._results.innerHTML : "";
-
-      // Platform keyboard-shortcut label \u2014 injected into [data-kbd-shortcut]
-      var nav = navigator;
-      var isMac = /Mac|iPhone|iPad|iPod/.test(
-        (nav.userAgentData && nav.userAgentData.platform) || nav.userAgent
-      );
-      this._shortcut = isMac ? "\\u2318K" : "Ctrl+K";
-      var kbdEl = this.querySelector("[data-kbd-shortcut]");
-      if (kbdEl) kbdEl.textContent = this._shortcut;
-
-      // Wire open/close handlers
-      var self = this;
-      if (this._openBtn) {
-        this._openBtn.addEventListener("click", function() { self.openDialog(); });
-      }
-      if (this._closeBtn) {
-        this._closeBtn.addEventListener("click", function() { self.closeDialog(); });
-      }
-      if (this._dialog) {
-        this._dialog.addEventListener("close", function() {
-          document.documentElement.style.overflow = "";
-        });
-        this._dialog.addEventListener("click", function(e) {
-          if (e.target === self._dialog) self.closeDialog();
-        });
-      }
-      if (this._input) {
-        this._input.addEventListener("input", function() { self.handleInput(); });
-      }
-
-      // Close-on-result-click (epic #2148): result links are created dynamically
-      // in renderResult(), so use one delegated listener on the results container
-      // instead of per-link handlers. We do NOT preventDefault \u2014 the link's own
-      // navigation (zfb Strategy-B SPA swap or a plain load) must still proceed;
-      // we only close the <dialog> so it does not linger over the swapped page.
-      // closeDialog() runs synchronously before navigation; the dialog's close
-      // restores documentElement overflow via the existing "close" listener.
-      if (this._results) {
-        this._resultsClickHandler = function(e) {
-          var t = e.target;
-          while (t && t !== self._results) {
-            if (t.tagName === "A") { self.closeDialog(); return; }
-            t = t.parentNode;
-          }
-        };
-        this._results.addEventListener("click", this._resultsClickHandler);
-      }
-
-      // Global keyboard shortcut (\u2318K / Ctrl+K to open)
-      this._keydownHandler = function(e) {
-        if ((e.metaKey || e.ctrlKey) && e.key === "k") {
-          e.preventDefault();
-          self.openDialog();
-        }
-      };
-      document.addEventListener("keydown", this._keydownHandler);
-
-      // View-Transitions compat: re-run on the v2 after-navigate event.
-      // Stored on the instance so disconnectedCallback can detach it on
-      // body swap when this element is NOT persisted via
-      // data-zfb-transition-persist (zudolab/zudo-doc#1523).
-      this._afterNavHandler = function() {
-        // Backstop for the original bug (epic #2148): if the dialog is somehow
-        // still open after an SPA body swap (e.g. a nav path that bypassed the
-        // result-click handler), close it so it does not linger / flash over the
-        // newly-swapped page. Safe no-op when already closed.
-        if (self._dialog && self._dialog.open) self.closeDialog();
-        var kbdEl2 = self.querySelector("[data-kbd-shortcut]");
-        if (kbdEl2) kbdEl2.textContent = self._shortcut;
-      };
-      document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, this._afterNavHandler);
-    }
-
-    disconnectedCallback() {
-      if (this._keydownHandler) {
-        document.removeEventListener("keydown", this._keydownHandler);
-        this._keydownHandler = null;
-      }
-      if (this._afterNavHandler) {
-        document.removeEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, this._afterNavHandler);
-        this._afterNavHandler = null;
-      }
-      if (this._resultsClickHandler && this._results) {
-        this._results.removeEventListener("click", this._resultsClickHandler);
-        this._resultsClickHandler = null;
-      }
-      this.teardownSentinel();
-    }
-
-    openDialog() {
-      if (!this._dialog) return;
-      document.documentElement.style.overflow = "hidden";
-      this._dialog.showModal();
-      if (this._input) {
-        this._input.focus();
-        this._input.select();
-      }
-      if (!this._entries && !this._loading) {
-        this.loadIndex();
-      }
-    }
-
-    closeDialog() {
-      if (!this._dialog) return;
-      this._dialog.close();
-      document.documentElement.style.overflow = "";
-    }
-
-    handleInput() {
-      var self = this;
-      if (this._debounce) clearTimeout(this._debounce);
-      this._debounce = setTimeout(function() { self.search(); }, 150);
-    }
-
-    loadIndex() {
-      if (this._loading) return;
-      this._loading = true;
-      var self = this;
-      var base = this.dataset.base || "/";
-      fetch(base + "search-index.json")
-        .then(function(r) {
-          if (!r.ok) throw new Error("HTTP " + r.status);
-          return r.json();
-        })
-        .then(function(data) {
-          self._entries = Array.isArray(data) ? data : (data.entries || []);
-          prepareLc(self._entries);
-          self._loading = false;
-          // Clear the unavailable flag BEFORE re-running search so a successful
-          // retry (e.g. via the openDialog() reload path) fully recovers (#2062).
-          self._indexUnavailable = false;
-          // If user already typed, search now
-          if (self._input && self._input.value.trim()) {
-            self.search();
-          }
-        })
-        .catch(function() {
-          self._loading = false;
-          self._indexUnavailable = true;
-          if (self._results) {
-            self._results.innerHTML = "<p class=\\"text-small text-muted\\">" + escapeHtml(self._searchUnavailable) + "</p>";
-          }
-        });
-    }
-
-    search() {
-      var query = this._input ? this._input.value.trim() : "";
-      this._currentQuery = query;
-
-      if (!query) {
-        this.teardownSentinel();
-        this._allResults = [];
-        this._shownCount = 0;
-        if (this._results) this._results.innerHTML = this.placeholderHtml();
-        this.updateCount();
-        return;
-      }
-
-      if (!this._entries) {
-        // Index failed to load: show the terminal "Search unavailable" state and
-        // stop \u2014 do NOT show "Loading search index\u2026" or refetch on every
-        // keystroke (#2062). The openDialog() reload path is the intended retry
-        // trigger. Clear any stale result state/count/sentinel first.
-        if (this._indexUnavailable) {
-          this.teardownSentinel();
-          this._allResults = [];
-          this._shownCount = 0;
-          if (this._results) {
-            this._results.innerHTML = "<p class=\\"text-small text-muted\\">" + escapeHtml(this._searchUnavailable) + "</p>";
-          }
-          this.updateCount();
-          return;
-        }
-        if (this._results) {
-          this._results.innerHTML = "<p class=\\"text-small text-muted\\">" + escapeHtml(this._loadingIndex) + "</p>";
-        }
-        if (!this._loading) this.loadIndex();
-        return;
-      }
-
-      // Lowercase the query terms once here so scoreEntry() can do plain
-      // indexOf() against pre-lowercased entry fields without repeating
-      // toLowerCase() across the entire index on every keystroke.
-      var terms = parseTerms(query).map(function(t) { return t.toLowerCase(); });
-      var scored = [];
-      for (var i = 0; i < this._entries.length; i++) {
-        var s = scoreEntry(this._entries[i], terms);
-        if (s > 0) scored.push({ entry: this._entries[i], score: s });
-      }
-      scored.sort(function(a, b) { return b.score - a.score; });
-      this._allResults = scored;
-      this._shownCount = 0;
-      this.teardownSentinel();
-      this.updateCount();
-
-      if (!scored.length) {
-        if (this._results) {
-          this._results.innerHTML = "<p class=\\"text-small text-muted\\">" + escapeHtml(this._noResults) + "</p>";
-        }
-        return;
-      }
-
-      if (this._results) this._results.innerHTML = "";
-      this.loadMore();
-      if (this._shownCount < this._allResults.length) {
-        this.setupSentinel();
-      }
-    }
-
-    loadMore() {
-      if (this._isLoadingBatch) return;
-      if (this._shownCount >= this._allResults.length) return;
-      this._isLoadingBatch = true;
-      try {
-        var batch = this._allResults.slice(this._shownCount, this._shownCount + PAGE_SIZE);
-        var self = this;
-        for (var i = 0; i < batch.length; i++) {
-          var article = self.renderResult(batch[i].entry);
-          if (self._sentinel && self._sentinel.parentNode === self._results) {
-            self._results.insertBefore(article, self._sentinel);
-          } else if (self._results) {
-            self._results.appendChild(article);
-          }
-        }
-        this._shownCount += batch.length;
-        if (this._shownCount >= this._allResults.length) {
-          this.teardownSentinel();
-        }
-      } finally {
-        this._isLoadingBatch = false;
-      }
-    }
-
-    setupSentinel() {
-      this.teardownSentinel();
-      if (!this._results) return;
-      var sentinel = document.createElement("div");
-      sentinel.setAttribute("data-search-sentinel", "");
-      sentinel.setAttribute("aria-hidden", "true");
-      sentinel.style.height = "1px";
-      sentinel.style.width = "100%";
-      this._results.appendChild(sentinel);
-      this._sentinel = sentinel;
-      var self = this;
-      this._observer = new IntersectionObserver(function(entries) {
-        for (var i = 0; i < entries.length; i++) {
-          if (entries[i].isIntersecting) self.loadMore();
-        }
-      }, { root: this._results, rootMargin: "200px 0px" });
-      this._observer.observe(sentinel);
-    }
-
-    teardownSentinel() {
-      if (this._observer) { this._observer.disconnect(); this._observer = null; }
-      if (this._sentinel) { this._sentinel.remove(); this._sentinel = null; }
-    }
-
-    updateCount() {
-      var count = this._allResults.length;
-      var template = this._resultCountTemplate;
-      var text = count > 0 ? template.replace("{count}", String(count)) : "";
-      var show = !!text;
-      if (this._countWide) {
-        this._countWide.textContent = text;
-        this._countWide.classList.toggle("hidden", !show);
-      }
-      if (this._countNarrow) {
-        this._countNarrow.textContent = text;
-        this._countNarrow.classList.toggle("hidden", !show);
-      }
-    }
-
-    placeholderHtml() {
-      return this._placeholderHtml;
-    }
-
-    renderResult(entry) {
-      var article = document.createElement("article");
-      article.className = "-mx-hsp-lg border-b border-muted";
-      var link = document.createElement("a");
-      link.href = safeHref(entry.url);
-      link.className =
-        "group block px-hsp-lg py-vsp-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent";
-      var title = document.createElement("span");
-      title.className =
-        "font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:underline";
-      var terms = parseTerms(this._currentQuery);
-      title.innerHTML = highlightTerms(entry.title || "", terms);
-      link.appendChild(title);
-      var text = entry.description || entry.body;
-      if (text) {
-        var excerpt = document.createElement("p");
-        excerpt.className =
-          "mt-vsp-2xs text-caption text-muted leading-relaxed group-hover:underline group-focus-visible:underline decoration-muted";
-        var truncated = truncate(text, this._currentQuery, 200);
-        excerpt.innerHTML = highlightTerms(truncated, terms);
-        link.appendChild(excerpt);
-      }
-      article.appendChild(link);
-      return article;
-    }
-  });
-})();`
-);
+import { SEARCH_WIDGET_SCRIPT } from "./generated-script.js";
 export {
   SEARCH_WIDGET_SCRIPT
 };

package/dist/settings.d.ts

@@ -207,6 +207,26 @@ export interface MetaTagsConfig {
     /** twitter:creator handle. Optional. */
     twitterCreator?: string;
 }
+/**
+ * Explicit favicon link set. Each key maps to one `<link rel="icon">` slot of
+ * the default four-file convention, and **only the supplied keys are emitted**
+ * — that is how a project whose `public/` has no `favicon.ico` stops shipping
+ * a 404ing link. Emission order is fixed (`svg → ico → png32 → png16`)
+ * regardless of key order in the object; `{}` emits nothing.
+ *
+ * Values starting with `/` are passed through `withBase()`; anything else
+ * (`data:`, `https://…`) is emitted verbatim. The `"auto"` sentinel is a
+ * whole-`favicon` value only — it is not meaningful inside this object. An
+ * empty-string slot (e.g. `{ ico: "" }`) throws a `TypeError` naming the
+ * slot at config resolution rather than being emitted (#3471) — `{}` (no
+ * slots at all) stays valid and emits nothing.
+ */
+export interface FaviconConfig {
+    svg?: string;
+    png32?: string;
+    png16?: string;
+    ico?: string;
+}
 /**
  * Site-wide custom `<head>` extras injected into every page via
  * {@link HeadWithDefaults}. All fields are JSON-serializable (no VNodes or
@@ -270,9 +290,24 @@ export interface Settings {
      * Home-hero logo. `"auto"` (the default when omitted) renders a generated
      * deterministic SVG seeded by `siteName`; a path string (e.g.
      * `"/img/logo.svg"`) renders that asset as a theme-adaptive CSS mask;
-     * `false` hides the logo block entirely.
+     * `false` hides the logo block entirely. The empty string `""` throws a
+     * `TypeError` at config resolution instead of silently rendering a mask
+     * of an empty path — pass `false` or omit the field instead (#3471).
      */
     logo?: string | false;
+    /**
+     * Favicon links. Omitted (the default) emits the four-file convention
+     * (`/favicon.svg`, `/favicon.ico`, `/favicon-32x32.png`,
+     * `/favicon-16x16.png`); `"auto"` emits one inline SVG data-URL icon
+     * generated from `siteName` (the same glyph `logo: "auto"` renders); any
+     * other string emits one link with the `type` inferred from its extension;
+     * a {@link FaviconConfig} object emits only the slots it supplies; `false`
+     * emits no favicon links at all. The empty string `""` (top-level or any
+     * `FaviconConfig` slot) throws a `TypeError` at config resolution instead
+     * of silently emitting `<link rel="icon" href="">`, which the HTML spec
+     * resolves to the current document — pass `false` or omit instead (#3471).
+     */
+    favicon?: string | FaviconConfig | false;
     base: string;
     trailingSlash: boolean;
     /** Package-owned home-page layout. Narrow when omitted. */
@@ -432,6 +467,52 @@ export interface Settings {
      * Only the PATH travels through `settings` (a string is serializable
      * data) — the bundler imports the actual builder from the re-exported
      * module. Irrelevant when `designTokenPanel` is `false`.
+     *
+     * SCOPE (#3396, bounded by #3414): this setting applies only to pages
+     * rendered through the package-injected routes. A doc page rendered by a
+     * SELF-CONTAINED host `pages/` stub does not reach the configured island —
+     * and, since the panel is configured once per browser session, a stub page
+     * mounting the package-default bootstrap used to decide the config for the
+     * whole session whenever it was the hard-loaded entry page (#3406).
+     *
+     * So when this setting is set and the host supplies no explicit
+     * `chromeBindings.DesignTokenPanelBootstrap`, stub-rendered pages now mount
+     * NO panel island at all (the injected routes still get the configured one,
+     * from any entry page). To get a panel on stub-rendered pages too, thread
+     * your builder through `chromeBindings.DesignTokenPanelBootstrap` — that
+     * binding wins everywhere and is unaffected by this rule. See
+     * `docs/adr/route-injection-seam.md`.
+     *
+     * EDGE CASE (zudolab/zudo-doc#3420, diagnostic added #3428, scoped by
+     * #3434/#3435): a locked-manifest host whose kept `pages/` stubs happen to
+     * shadow every injected route a READER BROWSES (Decision 6 in
+     * `plugins/routes.ts` drops a collided injected route silently — user
+     * `pages/` always wins) gets no configured DTP island on any page of its
+     * documentation when this setting is set, with no build error.
+     * `plugins/routes.ts` now probes for exactly this at plugin setup — if every
+     * derived route tagged `includedInDtpShadowDiagnostic` resolves to an
+     * existing user `pages/` file, it emits a loud `ctx.logger.warn` naming this
+     * gap and the `chromeBindings.DesignTokenPanelBootstrap` workaround above.
+     * The denominator deliberately excludes `/404`, `/sitemap.xml`,
+     * `/robots.txt` and `/api/ai-chat` — none of them is a documentation page a
+     * reader browses, and the two non-HTML ones could never be shadowed by a
+     * minimal scaffold, which is what kept the original all-routes form of this
+     * check from ever firing (#3434).
+     *
+     * Three further suppressions: the diagnostic is silent unless
+     * `designTokenPanel` is `true` (with the feature off this setting is
+     * irrelevant, per the paragraph above — #3435); silent when the resolved
+     * `chromeBindingsModule` file already contains the literal token
+     * `DesignTokenPanelBootstrap` (a best-effort static text scan — an
+     * indirectly-composed override that never spells the name out keeps
+     * warning); and a `pages/` file that is an exact default re-export of the
+     * shadowed route's OWN package entrypoint
+     * (`export { default, paths, frontmatter } from "@takazudo/zudo-doc/routes/…"`)
+     * does not count as a shadow at all, because it still reaches the configured
+     * bootstrap through `routes/_chrome.tsx` (#3451 — also a best-effort text
+     * scan, so a file that reaches the same entrypoint some other way still
+     * counts as shadowed). Partial shadowing stays silent: the config still
+     * applies on whichever reader-facing routes survive.
      */
     designTokenPanelConfigModule?: string;
     /**

package/dist/sidebar-tree/category-meta.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Synchronous reader for `_category_.json` files. Walks a directory tree
+ * and returns a map of `<relative-dir-path>` → {@link CategoryMeta}.
+ *
+ * Lives in this folder rather than reusing the project's existing
+ * `loadCategoryMeta` because the framework-layer must not import anything
+ * from the consumer project (`@/utils/...`). Behaviour is intentionally
+ * identical to the original so call sites can swap implementations 1:1.
+ */
 import type { CategoryMeta } from "./types.js";
 /**
  * Scan `contentDir` recursively for `_category_.json` files. Each file's

package/dist/sidebar-tree/category-meta.js

@@ -1,24 +1,33 @@
-import fs from "node:fs";
-import path from "node:path";
 const cache = /* @__PURE__ */ new Map();
-function loadCategoryMeta(contentDir) {
-  let absolute;
+function resolveBuiltins() {
+  const getBuiltinModule = globalThis.process?.getBuiltinModule;
+  if (typeof getBuiltinModule !== "function") return void 0;
   try {
-    absolute = path.resolve(contentDir);
+    const fs = getBuiltinModule("node:fs");
+    const path = getBuiltinModule("node:path");
+    if (!fs || !path) return void 0;
+    return { fs, path };
   } catch {
-    absolute = contentDir;
+    return void 0;
   }
+}
+function loadCategoryMeta(contentDir) {
+  const builtins = resolveBuiltins();
+  const absolute = builtins ? builtins.path.resolve(contentDir) : contentDir;
   const cached = cache.get(absolute);
   if (cached) return cached;
   const result = /* @__PURE__ */ new Map();
-  scanDir(absolute, absolute, result);
+  if (builtins) {
+    scanDir(builtins, absolute, absolute, result);
+  }
   cache.set(absolute, result);
   return result;
 }
 function clearCategoryMetaCache() {
   cache.clear();
 }
-function scanDir(baseDir, currentDir, result) {
+function scanDir(builtins, baseDir, currentDir, result) {
+  const { fs, path } = builtins;
   let entries;
   try {
     entries = fs.readdirSync(currentDir, { withFileTypes: true });
@@ -30,19 +39,19 @@ function scanDir(baseDir, currentDir, result) {
     const fullPath = path.join(currentDir, entry.name);
     const categoryFile = path.join(fullPath, "_category_.json");
     if (fs.existsSync(categoryFile)) {
-      const meta = readCategoryFile(categoryFile);
+      const meta = readCategoryFile(builtins, categoryFile);
       if (meta) {
         const relativePath = path.relative(baseDir, fullPath);
         result.set(relativePath, meta);
       }
     }
-    scanDir(baseDir, fullPath, result);
+    scanDir(builtins, baseDir, fullPath, result);
   }
 }
-function readCategoryFile(filePath) {
+function readCategoryFile(builtins, filePath) {
   let raw;
   try {
-    raw = fs.readFileSync(filePath, "utf-8");
+    raw = builtins.fs.readFileSync(filePath, "utf-8");
   } catch {
     return void 0;
   }

package/dist/sidebar-tree-island/index.d.ts

@@ -2,12 +2,19 @@ import type { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink } from "../
 export interface SidebarTreeProps {
     nodes: SidebarNavNode[];
     currentSlug?: string;
+    /**
+     * Explicit current-route override, checked before the
+     * `data-zd-current-path` dataset override and `window.location.pathname`
+     * when deriving the active slug on hydration and at every View Transition.
+     * See `deriveActiveSlug` (zudolab/zudo-doc#3398).
+     */
+    currentPath?: string;
     rootMenuItems?: SidebarRootMenuItem[];
     backToMenuLabel?: string;
     localeLinks?: SidebarLocaleLink[];
     themeDefaultMode?: "light" | "dark";
 }
-export declare function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps): import("preact").JSX.Element;
+export declare function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps): import("preact").JSX.Element;
 export declare namespace SidebarTree {
     var displayName: string;
 }