From a5156998c089cef18e20e200932413f259f6ba70 Mon Sep 17 00:00:00 2001
From: ubay1 <tomdelonge976@gmail.com>
Date: Mon, 27 Jul 2026 14:31:51 +0700
Subject: [PATCH 1/2] add component ClientLink for SPA navigation for generator
 web

---
 .gitignore                                    |   5 +
 src/generators/web/README.md                  |  38 ++++
 .../web/ui/components/ClientLink/index.jsx    | 171 ++++++++++++++++++
 .../web/ui/components/SideBar/index.jsx       |   5 +-
 4 files changed, 217 insertions(+), 2 deletions(-)
 create mode 100644 src/generators/web/ui/components/ClientLink/index.jsx
diff --git a/.gitignore b/.gitignore
index ac08a4ba..862ff8a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,8 @@ node
 # Playwright
 playwright-report/
 test-results/
+
+# Local documentation (ignored)
+LOCAL_LINK_GUIDE.md
+WEB_GENERATOR_GUIDE.md
+CLIENT_LINK_GUIDE.md
diff --git a/src/generators/web/README.md b/src/generators/web/README.md
index 17f8e138..7054f0af 100644
--- a/src/generators/web/README.md
+++ b/src/generators/web/README.md
@@ -128,3 +128,41 @@ Since the template supports arbitrary JS expressions, you can use conditionals a
   ${importMap}
 </script>
 ```
+
+### Client-Side SPA Navigation (`ClientLink` & `navigate`)
+
+`doc-kit` provides a built-in zero-reload navigation solution for static web output without requiring browser storage (`sessionStorage`/`localStorage`).
+
+#### Features
+- **Zero-Reload Navigation**: Intercepts internal link clicks (`<a>`), fetches target page HTML in the background, and updates the `#root` container.
+- **Scroll Position Preservation**: Retains the sidebar (`<aside>`) scroll position in module memory across page transitions without resetting or requiring storage APIs.
+- **View Transitions API Integration**: Automatically utilizes `document.startViewTransition()` if supported for smooth page crossfades.
+- **TOC & Hash Link Support**: Smoothly handles in-page anchor links (`#heading-id`) and Table of Contents (TOC) navigation via `scrollIntoView`.
+- **History & Popstate Handling**: Listens for `popstate` events to support browser Back and Forward buttons seamlessly.
+
+#### Usage
+
+##### 1. Using `ClientLink` in Custom Components
+Import `ClientLink` and pass it as the `as` prop to `<SideBar>` or use it directly as a drop-in replacement for `<a>`:
+
+```jsx
+import ClientLink, { navigate } from '@node-core/doc-kit/src/generators/web/ui/components/ClientLink/index.jsx';
+
+export default ({ metadata }) => (
+  <SideBar
+    pathname={`/learn${metadata.path.replace('/index', '')}`}
+    groups={sidebar}
+    onSelect={navigate}
+    as={ClientLink}
+    title="Navigation"
+  />
+);
+```
+
+##### 2. Programmatic Navigation with `navigate()`
+```javascript
+import { navigate } from '@node-core/doc-kit/src/generators/web/ui/components/ClientLink/index.jsx';
+
+// Navigate programmatically without a full page reload
+navigate('/learn/getting-started.html');
+```
diff --git a/src/generators/web/ui/components/ClientLink/index.jsx b/src/generators/web/ui/components/ClientLink/index.jsx
new file mode 100644
index 00000000..af97fa93
--- /dev/null
+++ b/src/generators/web/ui/components/ClientLink/index.jsx
@@ -0,0 +1,171 @@
+/**
+ * ClientLink – zero-reload navigation for doc-kit static sites.
+ *
+ * How it works:
+ *   1. Intercepts clicks on internal `<a>` links (via the component AND
+ *      a global event-delegation listener so links inside swapped DOM
+ *      keep working).
+ *   2. Fetches the target page's HTML in the background.
+ *   3. Replaces `#root` innerHTML with the new page's `#root` content,
+ *      preserving the already-loaded CSS / JS assets in `<head>`.
+ *   4. Saves & restores the sidebar (`<aside>`) scroll position in a
+ *      plain JS variable – no sessionStorage / localStorage needed.
+ *   5. Handles browser Back / Forward buttons via `popstate`.
+ *
+ * @module ClientLink
+ */
+
+// ---------------------------------------------------------------------------
+// State kept in module scope (survives DOM replacements, no storage needed)
+// ---------------------------------------------------------------------------
+let sidebarScrollTop = 0;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when `href` points to an internal page that can be navigated
+ * client-side (same-origin, not a hash-only link, not a special protocol).
+ *
+ * @param {string | undefined | null} href
+ * @returns {boolean}
+ */
+const isInternalLink = href => {
+  if (!href) {
+    return false;
+  }
+  if (/^(https?:|mailto:|tel:|#)/.test(href)) {
+    return false;
+  }
+  return true;
+};
+
+/**
+ * Returns true when the click event carries modifier keys that signal
+ * "open in new tab / window" – we should let the browser handle those.
+ */
+const hasModifier = e =>
+  e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0;
+
+// ---------------------------------------------------------------------------
+// Core navigation function
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform client-side navigation to `url` without a full page reload.
+ *
+ * @param {string}  url
+ * @param {boolean} [isPopState=false] – true when triggered by Back/Forward
+ */
+export const navigate = async (url, isPopState = false) => {
+  // 1. Save sidebar scroll position BEFORE touching the DOM
+  const sidebar = document.querySelector('aside');
+  if (sidebar) {
+    sidebarScrollTop = sidebar.scrollTop;
+  }
+
+  // 2. Push browser history (skip for popstate – browser already did it)
+  if (!isPopState) {
+    window.history.pushState({}, '', url);
+  }
+
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const html = await response.text();
+    const newDoc = new DOMParser().parseFromString(html, 'text/html');
+
+    const currentRoot = document.getElementById('root');
+    const newRoot = newDoc.getElementById('root');
+
+    if (currentRoot && newRoot) {
+      // 3. Swap the entire #root – all CSS module classes are preserved
+      //    because they come straight from the server-rendered HTML and
+      //    the shared styles.css is already loaded in <head>.
+      const updateDOM = () => {
+        currentRoot.innerHTML = newRoot.innerHTML;
+        document.title = newDoc.title;
+
+        // 4. Restore sidebar scroll position
+        const newSidebar = document.querySelector('aside');
+        if (newSidebar) {
+          newSidebar.scrollTop = sidebarScrollTop;
+        }
+
+        // 5. Scroll to hash target if URL contains a hash, otherwise to top
+        const hash = new URL(url, window.location.origin).hash;
+        if (hash) {
+          const target = document.getElementById(hash.slice(1));
+          if (target) {
+            target.scrollIntoView({ behavior: 'smooth' });
+          }
+        } else {
+          window.scrollTo({ top: 0, behavior: 'instant' });
+        }
+      };
+
+      // Use View Transitions API for a smooth crossfade when available
+      if (document.startViewTransition) {
+        document.startViewTransition(updateDOM);
+      } else {
+        updateDOM();
+      }
+    } else {
+      // Fallback: full page navigation
+      window.location.href = url;
+    }
+  } catch {
+    window.location.href = url;
+  }
+};
+
+// Global event delegation (attached once, survives any DOM replacement)
+if (typeof window !== 'undefined' && !window.__dockit_client_nav) {
+  window.__dockit_client_nav = true;
+
+  // Handle clicks on ANY <a> inside the page – even ones injected via
+  // innerHTML replacement – so navigation keeps working after a swap.
+  document.addEventListener('click', e => {
+    const anchor = e.target.closest('a[href]');
+    if (!anchor) {
+      return;
+    }
+
+    const href = anchor.getAttribute('href');
+    if (hasModifier(e)) {
+      return;
+    }
+
+    // Handle hash-only links (#heading-id) manually because native hash
+    // navigation can break after innerHTML swap of #root
+    if (href && href.startsWith('#')) {
+      const target = document.getElementById(href.slice(1));
+      if (target) {
+        e.preventDefault();
+        target.scrollIntoView({ behavior: 'smooth' });
+        window.history.pushState({}, '', href);
+      }
+      return;
+    }
+
+    if (!isInternalLink(href)) {
+      return;
+    }
+
+    e.preventDefault();
+    navigate(href);
+  });
+
+  // Handle browser Back / Forward buttons
+  window.addEventListener('popstate', () => {
+    navigate(window.location.href, true);
+  });
+}
+
+export default function ClientLink({ children, ...props }) {
+  return <a {...props}>{children}</a>;
+}
diff --git a/src/generators/web/ui/components/SideBar/index.jsx b/src/generators/web/ui/components/SideBar/index.jsx
index 2df4e200..f5cbb3d2 100644
--- a/src/generators/web/ui/components/SideBar/index.jsx
+++ b/src/generators/web/ui/components/SideBar/index.jsx
@@ -3,6 +3,7 @@ import SideBar from '@node-core/ui-components/Containers/Sidebar';
 
 import styles from './index.module.css';
 import { relativeOrAbsolute } from '../../utils/relativeOrAbsolute.mjs';
+import ClientLink, { navigate } from '../ClientLink';
 
 import { project, version, versions, pages } from '#theme/config';
 
@@ -17,7 +18,7 @@ const getMajorVersion = v => parseInt(String(v).match(/\d+/)?.[0] ?? '0', 10);
  * Redirect to a URL
  * @param {string} url URL
  */
-const redirect = url => (window.location.href = url);
+const redirect = url => navigate(url);
 
 /**
  * Sidebar component for MDX documentation with version selection and page navigation
@@ -49,7 +50,7 @@ export default ({ metadata }) => {
       pathname={`${metadata.basename}.html`}
       groups={[{ groupName: 'API Documentation', items }]}
       onSelect={redirect}
-      as={props => <a {...props} rel="prefetch" />}
+      as={ClientLink}
       title="Navigation"
     >
       <div>

From b091c5f4452be7ec5c55e22c28b9322fdcb93ad3 Mon Sep 17 00:00:00 2001
From: ubay1 <tomdelonge976@gmail.com>
Date: Mon, 27 Jul 2026 21:28:38 +0700
Subject: [PATCH 2/2] feat(web): implement dynamic Preact re-hydration in
 ClientLink for SPA navigation: Replace hacky legacy DOM query
 re-initialization functions with native Preact dynamic hydration. Key
 changes: - Dynamically import the target page's entrypoint module script
 after swapping #root via innerHTML. - Append a timestamp query parameter to
 bypass browser ES module evaluation cache, ensuring Preact executes hydrate()
 on every transition. - Automatically re-attach all synthetic React/Preact
 event listeners (CodeBox copy buttons, tabs) without storage dependencies. -
 Remove obsolete legacy functions and translate internal comments to English.
 - Update web generator documentation (README.md).

---
 src/generators/web/README.md                  |  1 +
 .../web/ui/components/ClientLink/index.jsx    | 38 +++++++++++++++++--
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/src/generators/web/README.md b/src/generators/web/README.md
index 7054f0af..445cc2ae 100644
--- a/src/generators/web/README.md
+++ b/src/generators/web/README.md
@@ -139,6 +139,7 @@ Since the template supports arbitrary JS expressions, you can use conditionals a
 - **View Transitions API Integration**: Automatically utilizes `document.startViewTransition()` if supported for smooth page crossfades.
 - **TOC & Hash Link Support**: Smoothly handles in-page anchor links (`#heading-id`) and Table of Contents (TOC) navigation via `scrollIntoView`.
 - **History & Popstate Handling**: Listens for `popstate` events to support browser Back and Forward buttons seamlessly.
+- **Dynamic Preact Re-Hydration**: Automatically identifies and imports the new page's entrypoint module script (`<script type="module" src="...">`) with a timestamp query parameter after swapping `#root`. This triggers Preact's `hydrate()` on the freshly injected DOM, seamlessly re-attaching all synthetic event listeners (e.g., `CodeBox` copy buttons, tab switchers, interactive pickers) without any manual DOM manipulation or storage dependencies.
 
 #### Usage
 
diff --git a/src/generators/web/ui/components/ClientLink/index.jsx b/src/generators/web/ui/components/ClientLink/index.jsx
index af97fa93..8a5683be 100644
--- a/src/generators/web/ui/components/ClientLink/index.jsx
+++ b/src/generators/web/ui/components/ClientLink/index.jsx
@@ -48,6 +48,26 @@ const isInternalLink = href => {
 const hasModifier = e =>
   e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0;
 
+/**
+ * Re-import and execute the new page's entrypoint module script after a DOM swap.
+ * By appending a timestamp query parameter, we bypass the browser's ES module
+ * evaluation cache, ensuring Preact runs `hydrate()` on the freshly injected `#root`.
+ * This natively re-attaches all synthetic event listeners (such as CodeBox copy
+ * buttons or CodeTabs switchers) without requiring browser storage or DOM hacks.
+ */
+function reinitPageFeatures(newDoc) {
+  const newScript = newDoc.querySelector('body script[type="module"][src]');
+  if (newScript && newScript.getAttribute('src')) {
+    const scriptUrl = new URL(
+      newScript.getAttribute('src'),
+      window.location.origin
+    );
+    // Bypass module evaluation cache so Preact re-hydrates on every navigation
+    scriptUrl.searchParams.set('t', Date.now());
+    import(/* @vite-ignore */ scriptUrl.toString()).catch(() => {});
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Core navigation function
 // ---------------------------------------------------------------------------
@@ -96,7 +116,11 @@ export const navigate = async (url, isPopState = false) => {
           newSidebar.scrollTop = sidebarScrollTop;
         }
 
-        // 5. Scroll to hash target if URL contains a hash, otherwise to top
+        // 5. Re-import the new page's module script to trigger Preact hydration
+        //    on the newly swapped DOM nodes (CodeBox copy buttons, tabs, etc.).
+        reinitPageFeatures(newDoc);
+
+        // 6. Scroll to hash target if URL contains a hash, otherwise to top
         const hash = new URL(url, window.location.origin).hash;
         if (hash) {
           const target = document.getElementById(hash.slice(1));
@@ -140,8 +164,16 @@ if (typeof window !== 'undefined' && !window.__dockit_client_nav) {
       return;
     }
 
-    // Handle hash-only links (#heading-id) manually because native hash
-    // navigation can break after innerHTML swap of #root
+    // ====== PICKER-HEADER LINKS ======
+    // .picker-header > a toggles legacy dropdown menus.
+    // Never intercept these – let the attached click listener handle them.
+    if (anchor.closest('.picker-header')) {
+      return;
+    }
+
+    // ====== HASH-ONLY LINKS ======
+    // Handle #heading-id links manually because native hash navigation can
+    // break after innerHTML swap of #root (the element may have moved).
     if (href && href.startsWith('#')) {
       const target = document.getElementById(href.slice(1));
       if (target) {
