create-zudo-doc 0.2.2 → 0.2.4

package/dist/scaffold.js

@@ -269,16 +269,30 @@ function generatePackageJson(choices) {
         // cross-file anchor validation. BREAKING upstream: the no-op
         // `linkValidation.allowExternal` knob was removed — neither the host nor
         // the generated config ever emitted it, so no migration is needed here.
-        "@takazudo/zfb": "0.1.0-next.38",
-        "@takazudo/zfb-runtime": "0.1.0-next.38",
+        // next.39 is features + fixes, no breaking changes:
+        // npm-dist `"use client"` island scanning, link-resolution fixes for
+        // directory-style hrefs, and island-registry hardening (warns on island
+        // marker-name collisions).
+        // next.40 flips `zfb dev` to lazy rendering by default —
+        // pages render on first request instead of on every file-change tick
+        // (Takazudo/zudo-front-builder#1029); `ZFB_DEV_EAGER=1` restores eager
+        // mode. Dev-server-only change, no build/config migration needed.
+        // next.41 (current pin) adds a URL-space fallback in resolve_links —
+        // dir-style hrefs written from non-index pages now resolve against the
+        // page's URL directory when the file-space lookup misses
+        // (Takazudo/zudo-front-builder#1030) — and the data-file skip warning
+        // (e.g. for `_category_.json`) now respects the collection's
+        // include/exclude globs (#1032). No consumer-facing breaking change.
+        "@takazudo/zfb": "0.1.0-next.41",
+        "@takazudo/zfb-runtime": "0.1.0-next.41",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.38",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.41",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
         // version moves, so a fresh scaffold pulls the version we just published.
-        "@takazudo/zudo-doc": "^0.2.2",
+        "@takazudo/zudo-doc": "^0.2.4",
         // zod — used by the generated zfb.config.ts. zfb-config-gen emits
         // `import { z } from "zod"` for the content-collection schema +
         // `z.toJSONSchema(...)` conversion. Without this dep, the consumer
@@ -332,7 +346,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^0.2.2";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.4";
         // W7A (#1736): doc-history-plugin.mjs spawns `tsx -e <inline-script>` to
         // run the v2 runtime in a TS-aware Node subprocess; without tsx the
         // plugin's preBuild step exits with ENOENT before zfb finishes config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/404.tsx

@@ -36,6 +36,11 @@ export default function NotFoundPage(): JSX.Element {
       noindex={true}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

package/templates/base/pages/index.tsx

@@ -65,6 +65,11 @@ export default function IndexPage(): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/")} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -109,10 +109,14 @@ export interface BodyEndIslandsProps {
 }
 
 /**
- * The three default body-end islands every doc page mounts: the
- * design-token tweak panel (overlay, fixed-position), the AI chat
- * modal (`<dialog>` overlay), and the image-enlarge dialog (mounted
- * lazily based on viewport scan).
+ * The default body-end islands a doc page may mount: the design-token
+ * tweak panel (overlay, fixed-position), the AI chat modal (`<dialog>`
+ * overlay), and the image-enlarge dialog (mounted lazily based on
+ * viewport scan). Each is feature-gated — the design-token panel on
+ * `settings.designTokenPanel`, the AI chat modal (and its sr-only
+ * landmark heading) on `settings.aiAssistant`, and image-enlarge on
+ * `settings.imageEnlarge` — so a feature-off consumer ships neither the
+ * island marker nor a misleading landmark (zudolab/zudo-doc#2058).
  *
  * Each island is wrapped in `<Island ssrFallback>` so the heavy
  * component is NOT evaluated server-side — they depend on
@@ -120,9 +124,10 @@ export interface BodyEndIslandsProps {
  * fetch, etc. The hydration runtime swaps each placeholder on the
  * client.
  *
- * The `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in
- * the SSG output so screen readers and crawlers can discover the chat
- * section landmark before JS hydration.
+ * When `settings.aiAssistant` is enabled, the
+ * `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in the SSG
+ * output so screen readers and crawlers can discover the chat section
+ * landmark before JS hydration.
  */
 export function BodyEndIslands({
   basePath,
@@ -163,26 +168,52 @@ export function BodyEndIslands({
         )
       : null;
 
-  // Use a visually-hidden paragraph as the AiChatModal SSR fallback so
-  // the body label is present in static HTML for screen readers before
-  // JS hydration. sr-only keeps it invisible to sighted users.
-  const aiChat = Island({
-    ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
-    children: <AiChatModal basePath={basePath} />,
-  }) as unknown as VNode;
+  // Gated on `settings.aiAssistant` (zudolab/zudo-doc#2058): when the AI
+  // assistant feature is off, neither the AiChatModal island marker nor the
+  // sr-only "AI Assistant" landmark heading should reach the SSG output —
+  // otherwise feature-off consumers ship a dead island marker plus a
+  // misleading screen-reader landmark for a section that never hydrates.
+  // Mirrors the `designTokenPanel` gating above.
+  //
+  // KNOWN CAVEAT: zfb's island scanner walks the static `"use client"`
+  // import chain, so gating this JSX removes the SSR marker and heading but
+  // may NOT strip the AiChatModal bundle from the build output. Marker
+  // removal is the agreed first fix (#2058); bundle stripping is out of scope.
+  //
+  // The sr-only <p> fallback keeps the body label in static HTML for screen
+  // readers before JS hydration; sr-only keeps it invisible to sighted users.
+  const aiAssistant = settings.aiAssistant ? (
+    <>
+      {/* Emits the "AI Assistant" heading in the SSG output so screen
+          readers can discover the chat section landmark before JS
+          hydration. */}
+      <h2 class="sr-only">AI Assistant</h2>
+      {
+        Island({
+          ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
+          children: <AiChatModal basePath={basePath} />,
+        }) as unknown as VNode
+      }
+    </>
+  ) : null;
 
-  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty,
-  // closed `<dialog class="zd-enlarge-dialog ...">` shell so the dist
-  // HTML carries one dialog from the start. Without this the smoke
-  // "exactly one zd-enlarge-dialog element" assertion sees zero
-  // (skip-ssr placeholders are empty divs) and the no-JS path has no
-  // dialog at all. Hydration replaces this shell with the real
-  // ImageEnlarge component when the page goes idle.
-  const imageEnlarge = Island({
-    when: "idle",
-    ssrFallback: <ImageEnlargeSsrFallback />,
-    children: <ImageEnlarge />,
-  }) as unknown as VNode;
+  // Gated on `settings.imageEnlarge` (zudolab/zudo-doc#2058). Same caveat as
+  // the AI assistant gating: removing this JSX drops the SSR dialog shell and
+  // island marker, but the bundle may persist via the static import scan.
+  //
+  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty, closed
+  // `<dialog class="zd-enlarge-dialog ...">` shell so the dist HTML carries
+  // one dialog from the start. Without this the smoke "exactly one
+  // zd-enlarge-dialog element" assertion sees zero (skip-ssr placeholders are
+  // empty divs) and the no-JS path has no dialog at all. Hydration replaces
+  // this shell with the real ImageEnlarge component when the page goes idle.
+  const imageEnlarge = settings.imageEnlarge
+    ? (Island({
+        when: "idle",
+        ssrFallback: <ImageEnlargeSsrFallback />,
+        children: <ImageEnlarge />,
+      }) as unknown as VNode)
+    : null;
 
   return (
     <>
@@ -192,11 +223,7 @@ export function BodyEndIslands({
       <PageLoadingOverlay />
       {clientRouterBootstrap}
       {designTokenPanelBootstrap}
-      {/* Emits the "AI Assistant" heading in the SSG output so screen
-          readers can discover the chat section landmark before JS
-          hydration. */}
-      <h2 class="sr-only">AI Assistant</h2>
-      {aiChat}
+      {aiAssistant}
       {imageEnlarge}
       {/* @slot:body-end-islands:extra-islands */}
     </>

package/templates/base/pages/lib/_doc-page-shell.tsx

@@ -17,9 +17,12 @@
 // keeping the create-zudo-doc template copies byte-identical to the host.
 
 import type { ComponentChildren, JSX, VNode } from "preact";
+import { Island } from "@takazudo/zfb";
 import { settings } from "@/config/settings";
 import type { NavNode } from "@/utils/docs";
 import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Toc, MobileToc } from "@takazudo/zudo-doc/toc";
+import { getTocTitle } from "./_toc-title";
 import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
 import { NavCardGrid } from "@takazudo/zudo-doc/nav-indexing";
 import { HeadWithDefaults } from "./_head-with-defaults";
@@ -145,6 +148,31 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
     docHistorySlot,
   } = props;
 
+  // TOC overrides: mount the package Toc/MobileToc with the host-resolved
+  // locale-aware `tocTitle`. The gating mirrors the package's
+  // `shouldRenderDefaultToc` exactly (`!hideToc && headings.length > 0`) so an
+  // undefined override never silently falls back to the package default with a
+  // different title. Each is wrapped in `<Island when="load">` here (the call
+  // site), matching how the package wraps its own default. Hydrating these
+  // npm-dist "use client" components requires zfb >= 0.1.0-next.39, whose
+  // scanner registers node_modules islands (zfb#999/#1001) — the former
+  // scanner-visible local shims (#2057) are gone; re-adding them would
+  // recreate island marker-name collisions.
+  const tocTitle = getTocTitle(locale);
+  const shouldRenderToc = !hideToc && headings.length > 0;
+  const tocOverride = shouldRenderToc
+    ? (Island({
+        when: "load",
+        children: <Toc headings={headings} title={tocTitle} />,
+      }) as unknown as VNode)
+    : undefined;
+  const mobileTocOverride = shouldRenderToc
+    ? (Island({
+        when: "load",
+        children: <MobileToc headings={headings} title={tocTitle} />,
+      }) as unknown as VNode)
+    : undefined;
+
   return (
     <DocLayoutWithDefaults
       title={composeMetaTitle(title)}
@@ -183,6 +211,8 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
           currentPath={currentPath}
         />
       }
+      tocOverride={tocOverride}
+      mobileTocOverride={mobileTocOverride}
       afterSidebar={<SidebarPrepaint />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<DocBodyEnd />}

package/templates/base/pages/lib/_header-with-defaults.tsx

@@ -45,14 +45,12 @@ import {
   VersionSwitcher,
   type VersionSwitcherLabels,
 } from "@takazudo/zudo-doc/i18n-version";
-// ThemeToggle via the project-source shim (`@/components/theme-toggle`)
-// rather than the package subpath directly. zfb's island scanner does not
-// register "use client" modules under node_modules (zfb#999), so importing
-// the package component here would emit an island marker with no registry
-// entry and the toggle would never hydrate (zudolab/zudo-doc#2048). The shim
-// re-wraps the bare (non-island-wrapped) package ThemeToggle; this wrapper
-// composes its own Island below, avoiding nesting an island inside an island.
-import { ThemeToggle } from "@/components/theme-toggle";
+// The bare (non-island-wrapped) package ThemeToggle, imported straight from
+// the npm subpath: zfb >= 0.1.0-next.39 scans "use client" modules under
+// node_modules (zfb#999/#1001), so the marker registers without the former
+// project-source shim (#2048/#2057). This header composes its own Island
+// below, avoiding nesting an island inside an island.
+import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
 import SidebarToggle from "@/components/sidebar-toggle";
 import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";

package/templates/base/pages/lib/_search-widget-script.ts

@@ -249,6 +249,9 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
           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();
@@ -277,6 +280,20 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       }
 
       if (!this._entries) {
+        // Index failed to load: show the terminal "Search unavailable" state and
+        // stop — do NOT show "Loading search index…" 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\\">Search unavailable</p>";
+          }
+          this.updateCount();
+          return;
+        }
         if (this._results) {
           this._results.innerHTML = "<p class=\\"text-small text-muted\\">Loading search index\\u2026</p>";
         }

package/templates/base/pages/lib/_toc-title.ts

@@ -0,0 +1,3 @@
+// TOC section-label resolver for the Toc/MobileToc overrides mounted by
+// `_doc-page-shell.tsx`, re-exported from the @takazudo/zudo-doc package.
+export { getTocTitle } from "@takazudo/zudo-doc/toc";

package/templates/base/src/components/sidebar-toggle.tsx

@@ -131,8 +131,15 @@ export default function SidebarToggle({
         onClick={() => setOpen(false)}
       />
 
-      {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout) */}
+      {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout).
+          `inert` when closed: the panel is only visually hidden via
+          `-translate-x-full`, so without `inert` its links/filter/buttons
+          stay in the tab order and accessibility tree while off-screen
+          (zudolab/zudo-doc#2059). `inert={false}` serialises to no attribute,
+          so the SSR (open=false → `inert`) and initial client render stay
+          byte-stable for hydration. */}
       <aside
+        inert={!open}
         className={`
           fixed top-[3.5rem] left-0 z-40 h-[calc(100vh-3.5rem)] w-[16rem] flex flex-col
           border-r border-muted bg-bg transition-transform duration-200

package/templates/features/docHistory/files/src/components/doc-history.tsx

@@ -610,7 +610,12 @@ export function DocHistory({ slug, locale, basePath = "/" }: DocHistoryProps) {
               {/* Right: diff viewer (on mobile, replaces the sidebar) */}
               {hasDiff && (
                 <div className="flex-1 min-w-0 h-full">
+                  {/* Key on the compared pair forces a fresh mount whenever the
+                      selection changes, so the previous pair's diff rows can
+                      never render under the new header hashes while the lazy
+                      import("diff") recompute is in flight (#2068). */}
                   <DiffViewer
+                    key={`${diffSelection.older.hash}:${diffSelection.newer.hash}`}
                     selection={diffSelection}
                     onBack={handleBackToRevisions}
                     showBackButton={true}

package/templates/features/docTags/files/pages/lib/_tag-pages.tsx

@@ -131,6 +131,11 @@ export function TagDetailPageView({
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       // Tag segment URL-encoded — emitted href/path sites only; route params
       // stay raw (e.g. "type:guide" → "type%3Aguide").
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags/${encodeURIComponent(tag)}`)} />}
@@ -184,6 +189,11 @@ export function TagsIndexPageView({ locale }: { locale: string }): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags`)} />}
       breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
       footerOverride={<FooterWithDefaults lang={locale} />}

package/templates/features/i18n/files/pages/[locale]/index.tsx

@@ -103,6 +103,11 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`/${locale}/`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

package/templates/features/versioning/files/pages/lib/_versions-page.tsx

@@ -65,6 +65,11 @@ export function VersionsPageView({ locale }: { locale: string }): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`${prefix}/docs/versions`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

package/templates/base/src/components/theme-toggle.tsx

@@ -1,23 +0,0 @@
-"use client";
-
-// Scanner-visible ThemeToggle shim. zfb's island scanner does not register
-// "use client" modules located under node_modules (Takazudo/zudo-front-builder#999),
-// so importing the package ThemeToggle straight into the server-rendered header
-// emits an island marker with no matching registry entry — the toggle renders
-// but never hydrates, on every page (zudolab/zudo-doc#2048). This thin
-// project-source wrapper gives the scanner a local binding to register; it
-// re-wraps the bare (non-island-wrapped) package component unchanged.
-import type { JSX } from "preact";
-import {
-  ThemeToggle as ZudoDocThemeToggle,
-  type ThemeToggleProps,
-} from "@takazudo/zudo-doc/theme-toggle";
-
-export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
-  return <ZudoDocThemeToggle {...props} />;
-}
-ThemeToggle.displayName = "ThemeToggle";
-
-export type { ThemeToggleProps };
-
-export default ThemeToggle;