@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

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

@@ -0,0 +1,197 @@
+/**
+ * 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`.
+ *
+ * Actions are dispatched sequentially through a client-wide queue
+ * (TIM-1475): each action's POST starts only after the previous one has
+ * settled and its result has been applied. Navigations do not enter the
+ * queue — they preempt via the NavigationEpoch, marking any running
+ * action as discarded (TIM-1474). Queries (TIM-1415) will bypass the
+ * queue entirely.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+
+import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.ts';
+import { getRouter, getRouterOrNull } from '#client-internal';
+import { setHardNavigating } from '../navigation-root.tsx';
+import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.ts';
+import { markClientStale } from '../stale-client.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+import { createActionQueue } from './action-queue.ts';
+
+/**
+ * Wait for a navigation or refresh to both settle (promise resolved) AND
+ * commit (pushState / renderPayload's commit thunk ran). The queue must
+ * not release the next action until the URL is correct in the address bar
+ * — same rule `<Link>` uses for `isPending` (design/19 §Per-Link Pending
+ * State). `onCommit` fires exactly once: on commit, supersession, or
+ * failure, so nothing awaiting this can hang (codex on #1125).
+ */
+function settledAndCommitted(start: (onCommit: () => void) => Promise<void>): Promise<void> {
+  let commitResolve!: () => void;
+  const committed = new Promise<void>((r) => (commitResolve = r));
+  return Promise.all([start(commitResolve).catch(() => {}), committed]).then(() => {});
+}
+
+export function setupServerActions(): void {
+  const queue = createActionQueue({
+    refreshWhenIdle(): void {
+      const router = getRouterOrNull();
+      if (!router) return;
+      router.runWhenIdle(() => void router.refresh());
+    },
+  });
+
+  setServerCallback((id: string, args: unknown[]) => {
+    return queue.run(async ({ hold }) => {
+      // encodeReply inside the queue — preserves call order when two
+      // calls' args serialize in different numbers of microtasks.
+      const body = await encodeReply(args);
+
+      // Capture the epoch AFTER the previous action has settled and
+      // applied, so it reflects the router's real state — not stale
+      // from a predecessor's refresh bumping the seq (TIM-1474).
+      const router = getRouterOrNull();
+      const epoch = router?.epoch();
+
+      let hasRevalidation = false;
+      let hasRedirect = false;
+      const reval: { paths: string | null } = { paths: null };
+
+      const actionHeaders: Record<string, string> = {
+        'Accept': RSC_CONTENT_TYPE,
+        '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) => {
+        if (res.headers.get(RELOAD_HEADER) === '1') {
+          markClientStale();
+          throw new Error('Version skew detected — this client is out of date');
+        }
+        hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+        hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+        reval.paths = res.headers.get('X-Timber-Revalidation-Path');
+        return res;
+      });
+
+      const decoded = await createFromFetch(response);
+
+      // TIM-1454: Invalidate non-matching paths unconditionally — the
+      // mutation happened server-side regardless of navigation state.
+      if (reval.paths) {
+        if (router) {
+          for (const p of reval.paths.split(' ')) {
+            router.invalidatePath(p);
+          }
+        }
+      }
+
+      // TIM-1476: When the server reports any revalidation, evict all
+      // prefetch cache entries and history stack payloads — the mutation
+      // may affect data any route reads, not just the paths the server
+      // named. Placed before the redirect branch so an internal redirect
+      // via router.navigate() cannot consume a stale prefetch (codex on
+      // #1131). In-flight prefetch singleflights are fenced by the
+      // eviction generation and will not repopulate the cache.
+      if (router && (hasRevalidation || reval.paths)) {
+        router.evictStaleCaches();
+      }
+
+      // Redirects apply unconditionally — the server mutated and told
+      // the client where to go. Return undefined to React NOW so the
+      // action scope settles — awaiting the commit inline would deadlock:
+      // React entangles the commit lane with the action scope, so the
+      // commit waits on the action while the action waits on the commit.
+      // The navigate is fire-and-forget: unlike revalidation (where the
+      // next action must capture the refreshed epoch), a redirect leaves
+      // the page entirely — no subsequent action runs on this URL.
+      if (hasRedirect) {
+        const wrapper = decoded as { _redirect: string; _status: number };
+        const isExternal =
+          wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
+        if (isExternal) {
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+          // Never settle — the document is going away and queued actions
+          // must not resume during page teardown (codex on #1125).
+          return new Promise<undefined>(() => {});
+        }
+        try {
+          const r = getRouter();
+          void r.navigate(wrapper._redirect);
+        } catch (e) {
+          console.debug(
+            '[timber] action redirect: router not ready, using full navigation',
+            e instanceof Error ? e.message : e
+          );
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+        }
+        return undefined;
+      }
+
+      if (hasRevalidation) {
+        const wrapper = decoded as { _action: unknown; _tree: unknown };
+        // Return the action result to React NOW — it may be validation errors
+        // the form needs immediately — and hold the queue until the piggybacked
+        // tree commits. Awaiting applyActionResult inline would deadlock: the
+        // action promise settles only after the commit, but React entangles the
+        // commit lane with the action scope, so the commit waits on the action.
+        // Same pattern as the no-tree branch below (codex on #1126).
+        if (router && epoch) {
+          hold(
+            Promise.resolve()
+              .then(() => router.applyActionResult(epoch, wrapper._tree))
+              .then(
+                (applied) => {
+                  if (!applied) queue.markNeedsRefresh();
+                },
+                (e: unknown) => {
+                  console.error('[timber] applyActionResult failed after server action', e);
+                }
+              )
+          );
+        }
+        return wrapper._action;
+      }
+
+      // revalidatePath was called but only for non-current paths —
+      // caches were already invalidated above, no refresh needed.
+      if (reval.paths) {
+        return decoded;
+      }
+
+      // No piggybacked revalidation — return the result to React NOW
+      // (it may be validation errors the form needs immediately) and hold
+      // the queue until the refresh commits so the next action captures a
+      // current epoch (codex on #1125).
+      if (router && epoch) {
+        hold(
+          router.applyActionResult(epoch).then(
+            (applied) => {
+              if (!applied) queue.markNeedsRefresh();
+            },
+            (e: unknown) => {
+              console.debug('[timber] action refresh failed', e instanceof Error ? e.message : e);
+            }
+          )
+        );
+      }
+
+      return decoded;
+    });
+  });
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Sequential Action Queue — serialises server action dispatch.
+ *
+ * One action at a time. The next action's POST starts only after the
+ * previous one has settled AND its result has been applied (revalidation
+ * rendered or refresh awaited). Navigations do not enter the queue —
+ * they preempt via the NavigationEpoch. Queries (TIM-1415) bypass it
+ * entirely.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ * and design/19-client-navigation.md §State Update Invariants (TIM-1475).
+ */
+
+export interface ActionQueueDeps {
+  refreshWhenIdle: () => void;
+}
+
+const noop = (): void => {};
+
+/**
+ * Passed into `work` so it can return a result to React immediately
+ * while keeping the queue blocked on a side effect (e.g. a refresh
+ * that must commit before the next action captures its epoch).
+ */
+export interface ActionQueueRun {
+  hold: (p: Promise<unknown>) => void;
+}
+
+export interface ActionQueue {
+  /**
+   * Enqueue `work` to run after all preceding actions have settled.
+   * Returns `work`'s own promise so the caller (React) gets the action
+   * result or rejection. If the preceding action rejected, `work` still
+   * runs — errors do not break the chain.
+   *
+   * `work` receives a `hold` handle: calling `hold(promise)` keeps the
+   * queue blocked until that promise settles, independent of `work`'s
+   * return value. Use it for "return the result NOW, await the refresh
+   * commit for sequencing."
+   */
+  run: <T>(work: (q: ActionQueueRun) => Promise<T>) => Promise<T>;
+  /**
+   * Mark that a discarded action would have revalidated. When the queue
+   * drains, one refresh fires via `deps.refreshWhenIdle`.
+   */
+  markNeedsRefresh: () => void;
+}
+
+export function createActionQueue(deps: ActionQueueDeps): ActionQueue {
+  let tail: Promise<void> = Promise.resolve();
+  let needsRefresh = false;
+
+  function drain(): void {
+    if (!needsRefresh) return;
+    needsRefresh = false;
+    deps.refreshWhenIdle();
+  }
+
+  function run<T>(work: (q: ActionQueueRun) => Promise<T>): Promise<T> {
+    const holds: Promise<unknown>[] = [];
+    const hold = (p: Promise<unknown>): void => {
+      holds.push(p.then(noop, noop));
+    };
+    // `p` is the caller-visible promise — it resolves/rejects with work's
+    // result (React sees this). `settled` is the chain link: work settled
+    // AND every held promise settled. It never rejects, so the chain never
+    // breaks and the next action always runs.
+    const p = tail.then(
+      () => work({ hold }),
+      () => work({ hold })
+    );
+    const settled = p
+      .then(noop, noop)
+      .then(() => Promise.all(holds))
+      .then(noop);
+    tail = settled;
+    // Drain when the queue empties: tail identity means nobody enqueued
+    // behind this action between its start and its settlement.
+    void settled.then(() => {
+      if (tail === settled) drain();
+    });
+    return p;
+  }
+
+  function markNeedsRefresh(): void {
+    needsRefresh = true;
+  }
+
+  return { run, markNeedsRefresh };
+}

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,148 @@
+/**
+ * Hydration — pre-hydration sequence and hydrating the React root.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrate the router's React root with the payload
+ * 2. No RSC payload: nothing — the root is created by the first render
+ *    (client/react-root.ts)
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()          — creates the global router so useRouter()
+ *                              works during render
+ *   2. setNavigationState()  — populates pathname/search so usePathname()
+ *                              returns correct values during hydration
+ *   3. hydrateRoot()         — synchronously executes component render
+ *                              functions that depend on steps 1-2
+ *
+ * Params are not part of this sequence. 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 { getRouterOrNull } from '#client-internal';
+import { getNavigationState, setNavigationState } from '../navigation-context.ts';
+import { isPageUnloading } from '../unload-guard.ts';
+import { locationSearch } from '../location-search.ts';
+import type { ReactRootHost } from '../react-root.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;
+  /** The router's wrapper chain — see `RouterInitResult.renderTree`. */
+  renderTree: RouterInitResult['renderTree'];
+}
+
+/**
+ * Run the pre-hydration sequence: set navigation state from the address bar.
+ * Must be called AFTER initRouter().
+ *
+ * Params are no longer seeded here. They used to arrive on two inline scripts
+ * that had to execute before `hydrateRoot()`, because hydration synchronously
+ * renders components that read them. They now ride the payload root, and the
+ * provider that publishes them renders before its own descendants — so the
+ * ordering the step existed to guarantee is now a property of the tree rather
+ * than of the bootstrap sequence (TIM-1294, TIM-1297).
+ */
+export function runPreHydration(): void {
+  setNavigationState({
+    pathname: window.location.pathname,
+    search: locationSearch(),
+  });
+}
+
+/**
+ * Hydrate the React tree 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) there is nothing to
+ * hydrate and nothing to do: 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, renderTree }: HydrateOptions): void {
+  if (!rscResult) return;
+
+  // 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 wrapped = renderTree(rscResult.element, getNavigationState(), rscResult.params);
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (!getRouterOrNull()) {
+      throw new Error('[timber] hydrateRoot called before initRouter() — bootstrap order violated');
+    }
+  }
+
+  reactRoot.hydrate(wrapped, {
+    // 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,131 @@
+/**
+ * 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 + hydrating the root
+ *   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. createReactRoot() +       — the root host the router renders through,
+ *      createTimberRouter()        then the router + Navigation API
+ *   4. runPreHydration()         — set params + navigation state
+ *   5. hydrateApp()              — hydrate the root (no-op without a payload)
+ *   6. setupPostHydration()      — history stack, popstate, scroll
+ *   7. setupHmr()                — dev-only HMR wiring
+ *   8. 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 { readPublishedParams } from '../../shared/payload-root.ts';
+import { runPreHydration, hydrateApp } from './hydrate.ts';
+import { setupPostHydration } from './post-hydration.ts';
+import { setupHmr } from './hmr.ts';
+
+// ─── 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);
+  }
+
+  // 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, renderTree } = createTimberRouter({
+    render: reactRoot.render,
+    initialElement: rscResult?.element ?? undefined,
+    initialParams: rscResult?.params,
+    clientSegmentCache:
+      ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
+  });
+
+  // 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, reactRoot, renderTree });
+
+  // Step 6: Post-hydration wiring
+  setupPostHydration({
+    router,
+    navApiController,
+    initialElement: rscResult?.element ?? null,
+    initialParams: rscResult?.params ?? readPublishedParams(undefined),
+  });
+
+  // Step 7: HMR (dev-only, no-op in production)
+  setupHmr(router);
+}
+
+bootstrap(config);
+
+// ─── 8. 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);