@timber-js/app 0.1.16 → 0.1.18

package/dist/plugins/shims.d.ts

@@ -1,14 +1,19 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution
+ * and #/ subpath import canonicalization.
  *
- * Intercepts imports of next/* modules and redirects them to timber.js
- * shim implementations. This enables Next.js-compatible libraries
- * (nuqs, next-intl, etc.) to work unmodified.
+ * Two responsibilities:
+ * 1. Intercepts imports of next/* modules and redirects them to timber.js
+ *    shim implementations. This enables Next.js-compatible libraries
+ *    (nuqs, next-intl, etc.) to work unmodified.
+ * 2. Canonicalizes #/* subpath imports (package.json "imports" field) to
+ *    absolute file paths, preventing Vite dev from creating duplicate
+ *    module instances when the same file is reached via different import
+ *    paths (e.g., #/client/router-ref.js vs ./router-ref.js).
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports
+ * (except @timber-js/app/server). Those are handled by Vite's native
+ * package.json `exports` resolution, which maps them to dist/ files.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */

package/dist/plugins/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6DhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAkIvD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmFhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAmJvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -130,6 +130,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
+/** Read scroll position from window or scroll containers. */
+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;
+}
+
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
@@ -157,6 +168,9 @@ function bootstrap(runtimeConfig: typeof config): void {
 
   let reactRoot: Root | null = null;
   let initialElement: unknown = null;
+  // Declared here so it's accessible after the if/else hydration block.
+  // Assigned inside initRouter() which is called in both branches.
+  let router!: RouterInstance;
 
   if (timberChunks) {
     const encoder = new TextEncoder();
@@ -240,6 +254,15 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     const element = createFromReadableStream(rscPayload);
     initialElement = element;
+
+    // ── Initialize the navigation router BEFORE hydration ──────────────
+    // hydrateRoot() synchronously executes component render functions.
+    // Components that call useRouter() during render need the global
+    // router to be available, otherwise they get a stale no-op reference.
+    // The renderRoot callback reads `reactRoot` lazily (via closure), so
+    // it's safe to create the router before reactRoot is assigned.
+    initRouter();
+
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
     // Wrap with TimberNuqsAdapter so useQueryStates works out of the box.
@@ -267,66 +290,66 @@ function bootstrap(runtimeConfig: typeof config): void {
     // non-hydrated root so client navigation can still render RSC payloads.
     // The initial SSR HTML remains as-is; the first client navigation will
     // replace it with a React-managed tree.
+    initRouter();
     reactRoot = createRoot(document);
   }
 
-  // Initialize the client-side navigation router.
-  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),
-    scrollTo: (x, y) => {
-      window.scrollTo(x, y);
-      document.documentElement.scrollTop = y;
-      document.body.scrollTop = y;
-      // Also scroll any element explicitly marked as a scroll container.
-      for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
-        (el as HTMLElement).scrollTop = y;
-      }
-    },
-    getCurrentUrl: () => window.location.pathname + window.location.search,
-    getScrollY: () => {
-      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;
-    },
-
-    // Decode RSC Flight stream using createFromFetch.
-    // createFromFetch takes a Promise<Response> and progressively
-    // parses the RSC stream as chunks arrive.
-    decodeRsc: (fetchPromise: Promise<Response>) => {
-      return createFromFetch(fetchPromise);
-    },
+  // ── Router initialization (hoisted above hydrateRoot) ────────────────
+  // Extracted into a function so both the hydration and createRoot paths
+  // can call it. Must run before hydrateRoot so useRouter() works during
+  // the initial render. The renderRoot dep reads `reactRoot` via closure,
+  // so it's fine that reactRoot is assigned after this runs.
+  function initRouter(): void {
+    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),
+      scrollTo: (x, y) => {
+        window.scrollTo(x, y);
+        document.documentElement.scrollTop = y;
+        document.body.scrollTop = y;
+        // Also scroll any element explicitly marked as a scroll container.
+        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.
+      decodeRsc: (fetchPromise: Promise<Response>) => {
+        return createFromFetch(fetchPromise);
+      },
 
-    // Render decoded RSC tree into the hydrated React root.
-    // Wrap with TimberNuqsAdapter to maintain nuqs context across navigations.
-    renderRoot: (element: unknown) => {
-      if (reactRoot) {
-        const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
-        reactRoot.render(wrapped);
-      }
-    },
+      // Render decoded RSC tree into the hydrated React root.
+      // Wrap with TimberNuqsAdapter to maintain nuqs context across navigations.
+      // Reads `reactRoot` from the outer closure — assigned after hydrateRoot().
+      renderRoot: (element: unknown) => {
+        if (reactRoot) {
+          const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
+          reactRoot.render(wrapped);
+        }
+      },
 
-    // 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);
-      });
-    },
+      // 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,
-  };
+      // 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);
+    router = createRouter(deps);
+    setGlobalRouter(router);
+  }
 
   // Store the initial page in the history stack so back-button works
   // after the first navigation. We store the decoded RSC element so
@@ -379,7 +402,7 @@ function bootstrap(runtimeConfig: typeof config): void {
       const state = window.history.state;
       if (state && typeof state === 'object') {
         // Use getScrollY to capture scroll from overflow containers too.
-        window.history.replaceState({ ...state, scrollY: deps.getScrollY() }, '');
+        window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
       }
     }, 100);
   }

package/src/client/router-ref.ts

@@ -1,9 +1,17 @@
 // Global router reference — shared between browser-entry and client hooks.
 // This module has no dependencies on virtual modules, so it can be safely
 // imported by client hooks without pulling in browser-entry's virtual imports.
+//
+// The router is stored as a module-level variable. The timber-shims plugin
+// canonicalizes #/* subpath imports to absolute file paths, ensuring that
+// all import chains (shim chain, browser-entry relative imports, etc.)
+// resolve to the same module instance in Vite's module graph.
+//
+// See design/18-build-system.md §"Subpath Import Canonicalization"
 
 import type { RouterInstance } from './router.js';
 
+/** Module-level singleton — set once during bootstrap. */
 let globalRouter: RouterInstance | null = null;
 
 /**
@@ -23,3 +31,21 @@ export function getRouter(): RouterInstance {
   }
   return globalRouter;
 }
+
+/**
+ * Get the global router instance or null if not yet initialized.
+ * Used by useRouter() methods to avoid silent failures — callers
+ * can log a meaningful warning instead of silently no-oping.
+ */
+export function getRouterOrNull(): RouterInstance | null {
+  return globalRouter;
+}
+
+/**
+ * Reset the global router to null. Used only in tests to isolate
+ * module-level state between test cases.
+ * @internal
+ */
+export function resetGlobalRouter(): void {
+  globalRouter = null;
+}

package/src/client/use-router.ts

@@ -10,7 +10,7 @@
  */
 
 import { startTransition } from 'react';
-import { getRouter } from './router-ref.js';
+import { getRouterOrNull } from './router-ref.js';
 
 export interface AppRouterInstance {
   /** Navigate to a URL, pushing a new history entry */
@@ -27,16 +27,6 @@ export interface AppRouterInstance {
   prefetch(href: string): void;
 }
 
-/** No-op router returned during SSR or before bootstrap. All methods are safe no-ops. */
-const SSR_NOOP_ROUTER: AppRouterInstance = {
-  push() {},
-  replace() {},
-  refresh() {},
-  back() {},
-  forward() {},
-  prefetch() {},
-};
-
 /**
  * Get a router instance for programmatic navigation.
  *
@@ -47,7 +37,7 @@ const SSR_NOOP_ROUTER: AppRouterInstance = {
  * because during hydration, React synchronously executes component render
  * functions *before* the router is bootstrapped in browser-entry.ts.
  * If we eagerly captured the router during render, components would get
- * the SSR_NOOP_ROUTER and be stuck with silent no-ops forever.
+ * a null reference and be stuck with silent no-ops forever.
  *
  * Returns safe no-ops during SSR or before bootstrap. The `typeof window`
  * check is insufficient because Vite's client SSR environment defines
@@ -57,8 +47,15 @@ const SSR_NOOP_ROUTER: AppRouterInstance = {
 export function useRouter(): AppRouterInstance {
   return {
     push(href: string, options?: { scroll?: boolean }) {
-      let router;
-      try { router = getRouter(); } catch { return; }
+      const router = getRouterOrNull();
+      if (!router) {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.'
+          );
+        }
+        return;
+      }
       // Wrap in startTransition so React 19 tracks the async navigation.
       // React 19's startTransition accepts async callbacks — it keeps
       // isPending=true until the returned promise resolves. This means
@@ -69,15 +66,25 @@ export function useRouter(): AppRouterInstance {
       });
     },
     replace(href: string, options?: { scroll?: boolean }) {
-      let router;
-      try { router = getRouter(); } catch { return; }
+      const router = getRouterOrNull();
+      if (!router) {
+        if (process.env.NODE_ENV === 'development') {
+          console.error('[timber] useRouter().replace() called but router is not initialized.');
+        }
+        return;
+      }
       startTransition(async () => {
         await router.navigate(href, { scroll: options?.scroll, replace: true });
       });
     },
     refresh() {
-      let router;
-      try { router = getRouter(); } catch { return; }
+      const router = getRouterOrNull();
+      if (!router) {
+        if (process.env.NODE_ENV === 'development') {
+          console.error('[timber] useRouter().refresh() called but router is not initialized.');
+        }
+        return;
+      }
       startTransition(async () => {
         await router.refresh();
       });
@@ -89,8 +96,8 @@ export function useRouter(): AppRouterInstance {
       if (typeof window !== 'undefined') window.history.forward();
     },
     prefetch(href: string) {
-      let router;
-      try { router = getRouter(); } catch { return; }
+      const router = getRouterOrNull();
+      if (!router) return; // Silent — prefetch failure is non-fatal
       router.prefetch(href);
     },
   };

package/src/plugins/shims.ts

@@ -1,20 +1,26 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution
+ * and #/ subpath import canonicalization.
  *
- * Intercepts imports of next/* modules and redirects them to timber.js
- * shim implementations. This enables Next.js-compatible libraries
- * (nuqs, next-intl, etc.) to work unmodified.
+ * Two responsibilities:
+ * 1. Intercepts imports of next/* modules and redirects them to timber.js
+ *    shim implementations. This enables Next.js-compatible libraries
+ *    (nuqs, next-intl, etc.) to work unmodified.
+ * 2. Canonicalizes #/* subpath imports (package.json "imports" field) to
+ *    absolute file paths, preventing Vite dev from creating duplicate
+ *    module instances when the same file is reached via different import
+ *    paths (e.g., #/client/router-ref.js vs ./router-ref.js).
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports
+ * (except @timber-js/app/server). Those are handled by Vite's native
+ * package.json `exports` resolution, which maps them to dist/ files.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
 
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { PluginContext } from '#/index.js';
 
@@ -26,6 +32,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = __dirname.endsWith('plugins')
   ? resolve(__dirname, '..', '..')
   : resolve(__dirname, '..');
+const SRC_DIR = resolve(PKG_ROOT, 'src');
 const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 
 /**
@@ -55,18 +62,6 @@ const SHIM_MAP: Record<string, string> = {
   'next/font/local': '\0@timber/fonts/local',
 };
 
-/**
- * Client-only shim overrides for the browser environment.
- *
- * next/navigation in the client environment resolves to navigation-client.ts
- * which only re-exports client hooks — not server functions like redirect()
- * and deny(). This prevents server/primitives.ts from being pulled into the
- * browser bundle via tree-shaking-resistant imports.
- */
-const CLIENT_SHIM_OVERRIDES: Record<string, string> = {
-  'next/navigation': resolve(SHIMS_DIR, 'navigation-client.ts'),
-};
-
 /**
  * Strip .js extension from an import specifier.
  *
@@ -77,6 +72,39 @@ function stripJsExtension(id: string): string {
   return id.endsWith('.js') ? id.slice(0, -3) : id;
 }
 
+/**
+ * Resolve a #/* subpath import to an absolute file path.
+ *
+ * The package.json "imports" field maps #/* → ./src/*. Vite's resolver
+ * handles this via Node.js subpath imports, but in dev mode the resulting
+ * module URL can differ from a relative import to the same file. This
+ * causes module duplication — the same file loaded as two separate ES
+ * modules with separate module-level state.
+ *
+ * This function resolves #/foo/bar.js to <PKG_ROOT>/src/foo/bar.ts
+ * (trying .ts first, then .tsx, then .js, then the raw path).
+ * Returns null if the import is not a #/ import or the file doesn't exist.
+ */
+function resolveSubpathImport(id: string): string | null {
+  if (!id.startsWith('#/')) return null;
+
+  // Strip the #/ prefix and map to src/
+  const subpath = id.slice(2);
+  const basePath = resolve(SRC_DIR, subpath);
+
+  // Strip .js extension and try TypeScript extensions first
+  const withoutJs = stripJsExtension(basePath);
+  for (const ext of ['.ts', '.tsx', '.js']) {
+    const candidate = withoutJs + ext;
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // Try the raw path (e.g., if it already has the right extension)
+  if (existsSync(basePath)) return basePath;
+
+  return null;
+}
+
 /**
  * Create the timber-shims Vite plugin.
  *
@@ -92,13 +120,21 @@ export function timberShims(_ctx: PluginContext): Plugin {
     enforce: 'pre',
 
     /**
-     * Resolve next/* imports to shim files.
+     * Resolve imports to canonical file paths.
      *
      * Resolution order:
      * 1. Check server-only / client-only poison pill packages
-     * 2. Strip .js extension from the import specifier
-     * 3. Check next/* shim map
-     * 4. Return null (pass through) for everything else
+     * 2. Canonicalize #/* subpath imports to absolute paths
+     * 3. Strip .js extension from the import specifier
+     * 4. Check next/* shim map (with client environment override for navigation)
+     * 5. Handle @timber-js/app/server
+     * 6. Return null (pass through) for everything else
+     *
+     * #/* canonicalization (step 2) prevents module duplication in Vite dev.
+     * Package.json "imports" maps #/* → ./src/*, but Vite can resolve the
+     * same file to different module URLs depending on the import chain.
+     * By resolving #/ imports to absolute paths here, all import paths
+     * converge to a single module instance.
      *
      * @timber-js/app/server is resolved to src/ so it shares the same module
      * instance as framework internals (which import via #/). This ensures
@@ -112,15 +148,24 @@ export function timberShims(_ctx: PluginContext): Plugin {
       if (id === 'server-only') return SERVER_ONLY_VIRTUAL;
       if (id === 'client-only') return CLIENT_ONLY_VIRTUAL;
 
+      // Canonicalize #/* subpath imports to absolute file paths.
+      // This is the fix for module duplication (LOCAL-302): ensures that
+      // #/client/router-ref.js and ./router-ref.js from the same directory
+      // resolve to the same module URL in Vite's module graph.
+      const subpathResolved = resolveSubpathImport(id);
+      if (subpathResolved) return subpathResolved;
+
       const cleanId = stripJsExtension(id);
 
       // Check next/* shim map.
-      // In the client (browser) environment, use client-only shim overrides
-      // to avoid pulling server code (primitives.ts) into the browser bundle.
+      // In the client (browser) environment, next/navigation resolves to
+      // navigation-client.ts which only re-exports client hooks — not server
+      // functions like redirect() and deny(). This prevents server/primitives.ts
+      // from being pulled into the browser bundle.
       if (cleanId in SHIM_MAP) {
         const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'client' && cleanId in CLIENT_SHIM_OVERRIDES) {
-          return CLIENT_SHIM_OVERRIDES[cleanId];
+        if (envName === 'client' && cleanId === 'next/navigation') {
+          return resolve(SHIMS_DIR, 'navigation-client.ts');
         }
         return SHIM_MAP[cleanId];
       }