@uniflowed/vite 0.0.0-alpha.40 → 0.0.0-alpha.42

package/driver.js

@@ -42,6 +42,7 @@
 import { randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { builtinModules, register } from "node:module";
+import { esmExternalRequirePlugin } from "rolldown/plugins";
 import { installFlowHooks } from "@uniflowed/host/internal/sync-hooks.js";
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -524,6 +525,9 @@ async function preview() {
         if ((request.url ?? "").split("?")[0].endsWith("/__uf.flight")) {
           response.setHeader("content-type", "text/x-component");
         }
+        if ((request.url ?? "").split("?")[0] === "/.well-known/apple-app-site-association") {
+          response.setHeader("content-type", "application/json; charset=utf-8");
+        }
         next();
       });
       if (handle == null) return;
@@ -1576,7 +1580,12 @@ async function deploy() {
     plugins: [
       ...inline.plugins,
       nativeAddonGuard(),
-      ...(shape.workerBuiltins === true ? [workerBuiltinGuard()] : []),
+      ...(shape.workerBuiltins === true
+        ? [
+            workerBuiltinGuard(),
+            esmExternalRequirePlugin({ external: [...builtinModules, /^node:/] }),
+          ]
+        : []),
     ],
     // Fixed, because this bundle inlines every dependency and so both of each
     // React package's builds, and a runtime lookup of `NODE_ENV` in a worker
@@ -1607,6 +1616,10 @@ async function deploy() {
       emptyOutDir: false,
       rollupOptions: {
         input,
+        // Workers provide the selected built-ins, but cannot use Node's
+        // createRequire(import.meta.url) runtime helper. External requires
+        // above become ESM imports; the remaining helpers are platform neutral.
+        ...(shape.workerBuiltins === true ? { platform: "neutral" } : {}),
         output: {
           entryFileNames: "[name].js",
           // Route modules are lazy `import()`s, so the server bundle splits
@@ -1677,11 +1690,12 @@ async function deploy() {
 function handlerEntrySource(document, cache, capabilities, build, regeneration) {
   const route = cache?.route === true;
   const fetchCache = cache?.fetch === true;
+  const dataCache = cache?.data === true;
   // Nothing at all when both switches are off, so a default project's
   // `handler.js` is the file it has always been. A cache that appears in
   // generated output nobody asked for is the second half of the complaint
   // #277 makes about the first half.
-  const store = route || fetchCache;
+  const store = route || fetchCache || dataCache;
   const durable = store ? durableStoreSource(root, cache, build) : null;
   const options = [
     "app",
@@ -1716,7 +1730,7 @@ ${
       } See ubugeeei-prod/uf#277.
 const cache = { store: createCacheStore(${
         durable == null ? "" : `{ provider: ${durable.provider}, build: ${JSON.stringify(build)} }`
-      }), route: ${String(route)}, fetch: ${String(fetchCache)} };
+      }), route: ${String(route)}, fetch: ${String(fetchCache)}, data: ${String(dataCache)} };
 
 `
     : ""

package/index.js

@@ -44,11 +44,14 @@
 // `uniflowed(options)` returns the array; a project that wants to add a plugin
 // declares it in `uf.config.js` and the driver appends it after these.
 
-import { readdirSync } from "node:fs";
+import { instrumentationFile } from "./internal/instrumentation.js";
+
 import path from "node:path";
+import { nativeWebPlugin } from "./internal/native-web.js";
 
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
+import { relayConfig, relayDependencies, transformRelay } from "./internal/relay.js";
 
 import {
   AUDIT_PUBLIC_PATH,
@@ -59,7 +62,7 @@ import {
 } from "./internal/a11y.js";
 import { assetPlugin } from "./internal/assets.js";
 import { barrelImportsPlugin, namespaceViewOf } from "./internal/barrel-imports.js";
-import { emit, reportRenderError } from "./internal/events.js";
+import { emit, reportRenderError, errorEvent } from "./internal/events.js";
 import remarkFrontmatterExport from "./internal/frontmatter.js";
 import { highlightPlugin } from "./internal/highlight.js";
 import { moduleId } from "./internal/module-graph.js";
@@ -93,11 +96,12 @@ import {
   scanRoutes,
   serverModuleSource,
 } from "./internal/routes.js";
-import { TransformService, isFlowModule } from "@uniflowed/host/transform";
+import { TransformService, isFlowModule, uniflowedPackages } from "@uniflowed/host/transform";
 import {
   DEV_RSC_HOOK,
   FLIGHT_BROWSER_DEPENDENCIES,
   FLIGHT_VIRTUAL,
+  INTERCEPTED_FROM_HEADER,
   RSC_ENVIRONMENT,
   builtBridgeSource,
   builtReferencesSource,
@@ -118,6 +122,7 @@ import {
   rscEnvironment,
 } from "./internal/flight.js";
 import { createChannelMiddleware } from "./internal/diagnostics.js";
+import { startDevState } from "./internal/dev-state.js";
 import { devtoolsPreamble } from "./internal/devtools.js";
 import { send, toAddressRequest, toRequest } from "./internal/http.js";
 import {
@@ -133,6 +138,25 @@ import { serverComponentsProblem } from "./internal/server-components.js";
 const resolved = (id) => `\0${id}`;
 const VIRTUAL_IDS = new Set([...Object.values(VIRTUAL), ...Object.values(FLIGHT_VIRTUAL)]);
 
+/**
+ * CommonJS packages the browser can reach only through an installed
+ * `@uniflowed/*` package.
+ *
+ * uf excludes its own packages from Vite's dependency optimizer because they
+ * ship Flow, so Vite will not discover a CommonJS peer through them once they
+ * live under a project's `node_modules`. React Testing's `happy-dom` edge is
+ * ESM and browser-mapped to a local stub, and the optional `axe-core` edge is
+ * named separately below only when the project actually installed it.
+ */
+const CLIENT_COMMONJS_DEPENDENCIES = Object.freeze([
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react/compiler-runtime",
+  "react-dom",
+  "react-dom/client",
+]);
+
 /**
  * Prefix of the virtual module that carries one source module's StyleX rules.
  *
@@ -229,6 +253,7 @@ export default function uniflowed(options = {}) {
       routing,
       command: options.command,
       accessibility,
+      relayEnabled: builtins.relay !== false,
     }),
     ...(flightState == null ? [] : [clientReferencePlugin(flightState), clientModuleUrlPlugin()]),
     // After the references, so a client module the rsc graph has already
@@ -242,6 +267,7 @@ export default function uniflowed(options = {}) {
       og: builtins.og ?? {},
       command: options.command,
     }),
+    nativeWebPlugin(routeTarget),
   ];
 }
 
@@ -257,6 +283,7 @@ function flowPlugin({
   routing,
   command,
   accessibility,
+  relayEnabled,
 }) {
   let root = process.cwd();
   let isProduction = false;
@@ -276,6 +303,7 @@ function flowPlugin({
   let server = null;
   /** @type {TransformService | null} */
   let service = null;
+  let relayOptions = null;
   /**
    * Each module's compiled stylesheet, keyed by the virtual id serving it.
    *
@@ -413,16 +441,12 @@ function flowPlugin({
         // uf serves HTML itself; there is no index.html to fall back to.
         appType: "custom",
         resolve: {
-          dedupe: ["react", "react-dom"],
+          dedupe: ["react", "react-dom", "react-relay", "relay-runtime"],
         },
         optimizeDeps: {
           include: [
-            "react",
-            "react/jsx-runtime",
-            "react/jsx-dev-runtime",
-            "react/compiler-runtime",
-            "react-dom",
-            "react-dom/client",
+            ...CLIENT_COMMONJS_DEPENDENCIES,
+            ...relayDependencies(projectRoot),
             // React's Flight client, for an application whose routes render as
             // Server Components; `FLIGHT_BROWSER_DEPENDENCIES` says why.
             ...(flightState == null ? [] : FLIGHT_BROWSER_DEPENDENCIES),
@@ -455,6 +479,7 @@ function flowPlugin({
           : {
               environments: {
                 [RSC_ENVIRONMENT]: rscEnvironment({
+                  root: projectRoot,
                   production: env.command === "build",
                   exclude: uniflowedPackages(projectRoot),
                 }),
@@ -556,6 +581,7 @@ function flowPlugin({
       // looking at. See `clientModuleSource`.
       if (id === resolved(VIRTUAL.client) && flightState != null) {
         return flightClientSource(entryPath, {
+          instrumentation: instrumentationFile(appRoot, true),
           strictMode: strictMode && !isProduction,
           navigation,
           staleTime,
@@ -564,6 +590,7 @@ function flowPlugin({
       }
       if (id === resolved(VIRTUAL.client)) {
         return clientModuleSource(entryPath, {
+          instrumentation: instrumentationFile(appRoot, true),
           strictMode: strictMode && !isProduction,
           navigation,
           staleTime,
@@ -573,8 +600,14 @@ function flowPlugin({
       }
       if (id === resolved(VIRTUAL.server)) {
         return flightState == null
-          ? serverModuleSource(entryPath, routing)
-          : flightServerSource(entryPath, VIRTUAL.routes, VIRTUAL.actions, routing);
+          ? serverModuleSource(entryPath, routing, instrumentationFile(appRoot))
+          : flightServerSource(
+              entryPath,
+              VIRTUAL.routes,
+              VIRTUAL.actions,
+              routing,
+              instrumentationFile(appRoot),
+            );
       }
       if (flightState != null) {
         if (id === resolved(FLIGHT_VIRTUAL.entry)) return rscEntrySource(VIRTUAL.routes, routing);
@@ -657,7 +690,16 @@ function flowPlugin({
         reported,
         suppressed,
       });
-      const map = out.map == null ? null : JSON.parse(out.map);
+      let map = out.map == null ? null : JSON.parse(out.map);
+      let output = out.code;
+      if (relayEnabled && output.includes("graphql")) {
+        relayOptions ??= relayConfig(root);
+        const transformed = await transformRelay(output, cleanId(id), map, await relayOptions);
+        if (transformed != null) {
+          output = transformed.code;
+          map = transformed.map;
+        }
+      }
       // StyleX. `uf transform` compiled the module's `stylex.create` calls into
       // class names and handed back the rules they declared; the rules become a
       // module of their own that this one imports.
@@ -675,7 +717,6 @@ function flowPlugin({
       // and an absolute name would publish where the machine that built it
       // keeps its files. A module outside the root climbs out with `../`.
       const styled = out.css != null && out.css !== "";
-      let output = out.code;
       if (styled) {
         const styleId = `${STYLE_PREFIX}${moduleId(root, cleanId(id))}.css`;
         styles.set(styleId, out.css);
@@ -763,6 +804,16 @@ function flowPlugin({
 
     configureServer(devServer) {
       server = devServer;
+      const diagnostics = startDevState(root, () => ({
+        routes: scanRoutes(appRoot, { target: routeTarget }).routes.map((route) => ({
+          path: route.path,
+          page: route.page,
+          layouts: route.layouts,
+        })),
+        actions: actionTables().table,
+      }));
+      devServer.middlewares.use(diagnostics.middleware);
+      devServer.httpServer?.once("close", diagnostics.close);
       // The ssr graph's way into the rsc graph; see `devBridgeSource`.
       if (flightState != null) {
         globalThis[Symbol.for(DEV_RSC_HOOK)] = () =>
@@ -823,8 +874,10 @@ function flowPlugin({
       const reserved = new RegExp(`/(${stems})(\\.[a-z]+)?\\.(js|jsx|mdx)$`);
       const onRouteFile = (file) => {
         if (!reserved.test(file) || !file.startsWith(appRoot)) return;
-        const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
-        if (routes) devServer.moduleGraph.invalidateModule(routes);
+        for (const id of [VIRTUAL.routes, VIRTUAL.server, VIRTUAL.client]) {
+          const module = devServer.moduleGraph.getModuleById(resolved(id));
+          if (module) devServer.moduleGraph.invalidateModule(module);
+        }
         devServer.ws.send({ type: "full-reload", path: "*" });
       };
       devServer.watcher.on("add", onRouteFile);
@@ -995,8 +1048,10 @@ function flowPlugin({
               if (payloadFor != null && (request.method === "GET" || request.method === "HEAD")) {
                 const query = url.includes("?") ? url.slice(url.indexOf("?")) : "";
                 const target = payloadFor + query;
+                const fromHeader = request.headers[INTERCEPTED_FROM_HEADER];
                 const answered = await entry.flight(target, {
                   onError: (error) => reportRenderError(devServer, target, error),
+                  interceptedFrom: Array.isArray(fromHeader) ? fromHeader[0] : fromHeader,
                 });
                 if (answered.error != null) reportRenderError(devServer, target, answered.error);
                 if (request.method === "HEAD") await answered.stream?.cancel();
@@ -1148,6 +1203,12 @@ function flowPlugin({
             // Map the stack back onto the Flow source before it reaches the
             // overlay.
             if (error instanceof Error) devServer.ssrFixStacktrace(error);
+            emit("diagnostic", {
+              severity: "error",
+              kind: "runtime",
+              origin: url,
+              ...errorEvent(error),
+            });
             next(error);
           }
         });
@@ -1420,24 +1481,3 @@ function cleanId(id) {
   const at = id.indexOf("?");
   return at === -1 ? id : id.slice(0, at);
 }
-
-/**
- * Every `@uniflowed/*` package the project can resolve, for
- * `optimizeDeps.exclude`, which takes names rather than patterns.
- */
-function uniflowedPackages(root) {
-  const names = new Set();
-  let directory = root;
-  for (let depth = 0; depth < 16; depth += 1) {
-    const scope = path.join(directory, "node_modules", "@uniflowed");
-    try {
-      for (const entry of readdirSync(scope)) names.add(`@uniflowed/${entry}`);
-    } catch {
-      // no packages at this level
-    }
-    const parent = path.dirname(directory);
-    if (parent === directory) break;
-    directory = parent;
-  }
-  return [...names].sort();
-}

package/internal/dev-state.js

@@ -0,0 +1,161 @@
+// @noflow
+// A local, bounded snapshot of the same diagnostic channel the terminal reads.
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { format } from "node:util";
+
+const requests = new AsyncLocalStorage();
+let receive = null;
+
+export function recordDevEvent(event) {
+  const request = requests.getStore();
+  receive?.({ ...event, ...(request == null ? {} : request), time: Date.now() });
+}
+
+export function startDevState(root, metadata) {
+  const directory = path.join(root, ".uf");
+  if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink())
+    throw new Error("uf dev: .uf must not be a symlink for diagnostics");
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, "dev-state.json");
+  if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink())
+    throw new Error("uf dev: diagnostic state must not be a symlink");
+  const session = randomUUID();
+  const temporary = path.join(directory, "dev-state-" + session + ".tmp");
+  const state = {
+    schema: 1,
+    session,
+    pid: process.pid,
+    startedAt: Date.now(),
+    updatedAt: 0,
+    generation: 0,
+    errors: [],
+    logs: [],
+    routes: [],
+    actions: [],
+  };
+  let closed = false;
+  const persist = (refresh = false) => {
+    if (closed) return;
+    if (refresh || state.updatedAt === 0) {
+      let current;
+      try {
+        current = metadata();
+        state.metadataError = null;
+      } catch (error) {
+        state.metadataError = String(error.message ?? error).slice(0, 4000);
+        current = { routes: state.routes, actions: state.actions };
+      }
+      state.routes = current.routes.slice(0, 1000);
+      state.actions = current.actions.slice(0, 1000);
+      state.truncated = current.routes.length > 1000 || current.actions.length > 1000;
+    }
+    state.updatedAt = Date.now();
+    let serialized = JSON.stringify(state);
+    while (Buffer.byteLength(serialized) > 3 * 1024 * 1024) {
+      const rows = state.logs.length
+        ? state.logs
+        : state.errors.length
+          ? state.errors
+          : state.routes.length
+            ? state.routes
+            : state.actions;
+      if (rows.length === 0) break;
+      rows.shift();
+      state.truncated = true;
+      serialized = JSON.stringify(state);
+    }
+    fs.writeFileSync(temporary, serialized, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+  };
+  const observer = (event) => {
+    const safe = bound(event);
+    if (event.event === "source-changed") {
+      state.generation += 1;
+      state.errors = [];
+    }
+    if (
+      event.event === "error" ||
+      (event.event === "log" && event.level === "error") ||
+      (event.event === "diagnostic" && event.severity === "error")
+    ) {
+      safe.kind ??= /hydrat/i.test(event.message ?? "")
+        ? "hydration"
+        : event.event === "diagnostic"
+          ? "runtime"
+          : "build";
+      state.errors.push(safe);
+      state.errors = state.errors.slice(-100);
+    }
+    if (["log", "diagnostic", "error", "request"].includes(event.event)) {
+      state.logs.push(safe);
+      state.logs = state.logs.slice(-150);
+    }
+    persist(event.event === "source-changed");
+  };
+  receive = observer;
+  persist();
+  // The terminal sees application console output too; keep its original behavior.
+  const originals = new Map();
+  for (const level of ["log", "info", "warn", "error", "debug"]) {
+    const original = console[level];
+    const wrapper = (...args) => {
+      recordDevEvent({ event: "log", level, kind: "runtime", message: format(...args) });
+      original.apply(console, args);
+    };
+    originals.set(level, { original, wrapper });
+    console[level] = wrapper;
+  }
+  const timer = setInterval(() => {
+    try {
+      persist(true);
+    } catch {
+      close();
+    }
+  }, 5000);
+  timer.unref?.();
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    clearInterval(timer);
+    if (receive === observer) receive = null;
+    for (const [level, { original, wrapper }] of originals) {
+      if (console[level] === wrapper) console[level] = original;
+    }
+    try {
+      if (JSON.parse(fs.readFileSync(file, "utf8")).session === session) fs.unlinkSync(file);
+    } catch {
+      /* A missing or unreadable channel is reported by the MCP reader. */
+    }
+    process.off("exit", close);
+  };
+  process.once("exit", close);
+  return {
+    close,
+    middleware(request, response, next) {
+      const requestId = randomUUID();
+      const url = String(request.url ?? "/")
+        .split("?")[0]
+        .slice(0, 1000);
+      response.setHeader("x-uf-request-id", requestId);
+      requests.run({ requestId, url }, () => {
+        observer({ event: "request", requestId, url, method: request.method, time: Date.now() });
+        next();
+      });
+    },
+  };
+}
+
+function bound(value, depth = 0) {
+  if (typeof value === "string") return value.slice(0, 4000);
+  if (value == null || typeof value !== "object") return value;
+  if (depth > 4) return "[truncated]";
+  if (Array.isArray(value)) return value.slice(0, 40).map((v) => bound(v, depth + 1));
+  return Object.fromEntries(
+    Object.entries(value)
+      .slice(0, 32)
+      .map(([key, v]) => [key, bound(v, depth + 1)]),
+  );
+}

package/internal/events.js

@@ -11,6 +11,7 @@
 // logger, which is redirected here as well so nothing bypasses the channel.
 
 import { createLogger } from "vite";
+import { recordDevEvent } from "./dev-state.js";
 
 /**
  * Emit one event.
@@ -19,6 +20,7 @@ import { createLogger } from "vite";
  * `done` is on the pipe before the process exits.
  */
 export function emit(event, fields = {}) {
+  recordDevEvent({ event, ...fields });
   process.stdout.write(`${JSON.stringify({ event, ...fields })}\n`);
 }
 
@@ -67,6 +69,7 @@ export function reportRenderError(server, url, error) {
   if (error instanceof Error) {
     server.ssrFixStacktrace(error);
   }
+  emit("diagnostic", { severity: "error", kind: "runtime", origin: url, ...errorEvent(error) });
   const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
   server.config.logger.error(`${url} rendered its error boundary\n${stripAnsi(detail)}`);
 }

package/internal/flight.js

@@ -49,7 +49,10 @@
 // In development the rsc environment's module graph is read instead, once the
 // route's modules have been imported.
 
+import { clientInstrumentationSource } from "./instrumentation.js";
+
 import path from "node:path";
+import { relayDependencies } from "./relay.js";
 
 import {
   createRunnableDevEnvironment,
@@ -120,6 +123,9 @@ export const DEV_RSC_HOOK = "uf.dev.rsc";
  */
 export const FLIGHT_SEGMENT = "__uf.flight";
 
+/** The header a browser sends when a Flight payload should render an interception. */
+export const INTERCEPTED_FROM_HEADER = "uf-intercepted-from";
+
 /** The document a payload path is for, or `null` for any other path. */
 export function flightDocumentPath(pathname) {
   const suffix = `/${FLIGHT_SEGMENT}`;
@@ -166,7 +172,7 @@ export function rendersFlight(app, { mount, routeTarget }) {
  *
  * @param {{ production: boolean, exclude: Array<string> }} options
  */
-export function rscEnvironment({ production, exclude }) {
+export function rscEnvironment({ production, exclude, root = process.cwd() }) {
   return {
     consumer: "server",
     resolve: {
@@ -180,6 +186,7 @@ export function rscEnvironment({ production, exclude }) {
         "react/jsx-runtime",
         "react/jsx-dev-runtime",
         "react-server-dom-parcel/server",
+        ...relayDependencies(root, true),
       ],
       exclude,
     },
@@ -661,7 +668,7 @@ export function flightClientSource(appEntry, options = {}) {
     options.staleTime > 0 ? `, staleTime: ${JSON.stringify(options.staleTime)}` : "";
   return `import { hydrateFlight } from "@uniflowed/router/rsc/client";
 import App from ${JSON.stringify(appEntry)};
-hydrateFlight({ App${strictMode}${navigation}${staleTime}${routing} });
+${clientInstrumentationSource(options.instrumentation)}hydrateFlight({ App${strictMode}${navigation}${staleTime}${routing} });
 `;
 }
 
@@ -682,9 +689,13 @@ export function flightServerSource(
   routesId,
   actionsId,
   routing = { redirects: [], rewrites: [], headers: [], basePath: "", trailingSlash: "ignore" },
+  instrumentation = null,
 ) {
   return `import {
   createActionDispatcher,
+  createInstrumentation,
+  instrumentRender,
+  traceRequestPhase,
   createDispatcher,
   createMiddlewareRunner,
   installRouting,
@@ -698,15 +709,22 @@ import App from ${JSON.stringify(appEntry)};
 export const routing = ${JSON.stringify(routing)};
 installRouting(routing);
 export { routes, handlers, middleware, notFound, errors };
-export { beginRequest } from "@uniflowed/router/server";
+${instrumentation == null ? "" : `import * as hooks from ${JSON.stringify(instrumentation)};`}
+export const { beginRequest } = createInstrumentation(${instrumentation == null ? "" : "hooks"});
 const renderer = createDocumentRenderer({ App, renderFlight, loadClientModule });
-export const render = renderer.render;
+export const render = (url, assets, options = {}) => instrumentRender(
+  (onError) => renderer.render(url, assets, { ...options, onError }), options.onError,
+);
 export const prerender = renderer.prerender;
-export const flight = renderer.flight;
+export const flight = (url, options = {}) => instrumentRender(
+  (onError) => renderer.flight(url, { ...options, onError }), options.onError,
+);
 export { shellDocument } from "@uniflowed/router/server";
-export const dispatch = createDispatcher({ handlers });
+const dispatchRoute = createDispatcher({ handlers });
+export const dispatch = (request) => traceRequestPhase("route", () => dispatchRoute(request));
 export const callAction = createActionDispatcher({ actions });
-export const runMiddleware = createMiddlewareRunner({ middleware });
+const guard = createMiddlewareRunner({ middleware });
+export const runMiddleware = (request) => traceRequestPhase("middleware", () => guard(request));
 `;
 }
 
@@ -731,7 +749,7 @@ export function devStylesheets(server) {
     // package's, which Vite serves under `/@fs/` — and the same rule a client
     // reference's URL follows. A stylesheet with no file is a virtual one.
     urls.push(
-      typeof module.file === "string" && module.file !== ""
+      typeof module.file === "string" && path.isAbsolute(module.file)
         ? devUrlOf(root, base, module.file)
         : `${base.replace(/\/$/, "")}/@id/${id.replace(/\0/g, "__x00__")}`,
     );

package/internal/instrumentation.js

@@ -0,0 +1,23 @@
+// @noflow
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export function instrumentationFile(root, client = false) {
+  const stem = client ? "$instrumentation.client" : "$instrumentation";
+  const files = [".js", ".jsx"]
+    .map((extension) => path.join(root, stem + extension))
+    .filter(existsSync);
+  if (files.length > 1)
+    throw new Error(`uf: choose one instrumentation module: ${files.join(", ")}`);
+  return files[0] ?? null;
+}
+
+export function clientInstrumentationSource(file) {
+  if (file == null) return "";
+  return `import * as instrumentation from ${JSON.stringify(file)};
+import { installClientInstrumentation } from "@uniflowed/router/instrumentation";
+const disposeInstrumentation = await installClientInstrumentation(instrumentation);
+if (import.meta.hot) import.meta.hot.dispose(disposeInstrumentation);
+`;
+}

package/internal/native-web.js

@@ -0,0 +1,26 @@
+// @noflow
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/** React Native Web is supplied by the application, including its version. */
+export function nativeWebPlugin(target) {
+  let root = process.cwd();
+  return {
+    name: "uf:react-native-web",
+    enforce: "pre",
+    configResolved(config) {
+      root = config.root;
+    },
+    resolveId(source) {
+      if (target !== "web" || source !== "react-native") return null;
+      try {
+        return createRequire(path.join(root, "package.json")).resolve("react-native-web");
+      } catch {
+        throw new Error(
+          "A shared React Native page needs the application's react-native-web dependency: run `uf add react-native-web`.",
+        );
+      }
+    },
+  };
+}

package/internal/relay.js

@@ -0,0 +1,74 @@
+// @noflow
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** CommonJS hidden behind uf's excluded Flow packages still needs prebundling. */
+export function relayDependencies(root, server = false) {
+  const require = createRequire(path.join(root, "package.json"));
+  const entries = server
+    ? ["relay-runtime", "relay-runtime/experimental", "react-relay/rsc_EXPERIMENTAL.js"]
+    : ["relay-runtime", "react-relay", "react-relay/rsc-client_EXPERIMENTAL.js"];
+  return entries.filter((entry) => {
+    try {
+      require.resolve(entry);
+      return true;
+    } catch (error) {
+      if (error.code === "MODULE_NOT_FOUND" || error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+        return false;
+      throw error;
+    }
+  });
+}
+
+/** Resolve config from the application, independently of the process's cwd. */
+export async function relayConfig(root) {
+  for (const name of ["relay.config.json", "relay.config.js", "relay.config.mjs"]) {
+    const filename = path.join(root, name);
+    if (!fs.existsSync(filename)) continue;
+    const config = name.endsWith(".json")
+      ? JSON.parse(fs.readFileSync(filename, "utf8"))
+      : (await import(pathToFileURL(filename).href)).default;
+    return artifactOptions(root, config);
+  }
+  const filename = path.join(root, "package.json");
+  const config = fs.existsSync(filename)
+    ? JSON.parse(fs.readFileSync(filename, "utf8")).relay
+    : null;
+  return artifactOptions(root, config);
+}
+
+function artifactOptions(root, config) {
+  if (config?.projects != null) {
+    throw new Error("uf's Relay integration currently needs a single-project Relay config.");
+  }
+  return {
+    artifactDirectory:
+      config?.artifactDirectory == null ? null : path.resolve(root, config.artifactDirectory),
+    eagerEsModules: true,
+    jsModuleFormat: "commonjs",
+    codegenCommand: "uf run relay",
+  };
+}
+
+/** Flow has already lowered components/hooks; Relay owns the GraphQL transform. */
+export async function transformRelay(code, filename, map, options) {
+  if (
+    !code.includes("graphql") ||
+    !/["'](?:@uniflowed\/relay|react-relay|relay-runtime)["']/.test(code)
+  )
+    return null;
+  const [{ transformAsync }, { default: relay }] = await Promise.all([
+    import("@babel/core"),
+    import("babel-plugin-relay"),
+  ]);
+  return transformAsync(code, {
+    filename,
+    babelrc: false,
+    configFile: false,
+    sourceMaps: true,
+    inputSourceMap: map ?? undefined,
+    plugins: [[relay, options]],
+  });
+}

package/internal/routes.js

@@ -14,6 +14,8 @@
 // route table imports every page and layout lazily, so a route is a chunk of
 // its own and the client only downloads what it navigates to.
 
+import { clientInstrumentationSource } from "./instrumentation.js";
+
 import { readdirSync, statSync } from "node:fs";
 import path from "node:path";
 
@@ -28,6 +30,7 @@ export const RESERVED = Object.freeze({
   error: "$error",
   loading: "$loading",
   route: "$route",
+  instrumentation: "$instrumentation",
 });
 
 /**
@@ -381,6 +384,15 @@ export function scanRoutes(appRoot, options = {}) {
     );
 
     refuseUnsupportedTemplateFiles(directory, entries);
+    for (const entry of entries) {
+      if (entry.name.startsWith("$instrumentation") && !/\.test\.jsx?$/.test(entry.name)) {
+        if (depth !== 0 || !/^\$instrumentation(?:\.client)?\.jsx?$/.test(entry.name)) {
+          throw new Error(
+            `uf: ${path.join(directory, entry.name)} must be $instrumentation.js or $instrumentation.client.js at the router root`,
+          );
+        }
+      }
+    }
 
     // A `$default.js` answers one question — what a slot renders when the
     // URL says nothing about it — and this walk is everywhere a slot is not,
@@ -1660,7 +1672,7 @@ export function clientModuleSource(appEntry, options = {}) {
   return `import { ${mount} } from "@uniflowed/router/client";
 import { routes, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-${mount}({ App, routes, notFound, errors${strictMode}${navigation}${staleTime}${routing} });
+${clientInstrumentationSource(options.instrumentation)}${mount}({ App, routes, notFound, errors${strictMode}${navigation}${staleTime}${routing} });
 `;
 }
 
@@ -1718,9 +1730,12 @@ ${mount}({ App, routes, notFound, errors${strictMode}${navigation}${staleTime}${
  * shorter proof of the paragraph above: the copy the router dispatches and
  * renders with is by construction the copy the host is handed.
  */
-export function serverModuleSource(appEntry, routing = routingRulesOf({})) {
+export function serverModuleSource(appEntry, routing = routingRulesOf({}), instrumentation = null) {
   return `import {
   createActionDispatcher,
+  createInstrumentation,
+  instrumentRender,
+  traceRequestPhase,
   createDispatcher,
   createMiddlewareRunner,
   createRenderer,
@@ -1731,14 +1746,19 @@ import { actions } from ${JSON.stringify(VIRTUAL.actions)};
 import App from ${JSON.stringify(appEntry)};
 ${routingExportSource(routing)}installRouting(routing);
 export { routes, handlers, middleware, notFound, errors };
-export { beginRequest } from "@uniflowed/router/server";
+${instrumentation == null ? "" : `import * as hooks from ${JSON.stringify(instrumentation)};`}
+export const { beginRequest } = createInstrumentation(${instrumentation == null ? "" : "hooks"});
 const renderer = createRenderer({ App, routes, notFound, errors });
-export const render = renderer.render;
+export const render = (url, assets, options = {}) => instrumentRender(
+  (onError) => renderer.render(url, assets, { ...options, onError }), options.onError,
+);
 export const prerender = renderer.prerender;
 export { shellDocument } from "@uniflowed/router/server";
-export const dispatch = createDispatcher({ handlers });
+const dispatchRoute = createDispatcher({ handlers });
+export const dispatch = (request) => traceRequestPhase("route", () => dispatchRoute(request));
 export const callAction = createActionDispatcher({ actions });
-export const runMiddleware = createMiddlewareRunner({ middleware });
+const guard = createMiddlewareRunner({ middleware });
+export const runMiddleware = (request) => traceRequestPhase("middleware", () => guard(request));
 `;
 }
 

package/internal/serve.js

@@ -112,18 +112,19 @@ function deployment() {
  * a setting nobody can set would be the shape of configurability with none of
  * the substance.
  *
- * @param {{route?: boolean, fetch?: boolean, store?: string, storeDir?: string} | undefined} declared
+ * @param {{route?: boolean, fetch?: boolean, data?: boolean, store?: string, storeDir?: string} | undefined} declared
  * @param {(options?: object) => object} createCacheStore
  * @param {{root: string, build: string | null}} where
  */
 async function cacheFor(declared, createCacheStore, where) {
   const route = declared?.route === true;
   const fetchCache = declared?.fetch === true;
-  if (!route && !fetchCache) return undefined;
+  const data = declared?.data === true;
+  if (!route && !fetchCache && !data) return undefined;
   const provider = await providerFor(declared, where);
   const store =
     provider == null ? createCacheStore() : createCacheStore({ provider, build: where.build });
-  return { store, route, fetch: fetchCache };
+  return { store, route, fetch: fetchCache, data };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.40",
+  "version": "0.0.0-alpha.42",
   "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
   "type": "module",
   "license": "MIT",
@@ -32,12 +32,14 @@
     "!*.test.js"
   ],
   "dependencies": {
+    "@babel/core": "^7.29.7",
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.40",
-    "@uniflowed/router": "0.0.0-alpha.40",
-    "@uniflowed/server": "0.0.0-alpha.40",
-    "@uniflowed/validator": "0.0.0-alpha.40",
+    "@uniflowed/host": "0.0.0-alpha.42",
+    "@uniflowed/router": "0.0.0-alpha.42",
+    "@uniflowed/server": "0.0.0-alpha.42",
+    "@uniflowed/validator": "0.0.0-alpha.42",
+    "babel-plugin-relay": "^21.0.1",
     "estree-util-value-to-estree": "^3.5.0",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
@@ -45,12 +47,13 @@
     "shiki": "^3.23.0",
     "unist-util-mdx-define": "^1.1.2",
     "vite": "^8.2.2",
-    "yaml": "^2.9.1"
+    "yaml": "^2.9.1",
+    "rolldown": "^1.2.7"
   },
   "peerDependencies": {
+    "axe-core": ">=4",
     "react": ">=19",
-    "react-dom": ">=19",
-    "axe-core": ">=4"
+    "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
     "axe-core": {