@timber-js/app 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/plugins/fonts.ts

@@ -14,13 +14,15 @@
  * Design doc: 24-fonts.md
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
 import type { PluginContext } from '#/index.js';
 import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
 import type { ManifestFontEntry } from '#/server/build-manifest.js';
-import { generateVariableClass, generateFontFamilyClass } from '#/fonts/css.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from '#/fonts/css.js';
 import { generateFallbackCss, buildFontStack } from '#/fonts/fallbacks.js';
-import { processLocalFont } from '#/fonts/local.js';
+import { processLocalFont, generateLocalFontFaces } from '#/fonts/local.js';
 import { inferFontFormat } from '#/fonts/local.js';
 import { downloadAndCacheFonts, type CachedFont } from '#/fonts/google.js';
 import {
@@ -34,6 +36,23 @@ const VIRTUAL_LOCAL = '@timber/fonts/local';
 const RESOLVED_GOOGLE = '\0@timber/fonts/google';
 const RESOLVED_LOCAL = '\0@timber/fonts/local';
 
+/**
+ * Virtual side-effect module that registers font CSS on globalThis.
+ *
+ * When a file calls localFont() or a Google font function, the transform
+ * hook injects `import 'virtual:timber-font-css-register'` into that file.
+ * This virtual module sets `globalThis.__timber_font_css` with the combined
+ * @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
+ *
+ * This approach avoids timing issues because:
+ * 1. The font file is in the RSC module graph (imported by layout.tsx)
+ * 2. The side-effect import is added to the font file during transform
+ * 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
+ * 4. RSC entry renders → reads globalThis → inlines <style>
+ */
+const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
+const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+
 /**
  * Registry of fonts extracted during transform.
  * Keyed by a unique font ID derived from family + config.
@@ -242,27 +261,44 @@ function generateLocalVirtualModule(): string {
   ].join('\n');
 }
 
+/**
+ * Generate CSS for a single extracted font.
+ *
+ * Includes @font-face rules (for local fonts), fallback @font-face,
+ * and the scoped class rule.
+ */
+export function generateFontCss(font: ExtractedFont): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
 /**
  * Generate the CSS output for all extracted fonts.
  *
- * Includes @font-face rules, fallback @font-face rules, and scoped classes.
+ * Includes @font-face rules for local fonts, fallback @font-face rules,
+ * and scoped classes.
  */
 export function generateAllFontCss(registry: FontRegistry): string {
   const cssParts: string[] = [];
-
   for (const font of registry.values()) {
-    // Generate fallback @font-face if metrics are available
-    const fallbackCss = generateFallbackCss(font.family);
-    if (fallbackCss) cssParts.push(fallbackCss);
-
-    // Generate scoped class
-    if (font.variable) {
-      cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
-    } else {
-      cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
-    }
+    cssParts.push(generateFontCss(font));
   }
-
   return cssParts.join('\n\n');
 }
 
@@ -359,23 +395,112 @@ export function timberFonts(ctx: PluginContext): Plugin {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google` and `@timber/fonts/local` to virtual modules.
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`,
+     * and `virtual:timber-font-css` virtual modules.
+     *
+     * Handles \0 prefix and root prefix stripping for RSC/SSR
+     * environments where the RSC plugin re-imports virtual modules
+     * with additional prefixes.
      */
     resolveId(id: string) {
-      if (id === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
-      if (id === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      // Strip \0 prefix (RSC plugin re-imports)
+      let cleanId = id.startsWith('\0') ? id.slice(1) : id;
+      // Strip root prefix (SSR build entries)
+      if (cleanId.startsWith(ctx.root)) {
+        const stripped = cleanId.slice(ctx.root.length);
+        if (stripped.startsWith('/') || stripped.startsWith('\\')) {
+          cleanId = stripped.slice(1);
+        } else {
+          cleanId = stripped;
+        }
+      }
+
+      if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
+      if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
+     *
+     * `virtual:timber-font-css` exports the combined @font-face CSS
+     * as a string. The RSC entry imports it and inlines a <style> tag.
+     * Because this is loaded lazily (on first request), the font
+     * registry is always populated by the time it's needed.
      */
     load(id: string) {
       if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
+
+      if (id === RESOLVED_FONT_CSS_REGISTER) {
+        const css = generateAllFontCss(registry);
+        // Side-effect module: sets font CSS on globalThis for the RSC entry to read.
+        return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+      }
       return null;
     },
 
+    /**
+     * Serve local font files and font CSS in dev mode under `/_timber/fonts/`.
+     *
+     * Serves:
+     * - `/_timber/fonts/fonts.css` — combined @font-face + scoped class CSS
+     * - `/_timber/fonts/<filename>` — individual font files from the registry
+     *
+     * Only files registered in the font registry are served.
+     * Paths are validated to prevent directory traversal.
+     */
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use((req, res, next) => {
+        const url = req.url;
+        if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+        const requestedFilename = url.slice('/_timber/fonts/'.length);
+        // Reject path traversal attempts
+        if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+          res.statusCode = 400;
+          res.end('Bad request');
+          return;
+        }
+
+        // Font CSS is now injected via Vite's CSS pipeline (virtual:timber-font-css modules).
+        // This middleware only serves font binary files (woff2, etc.).
+
+        // Find the matching font file in the registry
+        for (const font of registry.values()) {
+          if (font.provider !== 'local' || !font.localSources) continue;
+          for (const src of font.localSources) {
+            const basename = src.path.split('/').pop() ?? '';
+            if (basename === requestedFilename) {
+              const absolutePath = normalize(resolve(src.path));
+              if (!existsSync(absolutePath)) {
+                res.statusCode = 404;
+                res.end('Not found');
+                return;
+              }
+              const data = readFileSync(absolutePath);
+              const ext = absolutePath.split('.').pop()?.toLowerCase();
+              const mimeMap: Record<string, string> = {
+                woff2: 'font/woff2',
+                woff: 'font/woff',
+                ttf: 'font/ttf',
+                otf: 'font/otf',
+                eot: 'application/vnd.ms-fontopen',
+              };
+              res.setHeader('Content-Type', mimeMap[ext ?? ''] ?? 'application/octet-stream');
+              res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+              res.setHeader('Access-Control-Allow-Origin', '*');
+              res.end(data);
+              return;
+            }
+          }
+        }
+
+        next();
+      });
+    },
+
     /**
      * Download and cache Google Fonts during production builds.
      *
@@ -499,6 +624,11 @@ export function timberFonts(ctx: PluginContext): Plugin {
       }
 
       if (transformedCode !== code) {
+        // Inject side-effect import that registers font CSS on globalThis.
+        // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+        if (registry.size > 0) {
+          transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+        }
         return { code: transformedCode, map: null };
       }
 
@@ -525,6 +655,28 @@ export function timberFonts(ctx: PluginContext): Plugin {
         });
       }
 
+      // Emit local font files as assets
+      for (const font of registry.values()) {
+        if (font.provider !== 'local' || !font.localSources) continue;
+        for (const src of font.localSources) {
+          const absolutePath = normalize(resolve(src.path));
+          if (!existsSync(absolutePath)) {
+            this.warn(`Local font file not found: ${absolutePath}`);
+            continue;
+          }
+          const basename = src.path.split('/').pop() ?? src.path;
+          const data = readFileSync(absolutePath);
+          this.emitFile({
+            type: 'asset',
+            fileName: `_timber/fonts/${basename}`,
+            source: data,
+          });
+        }
+      }
+
+      // Font CSS is emitted by Vite's CSS pipeline via virtual:timber-font-css modules.
+      // We only need to emit font binary files and update the build manifest here.
+
       if (!ctx.buildManifest) return;
 
       // Build a lookup from font family → cached files for manifest entries

package/src/plugins/mdx.ts

@@ -16,19 +16,23 @@ import type { PluginContext } from '#/index.js';
 const MDX_EXTENSIONS = ['mdx', 'md'];
 
 /**
- * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+ * or in src/. Root takes precedence, matching Next.js behavior.
  * Returns the absolute path if found, otherwise undefined.
  */
-function findMdxComponents(root: string): string | undefined {
+export function findMdxComponents(root: string): string | undefined {
   const candidates = [
     'mdx-components.tsx',
     'mdx-components.ts',
     'mdx-components.jsx',
     'mdx-components.js',
   ];
-  for (const name of candidates) {
-    const p = join(root, name);
-    if (existsSync(p)) return p;
+  const dirs = [root, join(root, 'src')];
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const p = join(dir, name);
+      if (existsSync(p)) return p;
+    }
   }
   return undefined;
 }

package/src/plugins/server-bundle.ts

@@ -65,6 +65,10 @@ export function timberServerBundle(): Plugin[] {
       // eliminated by Rollup's tree-shaking. Without this, the runtime
       // check falls through on platforms where process.env is empty
       // (e.g. Cloudflare Workers), causing dev code to run in production.
+      // Define process.env.NODE_ENV so dev-only React code is tree-shaken.
+      // TIMBER_DEBUG is intentionally NOT defined here — it must remain a
+      // runtime check so `isDebug()` in server/debug.ts can read it at
+      // request time. See TIM-365.
       const serverDefine = {
         'process.env.NODE_ENV': JSON.stringify('production'),
       };

package/src/rsc-runtime/ssr.ts

@@ -11,3 +11,53 @@
  */
 
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+
+// ─── Node.js Stream Path ─────────────────────────────────────────────────────
+//
+// On Node.js, createFromNodeStream reads RSC Flight data from a Node.js
+// Readable (C++ backed) instead of a Web ReadableStream (JS reimplementation).
+// Eliminates Promise-per-chunk overhead on the SSR decode path.
+//
+// The plugin only exports createFromReadableStream (via client.edge.js).
+// createFromNodeStream lives in the vendored client.node.js. We import it
+// directly and wire up the same serverConsumerManifest the plugin uses.
+
+import { createServerConsumerManifest } from '@vitejs/plugin-rsc/ssr';
+
+type CreateFromNodeStreamFn = (
+  stream: import('node:stream').Readable,
+  manifest: ReturnType<typeof createServerConsumerManifest>,
+  options?: Record<string, unknown>
+) => React.ReactNode;
+
+let _createFromNodeStream: CreateFromNodeStreamFn | null = null;
+
+try {
+  if (typeof process !== 'undefined' && process.release?.name === 'node') {
+    const clientNode = await import('@vitejs/plugin-rsc/vendor/react-server-dom/client.node');
+    if (typeof clientNode.createFromNodeStream === 'function') {
+      _createFromNodeStream = clientNode.createFromNodeStream;
+    }
+  }
+} catch {
+  // Not available — fall back to createFromReadableStream
+}
+
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export function createFromNodeStream(
+  stream: import('node:stream').Readable
+): React.ReactNode | null {
+  if (!_createFromNodeStream) return null;
+  return _createFromNodeStream(stream, createServerConsumerManifest());
+}
+
+/** Whether the Node.js stream RSC decode path is available. */
+export const hasNodeStreamDecode = _createFromNodeStream !== null;

package/src/rsc-runtime/vendor-types.d.ts

@@ -0,0 +1,7 @@
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.node' {
+  export function createFromNodeStream(
+    stream: import('node:stream').Readable,
+    manifest: unknown,
+    options?: Record<string, unknown>
+  ): React.ReactNode;
+}

package/src/server/access-gate.tsx

@@ -16,6 +16,7 @@
 import { DenySignal, RedirectSignal } from './primitives.js';
 import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
+import { isDebug } from './debug.js';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -114,7 +115,7 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
     // slot would redirect the entire page, which breaks the contract that
     // slot failure is graceful degradation.
     if (error instanceof RedirectSignal) {
-      if (process.env.NODE_ENV !== 'production') {
+      if (isDebug()) {
         console.error(
           '[timber] redirect() is not allowed in slot access.ts. ' +
             'Slots use deny() for graceful degradation — denied.tsx → default.tsx → null. ' +
@@ -127,7 +128,7 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
 
     // Unhandled error — re-throw so error boundaries can catch it.
     // Dev-mode warning: slot access should use deny(), not throw.
-    if (process.env.NODE_ENV !== 'production') {
+    if (isDebug()) {
       console.warn(
         '[timber] Unhandled error in slot access.ts. ' +
           'Use deny() for access control, not unhandled throws.',

package/src/server/action-client.ts

@@ -184,6 +184,7 @@ async function runActionMiddleware<TCtx>(
 // Re-export parseFormData for use throughout the framework
 import { parseFormData } from './form-data.js';
 import { formatSize } from '#/utils/format.js';
+import { isDebug, isDevMode } from './debug.js';
 
 /**
  * Extract validation errors from a schema error.
@@ -246,12 +247,15 @@ export function handleActionError(error: unknown): ActionResult<never> {
     };
   }
 
-  // In dev, include the message for debugging
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  // In dev, include the message for debugging.
+  // Uses isDevMode() — NOT isDebug() — because this data is sent to the
+  // browser. TIMBER_DEBUG must never cause error messages to leak to clients.
+  // See design/13-security.md principle 4: "Errors don't leak."
+  const devMode = isDevMode();
   return {
     serverError: {
       code: 'INTERNAL_ERROR',
-      ...(isDev && error instanceof Error ? { data: { message: error.message } } : {}),
+      ...(devMode && error instanceof Error ? { data: { message: error.message } } : {}),
     },
   };
 }
@@ -291,8 +295,14 @@ export function createActionClient<TCtx = Record<string, never>>(
         // Determine input — either FormData (from useActionState) or direct arg
         let rawInput: unknown;
         if (args.length === 2 && args[1] instanceof FormData) {
-          // Called as (prevState, formData) by React useActionState
+          // Called as (prevState, formData) by React useActionState (with-JS path)
           rawInput = schema ? parseFormData(args[1]) : args[1];
+        } else if (args.length === 1 && args[0] instanceof FormData) {
+          // No-JS path: React's decodeAction binds FormData as the sole argument.
+          // The form POSTs without JavaScript, decodeAction resolves the server
+          // reference and binds the FormData, then executeAction calls fn() with
+          // no additional args — so the bound FormData arrives as args[0].
+          rawInput = schema ? parseFormData(args[0]) : args[0];
         } else {
           // Direct call: action(input)
           rawInput = args[0];
@@ -413,7 +423,7 @@ export function validated<TInput, TData>(
  * In production, validation errors are only returned to the client.
  */
 function logValidationFailure(errors: ValidationErrors): void {
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  const isDev = isDebug();
   if (!isDev) return;
 
   const fields = Object.entries(errors)

package/src/server/debug.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime debug flag for timber.js.
+ *
+ * Two distinct functions for two distinct security levels:
+ *
+ * ## `isDebug()` — server-side logging only
+ *
+ * Returns true when timber's debug/warning messages should be written to
+ * stderr / the server console. This NEVER affects what is sent to the
+ * client (no error details, no timing headers, no stack traces).
+ *
+ * Active when any of:
+ * - `NODE_ENV !== 'production'` (standard dev mode)
+ * - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+ * - `timber.config.ts` has `debug: true`
+ *
+ * ## `isDevMode()` — client-visible dev behavior
+ *
+ * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+ * that changes what clients can observe:
+ * - Dev error pages with stack traces (fallback-error.ts)
+ * - Detailed Server-Timing headers (pipeline.ts)
+ * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * `isDevMode()` is statically replaced in production builds → the guarded
+ * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+ *
+ * Usage:
+ *   In Cloudflare Workers wrangler.toml:
+ *     [vars]
+ *     TIMBER_DEBUG = "1"
+ *
+ *   In Node.js:
+ *     TIMBER_DEBUG=1 node server.js
+ *
+ *   In timber.config.ts:
+ *     export default { debug: true }
+ *
+ * See design/13-security.md for the security taxonomy.
+ * See design/18-build-system.md for build pipeline details.
+ */
+
+// ─── Dev Mode (client-visible) ──────────────────────────────────────────────
+
+/**
+ * Check if the application is running in development mode.
+ *
+ * This is the ONLY function that should gate client-visible dev behavior:
+ * - Dev error pages with stack traces
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+ * - Error messages in action `INTERNAL_ERROR` payloads
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * Returns `process.env.NODE_ENV !== 'production'`, which is statically
+ * replaced by the bundler in production builds. Code guarded by this
+ * function is tree-shaken to zero bytes in production.
+ *
+ * TIMBER_DEBUG does NOT enable this — that would leak server internals
+ * to clients. Use `isDebug()` for server-side-only logging.
+ */
+export function isDevMode(): boolean {
+  return process.env.NODE_ENV !== 'production';
+}
+
+// ─── Debug Flag (server-side logging only) ──────────────────────────────────
+
+/**
+ * Config-level debug override. Set via `setDebugFromConfig()` during
+ * initialization when timber.config.ts has `debug: true`.
+ */
+let _configDebug = false;
+
+/**
+ * Set the debug flag from timber.config.ts.
+ * Called during handler initialization.
+ */
+export function setDebugFromConfig(debug: boolean): void {
+  _configDebug = debug;
+}
+
+/**
+ * Check if timber debug logging is active (server-side only).
+ *
+ * Returns true if ANY of these conditions hold:
+ * - NODE_ENV is not 'production' (standard dev mode)
+ * - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+ * - timber.config.ts has `debug: true`
+ *
+ * This function controls ONLY server-side logging — messages written to
+ * stderr or the server console. It NEVER affects client-visible behavior
+ * (error pages, response headers, action payloads). For client-visible
+ * behavior, use `isDevMode()`.
+ *
+ * The TIMBER_DEBUG check is deliberately written as a dynamic property
+ * access so bundlers cannot statically replace it.
+ */
+export function isDebug(): boolean {
+  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)
+  if (process.env.NODE_ENV !== 'production') return true;
+
+  // Config override
+  if (_configDebug) return true;
+
+  // Runtime env var check — uses dynamic access to prevent static replacement.
+  // In production builds, process.env.NODE_ENV is statically replaced, but
+  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access
+  // pattern ensures the bundler treats this as opaque.
+  return _readTimberDebugEnv();
+}
+
+/**
+ * Read TIMBER_DEBUG from the environment at runtime.
+ *
+ * Extracted to a separate function to:
+ * 1. Prevent bundler inlining (cross-module function calls are not inlined)
+ * 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+ * 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+ */
+function _readTimberDebugEnv(): boolean {
+  // globalThis override — useful for programmatic control and testing
+  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;
+
+  // process.env — works in Node.js and platforms that polyfill process
+  try {
+    const key = 'TIMBER_DEBUG';
+    const val =
+      typeof process !== 'undefined' && process.env
+        ? (process.env as Record<string, string | undefined>)[key]
+        : undefined;
+    if (val && val !== '0' && val !== 'false') return true;
+  } catch {
+    // process may not exist or env may throw — safe to ignore
+  }
+
+  return false;
+}

package/src/server/deny-renderer.ts

@@ -20,6 +20,7 @@ import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';
+import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import { resolveManifestStatusFile } from './manifest-status-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
@@ -94,7 +95,7 @@ export async function renderDenyPage(
 
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // This helps developers understand why their .json file isn't being served.
-  if (process.env.NODE_ENV !== 'production') {
+  if (isDebug()) {
     const jsonResolution = resolveManifestStatusFile(deny.status, segments, 'json');
     if (jsonResolution) {
       console.warn(
@@ -133,7 +134,7 @@ export async function renderDenyPage(
       const { component } = layoutsToWrap[i];
       element = h(component, null, element);
     }
-  } else if (process.env.NODE_ENV !== 'production') {
+  } else if (isDebug()) {
     // Dev-mode: warn if shell=false might conflict with Suspense
     // The actual Suspense boundary check happens at render time in the pipeline.
     // This is a preemptive log for developer awareness.

package/src/server/dev-warnings.ts

@@ -15,6 +15,7 @@
  */
 
 import type { ViteDevServer } from 'vite';
+import { isDebug } from './debug.js';
 
 // ─── Warning IDs ───────────────────────────────────────────────────────────
 
@@ -54,7 +55,7 @@ export function setViteServer(server: ViteDevServer | null): void {
 }
 
 function isDev(): boolean {
-  return process.env.NODE_ENV !== 'production';
+  return isDebug();
 }
 
 /**