@takazudo/zudo-doc 2.4.1 → 2.5.1

package/dist/desktop-sidebar-toggle-island/index.d.ts

@@ -1,4 +1,6 @@
 export declare const SIDEBAR_STORAGE_KEY = "zudo-doc-sidebar-visible";
+export declare function readState(): boolean;
+export declare function setDataAttribute(isVisible: boolean): void;
 export declare function DesktopSidebarToggle(): import("preact").JSX.Element;
 export declare namespace DesktopSidebarToggle {
     var displayName: string;

package/dist/desktop-sidebar-toggle-island/index.js

@@ -58,5 +58,7 @@ function DesktopSidebarToggle() {
 DesktopSidebarToggle.displayName = "DesktopSidebarToggle";
 export {
   DesktopSidebarToggle,
-  SIDEBAR_STORAGE_KEY
+  SIDEBAR_STORAGE_KEY,
+  readState,
+  setDataAttribute
 };

package/dist/doc-page-shell/index.js

@@ -4,7 +4,10 @@ import { DocLayoutWithDefaults } from "../doclayout/index.js";
 import { Toc, MobileToc, getTocTitle } from "../toc/index.js";
 import { Breadcrumb } from "../breadcrumb/index.js";
 import { NavCardGrid } from "../nav-indexing/index.js";
-import { createSidebarPrepaint } from "../sidebar-prepaint/index.js";
+import {
+  createSidebarPrepaint,
+  createSidebarVisibilityPrepaint
+} from "../sidebar-prepaint/index.js";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
 import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
 import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
@@ -21,8 +24,14 @@ function createDocPageShell(ctx) {
   const SidebarWithDefaults = createSidebarWithDefaults(ctx);
   const HeaderWithDefaults = createHeaderWithDefaults(ctx);
   const FooterWithDefaults = createFooterWithDefaults(ctx);
+  const sidebarToggleEnabled = Boolean(
+    ctx.settings.sidebarToggle
+  );
   const SidebarPrepaint = createSidebarPrepaint({
-    sidebarToggle: Boolean(ctx.settings.sidebarToggle)
+    sidebarToggle: sidebarToggleEnabled
+  });
+  const SidebarVisibilityPrepaint = createSidebarVisibilityPrepaint({
+    sidebarToggle: sidebarToggleEnabled
   });
   const DocBodyEnd = createDocBodyEnd(ctx);
   const DocPager = createDocPager(ctx);
@@ -69,7 +78,10 @@ function createDocPageShell(ctx) {
       {
         title: composeMetaTitle(title),
         description: settings.metaTags.description ? description : void 0,
-        head: /* @__PURE__ */ jsx(HeadWithDefaults, { title, description, canonical }),
+        head: /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(HeadWithDefaults, { title, description, canonical }),
+          /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar })
+        ] }),
         lang: locale,
         noindex: settings.noindex,
         hideSidebar,

package/dist/integrations/claude-resources/generate.js

@@ -97,11 +97,14 @@ function downgradeRepoRelativeLinks(content) {
 function findClaudeMdFiles(dir, excludeDirs) {
   const results = [];
   if (!fs.existsSync(dir)) return results;
+  const excludes = excludeDirs.map(
+    (d) => d.endsWith(path.sep) ? d.slice(0, -path.sep.length) : d
+  );
   for (const item of fs.readdirSync(dir)) {
     if (item === "node_modules") continue;
     if (item.startsWith(".")) continue;
     const itemPath = path.join(dir, item);
-    if (excludeDirs.some((d) => itemPath.startsWith(d))) continue;
+    if (excludes.some((d) => itemPath === d || itemPath.startsWith(d + path.sep))) continue;
     let stat;
     try {
       stat = fs.lstatSync(itemPath);
@@ -109,7 +112,7 @@ function findClaudeMdFiles(dir, excludeDirs) {
       continue;
     }
     if (stat.isDirectory()) {
-      results.push(...findClaudeMdFiles(itemPath, excludeDirs));
+      results.push(...findClaudeMdFiles(itemPath, excludes));
     } else if (stat.isFile() && item === "CLAUDE.md") {
       results.push(itemPath);
     }
@@ -441,8 +444,6 @@ sidebar_position: 899
 generated: true
 ---
 
-Claude Code configuration reference.
-
 ## Resources
 
 <CategoryNav categories={${categoriesAttr}} />

package/dist/integrations/claude-resources/index.d.ts

@@ -12,10 +12,27 @@ export interface ClaudeResourcesPluginOptions {
      */
     claudeDir: string;
     /**
-     * Project root used both as the search root for `CLAUDE.md` discovery
-     * and to anchor relative paths. Defaults to `process.cwd()`.
+     * Anchor for resolving the relative `claudeDir`, `docsDir`, and `scanRoot`
+     * paths, and the default value of `scanRoot`. Defaults to `process.cwd()`.
+     *
+     * Note: this does NOT itself decide where `CLAUDE.md` discovery walks — that
+     * is `scanRoot` (which defaults to this). Set `scanRoot` to widen discovery
+     * (e.g. a subdirectory doc site scanning its repo root) without moving the
+     * output base, which stays anchored here.
      */
     projectRoot?: string;
+    /**
+     * Root for `CLAUDE.md` discovery and the base for the generated pages'
+     * relative-path titles/slugs. Defaults to `projectRoot`. Resolved against
+     * `projectRoot` when relative (absolute allowed).
+     *
+     * Scope: governs `CLAUDE.md` discovery ONLY. Commands, skills, and agents
+     * always come from `claudeDir` and are unaffected by `scanRoot`. Decoupling
+     * this from `projectRoot` lets a doc site in a repo subdirectory scan
+     * repo-wide `CLAUDE.md` files while still writing generated pages into its
+     * own content collection (see #2558).
+     */
+    scanRoot?: string;
     /**
      * Output directory for generated MDX pages, resolved against
      * `projectRoot` when relative. Defaults to `src/content/docs` to

package/dist/integrations/claude-resources/index.js

@@ -12,9 +12,10 @@ function claudeResourcesPlugin(options) {
 function runClaudeResourcesPreStep(options) {
   const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
   const claudeDir = path.isAbsolute(options.claudeDir) ? options.claudeDir : path.resolve(projectRoot, options.claudeDir);
+  const scanRoot = options.scanRoot === void 0 ? projectRoot : path.isAbsolute(options.scanRoot) ? options.scanRoot : path.resolve(projectRoot, options.scanRoot);
   const docsDirInput = options.docsDir ?? "src/content/docs";
   const docsDir = path.isAbsolute(docsDirInput) ? docsDirInput : path.resolve(projectRoot, docsDirInput);
-  return generateClaudeResourcesDocs({ claudeDir, projectRoot, docsDir });
+  return generateClaudeResourcesDocs({ claudeDir, projectRoot: scanRoot, docsDir });
 }
 export {
   CLAUDE_RESOURCES_PLUGIN_NAME,

package/dist/plugins/claude-resources.js

@@ -10,10 +10,12 @@ const plugin = {
       );
     }
     const projectRootOpt = ctx.options["projectRoot"];
+    const scanRootOpt = ctx.options["scanRoot"];
     const docsDirOpt = ctx.options["docsDir"];
     const result = await runClaudeResourcesPreStep({
       claudeDir,
       projectRoot: typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
+      scanRoot: typeof scanRootOpt === "string" ? scanRootOpt : void 0,
       docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs"
     });
     ctx.logger.info(

package/dist/preset.d.ts

@@ -50,6 +50,11 @@ export interface PresetVersionConfig {
 export interface PresetClaudeResourcesConfig {
     claudeDir: string;
     projectRoot?: string;
+    /**
+     * Root for `CLAUDE.md` discovery; defaults to `projectRoot`. Decouples
+     * repo-wide scanning from the output base for subdirectory doc sites (#2558).
+     */
+    scanRoot?: string;
 }
 /**
  * The subset of `settings` the preset reads. Any concrete `typeof settings`

package/dist/preset.js

@@ -171,6 +171,7 @@ function buildPlugins(settings, routeContext) {
         options: {
           claudeDir: settings.claudeResources.claudeDir,
           projectRoot: settings.claudeResources.projectRoot,
+          scanRoot: settings.claudeResources.scanRoot,
           docsDir: settings.docsDir
         }
       }

package/dist/settings.d.ts

@@ -301,6 +301,7 @@ export interface Settings {
     claudeResources: {
         claudeDir: string;
         projectRoot?: string;
+        scanRoot?: string;
     } | false;
     defaultLocaleOnlyPrefixes: string[];
     footer: FooterConfig | false;

package/dist/sidebar-prepaint/index.d.ts

@@ -8,10 +8,36 @@ export interface SidebarPrepaintProps {
      */
     hideSidebar?: boolean;
 }
-/** Settings subset read by {@link createSidebarPrepaint}. */
+/** Settings subset read by the sidebar-prepaint factories. */
 export interface SidebarPrepaintSettings {
     sidebarToggle?: boolean;
 }
+/**
+ * Pre-paint inline script body: restore persisted sidebar visibility to
+ * `<html data-sidebar-hidden>` before first paint to avoid a hard-reload flash.
+ *
+ * A tiny synchronous IIFE that reads `localStorage[SIDEBAR_STORAGE_KEY]` and
+ * sets `data-sidebar-hidden` only when the stored value is exactly "false"
+ * (the collapsed preference) — the default (visible) needs no attribute and
+ * causes no layout shift. Silently no-ops in privacy / disabled-storage modes.
+ *
+ * The storage key is interpolated from `SIDEBAR_STORAGE_KEY` so it stays in
+ * sync with the island's reader; the `data-sidebar-hidden` attribute name is a
+ * literal here (the island's `setDataAttribute` hardcodes the same literal —
+ * keep the two in sync). Intended for `<head>` placement so it executes before
+ * the `<aside>` sidebar is painted.
+ */
+export declare const SIDEBAR_VISIBILITY_PREPAINT_SCRIPT: string;
+/**
+ * Create a `SidebarVisibilityPrepaint` component bound to the host's settings.
+ *
+ * Returns the pre-paint `<script>` (for the page `<head>`) when
+ * `settings.sidebarToggle` is enabled AND the page actually shows a sidebar;
+ * returns `undefined` when the toggle is disabled or the page hides the sidebar
+ * — the SAME gating as {@link createSidebarPrepaint}, so the head script and
+ * the afterSidebar toggle button always appear together.
+ */
+export declare function createSidebarVisibilityPrepaint(settings: SidebarPrepaintSettings): (props: SidebarPrepaintProps) => JSX.Element | undefined;
 /**
  * Create a `SidebarPrepaint` component bound to the host's settings.
  *

package/dist/sidebar-prepaint/index.js

@@ -1,23 +1,43 @@
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { Fragment, jsx } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
-import { DesktopSidebarToggle } from "../desktop-sidebar-toggle-island/index.js";
+import {
+  DesktopSidebarToggle,
+  SIDEBAR_STORAGE_KEY
+} from "../desktop-sidebar-toggle-island/index.js";
+function sidebarPrepaintActive(settings, hideSidebar) {
+  return Boolean(settings.sidebarToggle) && !hideSidebar;
+}
+const SIDEBAR_VISIBILITY_PREPAINT_SCRIPT = `(function(){try{if(localStorage.getItem(${JSON.stringify(
+  SIDEBAR_STORAGE_KEY
+)})==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`;
+function createSidebarVisibilityPrepaint(settings) {
+  function SidebarVisibilityPrepaint({
+    hideSidebar
+  }) {
+    if (!sidebarPrepaintActive(settings, hideSidebar)) return void 0;
+    return /* @__PURE__ */ jsx(
+      "script",
+      {
+        dangerouslySetInnerHTML: { __html: SIDEBAR_VISIBILITY_PREPAINT_SCRIPT }
+      }
+    );
+  }
+  return SidebarVisibilityPrepaint;
+}
 function createSidebarPrepaint(settings) {
   function SidebarPrepaint({
     hideSidebar
   }) {
-    if (!settings.sidebarToggle || hideSidebar) return void 0;
-    return /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: {
-        __html: `(function(){try{if(localStorage.getItem('zudo-doc-sidebar-visible')==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`
-      } }),
-      Island({
-        when: "load",
-        children: /* @__PURE__ */ jsx(DesktopSidebarToggle, {})
-      })
-    ] });
+    if (!sidebarPrepaintActive(settings, hideSidebar)) return void 0;
+    return /* @__PURE__ */ jsx(Fragment, { children: Island({
+      when: "load",
+      children: /* @__PURE__ */ jsx(DesktopSidebarToggle, {})
+    }) });
   }
   return SidebarPrepaint;
 }
 export {
-  createSidebarPrepaint
+  SIDEBAR_VISIBILITY_PREPAINT_SCRIPT,
+  createSidebarPrepaint,
+  createSidebarVisibilityPrepaint
 };

package/dist/url-helpers/index.js

@@ -25,7 +25,8 @@ function makeUrlHelpers(settings, i18n) {
     return settings.siteUrl ? settings.siteUrl.replace(/\/$/, "") + pageUrl : void 0;
   }
   function docsUrl(slug, lang = defaultLocale) {
-    const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
+    const defaultPath = `/docs/${slug}`;
+    const path = lang === defaultLocale || isDefaultLocaleOnlyPath(defaultPath) ? defaultPath : `/${lang}/docs/${slug}`;
     return withBase(path);
   }
   function isExternal(href) {
@@ -35,7 +36,7 @@ function makeUrlHelpers(settings, i18n) {
     return isExternal(href) ? href : withBase(href);
   }
   function navHref(path, lang, currentVersion) {
-    const isNonDefaultLocale = lang != null && lang !== defaultLocale;
+    const isNonDefaultLocale = lang != null && lang !== defaultLocale && !isDefaultLocaleOnlyPath(path);
     const versionPrefix = currentVersion ? `/v/${currentVersion}` : "";
     return withBase(
       isNonDefaultLocale ? `${versionPrefix}/${lang}${path}` : `${versionPrefix}${path}`
@@ -82,7 +83,8 @@ function makeUrlHelpers(settings, i18n) {
     }));
   }
   function versionedDocsUrl(slug, versionSlug, lang = defaultLocale) {
-    const path = lang === defaultLocale ? `/v/${versionSlug}/docs/${slug}` : `/v/${versionSlug}/${lang}/docs/${slug}`;
+    const localePrefixed = lang !== defaultLocale && !isDefaultLocaleOnlyPath(`/docs/${slug}`);
+    const path = localePrefixed ? `/v/${versionSlug}/${lang}/docs/${slug}` : `/v/${versionSlug}/docs/${slug}`;
     return withBase(path);
   }
   return {

package/eject/desktop-sidebar-toggle-island/index.tsx

@@ -8,7 +8,12 @@ import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 
 export const SIDEBAR_STORAGE_KEY = "zudo-doc-sidebar-visible";
 
-function readState(): boolean {
+// Exported for unit testing the mount-reconcile logic in a plain Node env
+// (no jsdom in the package vitest config) — the same convention the sibling
+// ThemeToggle uses via color-scheme-sync.ts. `readState` is the localStorage
+// reader the mount effect uses to reconcile `visible` on initial load;
+// `setDataAttribute` is the `<html data-sidebar-hidden>` writer.
+export function readState(): boolean {
   if (typeof window === "undefined") return true;
   try {
     return localStorage.getItem(SIDEBAR_STORAGE_KEY) !== "false";
@@ -17,7 +22,7 @@ function readState(): boolean {
   }
 }
 
-function setDataAttribute(isVisible: boolean) {
+export function setDataAttribute(isVisible: boolean) {
   if (isVisible) {
     document.documentElement.removeAttribute("data-sidebar-hidden");
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -586,7 +586,7 @@
     "zod": "^4.3.6",
     "@takazudo/zfb": "0.1.0-next.76",
     "@takazudo/zfb-runtime": "0.1.0-next.76",
-    "@takazudo/zudo-doc-history-server": "2.4.1"
+    "@takazudo/zudo-doc-history-server": "2.5.1"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",