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

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

package/src/client/browser-entry/router-init.ts

@@ -0,0 +1,184 @@
+/**
+ * Router Initialization — creates the timber router with all dependencies.
+ *
+ * Wires up RouterDeps (fetch, history, scroll, RSC decoding, render
+ * callbacks) and optionally sets up Navigation API integration.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+
+import { createElement } from 'react';
+import { createFromFetch } from '../../rsc-runtime/browser.js';
+import { createRouter, setGlobalRouter } from '#client-internal';
+import type { RouterDeps, RouterInstance } from '#client-internal';
+import type { NavigationState } from '#client-internal';
+import { applyHeadElements } from '../head.js';
+import { TimberNuqsAdapter } from '../nuqs-adapter.js';
+import { NavigationProvider } from '../navigation-context.js';
+import { transitionRender, navigateTransition } from '../navigation-root.js';
+import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from '../navigation-api.js';
+import { getScrollY } from './scroll.js';
+
+export interface RouterInitResult {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+}
+
+/**
+ * Create and register the global timber router.
+ *
+ * Must be called before hydrateRoot so `useRouter()` works during
+ * the initial render (methods lazily resolve the router at invocation,
+ * not render time, but initRouter must still run first).
+ */
+export function createTimberRouter(): RouterInitResult {
+  // Feature-detect Navigation API. When available, the navigate event
+  // replaces popstate for back/forward and catches external navigations.
+  // See design/19-client-navigation.md §"Navigation API Integration"
+  const useNavApi = hasNavigationApi();
+
+  const deps: RouterDeps = {
+    fetch: (url, init) => window.fetch(url, init),
+    pushState: (data, unused, url) => window.history.pushState(data, unused, url),
+    replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+    navigationApiActive: useNavApi,
+    scrollTo: (x, y) => {
+      // Scroll the document viewport.
+      window.scrollTo(x, y);
+      document.documentElement.scrollTop = y;
+      document.body.scrollTop = y;
+      // Scroll any element explicitly marked as a scroll container.
+      // With segment tree merging, shared layouts (sidebars, nav bars)
+      // are reconciled in place via cloneElement — React preserves their
+      // DOM and scroll state naturally. We no longer auto-detect overflow
+      // containers, which previously found the wrong element (e.g.,
+      // scrolling a sidebar instead of the main content area).
+      // Use `data-timber-scroll-restoration` to opt in specific containers.
+      for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
+        (el as HTMLElement).scrollTop = y;
+      }
+    },
+    getCurrentUrl: () => window.location.pathname + window.location.search,
+    getScrollY,
+
+    // Decode RSC Flight stream using createFromFetch.
+    // createFromFetch takes a Promise<Response> and progressively
+    // parses the RSC stream as chunks arrive.
+    //
+    // Wrapped with stale client reference detection: if the server
+    // has been redeployed with new bundles, the RSC payload may
+    // reference module IDs that don't exist in the old client bundle.
+    // We catch "Could not find the module" errors and trigger a full
+    // page reload so the browser fetches the new bundle.
+    decodeRsc: async (fetchPromise: Promise<Response>) => {
+      try {
+        return await createFromFetch(fetchPromise);
+      } catch (error) {
+        if (isStaleClientReference(error)) {
+          triggerStaleReload();
+          // Return a never-resolving promise to prevent further processing
+          // while the page is reloading.
+          return new Promise(() => {});
+        }
+        throw error;
+      }
+    },
+
+    // Render decoded RSC tree via NavigationRoot's state-based mechanism.
+    // Used for non-navigation renders (popstate cached replay, applyRevalidation).
+    // Wraps with NavigationProvider + TimberNuqsAdapter.
+    //
+    // For navigation renders (navigate, refresh, popstate-with-fetch),
+    // navigateTransition is used instead — it wraps the entire navigation
+    // in a React transition with useOptimistic for the pending URL.
+    //
+    // navState is passed explicitly by the router — no temporal coupling
+    // with getNavigationState().
+    renderRoot: (element: unknown, navState: NavigationState) => {
+      const withNav = createElement(
+        NavigationProvider,
+        { value: navState },
+        element as React.ReactNode
+      );
+      const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+      transitionRender(wrapped);
+    },
+
+    // Run a navigation inside a React transition with optimistic pending URL.
+    // The entire fetch + state update runs inside startTransition. useOptimistic
+    // shows the pending URL immediately and reverts to null when the transition
+    // commits (atomic with the new tree + params).
+    //
+    // The perform callback receives a wrapPayload function that wraps the
+    // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+    // is passed explicitly by the router — no getNavigationState() needed.
+    navigateTransition: (pendingUrl: string, perform) => {
+      return navigateTransition(pendingUrl, async () => {
+        const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
+          const withNav = createElement(
+            NavigationProvider,
+            { value: navState },
+            rawPayload as React.ReactNode
+          );
+          return createElement(TimberNuqsAdapter, null, withNav);
+        });
+        return payload as React.ReactNode;
+      });
+    },
+
+    // Schedule a callback after the next paint so scroll operations
+    // happen after React commits the new content to the DOM.
+    // Double-rAF ensures the browser has painted the new frame.
+    afterPaint: (callback: () => void) => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(callback);
+      });
+    },
+
+    // Apply resolved head elements (title, meta tags) to the DOM after
+    // SPA navigation. See design/16-metadata.md.
+    applyHead: applyHeadElements,
+  };
+
+  const router = createRouter(deps);
+  setGlobalRouter(router);
+
+  // Set up Navigation API integration after router is created.
+  // The navigate event listener delegates to router.navigate and
+  // router.handlePopState for external navigations and traversals.
+  let navApiController: NavigationApiController | null = null;
+  if (useNavApi) {
+    navApiController = setupNavigationApi({
+      onExternalNavigate: async (url, { replace, signal, scroll }) => {
+        // Navigation intercepted by the Navigation API. Covers both
+        // Link <a> clicks (user-initiated) and external navigations.
+        // The Navigation API handles the URL update via intercept(),
+        // so pass _skipHistory to avoid double pushState.
+        await router.navigate(url, {
+          replace,
+          scroll,
+          _signal: signal,
+          _skipHistory: true,
+        });
+      },
+      onTraverse: async (url, scrollY, signal) => {
+        // Back/forward — delegate to the router's popstate handler.
+        await router.handlePopState(url, scrollY, signal);
+      },
+    });
+
+    // Wire the router-navigating flag into RouterDeps.
+    // This must be done after setupNavigationApi returns the controller.
+    deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+    deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
+    deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
+    deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
+  }
+
+  return { router, navApiController };
+}

package/src/client/browser-entry/rsc-stream.ts

@@ -0,0 +1,157 @@
+/**
+ * RSC Stream Bootstrap — decodes the server-inlined RSC payload.
+ *
+ * The RSC payload is embedded in the HTML as progressive inline script
+ * tags that call `self.__timber_f.push([type, data])` as RSC chunks arrive.
+ * Typed tuples: [0] = bootstrap signal, [1, string] = Flight data chunk.
+ *
+ * This module sets up a ReadableStream fed by those push() calls so
+ * `createFromReadableStream` can decode the Flight protocol progressively.
+ *
+ * See design/18-build-system.md §"Entry Files"
+ */
+
+import { createFromReadableStream } from '../../rsc-runtime/browser.js';
+import { isPageUnloading } from '../unload-guard.js';
+
+type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
+
+export interface RscStreamResult {
+  /** The decoded RSC element (thenable/lazy — resolved by React during render) */
+  element: unknown;
+}
+
+/**
+ * Create the RSC payload stream from server-inlined `__timber_f` chunks.
+ *
+ * Returns null if no RSC payload was inlined (e.g., JS-only client).
+ * When a payload exists, returns the decoded element for hydration.
+ */
+export function createRscPayloadStream(): RscStreamResult | null {
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). If it doesn't exist, skip Flight decoding
+  // entirely and fall through to the createRoot branch.
+  // Do NOT defensively create it here: that would cause
+  // createFromReadableStream to be called on an empty stream, producing
+  // a "Connection closed" error on hydration. See TIM-552.
+  const timberChunks = (self as unknown as Record<string, FlightSegment[] | undefined>).__timber_f;
+  if (!timberChunks) return null;
+
+  const encoder = new TextEncoder();
+
+  // Buffer to hold string data until the stream writer is ready.
+  // Scripts that execute before hydration starts push data here.
+  let dataBuffer: string[] | undefined = [];
+  let streamWriter: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let streamFlushed = false;
+
+  /** Process a typed tuple from __timber_f. */
+  function handleSegment(seg: FlightSegment): void {
+    if (seg[0] === 0) {
+      // Bootstrap signal — initialize buffer (already done above)
+      if (!dataBuffer) dataBuffer = [];
+    } else if (seg[0] === 1) {
+      // Flight data chunk
+      if (streamWriter) {
+        streamWriter.enqueue(encoder.encode(seg[1]));
+      } else if (dataBuffer) {
+        dataBuffer.push(seg[1]);
+      }
+    }
+  }
+
+  // Process any chunks that arrived before this script executed.
+  for (const seg of timberChunks) {
+    handleSegment(seg);
+  }
+  // Clear the array to release memory.
+  timberChunks.length = 0;
+
+  // Patch push() so subsequent script tags feed data in real time.
+  (timberChunks as unknown as { push: (seg: FlightSegment) => void }).push = handleSegment;
+
+  const rscPayload = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamWriter = controller;
+      // Flush buffered data into the stream.
+      if (dataBuffer) {
+        for (const data of dataBuffer) {
+          controller.enqueue(encoder.encode(data));
+        }
+        dataBuffer = undefined;
+      }
+      // If DOM already loaded (non-streaming or fast page), close now.
+      if (streamFlushed) {
+        controller.close();
+      }
+    },
+  });
+
+  // Close the stream when the document finishes loading.
+  // DOMContentLoaded fires after the HTML parser has processed all
+  // inline scripts (including streamed Suspense replacements and
+  // RSC data), so all push() calls have completed by this point.
+  //
+  // If the page is unloading (user refreshed or navigated away),
+  // do NOT close the stream. When the connection drops mid-stream,
+  // DOMContentLoaded fires because the parser finishes. Closing an
+  // incomplete RSC stream causes React's Flight client to throw
+  // "Connection closed." — a jarring error on a page being replaced.
+  // Leaving the stream open is harmless: the page is being torn down.
+  function onDOMContentLoaded(): void {
+    if (isPageUnloading()) return;
+
+    // In dev mode, do NOT close the stream. React's RSC renderer
+    // includes debug owner/stack references ($1, $14, etc.) in the
+    // Flight payload that point to rows delivered through the debug
+    // channel, not the main Flight stream. The browser Flight client
+    // tracks these as pending chunks. Closing the stream with
+    // unresolved chunks triggers reportGlobalError("Connection closed")
+    // which kills the entire React tree.
+    //
+    // Leaving the stream open is harmless: React has already received
+    // all data rows and can hydrate fully. The pending debug chunks
+    // just remain unresolved (they're only used for React DevTools
+    // component stacks, not rendering).
+    //
+    // In production, debug rows are not emitted, so closing is safe.
+    if (process.env.NODE_ENV === 'development') {
+      // Mark as flushed so no more data is buffered, but don't close.
+      streamFlushed = true;
+      dataBuffer = undefined;
+      return;
+    }
+
+    if (streamWriter && !streamFlushed) {
+      streamWriter.close();
+      streamFlushed = true;
+      dataBuffer = undefined;
+    }
+    streamFlushed = true;
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
+  } else {
+    // DOM already parsed. All inline RSC <script> tags have already
+    // executed and pushed their data into the buffer. The buffer was
+    // flushed into the stream during start() above.
+    //
+    // Close via queueMicrotask rather than setTimeout. setTimeout
+    // defers to the next macrotask, which can race with React's
+    // Flight client read loop — if React finishes reading all queued
+    // chunks and issues a reader.read() that pends, the stream is
+    // NOT closed yet (setTimeout hasn't fired), so React sees an
+    // open stream and waits. Then setTimeout fires and closes it.
+    // This works in theory but some React Flight builds interpret
+    // a mid-read close as "Connection closed" rather than clean EOF.
+    // queueMicrotask fires at the end of the current microtask
+    // checkpoint — after start() and createFromReadableStream
+    // initialization but before any macrotask, giving React a
+    // consistent close signal. See TIM-524.
+    queueMicrotask(onDOMContentLoaded);
+  }
+
+  const element = createFromReadableStream(rscPayload);
+  return { element };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Scroll position helpers for the browser entry.
+ *
+ * Reads scroll position from the document viewport or explicitly marked
+ * `data-timber-scroll-restoration` containers.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
+
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ */
+export function getScrollY(): number {
+  if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
+    return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
+  }
+  for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
+    if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
+  }
+  return 0;
+}