@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/client/browser-entry/action-dispatch.ts

@@ -0,0 +1,116 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * The callback:
+ * 1. Serializes args via `encodeReply` (RSC wire format)
+ * 2. POSTs to the current URL with `Accept: text/x-component`
+ * 3. Decodes the RSC response stream
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+
+import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.js';
+import { getRouter } from '#client-internal';
+import { setHardNavigating } from '../navigation-root.js';
+import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
+import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
+
+export function setupServerActions(): void {
+  setServerCallback(async (id: string, args: unknown[]) => {
+    const body = await encodeReply(args);
+
+    // Track the X-Timber-Revalidation header from the response.
+    // We intercept the fetch promise to read headers before createFromFetch
+    // consumes the body stream.
+    let hasRevalidation = false;
+    let hasRedirect = false;
+    let headElementsJson: string | null = null;
+
+    // Build action request headers. Include deployment ID for version
+    // skew detection (TIM-446) — the server rejects stale actions gracefully.
+    const actionHeaders: Record<string, string> = {
+      'Accept': 'text/x-component',
+      'x-rsc-action': id,
+    };
+    const actionDeploymentId = getClientDeploymentId();
+    if (actionDeploymentId) {
+      actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+    }
+
+    const response = fetch(window.location.href, {
+      method: 'POST',
+      headers: actionHeaders,
+      body,
+    }).then((res) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // trigger a full page load to pick up the new deployment.
+      if (res.headers.get(RELOAD_HEADER) === '1') {
+        window.location.reload();
+        throw new Error('Version skew detected — reloading page');
+      }
+      hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+      hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+      headElementsJson = res.headers.get('X-Timber-Head');
+      return res;
+    });
+
+    let decoded: unknown;
+    try {
+      decoded = await createFromFetch(response);
+    } catch (error) {
+      if (isStaleClientReference(error)) {
+        triggerStaleReload();
+        // Return a never-resolving promise to prevent further processing
+        return new Promise(() => {});
+      }
+      throw error;
+    }
+
+    // Handle redirect — server encoded the redirect location in the RSC stream
+    // instead of returning HTTP 302. Perform a client-side SPA navigation.
+    if (hasRedirect) {
+      const wrapper = decoded as { _redirect: string; _status: number };
+      try {
+        const router = getRouter();
+        void router.navigate(wrapper._redirect);
+      } catch {
+        // Router not yet initialized — fall back to full navigation.
+        // Set hard-navigating flag to prevent Navigation API interception
+        // and React from rendering during page teardown. See TIM-626.
+        setHardNavigating(true);
+        window.location.href = wrapper._redirect;
+      }
+      return undefined;
+    }
+
+    if (hasRevalidation) {
+      // Piggybacked response: wrapper object { _action, _tree }
+      // Apply the revalidated tree directly — no separate router.refresh() needed.
+      const wrapper = decoded as { _action: unknown; _tree: unknown };
+      try {
+        const router = getRouter();
+        const headElements = headElementsJson ? JSON.parse(headElementsJson) : null;
+        router.applyRevalidation(wrapper._tree, headElements);
+      } catch {
+        // Router not yet initialized — fall through
+      }
+      return wrapper._action;
+    }
+
+    // No piggybacked revalidation — refresh to pick up any mutations.
+    // This covers actions that don't call revalidatePath().
+    try {
+      const router = getRouter();
+      void router.refresh();
+    } catch {
+      // Router not yet initialized (rare edge case during bootstrap)
+    }
+
+    return decoded;
+  });
+}

package/src/client/browser-entry/hmr.ts

@@ -0,0 +1,81 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+
+import type { RouterInstance } from '#client-internal';
+import {
+  setupServerLogReplay,
+  setupClientErrorForwarding,
+  showCompilingOverlay,
+  hideCompilingOverlay,
+} from '../browser-dev.js';
+
+type HotApi = {
+  on(event: string, cb: (...args: unknown[]) => void): void;
+  send(event: string, data: unknown): void;
+};
+
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export function setupHmr(router: RouterInstance): void {
+  // Vite injects import.meta.hot in dev mode. Cast to access it without
+  // requiring vite/client types in the package tsconfig.
+  const hot = (import.meta as unknown as { hot?: HotApi }).hot;
+  if (!hot) return;
+
+  // ─── Compiling overlay: Vite client HMR updates ──────────────
+  // vite:beforeUpdate fires when Vite begins applying client-side
+  // module updates (React Fast Refresh, CSS hot update, etc.).
+  // vite:afterUpdate fires once all updates are applied.
+  hot.on('vite:beforeUpdate', () => {
+    showCompilingOverlay();
+  });
+  hot.on('vite:afterUpdate', () => {
+    hideCompilingOverlay();
+  });
+
+  // ─── RSC module invalidation ─────────────────────────────────
+  // rsc:update fires when a server component is edited.
+  // Show the compiling overlay while the RSC refresh is in flight.
+  hot.on('rsc:update', () => {
+    showCompilingOverlay();
+    void router.refresh().finally(() => {
+      hideCompilingOverlay();
+    });
+  });
+
+  // Listen for dev warnings forwarded from the server via WebSocket.
+  // See dev-warnings.ts — emitOnce() sends these via server.hot.send().
+  hot.on('timber:dev-warning', (data: unknown) => {
+    const warning = data as { level: string; message: string };
+    if (warning.level === 'error') {
+      console.error(warning.message);
+    } else {
+      console.warn(warning.message);
+    }
+  });
+
+  // Listen for server console logs forwarded via WebSocket.
+  // Replays them in the browser console with a [SERVER] prefix
+  // so developers can see server output without switching to the terminal.
+  // See plugins/dev-logs.ts.
+  setupServerLogReplay(hot);
+
+  // Forward uncaught client errors to the server for the dev overlay.
+  // The server source-maps the stack and sends it back via Vite's
+  // error overlay protocol. See dev-server.ts §client error listener.
+  setupClientErrorForwarding(hot);
+}

package/src/client/browser-entry/hydrate.ts

@@ -0,0 +1,145 @@
+/**
+ * Hydration — pre-hydration sequence and React root creation.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
+ * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()        — creates the global router so useRouter()
+ *                            works during render
+ *   2. setCurrentParams()  — populates params snapshot so
+ *      + setNavigationState()  useSegmentParams() and usePathname()
+ *                            return correct values during hydration
+ *   3. hydrateRoot()       — synchronously executes component render
+ *                            functions that depend on steps 1-2
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { createElement } from 'react';
+import { hydrateRoot, createRoot } from 'react-dom/client';
+import { getRouterOrNull, setCurrentParams } from '#client-internal';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.js';
+import { TimberNuqsAdapter } from '../nuqs-adapter.js';
+import { isPageUnloading } from '../unload-guard.js';
+import { NavigationRoot, installDeferredNavigation } from '../navigation-root.js';
+import type { TopLoaderConfig } from '../top-loader.js';
+
+import type { RscStreamResult } from './rsc-stream.js';
+
+interface HydrateOptions {
+  /** RSC stream result (null if no inlined payload) */
+  rscResult: RscStreamResult | null;
+  /** Runtime config from virtual:timber-config */
+  config: { topLoader?: TopLoaderConfig };
+}
+
+/**
+ * Run the pre-hydration sequence: read server-embedded params and
+ * set navigation state. Must be called AFTER initRouter().
+ */
+export function runPreHydration(): void {
+  const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
+  if (earlyParams && typeof earlyParams === 'object') {
+    setCurrentParams(earlyParams as Record<string, string | string[]>);
+    setNavigationState({
+      params: earlyParams as Record<string, string | string[]>,
+      pathname: window.location.pathname,
+    });
+    delete (self as unknown as Record<string, unknown>).__timber_params;
+  } else {
+    setNavigationState({
+      params: {},
+      pathname: window.location.pathname,
+    });
+  }
+}
+
+/**
+ * Hydrate the React tree or set up deferred root creation.
+ *
+ * When an RSC payload is available, wraps it with NavigationProvider +
+ * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
+ * document.
+ *
+ * When no RSC payload is available (JS-only client), sets up deferred
+ * navigation so the first client navigation creates the React root.
+ */
+export function hydrateApp({ rscResult, config }: HydrateOptions): void {
+  if (rscResult) {
+    const element = rscResult.element;
+
+    // Wrap with NavigationProvider (for atomic useParams/usePathname),
+    // TimberNuqsAdapter (for nuqs context), and NavigationRoot (for
+    // transition-based rendering during client navigation).
+    //
+    // NavigationRoot holds the element in React state and updates via
+    // startTransition, so React keeps old UI visible while new Suspense
+    // boundaries resolve during navigation. See design/05-streaming.md.
+    const navState = getNavigationState();
+    const withNav = createElement(
+      NavigationProvider,
+      { value: navState },
+      element as React.ReactNode
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+    const rootElement = createElement(NavigationRoot, {
+      initial: wrapped,
+      topLoaderConfig: config.topLoader,
+    });
+
+    if (process.env.NODE_ENV !== 'production') {
+      if (!getRouterOrNull()) {
+        throw new Error(
+          '[timber] hydrateRoot called before initRouter() — bootstrap order violated'
+        );
+      }
+    }
+
+    hydrateRoot(document, rootElement, {
+      // Suppress recoverable hydration errors from deny/error signals
+      // inside Suspense boundaries. The server already handled these
+      // (wrapStreamWithErrorHandling closes the stream cleanly after
+      // the shell is flushed). React replays the error during hydration
+      // but the server HTML is already correct — no recovery needed.
+      onRecoverableError(error: unknown) {
+        // Suppress errors during page unload (refresh/navigate away).
+        // The aborted stream causes incomplete HTML which React flags
+        // as a recoverable error — but the page is being replaced.
+        if (isPageUnloading()) return;
+        // Only log in dev — in production these are expected for
+        // deny() inside Suspense and streaming error boundaries.
+        if (process.env.NODE_ENV === 'development') {
+          console.debug('[timber] Hydration recoverable error:', error);
+        }
+      },
+    });
+  } else {
+    // No RSC payload available — defer React root creation until the
+    // first client navigation (TIM-600).
+    //
+    // We must NOT call createRoot(document).render() here — that would
+    // take React ownership of the entire document and blank the SSR HTML.
+    // Instead, installDeferredNavigation sets up one-shot callbacks so
+    // the first navigateTransition/transitionRender call creates the root
+    // on `document` with the navigated content. After that initial render,
+    // NavigationRoot's real startTransition-based callbacks take over.
+    //
+    // This also fixes TIM-580 (navigation from SSR-only pages) because
+    // the deferred callbacks ensure NavigationRoot is mounted before the
+    // first navigation completes.
+    installDeferredNavigation((initial) => {
+      const rootElement = createElement(NavigationRoot, {
+        initial,
+        topLoaderConfig: config.topLoader,
+      });
+      const root = createRoot(document);
+      root.render(rootElement);
+    });
+  }
+}

package/src/client/browser-entry/index.ts

@@ -0,0 +1,138 @@
+/**
+ * Browser Entry — Client-side hydration and navigation bootstrap.
+ *
+ * This is the thin orchestrator that coordinates the bootstrap sequence.
+ * Each responsibility is extracted into a focused module:
+ *
+ *   action-dispatch.ts  — server action callServer callback
+ *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
+ *   router-init.ts      — createRouter + Navigation API setup
+ *   hydrate.ts          — pre-hydration sequence + hydrateRoot/createRoot
+ *   post-hydration.ts   — history stack, segment cache, popstate, scroll
+ *   hmr.ts              — dev-only HMR + error forwarding
+ *   scroll.ts           — getScrollY helper
+ *
+ * Bootstrap call order contract:
+ *
+ *   1. setupServerActions()      — register callServer (independent)
+ *   2. createRscPayloadStream()  — decode inlined RSC payload
+ *   3. createTimberRouter()      — create router + Navigation API
+ *   4. runPreHydration()         — set params + navigation state
+ *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   6. setupPostHydration()      — history stack, popstate, scroll
+ *   7. setupHmr()                — dev-only HMR wiring
+ *   8. stale reload handlers     — global error listeners
+ *   9. timber-ready signal       — E2E test readiness indicator
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
+ */
+
+// @ts-expect-error — virtual module provided by timber-entries plugin
+import config from 'virtual:timber-config';
+
+import { setClientDeploymentId } from '../rsc-fetch.js';
+import {
+  isStaleClientReference,
+  isChunkLoadError,
+  triggerStaleReload,
+  clearStaleReloadFlag,
+} from '../stale-reload.js';
+
+import { setupServerActions } from './action-dispatch.js';
+import { createRscPayloadStream } from './rsc-stream.js';
+import { createTimberRouter } from './router-init.js';
+import { runPreHydration, hydrateApp } from './hydrate.js';
+import { setupPostHydration } from './post-hydration.js';
+import { setupHmr } from './hmr.js';
+
+// ─── 1. Server Action Dispatch (independent) ────────────────────
+
+setupServerActions();
+
+// ─── 2–7. Bootstrap ─────────────────────────────────────────────
+
+function bootstrap(runtimeConfig: typeof config): void {
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (runtimeConfig as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
+  window.history.scrollRestoration = 'manual';
+
+  // Step 2: Decode inlined RSC payload (may be null for JS-only clients)
+  const rscResult = createRscPayloadStream();
+
+  // Step 3: Create router + Navigation API integration
+  const { router, navApiController } = createTimberRouter();
+
+  // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)
+  runPreHydration();
+
+  // Step 5: Hydrate or set up deferred root creation
+  hydrateApp({ rscResult, config: runtimeConfig });
+
+  // Step 6: Post-hydration wiring
+  setupPostHydration({
+    router,
+    navApiController,
+    initialElement: rscResult?.element ?? null,
+  });
+
+  // Step 7: HMR (dev-only, no-op in production)
+  setupHmr(router);
+}
+
+bootstrap(config);
+
+// ─── 8. Stale Reload Handlers ───────────────────────────────────
+
+// Clear the stale reload flag on successful bootstrap. If the page
+// loaded and bootstrapped without hitting a stale reference error,
+// the loop guard should reset so the next stale error gets a fresh
+// reload attempt.
+clearStaleReloadFlag();
+
+// Global error handler for stale client reference errors during hydration.
+// The initial RSC payload is decoded lazily by React via createFromReadableStream.
+// If the payload references a module ID from a newer deployment, the error
+// surfaces as an unhandled rejection during React's render/hydration cycle.
+// This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
+window.addEventListener('unhandledrejection', (event) => {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// ─── 9. Ready Signal ────────────────────────────────────────────
+
+// Signal that the client runtime has been initialized.
+// Used by E2E tests to wait for hydration before interacting.
+// We append a <meta name="timber-ready"> tag rather than setting a
+// data attribute on <html>. Since React owns the entire document
+// via hydrateRoot(document, ...), mutating <html> attributes causes
+// hydration mismatch warnings. Dynamically-added <meta> tags don't
+// conflict because React doesn't reconcile them.
+const readyMeta = document.createElement('meta');
+readyMeta.name = 'timber-ready';
+document.head.appendChild(readyMeta);

package/src/client/browser-entry/post-hydration.ts

@@ -0,0 +1,119 @@
+/**
+ * Post-Hydration Wiring — history stack, segment cache, popstate, scroll.
+ *
+ * Sets up everything that needs to happen after the React root exists:
+ * - Stores initial page in history stack for instant back navigation
+ * - Initializes scroll state for the initial entry
+ * - Populates segment cache from server-embedded metadata
+ * - Registers popstate handler for back/forward navigation
+ * - Sets up debounced scroll position saving
+ *
+ * See design/19-client-navigation.md §"History Stack"
+ */
+
+import { setCurrentParams } from '#client-internal';
+import type { RouterInstance } from '#client-internal';
+import { setNavigationState } from '../navigation-context.js';
+import type { NavigationApiController } from '../navigation-api.js';
+import { getScrollY } from './scroll.js';
+
+interface PostHydrationOptions {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+  /** Decoded RSC element from initial SSR (null if no RSC payload) */
+  initialElement: unknown;
+}
+
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export function setupPostHydration({
+  router,
+  navApiController,
+  initialElement,
+}: PostHydrationOptions): void {
+  // Store the initial page in the history stack so back-button works
+  // after the first navigation. We store the decoded RSC element so
+  // back navigation can replay it instantly without a server fetch.
+  router.historyStack.push(window.location.pathname + window.location.search, {
+    payload: initialElement,
+    headElements: null, // SSR already set the correct head
+  });
+
+  // Initialize scroll state for the initial entry.
+  // When Navigation API is available, use per-entry state.
+  // Otherwise fall back to history.state.
+  if (navApiController) {
+    navApiController.saveScrollPosition(0);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  }
+
+  // Populate the segment cache from server-embedded segment metadata.
+  // This enables state tree diffing from the very first client navigation.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
+  if (Array.isArray(timberSegments)) {
+    router.initSegmentCache(timberSegments);
+    delete (self as unknown as Record<string, unknown>).__timber_segments;
+  }
+
+  // NOTE: We do NOT cache segment elements from the initial RSC payload here.
+  // The decoded element from createFromReadableStream is a thenable/lazy
+  // element that React resolves during render — the segment walker can't
+  // traverse it. The element cache is populated lazily after the first SPA
+  // navigation (via mergeAndCachePayload in renderViaTransition), when
+  // the decoded payload is a fully resolved React element tree.
+
+  // If the hydration path was skipped (no RSC payload), populate the
+  // fallback params from server embed here.
+  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
+  if (lateTimberParams && typeof lateTimberParams === 'object') {
+    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
+    setNavigationState({
+      params: lateTimberParams as Record<string, string | string[]>,
+      pathname: window.location.pathname,
+    });
+    delete (self as unknown as Record<string, unknown>).__timber_params;
+  }
+
+  // Register popstate handler for back/forward navigation.
+  // When Navigation API is active, the navigate event covers traversals —
+  // popstate is a no-op. When unavailable, popstate handles back/forward.
+  //
+  // Use pathname+search (not full href) to match the URL format used by
+  // navigate() — Link hrefs are relative paths like "/scroll-test/page-a".
+  // Read scrollY from history.state — the browser maintains per-entry state
+  // so duplicate URLs in history each have their own scroll position.
+  window.addEventListener('popstate', () => {
+    // Navigation API handles traversals via the navigate event.
+    if (navApiController) return;
+
+    const state = window.history.state;
+    const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
+    void router.handlePopState(window.location.pathname + window.location.search, scrollY);
+  });
+
+  // Keep scroll position up to date as the user scrolls.
+  // This ensures that when the user presses back/forward, the departing
+  // page's scroll position is already saved in its history entry.
+  // When Navigation API is available, uses per-entry state via
+  // navigation.updateCurrentEntry(). Otherwise falls back to history.state.
+  // Debounced to avoid excessive state updates during smooth scrolling.
+  let scrollTimer: ReturnType<typeof setTimeout>;
+  function saveScrollPosition(): void {
+    clearTimeout(scrollTimer);
+    scrollTimer = setTimeout(() => {
+      const y = getScrollY();
+      if (navApiController) {
+        navApiController.saveScrollPosition(y);
+      } else {
+        const state = window.history.state;
+        if (state && typeof state === 'object') {
+          window.history.replaceState({ ...state, scrollY: y }, '');
+        }
+      }
+    }, 100);
+  }
+  window.addEventListener('scroll', saveScrollPosition, { passive: true });
+}