@timber-js/app 0.1.42 → 0.1.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -100,7 +100,7 @@
     "nuqs": "^2.0.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "vite": "^8.0.0",
+    "vite": "^8.0.1",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {

package/src/client/navigation-context.ts

@@ -47,16 +47,35 @@ export interface NavigationState {
  * The context is created lazily to avoid calling createContext at module
  * level. In the RSC environment, React.createContext doesn't exist —
  * calling it at import time would crash the server.
+ *
+ * IMPORTANT: Context instances are stored on globalThis, NOT in module-
+ * level variables. The RSC client bundler duplicates this module across
+ * the browser-entry chunk (index) and client-reference chunk (shared-app)
+ * because both entry graphs import it. Module-level variables would create
+ * separate singleton instances per chunk — the provider in TransitionRoot
+ * (index chunk) would use context A while the consumer in LinkStatusProvider
+ * (shared-app chunk) reads from context B. globalThis guarantees a single
+ * instance regardless of how many times the module is duplicated.
+ *
+ * See design/19-client-navigation.md §"Singleton Context Guarantee"
  */
-let _context: React.Context<NavigationState | null> | undefined;
+
+// Symbol keys for globalThis storage — prevents collisions with user code
+const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
+const PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');
 
 function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
-  if (_context !== undefined) return _context;
+  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
+    | React.Context<NavigationState | null>
+    | undefined;
+  if (existing !== undefined) return existing;
   // createContext may not exist in the RSC environment
   if (typeof React.createContext === 'function') {
-    _context = React.createContext<NavigationState | null>(null);
+    const ctx = React.createContext<NavigationState | null>(null);
+    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
+    return ctx;
   }
-  return _context;
+  return undefined;
 }
 
 /**
@@ -101,22 +120,34 @@ export function NavigationProvider({ value, children }: NavigationProviderProps)
 // ---------------------------------------------------------------------------
 
 /**
- * Module-level navigation state. Updated by the router before calling
- * renderRoot(). The renderRoot callback reads this to create the
- * NavigationProvider with the correct values.
+ * Navigation state communicated between the router and renderRoot.
+ *
+ * The router calls setNavigationState() before renderRoot(). The
+ * renderRoot callback reads via getNavigationState() to create the
+ * NavigationProvider with the correct params/pathname.
  *
  * This is NOT used by hooks directly — hooks read from React context.
- * This exists only as a communication channel between the router
- * (which knows the new nav state) and renderRoot (which wraps the element).
+ *
+ * Stored on globalThis (like the context instances above) because the
+ * router lives in the shared-app chunk while renderRoot lives in the
+ * index chunk. Module-level variables would be separate per chunk.
  */
-let _currentNavState: NavigationState = { params: {}, pathname: '/' };
+const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
+
+function _getNavStateStore(): { current: NavigationState } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[NAV_STATE_KEY]) {
+    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/' } };
+  }
+  return g[NAV_STATE_KEY] as { current: NavigationState };
+}
 
 export function setNavigationState(state: NavigationState): void {
-  _currentNavState = state;
+  _getNavStateStore().current = state;
 }
 
 export function getNavigationState(): NavigationState {
-  return _currentNavState;
+  return _getNavStateStore().current;
 }
 
 // ---------------------------------------------------------------------------
@@ -125,23 +156,25 @@ export function getNavigationState(): NavigationState {
 
 /**
  * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (useOptimistic state), consumed by LinkStatusProvider
+ * TransitionRoot (urgent useState), consumed by LinkStatusProvider
  * and useNavigationPending.
  *
- * Lives in this module (not a separate file) to guarantee singleton
- * identity across chunks. The `'use client'` LinkStatusProvider and
- * the non-directive TransitionRoot both import from this module —
- * if they were in separate files, the bundler could duplicate the
- * module-level context variable across chunks.
+ * Uses globalThis via Symbol.for for the same reason as NavigationContext
+ * above — the bundler duplicates this module across chunks, and module-
+ * level variables would create separate context instances.
  */
-let _pendingContext: React.Context<string | null> | undefined;
 
 function getOrCreatePendingContext(): React.Context<string | null> | undefined {
-  if (_pendingContext !== undefined) return _pendingContext;
+  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as
+    | React.Context<string | null>
+    | undefined;
+  if (existing !== undefined) return existing;
   if (typeof React.createContext === 'function') {
-    _pendingContext = React.createContext<string | null>(null);
+    const ctx = React.createContext<string | null>(null);
+    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;
+    return ctx;
   }
-  return _pendingContext;
+  return undefined;
 }
 
 /**