@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.147

package/src/plugins/cache.ts

@@ -10,9 +10,36 @@
  * The plugin transforms:
  *   cache(fn, opts)  →  cache(fn, opts, "stable-id")
  *
- * where stable-id = fnv1a(relativeModulePath + ":cache:" + callIndex).
+ * where stable-id =
+ *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
  *
- * See TIM-997, design/06-caching.md §"Cache Key Security".
+ * stmtText is the source text of the enclosing *top-level statement* and
+ * callSpanText is the source text of the cache(...) call expression itself.
+ *
+ * The ID is derived from the *content* of the call, not its ordinal position
+ * in the file. A position-based index (the original TIM-997 scheme) was stable
+ * within one build but shifted across builds: inserting, deleting, or
+ * reordering a cache() call changed the index of every call below it, so with
+ * a persistent shared CacheHandler (Redis/KV) a new function could inherit
+ * another function's old ID and serve its persisted data — cross-deploy cache
+ * poisoning (TIM-1053). Content hashing makes IDs immune to reordering and
+ * unrelated edits, while a changed call gets a fresh ID — which is exactly
+ * when invalidation is wanted.
+ *
+ * The enclosing-statement text is included so that byte-identical cache()
+ * calls in different scopes — e.g. two factory helpers that each `return
+ * cache(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * enclosing declarations differ by name/body even when the call spans are
+ * identical. Without it, a source-order occurrence counter alone would shift
+ * when an identical span is inserted above, reassigning IDs across deploys.
+ * Calls that are byte-identical INCLUDING their enclosing top-level statement
+ * are disambiguated by a source-order occurrence index. That residue is safe:
+ * identical top-level declarations are a redeclaration error, so fully
+ * identical (statement, call) pairs can only be expression statements
+ * referencing the same bindings — the same function, where an ID swap is
+ * harmless.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
  */
 
 import { relative } from 'node:path';
@@ -118,16 +145,30 @@ function findCacheCallSites(
 }
 
 /**
- * Generate a stable callsite ID from a module path and call index.
+ * Generate a stable callsite ID from a module path, the source text of the
+ * enclosing top-level statement, the source text of the cache(...) call
+ * expression, and an occurrence index among fully byte-identical
+ * (statement, call) pairs in the same file.
  *
- * The ID is an FNV-1a hash of the relative module path + call index,
- * providing a deterministic identifier that is:
- * - Stable across cold starts of the same build
- * - Unique across different modules
- * - Unique across multiple cache() calls within the same module
+ * The ID is deterministic and:
+ * - Stable across cold starts AND across builds/deploys for unchanged calls —
+ *   inserting, deleting, or reordering other cache() calls does not affect it
+ * - Unique across different modules (relPath component)
+ * - Unique across distinct cache() calls within a module (statement + span
+ *   hashes), with fully identical duplicates disambiguated by source-order
+ *   occurrence
+ * - Fresh when the wrapped fn, opts, or enclosing statement change, which
+ *   intentionally invalidates the old persisted entries
  */
-function generateStableId(relativeModulePath: string, callIndex: number): string {
-  return fnv1aHash(`${relativeModulePath}:cache:${callIndex}`);
+function generateStableId(
+  relativeModulePath: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number
+): string {
+  return fnv1aHash(
+    `${relativeModulePath}:cache:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`
+  );
 }
 
 export function timberCacheTransform(ctx: PluginContext): Plugin {
@@ -149,23 +190,40 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
       const cacheBindings = findCacheBindings(program);
       if (cacheBindings.size === 0) return;
 
-      const callSites: CallExpressionNode[] = [];
-      findCacheCallSites(program, cacheBindings, callSites);
+      // Collect call sites per top-level statement so each call carries its
+      // enclosing statement's source text into the ID hash.
+      const callSites: Array<{ call: CallExpressionNode; stmt: PositionedNode }> = [];
+      for (const stmt of program.body) {
+        const calls: CallExpressionNode[] = [];
+        findCacheCallSites(stmt, cacheBindings, calls);
+        for (const call of calls) callSites.push({ call, stmt });
+      }
       if (callSites.length === 0) return;
 
-      // Sort by position in file for deterministic call indices
-      callSites.sort((a, b) => a.start - b.start);
+      // Sort by position in file so occurrence indices among byte-identical
+      // (statement, call) pairs are assigned in deterministic source order
+      callSites.sort((a, b) => a.call.start - b.call.start);
 
       const root = ctx.root || process.cwd();
       const relPath = relative(root, id);
       const s = new MagicString(code);
-
-      for (let i = 0; i < callSites.length; i++) {
-        const call = callSites[i];
-        const stableId = generateStableId(relPath, i);
-        // Insert the stable ID as the 3rd argument just before the closing ')'
-        const insertPos = call.end - 1;
-        s.appendLeft(insertPos, `, "${stableId}"`);
+      const occurrences = new Map<string, number>();
+
+      for (const { call, stmt } of callSites) {
+        const stmtText = code.slice(stmt.start, stmt.end);
+        const spanText = code.slice(call.start, call.end);
+        const dupKey = stmtText + String.fromCharCode(0) + spanText;
+        const occurrence = occurrences.get(dupKey) ?? 0;
+        occurrences.set(dupKey, occurrence + 1);
+        const stableId = generateStableId(relPath, stmtText, spanText, occurrence);
+        // Insert the stable ID as the 3rd argument directly after the last
+        // argument — NOT before the closing ')'. The call may already have a
+        // trailing comma after the options argument (Prettier v3 default for
+        // multiline calls); inserting before ')' would emit `,, "id"`, a
+        // parse error (TIM-1021). A trailing comma after the inserted
+        // argument remains valid JS.
+        const lastArg = call.arguments[call.arguments.length - 1];
+        s.appendLeft(lastArg.end, `, "${stableId}"`);
       }
 
       return {

package/src/plugins/cloudflare-wasm.ts

@@ -10,11 +10,15 @@
  * 2. Externalizes `.wasm` imports so Rolldown skips them
  * 3. Copies the WASM files to the build output so wrangler can find them
  *
- * Only active for Cloudflare adapter production builds.
+ * Only active for Cloudflare adapter production builds — every hook bails
+ * unless `isCloudflareBuild` was set in configResolved. In dev and non-CF
+ * builds, `.wasm` imports are left to Vite's own handling (?init / ?url or
+ * a clear build error), never silently externalized.
  */
 
 import { basename, resolve, dirname } from 'node:path';
-import { copyFile, mkdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
 import type { Plugin, ResolvedConfig } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 
@@ -24,8 +28,13 @@ function isCloudflareAdapter(ctx: PluginContext): boolean {
 }
 
 export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
-  // Track resolved WASM file paths so we can copy them to the output
+  // Resolved WASM files, keyed by absolute source path so two files that
+  // share a basename (e.g. lib_bg.wasm from two packages) don't collide.
+  // The value is the unique output basename used for the external import
+  // specifier and the copy destination.
   const wasmFiles = new Map<string, string>();
+  const usedBasenames = new Set<string>();
+  let isCloudflareBuild = false;
 
   const plugin: Plugin = {
     name: 'timber-cloudflare-wasm',
@@ -33,6 +42,7 @@ export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
     configResolved(resolved: ResolvedConfig) {
       if (resolved.command !== 'build') return;
       if (!isCloudflareAdapter(ctx)) return;
+      isCloudflareBuild = true;
 
       // Prepend `workerd` to resolve conditions for server environments
       // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
@@ -49,9 +59,23 @@ export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
       }
     },
 
+    // Strip /* @vite-ignore */ from @takumi-rs/wasm dynamic imports so
+    // Rolldown bundles them instead of leaving bare specifiers that fail
+    // at runtime on Cloudflare Workers (no node_modules).
+    transform(code, id) {
+      if (!isCloudflareBuild) return;
+      if (!id.includes('takumi')) return;
+      const stripped = code.replaceAll(
+        /\/\*\s*@vite-ignore\s*\*\/\s*\n\s*"@takumi-rs\/wasm"/g,
+        '"@takumi-rs/wasm"'
+      );
+      if (stripped !== code) return stripped;
+    },
+
     resolveId: {
       order: 'pre',
       async handler(source, importer) {
+        if (!isCloudflareBuild) return;
         if (!source.endsWith('.wasm')) return;
 
         let absolutePath: string;
@@ -61,14 +85,28 @@ export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
           return;
         }
 
-        const filename = basename(absolutePath);
-        wasmFiles.set(filename, absolutePath);
+        let outputName = wasmFiles.get(absolutePath);
+        if (!outputName) {
+          outputName = basename(absolutePath);
+          if (usedBasenames.has(outputName)) {
+            // Another wasm file already claimed this basename — disambiguate
+            // with a short content hash so both files land in the output.
+            const hash = createHash('sha256')
+              .update(await readFile(absolutePath))
+              .digest('hex')
+              .slice(0, 8);
+            outputName = outputName.replace(/\.wasm$/, `.${hash}.wasm`);
+          }
+          usedBasenames.add(outputName);
+          wasmFiles.set(absolutePath, outputName);
+        }
 
-        return { id: './' + filename, external: true };
+        return { id: './' + outputName, external: true };
       },
     },
 
     async writeBundle(options, bundle) {
+      if (!isCloudflareBuild) return;
       if (wasmFiles.size === 0) return;
 
       const outDir = options.dir;
@@ -79,8 +117,8 @@ export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
       const targetDirs = new Set<string>();
       for (const chunk of Object.values(bundle)) {
         if (chunk.type !== 'chunk') continue;
-        for (const filename of wasmFiles.keys()) {
-          if (chunk.code.includes(filename)) {
+        for (const outputName of wasmFiles.values()) {
+          if (chunk.code.includes(outputName)) {
             targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
           }
         }
@@ -91,8 +129,8 @@ export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
       const copies: Promise<void>[] = [];
       for (const dir of targetDirs) {
         await mkdir(dir, { recursive: true });
-        for (const [filename, absolutePath] of wasmFiles) {
-          copies.push(copyFile(absolutePath, resolve(dir, filename)));
+        for (const [absolutePath, outputName] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, outputName)));
         }
       }
       await Promise.all(copies);

package/src/plugins/dev-server.ts

@@ -14,6 +14,7 @@
 
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { TLSSocket } from 'node:tls';
 import { join } from 'node:path';
 import type { PluginContext } from '../plugin-context.js';
 import { setViteServer } from '../dev-tools/warnings.js';
@@ -24,11 +25,8 @@ import {
   parseFirstAppFrame,
   type ErrorPhase,
 } from '../dev-tools/overlay.js';
-import {
-  generateDevErrorPage,
-  extractHmrOptions,
-  type DevErrorHmrOptions,
-} from '../dev-tools/error-page.js';
+import { generateDevErrorPage } from '../dev-tools/error-page.js';
+import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.js';
 import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
 import { isMetadataRouteServePath } from '../server/metadata-routes.js';
@@ -207,6 +205,7 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
                 stack: unknown[] | null;
               }>
             ) => void;
+            devHmrOptions?: DevErrorHmrOptions;
           }
         | undefined;
       if (config) {
@@ -219,6 +218,11 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
             debugComponents
           );
         };
+        // Plumb the resolved HMR options into the RSC environment. The RSC
+        // entry can't read the Vite server config (separate module graph),
+        // but its dev 404 page and fallback error page need the HMR endpoint
+        // (including Vite 8's required WS token) for auto-reload (TIM-1067).
+        config.devHmrOptions = hmrOptions;
       }
 
       // Wire source-map handler so error pages show original positions.
@@ -357,15 +361,30 @@ function addTimberContext(error: Error): void {
  *
  * Constructs the full URL from the Host header and request URL,
  * and forwards the method, headers, and body.
+ *
+ * The scheme comes from the socket's TLS state — with `server.https` the
+ * browser sends `Origin: https://host`, and a hardcoded `http://` would
+ * fail CSRF origin comparison on every POST. X-Forwarded-Proto is NOT
+ * consulted: dev connections are direct, so the header would be
+ * attacker-controlled. (TIM-1067, B32)
+ *
+ * Exported for tests.
  */
-function toWebRequest(nodeReq: IncomingMessage): Request {
-  const protocol = 'http';
-  const host = nodeReq.headers.host ?? 'localhost';
+export function toWebRequest(nodeReq: IncomingMessage): Request {
+  const protocol = (nodeReq.socket as TLSSocket | undefined)?.encrypted ? 'https' : 'http';
+  // Under HTTP/2 there is no Host header — the authority lives in the
+  // `:authority` pseudo-header.
+  const host =
+    nodeReq.headers.host ?? (nodeReq.headers[':authority'] as string | undefined) ?? 'localhost';
   const url = `${protocol}://${host}${nodeReq.url}`;
 
   const headers = new Headers();
   for (const [key, value] of Object.entries(nodeReq.headers)) {
     if (value === undefined) continue;
+    // HTTP/2 pseudo-headers (:method, :path, :authority, :scheme) are not
+    // valid Headers names — Headers.set() throws on them. They're already
+    // reflected in the request URL/method above.
+    if (key.startsWith(':')) continue;
     if (Array.isArray(value)) {
       for (const v of value) {
         headers.append(key, v);
@@ -374,6 +393,11 @@ function toWebRequest(nodeReq: IncomingMessage): Request {
       headers.set(key, value);
     }
   }
+  // HTTP/2 requests carry the authority in `:authority`, not Host — but
+  // downstream consumers (CSRF origin validation) read the Host header.
+  if (!headers.has('host')) {
+    headers.set('host', host);
+  }
 
   const method = nodeReq.method ?? 'GET';
   const hasBody = method !== 'GET' && method !== 'HEAD';

package/src/plugins/server-bundle.ts

@@ -11,8 +11,14 @@
  * Design docs: design/11-platform.md, design/25-production-deployments.md
  */
 
+import { builtinModules } from 'node:module';
 import type { Plugin } from 'vite';
 
+// Every Node built-in as both bare (`stream`) and prefixed (`node:stream`).
+// Available at runtime on all targets (Node natively, Workers via nodejs_compat).
+// Listing explicitly silences Vite's "Automatically externalized" warnings.
+const NODE_BUILTINS: string[] = builtinModules.flatMap((m) => [m, `node:${m}`]);
+
 // Build-time-only packages that must never be bundled into the runtime
 // server environments. With `noExternal: true` rolldown otherwise follows
 // the transitive graph through the user's `timber.config.ts` (loaded by the
@@ -31,6 +37,7 @@ import type { Plugin } from 'vite';
 //
 // Mirrored on both rsc and ssr environments. See TIM-988.
 const BUILD_ONLY_EXTERNALS: string[] = [
+  ...NODE_BUILTINS,
   'nitro',
   'rollup',
   '@mdx-js/rollup',
@@ -128,15 +135,18 @@ export function timberServerBundle(): Plugin[] {
   // back to lazy retry on failure. This handles two failure modes:
   //
   // 1. Forward references (e.g. Zod v4): `init_iso` calls `init_schemas`
-  //    which hasn't been defined yet. Eager execution fails, but when the
-  //    function is called lazily later, all dependencies are available.
+  //    which hasn't been defined yet. Eager execution fails silently, but
+  //    when the function is called lazily later, all dependencies are
+  //    available and the retry succeeds (and caches).
   //
   // 2. Optional peer dep shims (e.g. @emotion/is-prop-valid for
   //    framer-motion): Vite generates shims that throw for missing
-  //    optional deps. The throw is deferred to lazy execution where
-  //    the consuming package's try/catch handles it.
+  //    optional deps. The eager attempt swallows the throw; the lazy call
+  //    PROPAGATES it so the consuming package's try/catch handles it.
   //
-  // The key: on failure, `fn` is NOT cleared, so the next call retries.
+  // The key: only the eager attempt swallows errors. Once the helper is
+  // returned, lazy calls use the original Rolldown semantics — a throwing
+  // init propagates to the caller (and clears `fn`, matching upstream).
   // On success, `fn` is set to 0 so subsequent calls are no-ops.
   const esmInitFixPlugin: Plugin = {
     name: 'timber-esm-init-fix',
@@ -147,13 +157,19 @@ export function timberServerBundle(): Plugin[] {
       const lazy = 'var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);';
       if (!code.includes(lazy)) return null;
 
-      // Eager-with-retry: attempt init immediately. On success, mark done
-      // (fn = 0). On failure, leave fn intact so the lazy wrapper retries
-      // on next call — by then forward dependencies are initialized.
+      // Eager-with-retry: attempt init immediately, swallowing failures
+      // (forward refs aren't defined yet). After the eager attempt, flip
+      // to lazy mode where errors propagate to the caller — consumers'
+      // try/catch (framer-motion's optional @emotion dep) must see them.
       const eager = [
         'var __esmMin = (fn, res) => {',
-        '  var l = () => { if (fn) { var f = fn; try { res = f(); fn = 0; } catch(e) {} } return res; };',
+        '  var eager = 1;',
+        '  var l = () => {',
+        '    if (fn) { if (eager) { try { res = fn(); fn = 0; } catch(e) {} } else { res = fn(fn = 0); } }',
+        '    return res;',
+        '  };',
         '  l();',
+        '  eager = 0;',
         '  return l;',
         '};',
       ].join(' ');

package/src/plugins/shims.ts

@@ -44,19 +44,67 @@ const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
  *
  * 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.
+ * add it here too — tests/shims-drift.test.ts enumerates package.json
+ * exports and fails if an entry is missing. See TIM-568.
+ *
+ * Exported for the drift test.
  */
-const SUBPATH_SRC_MAP: Record<string, string> = {
+export const SUBPATH_SRC_MAP: Record<string, string> = {
   'cache': 'cache/index.ts',
+  'codec': 'codec.ts',
   'cookies': 'cookies/index.ts',
+  'params': 'params/index.ts',
   'search-params': 'search-params/index.ts',
   'segment-params': 'segment-params/index.ts',
 
   'adapters/cloudflare': 'adapters/cloudflare.ts',
+  'adapters/cloudflare/cache': 'adapters/cloudflare-kv-cache.ts',
   'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
   'adapters/nitro': 'adapters/nitro.ts',
 };
 
+/**
+ * Runtime value exports of @timber-js/app/server, stubbed in the client
+ * (browser) environment so a stray client-side import fails with a clear
+ * call-time error instead of a confusing bundler error.
+ *
+ * Must stay in sync with the actual runtime exports of server/index.ts —
+ * tests/shims-drift.test.ts compares this list against
+ * Object.keys(import('../server/index.ts')) and fails on drift.
+ * Type-only exports (DenyOptions, AccessContext, …) are erased at runtime
+ * and must NOT appear here.
+ */
+export const SERVER_STUB_EXPORTS: readonly string[] = [
+  // request-context
+  'getHeaders',
+  'getSegmentParams',
+  // cookie-context
+  'getCookieJar',
+  // primitives
+  'deny',
+  'redirect',
+  'redirectExternal',
+  'RedirectType',
+  'waitUntil',
+  // action-client
+  'createActionClient',
+  'ActionError',
+  'validated',
+  // form-data
+  'coerce',
+  'parseFormData',
+  // form-flash
+  'getFormFlash',
+  // revalidation
+  'revalidatePath',
+  'revalidateTag',
+  // tracing
+  'getTraceId',
+  'getSpanId',
+  'withSpan',
+  'addSpanEvent',
+];
+
 /**
  * Map from next/* import specifiers to shim file paths.
  *
@@ -88,6 +136,16 @@ function stripJsExtension(id: string): string {
   return id.endsWith('.js') ? id.slice(0, -3) : id;
 }
 
+/**
+ * Read the Vite environment name from a plugin hook's `this` context.
+ *
+ * Duck-typed because the hook context type doesn't expose `environment`
+ * in a way that survives our Plugin typing — see Vite's Environment API.
+ */
+function envName(hookCtx: unknown): string | undefined {
+  return (hookCtx as { environment?: { name?: string } }).environment?.name;
+}
+
 /**
  * Create the timber-shims Vite plugin.
  *
@@ -111,14 +169,16 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * 3. Check next/* shim map
      * 4. Return null (pass through) for everything else
      *
-     * 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).
+     * In server environments (RSC + SSR), @timber-js/app/* subpath imports
+     * are remapped to src/ via SUBPATH_SRC_MAP and the explicit branches
+     * below — dist/ chunks miss Vite's RSC transforms and would duplicate
+     * mutable module state (see TIM-568 and the rationale comments below).
      *
-     * 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.
+     * In the client (browser) environment, imports resolve to dist/ via
+     * package.json exports — except @timber-js/app/client (remapped to src/
+     * to share module instances with browser-entry) and @timber-js/app/server,
+     * 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()
@@ -133,8 +193,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // 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 === 'next/navigation') {
+        const env = envName(this);
+        if (env === 'client' && cleanId === 'next/navigation') {
           return resolve(SHIMS_DIR, 'navigation-client.ts');
         }
         return SHIM_MAP[cleanId];
@@ -171,8 +231,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // 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') {
+        const env = envName(this);
+        if (env === 'client') {
           return '\0timber:server-empty';
         }
         return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
@@ -197,8 +257,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // 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') {
+        const env = envName(this);
+        if (env === 'client') {
           return '\0timber:server-empty';
         }
         return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
@@ -210,8 +270,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
       }
 
       if (cleanId === '@timber-js/app/server') {
-        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'client') {
+        const env = envName(this);
+        if (env === 'client') {
           return '\0timber:server-empty';
         }
         // RSC + SSR: remap to src/
@@ -219,7 +279,7 @@ export function timberShims(_ctx: PluginContext): Plugin {
       }
 
       if (cleanId === '@timber-js/app/client') {
-        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        const env = envName(this);
         // 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
@@ -227,7 +287,7 @@ export function timberShims(_ctx: PluginContext): Plugin {
         // 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') {
+        if (env === 'ssr' || env === 'client') {
           return resolve(PKG_ROOT, 'src', 'client', 'index.ts');
         }
         return null;
@@ -236,8 +296,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // 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 env = envName(this);
+        if (env !== 'client') {
           const subpath = cleanId.slice('@timber-js/app/'.length);
           const srcPath = SUBPATH_SRC_MAP[subpath];
           if (srcPath) {
@@ -257,8 +317,8 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * clearly identifies the boundary violation.
      */
     load(id: string) {
-      const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-      const isClient = envName === 'client';
+      const env = envName(this);
+      const isClient = env === 'client';
 
       if (id === SERVER_ONLY_VIRTUAL) {
         if (isClient) {
@@ -288,41 +348,23 @@ export function timberShims(_ctx: PluginContext): Plugin {
       if (id === '\0timber:server-empty') {
         // Export named stubs instead of throwing at evaluation time.
         // Throwing at eval breaks the module system — the browser can't
-        // resolve named imports like `import { notFound } from '...'`.
+        // resolve named imports like `import { deny } from '...'`.
         // Instead, each stub throws at call time with a clear message.
+        // The export names are generated from SERVER_STUB_EXPORTS so the
+        // list cannot drift from server/index.ts (drift test enforced).
+        // RedirectType is a plain const object on the server, so it is
+        // mirrored as one here — libraries read RedirectType.push as a value.
+        const stubExports = SERVER_STUB_EXPORTS.map((name) =>
+          name === 'RedirectType'
+            ? `export const RedirectType = { push: 'push', replace: 'replace' };`
+            : `export const ${name} = stub;`
+        ).join('\n');
         return `
 const msg = "[timber] @timber-js/app/server was imported from client code. " +
   "Server modules (headers, cookies, redirect, deny, etc.) cannot be used in client components. " +
   "If you need these APIs, move the import to a server component or middleware.";
 function stub() { throw new Error(msg); }
-export const headers = stub;
-export const cookies = stub;
-export const getHeaders = stub;
-export const getHeader = stub;
-export const getCookieJar = 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;
-export const redirect = stub;
-export const permanentRedirect = stub;
-export const redirectExternal = stub;
-export const waitUntil = stub;
-export const DenyOptions = {};
-export const RedirectType = {};
-export const DenySignal = stub;
-export const RedirectSignal = stub;
-export const createPipeline = stub;
-export const revalidatePath = stub;
-export const revalidateTag = stub;
-export const createActionClient = stub;
-export const ActionError = stub;
-export const validated = stub;
-export const getFormFlash = stub;
-export const parseFormData = stub;
-export const coerce = stub;
+${stubExports}
 `;
       }
     },

package/src/routing/codegen-types.ts

@@ -21,6 +21,10 @@ export interface RouteEntry {
   searchParamsPagePath?: string;
   /** Whether this is an API route (route.ts) vs page route */
   isApiRoute: boolean;
+  /** Whether this entry lives inside a parallel slot (@name). Slot entries
+   *  share their parent's urlPath — urlPath-keyed emissions dedupe them,
+   *  preferring the non-slot entry. segmentPath-keyed emissions keep all. */
+  isSlotRoute?: boolean;
   /** Whether a global schema (app/schema.ts) exists for this app */
   hasSchema?: boolean;
 }