@uniflowed/router 0.0.0-alpha.13 → 0.0.0-alpha.14

package/handler.js

@@ -69,7 +69,7 @@
 // `after()` promises. A handler that streams its body has not sent a byte at
 // that point. See ubugeeei-prod/uf#389.
 
-import { noteRoute } from "@uniflowed/server/host";
+import { asResponder, noteRoute } from "@uniflowed/server/host";
 
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
@@ -157,10 +157,15 @@ export function createDispatcher(options: {|
       // In the host's request, so a handler that calls `headers()`,
       // `cookies()` or `after()` answers about the same one its guard did, and
       // what it defers is drained once, by the host, after the bytes are out.
-      const response = await handler(request, {
-        params,
-        searchParams: url.searchParams,
-      });
+      //
+      // And inside `asResponder`, which is the other half: a route handler is
+      // one of the two things that owns a response, so it is one of the two
+      // places `draftMode().enable()` is allowed — and the `Set-Cookie` it
+      // decided on is written onto the response below rather than left on an
+      // object the host is about to discard. See ubugeeei-prod/uf#282.
+      const response = await asResponder("a route handler", async () =>
+        handler(request, { params, searchParams: url.searchParams }),
+      );
 
       // A `HEAD` answered by `GET` must not carry the body. The test is
       // against the module's own `HEAD`, not `pick`'s — `pick` falls back to

package/internal/action-endpoint.js

@@ -76,6 +76,8 @@
 // it. Written here because this is the file somebody reads before deciding
 // otherwise.
 
+import { asResponder } from "@uniflowed/server/host";
+
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
@@ -198,32 +200,44 @@ export function createActionDispatcher(options: {|
       return refusal(500);
     }
 
-    let result: mixed;
-    try {
-      // The build-time contract says this is `async (...ActionValue) => …`
-      // (`ServerActionBoundary` in `../action.js`), and Flow cannot read that
-      // through a module loaded by a thunk. The arguments are the ones
-      // `decodeActionArguments` produced, so what is unchecked here is the
-      // shape of the function and not the shape of the payload.
-      const call = action as $FlowFixMe;
-      result = await call(...args);
-    } catch (error) {
-      report(record, error);
-      return refusal(500);
-    }
+    // Everything from here to the answer runs as the thing that owns this
+    // response, which is what makes `draftMode().enable()` legal in an action:
+    // a `"use server"` function is one of the two places uf lets draft mode be
+    // changed, and the `Set-Cookie` it decides on is written onto the response
+    // this returns rather than onto an object the host discards. See
+    // ubugeeei-prod/uf#282 and `asResponder`.
+    //
+    // The refusals stay outside it. A `403` for a cross-origin call must not
+    // carry a cookie the caller asked for, and a scope that covered them would
+    // be a scope in which nothing ran that could have asked.
+    return asResponder("a server action", async () => {
+      let result: mixed;
+      try {
+        // The build-time contract says this is `async (...ActionValue) => …`
+        // (`ServerActionBoundary` in `../action.js`), and Flow cannot read that
+        // through a module loaded by a thunk. The arguments are the ones
+        // `decodeActionArguments` produced, so what is unchecked here is the
+        // shape of the function and not the shape of the payload.
+        const call = action as $FlowFixMe;
+        result = await call(...args);
+      } catch (error) {
+        report(record, error);
+        return refusal(500);
+      }
 
-    let answer: string;
-    try {
-      answer = encodeActionResult(result);
-    } catch (error) {
-      // The action ran and its return value cannot cross. Flow says so at
-      // build time — `ServerActionBoundary` in `../action.js` holds every
-      // action's return type against the grammar — so this is the case where
-      // it was reached anyway, and half a value is worse than none.
-      report(record, error);
-      return refusal(500);
-    }
-    return new Response(answer, { status: 200, headers: { ...ANSWER_HEADERS } });
+      let answer: string;
+      try {
+        answer = encodeActionResult(result);
+      } catch (error) {
+        // The action ran and its return value cannot cross. Flow says so at
+        // build time — `ServerActionBoundary` in `../action.js` holds every
+        // action's return type against the grammar — so this is the case where
+        // it was reached anyway, and half a value is worse than none.
+        report(record, error);
+        return refusal(500);
+      }
+      return new Response(answer, { status: 200, headers: { ...ANSWER_HEADERS } });
+    });
   };
 }
 

package/internal/diagnostics.js

@@ -0,0 +1,169 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the way a diagnostic the browser produced
+// reaches the terminal.
+//
+// Every other uf diagnostic — a type error, a lint finding, a failing test, a
+// page that rendered its error boundary — arrives in the terminal the
+// developer already has open. One produced *in the browser* had nowhere to go:
+// the page is the only process that knows about it, and `uf dev`'s diagnostics
+// come up the driver's event channel from the Node process. So the hydration
+// report added in ubugeeei-prod/uf#582 lived in a browser overlay and in the
+// console, which has to be noticed, in a window that may not be in front, by
+// somebody who does not know to look. See ubugeeei-prod/uf#583.
+//
+// This is the client half. The server half is `uf dev`, through
+// `@uniflowed/vite`'s `internal/diagnostics.js`, which turns what arrives into
+// the same rendering the terminal gives everything else: a severity, the page
+// it came from, and a code frame when there is a position to draw one around.
+//
+// # One channel, and why the poster is not shared
+//
+// `/__uf/diagnostic` and `/__uf/vitals` are one channel: two paths, one payload
+// shape, one `diagnostic` event out of the driver, one renderer. What is *not*
+// shared is the twenty lines that post to it. `@uniflowed/web/vitals` has its
+// own `vitalsBeacon`, and this is the router's.
+//
+// `@uniflowed/hmr` would have been the tidier home — it is already "the browser
+// half of `uf dev`" — and it cannot be one. `tools/ci/publishable.sh` refuses a
+// published package that depends on an unpublished one, because the tarball
+// would name a version the registry does not have; `@uniflowed/router` is on
+// npm and `@uniflowed/hmr` is a declaration package that is not. What the two
+// posters do share is the contract, and `tests/library/dev-channel.test.js`
+// asserts that every spelling of these paths agrees — a duplicated constant
+// with a test on it is honest, and one without is how a browser ends up
+// posting to a path nothing serves.
+//
+// # It is development only, and it is best effort
+//
+// `uf dev` serves this path and nothing else does: a built application has no
+// `/__uf/` anything, so a call in production posts to a path that answers 404
+// and the rejected promise is swallowed here. That is a fallback rather than a
+// design — the only caller is behind `import.meta.hot` in `../client.js`, so a
+// production bundle has no path to this module rather than merely no answer
+// from it.
+//
+// Nothing here opens a connection until it is called, importing it does nothing
+// at all, and what it sends goes to the page's own origin as a path rather than
+// a URL, so it cannot be pointed at somebody else's server. Nothing leaves the
+// machine.
+
+/**
+ * The path `uf dev` serves the diagnostic channel on.
+ *
+ * Under `/__uf/`, beside the update stream `@uniflowed/hmr` opens and the
+ * vitals endpoint `@uniflowed/web/vitals` posts to, for the reason that prefix
+ * exists: a directory in `app/` whose name begins with `_` is not a route, so
+ * no application can put anything here and nothing here can shadow a path a
+ * project wrote.
+ */
+export const DIAGNOSTIC_ENDPOINT: string = "/__uf/diagnostic";
+
+/**
+ * How loudly a diagnostic reads in the terminal.
+ *
+ * `error` for something that is wrong, `warn` for something that is worth
+ * knowing, `info` for something that is only a measurement. Three rather than
+ * two because the vitals report on the same channel needs the third: a page
+ * whose numbers are all good has still reported, and printing that as a warning
+ * would teach the reader to ignore the warnings.
+ */
+export type DiagnosticSeverity = "error" | "warn" | "info";
+
+/**
+ * One diagnostic, as the channel carries it.
+ *
+ * `message` is the headline and the only required field: one line, the thing
+ * that is wrong. `detail` is everything under it — the values that differed,
+ * the path through the tree, the advice — and is a list of lines rather than a
+ * blob so the terminal can indent them without guessing where they break.
+ *
+ * `url` is the page the browser was on, which the reporter fills in when the
+ * caller does not: a diagnostic that does not say which page produced it is a
+ * diagnostic somebody has to reproduce before they can act on it.
+ *
+ * `file`, `line` and `column` are for the rare browser-side report that knows a
+ * source position. When the file and the line are both there `uf dev` draws its
+ * ordinary code frame; when they are not it prints the headline and the detail,
+ * which is what a hydration mismatch — a fact about a DOM node rather than
+ * about a line — can honestly offer.
+ */
+export type BrowserDiagnostic = {
+  readonly severity: DiagnosticSeverity,
+  readonly message: string,
+  readonly detail?: $ReadOnlyArray<string>,
+  readonly url?: string,
+  readonly file?: string,
+  readonly line?: number,
+  readonly column?: number,
+};
+
+/** The part of the browser this module needs. */
+type ReportingWindow = {
+  readonly location?: { readonly href?: string, ... },
+  readonly fetch?: (input: string, init: { ... }) => Promise<mixed>,
+  ...
+};
+
+/** For a promise whose outcome is deliberately not looked at. */
+function noop(): void {}
+
+/**
+ * Send one diagnostic to `uf dev`, if there is a `uf dev` to send it to.
+ *
+ * Returns nothing and throws nothing. A diagnostic is a thing a person reads,
+ * not a thing an application branches on, and a reporter that could fail would
+ * make every caller wrap it — from a code path that is, by construction,
+ * already handling something that went wrong.
+ *
+ * `fetch` rather than `sendBeacon`, which is the opposite of the choice
+ * `vitalsBeacon` makes and for the opposite reason: a vital is measured as the
+ * page is put away and needs a transport that outlives it, while a diagnostic
+ * is produced by a page that is still running and had better arrive in the
+ * order it happened. `keepalive` covers the case where the page goes away
+ * immediately afterwards anyway.
+ *
+ * @param diagnostic what to report
+ * @param endpoint where to post it; [`DIAGNOSTIC_ENDPOINT`] by default
+ */
+export function reportDiagnostic(diagnostic: BrowserDiagnostic, endpoint?: string): void {
+  const win = reportingWindow();
+  if (win == null) {
+    return;
+  }
+  const post = win.fetch;
+  if (post == null) {
+    return;
+  }
+
+  const body = JSON.stringify({
+    ...diagnostic,
+    url: diagnostic.url ?? win.location?.href ?? "",
+  });
+  // A rejected promise nobody is holding becomes an unhandled rejection, which
+  // arrives in whatever error reporter the application installed — from a line
+  // about development tooling. Losing the report is the right outcome when
+  // there is nothing listening; reporting the loss as an application error is
+  // not.
+  post(endpoint ?? DIAGNOSTIC_ENDPOINT, {
+    method: "POST",
+    body,
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+  }).then(noop, noop);
+}
+
+/**
+ * The window to report from, or `null` where there is no browser.
+ *
+ * The same reading `@uniflowed/web/vitals` makes, and for the same reason: in a
+ * browser `globalThis` *is* the window, but not where a document has been
+ * installed onto another host's global, which is every uf test process. Asking
+ * for the document first is what makes both cases work.
+ */
+function reportingWindow(): ReportingWindow | null {
+  if (typeof globalThis.document === "undefined") {
+    return null;
+  }
+  return globalThis.window ?? globalThis;
+}

package/internal/hydration.js

@@ -84,10 +84,21 @@
 // seed decided once and read by both sides (ubugeeei-prod/uf#554) — and this is
 // for the ones that still do.
 //
-// It does not reach the terminal either. `uf dev`'s diagnostics come up the
-// driver's event channel from the Node process, and a hydration mismatch
-// happens in the browser, which has no channel to send one back on. Naming
-// that here is more use than a half-built one: see ubugeeei-prod/uf#508.
+// # It does reach the terminal
+//
+// It did not, once. `uf dev`'s diagnostics come up the driver's event channel
+// from the Node process, and a hydration mismatch happens in the browser, which
+// had no channel to send one back on — so this report existed in an overlay and
+// in the console, and had to be noticed by somebody who knew to look. There is
+// a channel now: `./diagnostics.js` posts to `/__uf/diagnostic`, `uf dev`
+// answers it, and the same words this module formats for the overlay are
+// printed by the same renderer that prints a type error. See
+// ubugeeei-prod/uf#583, and #508 for where the gap was named.
+//
+// The overlay stays. It is in front of the reader who caused the mismatch by
+// editing the page, and the terminal is for the one who did not.
+
+import { reportDiagnostic } from "./diagnostics.js";
 
 /** Which of the usual causes the difference looks like. */
 export type HydrationCause = "variable-input" | "browser-only" | "invalid-nesting" | "unknown";
@@ -813,6 +824,13 @@ function paragraph(document: Document, text: string, className: string | null):
  * `reportError`, which is what React would have done: this callback replaces
  * React's default rather than adding to it, so anything it swallows is
  * swallowed for good.
+ *
+ * A mismatch goes to three places, and all three say the same words because all
+ * three come out of [`formatHydrationReport`]: the overlay, for the reader
+ * looking at the page; the console, for a headless run, a CI browser and a
+ * reader who closed the panel; and `uf dev`'s terminal, through
+ * [`reportDiagnostic`], for the reader who is not looking at the browser at
+ * all. See ubugeeei-prod/uf#583.
  */
 export function hydrationErrorHandler(
   container: Node,
@@ -848,6 +866,19 @@ export function hydrationErrorHandler(
     // console is where a headless run, a CI browser and a reader who closed
     // the panel all still see the report.
     console.error(text);
+    // And the terminal, where every other uf diagnostic already is. The
+    // headline is the first line and the rest is the detail, which is the
+    // shape the channel carries and is why the formatter puts the sentence
+    // first: one report, one wording, three places. No position goes with it —
+    // a mismatch is a fact about a DOM node rather than about a line of a
+    // file, and inventing a file and a line to earn a code frame would send
+    // the reader somewhere that is not the answer.
+    const [headlineLine, ...rest] = text.split("\n");
+    reportDiagnostic({
+      severity: "error",
+      message: headlineLine,
+      detail: rest,
+    });
   };
 }
 

package/internal/runtime.js

@@ -15,10 +15,8 @@ import {
   createContext,
   startTransition,
   use,
-  useCallback,
   useContext,
   useEffect,
-  useMemo,
   useState,
   useSyncExternalStore,
 } from "react";
@@ -31,6 +29,12 @@ import {
 // being evaluated.
 import { flushSync } from "react-dom";
 
+// The two things a render has to fix — its instant and its random seed — and
+// the provider that fixes them. Imported here rather than left to the
+// application, because a hydration guarantee nobody wires is not a guarantee:
+// see [`routerView`] and ubugeeei-prod/uf#559.
+import { RenderProvider } from "@uniflowed/hooks/render";
+
 // The id of the script the loader data is embedded in. It moved out of the
 // head and into the tree with ubugeeei-prod/uf#373 — see [`loaderDataScript`]
 // — so the module that renders it is this one rather than `../server.js`.
@@ -1530,9 +1534,9 @@ component RouteErrorView(module: ?ErrorModule, error: RouteError, reset: () => v
  */
 component ResolvedErrorPage() {
   const { resolved, router } = useRouterState();
-  const reset = useCallback(() => {
+  const reset = () => {
     router.refresh().catch(() => {});
-  }, [router]);
+  };
 
   if (resolved.error == null) {
     // Unreachable: this module is only ever the page of a resolved error route.
@@ -1850,7 +1854,7 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   const [resolved, setResolved] = useState<ResolvedRoute>(initial);
   const [pending, setPending] = useState<boolean>(false);
 
-  const navigate = useCallback(async (to: string, options?: NavigateOptions): Promise<void> => {
+  const navigate = async (to: string, options?: NavigateOptions): Promise<void> => {
     if (!isBrowser()) {
       return;
     }
@@ -1899,7 +1903,7 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
       setPending(false);
       throw error;
     }
-  }, []);
+  };
 
   useEffect(() => {
     if (!isBrowser()) {
@@ -1930,59 +1934,53 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     };
   }, []);
 
-  const router = useMemo<Router>(
-    () => ({
-      push: (to, options) => navigate(to, options),
-      replace: (to) => navigate(to, { replace: true }),
-      prefetch: async (to) => {
-        if (!isBrowser()) {
-          return;
-        }
-        const target = new URL(to, window.location.href);
-        const matched = matchRoute(routeTable().routes, target.pathname);
-        const load = matched?.route.page;
-        if (matched == null || load == null) {
-          return;
-        }
-        await Promise.all([
-          loadOnce(load),
-          ...matched.route.layouts.map((layout) => loadOnce(layout)),
-        ]);
-      },
-      refresh: async () => {
-        if (!isBrowser()) {
-          return;
-        }
-        const nextResolved = await resolveMatch(
-          routeTable(),
-          window.location.pathname + window.location.search,
-        );
-        // No view transition, and it is the one place that is right: a refresh
-        // is the same URL resolved again, so a transition would animate a page
-        // into itself — a cross-fade between two frames of the same thing,
-        // which is a flicker with a name.
-        startTransition(() => {
-          setResolved(nextResolved);
-        });
-      },
-      back: () => {
-        if (isBrowser()) {
-          window.history.back();
-        }
-      },
-      forward: () => {
-        if (isBrowser()) {
-          window.history.forward();
-        }
-      },
-    }),
-    [navigate],
-  );
+  const router: Router = {
+    push: (to, options) => navigate(to, options),
+    replace: (to) => navigate(to, { replace: true }),
+    prefetch: async (to) => {
+      if (!isBrowser()) {
+        return;
+      }
+      const target = new URL(to, window.location.href);
+      const matched = matchRoute(routeTable().routes, target.pathname);
+      const load = matched?.route.page;
+      if (matched == null || load == null) {
+        return;
+      }
+      await Promise.all([
+        loadOnce(load),
+        ...matched.route.layouts.map((layout) => loadOnce(layout)),
+      ]);
+    },
+    refresh: async () => {
+      if (!isBrowser()) {
+        return;
+      }
+      const nextResolved = await resolveMatch(
+        routeTable(),
+        window.location.pathname + window.location.search,
+      );
+      // No view transition, and it is the one place that is right: a refresh
+      // is the same URL resolved again, so a transition would animate a page
+      // into itself — a cross-fade between two frames of the same thing,
+      // which is a flicker with a name.
+      startTransition(() => {
+        setResolved(nextResolved);
+      });
+    },
+    back: () => {
+      if (isBrowser()) {
+        window.history.back();
+      }
+    },
+    forward: () => {
+      if (isBrowser()) {
+        window.history.forward();
+      }
+    },
+  };
 
-  const value = useMemo<RouterState>(
-    () => ({ resolved, router, pending }),
-    [resolved, router, pending],
-  );
+  const value: RouterState = { resolved, router, pending };
   return <RouterContext.Provider value={value}>{children}</RouterContext.Provider>;
 }
 
@@ -2697,14 +2695,37 @@ function isExternal(to: string): boolean {
  * The argument documents where the routes live; the table itself is generated
  * from that directory at build time and installed by the entry that starts
  * the app, so the component only has to render it.
+ *
+ * # Why the render anchor is here
+ *
+ * `RenderProvider` fixes the render's instant, time zone and random seed once,
+ * writes them into the markup and reads them back on the client, which is what
+ * makes `useRenderedAt` and `useRandom` agree across hydration. An application
+ * that did not render one got no error — it got the old behaviour, which is a
+ * silent hydration mismatch in every page with a clock or a shuffle on it. A
+ * guarantee that depends on remembering to opt in is not one, so the router
+ * provides it and an application that wants different values *replaces* it by
+ * rendering its own inside this one. See ubugeeei-prod/uf#559.
+ *
+ * Above `RouterProvider` rather than below it, because the route's own
+ * modules — layouts as much as pages — are things that read a clock, and a
+ * masthead showing the time is the first component anybody writes that does.
+ *
+ * It is safe above a root layout that renders `<html>` only because the
+ * envelope's carrier is a `<meta>`: React hoists one into the head of a
+ * document it rendered, and to the front of a tree that is not one, where uf's
+ * shell lifts it into the head it wrote itself. `packages/hooks/render.js` has
+ * the argument, and it is the reason the carrier is no longer a `<script>`.
  */
 export function routerView(root: string): React.ComponentType<AppProps> {
   void root;
   component App(url: string, initial: ResolvedRoute) {
     return (
-      <RouterProvider url={url} initial={initial}>
-        <RouteView />
-      </RouterProvider>
+      <RenderProvider>
+        <RouterProvider url={url} initial={initial}>
+          <RouteView />
+        </RouterProvider>
+      </RenderProvider>
     );
   }
   return App;

package/middleware.js

@@ -38,9 +38,18 @@
 // `@uniflowed/server/host`, once per request, around everything that answers
 // it — and the guard, the handler or page underneath it, and the render all
 // see that one context. So `cookies()` in a guard and `cookies()` in the page
-// it guards are the same cookies, `draftMode().enable()` in a guard is visible
-// to what it guards, and every `after()` on the request is one ordered list
-// the host drains after the response has gone.
+// it guards are the same cookies, `draftMode().isEnabled` gives a guard and
+// the page under it the same answer, and every `after()` on the request is one
+// ordered list the host drains after the response has gone.
+//
+// *Changing* draft mode is not a guard's to do, and that is a separate rule
+// with a separate reason: `enable()` writes a cookie, a cookie is part of a
+// response, and a guard may decline — so a guard that turned draft mode on and
+// then let the request through would have made a decision with nowhere to be
+// written. `asResponder` marks the two calls that do own a response, a route
+// handler and a server action, and `draftMode().enable()` refuses anywhere
+// else by name. A guard that wants draft mode on answers with a redirect to
+// the handler that turns it on. See ubugeeei-prod/uf#282.
 //
 // It used to be the other way, and it is worth saying why that was wrong
 // rather than merely different: this module built its own context and drained
@@ -140,8 +149,8 @@ export function createMiddlewareRunner(options: {|
       const middleware = pick(await record.load(), record.file);
       // In the host's context, not one of this module's own. Two middleware on
       // the same path see the same cookies, and so does the handler or the page
-      // underneath them: `draftMode().enable()` in a guard is visible to what
-      // it guards, and every `after()` on the request lands in one ordered list
+      // underneath them: `draftMode().isEnabled` is one answer for the whole
+      // request, and every `after()` on the request lands in one ordered list
       // that the host drains once, after the response has gone.
       const result = await middleware(request, { params, searchParams: url.searchParams });
       if (result != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.13",
+  "version": "0.0.0-alpha.14",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/server": "0.0.0-alpha.13"
+    "@uniflowed/hooks": "0.0.0-alpha.14",
+    "@uniflowed/server": "0.0.0-alpha.14"
   }
 }