@timber-js/app 0.1.18 → 0.1.20

package/dist/plugins/shims.d.ts

@@ -1,19 +1,14 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution
- * and #/ subpath import canonicalization.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
  *
- * 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).
+ * 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.
  *
- * 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.
+ * 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).
  *
  * 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;;;;;;;;;;;;;;;;;;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"}
+{"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;AAiDhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAoIvD"}

package/dist/shims/link.d.ts

@@ -3,7 +3,10 @@
  *
  * Re-exports timber's Link component so libraries that import next/link
  * get the timber equivalent without modification.
+ *
+ * Imports from @timber-js/app/client (not #/) so the component resolves
+ * to the same module instance as user code in Vite dev.
  */
-export { Link as default, Link } from '#/client/link.js';
-export type { LinkProps } from '#/client/link.js';
+export { Link as default, Link } from '@timber-js/app/client';
+export type { LinkProps } from '@timber-js/app/client';
 //# sourceMappingURL=link.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/shims/link.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/shims/link.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/shims/navigation-client.d.ts

@@ -1,20 +1,21 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's navigation shims.
+ * Re-exports only the client-side hooks from timber's client API.
  * Server-only functions (redirect, notFound, etc.) are excluded to prevent
  * server/primitives.ts from being pulled into the browser bundle.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
  * where both client hooks and server functions are needed.
  *
+ * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
+ * to the same module instances as user code in Vite dev — preventing module
+ * duplication where setGlobalRouter() writes to one instance and useRouter()
+ * reads from another.
+ *
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
-export { useParams } from '#/client/use-params.js';
-export { usePathname } from '#/client/use-pathname.js';
-export { useSearchParams } from '#/client/use-search-params.js';
-export { useRouter } from '#/client/use-router.js';
-export { useSelectedLayoutSegment, useSelectedLayoutSegments, } from '#/client/use-selected-layout-segment.js';
+export { useParams, usePathname, useSearchParams, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
 export declare const RedirectType: {
     readonly push: "push";
     readonly replace: "replace";

package/dist/shims/navigation-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-client.d.ts","sourceRoot":"","sources":["../../src/shims/navigation-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,yCAAyC,CAAC;AAIjD,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAKX,wBAAgB,QAAQ,IAAI,KAAK,CAKhC;AAED,wBAAgB,iBAAiB,IAAI,KAAK,CAKzC;AAED,wBAAgB,QAAQ,IAAI,KAAK,CAIhC"}
+{"version":3,"file":"navigation-client.d.ts","sourceRoot":"","sources":["../../src/shims/navigation-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAI/B,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAKX,wBAAgB,QAAQ,IAAI,KAAK,CAKhC;AAED,wBAAgB,iBAAiB,IAAI,KAAK,CAKzC;AAED,wBAAgB,QAAQ,IAAI,KAAK,CAIhC"}

package/dist/shims/navigation.d.ts

@@ -1,15 +1,10 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks use #/ source imports (individual files with 'use client' directives
- * that the RSC plugin detects).
- * Server functions use @timber-js/app/server (resolved to dist/ via native exports)
- * for ALS singleton consistency.
+ * Client hooks import from @timber-js/app/client (the public barrel) so they
+ * resolve to the same module instances as user code in Vite dev. Server
+ * functions import from @timber-js/app/server for ALS singleton consistency.
  */
-export { useParams } from '#/client/use-params.js';
-export { usePathname } from '#/client/use-pathname.js';
-export { useSearchParams } from '#/client/use-search-params.js';
-export { useRouter } from '#/client/use-router.js';
-export { useSelectedLayoutSegment, useSelectedLayoutSegments, } from '#/client/use-selected-layout-segment.js';
+export { useParams, usePathname, useSearchParams, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, } from '@timber-js/app/client';
 export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
 //# sourceMappingURL=navigation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/shims/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,yCAAyC,CAAC;AAGjD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/shims/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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

@@ -30,13 +30,25 @@ import {
   setServerCallback,
   encodeReply,
 } from '@vitejs/plugin-rsc/browser';
-import { createRouter } from './router.js';
-import type { RouterDeps, RouterInstance } from './router.js';
+// Shared-state modules MUST be imported from @timber-js/app/client (the public
+// barrel) so they resolve to the same module instances as user code. In Vite dev,
+// user code imports @timber-js/app/client from dist/ via package.json exports.
+// If we used relative imports (./router-ref.js), Vite would load separate src/
+// copies with separate module-level state — e.g., globalRouter set here but
+// read as null from the dist/ copy used by useRouter().
+import {
+  createRouter,
+  setGlobalRouter,
+  getRouter,
+  setCurrentParams,
+} from '@timber-js/app/client';
+import type { RouterDeps, RouterInstance } from '@timber-js/app/client';
+
+// Internal-only modules (no shared mutable state with user code) use relative
+// imports — they don't need singleton behavior across module graphs.
 import { applyHeadElements } from './head.js';
-import { setGlobalRouter, getRouter } from './router-ref.js';
 import { TimberNuqsAdapter } from './nuqs-adapter.js';
 import { isPageUnloading } from './unload-guard.js';
-import { setCurrentParams } from './use-params.js';
 import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────

package/src/client/index.ts

@@ -18,7 +18,7 @@ export type {
 export { useNavigationPending } from './use-navigation-pending';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter } from './router-ref';
+export { getRouter, setGlobalRouter } from './router-ref';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';

package/src/client/router-ref.ts

@@ -2,12 +2,13 @@
 // 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.
+// The router is stored as a module-level variable. browser-entry.ts and all
+// shim files import from @timber-js/app/client (the public barrel) rather
+// than relative paths or #/ subpath imports. This ensures all import chains
+// resolve to the same module instance via Vite's dep optimizer, preventing
+// the duplication that previously required a window.__timber_router workaround.
 //
-// See design/18-build-system.md §"Subpath Import Canonicalization"
+// See design/18-build-system.md §"Module Singleton Strategy"
 
 import type { RouterInstance } from './router.js';
 

package/src/client/use-params.ts

@@ -18,18 +18,59 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
+ * Reactivity: useParams() uses useSyncExternalStore so that components
+ * in unchanged layouts (e.g., sidebar items) re-render atomically when
+ * params change during client-side navigation. This matches the pattern
+ * used by usePathname() and useSearchParams().
+ *
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
+import { useSyncExternalStore } from 'react';
 import type { Routes } from '#/index.js';
 import { getSsrData } from './ssr-data.js';
 
-// The current params are set by the framework during navigation.
-// In production, this is populated by the segment router when it
-// processes an RSC payload and extracts the matched route params.
-// During SSR, params are read from getSsrData() instead (ALS-backed).
+// ---------------------------------------------------------------------------
+// Module-level state + subscribe/notify pattern
+// ---------------------------------------------------------------------------
+
+// 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);
+}
+
+/**
+ * Get the current params snapshot (client).
+ * Exported for testing — not intended for direct use by app code.
+ */
+export function getSnapshot(): Record<string, string | string[]> {
+  return currentParams;
+}
+
+/**
+ * Get the server-side params snapshot (SSR).
+ * Falls back to the module-level currentParams if no SSR context
+ * is available (shouldn't happen, but defensive).
+ */
+function getServerSnapshot(): Record<string, string | string[]> {
+  return getSsrData()?.params ?? currentParams;
+}
+
+// ---------------------------------------------------------------------------
+// Framework API — called by the segment router on each navigation
+// ---------------------------------------------------------------------------
+
 /**
  * Set the current route params. Called by the framework internals
  * during navigation — not intended for direct use by app code.
@@ -38,11 +79,22 @@ let currentParams: Record<string, string | string[]> = {};
  * 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) {
+    listener();
+  }
 }
 
+// ---------------------------------------------------------------------------
+// Public hook
+// ---------------------------------------------------------------------------
+
 /**
  * Read the current route's dynamic params.
  *
@@ -50,8 +102,8 @@ export function setCurrentParams(params: Record<string, string | string[]>): voi
  * it does not affect the runtime return value.
  *
  * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation. On the client, reads from module-level state
- * (set by the segment router on each navigation).
+ * per-request isolation. On the client, subscribes to the module-level
+ * params store via useSyncExternalStore.
  *
  * @overload Typed — when a known route path is passed, returns the
  *   exact params shape from the generated Routes interface.
@@ -67,5 +119,17 @@ export function useParams(_route?: string): Record<string, string | string[]> {
   if (ssrData) {
     return ssrData.params;
   }
-  return currentParams;
+
+  // 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.
+  try {
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  } catch {
+    // No React dispatcher available — return the snapshot directly.
+    // This path is hit when useParams() is called outside a component,
+    // e.g. in test assertions that verify the current params value.
+    return getSnapshot();
+  }
 }

package/src/client/use-router.ts

@@ -50,9 +50,7 @@ export function useRouter(): AppRouterInstance {
       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.'
-          );
+          console.error('[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.');
         }
         return;
       }

package/src/plugins/shims.ts

@@ -1,26 +1,20 @@
 /**
- * timber-shims — Vite sub-plugin for next/* → timber shim resolution
- * and #/ subpath import canonicalization.
+ * timber-shims — Vite sub-plugin for next/* → timber shim resolution.
  *
- * 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).
+ * 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.
  *
- * 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.
+ * 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).
  *
  * 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';
 
@@ -32,7 +26,6 @@ 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');
 
 /**
@@ -72,39 +65,6 @@ 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.
  *
@@ -120,21 +80,13 @@ export function timberShims(_ctx: PluginContext): Plugin {
     enforce: 'pre',
 
     /**
-     * Resolve imports to canonical file paths.
+     * Resolve next/* imports to shim files.
      *
      * Resolution order:
      * 1. Check server-only / client-only poison pill packages
-     * 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.
+     * 2. Strip .js extension from the import specifier
+     * 3. Check next/* shim map
+     * 4. Return null (pass through) for everything else
      *
      * @timber-js/app/server is resolved to src/ so it shares the same module
      * instance as framework internals (which import via #/). This ensures
@@ -148,13 +100,6 @@ 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.

package/src/shims/link.ts

@@ -5,7 +5,10 @@
  *
  * Re-exports timber's Link component so libraries that import next/link
  * get the timber equivalent without modification.
+ *
+ * Imports from @timber-js/app/client (not #/) so the component resolves
+ * to the same module instance as user code in Vite dev.
  */
 
-export { Link as default, Link } from '#/client/link.js';
-export type { LinkProps } from '#/client/link.js';
+export { Link as default, Link } from '@timber-js/app/client';
+export type { LinkProps } from '@timber-js/app/client';

package/src/shims/navigation-client.ts

@@ -1,25 +1,30 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's navigation shims.
+ * Re-exports only the client-side hooks from timber's client API.
  * Server-only functions (redirect, notFound, etc.) are excluded to prevent
  * server/primitives.ts from being pulled into the browser bundle.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
  * where both client hooks and server functions are needed.
  *
+ * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
+ * to the same module instances as user code in Vite dev — preventing module
+ * duplication where setGlobalRouter() writes to one instance and useRouter()
+ * reads from another.
+ *
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks (client-side only)
-export { useParams } from '#/client/use-params.js';
-export { usePathname } from '#/client/use-pathname.js';
-export { useSearchParams } from '#/client/use-search-params.js';
-export { useRouter } from '#/client/use-router.js';
+// Hooks — imported from the public barrel for module singleton consistency.
 export {
+  useParams,
+  usePathname,
+  useSearchParams,
+  useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
-} from '#/client/use-selected-layout-segment.js';
+} from '@timber-js/app/client';
 
 // RedirectType enum is safe (no server code dependency) and used by some
 // client-side libraries for type checking.

package/src/shims/navigation.ts

@@ -1,21 +1,20 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks use #/ source imports (individual files with 'use client' directives
- * that the RSC plugin detects).
- * Server functions use @timber-js/app/server (resolved to dist/ via native exports)
- * for ALS singleton consistency.
+ * Client hooks import from @timber-js/app/client (the public barrel) so they
+ * resolve to the same module instances as user code in Vite dev. Server
+ * functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — must use source imports for RSC 'use client' detection)
-export { useParams } from '#/client/use-params.js';
-export { usePathname } from '#/client/use-pathname.js';
-export { useSearchParams } from '#/client/use-search-params.js';
-export { useRouter } from '#/client/use-router.js';
+// Hooks (client-side — imported from public barrel for module singleton)
 export {
+  useParams,
+  usePathname,
+  useSearchParams,
+  useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
-} from '#/client/use-selected-layout-segment.js';
+} from '@timber-js/app/client';
 
-// Functions (server-side — resolved to dist/ for ALS singleton consistency)
+// Functions (server-side)
 export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';