@timber-js/app 0.2.0-alpha.210 → 0.2.0-alpha.212

package/src/client/router-lifecycle.ts

@@ -35,23 +35,13 @@ export interface NavigationEpoch {
   readonly idle: boolean;
 }
 
-/** The subset of `RouterDeps` the navigation lifecycle needs. */
-export interface NavigationLifecycleDeps {
-  /**
-   * Signal that a router-initiated navigation has completed. Resolves the
-   * deferred promise that ties the browser's native loading state to the
-   * navigation lifecycle.
-   */
-  completeRouterNavigation?: () => void;
-}
-
 export interface NavigationLifecycle {
   /** The owner that holds the router right now, or null when idle. */
   currentOwner: () => RenderOwner | null;
   /**
    * Take ownership of the router, superseding whatever held it. Returns
    * a fresh `RenderOwner` for the new navigation. See the implementation
-   * for the three parts of superseding.
+   * for the two parts of superseding.
    */
   createNavOwner: (
     kind: 'navigation' | 'revalidation',
@@ -99,6 +89,21 @@ export interface NavigationLifecycle {
    * replaces an earlier one (TIM-1474).
    */
   runWhenIdle: (task: () => void) => void;
+  /**
+   * Subscribe to the router becoming idle (pending false AND commit done):
+   * `listener` runs on every such transition until unsubscribed. Unlike
+   * `runWhenIdle`, any number of listeners may wait.
+   */
+  onIdle: (listener: () => void) => () => void;
+  /**
+   * Subscribe to React committing a navigation's tree — the tree on screen
+   * has changed, whether or not its stream has finished decoding (so the
+   * router may still be pending). Runs on every commit until unsubscribed,
+   * with the committing navigation's `epoch().seq`: a tree handed to React
+   * before a later navigation started can still commit after it, and the
+   * sequence says which one it was.
+   */
+  onTreeCommit: (listener: (seq: number) => void) => () => void;
   /**
    * Settle any handed-off-but-uncommitted owners as superseded, then flush
    * the idle task if the router is now idle. Called by `syncShallowSearch`
@@ -119,7 +124,7 @@ function isAbortError(error: unknown): boolean {
   return false;
 }
 
-export function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle {
+export function createNavigationLifecycle(): NavigationLifecycle {
   // The single ownership slot. One navigation at a time.
   let current: RenderOwner | null = null;
 
@@ -135,6 +140,10 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
 
   let navigationSeq = 0;
   let idleTask: (() => void) | null = null;
+  const idleListeners = new Set<() => void>();
+  const treeCommitListeners = new Set<(seq: number) => void>();
+  // The navigationSeq each owner ran under, for tree-commit listeners.
+  const ownerSeq = new WeakMap<RenderOwner, number>();
 
   /**
    * Whether a handed-off tree has not yet committed. Derived from the slot:
@@ -167,17 +176,13 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
    * in-flight navigation. Optionally links to an external signal (e.g.,
    * from the Navigation API's NavigateEvent.signal).
    *
-   * Superseding is one operation with three parts:
+   * Superseding is one operation with two parts:
    * 1. Abort the previous navigation's fetch — UNLESS its tree is the one on
    *    screen, in which case tearing the stream down would error the page the
    *    user is currently looking at. See `RenderOwner.handedOff`.
    * 2. Settle the previous owner as 'superseded' so its transition detects
    *    it lost and never hands a stale tree to React. This replaces both
    *    `supersedeNavigationTransitions()` and the transition counter bump.
-   * 3. Resolve its Navigation API deferred — the superseded navigation's
-   *    finally block is staleness-guarded (see TIM-1034) and no longer
-   *    cleans up after itself, so the browser's native loading state for
-   *    the dead navigation is cleared here.
    */
   function createNavOwner(
     kind: 'navigation' | 'revalidation',
@@ -186,7 +191,6 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
     if (current) {
       abortUnlessHandedOff(current);
       current.settle('superseded');
-      deps.completeRouterNavigation?.();
     }
     // A handed-off owner whose runNavigation has already finished but whose
     // tree hasn't committed yet. Settle it so its onCommit fires.
@@ -196,6 +200,7 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
     }
     navigationSeq += 1;
     const owner = createRenderOwner(kind);
+    ownerSeq.set(owner, navigationSeq);
     current = owner;
 
     // If an external signal is provided (e.g., Navigation API),
@@ -264,14 +269,16 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       if (current === owner) {
         current = null;
         setPending(false);
-        deps.completeRouterNavigation?.();
         flushIdleTask();
       }
     }
   }
 
+  // Every place the router may have just become idle calls this.
   function flushIdleTask(): void {
-    if (routerPhase.phase !== 'idle' || hasUncommittedNav() || !idleTask) return;
+    if (routerPhase.phase !== 'idle' || hasUncommittedNav()) return;
+    for (const listener of [...idleListeners]) listener();
+    if (!idleTask) return;
     const task = idleTask;
     idleTask = null;
     task();
@@ -307,10 +314,13 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       if (pendingCommit === owner) {
         pendingCommit = null;
       }
+      const seq = ownerSeq.get(owner) ?? navigationSeq;
+      for (const listener of [...treeCommitListeners]) listener(seq);
       flushIdleTask();
     },
 
     placeRevalidationOwner(owner: RenderOwner): void {
+      ownerSeq.set(owner, navigationSeq);
       current = owner;
     },
 
@@ -340,6 +350,16 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       idleTask = task;
     },
 
+    onIdle(listener) {
+      idleListeners.add(listener);
+      return () => idleListeners.delete(listener);
+    },
+
+    onTreeCommit(listener) {
+      treeCommitListeners.add(listener);
+      return () => treeCommitListeners.delete(listener);
+    },
+
     settleHandoffs(): void {
       if (pendingCommit) {
         pendingCommit.settle('superseded');

package/src/client/router-pipeline.ts

@@ -55,7 +55,6 @@ export interface NavigationFetchOptions {
   replace: boolean;
   commitUrl?: string;
   signal?: AbortSignal;
-  skipHistory?: boolean;
   departingUrl?: string;
 }
 
@@ -388,9 +387,9 @@ export function createNavigationPipeline({
       result = await fetchRscPayload(url, deps, freshStateTree, currentUrl, options.signal);
     }
 
-    // Update the browser history — skip when the Navigation API has already
-    // updated the URL via event.intercept() (external navigations).
-    // The committed URL keeps the #fragment (commitUrl) even though the
+    // Update the browser history. This is the only place a push/replace
+    // navigation moves the address bar, with or without the Navigation API
+    // (its listener leaves same-document pushState alone). The committed URL keeps the #fragment (commitUrl) even though the
     // fetch/history-stack URL is hash-less (TIM-1035).
     //
     // Deferred with the rest of the commit: the address bar is navigation
@@ -400,17 +399,12 @@ export function createNavigationPipeline({
     // response that won the race anyway re-pushed the abandoned URL
     // (TIM-1022's failure mode, made unconditional by TIM-1301).
     const commitHistoryUrl = (): void => {
-      if (options.skipHistory) return;
       const commitUrl = options.commitUrl ?? url;
-      // Set the router-navigating flag so the Navigation API's navigate
-      // listener doesn't double-intercept this pushState/replaceState.
-      deps.setRouterNavigating?.(true);
       if (options.replace) {
         deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);
       } else {
         deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);
       }
-      deps.setRouterNavigating?.(false);
     };
 
     const params = await result.params;

package/src/client/router-types.ts

@@ -89,25 +89,6 @@ export interface NavigationOptions {
    * which of the three it was.
    */
   onCommit?: (outcome: CommitOutcome) => void;
-  /**
-   * @internal AbortSignal from the Navigation API's NavigateEvent.
-   * When provided, the signal is linked to the router's per-navigation
-   * AbortController so in-flight RSC fetches are cancelled when a new
-   * navigation starts.
-   */
-  _signal?: AbortSignal;
-  /**
-   * @internal Skip pushState/replaceState — the Navigation API has already
-   * updated the URL via event.intercept(). Used for external navigations
-   * intercepted by the navigate event handler.
-   */
-  _skipHistory?: boolean;
-  /**
-   * @internal The URL the user is navigating FROM, captured before the
-   * Navigation API commits the destination. Sent as X-Timber-URL for
-   * slot skip comparison on the server (TIM-1232).
-   */
-  _departingUrl?: string;
 }
 
 /**
@@ -177,34 +158,12 @@ export interface RouterDeps {
     onCommit?: (outcome: CommitOutcome) => void
   ) => Promise<void>;
 
-  /**
-   * Whether the Navigation API is active and handling traversals.
-   * When true, the popstate handler is a no-op — the Navigation API's
-   * navigate event covers back/forward button presses.
-   */
-  navigationApiActive?: boolean;
-
-  /**
-   * Called around pushState/replaceState to set a flag that prevents
-   * the Navigation API's navigate listener from double-handling
-   * router-initiated navigations.
-   */
-  setRouterNavigating?: (value: boolean) => void;
-
   /**
    * Save scroll position via the Navigation API's per-entry state.
    * When provided, used instead of history.replaceState for scroll storage.
    */
   saveNavigationEntryScroll?: (scrollY: number) => void;
 
-  /**
-   * Signal that a router-initiated navigation has completed. Resolves the
-   * deferred promise that ties the browser's native loading state to the
-   * navigation lifecycle. Called in the finally block of navigate/refresh,
-   * the same place `setPending(false)` clears the TopLoader.
-   */
-  completeRouterNavigation?: () => void;
-
   /**
    * Get the current unwrapped RSC payload element. Used for partial
    * navigation: the router re-wraps the same element with new
@@ -212,14 +171,6 @@ export interface RouterDeps {
    */
   _getCurrentPayload?: () => unknown;
 
-  /**
-   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
-   * Fires the navigate event BEFORE committing the URL, allowing Chrome
-   * to show its native loading indicator. Falls back to pushState when
-   * unavailable.
-   */
-  navigationNavigate?: (url: string, replace: boolean) => void;
-
   /**
    * Scroll the element matching a URL #fragment into view. Returns true
    * when a matching element was found and scrolled. When absent or false,
@@ -301,6 +252,20 @@ export interface RouterInstance {
    * router-idle are true (TIM-1474).
    */
   runWhenIdle(task: () => void): void;
+  /**
+   * Subscribe to the router becoming idle — no navigation pending and no
+   * handed-off tree waiting to commit. Runs on every such transition until
+   * the returned function unsubscribes; any number of listeners may wait.
+   */
+  onIdle(listener: () => void): () => void;
+  /**
+   * Subscribe to React committing a navigation's tree: the page on screen
+   * has changed, even if its stream is still decoding and the router is
+   * still pending. Runs on every commit until unsubscribed, with the
+   * committing navigation's `epoch().seq` — a tree handed to React before a
+   * later navigation started can still commit after it.
+   */
+  onTreeCommit(listener: (seq: number) => void): () => void;
   /**
    * Settle any handed-off-but-uncommitted owners as superseded, then flush
    * idle tasks. Called by `syncShallowSearch` when a shallow URL update

package/src/client/router.ts

@@ -59,7 +59,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   // Ownership of the router: who is navigating, whose fetch may be cut, and
   // the pending store TopLoader subscribes to. See router-lifecycle.ts.
-  const lifecycle = createNavigationLifecycle(deps);
+  const lifecycle = createNavigationLifecycle();
   const {
     currentOwner,
     createNavOwner,
@@ -108,8 +108,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
     const scroll = options.scroll !== false;
     const replace = options.replace === true;
-    const externalSignal = options._signal as AbortSignal | undefined;
-    const skipHistory = options._skipHistory === true;
     // A push, a replace, and a server action redirect all move the user
     // forward; the caller's own types ride beside it. A redirect this router
     // follows keeps the types of the render it interrupted instead.
@@ -127,11 +125,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
     const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
-    // Use the pre-intercept departing URL when the Navigation API has already
-    // committed the destination (_departingUrl from navigation-api.ts). Otherwise
-    // capture it now — getCurrentUrl() is still the departing URL at this point
-    // for non-Navigation-API navigations (TIM-1232).
-    const departingUrl = options._departingUrl ?? deps.getCurrentUrl();
+    // The address bar moves only when the destination commits, so it still
+    // names the page being left (TIM-1232).
+    const departingUrl = deps.getCurrentUrl();
 
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
@@ -155,57 +151,39 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await leaveSpaSuperseding(url, departingUrl);
     }
 
-    let effectiveSkipHistory = skipHistory;
-
-    await runNavigation(
-      url,
-      async (owner) => {
-        // When Navigation API is active, initiate the navigation via
-        // navigation.navigate() BEFORE the fetch. Must happen after
-        // createNavOwner supersedes the previous navigation (done by
-        // runNavigation) so the old deferred is resolved first.
-        if (!effectiveSkipHistory && deps.navigationNavigate) {
-          deps.setRouterNavigating?.(true);
-          deps.navigationNavigate(url, replace);
-          deps.setRouterNavigating?.(false);
-          effectiveSkipHistory = true;
-        }
-
-        try {
-          await renderViaTransition(
-            fetchUrl,
-            owner,
-            types,
-            () =>
-              performNavigationFetch(fetchUrl, {
-                replace,
-                commitUrl: url,
-                signal: owner.fetchAbort.signal,
-                skipHistory: effectiveSkipHistory,
-                departingUrl,
-              }),
-            options.onCommit
-          );
-
-          // Scroll-to-top on forward navigation, scroll to the #fragment target
-          // when the URL has one, or restore captured position for scroll={false}.
-          if (scroll && hash) {
-            scrollToHashAfterPaint(hash);
-          } else {
-            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-          }
-        } catch (error) {
-          // `url` is where the user asked to go and `departingUrl` is where
-          // they were: a failure here finishes the click as a full document
-          // load of the destination, fragment included (TIM-1234). Reloading
-          // instead would rebuild the page they were *leaving* and discard
-          // the click (TIM-1275).
-          if (await recoverFromNavigationError(error, owner, url, departingUrl, types)) return;
-          throw error;
+    await runNavigation(url, async (owner) => {
+      try {
+        await renderViaTransition(
+          fetchUrl,
+          owner,
+          types,
+          () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: owner.fetchAbort.signal,
+              departingUrl,
+            }),
+          options.onCommit
+        );
+
+        // Scroll-to-top on forward navigation, scroll to the #fragment target
+        // when the URL has one, or restore captured position for scroll={false}.
+        if (scroll && hash) {
+          scrollToHashAfterPaint(hash);
+        } else {
+          restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
         }
-      },
-      externalSignal
-    );
+      } catch (error) {
+        // `url` is where the user asked to go and `departingUrl` is where
+        // they were: a failure here finishes the click as a full document
+        // load of the destination, fragment included (TIM-1234). Reloading
+        // instead would rebuild the page they were *leaving* and discard
+        // the click (TIM-1275).
+        if (await recoverFromNavigationError(error, owner, url, departingUrl, types)) return;
+        throw error;
+      }
+    });
   }
 
   /**
@@ -523,6 +501,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       return outcome === 'committed';
     },
     runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
+    onIdle: (listener) => lifecycle.onIdle(listener),
+    onTreeCommit: (listener) => lifecycle.onTreeCommit(listener),
     settleHandoffs: () => lifecycle.settleHandoffs(),
     suppressSegmentReuse(): void {
       // TIM-1466: uses invalidateReuse() instead of clear() to preserve

package/src/index.ts

@@ -18,7 +18,7 @@ import { createRequire } from 'node:module';
 import react from '@vitejs/plugin-react';
 import { timberContent } from './plugins/content.ts';
 import { timberDevServer } from './plugins/dev-server.ts';
-import { timberEntries } from './plugins/entries.ts';
+import { timberEntries, BROWSER_ENTRY_FILE } from './plugins/entries.ts';
 import { timberMdx } from './plugins/mdx.ts';
 import { timberRouting } from './plugins/routing.ts';
 import { timberShims } from './plugins/shims.ts';
@@ -473,9 +473,28 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
             console: originalConsole as Console,
           });
 
+      // Seed the client optimizer's startup crawl with every 'use client'
+      // file so client-only packages are pre-bundled before the first
+      // request, not discovered mid-load (which full-reloads the page).
+      // Vite concatenates these with any entries the user sets.
+      // See design/21-dev-server.md §"Client Dependency Pre-Bundling".
+      let environments: Record<string, object> = envOutDirs;
+      if (!isPreview) {
+        ctx.timer.start('client-deps-scan');
+        // Loaded lazily: directive detection pulls in @vitejs/plugin-rsc's
+        // transforms, which builds and preview never need.
+        const { clientOptimizeDepsEntries } = await import('./plugins/client-dep-entries.ts');
+        const entries = await clientOptimizeDepsEntries(resolvedRoot, BROWSER_ENTRY_FILE, buildDir);
+        ctx.timer.end('client-deps-scan');
+        environments = {
+          ...envOutDirs,
+          client: { ...envOutDirs.client, optimizeDeps: { entries } },
+        };
+      }
+
       return {
         build: { outDir: buildOutDir },
-        environments: envOutDirs,
+        environments,
         optimizeDeps: { exclude: timberOptimizeDepsExclude },
         customLogger,
         server: serverConfig,

package/src/plugins/client-dep-entries.ts

@@ -0,0 +1,78 @@
+/**
+ * client-dep-entries — seed the client dep optimizer's startup scan with
+ * the app's `'use client'` modules.
+ *
+ * Vite's dev optimizer discovers bare imports by crawling from its
+ * entries before the first request. With no `optimizeDeps.entries`, the
+ * client environment crawls its build input — timber's browser entry —
+ * and nothing more: every `'use client'` module is reached only through
+ * the RSC payload at runtime, never through a static import the crawl
+ * can follow. A package imported only from client components is then
+ * found on the first browser request, re-optimized mid-load, and the
+ * page full-reloads ("optimized dependencies changed. reloading"). That
+ * reload can leave react and react-dom from two optimizer runs in the
+ * browser (duplicate React → "Invalid hook call").
+ *
+ * Listing the `'use client'` files as entries lets the startup crawl see
+ * those imports. Setting `entries` replaces the build-input default, so
+ * the browser entry is listed too. Files that gain the directive after
+ * startup still fall back to Vite's late discovery.
+ *
+ * Design docs: 21-dev-server.md §"Client Dependency Pre-Bundling".
+ */
+
+import { readFile } from 'node:fs/promises';
+import { sep } from 'node:path';
+import { detectDirective, PARSEABLE_EXTENSIONS } from '../analyze/classify.ts';
+import { normalizeSlashes, scanProjectSourceFiles } from '../analyze/scan.ts';
+
+/**
+ * Every project source file under `root` whose directive prologue holds
+ * `'use client'`. Uses the same walker as `timber graph` (node_modules,
+ * root-level dot dirs and build outputs skipped) and the same AST
+ * directive check the RSC plugin applies. Files under `excludeDir` (the
+ * build output) are skipped.
+ */
+export async function findUseClientFiles(root: string, excludeDir?: string): Promise<string[]> {
+  const files: string[] = [];
+  // An unreadable directory only means its client deps are discovered
+  // late, through Vite's normal fallback — never fatal for dev startup.
+  await scanProjectSourceFiles(root, files, () => {}, 0, PARSEABLE_EXTENSIONS);
+  const excludePrefix = excludeDir ? excludeDir + sep : undefined;
+  const candidates = excludePrefix ? files.filter((f) => !f.startsWith(excludePrefix)) : files;
+
+  const matches = await Promise.all(
+    candidates.map(async (file) => {
+      const code = await readFile(file, 'utf8').catch(() => null);
+      // Cheap text gate before parsing: a directive is a literal
+      // without escapes, so a file lacking the text cannot carry it.
+      if (code === null || !code.includes('use client')) return null;
+      return detectDirective(code, file) === 'use client' ? file : null;
+    })
+  );
+  return matches.filter((file): file is string => file !== null);
+}
+
+/**
+ * Escape a path for use as an `optimizeDeps.entries` pattern. Vite globs
+ * entries, and route directories are full of glob syntax: `(group)`,
+ * `[slug]`, `[[...catchAll]]`, `@slot`. Slashes are normalized first, so
+ * the only backslashes left are literal (POSIX) ones, which are escaped
+ * too.
+ */
+export function escapeGlobPath(path: string): string {
+  return normalizeSlashes(path).replace(/[\\()[\]{}*?|!+@]/g, '\\$&');
+}
+
+/**
+ * The client environment's `optimizeDeps.entries`: timber's browser
+ * entry plus every `'use client'` file in the project.
+ */
+export async function clientOptimizeDepsEntries(
+  root: string,
+  browserEntryFile: string,
+  buildDir: string
+): Promise<string[]> {
+  const clientFiles = await findUseClientFiles(root, buildDir);
+  return [browserEntryFile, ...clientFiles].map(escapeGlobPath);
+}

package/src/plugins/content.ts

@@ -8,7 +8,7 @@
  * Design doc: 20-content-collections.md §"Content Collections"
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, PluginOption } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import type { PluginContext } from '../plugin-context.ts';
@@ -31,6 +31,27 @@ function findConfigFile(root: string): string | undefined {
   return undefined;
 }
 
+/** The name @content-collections/vite gives its plugin. */
+const CONTENT_COLLECTIONS_PLUGIN_NAME = 'content-collections';
+
+/**
+ * Whether the user's own config already registers @content-collections/vite.
+ * Walks nested arrays and awaits promised plugins, the same PluginOption
+ * shapes Vite flattens (and has already resolved by the time config hooks
+ * run, so awaiting here costs nothing).
+ */
+async function registersContentCollections(plugins: PluginOption[] | undefined): Promise<boolean> {
+  for (const option of plugins ?? []) {
+    const plugin = await option;
+    if (Array.isArray(plugin)) {
+      if (await registersContentCollections(plugin)) return true;
+    } else if (plugin && 'name' in plugin && plugin.name === CONTENT_COLLECTIONS_PLUGIN_NAME) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Create the timber-content Vite plugin.
  *
@@ -75,6 +96,10 @@ export function timberContent(ctx: PluginContext): Plugin {
     name: 'timber-content',
 
     async config(config, env) {
+      // Two registrations start two builders and two watchers that race on
+      // the same cache ("Failed to parse the cache mapping"). The user's
+      // own registration, with its options, wins.
+      if (await registersContentCollections(config.plugins)) return;
       const root = config.root ?? ctx.root;
       ctx.timer.start('content-activate');
       await activate(root);

package/src/plugins/entries.ts

@@ -53,6 +53,13 @@ const ENTRY_FILE_MAP: Record<string, string> = {
   [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry', 'index.ts'),
 };
 
+/**
+ * The real file behind virtual:timber-browser-entry. The client dep
+ * optimizer scans it explicitly once timber sets optimizeDeps.entries
+ * (see plugins/client-dep-entries.ts).
+ */
+export const BROWSER_ENTRY_FILE = ENTRY_FILE_MAP[VIRTUAL_IDS.browserEntry];
+
 /** The \0-prefixed resolved ID for virtual:timber-config */
 const RESOLVED_CONFIG_ID = `\0${VIRTUAL_IDS.config}`;
 

package/src/plugins/shims.ts

@@ -103,8 +103,6 @@ export const SERVER_STUB_EXPORTS: readonly string[] = [
   // form-data
   'coerce',
   'parseFormData',
-  // form-flash
-  'getFormFlash',
   // revalidation
   'revalidatePath',
   'revalidateTag',

package/src/rsc-runtime/rsc.ts

@@ -16,6 +16,9 @@ export {
   loadServerAction,
   decodeReply,
   decodeAction,
+  // No-JS action result → the `useActionState` hook that submitted it
+  // (server/action-handler.ts), as Next.js does in its action handler.
+  decodeFormState,
   encryptActionBoundArgs,
   decryptActionBoundArgs,
   // Flight client running INSIDE the RSC environment — decodes a cached

package/src/rsc-runtime/vendor-types.d.ts

@@ -25,3 +25,17 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
     options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
   ): Promise<unknown[]>;
 }
+
+// src decodes through plugin-rsc's wrappers; tests decode a Flight response
+// with the vendored client directly, as the browser's createFromFetch does.
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.edge' {
+  export function createFromReadableStream(
+    stream: ReadableStream<Uint8Array>,
+    options: {
+      serverConsumerManifest: unknown;
+      nonce?: string;
+      temporaryReferences?: unknown;
+      encodeFormAction?: unknown;
+    }
+  ): PromiseLike<unknown>;
+}