@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.146

package/src/client/router.ts

@@ -18,7 +18,7 @@ import {
   ServerErrorResponse,
   VersionSkewError,
 } from './rsc-fetch.js';
-import { setHardNavigating } from './navigation-root.js';
+import { setHardNavigating, supersedeNavigationTransitions } from './navigation-root.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -150,6 +150,14 @@ export interface RouterDeps {
    * unavailable.
    */
   navigationNavigate?: (url: string, replace: boolean) => void;
+
+  /**
+   * Scroll the element matching a URL #fragment into view. Returns true
+   * when a matching element was found and scrolled. When absent or false,
+   * the router falls back to scroll-to-top on forward navigation — same
+   * as a full page load with an unknown fragment landing at the top.
+   */
+  scrollToHash?: (hash: string) => boolean;
 }
 
 export interface RouterInstance {
@@ -228,13 +236,25 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   let currentNavAbort: AbortController | null = null;
 
   /**
-   * Create a new AbortController for a navigation, aborting any
+   * Create a new AbortController for a navigation, superseding any
    * previous in-flight navigation. Optionally links to an external
    * signal (e.g., from the Navigation API's NavigateEvent.signal).
+   *
+   * Superseding is one operation with three parts:
+   * 1. Abort the previous navigation's fetch.
+   * 2. Invalidate its render transition so a response that already
+   *    arrived can't commit a stale tree (NavigationRoot's transId guard).
+   * 3. Resolve its Navigation API deferred — the superseded navigation's
+   *    finally block is staleness-guarded (see TIM-1034) and no longer
+   *    cleans up after itself, so the browser's native loading state for
+   *    the dead navigation is cleared here.
    */
   function createNavAbort(externalSignal?: AbortSignal): AbortController {
-    // Abort previous navigation's fetch
-    currentNavAbort?.abort();
+    if (currentNavAbort) {
+      currentNavAbort.abort();
+      supersedeNavigationTransitions();
+      deps.completeRouterNavigation?.();
+    }
     const controller = new AbortController();
     currentNavAbort = controller;
 
@@ -445,13 +465,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     });
   }
 
+  /**
+   * Scroll to the element matching the URL #fragment after paint, falling
+   * back to scroll-to-top when no element matches (matching full-page-load
+   * behavior for an unknown fragment). Used by forward navigation to a
+   * hash-bearing URL (TIM-1035).
+   */
+  function scrollToHashAfterPaint(hash: string): void {
+    afterPaint(() => {
+      if (deps.scrollToHash?.(hash) !== true) {
+        deps.scrollTo(0, 0);
+      }
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
   /**
    * Core navigation logic shared between the transition and fallback paths.
    * Fetches the RSC payload, updates all state, and returns the result.
    */
   async function performNavigationFetch(
     url: string,
-    options: { replace: boolean; signal?: AbortSignal; skipHistory?: boolean }
+    options: { replace: boolean; commitUrl?: string; signal?: AbortSignal; skipHistory?: boolean }
   ): Promise<FetchResult & { navState: NavigationState }> {
     // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
     // fields — normalize to null for FetchResult compatibility.
@@ -480,14 +515,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     // Update the browser history — skip when the Navigation API has already
     // updated the URL via event.intercept() (external navigations).
+    // The committed URL keeps the #fragment (commitUrl) even though the
+    // fetch/history-stack URL is hash-less (TIM-1035).
     if (!options.skipHistory) {
+      const commitUrl = options.commitUrl ?? url;
       // Set the router-navigating flag so the Navigation API's navigate
       // listener doesn't double-intercept this pushState/replaceState.
       deps.setRouterNavigating?.(true);
       if (options.replace) {
-        deps.replaceState({ timber: true, scrollY: 0 }, '', url);
+        deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);
       } else {
-        deps.pushState({ timber: true, scrollY: 0 }, '', url);
+        deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);
       }
       deps.setRouterNavigating?.(false);
     }
@@ -512,6 +550,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const externalSignal = options._signal as AbortSignal | undefined;
     const skipHistory = options._skipHistory === true;
 
+    // Split the #fragment off the navigation URL (TIM-1035). The full URL
+    // (with hash) is committed to the address bar; the hash-less URL is used
+    // for the RSC fetch (fragments are client-only — keeping it would also
+    // swallow the ?_rsc cache-bust param into the fragment) and for
+    // history-stack/prefetch keys (popstate lookups use pathname + search).
+    const hashIndex = url.indexOf('#');
+    const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+
     // Create an abort controller for this navigation. Links to the external
     // signal (Navigation API's event.signal) when provided.
     const navAbort = createNavAbort(externalSignal);
@@ -545,9 +592,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, url);
 
     try {
-      const { headElements } = await renderViaTransition(url, () =>
-        performNavigationFetch(url, {
+      const { headElements } = await renderViaTransition(fetchUrl, () =>
+        performNavigationFetch(fetchUrl, {
           replace,
+          commitUrl: url,
           signal: navAbort.signal,
           skipHistory: effectiveSkipHistory,
         })
@@ -559,10 +607,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Notify nuqs adapter (and any other listeners) that navigation completed.
       window.dispatchEvent(new Event('timber:navigation-end'));
 
-      // Scroll-to-top on forward navigation, or restore captured position
-      // for scroll={false}. React's render() on the document root can reset
-      // scroll during DOM reconciliation, so all scroll must be actively managed.
-      restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+      // Scroll-to-top on forward navigation, scroll to the #fragment target
+      // when the URL has one, or restore captured position for scroll={false}.
+      // React's render() on the document root can reset scroll during DOM
+      // reconciliation, so all scroll must be actively managed.
+      if (scroll && hash) {
+        scrollToHashAfterPaint(hash);
+      } else {
+        restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+      }
     } catch (error) {
       // Version skew — server has been redeployed. Full page reload
       // so the browser fetches the new bundle. See TIM-446.
@@ -574,8 +627,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Server-side redirect during RSC fetch → soft router navigation.
       // The redirect navigate will push/replace its own URL.
       if (error instanceof RedirectError) {
-        setPending(false);
-        deps.completeRouterNavigation?.();
+        // Drop the redirect if a newer navigation superseded this one
+        // while the redirect response was in flight — the newer
+        // navigation wins, same as the stale-transition guard.
+        if (currentNavAbort !== navAbort) return;
+        // The recursive navigate() supersedes this one via createNavAbort,
+        // which also resolves this navigation's Navigation API deferred.
         await navigate(error.redirectUrl, { replace: true });
         return;
       }
@@ -597,19 +654,27 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       if (isAbortError(error)) return;
       throw error;
     } finally {
-      // Clear the abort controller so we don't abort a completed navigation
-      // when the next one starts. In dev mode, the RSC body stream stays
-      // open after data arrives (React's Flight client waits for debug rows).
-      // Aborting a "completed" navigation kills the open stream reader →
-      // "BodyStreamBuffer was aborted". By clearing the controller here,
-      // createNavAbort() becomes a no-op for completed navigations.
+      // Staleness guard (TIM-1034): only clean up when this navigation
+      // still owns the abort controller. When a newer navigation
+      // superseded this one, createNavAbort() already replaced
+      // currentNavAbort — running setPending(false) /
+      // completeRouterNavigation() here would clear the NEWER
+      // navigation's pending state and resolve its Navigation API
+      // deferred. The superseding navigation resolved OUR deferred in
+      // createNavAbort().
       if (currentNavAbort === navAbort) {
+        // Clear the abort controller so we don't abort a completed
+        // navigation when the next one starts. In dev mode, the RSC body
+        // stream stays open after data arrives (React's Flight client
+        // waits for debug rows). Aborting a "completed" navigation kills
+        // the open stream reader → "BodyStreamBuffer was aborted".
         currentNavAbort = null;
+        setPending(false);
+        // Resolve the Navigation API deferred — clears the browser's
+        // native loading state (tab spinner) at the same time as the
+        // TopLoader.
+        deps.completeRouterNavigation?.();
       }
-      setPending(false);
-      // Resolve the Navigation API deferred — clears the browser's native
-      // loading state (tab spinner) at the same time as the TopLoader.
-      deps.completeRouterNavigation?.();
     }
   }
 
@@ -640,11 +705,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       if (isAbortError(error)) return;
       throw error;
     } finally {
+      // Staleness guard (TIM-1034) — see navigate()'s finally block.
       if (currentNavAbort === navAbort) {
         currentNavAbort = null;
+        setPending(false);
+        deps.completeRouterNavigation?.();
       }
-      setPending(false);
-      deps.completeRouterNavigation?.();
     }
   }
 
@@ -659,7 +725,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const entry = historyStack.get(url);
 
     if (entry && entry.payload !== null) {
-      // Replay cached payload — no server roundtrip
+      // Replay cached payload — no server roundtrip.
+      //
+      // A forward navigation may still be in flight (back pressed while a
+      // slow RSC fetch was pending). createNavAbort() supersedes it: aborts
+      // its fetch and invalidates its render transition so the stale
+      // forward payload can't commit over this replay (TIM-1022). The
+      // replay itself is synchronous — nothing to abort later — so the
+      // controller is cleared immediately, and any pending state left by
+      // the superseded navigation is reset.
+      createNavAbort(externalSignal);
+      currentNavAbort = null;
+      setPending(false);
       const navState = updateNavigationState(entry.params, url);
       renderPayload(entry.payload, navState);
       applyHead(entry.headElements);
@@ -687,10 +764,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         if (isAbortError(error)) return;
         throw error;
       } finally {
+        // Staleness guard (TIM-1034) — see navigate()'s finally block.
         if (currentNavAbort === navAbort) {
           currentNavAbort = null;
+          setPending(false);
         }
-        setPending(false);
       }
     }
   }

package/src/client/rsc-fetch.ts

@@ -14,6 +14,7 @@
 import type { SegmentInfo } from './segment-cache';
 import type { HeadElement } from './head';
 import type { RouterDeps } from './router';
+import { decodeHeadHeader, HEAD_HEADER } from '../shared/head-header.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -148,14 +149,13 @@ function warnMalformedHeader(headerName: string, raw: string): void {
  * Returns null if the header is missing or malformed.
  */
 export function extractHeadElements(response: Response): HeadElement[] | null {
-  const header = response.headers.get('X-Timber-Head');
+  const header = response.headers.get(HEAD_HEADER);
   if (!header) return null;
-  try {
-    return JSON.parse(decodeURIComponent(header));
-  } catch {
-    warnMalformedHeader('X-Timber-Head', header);
-    return null;
+  const decoded = decodeHeadHeader(header);
+  if (decoded === null) {
+    warnMalformedHeader(HEAD_HEADER, header);
   }
+  return decoded as HeadElement[] | null;
 }
 
 /**

package/src/dev-tools/404-page.ts

@@ -16,6 +16,7 @@
 import type { SegmentNode } from '../routing/types.js';
 import { collectLeafRoutes } from '../routing/walkers.js';
 import { escapeHtml } from '../server/utils/escape-html.js';
+import { renderDevPageShell, type DevErrorHmrOptions } from './dev-page-shell.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -112,23 +113,20 @@ const esc = escapeHtml;
 /**
  * Generate a dev-mode 404 page with route listing and suggestions.
  *
- * Returns an HTML string for a self-contained error page.
+ * Returns an HTML string for a self-contained error page. `hmrOptions`
+ * carries the resolved Vite HMR connection options (including the WS token
+ * Vite 8 requires on browser upgrades) so the auto-reload script can
+ * actually connect (TIM-1067, B33).
  */
-export function generateDev404Page(requestedPath: string, routes: RouteInfo[]): string {
+export function generateDev404Page(
+  requestedPath: string,
+  routes: RouteInfo[],
+  hmrOptions?: DevErrorHmrOptions
+): string {
   const suggestions = findSimilarRoutes(requestedPath, routes);
   const isEmpty = routes.length === 0;
 
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>404 — ${esc(requestedPath)} | timber.js</title>
-  <style>${CSS}</style>
-</head>
-<body>
-  <div class="container">
-    <header class="header">
+  const bodyHtml = `<header class="header">
       <div class="badge">404 Not Found</div>
       <h1 class="message">No route matches <code>${esc(requestedPath)}</code></h1>
     </header>
@@ -169,105 +167,38 @@ export function generateDev404Page(requestedPath: string, routes: RouteInfo[]):
         </ul>
       </div>`
         : ''
-    }
-
-    <footer class="footer">
-      <span class="timber-logo">🪵 timber.js</span>
-      <span class="footer-hint">Add or edit routes and this page will reload automatically.</span>
-    </footer>
-  </div>
-
-  <script>
-    // Auto-reload when Vite HMR fires (route added, file changed, etc.)
-    (function() {
-      try {
-        const ws = new WebSocket('ws://' + location.host, 'vite-hmr');
-        ws.addEventListener('message', function(e) {
-          try {
-            const data = JSON.parse(e.data);
-            if (data.type === 'full-reload' || data.type === 'update') {
-              location.reload();
-            }
-          } catch {}
-        });
-      } catch {}
-    })();
-  </script>
-</body>
-</html>`;
+    }`;
+
+  return renderDevPageShell({
+    title: `404 — ${requestedPath} | timber.js`,
+    extraCss: NOT_FOUND_CSS,
+    bodyHtml,
+    footerHint: 'Add or edit routes and this page will reload automatically.',
+    hmrOptions,
+  });
 }
 
-// ─── CSS ────────────────────────────────────────────────────────────────────
+// ─── Page-Specific CSS ──────────────────────────────────────────────────────
 
-const CSS = `
+const NOT_FOUND_CSS = `
   :root {
-    --bg: #fff;
-    --fg: #1a1a1a;
-    --fg-dim: #6b7280;
-    --border: #e5e7eb;
     --badge-bg: #fefce8;
     --badge-fg: #854d0e;
     --badge-border: #fde68a;
-    --source-bg: #fafafa;
-    --link: #2563eb;
-    --code-bg: #f3f4f6;
-    --btn-bg: #f3f4f6;
     --route-type-bg: #e0f2fe;
     --route-type-fg: #0369a1;
-    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
   }
 
   @media (prefers-color-scheme: dark) {
     :root {
-      --bg: #0a0a0a;
-      --fg: #f5f5f5;
-      --fg-dim: #9ca3af;
-      --border: #27272a;
       --badge-bg: #422006;
       --badge-fg: #fde68a;
       --badge-border: #854d0e;
-      --source-bg: #18181b;
-      --link: #60a5fa;
-      --code-bg: #27272a;
-      --btn-bg: #27272a;
       --route-type-bg: #0c4a6e;
       --route-type-fg: #bae6fd;
     }
   }
 
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-    background: var(--bg);
-    color: var(--fg);
-    line-height: 1.6;
-    padding: 2rem;
-  }
-
-  .container { max-width: 56rem; margin: 0 auto; }
-  .header { margin-bottom: 1.5rem; }
-
-  .badge {
-    display: inline-block;
-    font-size: 0.75rem;
-    font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    padding: 0.25rem 0.625rem;
-    border-radius: 0.375rem;
-    background: var(--badge-bg);
-    color: var(--badge-fg);
-    border: 1px solid var(--badge-border);
-    margin-bottom: 0.75rem;
-  }
-
-  .message {
-    font-size: 1.375rem;
-    font-weight: 600;
-    line-height: 1.3;
-  }
-
   .message code {
     font-family: var(--code-font);
     background: var(--code-bg);
@@ -317,24 +248,6 @@ const CSS = `
     margin: 0;
   }
 
-  .section {
-    margin-bottom: 1rem;
-    border: 1px solid var(--border);
-    border-radius: 0.5rem;
-    overflow: hidden;
-  }
-
-  .section-header {
-    font-size: 0.75rem;
-    font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    padding: 0.5rem 0.75rem;
-    background: var(--source-bg);
-    border-bottom: 1px solid var(--border);
-    color: var(--fg-dim);
-  }
-
   .route-list {
     list-style: none;
     padding: 0.5rem 0;
@@ -370,18 +283,4 @@ const CSS = `
   }
 
   .suggestions { background: var(--source-bg); }
-
-  .hint { font-size: 0.875rem; color: var(--fg-dim); }
-
-  .footer {
-    display: flex;
-    align-items: center;
-    gap: 0.75rem;
-    padding-top: 1rem;
-    border-top: 1px solid var(--border);
-    font-size: 0.75rem;
-    color: var(--fg-dim);
-  }
-
-  .timber-logo { font-weight: 600; white-space: nowrap; }
 `;