@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

package/src/testing/flight-normalize.ts

@@ -0,0 +1,38 @@
+/**
+ * normalizeFlight — scrub volatile bits from a Flight wire string so snapshots
+ * are stable across runs/machines.
+ *
+ * This is two regex replacements and NOTHING else. It is split out of flight.ts
+ * on purpose: flight.ts top-level imports the vendored react-server-dom
+ * serializer, which throws when imported outside the `react-server` export
+ * condition. The flight-matchers module (and a consumer's shared `setupFiles`
+ * that does `expect.extend(flightMatchers)`) must be importable under the PLAIN
+ * node condition, so the normalizer it needs cannot live next to that import.
+ * flight.ts re-exports normalizeFlight from here, so the public surface of the
+ * `@rangojs/router/testing/flight` entry is unchanged.
+ */
+
+// Volatile leading reference row: `:N<timestamp>` (dev debug-info anchor).
+const REFERENCE_ROW_RE = /^:N[\d.]+\n/;
+// Absolute file:// paths embedded in dev STACK rows. The serializer emits stack
+// frames as `["Component","file:///abs/path.tsx",<line>,<col>,...]`, so the
+// path is a quoted JSON string immediately followed by `",<line>,<col>`. The
+// lookahead scopes the scrub to exactly that frame shape, leaving a legitimate
+// `file://` href in RENDERED content (e.g. `{"href":"file:///x"}`) untouched.
+const FILE_URL_RE = /file:\/\/[^"\\]+(?=",\d+,\d+)/g;
+
+/**
+ * Scrub volatile bits from a Flight string so snapshots are stable across runs
+ * and machines:
+ * - the leading `:N<timestamp>` reference row (dev only),
+ * - absolute `file://...` paths inside dev stack rows.
+ *
+ * Under NODE_ENV=production these rows are already absent; normalize is a
+ * no-op safety net there. In dev mode it removes the machine/clock-specific
+ * noise while leaving the rendered tree intact.
+ */
+export function normalizeFlight(flight: string): string {
+  return flight
+    .replace(REFERENCE_ROW_RE, "")
+    .replace(FILE_URL_RE, "file://<path>");
+}

package/src/testing/flight-runtime.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ambient declaration for the vendored react-server-dom serializer shipped
+ * inside @vitejs/plugin-rsc. The package ships no .d.ts for this private
+ * subpath, so we declare the minimal surface renderToFlightString uses.
+ *
+ * Only loadable under the `react-server` export condition (see flight.ts).
+ */
+declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
+  /**
+   * Serialize a server-component payload to a Flight wire stream.
+   *
+   * @param payload The value to serialize (Rango wraps a payload object).
+   * @param clientManifest Client-reference manifest; `{}` for server-only trees.
+   * @param options Render options; `onError` is invoked per render error.
+   */
+  export function renderToReadableStream(
+    payload: unknown,
+    clientManifest: unknown,
+    options?: { onError?: (error: unknown) => string | void },
+  ): ReadableStream<Uint8Array>;
+
+  /**
+   * Tag a value as a client reference. Mutates `impl` in place (defining
+   * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports
+   * the same module binding renders it as a client boundary (an `I` row) rather
+   * than inlining it. `$$id` becomes `${id}#${exportName}`.
+   */
+  export function registerClientReference<T>(
+    impl: T,
+    id: string,
+    exportName: string,
+  ): T;
+}
+
+/**
+ * Vendored react-server-dom CLIENT deserializer wrappers shipped inside
+ * @vitejs/plugin-rsc. Used by renderServerTree to turn a Flight wire string
+ * back into an inspectable React element tree. These run in the same
+ * `react-server`-condition worker as the serializer (deserialize-only never
+ * renders, so the client React/react-dom imports they pull are inert).
+ */
+declare module "@vitejs/plugin-rsc/react/browser" {
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: { temporaryReferences?: unknown },
+  ): Promise<T>;
+}
+
+declare module "@vitejs/plugin-rsc/core/browser" {
+  /**
+   * Install the module loader the client deserializer resolves client
+   * references through. Init-once per worker (first call wins).
+   */
+  export function setRequireModule(options: {
+    load: (id: string) => unknown;
+  }): void;
+}