create-zudo-doc 0.2.10 → 0.2.11

package/dist/scaffold.js

@@ -350,7 +350,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.10",
+        "@takazudo/zudo-doc": "^0.2.11",
         // 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
@@ -405,7 +405,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.10";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.11";
         // 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.10",
+  "version": "0.2.11",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

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

@@ -717,6 +717,20 @@ pre[class^="syntect-"] .line .highlighted-word {
   }
 }
 
+/* Suppress sidebar geometry transitions during an SPA swap (#2198).
+ * swapRootAttributes wipes data-sidebar-hidden mid-swap, so without this the
+ * sidebar would animate open (attribute absent) and then animate shut again
+ * when the toggle island restores the attribute on zfb:after-swap — a visible
+ * flash + slide. The island sets data-sidebar-no-transition for the swap
+ * window and removes it (double rAF) after restoring the hidden state, so the
+ * wipe/restore apply instantly and a later user toggle still animates. */
+html[data-sidebar-no-transition] #desktop-sidebar,
+html[data-sidebar-no-transition] .zd-sidebar-content-wrapper,
+html[data-sidebar-no-transition] .zd-doc-content-band,
+html[data-sidebar-no-transition] .zd-desktop-sidebar-toggle {
+  transition: none !important;
+}
+
 /* ── Find-in-page highlight (W7A: unconditional — Tauri feature gates at runtime) ── */
 .find-match {
   background-color: color-mix(in oklch, var(--color-warning) 40%, transparent);
@@ -906,6 +920,10 @@ dialog.zd-mermaid-dialog::backdrop {
 
 .zd-mermaid-viewport[data-pan-active] {
   cursor: grab;
+  /* In pan mode a drag should pan, not select diagram text. Scoped to
+   * [data-pan-active] so text stays selectable when pan mode is off. */
+  -webkit-user-select: none;
+  user-select: none;
 }
 
 .zd-mermaid-viewport[data-pan-active]:active {
@@ -946,15 +964,14 @@ dialog.zd-mermaid-dialog::backdrop {
   overflow: visible;
 }
 
-/* Toolbar — bottom-center pill of zoom/pan controls. */
+/* Toolbar — bottom-right pill of zoom/pan controls (2× sized buttons). */
 .zd-mermaid-toolbar {
   position: absolute;
   bottom: var(--spacing-image-overlay-inset);
-  left: 50%;
-  transform: translateX(-50%);
+  right: var(--spacing-image-overlay-inset);
   display: flex;
-  gap: var(--spacing-hsp-2xs);
-  padding: var(--spacing-hsp-2xs);
+  gap: var(--spacing-hsp-xs);
+  padding: var(--spacing-hsp-xs);
   border: 1px solid var(--color-muted);
   border-radius: var(--radius-DEFAULT);
   background: color-mix(in oklch, var(--color-surface) 92%, transparent);
@@ -965,8 +982,8 @@ dialog.zd-mermaid-dialog::backdrop {
   display: flex;
   align-items: center;
   justify-content: center;
-  width: var(--spacing-icon-lg);
-  height: var(--spacing-icon-lg);
+  width: calc(var(--spacing-icon-lg) * 2);
+  height: calc(var(--spacing-icon-lg) * 2);
   padding: var(--spacing-vsp-2xs);
   border: none;
   border-radius: var(--radius-DEFAULT);
@@ -993,8 +1010,8 @@ dialog.zd-mermaid-dialog::backdrop {
 }
 
 .zd-mermaid-tool-btn > svg {
-  width: var(--spacing-icon-md);
-  height: var(--spacing-icon-md);
+  width: calc(var(--spacing-icon-md) * 2);
+  height: calc(var(--spacing-icon-md) * 2);
 }
 
 /* @slot:global-css:feature-styles */

package/templates/features/sidebarToggle/files/src/components/desktop-sidebar-toggle.tsx

@@ -22,6 +22,85 @@ function setDataAttribute(isVisible: boolean) {
   }
 }
 
+// SPA-navigation guard for the desktop sidebar's hidden-state (#2198).
+//
+// zfb's Strategy-B client router wipes EVERY <html> attribute during the body
+// swap (swapRootAttributes re-adds only NON_OVERRIDABLE_ZFB_ATTRS plus the
+// incoming SSR document's attributes), so the persisted `data-sidebar-hidden`
+// runtime value is lost on every navigation, and the pre-paint inline script
+// does not re-run on SPA hops. Left alone, the freshly-rendered sidebar paints
+// visible and then animates shut when the value is restored — the flash + slide.
+//
+// These listeners MUST live at module scope, NOT in the island's useEffect:
+// zfb-runtime (>= 0.1.0-next.51) calls unmountIslands() BEFORE the swap and
+// before firing AFTER_NAVIGATE_EVENT, so a useEffect-registered listener is torn
+// down (effect cleanup) before the swap and never sees the after-swap event —
+// the restore would never run (#2198 verification). Registering once on
+// `document` at bundle load — the same lifecycle-independent pattern as
+// client-router-bootstrap.tsx — keeps the guard alive across island
+// unmount/remount. SSR-safe: no-ops when `document` is undefined.
+//
+// Strategy: on BEFORE_NAVIGATE_EVENT, record whether the sidebar was hidden and
+// set a transient `data-sidebar-no-transition` marker (global.css zeroes the
+// sidebar/wrapper/band/toggle transitions). The swap then wipes BOTH the marker
+// and data-sidebar-hidden. On AFTER_NAVIGATE_EVENT (swap done → the live <html>
+// is no longer wiped) RE-SET the marker, then re-add data-sidebar-hidden in the
+// same synchronous batch, so the hidden geometry snaps in with transitions
+// suppressed (no slide, no open frame). Remove the marker on a double rAF
+// afterward so a later user toggle still animates.
+let spaNavGuardRegistered = false;
+function registerSidebarSpaNavGuard() {
+  if (typeof document === 'undefined' || spaNavGuardRegistered) return;
+  spaNavGuardRegistered = true;
+
+  let wasHidden = false;
+  let swapToken = 0;
+  // Long enough to outlast the View-Transition swap pipeline on slow
+  // machines/CI; short enough that an aborted nav self-heals quickly. Only a
+  // safety net for a nav that never reaches `restore` (aborted/superseded).
+  const STUCK_MARKER_FALLBACK_MS = 1500;
+
+  const capture = () => {
+    wasHidden = document.documentElement.hasAttribute('data-sidebar-hidden');
+    document.documentElement.setAttribute('data-sidebar-no-transition', '');
+    const token = ++swapToken;
+    window.setTimeout(() => {
+      if (token === swapToken) {
+        document.documentElement.removeAttribute('data-sidebar-no-transition');
+      }
+    }, STUCK_MARKER_FALLBACK_MS);
+  };
+
+  const restore = () => {
+    // Marker first, then the attribute, in one synchronous batch — so the
+    // hidden geometry is restored with transitions off (the swap already wiped
+    // the capture-time marker, so re-setting it here on the post-swap <html> is
+    // what actually suppresses the animation).
+    document.documentElement.setAttribute('data-sidebar-no-transition', '');
+    if (wasHidden) {
+      document.documentElement.setAttribute('data-sidebar-hidden', '');
+    }
+    // Drop the marker only after the restored state is committed. A single rAF
+    // can coincide with the restore's style recalc and animate it, so defer one
+    // extra frame. The token bump no-ops capture's safety-net for this swap.
+    const token = ++swapToken;
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        if (token === swapToken) {
+          document.documentElement.removeAttribute('data-sidebar-no-transition');
+        }
+      });
+    });
+  };
+
+  document.addEventListener(BEFORE_NAVIGATE_EVENT, capture);
+  document.addEventListener(AFTER_NAVIGATE_EVENT, restore);
+}
+
+// Register at module load (browser-only via the guard) so the listeners exist
+// before the first navigation and survive island unmount/remount.
+registerSidebarSpaNavGuard();
+
 export default function DesktopSidebarToggle() {
   // Initial state must match server render (always `true`) to avoid a
   // hydration mismatch when the persisted preference is "hidden". The
@@ -66,36 +145,10 @@ export default function DesktopSidebarToggle() {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // Re-apply data-sidebar-hidden to <html> after every SPA nav.
-  // zfb's swapRootAttributes wipes all non-preserved <html> attributes on
-  // each navigation (data-sidebar-hidden is not in NON_OVERRIDABLE_ZFB_ATTRS),
-  // and the pre-paint inline script does not re-run on SPA nav. Since this
-  // island is persisted (data-zfb-transition-persist), this listener stays
-  // registered across SPA swaps.
-  //
-  // Strategy: capture the attribute presence just before the swap
-  // (BEFORE_NAVIGATE_EVENT fires before swapRootAttributes runs), then
-  // restore it once the swap completes (AFTER_NAVIGATE_EVENT). This is
-  // authoritative regardless of how the attribute was set (toggle click,
-  // localStorage, or external mutation). (#1551, #1552 B10)
-  useEffect(() => {
-    let wasHidden = false;
-    const capture = () => {
-      wasHidden = document.documentElement.hasAttribute('data-sidebar-hidden');
-    };
-    const restore = () => {
-      if (wasHidden) {
-        document.documentElement.setAttribute('data-sidebar-hidden', '');
-      }
-      // If not hidden, swapRootAttributes already cleared it — nothing to do.
-    };
-    document.addEventListener(BEFORE_NAVIGATE_EVENT, capture);
-    document.addEventListener(AFTER_NAVIGATE_EVENT, restore);
-    return () => {
-      document.removeEventListener(BEFORE_NAVIGATE_EVENT, capture);
-      document.removeEventListener(AFTER_NAVIGATE_EVENT, restore);
-    };
-  }, []);
+  // The SPA-navigation flash guard (data-sidebar-hidden preservation +
+  // transition suppression) is NOT registered here. It must outlive this
+  // island's mount/unmount, so it lives at module scope — see
+  // registerSidebarSpaNavGuard() above. (#2198)
 
   return (
     <button