@timber-js/app 0.1.20 → 0.1.22

package/src/client/router.ts

@@ -5,7 +5,7 @@ import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
-import { setCurrentParams } from './use-params.js';
+import { setCurrentParams, notifyParamsListeners } from './use-params.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -393,12 +393,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // header reflects the currently mounted segments.
       updateSegmentCache(result.segmentInfo);
 
-      // Update useParams() with the new route's params before rendering.
+      // Update the params snapshot before rendering so new components in the
+      // RSC tree see the correct params via getSnapshot(). Subscriber
+      // notification is deferred until after renderPayload() so preserved
+      // layouts don't re-render with {old tree, new params}.
       updateParams(result.params);
 
       // Render the decoded RSC tree into the DOM.
       renderPayload(result.payload);
 
+      // Now notify useParams() subscribers — preserved layout components
+      // re-render after the new tree is committed, seeing {new tree, new params}.
+      notifyParamsListeners();
+
       // Update document.title and <meta> tags with the new page's metadata
       applyHead(result.headElements);
 
@@ -457,11 +464,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Update segment cache with fresh segment info from full render
       updateSegmentCache(result.segmentInfo);
 
-      // Update useParams() with refreshed route params
+      // Update params snapshot before rendering (see navigate() for rationale)
       updateParams(result.params);
 
-      // Render the fresh RSC tree and update head elements
+      // Render the fresh RSC tree, then notify params subscribers
       renderPayload(result.payload);
+      notifyParamsListeners();
       applyHead(result.headElements);
     } finally {
       setPending(false);
@@ -478,6 +486,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Replay cached payload — no server roundtrip
       updateParams(entry.params);
       renderPayload(entry.payload);
+      notifyParamsListeners();
       applyHead(entry.headElements);
       afterPaint(() => {
         deps.scrollTo(0, scrollY);
@@ -500,6 +509,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           params: result.params,
         });
         renderPayload(result.payload);
+        notifyParamsListeners();
         applyHead(result.headElements);
         afterPaint(() => {
           deps.scrollTo(0, scrollY);

package/src/client/ssr-data.ts

@@ -17,8 +17,18 @@
  * APIs, as it's imported by 'use client' hooks that are bundled for the browser.
  * The ALS instance lives in ssr-entry.ts (server-only); this module only holds
  * a reference to the provider function.
+ *
+ * All mutable state is delegated to client/state.ts for singleton guarantees.
+ * See design/18-build-system.md §"Singleton State Registry"
  */
 
+import {
+  ssrDataProvider,
+  currentSsrData,
+  _setSsrDataProvider,
+  _setCurrentSsrData,
+} from './state.js';
+
 // ─── Types ────────────────────────────────────────────────────────
 
 export interface SsrData {
@@ -44,8 +54,16 @@ export interface SsrData {
 // Server-side code (ssr-entry.ts) registers a provider that reads
 // from AsyncLocalStorage. This avoids importing node:async_hooks
 // in this browser-bundled module.
-
-let _ssrDataProvider: (() => SsrData | undefined) | undefined;
+//
+// Module singleton guarantee: In Vite's SSR environment, both
+// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks
+// (via @timber-js/app/client) must resolve to the SAME module instance
+// of this file. The timber-shims plugin ensures this by remapping
+// @timber-js/app/client → src/client/index.ts in the SSR environment.
+// Without this remap, @timber-js/app/client resolves to dist/ (via
+// package.json exports), creating a split where registerSsrDataProvider
+// writes to one instance but getSsrData reads from another.
+// See timber-shims plugin resolveId for details.
 
 /**
  * Register an ALS-backed SSR data provider. Called once at module load
@@ -56,15 +74,13 @@ let _ssrDataProvider: (() => SsrData | undefined) | undefined;
  * concurrent requests with streaming Suspense.
  */
 export function registerSsrDataProvider(provider: () => SsrData | undefined): void {
-  _ssrDataProvider = provider;
+  _setSsrDataProvider(provider);
 }
 
 // ─── Module-Level Fallback ────────────────────────────────────────
 //
 // Used by tests and as a fallback when no ALS provider is registered.
 
-let currentSsrData: SsrData | undefined;
-
 /**
  * Set the SSR data for the current request via module-level state.
  *
@@ -72,7 +88,7 @@ let currentSsrData: SsrData | undefined;
  * This function is retained for tests and as a fallback.
  */
 export function setSsrData(data: SsrData): void {
-  currentSsrData = data;
+  _setCurrentSsrData(data);
 }
 
 /**
@@ -82,7 +98,7 @@ export function setSsrData(data: SsrData): void {
  * This function is retained for tests and as a fallback.
  */
 export function clearSsrData(): void {
-  currentSsrData = undefined;
+  _setCurrentSsrData(undefined);
 }
 
 /**
@@ -95,8 +111,8 @@ export function clearSsrData(): void {
  * Used by client hooks' server snapshot functions.
  */
 export function getSsrData(): SsrData | undefined {
-  if (_ssrDataProvider) {
-    return _ssrDataProvider();
+  if (ssrDataProvider) {
+    return ssrDataProvider();
   }
   return currentSsrData;
 }

package/src/client/state.ts

@@ -0,0 +1,83 @@
+/**
+ * Centralized client singleton state registry.
+ *
+ * ALL mutable module-level state that must have singleton semantics across
+ * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
+ * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * and re-export thin wrapper functions.
+ *
+ * Why: In Vite dev, a module is instantiated separately if reached via different
+ * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).
+ * By centralizing all mutable state in a single module that is always reached
+ * through the same dependency chain (barrel → wrapper → state.ts), we guarantee
+ * a single instance of every piece of shared state.
+ *
+ * DO NOT import this file from outside client/. Server code must never depend
+ * on client state. The barrel (client/index.ts) is the public entry point.
+ *
+ * See design/18-build-system.md §"Module Singleton Strategy" and
+ * §"Singleton State Registry".
+ */
+
+import type { RouterInstance } from './router.js';
+import type { SsrData } from './ssr-data.js';
+
+// ─── Router (from router-ref.ts) ──────────────────────────────────────────
+
+/** The global router singleton — set once during bootstrap. */
+export let globalRouter: RouterInstance | null = null;
+
+export function _setGlobalRouter(router: RouterInstance | null): void {
+  globalRouter = router;
+}
+
+// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────
+
+/**
+ * ALS-backed SSR data provider. When registered, getSsrData() reads from
+ * this function (ALS store) instead of module-level currentSsrData.
+ */
+export let ssrDataProvider: (() => SsrData | undefined) | undefined;
+
+export function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {
+  ssrDataProvider = provider;
+}
+
+/** Fallback SSR data for tests and environments without ALS. */
+export let currentSsrData: SsrData | undefined;
+
+export function _setCurrentSsrData(data: SsrData | undefined): void {
+  currentSsrData = data;
+}
+
+// ─── Route Params (from use-params.ts) ──────────────────────────────────────
+
+/** Current route params snapshot — replaced (not mutated) on each navigation. */
+export let currentParams: Record<string, string | string[]> = {};
+
+export function _setCurrentParams(params: Record<string, string | string[]>): void {
+  currentParams = params;
+}
+
+/** Listeners notified when currentParams changes. */
+export const paramsListeners = new Set<() => void>();
+
+// ─── Search Params Cache (from use-search-params.ts) ────────────────────────
+
+/** Cached search string — avoids reparsing when URL hasn't changed. */
+export let cachedSearch = '';
+export let cachedSearchParams = new URLSearchParams();
+
+export function _setCachedSearch(search: string, params: URLSearchParams): void {
+  cachedSearch = search;
+  cachedSearchParams = params;
+}
+
+// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────
+
+/** Whether the page is currently being unloaded. */
+export let unloading = false;
+
+export function _setUnloading(value: boolean): void {
+  unloading = value;
+}

package/src/client/types.ts

@@ -1,4 +1,21 @@
-export interface RenderErrorDigest<Code extends string = string, Data = unknown> {
+/**
+ * A value that is safe to pass through `JSON.stringify` without data loss.
+ *
+ * Mirrors the server-side type. Defined separately to avoid importing server
+ * modules into the client bundle.
+ */
+export type JsonSerializable =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonSerializable[]
+  | { [key: string]: JsonSerializable };
+
+export interface RenderErrorDigest<
+  Code extends string = string,
+  Data extends JsonSerializable = JsonSerializable,
+> {
   code: Code;
   data: Data;
 }

package/src/client/unload-guard.ts

@@ -8,20 +8,23 @@
  * unloaded so error boundaries and error handlers can suppress abort-related
  * errors during the unload window.
  *
+ * Mutable state is delegated to client/state.ts for singleton guarantees.
+ * See design/18-build-system.md §"Singleton State Registry"
+ *
  * See design/10-error-handling.md §"Known limitation: deny() inside Suspense and hydration"
  */
 
-let unloading = false;
+import { unloading, _setUnloading } from './state.js';
 
 if (typeof window !== 'undefined') {
   window.addEventListener('beforeunload', () => {
-    unloading = true;
+    _setUnloading(true);
   });
 
   // Also detect pagehide for bfcache-aware browsers (Safari).
   // pagehide fires for both navigations and page hide events.
   window.addEventListener('pagehide', () => {
-    unloading = true;
+    _setUnloading(true);
   });
 }
 

package/src/client/use-params.ts

@@ -23,31 +23,28 @@
  * params change during client-side navigation. This matches the pattern
  * used by usePathname() and useSearchParams().
  *
+ * All mutable state is delegated to client/state.ts for singleton guarantees.
+ * See design/18-build-system.md §"Singleton State Registry"
+ *
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
 import { useSyncExternalStore } from 'react';
 import type { Routes } from '#/index.js';
 import { getSsrData } from './ssr-data.js';
+import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
 
 // ---------------------------------------------------------------------------
-// Module-level state + subscribe/notify pattern
+// Module-level subscribe/notify pattern — state lives in state.ts
 // ---------------------------------------------------------------------------
 
-// The current params snapshot. Replaced (not mutated) on each navigation
-// so that React's Object.is check on the snapshot detects changes.
-let currentParams: Record<string, string | string[]> = {};
-
-// Listeners notified when currentParams changes.
-const listeners = new Set<() => void>();
-
 /**
  * Subscribe to params changes. Called by useSyncExternalStore.
  * Exported for testing — not intended for direct use by app code.
  */
 export function subscribe(callback: () => void): () => void {
-  listeners.add(callback);
-  return () => listeners.delete(callback);
+  paramsListeners.add(callback);
+  return () => paramsListeners.delete(callback);
 }
 
 /**
@@ -72,21 +69,33 @@ function getServerSnapshot(): Record<string, string | string[]> {
 // ---------------------------------------------------------------------------
 
 /**
- * Set the current route params. Called by the framework internals
- * during navigation — not intended for direct use by app code.
+ * Set the current route params WITHOUT notifying subscribers.
+ * Called by the router before renderPayload() so that new components
+ * in the RSC tree see the updated params via getSnapshot(), but
+ * preserved layout components don't re-render prematurely with
+ * {old tree, new params}.
+ *
+ * After the React render commits, the router calls notifyParamsListeners()
+ * to trigger re-renders in preserved layouts that read useParams().
  *
  * On the client, the segment router calls this on each navigation.
  * During SSR, params are also available via getSsrData().params
  * (ALS-backed), but setCurrentParams is still called for the
  * module-level fallback path.
- *
- * After mutation, all useSyncExternalStore subscribers are notified
- * so that every mounted useParams() consumer re-renders in the same
- * React commit — even components in unchanged layouts.
  */
 export function setCurrentParams(params: Record<string, string | string[]>): void {
-  currentParams = params;
-  for (const listener of listeners) {
+  _setCurrentParams(params);
+}
+
+/**
+ * Notify all useSyncExternalStore subscribers that params have changed.
+ * Called by the router AFTER renderPayload() so that preserved layout
+ * components re-render only after the new tree is committed — producing
+ * an atomic {new tree, new params} update instead of a stale
+ * {old tree, new params} intermediate state.
+ */
+export function notifyParamsListeners(): void {
+  for (const listener of paramsListeners) {
     listener();
   }
 }
@@ -112,24 +121,25 @@ export function setCurrentParams(params: Record<string, string | string[]>): voi
 export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
 export function useParams(route?: string): Record<string, string | string[]>;
 export function useParams(_route?: string): Record<string, string | string[]> {
-  // During SSR, read from the ALS-backed SSR data context.
-  // This ensures correct params even for components inside Suspense
-  // boundaries that resolve asynchronously across concurrent requests.
-  const ssrData = getSsrData();
-  if (ssrData) {
-    return ssrData.params;
-  }
-
-  // useSyncExternalStore requires a React dispatcher (i.e., must be called
-  // inside a component render). When called outside a component (e.g., in
-  // tests or setup code), fall back to reading the snapshot directly.
-  // This mirrors React's own behavior — hooks only work during rendering.
+  // useSyncExternalStore handles both client and SSR:
+  // - Client: calls getSnapshot() → reads currentParams from state.ts
+  // - SSR: calls getServerSnapshot() → reads from ALS-backed getSsrData()
+  //
+  // We must always call the hook (Rules of Hooks — no conditional hook calls).
+  // React picks the right snapshot function based on the environment.
+  //
+  // When called outside a React component (e.g., in test assertions),
+  // useSyncExternalStore throws because there's no dispatcher. In that case,
+  // fall back to reading the snapshot directly.
   try {
     return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
   } catch {
-    // No React dispatcher available — return the snapshot directly.
+    // No React dispatcher available — return the best available snapshot.
     // This path is hit when useParams() is called outside a component,
     // e.g. in test assertions that verify the current params value.
-    return getSnapshot();
+    // Use getServerSnapshot() because it checks the ALS-backed SSR context
+    // first (request-isolated), falling back to module-level currentParams
+    // only when no SSR context exists (client-side / tests).
+    return getServerSnapshot();
   }
 }

package/src/client/use-search-params.ts

@@ -14,10 +14,14 @@
  *
  * During SSR, reads the request search params from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
+ *
+ * All mutable state is delegated to client/state.ts for singleton guarantees.
+ * See design/18-build-system.md §"Singleton State Registry"
  */
 
 import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.js';
 
 function getSearch(): string {
   if (typeof window !== 'undefined') return window.location.search;
@@ -43,16 +47,16 @@ function subscribe(callback: () => void): () => void {
 
 // Cache the last search string and its parsed URLSearchParams to avoid
 // creating a new object on every render when the URL hasn't changed.
-let cachedSearch = '';
-let cachedParams = new URLSearchParams();
+// State lives in client/state.ts for singleton guarantees.
 
 function getSearchParams(): URLSearchParams {
   const search = getSearch();
   if (search !== cachedSearch) {
-    cachedSearch = search;
-    cachedParams = new URLSearchParams(search);
+    const params = new URLSearchParams(search);
+    _setCachedSearch(search, params);
+    return params;
   }
-  return cachedParams;
+  return cachedSearchParams;
 }
 
 function getServerSearchParams(): URLSearchParams {

package/src/plugins/shims.ts

@@ -92,8 +92,10 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * instance as framework internals (which import via #/). This ensures
      * a single requestContextAls and _getRscFallback variable.
      *
-     * @timber-js/app/client is NOT mapped here — it resolves to dist/ via
-     * package.json exports, where 'use client' is preserved on the entry.
+     * @timber-js/app/client is resolved to src/ in the SSR environment so
+     * client hooks share the same module instance as ssr-entry.ts internals.
+     * In RSC it resolves to dist/ (via package.json exports) where 'use client'
+     * is preserved on the entry for client boundary detection.
      */
     resolveId(id: string) {
       // Poison pill packages — resolve to virtual modules handled by load()
@@ -127,6 +129,28 @@ export function timberShims(_ctx: PluginContext): Plugin {
         return resolve(PKG_ROOT, 'src', 'server', 'index.ts');
       }
 
+      // @timber-js/app/client → src/ in the SSR environment so client hooks
+      // (useParams, usePathname, etc.) share the same module instance as
+      // ssr-entry.ts's internal imports (via #/client/...).
+      //
+      // Without this remap, @timber-js/app/client resolves to dist/ (via
+      // package.json exports), creating a module instance split: ssr-entry.ts
+      // registers the ALS-backed SSR data provider on the src/ instance of
+      // ssr-data.ts, but client component hooks read getSsrData() from the
+      // dist/ instance — which has no provider. Result: hooks like useParams()
+      // return empty defaults during SSR.
+      //
+      // This remap is SSR-only. The RSC environment still resolves to dist/
+      // where 'use client' is preserved on the entry (needed for client
+      // boundary detection). The client (browser) environment uses dist/
+      // for bundling.
+      if (cleanId === '@timber-js/app/client') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'ssr') {
+          return resolve(PKG_ROOT, 'src', 'client', 'index.ts');
+        }
+      }
+
       return null;
     },
 

package/src/routing/scanner.ts

@@ -19,7 +19,10 @@ import type {
   InterceptionMarker,
 } from './types.js';
 import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-import { classifyMetadataRoute } from '#/server/metadata-routes.js';
+import {
+  classifyMetadataRoute,
+  isDynamicMetadataExtension,
+} from '#/server/metadata-routes.js';
 
 /**
  * Pattern matching encoded path delimiters that must be rejected during route discovery.
@@ -317,13 +320,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     }
 
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
+    // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
+    // When both exist for the same base name, dynamic takes precedence.
     // See design/16-metadata.md §"Metadata Routes"
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
       if (!node.metadataRoutes) {
         node.metadataRoutes = new Map();
       }
-      node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+      const existing = node.metadataRoutes.get(name);
+      if (existing) {
+        // Dynamic > static precedence: only overwrite if the new file is dynamic
+        // or the existing file is static (dynamic always wins).
+        const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
+        const newIsDynamic = isDynamicMetadataExtension(name, ext);
+        if (newIsDynamic || !existingIsDynamic) {
+          node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+        }
+      } else {
+        node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+      }
     }
   }
 

package/src/rsc-runtime/browser.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser Runtime Adapter — Re-exports from @vitejs/plugin-rsc/browser.
+ *
+ * This module insulates the rest of the framework from direct imports of
+ * @vitejs/plugin-rsc. The plugin is pre-1.0 and its API surface will change.
+ * By routing all browser-environment imports through this single file, a
+ * breaking upstream change only requires updating one place.
+ *
+ * Keep this as thin pass-through re-exports — the value is the single choke
+ * point, not abstraction.
+ */
+
+export {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+} from '@vitejs/plugin-rsc/browser';

package/src/rsc-runtime/rsc.ts

@@ -0,0 +1,19 @@
+/**
+ * RSC Runtime Adapter — Re-exports from @vitejs/plugin-rsc/rsc.
+ *
+ * This module insulates the rest of the framework from direct imports of
+ * @vitejs/plugin-rsc. The plugin is pre-1.0 and its API surface will change.
+ * By routing all RSC-environment imports through this single file, a breaking
+ * upstream change only requires updating one place instead of every file that
+ * touches the RSC runtime.
+ *
+ * Keep this as thin pass-through re-exports — the value is the single choke
+ * point, not abstraction.
+ */
+
+export {
+  renderToReadableStream,
+  loadServerAction,
+  decodeReply,
+  decodeAction,
+} from '@vitejs/plugin-rsc/rsc';

package/src/rsc-runtime/ssr.ts

@@ -0,0 +1,13 @@
+/**
+ * SSR Runtime Adapter — Re-exports from @vitejs/plugin-rsc/ssr.
+ *
+ * This module insulates the rest of the framework from direct imports of
+ * @vitejs/plugin-rsc. The plugin is pre-1.0 and its API surface will change.
+ * By routing all SSR-environment imports through this single file, a breaking
+ * upstream change only requires updating one place.
+ *
+ * Keep this as thin pass-through re-exports — the value is the single choke
+ * point, not abstraction.
+ */
+
+export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';