@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

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

@@ -0,0 +1,70 @@
+/**
+ * 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.ts';
+
+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 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,143 @@
+/**
+ * Hydration — making the server-rendered page current and hydrating the
+ * React root with it.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrate the router's React root with the payload
+ * 2. No RSC payload: nothing to hydrate — the root is created by the first
+ *    render (client/react-root.ts) — but the page is still made current
+ *
+ * Either way the page becomes current through `RouterInstance.hydrate`, the
+ * same prepare-and-commit every navigation uses, committed before the tree
+ * is handed to React. The one ordering left is that the router exists
+ * before `hydrateRoot()`, so `useRouter()` works during render. Pathname
+ * and search reach the tree as props of its NavigationProvider, from the
+ * router's prepared navState — there is no store to seed first (TIM-1541).
+ *
+ * Params are not part of this sequence either. They arrive on the payload root and
+ * are published by `PayloadRoot` at the top of the tree, so
+ * `useSegmentParams()` is correct during hydration without anything having to
+ * run before it (TIM-1294, TIM-1297).
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { isPageUnloading } from '../unload-guard.ts';
+import type { ReactRootHost } from '../react-root.ts';
+import { readPublishedParams } from '../../shared/payload-root.ts';
+import type { SegmentInfo } from '../../shared/segment-info.ts';
+
+import type { RscStreamResult } from './rsc-stream.ts';
+import type { RouterInitResult } from './router-init.ts';
+
+let showHydrationError: ((error: unknown) => void) | null = null;
+let isHydrationError: ((error: unknown) => boolean) | null = null;
+let pendingHydrationErrors: unknown[] = [];
+
+// React 19 emits attribute-only hydration mismatches via console.error
+// with format substitution: console.error(fmt, link, diff). We must
+// intercept before hydrateRoot() to catch errors during initial hydration.
+const ATTR_MISMATCH_RE =
+  /A tree hydrated but some attributes of the server rendered HTML didn't match/;
+if (process.env.NODE_ENV !== 'production') {
+  const origConsoleError = console.error;
+  console.error = (...args: unknown[]) => {
+    origConsoleError.apply(console, args);
+    if (typeof args[0] === 'string' && ATTR_MISMATCH_RE.test(args[0])) {
+      const message = args
+        .slice(1)
+        .reduce<string>((s, arg) => s.replace('%s', String(arg)), args[0] as string);
+      queueOrShowHydrationError(new Error(message));
+    }
+  };
+  import('../../dev-tools/hydration-overlay.ts').then((m) => {
+    showHydrationError = m.showHydrationError;
+    isHydrationError = m.isHydrationError;
+    for (const err of pendingHydrationErrors) {
+      if (m.isHydrationError(err)) m.showHydrationError(err);
+    }
+    pendingHydrationErrors = [];
+  });
+}
+
+function queueOrShowHydrationError(error: unknown): void {
+  if (showHydrationError && isHydrationError) {
+    if (isHydrationError(error)) showHydrationError(error);
+  } else {
+    pendingHydrationErrors.push(error);
+  }
+}
+
+interface HydrateOptions {
+  /** RSC stream result (null if no inlined payload) */
+  rscResult: RscStreamResult | null;
+  /** The router's React root — the one every navigation renders through. */
+  reactRoot: ReactRootHost;
+  /** Makes the page current and builds its tree — see `RouterInitResult.hydrate`. */
+  hydrate: RouterInitResult['hydrate'];
+}
+
+/**
+ * Take the segment metadata the server embedded in the document
+ * (`self.__timber_segments`), and remove it. It describes the chain the
+ * server rendered, so the first client navigation can send a state tree.
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header".
+ */
+function takeEmbeddedSegmentInfo(): SegmentInfo[] | null {
+  const embedded: unknown = Reflect.get(self, '__timber_segments');
+  Reflect.deleteProperty(self, '__timber_segments');
+  return Array.isArray(embedded) ? embedded : null;
+}
+
+/**
+ * Make the server-rendered page current, and hydrate the React tree with it
+ * when an RSC payload is available.
+ *
+ * Wraps the payload with the router's chain (NavigationProvider,
+ * TimberNuqsAdapter, the slot content cache, ...) and hydrates the router's
+ * React root with it, on the document.
+ *
+ * When no RSC payload is available (JS-only client) the page is committed
+ * at once and there is nothing to hydrate: the root must not be created at
+ * bootstrap —
+ * `createRoot(document).render()` would take React ownership of the entire
+ * document and blank the SSR HTML — so the router's first render, i.e. the
+ * first navigation or revalidation, creates it with the tree it renders
+ * (`createReactRoot`, TIM-600 / TIM-580).
+ */
+export function hydrateApp({ rscResult, reactRoot, hydrate }: HydrateOptions): void {
+  // The chain is the router's own `renderTree`, not a copy: an element type
+  // that is present here and absent on the first navigation (or the
+  // reverse) changes the type at that position, and React remounts
+  // everything below it — losing the layout state partial navigation exists
+  // to preserve. Sharing the function makes that impossible by construction.
+  //
+  // `rscResult.params` is the payload's params promise, not a resolved
+  // record: the inlined Flight stream is still arriving and hydration cannot
+  // wait for it. PayloadRoot suspends on it exactly where React was going to
+  // suspend on `element` (TIM-1297).
+  const page = {
+    payload: rscResult?.element ?? null,
+    params: rscResult?.params ?? readPublishedParams(undefined),
+    segmentInfo: takeEmbeddedSegmentInfo(),
+  };
+  //
+  // `hydrate` comes from the router's own init, so the router exists by
+  // construction when the tree it builds renders.
+  hydrate(page, (element) =>
+    reactRoot.hydrate(element, {
+      // 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) {
+        if (isPageUnloading()) return;
+        if (process.env.NODE_ENV === 'development') {
+          queueOrShowHydrationError(error);
+          console.debug('[timber] Hydration recoverable error:', error);
+        }
+      },
+    })
+  );
+}

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

@@ -0,0 +1,120 @@
+/**
+ * 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          — makes the server page current + hydrates the root
+ *   post-hydration.ts   — 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. createReactRoot() +       — the root host the router renders through,
+ *      createTimberRouter()        then the router + Navigation API
+ *   4. hydrateApp()              — make the page current through the router,
+ *                                   hydrate the root (no root without a payload)
+ *   5. setupPostHydration()      — popstate, scroll
+ *   6. setupHmr()                — dev-only HMR wiring
+ *   7. 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';
+// TIM-932: Populate the codec registry so Link's interpolateParams can
+// use codec.serialize() for URL construction. Side-effect-only import.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../../params/codec-registry.ts';
+setLinkCodecs(schemaCodecs);
+
+import { setClientDeploymentId, setStaticMode, setBasePath } from '../rsc-fetch.ts';
+import { initStaleClient } from '../stale-client.ts';
+
+import { setupServerActions } from './action-dispatch.ts';
+import { createRscPayloadStream } from './rsc-stream.ts';
+import { createTimberRouter } from './router-init.ts';
+import { createReactRoot } from '../react-root.ts';
+import type { TopLoaderConfig } from '../top-loader.tsx';
+import { hydrateApp } from './hydrate.ts';
+import { setupPostHydration } from './post-hydration.ts';
+import { setupHmr } from './hmr.ts';
+
+// ─── 1. Server Action Dispatch (independent) ────────────────────
+
+setupServerActions();
+
+// ─── 2–6. 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);
+  }
+
+  // Reactive skew recovery for failures that never reach the router —
+  // lazily imported client components, preloaded stylesheets. No-ops when
+  // there is no deployment ID, i.e. in dev (TIM-1260).
+  initStaleClient(deploymentId);
+
+  // Deployment base path (Vite's resolved `base`). Must be set before any
+  // RSC fetch — under a non-root base the payloads live below the prefix
+  // like every other emitted file (TIM-1261).
+  setBasePath((runtimeConfig as Record<string, unknown>).base as string | undefined);
+
+  // Static mode: fetch _rsc/*.rsc files instead of route URLs with
+  // Accept headers. Static hosts ignore Accept headers (TIM-1243).
+  if ((runtimeConfig as Record<string, unknown>).output === 'static') {
+    setStaticMode(true);
+  }
+
+  // Step 2: Decode inlined RSC payload (may be null for JS-only clients)
+  const rscResult = createRscPayloadStream();
+
+  // Step 3: Create the React root host and the router that renders through
+  // it. The root itself is created lazily — by hydration below, or by the
+  // first navigation when there is no payload to hydrate (TIM-600).
+  const reactRoot = createReactRoot({
+    container: document,
+    topLoaderConfig: (runtimeConfig as { topLoader?: TopLoaderConfig }).topLoader,
+  });
+  const { router, navApiController, hydrate } = createTimberRouter({
+    render: reactRoot.render,
+    clientSegmentCache:
+      ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
+  });
+
+  // Step 4: Make the page current and hydrate (no root without a payload)
+  hydrateApp({ rscResult, reactRoot, hydrate });
+
+  // Step 5: Post-hydration wiring
+  setupPostHydration({ router, navApiController });
+
+  // Step 6: HMR (dev-only, no-op in production)
+  setupHmr(router);
+}
+
+bootstrap(config);
+
+// ─── 7. 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,99 @@
+/**
+ * Post-Hydration Wiring — popstate and scroll.
+ *
+ * Sets up everything that needs to happen after the React root exists:
+ * - Initializes scroll state for the initial entry
+ * - Registers popstate handler for back/forward navigation
+ * - Sets up debounced scroll position saving
+ *
+ * The initial page's history entry and segment cache are not written here:
+ * they are the router's, and hydration makes the page current through
+ * `RouterInstance.hydrate` like any other commit (TIM-1541).
+ *
+ * See design/19-client-navigation.md §"History Stack"
+ */
+
+import type { RouterInstance } from '#client-internal';
+import type { NavigationApiController } from '../navigation-api.ts';
+import { getScrollY } from './scroll.ts';
+import { locationSearch } from '../location-search.ts';
+
+interface PostHydrationOptions {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+}
+
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export function setupPostHydration({ router, navApiController }: PostHydrationOptions): void {
+  // Leave scrollRestoration = 'auto' so the browser natively restores
+  // scroll on reload, tab restore, and back-from-external-page — cases
+  // JS cannot reliably cover because 'manual' persists on the session
+  // history entry across reloads. For client navigations the router's
+  // restoreScrollAfterPaint() re-applies the saved position after React
+  // commits, writing last and winning over the browser's auto-restore.
+  // Explicitly set 'auto' to heal entries from previously-deployed builds
+  // that set 'manual'.
+  window.history.scrollRestoration = 'auto';
+
+  // Initialize scroll state for the initial entry. On reload the browser's
+  // native restoration may land before or after this runs; the debounced
+  // scroll listener below updates the entry state to the true position.
+  const initialScrollY = getScrollY();
+  if (navApiController) {
+    navApiController.saveScrollPosition(initialScrollY);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: initialScrollY }, '');
+  }
+
+  // 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;
+    // `popstate` does not say which way the user went, and timber writes no
+    // index into `history.state` to work it out: any `pushState` the app
+    // makes itself (nuqs, a shallow update) can overwrite it. So the render is
+    // tagged `navigation-traverse`. The Navigation API path (navigation-api.ts)
+    // is the one that knows back from forward (TIM-1471).
+    void router.handlePopState(
+      window.location.pathname + locationSearch(),
+      scrollY,
+      undefined,
+      'navigation-traverse'
+    );
+  });
+
+  // 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 });
+}