@rangojs/router 0.0.0-experimental.101 → 0.0.0-experimental.103

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.101",
+  version: "0.0.0-experimental.103",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4861,7 +4861,7 @@ function generateRoutesManifestModule(state) {
       }
     }
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -4897,18 +4897,6 @@ function generateRoutesManifestModule(state) {
         );
       }
     }
-    if (state.isBuildMode) {
-      if (state.mergedPrecomputedEntries && state.mergedPrecomputedEntries.length > 0) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`
-        );
-      }
-    }
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.101",
+  "version": "0.0.0-experimental.103",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/bundle-analysis/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: bundle-analysis
+description: Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.
+argument-hint: "<app-dir>"
+---
+
+# Bundle Analysis
+
+Use this when you want **proof** that your Rango app is shipping the bundles you expect: small client, no server leaks, no doubled React, reasonable RSC worker size.
+
+## What this checks
+
+Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — and each ships its own bundle. The most common bundle bugs in a Rango app are:
+
+1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
+2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare vite plugin folds NODE_ENV automatically; vanilla `vite build` does it for client but not always for SSR/RSC.
+3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
+4. **Inefficient client-reference grouping.** Each `"use client"` boundary becomes a chunk. Too many small client components = many tiny chunks; one giant client component = one giant chunk that defeats code-splitting.
+
+Tree-shaking does _not_ catch (1) generated data inlined as string literals or (2) data-dependent conditionals like React's. You need a visualizer.
+
+## Step 1: Install the visualizer
+
+In your app's directory:
+
+```bash
+pnpm add -D rollup-plugin-visualizer
+# or: npm install --save-dev rollup-plugin-visualizer
+# or: yarn add -D rollup-plugin-visualizer
+```
+
+## Step 2: Wire it into your `vite.config.ts`
+
+Add a small helper that registers one visualizer instance **per Vite environment** (not just one global). The plugin caches its options after the first call, so a single instance can't handle multi-environment builds — you'll get a report for one environment and silence for the others.
+
+```ts
+// vite.config.ts
+import { defineConfig, type PluginOption, type Plugin } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+import { join } from "node:path";
+// ... your other imports ...
+
+function analyze(): PluginOption[] {
+  if (!process.env.ANALYZE) return [];
+  return (["client", "ssr", "rsc"] as const).map((envName) => {
+    const inner = visualizer({
+      filename: join("bundle-stats", `${envName}.html`),
+      template: "treemap",
+      gzipSize: true,
+      brotliSize: true,
+    }) as Plugin;
+    return {
+      ...inner,
+      name: `analyze-${envName}`,
+      applyToEnvironment(env) {
+        return env.name === envName;
+      },
+    } as Plugin;
+  });
+}
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    // your existing plugins...
+    ...analyze(),
+  ],
+  // For non-Cloudflare apps, fold NODE_ENV explicitly so React's CJS files
+  // emit only the .production.js variants in SSR/RSC. Skip if your build
+  // setup already does this (the Cloudflare vite plugin does).
+  define:
+    command === "build"
+      ? { "process.env.NODE_ENV": JSON.stringify("production") }
+      : undefined,
+}));
+```
+
+Add `bundle-stats/` to your `.gitignore`.
+
+## Step 3: Build with the analyzer enabled
+
+```bash
+ANALYZE=1 pnpm exec vite build
+```
+
+You'll get three HTML reports in `bundle-stats/`:
+
+- `bundle-stats/client.html` — what runs in the browser
+- `bundle-stats/ssr.html` — what runs during HTML stream
+- `bundle-stats/rsc.html` — what runs in your RSC server (Worker / Node)
+
+Open them with a quick local server (file:// has CORS issues with the embedded scripts):
+
+```bash
+pnpm dlx serve -l 5050 .
+# then visit http://localhost:5050/bundle-stats/client.html
+```
+
+## Step 4: Triage the reports
+
+### Open `client.html` first
+
+The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/brotli numbers.
+
+**Look for:**
+
+- **Your server code.** Any of your own files that contain database queries, secret keys, server actions implementation (not the action _reference_), or `node:` imports. If they appear in the client treemap with non-zero bytes, they leaked. Common causes:
+  - A shared module that mixes client and server code without a `"use client"` or `"use server"` directive.
+  - A barrel file (`index.ts`) that re-exports both client and server symbols. Tree-shaking should help, but `JSON.parse('{...}')` data and side-effecting top-level statements survive.
+  - Client component imports a server-only utility through an indirect path (e.g., shared types file that pulls server modules).
+- **Multiple copies of the same package.** Look for two boxes with the same package name but different version paths. Usually means a transitive dep pinned a different version.
+- **The `@rangojs/router` chunk** should be roughly **50 KB gzip** (74 files). If significantly larger, you might be importing client-incompatible APIs from the wrong subpath.
+- **Per-route client-reference chunks** (named like `chunk-<hash>.js`). Each `"use client"` boundary can become its own chunk. If you have hundreds of tiny chunks, you may have over-split (every leaf component as a client component); if you have one massive 200 KB chunk, you've under-split (a wide client tree behind one boundary).
+
+### Now check `ssr.html`
+
+**Look for:**
+
+- **`react-dom-server.edge.development-*.js`** (or any `*.development*.js` chunk). This is the dev/prod React doubling. Fix: add `define: { "process.env.NODE_ENV": '"production"' }` to your vite config (see Step 2).
+- **Your client components** appearing in SSR. They're _expected_ here — SSR hydration needs to produce HTML for them. The same components show up in `client.html` too because the browser hydrates them. This is not a leak.
+- **Total SSR size**: a reasonable Rango SSR is ~140 KB gzip plus your app code. If it's >300 KB, almost always (1) dev/prod React duplication or (2) a giant data structure being inlined.
+
+### Now check `rsc.html`
+
+**Look for:**
+
+- **`virtual:rsc-router/routes-manifest`** should be **tiny** (< 1 KB). If it's > 100 KB, you're on an old version of `@rangojs/router` that inlined the trie eagerly — upgrade to a release that includes commit `d10a2470`.
+- **`virtual:rsc-router/routes-manifest/<hash>`** is the lazy per-router chunk. Its size is proportional to your route count. For a typical app: 5–50 KB gzip. For a stress-test app with thousands of routes: hundreds of KB. If yours is unexpectedly huge, check whether you're generating routes you don't need.
+- **`<your-router>.named-routes.gen.ts`** — generated route map. Should match your route count.
+- **Your action and loader implementations** — these run server-side. Expected to be here, not in client.
+- **Worker-incompatible code** (Node-only imports like `node:fs` that Cloudflare doesn't support). The build will usually fail before the analyzer runs, but if you're seeing runtime errors at the edge, the RSC treemap shows what made it in.
+
+## Step 5: Fix what you find
+
+| Finding                                                  | Fix                                                                                                                                                                         |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your server code in `client.html` (non-zero bytes)       | Audit the import chain. Add `"use server"` to server-only files. Move shared data out of barrel files. Use the `@rangojs/router/server` subpath for explicitly server APIs. |
+| Your server code in `client.html` listed but 0 bytes     | Tree-shaking already eliminated it. Cosmetic. Leave it.                                                                                                                     |
+| `react-dom-server.edge.development-*.js` in SSR or RSC   | Add the `define` block from Step 2 to your vite config.                                                                                                                     |
+| Routes-manifest > 100 KB gzip in RSC eager chunk         | Update `@rangojs/router` to a release that includes the lazy-only manifest fix.                                                                                             |
+| Same package version present twice                       | Run `pnpm dedupe` (or `npm dedupe`). If the duplication persists, a transitive dep pins an incompatible version — open a PR upstream or pin the resolution.                 |
+| Client chunk > 500 KB gzip with a single dominant module | That module is your largest client component. Consider lazy-loading via dynamic `import()` or moving non-interactive parts to server components.                            |
+| Hundreds of tiny client chunks                           | You've sprinkled `"use client"` too liberally. Hoist directives to higher boundaries so React groups them.                                                                  |
+
+## When to re-run
+
+- Before every production deploy, especially after adding new dependencies.
+- After upgrading `@rangojs/router`, React, or `@vitejs/plugin-rsc`.
+- After adding routes that scale with data (e.g., one route per item from a content directory) — the manifest may have grown.
+- When CI starts reporting larger artifact sizes.
+
+## Reporting Rango regressions
+
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+
+- The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
+- The `@rangojs/router` version (`pnpm why @rangojs/router`).
+- Your `vite.config.ts`.
+
+The framework maintainers run a similar audit internally — the methodology in this skill mirrors what they use to validate every release.

package/skills/hooks/SKILL.md

@@ -552,6 +552,43 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+
+### .write() / .delete() (static, non-reactive)
+
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
+
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
+
+```tsx
+"use client";
+import { ProductState } from "./state";
+
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+
+// Read later (or on next mount).
+const current = ProductState.read();
+
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
+
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+
 ## Cache Hooks
 
 ### useClientCache()

package/skills/rango/SKILL.md

@@ -34,6 +34,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
 | `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
 | `/fonts`                | Load web fonts with preload hints                                          |
+| `/bundle-analysis`      | Audit your app's production bundle for server leaks and oversized chunks   |
 | `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
 | `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
 

package/src/browser/history-state.ts

@@ -61,6 +61,27 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/navigation-bridge.ts

@@ -13,7 +13,7 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -204,11 +204,7 @@ export function createNavigationBridge(
           },
           {},
         );
-        if (options.replace) {
-          window.history.replaceState(historyState, "", url);
-        } else {
-          window.history.pushState(historyState, "", url);
-        }
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,7 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
 // Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
@@ -186,12 +186,8 @@ export function createNavigationTransaction(
     // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL
-    if (replace) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
+    // Update browser URL (stamps history.state.idx for back() first-entry detection)
+    pushHistoryWithIdx(historyState, url, replace ?? false);
     // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 

package/src/browser/react/location-state-shared.ts

@@ -34,8 +34,43 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   __rsc_ls_key: string;
   /** Whether this state auto-clears after first read */
   readonly __rsc_ls_flash: boolean;
-  /** Read the current value from history.state (client-side only, undefined during SSR) */
+  /**
+   * Read the current value from history.state.
+   *
+   * Returns undefined during SSR (no `window`). To stay hydration-safe, do
+   * NOT call read() inline during the initial render — the server returns
+   * undefined while the client may have a value preserved in history.state
+   * (e.g. after a hard reload of an entry that earlier called write()),
+   * which causes a hydration mismatch. Call read() inside an event handler
+   * or a useEffect post-mount instead, or use useLocationState() if you
+   * want React to manage subscription/hydration for you.
+   */
   read(): TState | undefined;
+  /**
+   * Statically write the value into the current history entry under this
+   * definition's key, preserving any other keys already on history.state
+   * (e.g. router bookkeeping, other LocationState slots).
+   *
+   * This is the non-reactive counterpart to read(): it does not dispatch any
+   * event, so components reading via useLocationState() will NOT re-render
+   * until the next navigation/popstate. Use it when you only need the value
+   * to be there on the next read() or on the next mount (including after
+   * back/forward and hard refresh of the same entry).
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  write(value: TState): void;
+  /**
+   * Statically remove this definition's slot from the current history entry,
+   * leaving any other keys on history.state untouched. Idempotent: removing
+   * a slot that isn't present is a no-op.
+   *
+   * Same non-reactive semantics as write(): no event is dispatched, so
+   * useLocationState() readers will NOT re-render until the next navigation.
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  delete(): void;
 }
 
 /**
@@ -70,6 +105,15 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  *
  * // Read without hook (snapshot, client-side only)
  * const snap = ProductState.read();
+ *
+ * // Static write to current history entry (non-reactive, client-side only).
+ * // Survives back/forward and hard refresh; useLocationState() readers will
+ * // NOT see the new value until the next navigation. Pair with .read() or a
+ * // fresh mount.
+ * ProductState.write({ name: "Widget", price: 9.99 });
+ *
+ * // Manually clear the slot (non-reactive, client-side only).
+ * ProductState.delete();
  * ```
  */
 export function createLocationState<TState>(
@@ -128,6 +172,43 @@ export function createLocationState<TState>(
     enumerable: true,
   });
 
+  Object.defineProperty(fn, "write", {
+    value: (value: TState): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rsc-router] LocationState.write() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state ?? {};
+      window.history.replaceState(
+        { ...current, [key]: value },
+        "",
+        window.location.href,
+      );
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "delete", {
+    value: (): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rsc-router] LocationState.delete() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state;
+      if (current == null || !(key in current)) return;
+      const next = { ...current };
+      delete next[key];
+      window.history.replaceState(next, "", window.location.href);
+    },
+    enumerable: true,
+  });
+
   return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
 }
 

package/src/browser/react/location-state.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
 // Re-export shared utilities and types
@@ -13,6 +13,24 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
+function readLocationStateValue<TState>(
+  key: string | undefined,
+): TState | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (key) {
+    return window.history.state?.[key] as TState | undefined;
+  }
+  // Plain state: stored under history.state.state
+  return window.history.state?.state as TState | undefined;
+}
+
+function hasHydrated(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.hasAttribute("data-hydrated")
+  );
+}
+
 /**
  * Hook to read location state from history.state
  *
@@ -48,30 +66,33 @@ export function useLocationState<TArgs extends unknown[], TState>(
   const key = definition?.__rsc_ls_key;
   const isFlash = definition?.__rsc_ls_flash ?? false;
 
+  // Track whether the initial render returned undefined because the page
+  // hadn't hydrated yet. If so, the mount effect catches up by reading
+  // history.state once. If not, we already have the right value and must
+  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
+  // before the second setup pass, so a re-read would clobber the captured
+  // value with the now-cleared `undefined`.
+  const initialReadDeferredRef = useRef(false);
+
   const [state, setState] = useState<TState | undefined>(() => {
-    if (typeof window === "undefined") return undefined;
-    if (key) {
-      return window.history.state?.[key] as TState | undefined;
+    if (!hasHydrated()) {
+      initialReadDeferredRef.current = true;
+      return undefined;
     }
-    // Plain state: stored under history.state.state
-    return window.history.state?.state as TState | undefined;
+    return readLocationStateValue<TState>(key);
   });
 
   // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (key) {
-        setState(window.history.state?.[key] as TState | undefined);
-      } else {
-        setState(window.history.state?.state as TState | undefined);
-      }
+      setState(readLocationStateValue<TState>(key));
     };
 
     // Handle programmatic state changes (same-page navigation with
     // ctx.setLocationState where components don't remount)
     const handleLocationState = () => {
       if (key) {
-        const val = window.history.state?.[key] as TState | undefined;
+        const val = readLocationStateValue<TState>(key);
         if (isFlash) {
           // For flash state, only update if there's a new value
           if (val !== undefined) {
@@ -81,10 +102,15 @@ export function useLocationState<TArgs extends unknown[], TState>(
           setState(val);
         }
       } else {
-        setState(window.history.state?.state as TState | undefined);
+        setState(readLocationStateValue<TState>(key));
       }
     };
 
+    if (initialReadDeferredRef.current) {
+      initialReadDeferredRef.current = false;
+      setState(readLocationStateValue<TState>(key));
+    }
+
     window.addEventListener("popstate", handlePopstate);
     window.addEventListener("__rsc_locationstate", handleLocationState);
     return () => {

package/src/browser/react/use-router.ts

@@ -72,7 +72,20 @@ export function useRouter(): RouterInstance {
       },
 
       back(): void {
-        window.history.back();
+        // Avoid escaping the host on the first entry of this session.
+        // Prefer the Navigation API; fall back to the router-stamped
+        // history.state.idx (set by pushHistoryWithIdx) for older browsers.
+        const nav = (window as { navigation?: { canGoBack: boolean } })
+          .navigation;
+        const canGoBack =
+          nav && typeof nav.canGoBack === "boolean"
+            ? nav.canGoBack
+            : ((window.history.state as { idx?: number } | null)?.idx ?? 0) > 0;
+        if (canGoBack) {
+          window.history.back();
+        } else {
+          ctx.navigate(withBasename("/"), { replace: true });
+        }
       },
 
       forward(): void {

package/src/index.ts

@@ -305,9 +305,14 @@ export {
 // Path-based response type lookup from RegisteredRoutes
 export type { PathResponse } from "./href-client.js";
 
-// Telemetry sink
-export { createConsoleSink } from "./router/telemetry.js";
-export { createOTelSink } from "./router/telemetry-otel.js";
+// Telemetry types only — the createConsoleSink/createOTelSink values are
+// server-only and live in index.rsc.ts (the `react-server` condition of the
+// bare `@rangojs/router` import). Re-exporting them as values from this
+// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
+// the client module graph; both tree-shake to zero bytes but still appear in
+// bundle analysis output and slow build-time module resolution. Consumers
+// who need the values in non-RSC contexts can import from
+// `@rangojs/router/server`.
 export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
 export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
 

package/src/vite/discovery/virtual-module-codegen.ts

@@ -58,7 +58,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     }
 
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -101,28 +101,18 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       }
     }
 
-    // In dev mode, skip trie and precomputed entries injection. These are
-    // computed once during initial discovery and become stale after route
-    // changes. A stale trie would incorrectly match removed routes. The
-    // handler falls back to Phase 2 regex matching against the live
-    // router.urlpatterns, which is always correct after a program reload.
-    // In build mode, the trie is always fresh (built from the final route
-    // tree) so it's safe to inject.
-    if (state.isBuildMode) {
-      if (
-        state.mergedPrecomputedEntries &&
-        state.mergedPrecomputedEntries.length > 0
-      ) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`,
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`,
-        );
-      }
-    }
+    // Per-router trie and precomputedEntries are NOT inlined eagerly.
+    // They live in the per-router lazy chunks (generatePerRouterModule) and
+    // are loaded via ensureRouterManifest(routerId), which is awaited before
+    // every request in router.fetch() and before findMatch is reached.
+    // Inlining the merged versions here would duplicate the per-router data
+    // (the merged trie/precomputedEntries equal the per-router data for
+    // single-router apps; for multi-router, the merged trie is dead code
+    // because find-match.ts only consumes per-router tries).
+    //
+    // In dev mode, the handler also falls back to Phase 2 regex matching
+    // against live router.urlpatterns, which is always correct after a
+    // program reload.
 
     // Register lazy loaders for per-router manifest modules.
     // Each import() uses a static string literal so Rollup creates separate chunks.