npm - @uniflowed/router - Versions diffs - 0.0.0-alpha.18 → 0.0.0-alpha.21 - Mend

@uniflowed/router 0.0.0-alpha.18 → 0.0.0-alpha.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/client.js +187 -5
package/handler.js +15 -6
package/index.js +29 -6
package/internal/action-wire.js +6 -3
package/internal/boundaries.js +557 -0
package/internal/devtools.js +2 -2
package/internal/diagnostics.js +1 -1
package/internal/hydration.js +232 -39
package/internal/inspector.js +615 -0
package/internal/payload-rows.js +258 -0
package/internal/payload.js +669 -0
package/internal/runtime.js +754 -50
package/internal/stream.js +87 -17
package/middleware.js +3 -3
package/package.json +5 -4
package/server.js +72 -17

package/internal/stream.js CHANGED Viewed

@@ -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.
  *
@@ -313,9 +315,14 @@ async function* assembled(
   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 the four of them from drifting apart.
-  const opening = async (html: string): Promise<string> =>
-    transformHead == null ? html : await transformHead(html);
+  // 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") {
@@ -335,7 +342,7 @@ async function* assembled(
         continue;
       }
       shape = "shell-open";
-      yield await opening(shell.open + split.head + shell.body + split.rest);
+      yield await opening(shell.open + split.head + shell.body, split.rest);
       held = "";
       continue;
     }
@@ -350,6 +357,10 @@ async function* assembled(
     // `<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 await opening(
         ufDoctype(`${held.slice(0, body)}<head>${shell.head}</head>${held.slice(body)}`),
@@ -370,7 +381,7 @@ async function* assembled(
     // still open is over and whatever was left of it is markup like any other.
     const split = hoisted(held);
     shape = "shell-open";
-    yield await opening(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;
@@ -382,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.
  *
@@ -591,29 +621,57 @@ export type RenderOptions = {|
    */
   readonly onError: (error: mixed) => void,
   /**
-   * Rewrite the opening chunk — everything up to and including the head —
-   * before it goes out.
+   * 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 `_uf.loading.js` looked broken.
+   * nothing until it was finished, and `$loading.js` looked broken.
    * See ubugeeei-prod/uf#374.
    *
-   * The hook only ever sees the head, which is what makes this safe. Vite's
-   * injections are string-based against `<head>`, and its dev hook handles a
-   * document that ends mid-`<body>` without complaint — checked against Vite
-   * 8.2.2 before this existed, because "the parse step is the risk" was the
-   * open question on that issue.
+   * 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.
  *
@@ -632,7 +690,13 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
         onShellReady() {
           pipe(queueDestination(queue));
           resolve(
-            bodyOf(assembled(queue.chunks(), options.shell, options.transformHead), () => abort()),
+            bodyOf(
+              outgoing(
+                assembled(queue.chunks(), options.shell, options.transformHead),
+                options.onStream,
+              ),
+              () => abort(),
+            ),
           );
         },
         onShellError(error: mixed) {
@@ -693,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, options.transformHead), () => {
-        controller.abort();
-      }),
+      bodyOf(
+        outgoing(
+          assembled(decoded(stream), options.shell, options.transformHead),
+          options.onStream,
+        ),
+        () => {
+          controller.abort();
+        },
+      ),
   );
 }

package/middleware.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.18",
+  "version": "0.0.0-alpha.21",
   "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.18",
-    "@uniflowed/server": "0.0.0-alpha.18"
+    "@uniflowed/hooks": "0.0.0-alpha.21",
+    "@uniflowed/server": "0.0.0-alpha.21"
   }
 }

package/server.js CHANGED Viewed

@@ -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>,
@@ -113,46 +115,62 @@ export type RenderOptions = {|
    */
   readonly onError?: (error: mixed) => void,
   /**
-   * Rewrite the opening chunk — everything up to and including the head —
-   * before it goes out.
+   * 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 `_uf.loading.js` looked broken.
+   * 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 one chunk,
-   * so `injectTo` is answered against a document that stops inside `<body>`.
-   * Measured against Vite 8.2.2, injecting all four positions into a whole
-   * document and into a head-only one:
+   * `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>`** |
+   * | `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 has not been rendered yet when the hook runs. For a `<script>`
-   * that expects a complete DOM that is a real difference, and it is the price
-   * of streaming: a hook that wants the whole document and a server that sends
-   * the head first cannot both be satisfied.
+   * 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. `dev-head-transform`
-   * in `tests/library` pins the table above, so the day it changes is a failing
-   * test rather than a surprise.
+   * 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. */
@@ -304,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
@@ -327,6 +350,7 @@ export function createRenderer(options: {|
         shell: shellFor(assets),
         onError,
         transformHead: settings?.transformHead,
+        onStream,
       });
       streaming = true;
       // Recovered before the shell was ready: a `<Suspense>` boundary whose
@@ -358,6 +382,7 @@ export function createRenderer(options: {|
         shell: shellFor(assets),
         onError,
         transformHead: settings?.transformHead,
+        onStream,
       });
     }
@@ -465,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 {