@rangojs/router 0.0.0-experimental.143 → 0.0.0-experimental.145

package/src/ssr/inject-rsc-eager.ts

@@ -0,0 +1,167 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+/**
+ * Eager Flight-payload injector for the PPR resume path.
+ *
+ * rsc-html-stream's injectRSCPayload starts forwarding Flight chunks only from
+ * inside its first transform() callback — i.e. AFTER the first HTML chunk flows.
+ * That policy exists for the normal document path (a <script> must not precede
+ * the doctype). On a PPR shell HIT it parks the ENTIRE hydration payload: the
+ * resumed fizz render emits its first chunk only when the first hole's data
+ * resolves (live loaders — measured ~1.5s on SFCC-backed pages), while the
+ * Flight root row is ready within ~30ms of the tail render starting. The client
+ * cannot call hydrateRoot until that root row arrives, so the lazy start held
+ * hydration hostage to the slowest loader for no structural reason: the stored
+ * prelude (a complete document through </body></html>) is already on the wire
+ * before the tail, so every tail byte is foster-parented and a Flight <script>
+ * is valid as the FIRST tail byte.
+ *
+ * This injector starts pumping Flight chunks immediately in start(). Ordering
+ * safety is kept by serializing ALL writes through one promise chain: fizz
+ * chunks buffered within a tick flush as one atomic task (same batching idea as
+ * the stock injector — never inject between two partial HTML chunks), and each
+ * Flight script is its own task, so scripts land only between batches. The
+ * trailer is stripped from passing HTML and re-appended once, after both
+ * streams complete — identical to the stock contract.
+ *
+ * RESUME/DATA-VARIANT ONLY. The normal document path must keep the stock
+ * injector: there the first bytes are the document head, and an eager script
+ * would precede the doctype.
+ */
+
+const encoder = new TextEncoder();
+const TRAILER = "</body></html>";
+
+// Escape closing script tags and HTML comments in JS content (ported from
+// rsc-html-stream/server; escapes the "s" instead of the slash so a regexp
+// literal like `0</script/` stays valid JS).
+function escapeScript(script: string): string {
+  return script.replace(/<!--/g, "<\\!--").replace(/<\/(script)/gi, "</\\$1");
+}
+
+function writeScript(
+  controller: TransformStreamDefaultController<Uint8Array>,
+  jsExpr: string,
+  nonce: string | undefined,
+): void {
+  controller.enqueue(
+    encoder.encode(
+      `<script${nonce ? ` nonce="${nonce}"` : ""}>${escapeScript(
+        `(self.__FLIGHT_DATA||=[]).push(${jsExpr})`,
+      )}</script>`,
+    ),
+  );
+}
+
+export function injectRSCPayloadEager(
+  rscStream: ReadableStream<Uint8Array>,
+  options?: { nonce?: string },
+): TransformStream<Uint8Array, Uint8Array> {
+  const nonce = options?.nonce;
+  const htmlDecoder = new TextDecoder();
+  const t0 = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
+  let loggedFirstFlight = false;
+  let loggedFirstHtml = false;
+
+  // All output goes through this chain: one task per Flight script, one task
+  // per buffered-HTML batch. A script can therefore never split a batch.
+  let queue: Promise<void> = Promise.resolve();
+  const enqueueTask = (fn: () => void): Promise<void> => {
+    queue = queue.then(fn);
+    return queue;
+  };
+
+  let buffered: Uint8Array[] = [];
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  let rscDone: Promise<void> = Promise.resolve();
+
+  function flushBufferedHTML(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void {
+    if (INTERNAL_RANGO_DEBUG && !loggedFirstHtml && buffered.length > 0) {
+      loggedFirstHtml = true;
+      console.log(
+        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms`,
+      );
+    }
+    for (const chunk of buffered) {
+      let buf = htmlDecoder.decode(chunk, { stream: true });
+      if (buf.endsWith(TRAILER)) buf = buf.slice(0, -TRAILER.length);
+      controller.enqueue(encoder.encode(buf));
+    }
+    const remaining = htmlDecoder.decode();
+    if (remaining.length) {
+      const out = remaining.endsWith(TRAILER)
+        ? remaining.slice(0, -TRAILER.length)
+        : remaining;
+      controller.enqueue(encoder.encode(out));
+    }
+    buffered.length = 0;
+    timeout = null;
+  }
+
+  async function pumpRSC(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): Promise<void> {
+    const rscDecoder = new TextDecoder("utf-8", { fatal: true });
+    const reader = rscStream.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // String when the chunk is valid unicode, base64 round-trip otherwise —
+      // same fallback the stock injector uses.
+      let jsExpr: string;
+      try {
+        jsExpr = JSON.stringify(rscDecoder.decode(value, { stream: true }));
+      } catch {
+        const base64 = JSON.stringify(
+          btoa(String.fromCodePoint(...(value as Uint8Array))),
+        );
+        jsExpr = `Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`;
+      }
+      await enqueueTask(() => {
+        if (INTERNAL_RANGO_DEBUG && !loggedFirstFlight) {
+          loggedFirstFlight = true;
+          console.log(
+            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms`,
+          );
+        }
+        writeScript(controller, jsExpr, nonce);
+      });
+    }
+    const remaining = rscDecoder.decode();
+    if (remaining.length) {
+      await enqueueTask(() =>
+        writeScript(controller, JSON.stringify(remaining), nonce),
+      );
+    }
+  }
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    start(controller) {
+      // The eager part: pump Flight immediately, before any HTML arrives.
+      rscDone = pumpRSC(controller).catch((err) => {
+        try {
+          controller.error(err);
+        } catch {
+          // Stream already errored/closed; nothing to signal.
+        }
+      });
+    },
+    transform(chunk, controller) {
+      buffered.push(chunk);
+      if (timeout) return;
+      // Batch same-tick fizz chunks so a Flight script cannot land between two
+      // partial HTML chunks of one logical write (stock injector's invariant).
+      timeout = setTimeout(() => {
+        void enqueueTask(() => flushBufferedHTML(controller));
+      }, 0);
+    },
+    async flush(controller) {
+      await rscDone;
+      if (timeout) clearTimeout(timeout);
+      await enqueueTask(() => flushBufferedHTML(controller));
+      controller.enqueue(encoder.encode(TRAILER));
+    },
+  });
+}

package/src/testing/dispatch.ts

@@ -757,6 +757,10 @@ export async function dispatch<TEnv = any>(
           durationMs: performance.now() - telemetryStart,
           segmentCount: 0,
           cacheHit: false,
+          // dispatch's final response IS built before request.end (unlike
+          // match()/matchPartial(), whose Response is built after), so stamp its
+          // status — the same field a thrown-Response short-circuit carries.
+          status: finalResponse.status,
         });
       }
 
@@ -785,6 +789,9 @@ export async function dispatch<TEnv = any>(
             durationMs: performance.now() - telemetryStart,
             segmentCount: 0,
             cacheHit: false,
+            // Carry the short-circuit Response's status (parity with
+            // match-handlers.ts's thrown-Response request.end).
+            status: error.status,
           });
         } else {
           safeEmit(resolveSink(sink), {

package/src/vite/index.ts

@@ -8,6 +8,13 @@
 
 export { rango } from "./rango.js";
 export { poke } from "./plugins/refresh-cmd.js";
+// The built-in clientChunks strategy, exported so a custom `clientChunks`
+// function can OVERLAY it (route a few modules to a dedicated chunk, delegate
+// the rest) instead of replacing the whole route/marker grouping. Without this
+// a consumer override silently loses app-fallback/route splitting for the
+// entire app. Note: called without a ClientChunkContext the fallbackRefs-based
+// `app-fallback` split is inactive — discovery wires it only for the built-in.
+export { directoryClientChunks } from "./utils/client-chunks.js";
 
 export type {
   RangoNodeOptions,

package/src/vite/inject-client-debug.ts

@@ -1,3 +1,5 @@
+import type { Connect } from "vite";
+
 /**
  * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
  * module so the flag reaches the CLIENT debug logs by just setting the env var.
@@ -10,27 +12,77 @@
  * runs on the module regardless of how (or whether) the define is delivered, in
  * both dev and build and for every environment, so the discovery plugin uses this
  * to replace the module with the resolved literal.
- *
+ */
+
+/**
+ * Scope to the router's own internal-debug module: the published package
+ * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+ * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+ * consumer file that merely sits under a directory named `rangojs-router`.
+ * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ */
+export function isRouterInternalDebugId(id: string): boolean {
+  if (!id.includes("internal-debug")) return false;
+  const norm = id.replace(/\\/g, "/");
+  return (
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"))
+  );
+}
+
+/**
+ * Transform: replace the module with the resolved literal.
  * Returns null for any module that is not the router's internal-debug module.
  */
 export function injectClientDebugFlag(
   id: string,
 ): { code: string; map: null } | null {
   // Cheap early-out: this hook runs on every module in every environment.
-  if (!id.includes("internal-debug")) return null;
-  const norm = id.replace(/\\/g, "/");
-  // Scope to the router's own internal-debug module: the published package
-  // (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
-  // (`/packages/rangojs-router/`). The package-anchored path avoids matching a
-  // consumer file that merely sits under a directory named `rangojs-router`.
-  const isInternalDebug =
-    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
-    (norm.includes("/@rangojs/router/") ||
-      norm.includes("/packages/rangojs-router/"));
-  if (!isInternalDebug) return null;
+  if (!isRouterInternalDebugId(id)) return null;
   // Emit the whole module: internal-debug.ts has a single export, kept in sync.
   return {
     code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
     map: null,
   };
 }
+
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * immune -- workspace source is outside node_modules and served no-cache --
+ * which is why this bit only npm consumers.
+ *
+ * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
+ * are byte-identical across flag states), so forcing revalidation for this one
+ * tiny module is sufficient and costs one conditional request per session. The
+ * middleware is unconditional (not gated on the flag) so an already-poisoned
+ * cache heals in both directions. Alternatives that do not work: a plugin
+ * `resolveId` appending a flag query never fires in Vite 8 dev for
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value,
+        );
+      };
+    }
+    next();
+  };
+}

package/src/vite/router-discovery.ts

@@ -19,7 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
-import { injectClientDebugFlag } from "./inject-client-debug.js";
+import {
+  injectClientDebugFlag,
+  internalDebugNoCacheMiddleware,
+} from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -392,6 +395,11 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      // Serve the internal-debug module no-cache: consumers resolve it into
+      // node_modules, where dev's immutable `?v=` caching pinned browsers to a
+      // stale baked INTERNAL_RANGO_DEBUG. See internalDebugNoCacheMiddleware.
+      server.middlewares.use(internalDebugNoCacheMiddleware());
+
       // Discovery promise that the handler can await if requests arrive
       // before discovery completes
       let resolveDiscovery: () => void;