@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.73

package/src/cache/index.ts

@@ -1,5 +1,7 @@
 // @timber-js/app/cache — Caching primitives
 
+import { estimateByteSize } from './sizeof.js';
+
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
   set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
@@ -19,15 +21,33 @@ export interface CacheOptions<Fn extends (...args: any[]) => any> {
 
 export interface MemoryCacheHandlerOptions {
   /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+  maxEntries?: number;
+  /**
+   * @deprecated Use `maxEntries` instead. Will be removed in a future release.
+   * Alias for `maxEntries` — maximum number of entries (not bytes).
+   */
   maxSize?: number;
+  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */
+  maxBytes?: number;
+  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */
+  maxEntryBytes?: number;
 }
 
 export class MemoryCacheHandler implements CacheHandler {
-  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
-  private maxSize: number;
+  private store = new Map<
+    string,
+    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }
+  >();
+  private maxEntries: number;
+  private maxBytes: number | undefined;
+  private maxEntryBytes: number | undefined;
+  private currentBytes = 0;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
-    this.maxSize = opts?.maxSize ?? 1000;
+    // maxEntries takes precedence over deprecated maxSize
+    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;
+    this.maxBytes = opts?.maxBytes;
+    this.maxEntryBytes = opts?.maxEntryBytes;
   }
 
   async get(key: string) {
@@ -43,18 +63,33 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    // If key already exists, delete first to refresh insertion order
+    const byteSize = estimateByteSize(value);
+
+    // Reject entries exceeding per-entry byte limit
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
+      return;
+    }
+
+    // If key already exists, delete first to refresh insertion order and reclaim bytes
     if (this.store.has(key)) {
+      const existing = this.store.get(key)!;
+      this.currentBytes -= existing.byteSize;
       this.store.delete(key);
     }
 
-    // Evict oldest entries (front of Map) if at capacity
-    while (this.store.size >= this.maxSize) {
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) {
-        this.store.delete(oldest);
-      } else {
-        break;
+    // Evict oldest entries (front of Map) if at entry count capacity
+    while (this.store.size >= this.maxEntries) {
+      this.evictOldest();
+    }
+
+    // Evict oldest entries if byte budget would be exceeded
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      // If the single entry exceeds the total byte budget, don't store it
+      if (this.currentBytes + byteSize > this.maxBytes) {
+        return;
       }
     }
 
@@ -62,16 +97,23 @@ export class MemoryCacheHandler implements CacheHandler {
       value,
       expiresAt: Date.now() + opts.ttl * 1000,
       tags: opts.tags,
+      byteSize,
     });
+    this.currentBytes += byteSize;
   }
 
   async invalidate(opts: { key?: string; tag?: string }) {
     if (opts.key) {
-      this.store.delete(opts.key);
+      const entry = this.store.get(opts.key);
+      if (entry) {
+        this.currentBytes -= entry.byteSize;
+        this.store.delete(opts.key);
+      }
     }
     if (opts.tag) {
       for (const [key, entry] of this.store) {
         if (entry.tags.includes(opts.tag)) {
+          this.currentBytes -= entry.byteSize;
           this.store.delete(key);
         }
       }
@@ -82,6 +124,21 @@ export class MemoryCacheHandler implements CacheHandler {
   get size(): number {
     return this.store.size;
   }
+
+  /** Estimated total byte size of all cached values. */
+  get bytes(): number {
+    return this.currentBytes;
+  }
+
+  /** Evict the oldest entry (front of Map). */
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) {
+      const entry = this.store.get(oldest)!;
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(oldest);
+    }
+  }
 }
 
 export { RedisCacheHandler } from './redis-handler';
@@ -90,6 +147,8 @@ export { cache } from './cache-api';
 export { setCacheHandler, getCacheHandler } from './handler-store';
 // NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
 // Future feature pending design doc. See design/06-caching.md.
-export { stableStringify } from './stable-stringify';
-export { createSingleflight, SingleflightTimeoutError } from './singleflight';
-export type { Singleflight, SingleflightOptions } from './singleflight';
+export { estimateByteSize } from './sizeof';
+// stableStringify, createSingleflight, and SingleflightTimeoutError are
+// internal utilities used by the cache implementation. They are not
+// re-exported here — import directly from the source files if needed
+// within the package. See TIM-720.

package/src/cache/sizeof.ts

@@ -0,0 +1,31 @@
+/**
+ * Lightweight byte-size estimation for cache entries.
+ *
+ * Estimates the in-memory byte cost of a JavaScript value using
+ * JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+ * approximation — it doesn't account for V8 object overhead, Map
+ * metadata, or non-serializable values — but it's fast and good
+ * enough for cache budget enforcement.
+ *
+ * Values that fail JSON serialization (circular references, BigInt,
+ * etc.) return 0, allowing the entry to be cached without counting
+ * toward the byte budget. This is a conservative choice: it's better
+ * to cache and undercount than to reject the entry.
+ */
+
+/**
+ * Estimate the byte size of a value.
+ *
+ * Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+ * in-memory size. Returns 0 if the value is not serializable.
+ */
+export function estimateByteSize(value: unknown): number {
+  try {
+    const json = JSON.stringify(value);
+    if (json === undefined) return 0;
+    // Each JS string character is 2 bytes (UTF-16)
+    return json.length * 2;
+  } catch {
+    return 0;
+  }
+}

package/src/cli.ts

@@ -63,7 +63,12 @@ export interface ViteDeps {
 
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
   const createServer = _deps?.createServer ?? (await import('vite')).createServer;

package/src/client/browser-dev.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -100,6 +101,132 @@ export function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void {
   });
 }
 
+// ─── Compiling Overlay ──────────────────────────────────────────
+
+/**
+ * Compiling overlay state.
+ *
+ * A small non-blocking indicator in the bottom-left corner that shows
+ * "Compiling..." during HMR/module updates. Uses a 200ms debounce so
+ * near-instant updates never flash the indicator.
+ *
+ * The overlay is lazily created on first show and reused thereafter.
+ * All styles are inline — no external CSS dependency.
+ */
+
+let overlayEl: HTMLDivElement | null = null;
+let showTimeoutId: ReturnType<typeof setTimeout> | null = null;
+let pendingUpdates = 0;
+
+/** Debounce delay before showing the overlay (ms). */
+const SHOW_DELAY_MS = 200;
+
+/**
+ * Get the effective debounce delay.
+ * Checks for a test override on `window.__timber_compiling_debounce`
+ * (number) to allow E2E tests to bypass the debounce.
+ */
+function getShowDelay(): number {
+  const win = window as unknown as { __timber_compiling_debounce?: number };
+  return typeof win.__timber_compiling_debounce === 'number'
+    ? win.__timber_compiling_debounce
+    : SHOW_DELAY_MS;
+}
+
+/**
+ * Lazily create the overlay DOM element.
+ * Appended to document.body with fixed positioning in the bottom-left.
+ */
+function getOrCreateOverlay(): HTMLDivElement {
+  if (overlayEl) return overlayEl;
+
+  const el = document.createElement('div');
+  el.setAttribute('data-timber-compiling-overlay', '');
+  Object.assign(el.style, {
+    position: 'fixed',
+    bottom: '16px',
+    left: '16px',
+    padding: '6px 12px',
+    background: 'rgba(0, 0, 0, 0.85)',
+    color: '#fff',
+    fontSize: '13px',
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    fontWeight: '500',
+    borderRadius: '6px',
+    zIndex: '2147483647',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'opacity 150ms ease',
+    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.3)',
+    lineHeight: '1',
+  });
+  el.textContent = 'Compiling…';
+  document.body.appendChild(el);
+  overlayEl = el;
+  return el;
+}
+
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export function showCompilingOverlay(): void {
+  pendingUpdates++;
+  if (pendingUpdates === 1) {
+    const delay = getShowDelay();
+    if (delay <= 0) {
+      // Synchronous show — no setTimeout race with hideCompilingOverlay().
+      // Used by E2E tests to guarantee the overlay is visible before
+      // the async HMR refresh begins its network roundtrip.
+      const el = getOrCreateOverlay();
+      el.style.opacity = '1';
+    } else {
+      // Production path — debounce to avoid flashing for fast updates
+      showTimeoutId = setTimeout(() => {
+        showTimeoutId = null;
+        const el = getOrCreateOverlay();
+        el.style.opacity = '1';
+      }, delay);
+    }
+  }
+}
+
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export function hideCompilingOverlay(): void {
+  const win = window as unknown as { __timber_hold_compiling_overlay?: boolean };
+  if (win.__timber_hold_compiling_overlay) return;
+
+  pendingUpdates = Math.max(0, pendingUpdates - 1);
+  if (pendingUpdates === 0) {
+    if (showTimeoutId !== null) {
+      clearTimeout(showTimeoutId);
+      showTimeoutId = null;
+    }
+    if (overlayEl) {
+      overlayEl.style.opacity = '0';
+    }
+  }
+}
+
 // ─── Client Error Forwarding ────────────────────────────────────────
 
 /**

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);
+    });
+  }
+}