create-zudo-doc 0.2.17 → 0.2.19

package/dist/features/dynamic-page-transition.d.ts

@@ -2,10 +2,20 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Dynamic page transition feature.
  *
- * When enabled, wires the SPA client-side router (ClientRouterBootstrap
- * island) and the page-loading overlay (PageLoadingOverlay, pure SSR) into
- * body-end-islands, and injects the View-Transitions CSS + page-loading
- * overlay CSS into global.css.
+ * When enabled:
+ * - Sets `enableClientRouter={settings.dynamicPageTransition}` on every
+ *   `<DocLayoutWithDefaults>` render site — the SSR `<ClientRouter />` render
+ *   self-activates the SPA router on the client as a top-level module side
+ *   effect (primary activation path).
+ * - Wires the ClientRouterBootstrap island and the PageLoadingOverlay (pure
+ *   SSR) into body-end-islands — the island is now a redundant fallback;
+ *   PageLoadingOverlay provides the loading spinner UI.
+ * - Injects `@import "@takazudo/zudo-doc/page-loading.css"` at the
+ *   `@slot:global-css:imports` anchor (top of global.css, before rule blocks).
+ * - Injects the `--color-page-loading-overlay` token into `@theme` at the
+ *   `@slot:global-css:theme-tokens` anchor.
+ * - Injects the View-Transitions CSS into global.css at
+ *   `@slot:global-css:feature-styles`.
  *
  * Bug fix (#2265): the page-loading overlay CSS (.page-loading-overlay /
  * .page-loading-spinner / @keyframes page-loading-spin / [data-zd-nav-pending])
@@ -13,6 +23,12 @@ import type { FeatureModule } from "../compose.js";
  * the host global.css but had no corresponding injection for the template.
  * Gating this feature makes both the JS island and the CSS land together.
  *
+ * The page-loading CSS now ships as a package artifact
+ * `@takazudo/zudo-doc/page-loading.css` (Topic A, #2283) — the generator
+ * injects a gated `@import` instead of inline rule bodies. The
+ * `--color-page-loading-overlay` token is defined inline (inside `@theme`) so
+ * it lives alongside the other project tokens and can be overridden per-project.
+ *
  * The ClientRouterBootstrap component lives in
  * templates/features/dynamicPageTransition/files/src/components/ and is
  * byte-identical to the host src/components/client-router-bootstrap.tsx.

package/dist/features/dynamic-page-transition.js

@@ -1,10 +1,20 @@
 /**
  * Dynamic page transition feature.
  *
- * When enabled, wires the SPA client-side router (ClientRouterBootstrap
- * island) and the page-loading overlay (PageLoadingOverlay, pure SSR) into
- * body-end-islands, and injects the View-Transitions CSS + page-loading
- * overlay CSS into global.css.
+ * When enabled:
+ * - Sets `enableClientRouter={settings.dynamicPageTransition}` on every
+ *   `<DocLayoutWithDefaults>` render site — the SSR `<ClientRouter />` render
+ *   self-activates the SPA router on the client as a top-level module side
+ *   effect (primary activation path).
+ * - Wires the ClientRouterBootstrap island and the PageLoadingOverlay (pure
+ *   SSR) into body-end-islands — the island is now a redundant fallback;
+ *   PageLoadingOverlay provides the loading spinner UI.
+ * - Injects `@import "@takazudo/zudo-doc/page-loading.css"` at the
+ *   `@slot:global-css:imports` anchor (top of global.css, before rule blocks).
+ * - Injects the `--color-page-loading-overlay` token into `@theme` at the
+ *   `@slot:global-css:theme-tokens` anchor.
+ * - Injects the View-Transitions CSS into global.css at
+ *   `@slot:global-css:feature-styles`.
  *
  * Bug fix (#2265): the page-loading overlay CSS (.page-loading-overlay /
  * .page-loading-spinner / @keyframes page-loading-spin / [data-zd-nav-pending])
@@ -12,6 +22,12 @@
  * the host global.css but had no corresponding injection for the template.
  * Gating this feature makes both the JS island and the CSS land together.
  *
+ * The page-loading CSS now ships as a package artifact
+ * `@takazudo/zudo-doc/page-loading.css` (Topic A, #2283) — the generator
+ * injects a gated `@import` instead of inline rule bodies. The
+ * `--color-page-loading-overlay` token is defined inline (inside `@theme`) so
+ * it lives alongside the other project tokens and can be overridden per-project.
+ *
  * The ClientRouterBootstrap component lives in
  * templates/features/dynamicPageTransition/files/src/components/ and is
  * byte-identical to the host src/components/client-router-bootstrap.tsx.
@@ -64,7 +80,28 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";`,
         </>
       ) : null}`,
         },
-        // 4. View-Transitions CSS (chrome extraction + cross-fade + reduced motion).
+        // 4. Page-loading CSS import — gated at the top-of-file imports anchor.
+        //    `@import` must precede rule blocks in CSS; the `@slot:global-css:imports`
+        //    anchor sits immediately after the content.css import line so this lands
+        //    in a legal position. The CSS itself (overlay, spinner, keyframes) now
+        //    ships as a package artifact `@takazudo/zudo-doc/page-loading.css`
+        //    (see #2283 — Topic A) instead of being duplicated inline here.
+        {
+            file: "src/styles/global.css",
+            anchor: "/* @slot:global-css:imports */",
+            position: "after",
+            content: `@import "@takazudo/zudo-doc/page-loading.css";`,
+        },
+        // 5. `--color-page-loading-overlay` token — injected inside `@theme`.
+        //    Defined here so each scaffolded project can override it per-project.
+        //    Uses the same `--color-overlay` base token as the dialog backdrops.
+        {
+            file: "src/styles/global.css",
+            anchor: "/* @slot:global-css:theme-tokens */",
+            position: "after",
+            content: `--color-page-loading-overlay: color-mix(in oklch, var(--color-overlay) 60%, transparent);`,
+        },
+        // 6. View-Transitions CSS (chrome extraction + cross-fade + reduced motion).
         //    Injected AFTER `/* @slot:global-css:feature-styles */` in global.css.
         //    These rules are required for SPA page transitions via ClientRouter.
         {
@@ -173,67 +210,6 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";`,
   ::view-transition-new(zfb-sidebar-toggle):only-child {
     animation: none;
   }
-}
-
-/* Page-loading overlay CSS — moved out of PageLoadingOverlay's inline
- * <style> block to avoid the <style>-inside-<body> HTML5 content-model
- * violation flagged by html-validate (same pattern as version-switcher
- * fix in zudolab/zudo-doc#1505; see W2A confirm zudolab/zudo-doc#1543). */
-.page-loading-overlay {
-  position: fixed;
-  inset: 0;
-  /* Full-screen blocking load overlay — modal tier (was a raw z-index:9999).
-     It sits below the transient \`drag\` tier (sidebar-resizer ghost), which is
-     fine: a full page-load overlay and an active pointer-drag never coexist. */
-  z-index: var(--z-index-modal);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: color-mix(in oklch, var(--color-overlay) 60%, transparent);
-  opacity: 0;
-  pointer-events: none;
-  transition: opacity 150ms ease-out;
-}
-
-.page-loading-overlay[data-visible] {
-  opacity: 1;
-}
-
-a[data-zd-nav-pending],
-button[data-zd-nav-pending] {
-  color: var(--color-accent);
-}
-
-.page-loading-spinner {
-  width: 48px;
-  height: 48px;
-  border: 5px solid var(--color-fg, #fff);
-  border-bottom-color: transparent;
-  border-radius: 50%;
-  display: inline-block;
-  box-sizing: border-box;
-  animation: page-loading-spin 1s linear infinite;
-}
-
-@media (min-width: 1024px) {
-  .page-loading-spinner {
-    width: 64px;
-    height: 64px;
-    border-width: 6px;
-  }
-}
-
-@keyframes page-loading-spin {
-  0% { transform: rotate(0deg); }
-  100% { transform: rotate(360deg); }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .page-loading-spinner {
-    animation: none;
-    border-bottom-color: var(--color-fg, #fff);
-    opacity: 0.5;
-  }
 }`,
         },
     ],

package/dist/scaffold.js

@@ -340,7 +340,8 @@ export async function scaffold(choices) {
 }
 function generatePackageJson(choices) {
     // Intentionally absent from scaffolded deps:
-    //   @takazudo/zudo-doc-md-plugins — zero references in generator templates/source
+    //   @takazudo/zudo-doc-md-plugins — private fixture/parity-test asset; not published,
+    //   not for app import. Zero references in generator templates/source.
     const deps = {
         // zfb engine — distributed as published npm packages (the prebuilt binary
         // ships via an optionalDependency of @takazudo/zfb-<platform>); pinned to
@@ -447,11 +448,11 @@ function generatePackageJson(choices) {
         // stability, multi-valued response headers (e.g. multiple Set-Cookie),
         // supplementary-plane CJK reading-time, plus CLI/server/runtime hardening
         // and render perf passes. No consumer-facing / CLI breaking change.
-        "@takazudo/zfb": "0.1.0-next.55",
-        "@takazudo/zfb-runtime": "0.1.0-next.55",
+        "@takazudo/zfb": "0.1.0-next.57",
+        "@takazudo/zfb-runtime": "0.1.0-next.57",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.55",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.57",
         // @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
@@ -463,7 +464,7 @@ function generatePackageJson(choices) {
         // ties this pin to packages/zudo-doc's version, so the lockstep release
         // bumps both together; do not cut a create-zudo-doc release until the
         // matching @takazudo/zudo-doc version (with content.css) is on npm.
-        "@takazudo/zudo-doc": "^0.2.17",
+        "@takazudo/zudo-doc": "^0.2.19",
         // 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
@@ -517,7 +518,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.17";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.19";
         // 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.17",
+  "version": "0.2.19",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/404.tsx

@@ -44,6 +44,7 @@ export default function NotFoundPage(): JSX.Element {
       headerOverride={<HeaderWithDefaults lang={locale} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       <div class="min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl">
         <h1 class="text-display font-bold mb-vsp-md">404</h1>

package/templates/base/pages/index.tsx

@@ -73,6 +73,7 @@ export default function IndexPage(): JSX.Element {
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/")} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       {/* Hero: logo left, title+desc+links right, block centered */}
       <div class="flex justify-center mb-vsp-xl">

package/templates/base/pages/lib/_doc-body-end.tsx

@@ -18,8 +18,14 @@ import { SidebarResizerInit } from "@takazudo/zudo-doc/sidebar-resizer";
 
 /**
  * The `bodyEndComponents` slot content shared by all four doc-route page
- * components: `BodyEndIslands` (modal overlays, client-router bootstrap,
- * image-enlarge) and the optional `SidebarResizerInit` drag handle.
+ * components: `BodyEndIslands` (modal overlays, optional client-router
+ * bootstrap when `dynamicPageTransition` is on, image-enlarge) and the
+ * optional `SidebarResizerInit` drag handle. Whether the client-router
+ * bootstrap island is included depends on `settings.dynamicPageTransition`
+ * (gated inside `BodyEndIslands`). The SSR `<ClientRouter />` mounted by
+ * `DocLayout` self-activates when `enableClientRouter` is `true`; the
+ * island here is redundant for that activation path and kept only for the
+ * `when="load"` hydration slot.
  */
 export function DocBodyEnd(): JSX.Element {
   return (

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

@@ -218,6 +218,7 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
       afterSidebar={<SidebarPrepaint />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<DocBodyEnd />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       {kind === "autoIndex" ? (
         /* Auto-index page: category without an index.mdx.

package/templates/base/src/config/color-scheme-utils.ts

@@ -116,7 +116,7 @@ export function schemeToCssPairs(scheme: ColorScheme): [string, string][] {
   return [
     ["--zd-bg", resolveColor(scheme.background, p, p[0])],
     ["--zd-fg", resolveColor(scheme.foreground, p, p[15])],
-    ["--zd-cursor", resolveColor(scheme.cursor, p, p[6])],
+    ["--zd-cursor", resolveColor(scheme.cursor, p, p[6])], // intentionally inert/vestigial: exposed in the design-token panel but no CSS rule consumes it (no caret-color wiring); mirrors shikiTheme's status
     ["--zd-sel-bg", resolveColor(scheme.selectionBg, p, resolveColor(scheme.background, p, p[0]))],
     ["--zd-sel-fg", resolveColor(scheme.selectionFg, p, resolveColor(scheme.foreground, p, p[15]))],
     ...p.map((color, i) => [`--zd-${i}`, color] as [string, string]),

package/templates/base/src/config/color-schemes.ts

@@ -81,8 +81,8 @@ export const colorSchemes: Record<string, ColorScheme> = {
     selectionBg: 11,
     selectionFg: 10,
     palette: [
-      "#303030", "#dd3131", "#266538", "#a83838",  // p0-3: dark surface, danger, success, warning
-      "#3277c8", "#a35e0f", "#90a1b9", "#7a5218",  // p4-7: info, accent, neutral, secondary
+      "#303030", "#a01515", "#1f5429", "#903030",  // p0-3: dark surface, danger, success, warning — darkened for WCAG AA (#2298)
+      "#174fa0", "#7d470b", "#90a1b9", "#7a5218",  // p4-7: info, accent, neutral, secondary — darkened for WCAG AA (#2298)
       "#6b6b6b", "#e2ddda", "#ece9e9", "#303030",  // p8-11: muted, background, surface, text
       "#5b99dc", "#b89ee7", "#8590a0", "#654516",  // p12-15: accent variant, decorative, hover, muted foreground
     ],

package/templates/base/src/styles/global.css

@@ -42,6 +42,7 @@
    above (line 11); the safelist import above generates the component utilities
    its headings/links/etc. depend on. */
 @import "@takazudo/zudo-doc/content.css";
+/* @slot:global-css:imports */
 
 /* ========================================
  * Tailwind v4 content sources
@@ -269,6 +270,11 @@
   --text-scale-lg:  1.4rem;     /* 22.4px */
   --text-scale-xl:  3rem;       /* 48px */
   --text-scale-2xl: 3.75rem;    /* 60px */
+
+  --default-transition-duration: 150ms; /* consumed by hash-link opacity fade */
+  --zd-transition-slow: 200ms;          /* sidebar transform/visibility and content-band max-width */
+  --zd-transition-slower: 300ms;        /* view-transition fade-in (contentFadeIn animation) */
+  --zd-header-h: 80px;                  /* sticky header height; consumed by scroll-margin-top on [id] anchors */
 }
 
 /* ========================================
@@ -276,7 +282,7 @@
  * ======================================== */
 
 [id] {
-  scroll-margin-top: 80px;
+  scroll-margin-top: var(--zd-header-h);
 }
 
 body {
@@ -580,8 +586,8 @@ pre[class^="syntect-"] .line .highlighted-word {
 @media (min-width: 1024px) {
   #desktop-sidebar {
     transition:
-      transform 200ms ease-in-out,
-      visibility 200ms;
+      transform var(--zd-transition-slow) ease-in-out,
+      visibility var(--zd-transition-slow);
   }
 
   html[data-sidebar-hidden] #desktop-sidebar {
@@ -590,7 +596,7 @@ pre[class^="syntect-"] .line .highlighted-word {
   }
 
   .zd-sidebar-content-wrapper {
-    transition: margin-left 200ms ease-in-out;
+    transition: margin-left var(--zd-transition-slow) ease-in-out;
   }
 
   html[data-sidebar-hidden] .zd-sidebar-content-wrapper {
@@ -604,7 +610,7 @@ pre[class^="syntect-"] .line .highlighted-word {
    * branch in doc-layout.tsx. These rules are unlayered, so they win over
    * the Tailwind `max-w-[clamp(...)]` utility (utilities layer). (#2002) */
   .zd-doc-content-band {
-    transition: max-width 200ms ease-in-out;
+    transition: max-width var(--zd-transition-slow) ease-in-out;
   }
 
   html[data-sidebar-hidden] .zd-doc-content-band {

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

@@ -142,6 +142,7 @@ export function TagDetailPageView({
       breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       <h1 class="text-heading font-bold mb-vsp-xs">{pageTitle}</h1>
       <p class="text-muted mb-vsp-lg">{countText}</p>
@@ -198,6 +199,7 @@ export function TagsIndexPageView({ locale }: { locale: string }): JSX.Element {
       breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       <h1 class="text-heading font-bold mb-vsp-lg">{pageTitle}</h1>
       {!settings.docTags || tags.length === 0 ? (

package/templates/features/dynamicPageTransition/files/src/components/client-router-bootstrap.tsx

@@ -51,6 +51,14 @@ import type { JSX } from "preact";
  * walks page → BodyEndIslands → ClientRouterBootstrap and includes the
  * client-router barrel in the per-island bundle, where the side-effect
  * import above can fire on the client.
+ *
+ * Note: the SSR `<ClientRouter />` mounted by `DocLayout` (via
+ * `enableClientRouter`) self-activates the SPA router when its head meta
+ * tags reach the browser. This host island is therefore a no-op for
+ * router activation — it is kept only for the `when="load"` hydration
+ * slot and bundle inclusion. The actual on/off gate is
+ * `enableClientRouter` on `<DocLayoutWithDefaults>`, set to
+ * `settings.dynamicPageTransition` at every call site.
  */
 function ClientRouterBootstrap(): JSX.Element | null {
   return null;

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

@@ -117,6 +117,7 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`/${locale}/`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       {/* Hero: logo left, title+desc+links right, block centered */}
       <div class="flex justify-center mb-vsp-xl">

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

@@ -73,6 +73,7 @@ export function VersionsPageView({ locale }: { locale: string }): JSX.Element {
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`${prefix}/docs/versions`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
+      enableClientRouter={settings.dynamicPageTransition}
     >
       <VersionsPageContent
         latestHref={latestHref}