@uniflowed/router 0.0.0-alpha.17 → 0.0.0-alpha.20

package/internal/stream.js

@@ -43,6 +43,8 @@ import * as React from "react";
 import * as ReactDOMServer from "react-dom/server";
 import * as ReactDOMStatic from "react-dom/static";
 
+import { type StreamRecord, inspected } from "./inspector.js";
+
 /**
  * Where a document is written, when the host has a Node stream.
  *
@@ -307,9 +309,20 @@ function queueDestination(queue: ChunkQueue): NodeDestination {
 async function* assembled(
   chunks: AsyncGenerator<string, void, void>,
   shell: DocumentShell,
+  transformHead?: (html: string) => Promise<string>,
 ): AsyncGenerator<string, void, void> {
   let held = "";
   let shape = "unknown";
+  // The opening chunk is the only one the hook sees, and every path below
+  // reaches exactly one of them. Awaiting here rather than at each `yield`
+  // keeps them from drifting apart. The hook sees only the document opening:
+  // Vite's HTML parser is happy with an open body, but not with a React chunk
+  // that happens to end inside an attribute.
+  const opening = async (html: string, rest: string = ""): Promise<string> => {
+    const split = transformableOpening(html);
+    const transformed = transformHead == null ? split.opening : await transformHead(split.opening);
+    return transformed + split.rest + rest;
+  };
 
   for await (const chunk of chunks) {
     if (shape === "document-open" || shape === "shell-open") {
@@ -329,7 +342,7 @@ async function* assembled(
         continue;
       }
       shape = "shell-open";
-      yield shell.open + split.head + shell.body + split.rest;
+      yield await opening(shell.open + split.head + shell.body, split.rest);
       held = "";
       continue;
     }
@@ -337,15 +350,21 @@ async function* assembled(
     const close = held.indexOf("</head>");
     if (close !== -1) {
       shape = "document-open";
-      yield ufDoctype(held.slice(0, close) + shell.head + held.slice(close));
+      yield await opening(ufDoctype(held.slice(0, close) + shell.head + held.slice(close)));
       held = "";
       continue;
     }
     // `<body` before `</head>` means React wrote no head; give the tags one.
     const body = held.search(/<body[\s>]/i);
     if (body !== -1) {
+      const bodyEnd = held.indexOf(">", body);
+      if (bodyEnd === -1) {
+        continue;
+      }
       shape = "document-open";
-      yield ufDoctype(`${held.slice(0, body)}<head>${shell.head}</head>${held.slice(body)}`);
+      yield await opening(
+        ufDoctype(`${held.slice(0, body)}<head>${shell.head}</head>${held.slice(body)}`),
+      );
       held = "";
     }
   }
@@ -355,14 +374,14 @@ async function* assembled(
   // `<body>` in it, or a shell that is hoistable elements all the way down.
   // There is nothing left to wait for in any of them.
   if (shape === "document") {
-    yield ufDoctype(held + shell.head);
+    yield await opening(ufDoctype(held + shell.head));
     shape = "document-open";
   } else if (shape === "shell" || shape === "unknown") {
     // `complete` is not consulted: nothing more is coming, so a run that was
     // still open is over and whatever was left of it is markup like any other.
     const split = hoisted(held);
     shape = "shell-open";
-    yield shell.open + split.head + shell.body + split.rest;
+    yield await opening(shell.open + split.head + shell.body, split.rest);
   }
   if (shape === "shell-open") {
     yield shell.close;
@@ -374,6 +393,25 @@ async function* assembled(
   }
 }
 
+function transformableOpening(html: string): {| readonly opening: string, readonly rest: string |} {
+  const lower = html.toLowerCase();
+  const headEnd = lower.indexOf("</head>");
+  if (headEnd === -1) {
+    return { opening: html, rest: "" };
+  }
+  const afterHead = headEnd + "</head>".length;
+  const body = lower.indexOf("<body", afterHead);
+  if (body === -1) {
+    return { opening: html.slice(0, afterHead), rest: html.slice(afterHead) };
+  }
+  const bodyEnd = html.indexOf(">", body);
+  if (bodyEnd === -1) {
+    return { opening: html.slice(0, afterHead), rest: html.slice(afterHead) };
+  }
+  const afterBody = bodyEnd + 1;
+  return { opening: html.slice(0, afterBody), rest: html.slice(afterBody) };
+}
+
 /**
  * The head elements React opened the app's markup with, split from the rest.
  *
@@ -582,8 +620,58 @@ export type RenderOptions = {|
    * shell's own failure is not reported here — it rejects instead.
    */
   readonly onError: (error: mixed) => void,
+  /**
+   * Rewrite the document opening — the head and, when present, the body start
+   * tag — before it goes out.
+   *
+   * For `uf dev`, and only for it. Vite's `transformIndexHtml` rewrites asset
+   * URLs and injects `/@vite/client` and the refresh preamble, and it is a
+   * *whole document* hook, so the development server used to collect the page
+   * and transform it at the end. That made the one place a developer would
+   * notice streaming the one place it did not happen: a slow page showed
+   * nothing until it was finished, and `$loading.js` looked broken.
+   * See ubugeeei-prod/uf#374.
+   *
+   * The hook never sees application body markup, which is what makes this
+   * safe. Vite's injections are string-based against `<head>` and `<body>`,
+   * and its parser accepts a document that stops after the body start tag.
+   * It does not accept a React chunk that ends in the middle of an attribute.
+   *
+   * Absent everywhere else. `uf start`, `uf preview` and every deploy adapter
+   * have no such hook and stream already.
+   */
+  readonly transformHead?: (html: string) => Promise<string>,
+  /**
+   * Told what left, in what order, and what each chunk built.
+   *
+   * For `uf dev`, like `transformHead` above, and absent everywhere else —
+   * which is what makes it free rather than cheap: with nothing supplied no
+   * recorder is constructed, `./inspector.js` is never entered, and the
+   * generator a host consumes is the same object it was. See that module for
+   * what is done with the record and why it is a development affordance rather
+   * than a metric.
+   *
+   * Called once per document, after the last chunk and also after a render that
+   * was abandoned partway. `prerenderDocument` never calls it: a build resolves
+   * everything before it writes a byte, so there is no order to report.
+   */
+  readonly onStream?: (record: StreamRecord) => void,
 |};
 
+/**
+ * `chunks`, recorded on the way out when `uf dev` asked for it.
+ *
+ * The wrapping goes here rather than around `assembled` in each of the callers
+ * so that what is recorded is unambiguous: these are the bytes the host is
+ * handed, head and all, and not React's own output on the way past.
+ */
+function outgoing(
+  chunks: AsyncGenerator<string, void, void>,
+  onStream?: (record: StreamRecord) => void,
+): AsyncGenerator<string, void, void> {
+  return onStream == null ? chunks : inspected(chunks, onStream, () => performance.now());
+}
+
 /**
  * Stream `node` as a document, resolving once the shell is ready.
  *
@@ -601,7 +689,15 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
       const { pipe, abort } = ReactDOMServer.renderToPipeableStream(node, {
         onShellReady() {
           pipe(queueDestination(queue));
-          resolve(bodyOf(assembled(queue.chunks(), options.shell), () => abort()));
+          resolve(
+            bodyOf(
+              outgoing(
+                assembled(queue.chunks(), options.shell, options.transformHead),
+                options.onStream,
+              ),
+              () => abort(),
+            ),
+          );
         },
         onShellError(error: mixed) {
           reject(error);
@@ -661,9 +757,15 @@ export function renderWithReadableStream(
   const controller = new AbortController();
   return render(node, { onError: options.onError, signal: controller.signal }).then(
     (stream: ByteSource) =>
-      bodyOf(assembled(decoded(stream), options.shell), () => {
-        controller.abort();
-      }),
+      bodyOf(
+        outgoing(
+          assembled(decoded(stream), options.shell, options.transformHead),
+          options.onStream,
+        ),
+        () => {
+          controller.abort();
+        },
+      ),
   );
 }
 
@@ -712,7 +814,9 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
     typeof ReactDOMStatic.prerenderToNodeStream === "function"
       ? await ReactDOMStatic.prerenderToNodeStream(node, settings)
       : await ReactDOMStatic.prerender(node, settings);
-  return bodyOf(assembled(preludeChunks(result.prelude), options.shell)).text();
+  return bodyOf(
+    assembled(preludeChunks(result.prelude), options.shell, options.transformHead),
+  ).text();
 }
 
 /**

package/middleware.js

@@ -2,13 +2,13 @@
 //
 // Middleware: what runs before a path answers, whatever answers it.
 //
-// `app/dashboard/_uf.middleware.js` guards `/dashboard` and everything under
+// `app/dashboard/$middleware.js` guards `/dashboard` and everything under
 // it — the pages, the route handlers, and the paths under it that match
 // nothing at all. There is no `matcher` to write because the directory the
 // file sits in *is* the matcher, which is the same composition rule layouts
 // already use and the reason uf does not inherit Next's regular expressions.
 //
-//   // app/dashboard/_uf.middleware.js
+//   // app/dashboard/$middleware.js
 //   // @flow
 //   import { cookies } from "@uniflowed/server";
 //
@@ -167,7 +167,7 @@ export function createMiddlewareRunner(options: {|
  *
  * `default` or `middleware`, the same two spellings a page offers for its
  * component. Anything else is an authoring mistake and throws rather than
- * being skipped: a file named `_uf.middleware.js` that the router quietly
+ * being skipped: a file named `$middleware.js` that the router quietly
  * ignored is the bug this whole module exists to stop happening.
  */
 function pick(module: MiddlewareModule, file: string): Middleware {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.17",
+  "version": "0.0.0-alpha.20",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -26,14 +26,15 @@
     "index.js",
     "internal",
     "middleware.js",
-    "server.js"
+    "server.js",
+    "!*.test.js"
   ],
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.17",
-    "@uniflowed/server": "0.0.0-alpha.17"
+    "@uniflowed/hooks": "0.0.0-alpha.20",
+    "@uniflowed/server": "0.0.0-alpha.20"
   }
 }

package/server.js

@@ -18,7 +18,7 @@
 //
 // They were one function with `renderToString` behind it, which answered the
 // first question by giving up on it: nothing streamed, so nothing could
-// usefully suspend, so `_uf.loading.js` had nothing to be. Making the split
+// usefully suspend, so `$loading.js` had nothing to be. Making the split
 // explicit is the point of ubugeeei-prod/uf#254 rather than a side effect —
 // `internal/stream.js` holds the mechanics and says which React renderer serves
 // which.
@@ -46,6 +46,8 @@ import {
   resolveMatch,
 } from "./internal/runtime.js";
 
+import { type StreamDiagnostic, streamReporter } from "./internal/inspector.js";
+
 /** Asset URLs to reference from the document. */
 export type RenderAssets = {|
   readonly scripts: $ReadOnlyArray<string>,
@@ -112,6 +114,63 @@ export type RenderOptions = {|
    * bytes. `uf dev` reports them in the terminal; a production host logs them.
    */
   readonly onError?: (error: mixed) => void,
+  /**
+   * Rewrite the document opening — the head and, when present, the body start
+   * tag — before it goes out.
+   *
+   * For `uf dev` and nothing else. Vite's `transformIndexHtml` injects
+   * `/@vite/client` and the refresh preamble and rewrites asset URLs, and it
+   * is a *whole document* hook, so the development server used to collect the
+   * page and transform it at the end. That made the one place a developer
+   * would notice streaming the one place it did not happen: a slow page showed
+   * nothing until it was finished, and `$loading.js` looked broken.
+   * See ubugeeei-prod/uf#374.
+   *
+   * A production host passes nothing here and streams as it always did.
+   *
+   * # What a plugin that injects into the body gets
+   *
+   * `transformIndexHtml` is a whole-document hook and this hands it only the
+   * parseable opening of the document. Measured against Vite 8.2.2, injecting
+   * all four positions into a whole document and into the streamed opening:
+   *
+   * | `injectTo`     | whole document      | streamed |
+   * | -------------- | ------------------- | -------- |
+   * | `head-prepend` | after `<head>`      | same     |
+   * | `head`         | before `</head>`    | same     |
+   * | `body-prepend` | after `<body>`      | same     |
+   * | `body`         | before `</body>`    | after `<body>`     |
+   *
+   * Nothing is dropped — every tag still reaches the document — but a `body`
+   * tag lands at the top of the body rather than after the content, because
+   * the content is deliberately not passed to the hook. That keeps Vite's
+   * parser away from chunk boundaries that may sit inside an attribute.
+   *
+   * uf's own injections are `head` and `head-prepend`, and Vite's client is
+   * head-injected, so this is about a third-party plugin.
+   * `packages/vite/dev-head-transform.test.js` pins the table above, so the day
+   * it changes is a failing test rather than a surprise.
+   */
+  readonly transformHead?: (html: string) => Promise<string>,
+  /**
+   * Told, in words, when a document streamed differently than it did last time.
+   *
+   * For `uf dev` and nothing else, like `transformHead` above. It answers the
+   * half of ubugeeei-prod/uf#520 that is about the wire — what arrived, in what
+   * order, and which part of the tree each chunk built — for the stream uf has
+   * today, which is a document whose Suspense boundaries resolve independently.
+   * `internal/inspector.js` is what it is and what it deliberately is not.
+   *
+   * A host that passes nothing here records nothing: no recorder is
+   * constructed, and the chunks a production stream yields are untouched.
+   *
+   * It is handed a message and its detail lines rather than the record they
+   * came from, because the caller is `@uniflowed/vite` — plain JavaScript, run
+   * by Vite before any Flow transform exists, which is why `DEVTOOLS_HOOK` and
+   * `DIAGNOSTIC_ENDPOINT` are spelled twice rather than imported. The
+   * vocabulary of the report belongs on this side of that line.
+   */
+  readonly onStream?: (diagnostic: StreamDiagnostic) => void,
 |};
 
 /** The two ids the server writes and the client reads. */
@@ -263,6 +322,11 @@ export function createRenderer(options: {|
     }
     let resolved: ResolvedRoute = resolution.route;
     const report = settings?.onError ?? (() => {});
+    // Built once and shared by both renders below, so a page that threw its
+    // shell away and rendered its error boundary instead reports the stream the
+    // browser was actually sent rather than the one that was abandoned.
+    const send = settings?.onStream;
+    const onStream = send == null ? undefined : streamReporter(url, send);
 
     // React reports an exception to `onError` *and*, if it was in the shell, to
     // `onShellError` — so forwarding both would tell the host about one failure
@@ -285,6 +349,8 @@ export function createRenderer(options: {|
       body = await renderDocument(<App url={url} initial={resolved} />, {
         shell: shellFor(assets),
         onError,
+        transformHead: settings?.transformHead,
+        onStream,
       });
       streaming = true;
       // Recovered before the shell was ready: a `<Suspense>` boundary whose
@@ -315,6 +381,8 @@ export function createRenderer(options: {|
       body = await renderDocument(<App url={url} initial={resolved} />, {
         shell: shellFor(assets),
         onError,
+        transformHead: settings?.transformHead,
+        onStream,
       });
     }
 
@@ -422,6 +490,36 @@ function redirectDocument(error: RedirectError): RenderResult {
  * carried two of them, one in each place, and only one was where a browser
  * looks. Hoisting the rendered one leaves the metadata with a single source.
  */
+/**
+ * The document a single-page build writes, and the only one it writes.
+ *
+ * `app.rendering.modes: ["csr"]` renders no route at build time: the client
+ * router resolves and renders every one of them in the browser, so what the
+ * build has to leave behind is the *chrome* — the stylesheets, the module
+ * script, and the empty root the client renders into. That is exactly
+ * [`shellFor`]'s three strings with nothing between them, which is why this is
+ * three concatenations rather than a fourth shape of document to keep in step
+ * with the other three.
+ *
+ * No React runs. There is nothing to render: no URL has been asked for, and
+ * whatever this document is served for is decided by the host rather than by
+ * this build.
+ *
+ * # What it costs, said here because it is not visible from the file
+ *
+ * The document has no `<title>`, no `<meta name="description">` and no content.
+ * A crawler that runs no JavaScript sees an empty page for **every** URL, and a
+ * reader sees nothing until the bundle has loaded and the route has resolved.
+ * That is what a single-page application is, and it is why `modes: ["csr"]` is
+ * a declaration a project makes rather than something a build falls back to.
+ * A project that wants a document per route has `ssg`, and one that wants a
+ * document per request has `ssr`.
+ */
+export function shellDocument(assets: RenderAssets): string {
+  const shell = shellFor(assets);
+  return `${shell.open}${shell.body}${shell.close}`;
+}
+
 function shellFor(assets: RenderAssets): DocumentShell {
   const head = headTags(assets);
   return {