@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/plugins/mdx.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const MDX_EXTENSIONS = ['mdx', 'md'];
 

package/src/plugins/routing.ts

@@ -10,25 +10,46 @@
 
 import type { Plugin, ViteDevServer } from 'vite';
 import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { scanRoutes } from '#/routing/scanner.js';
-import { generateRouteMap } from '#/routing/codegen.js';
-import { collectInterceptionRewrites } from '#/routing/interception.js';
+import { scanRoutes } from '../routing/scanner.js';
+import { generateRouteMap } from '../routing/codegen.js';
+import { collectInterceptionRewrites } from '../routing/interception.js';
 import {
   lintStatusFileDirectives,
   formatStatusFileLintWarnings,
-} from '#/routing/status-file-lint.js';
-import type { RouteTree, SegmentNode, RouteFile } from '#/routing/types.js';
-import type { PluginContext } from '#/index.js';
+} from '../routing/status-file-lint.js';
+import {
+  lintConventions,
+  checkAppDirExists,
+  formatConventionWarnings,
+} from '../routing/convention-lint.js';
+import type { RouteTree, SegmentNode, RouteFile } from '../routing/types.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 
+// TIM-830: Search-params registry virtual module.
+//
+// Statically imports the `searchParams` named export from every page
+// that exports one, and registers each definition into the shared
+// search-params registry keyed by the un-interpolated route pattern
+// (e.g. '/products/[id]'). This lets `<Link>` serialize flat
+// `Partial<T>` values at runtime without callers importing the
+// definition at the call site.
+//
+// The imports are STATIC (`import { searchParams as r0 } from '...'`)
+// so Vite/Rolldown tree-shakes each page's component body out of the
+// registry chunk — only the `searchParams` named export is pulled in.
+const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
+const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
+
 /**
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|default|denied|search-params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
@@ -83,6 +104,24 @@ export function timberRouting(ctx: PluginContext): Plugin {
   const warnedFiles = new Set<string>();
 
   function rescan(): void {
+    // Check app/ directory exists before scanning
+    const appDirWarning = checkAppDirExists(ctx.appDir);
+    if (appDirWarning) {
+      const formatted = formatConventionWarnings([appDirWarning]);
+      if (formatted) process.stderr.write(`${formatted}\n`);
+      // Still create an empty tree so the rest of the pipeline doesn't crash
+      ctx.routeTree = {
+        root: {
+          segmentName: '',
+          segmentType: 'static',
+          urlPath: '/',
+          children: [],
+          slots: new Map(),
+        },
+      };
+      return;
+    }
+
     ctx.timer.start('route-scan');
     ctx.routeTree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
@@ -91,11 +130,20 @@ export function timberRouting(ctx: PluginContext): Plugin {
     writeCodegen(ctx);
 
     // Lint status files for missing 'use client' directive
-    const warnings = lintStatusFileDirectives(ctx.routeTree);
-    const newWarnings = warnings.filter((w) => !warnedFiles.has(w.filePath));
-    if (newWarnings.length > 0) {
-      for (const w of newWarnings) warnedFiles.add(w.filePath);
-      console.warn(formatStatusFileLintWarnings(newWarnings));
+    const statusWarnings = lintStatusFileDirectives(ctx.routeTree);
+    const newStatusWarnings = statusWarnings.filter((w) => !warnedFiles.has(w.filePath));
+    if (newStatusWarnings.length > 0) {
+      for (const w of newStatusWarnings) warnedFiles.add(w.filePath);
+      console.warn(formatStatusFileLintWarnings(newStatusWarnings));
+    }
+
+    // Lint conventions (empty app, missing methods, missing root layout)
+    const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
+    const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
+    if (newConventionWarnings.length > 0) {
+      for (const w of newConventionWarnings) warnedFiles.add(w.id);
+      const formatted = formatConventionWarnings(newConventionWarnings);
+      if (formatted) process.stderr.write(`${formatted}\n`);
     }
   }
 
@@ -123,6 +171,14 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_ID;
       }
 
+      // TIM-830: Search-params registry virtual module
+      if (
+        cleanId === SEARCH_PARAMS_REGISTRY_ID ||
+        cleanId.endsWith(`/${SEARCH_PARAMS_REGISTRY_ID}`)
+      ) {
+        return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
+      }
+
       return null;
     },
 
@@ -133,14 +189,22 @@ export function timberRouting(ctx: PluginContext): Plugin {
      * with absolute import paths for all file references.
      */
     load(id: string) {
-      if (id !== RESOLVED_VIRTUAL_ID) return null;
+      if (id === RESOLVED_VIRTUAL_ID) {
+        // If routeTree hasn't been built yet (shouldn't happen), scan now
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateManifestModule(ctx.routeTree!, ctx.root);
+      }
 
-      // If routeTree hasn't been built yet (shouldn't happen), scan now
-      if (!ctx.routeTree) {
-        rescan();
+      if (id === RESOLVED_SEARCH_PARAMS_REGISTRY_ID) {
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateSearchParamsRegistryModule(ctx.routeTree!);
       }
 
-      return generateManifestModule(ctx.routeTree!);
+      return null;
     },
 
     /**
@@ -168,20 +232,49 @@ export function timberRouting(ctx: PluginContext): Plugin {
       // Watch the app directory
       devServer.watcher.add(ctx.appDir);
 
-      const handleFileChange = (filePath: string) => {
-        // Only react to route-significant files in the app directory
+      /** Snapshot of the last generated manifest, used to detect structural changes. */
+      let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+
+      /**
+       * Handle a route-significant file being added or removed.
+       * Always triggers a full-reload since the route tree structure changed.
+       */
+      const handleStructuralChange = (filePath: string) => {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        // Rescan the route tree
         rescan();
-
-        // Invalidate the virtual module in all environments
+        lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         invalidateManifest(devServer);
       };
 
-      devServer.watcher.on('add', handleFileChange);
-      devServer.watcher.on('unlink', handleFileChange);
+      /**
+       * Handle a route file's content changing.
+       *
+       * Most content edits (JSX changes, fixing typos) don't affect route
+       * metadata — Vite's React Fast Refresh handles those via normal HMR.
+       * Only rescan and full-reload when route metadata actually changed
+       * (e.g., searchParams export added/removed, metadata export changed).
+       */
+      const handleContentChange = (filePath: string) => {
+        if (!filePath.startsWith(ctx.appDir)) return;
+        if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
+
+        rescan();
+        const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+        if (newManifest !== lastManifest) {
+          lastManifest = newManifest;
+          invalidateManifest(devServer);
+        }
+        // Otherwise: content edit didn't change route metadata — let Vite HMR handle it
+      };
+
+      devServer.watcher.on('add', handleStructuralChange);
+      devServer.watcher.on('unlink', handleStructuralChange);
+      // Watch content changes to page files — searchParams detection depends
+      // on file contents (export const searchParams), not just file presence.
+      // But only full-reload when route metadata actually changes.
+      devServer.watcher.on('change', handleContentChange);
       // Also watch renames (which are add+unlink) — handled by the above
     },
   };
@@ -198,9 +291,11 @@ function invalidateManifest(server: ViteDevServer): void {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    const mod = env.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID);
-    if (mod) {
-      env.moduleGraph.invalidateModule(mod);
+    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SEARCH_PARAMS_REGISTRY_ID]) {
+      const mod = env.moduleGraph.getModuleById(virtualId);
+      if (mod) {
+        env.moduleGraph.invalidateModule(mod);
+      }
     }
   }
 
@@ -208,13 +303,88 @@ function invalidateManifest(server: ViteDevServer): void {
   server.hot.send({ type: 'full-reload' });
 }
 
+/**
+ * TIM-830: Walk the route tree and collect every page that exports a
+ * `searchParams` definition, then emit a module that statically imports
+ * each export and registers it into the shared search-params registry.
+ *
+ * Keys use the un-interpolated route pattern (e.g. '/products/[id]') so
+ * <Link> can look up the definition from the original `href` prop before
+ * segmentParams are interpolated.
+ */
+function generateSearchParamsRegistryModule(tree: RouteTree): string {
+  const entries: Array<{ urlPath: string; filePath: string }> = [];
+
+  function walk(node: SegmentNode): void {
+    // params.ts is the canonical location for `export const searchParams`;
+    // page.tsx is the legacy fallback (see codegen.ts `collectRoutes`).
+    if (node.page) {
+      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
+      } else if (fileHasSearchParamsExport(node.page.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
+      }
+    }
+    for (const child of node.children) walk(child);
+    for (const [, slot] of node.slots) walk(slot);
+  }
+  walk(tree.root);
+
+  // Deterministic order for stable output / snapshots
+  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+
+  const lines: string[] = [];
+  lines.push('// Auto-generated search-params registry — do not edit.');
+  lines.push('// Generated by timber-routing plugin (TIM-830).');
+  lines.push('');
+  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
+  lines.push('');
+
+  // Static imports — Vite/Rolldown tree-shakes the page component body out
+  // of this chunk, leaving only the `searchParams` named export.
+  entries.forEach((entry, i) => {
+    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
+  });
+  lines.push('');
+
+  entries.forEach((entry, i) => {
+    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
+  });
+  lines.push('');
+
+  // Exporting an empty object keeps the module a real ESM module even
+  // when there are zero entries (no top-level imports in that case).
+  lines.push('export {};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Lightweight check for a `searchParams` named export. Mirrors
+ * `fileHasExport('searchParams')` in routing/codegen.ts so we stay
+ * in sync with what the type codegen detects.
+ */
+function fileHasSearchParamsExport(filePath: string): boolean {
+  try {
+    if (!existsSync(filePath)) return false;
+    const content = readFileSync(filePath, 'utf-8');
+    return (
+      /export\s+(const|let|var)\s+searchParams\b/.test(content) ||
+      /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content)
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Generate the virtual module source code for the route manifest.
  *
  * The output is a default-exported object containing the serialized route tree.
  * All file references use absolute paths (required for virtual modules).
  */
-function generateManifestModule(tree: RouteTree): string {
+function generateManifestModule(tree: RouteTree, viteRoot: string): string {
   const imports: string[] = [];
   let importIndex = 0;
 
@@ -301,12 +471,15 @@ function generateManifestModule(tree: RouteTree): string {
         `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
       );
     }
-    if (node.searchParams) {
-      const v = addImport(node.searchParams);
+    if (node.params) {
+      const v = addImport(node.params);
       parts.push(
-        `${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`
+        `${nextIndent}params: { load: ${v}, filePath: ${JSON.stringify(node.params.filePath)} },`
       );
     }
+    // searchParams is now a named export from page.tsx, not a separate file.
+    // The page module's searchParams export is loaded via the page's lazy import.
+    // Runtime registration happens in the route loader using the page module.
 
     // Status-code files
     if (node.statusFiles && node.statusFiles.size > 0) {
@@ -391,6 +564,13 @@ function generateManifestModule(tree: RouteTree): string {
     proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
   }
 
+  // Global error page (Tier 2)
+  let globalErrorLine = '';
+  if (tree.globalError) {
+    const v = addImport(tree.globalError);
+    globalErrorLine = `  globalError: { load: ${v}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
+  }
+
   // Interception rewrites — computed at build time from the route tree.
   // Only interceptedPattern and interceptingPrefix are needed at runtime.
   const rewrites = collectInterceptionRewrites(tree.root);
@@ -406,7 +586,9 @@ function generateManifestModule(tree: RouteTree): string {
     ...imports,
     '',
     'const manifest = {',
+    `  viteRoot: ${JSON.stringify(viteRoot)},`,
     proxyLine,
+    globalErrorLine,
     rewritesLine,
     `  root: ${rootSerialized},`,
     '};',

package/src/plugins/server-action-exports.ts

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 import { Parser } from 'acorn';
 import acornJsx from 'acorn-jsx';
-import { detectFileDirective } from '#/utils/directive-parser.js';
+import { detectFileDirective } from '../utils/directive-parser.js';
 
 const jsxParser = Parser.extend(acornJsx());
 

package/src/plugins/server-bundle.ts

@@ -137,5 +137,36 @@ export function timberServerBundle(): Plugin[] {
     },
   };
 
-  return [bundlePlugin, esmInitFixPlugin];
+  // Fix Rolldown's `createRequire(import.meta.url)` CJS interop shim for
+  // Cloudflare Workers. Rolldown emits this for CJS dependencies (e.g.
+  // @opentelemetry/context-async-hooks) that use `require()`. On Workers,
+  // `import.meta.url` is `undefined` for non-entry modules, causing:
+  //   TypeError: The argument 'path' must be a file URL object, a file URL
+  //   string, or an absolute path string. Received 'undefined'
+  //
+  // The fix: provide a fallback URL when `import.meta.url` is undefined.
+  // The actual URL doesn't matter — `createRequire` only needs it for
+  // resolving relative paths, but the only `__require()` calls are for
+  // Node built-ins (events, async_hooks) which resolve from any base.
+  //
+  // The top-level `ssr: { target: 'webworker' }` was supposed to prevent
+  // this, but it doesn't propagate to custom environments (rsc) in Vite's
+  // Environment API. See LOCAL-405.
+  const createRequireFixPlugin: Plugin = {
+    name: 'timber-create-require-fix',
+    applyToEnvironment(environment) {
+      return environment.name === 'rsc' || environment.name === 'ssr';
+    },
+    renderChunk(code) {
+      const pattern = 'createRequire(import.meta.url)';
+      if (!code.includes(pattern)) return null;
+
+      return {
+        code: code.replace(pattern, 'createRequire(import.meta.url || "file:///app")'),
+        map: null,
+      };
+    },
+  };
+
+  return [bundlePlugin, esmInitFixPlugin, createRequireFixPlugin];
 }

package/src/plugins/shims.ts

@@ -5,10 +5,11 @@
  * 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.
- * 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).
+ * This plugin also remaps ALL @timber-js/app/* subpath imports to src/ in
+ * server environments (RSC + SSR). This is required because dist/ chunks
+ * are pre-built and miss Vite's RSC transforms (e.g. createContext from
+ * 'react' doesn't exist in RSC's React build). It also ensures a single
+ * module instance for shared mutable state. See SUBPATH_SRC_MAP and TIM-568.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
@@ -16,7 +17,7 @@
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Detect whether we're running from source (src/plugins/) or dist (dist/).
@@ -38,6 +39,24 @@ const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 const SERVER_ONLY_VIRTUAL = '\0timber:server-only';
 const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
 
+/**
+ * Map from @timber-js/app/<subpath> to relative src/ file paths.
+ *
+ * Used by the catch-all resolveId rule to remap subpath imports to src/
+ * in server environments. When adding a new subpath export to package.json,
+ * add it here too. See TIM-568.
+ */
+const SUBPATH_SRC_MAP: Record<string, string> = {
+  'cache': 'cache/index.ts',
+  'cookies': 'cookies/index.ts',
+  'search-params': 'search-params/index.ts',
+  'segment-params': 'segment-params/index.ts',
+
+  'adapters/cloudflare': 'adapters/cloudflare.ts',
+  'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
+  'adapters/nitro': 'adapters/nitro.ts',
+};
+
 /**
  * Map from next/* import specifiers to shim file paths.
  *
@@ -49,10 +68,14 @@ const SHIM_MAP: Record<string, string> = {
   'next/image': resolve(SHIMS_DIR, 'image.ts'),
   'next/navigation': resolve(SHIMS_DIR, 'navigation.ts'),
   'next/headers': resolve(SHIMS_DIR, 'headers.ts'),
-  // next/font/* redirects to the timber-fonts virtual modules.
-  // The fonts plugin's load hook serves the actual module code.
+  // next/font/* and @timber-js/app/fonts/* redirect to the timber-fonts
+  // virtual modules. The fonts plugin's load hook serves the actual module
+  // code. The package.json exports point to shim stubs for non-Vite contexts
+  // (tsc, tests), but in Vite the virtual module takes priority via this map.
   'next/font/google': '\0@timber/fonts/google',
   'next/font/local': '\0@timber/fonts/local',
+  '@timber-js/app/fonts/google': '\0@timber/fonts/google',
+  '@timber-js/app/fonts/local': '\0@timber/fonts/local',
 };
 
 /**
@@ -88,14 +111,14 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * 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
-     * a single requestContextAls and _getRscFallback variable.
+     * All @timber-js/app/* subpath imports resolve to dist/ via package.json
+     * exports in all environments. This ensures a single module instance
+     * for each module — the dist/ chunks share code via rollup's code
+     * splitting. No src/ remapping is needed (see TIM-568).
      *
-     * @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.
+     * The only exception is @timber-js/app/server in the client (browser)
+     * environment, which returns a virtual stub — server code must never
+     * be bundled into the browser.
      */
     resolveId(id: string) {
       // Poison pill packages — resolve to virtual modules handled by load()
@@ -117,38 +140,110 @@ export function timberShims(_ctx: PluginContext): Plugin {
         return SHIM_MAP[cleanId];
       }
 
-      // @timber-js/app/server → src/ in server environments so user code
-      // shares the same module instance as framework internals (single ALS).
-      // In the client environment, return a virtual empty module — server
-      // code must never be bundled into the browser.
+      // ── @timber-js/app/* → src/ resolution in server environments ──
+      //
+      // All @timber-js/app/* subpath imports are remapped to src/ in server
+      // environments (RSC + SSR). This is required for two reasons:
+      //
+      // 1. RSC correctness: dist/ chunks eagerly import from 'react' (e.g.
+      //    createContext in segment-context) which doesn't exist in RSC's
+      //    React build. Vite's RSC plugin only transforms src/ files —
+      //    dist/ chunks are pre-built and served as-is.
+      //
+      // 2. Module singleton correctness: framework internals use relative
+      //    imports that resolve within src/. If user code resolved to dist/
+      //    while framework code resolved to src/, mutable module-level state
+      //    (ALS refs, registered callbacks) would be duplicated. By remapping
+      //    all @timber-js/app/* to src/, everything shares one module graph.
+      //
+      // Exception: @timber-js/app/client in RSC resolves to dist/ where
+      // 'use client' is preserved for client boundary detection.
+      //
+      // In the client (browser) environment, all imports resolve to dist/
+      // via package.json exports (no remapping needed).
+
+      // ── #imports resolution for package-internal modules ─────────────
+      //
+      // #server-internal and #client-internal are Node package imports
+      // (package.json "imports" field). They are only resolvable from
+      // within this package — external consumers get module-not-found.
+      //
+      // In Vite, we intercept them here to resolve to src/ for dev/build
+      // correctness (same rationale as the @timber-js/app/* remap above).
+      if (cleanId === '#server-internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '#client-internal') {
+        // Always resolve to src/ — all environments (RSC, SSR, client)
+        // use src/ for framework internals. In the client env, this
+        // ensures browser-entry and @timber-js/app/client share the
+        // same module graph (both resolve to src/).
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
+      if (cleanId === '#routing') {
+        return resolve(PKG_ROOT, 'src', 'routing', 'index.ts');
+      }
+
+      // Legacy aliases — vitest and monorepo configs may still reference
+      // the old @timber-js/app/server/internal and @timber-js/app/client/internal
+      // specifiers via resolve.alias. When those aliases resolve to the
+      // absolute src/ path, they bypass this plugin entirely. But if the
+      // specifier reaches us unresolved (e.g., in a Vite build without
+      // aliases), handle it the same way as the #imports above.
+      if (cleanId === '@timber-js/app/server/internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '@timber-js/app/client/internal') {
+        // Same as #client-internal above — always resolve to src/.
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
       if (cleanId === '@timber-js/app/server') {
         const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
         if (envName === 'client') {
           return '\0timber:server-empty';
         }
+        // RSC + SSR: remap to src/
         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') {
+        // RSC: return null — needs dist/ for 'use client' boundary detection.
+        // SSR + Client: resolve to src/ so that browser-entry (which uses
+        // relative imports from src/) and user code (which uses the bare
+        // specifier @timber-js/app/client) share the same module instances.
+        // Without this, state.ts is loaded twice (src/ and dist/) and
+        // setGlobalRouter() writes to one copy while getRouterOrNull()
+        // reads from the other (always null).
+        if (envName === 'ssr' || envName === 'client') {
           return resolve(PKG_ROOT, 'src', 'client', 'index.ts');
         }
+        return null;
+      }
+
+      // Catch-all: remap any other @timber-js/app/<subpath> to src/
+      // in non-client environments (RSC + SSR).
+      if (cleanId.startsWith('@timber-js/app/') && cleanId !== '@timber-js/app/package.json') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName !== 'client') {
+          const subpath = cleanId.slice('@timber-js/app/'.length);
+          const srcPath = SUBPATH_SRC_MAP[subpath];
+          if (srcPath) {
+            return resolve(PKG_ROOT, 'src', srcPath);
+          }
+        }
       }
 
       return null;
@@ -202,6 +297,12 @@ const msg = "[timber] @timber-js/app/server was imported from client code. " +
 function stub() { throw new Error(msg); }
 export const headers = stub;
 export const cookies = stub;
+export const getHeaders = stub;
+export const getHeader = stub;
+export const getCookies = stub;
+export const getCookie = stub;
+export const getSearchParams = stub;
+export const getSegmentParams = stub;
 export const searchParams = stub;
 export const deny = stub;
 export const notFound = stub;
@@ -209,7 +310,7 @@ export const redirect = stub;
 export const permanentRedirect = stub;
 export const redirectExternal = stub;
 export const waitUntil = stub;
-export const RenderError = stub;
+export const DenyOptions = {};
 export const RedirectType = {};
 export const DenySignal = stub;
 export const RedirectSignal = stub;