@uniflowed/vite 0.0.0-alpha.11 → 0.0.0-alpha.13

package/driver.js

@@ -246,6 +246,17 @@ async function dev() {
           return true;
         }
 
+        // A server action next, below the guard and above the handlers. It
+        // declines every request that carries no action id, so this costs a
+        // page request one header lookup; and it answers every request that
+        // carries one, refusals included, so an action can never fall through
+        // to a route handler that happens to sit at the URL it was posted to.
+        const acted = await entry.callAction(asRequest);
+        if (acted != null) {
+          await send(response, acted);
+          return true;
+        }
+
         // Route handlers next, and for every method: a handler is the only
         // thing that answers a POST, and it may also answer a GET for a path
         // that has no page.
@@ -749,7 +760,7 @@ async function compile() {
 const ADAPTERS = {
   node: {
     entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache),
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES),
       server: nodeEntrySource("./handler.js"),
     }),
   },
@@ -759,13 +770,13 @@ const ADAPTERS = {
   // `commands::deploy`.
   container: {
     entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache),
+      handler: handlerEntrySource(document, cache, NODE_CAPABILITIES),
       server: nodeEntrySource("./handler.js"),
     }),
   },
   edge: {
     entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache),
+      handler: handlerEntrySource(document, cache, EDGE_CAPABILITIES),
       worker: workerEntrySource("./handler.js"),
     }),
     // `workerd` first, so React resolves to the build that has
@@ -776,12 +787,33 @@ const ADAPTERS = {
   },
   serverless: {
     entries: (document, cache) => ({
-      handler: handlerEntrySource(document, cache),
+      handler: handlerEntrySource(document, cache, SERVERLESS_CAPABILITIES),
       lambda: lambdaEntrySource("./handler.js"),
     }),
   },
 };
 
+/**
+ * How each target says what it can do: the module, and the name to call.
+ *
+ * A pair of strings rather than a value, because this is the module that
+ * *writes* `handler.js` and never imports what it writes: the capabilities
+ * belong to the deployed application's copy of `@uniflowed/server`, not to the
+ * driver's. It is the same reason `beginRequest` is re-exported from the
+ * generated file rather than reached for here — see `handlerEntrySource`.
+ *
+ * Nothing is passed for `websocket` or `queue`, and that is not an oversight:
+ * uf defines both and implements neither, so a generated file that invented
+ * one would be inventing an upgrade for a runtime it cannot see. What the call
+ * does supply is the target's name and its two facts, which is what turns "an
+ * upgrade is not available" into "the serverless host cannot hold a socket
+ * open" and what lets `@uniflowed/server/lambda` refuse a queue that would be
+ * dropped.
+ */
+const NODE_CAPABILITIES = { module: "@uniflowed/server/node", name: "nodeCapabilities" };
+const EDGE_CAPABILITIES = { module: "@uniflowed/server/edge", name: "edgeCapabilities" };
+const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lambdaCapabilities" };
+
 /**
  * Link the application into a directory that can be copied, for
  * `uf build --adapter`.
@@ -952,7 +984,7 @@ async function deploy() {
  * package a bundler happened to give it, and the copy that matters is the one
  * the application resolved. See ubugeeei-prod/uf#277 and #389.
  */
-function handlerEntrySource(document, cache) {
+function handlerEntrySource(document, cache, capabilities) {
   const route = cache?.route === true;
   const fetchCache = cache?.fetch === true;
   // Nothing at all when both switches are off, so a default project's
@@ -960,9 +992,19 @@ function handlerEntrySource(document, cache) {
   // generated output nobody asked for is the second half of the complaint
   // #277 makes about the first half.
   const store = route || fetchCache;
+  const options = [
+    "app",
+    `document: ${JSON.stringify(document)}`,
+    ...(store ? ["cache"] : []),
+    "capabilities",
+  ].join(", ");
+  const cacheImport = store ? 'import { createCacheStore } from "@uniflowed/server/cache";\n' : "";
+  const from = JSON.stringify(capabilities.module);
+  const capabilityImport = `import { ${capabilities.name} } from ${from};`;
   return `// Generated by \`uf build --adapter\`. Not checked in, not edited.
 import { createFetchHandler } from "@uniflowed/server/fetch";
-${store ? 'import { createCacheStore } from "@uniflowed/server/cache";\n' : ""}import * as app from ${JSON.stringify(VIRTUAL.server)};
+${cacheImport}${capabilityImport}
+import * as app from ${JSON.stringify(VIRTUAL.server)};
 
 ${
   store
@@ -971,9 +1013,17 @@ ${
 // application. See ubugeeei-prod/uf#277.
 const cache = { store: createCacheStore(), route: ${String(route)}, fetch: ${String(fetchCache)} };
 
-export const fetch = createFetchHandler({ app, document: ${JSON.stringify(document)}, cache });`
-    : `export const fetch = createFetchHandler({ app, document: ${JSON.stringify(document)} });`
-}
+`
+    : ""
+}// What this target can do, and it is not the same for all four: whether a
+// response body reaches the client as it is produced, and whether the process
+// is still there once it has. A route handler that streams events or takes a
+// socket asks through this rather than finding out in production. Nothing is
+// passed for the upgrade or the queue — uf defines both and implements
+// neither. See \`@uniflowed/server/socket\` and \`@uniflowed/server/queue\`.
+const capabilities = ${capabilities.name}();
+
+export const fetch = createFetchHandler({ ${options} });
 export const beginRequest = app.beginRequest;
 
 export default { fetch, beginRequest };

package/index.js

@@ -55,7 +55,17 @@ import {
   preambleCode,
   refreshRuntimeSource,
 } from "./internal/refresh.js";
-import { RSC_MANIFEST_ENV, clientRouteFilter, readRscManifest } from "./internal/rsc.js";
+import {
+  ACTION_HEADER,
+  RSC_MANIFEST_ENV,
+  actionReferenceSource,
+  actionsModuleSource,
+  clientRouteFilter,
+  readRscManifest,
+  rscManifestKey,
+  serverActionModules,
+  serverActionTable,
+} from "./internal/rsc.js";
 import {
   RESERVED,
   VIRTUAL,
@@ -188,6 +198,35 @@ function flowPlugin({ routerRoot, appEntry, command }) {
     return routesModuleSource(table, { shipsPage: (route) => kept.has(route) });
   };
 
+  /**
+   * The manifest's two action tables, re-read only when the file changes.
+   *
+   * `load` runs for every module in the graph and has to ask "is this a
+   * `"use server"` module?" about each one, so parsing the manifest per call
+   * would put a JSON parse of the whole graph between Vite and every file it
+   * opens. Size and modification time are the identity — the same pair
+   * `.uf/cache/transform` keys on — and `uf dev` drops the memo outright when
+   * its watcher sees the file change, so a rewrite inside one millisecond is
+   * still seen.
+   */
+  let actionMemo = null;
+  const forgetActions = () => {
+    actionMemo = null;
+  };
+  const actionTables = () => {
+    const file = process.env[RSC_MANIFEST_ENV];
+    const key = rscManifestKey(file);
+    if (actionMemo == null || actionMemo.key !== key) {
+      const manifest = readRscManifest(file);
+      actionMemo = {
+        key,
+        modules: serverActionModules(manifest, root),
+        table: serverActionTable(manifest, root),
+      };
+    }
+    return actionMemo;
+  };
+
   return {
     name: "uf:flow",
     enforce: "pre",
@@ -256,7 +295,36 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       }
       if (id === resolved(VIRTUAL.client)) return clientModuleSource(entryPath);
       if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
+      // Only `virtual:uf/server` imports this, so it is only ever asked for in
+      // the server environment — but the table it carries is every callable
+      // endpoint of the build, so it is worth saying that a browser asking for
+      // it gets nothing rather than getting the list.
+      if (id === resolved(VIRTUAL.actions)) {
+        if (!isSsr(this, loadOptions))
+          return "export const actions = [];\nexport default actions;\n";
+        return actionsModuleSource(actionTables().table);
+      }
       if (id.startsWith(STYLE_PREFIX)) return styles.get(id) ?? "";
+
+      // A `"use server"` module, in the browser's graph only: what the client
+      // gets is one `createServerReference` per callable export, and never the
+      // file. This is where the second half of the RSC split actually happens
+      // — the route filter above decides which *pages* the browser is given,
+      // and this decides that an action module's body, its imports and
+      // everything only they reached are not the browser's business at all.
+      //
+      // Substituting the source rather than rewriting it: a transform that
+      // stripped the body would have to be right about every way a module can
+      // name something, and being wrong once means shipping a database handle.
+      // The exports the reference module declares come from the manifest, so
+      // they are exactly the exports `uf_rsc` decided are callable endpoints
+      // and an import of anything else is a build error rather than a silent
+      // `undefined`. `crates/uf_rsc/src/graph/build.rs` colours these modules
+      // server for the same reason, so the analysis and the bundle agree.
+      if (!isSsr(this, loadOptions)) {
+        const references = actionTables().modules.get(cleanId(id));
+        if (references != null) return actionReferenceSource(references);
+      }
       return null;
     },
 
@@ -378,8 +446,15 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         devServer.watcher.add(manifestPath);
         const onManifest = (file) => {
           if (path.resolve(file) !== manifestPath) return;
+          // The action tables are read from the same file and are memoised on
+          // its size and modification time, which is a pair two writes inside
+          // one millisecond can share. This is the answer that does not
+          // depend on a clock.
+          forgetActions();
           const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
           if (routes) devServer.moduleGraph.invalidateModule(routes);
+          const actions = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.actions));
+          if (actions) devServer.moduleGraph.invalidateModule(actions);
           devServer.ws.send({ type: "full-reload", path: "*" });
         };
         devServer.watcher.on("add", onManifest);
@@ -391,7 +466,14 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       // the renderer.
       return () => {
         devServer.middlewares.use(async (request, response, next) => {
-          if (!wantsDocument(request)) return next();
+          // Two kinds of request reach uf here, and the second one is why this
+          // is not `wantsDocument` alone: a server action is a `POST` carrying
+          // `uf-action`, which every gate below the renderer would refuse.
+          // `driver.js` claims every request and can afford to decide later;
+          // this middleware is mounted behind Vite's own and has to say up
+          // front which ones are uf's.
+          const document = wantsDocument(request);
+          if (!document && !isActionCall(request)) return next();
           try {
             const url = request.url ?? "/";
             const entry = await importServerEntry(devServer);
@@ -418,6 +500,19 @@ function flowPlugin({ routerRoot, appEntry, command }) {
                 return;
               }
 
+              // Then a server action, below the guard and above the handlers.
+              // It declines anything that carries no action id, so the two
+              // lines cost a document request one `headers.get`; and it never
+              // declines one that does, so an action call cannot reach a route
+              // handler that happens to share the URL it was posted to. The
+              // same two lines are in `driver.js`, in `fetch.js` for every
+              // deploy adapter, and in `standalone.js`.
+              const acted = await entry.callAction(asRequest);
+              if (acted != null) {
+                await send(response, acted);
+                return;
+              }
+
               // Then the route handlers, above the renderer and for the same
               // reason `driver.js` puts them there: a path that answers a
               // request is not a document, whatever the client said it would
@@ -438,6 +533,18 @@ function flowPlugin({ routerRoot, appEntry, command }) {
                 return;
               }
 
+              // A `POST` this middleware claimed because it named an action,
+              // that the endpoint then declined and no handler answered. It
+              // cannot happen — the endpoint answers every request carrying an
+              // id, including every refusal — and a page cannot answer a
+              // `POST` anyway, so the honest end is a 404 rather than a
+              // rendered document with a 200.
+              if (!document) {
+                response.statusCode = 404;
+                response.end();
+                return;
+              }
+
               const result = await entry.render(
                 url,
                 { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
@@ -507,6 +614,20 @@ async function importServerEntry(devServer) {
   return devServer.ssrLoadModule(VIRTUAL.server);
 }
 
+/**
+ * Whether this request is a server action call.
+ *
+ * The header alone, and never the path: an action is posted to the page's own
+ * URL, so there is nothing about the URL to recognise. Deliberately *not* the
+ * whole set of checks the endpoint makes — the origin, the content type, the
+ * body — because those decide whether the call is *allowed*, and a call that
+ * is not allowed must be refused by the endpoint rather than handed on to
+ * Vite's chain as though nobody had claimed it.
+ */
+function isActionCall(request) {
+  return request.method === "POST" && request.headers[ACTION_HEADER] != null;
+}
+
 function wantsDocument(request) {
   if (request.method !== "GET" && request.method !== "HEAD") return false;
   const url = request.url ?? "/";

package/internal/routes.js

@@ -20,6 +20,7 @@ import path from "node:path";
 /** The file names the router reserves inside the router root. */
 export const RESERVED = Object.freeze({
   layout: "_uf.layout",
+  template: "_uf.template",
   page: "_uf.page",
   middleware: "_uf.middleware",
   notFound: "_uf.not-found",
@@ -28,6 +29,31 @@ export const RESERVED = Object.freeze({
   route: "_uf.route",
 });
 
+/**
+ * Directory names uf reserves inside the router root without serving them.
+ *
+ * One spelling each, and they are here so `crates/uf_router/tests/
+ * reserved_names.rs` can hold this router and `uf_router::RouteSegment` to the
+ * same list — the way it already holds the two to the same `_uf.*` roles. A
+ * spelling one router refuses and the other serves as a URL is exactly the
+ * disagreement that made this necessary.
+ *
+ * `@team` is Next.js's parallel-route slot and `(.)photo` its intercepting
+ * route. uf has neither, and until #267 both fell through to "a literal URL
+ * segment": `@team` became `/@team`, `(.)photo` became `/(.)photo` — the test
+ * for a `(group)` is that the segment *ends* in `)` — and the generated
+ * `RoutePath` union contained them, so `route("/@team", …)` type checked. A
+ * convention served as nonsense is worse than one that is refused, because the
+ * project looks like it works.
+ */
+export const UNSUPPORTED_SEGMENTS = Object.freeze([
+  "@team",
+  "(.)photo",
+  "(..)photo",
+  "(...)photo",
+  "(..)(..)photo",
+]);
+
 /** Extensions a page or layout may use; `.mdx` is a page written as content. */
 const PAGE_EXTENSIONS = [".js", ".jsx", ".mdx"];
 const MODULE_EXTENSIONS = [".js", ".jsx"];
@@ -47,6 +73,8 @@ const MAX_DEPTH = 32;
  * @property {ReadonlyArray<{above: number, module: string}>} loading the
  *   `<Suspense>` boundaries in scope, root first; `above` is how many of
  *   `layouts` are outside each one
+ * @property {ReadonlyArray<{above: number, module: string}>} templates the
+ *   `_uf.template.js` wrappers in scope, root first, with the same `above`
  * @property {boolean} mdx whether the page is MDX content
  */
 
@@ -86,7 +114,9 @@ const MAX_DEPTH = 32;
  *
  * @typedef {object} NotFoundBoundary
  * @property {string} path route path of the directory that declares it
- * @property {string} page absolute path of the page module
+ * @property {?string} page absolute path of the page module, or `null` for the
+ *   record the scan synthesises at the router root when a project declares
+ *   none — see `scanRoutes`
  * @property {ReadonlyArray<string>} layouts absolute paths, root first
  * @property {boolean} mdx whether the page is MDX content
  */
@@ -103,7 +133,8 @@ const MAX_DEPTH = 32;
  *
  * @typedef {object} ErrorBoundary
  * @property {string} path route path of the directory that declares it
- * @property {string} module absolute path of the error module
+ * @property {?string} module absolute path of the error module, or `null` for
+ *   the synthesised root record
  * @property {ReadonlyArray<string>} layouts absolute paths, root first
  */
 
@@ -136,6 +167,10 @@ const MAX_DEPTH = 32;
  * Directories that do not exist yield an empty table rather than an error: a
  * library project has no router root, and that is not a mistake.
  *
+ * Throws for a directory named the way a parallel route or an intercepting
+ * route is spelled: uf has neither, and both used to become literal URL
+ * segments. See {@link UNSUPPORTED_SEGMENTS}.
+ *
  * @param {string} appRoot absolute path of the router root (`app/`)
  * @returns {{
  *   routes: Route[],
@@ -153,7 +188,11 @@ export function scanRoutes(appRoot) {
   const errors = [];
   if (!isDirectory(appRoot)) return { routes, handlers, middleware, notFound, errors };
 
-  const walk = (directory, segments, layouts, loading, depth) => {
+  // The layouts in scope at the router root, kept because the two synthesised
+  // records below are made of them. See the note beside them.
+  let rootLayouts = [];
+
+  const walk = (directory, segments, layouts, loading, templates, depth) => {
     if (depth > MAX_DEPTH) return;
     const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
       a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
@@ -161,6 +200,9 @@ export function scanRoutes(appRoot) {
 
     const ownLayout = findModule(directory, RESERVED.layout, MODULE_EXTENSIONS);
     const nextLayouts = ownLayout ? [...layouts, ownLayout] : layouts;
+    if (depth === 0) {
+      rootLayouts = nextLayouts;
+    }
 
     // Inside this directory's own layout, which is where Next.js puts it and
     // the only placement that makes sense: the fallback is what shows *within*
@@ -173,6 +215,17 @@ export function scanRoutes(appRoot) {
       ? [...loading, { above: nextLayouts.length, module: ownLoading }]
       : loading;
 
+    // A template accumulates the way a layout does, and is placed the way a
+    // loading file is: inside its own segment's layout and outside everything
+    // below, so `nextLayouts.length` is taken after the own layout is added.
+    // Every template above a route is on that route, one inside the next, for
+    // the reason every layout is — the difference between the two is a `key`,
+    // not a shape.
+    const ownTemplate = findModule(directory, RESERVED.template, MODULE_EXTENSIONS);
+    const nextTemplates = ownTemplate
+      ? [...templates, { above: nextLayouts.length, module: ownTemplate }]
+      : templates;
+
     // A middleware guards this directory and everything below it, whether or
     // not this directory is itself a route: `app/dashboard/_uf.middleware.js`
     // with no `_uf.page.js` beside it still guards `/dashboard/settings`.
@@ -191,6 +244,7 @@ export function scanRoutes(appRoot) {
         page,
         layouts: nextLayouts,
         loading: nextLoading,
+        templates: nextTemplates,
         mdx: page.endsWith(".mdx"),
       });
     }
@@ -233,17 +287,49 @@ export function scanRoutes(appRoot) {
       // A leading dot or underscore is private to the author: `_components/`
       // beside a page is a place to put things, not a route.
       if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
+      // Checked before descending, and after the private-directory test for
+      // the same reason `uf_router` prunes them: `app/_drafts/@team/` is not a
+      // route uf would have served, so it is not one to refuse.
+      const refused = unsupportedSegmentReason(entry.name);
+      if (refused != null) {
+        throw new Error(`${path.join(directory, entry.name)}: ${refused}`);
+      }
       walk(
         path.join(directory, entry.name),
         [...segments, entry.name],
         nextLayouts,
         nextLoading,
+        nextTemplates,
         depth + 1,
       );
     }
   };
 
-  walk(appRoot, [], [], [], 0);
+  walk(appRoot, [], [], [], [], 0);
+
+  // A boundary at the router root for a project that declared none, carrying
+  // the root's layouts and no module of its own.
+  //
+  // Without it the router had no record to answer an unmatched URL with, so it
+  // answered with the framework's page and `layouts: []` — and a site whose
+  // root layout owns the masthead, the stylesheet and often `<html>` itself
+  // replied to a stale link with a white page saying 404, with no way to leave
+  // it. That was never the nearest-ancestor rule failing: the rule had nothing
+  // to find. `uf create` scaffolds neither boundary, so this is the state every
+  // new project is in until it writes one. See ubugeeei-prod/uf#351.
+  //
+  // Only when nothing is at `/` already. A `(group)` directory is not a URL
+  // segment, so `app/(marketing)/_uf.not-found.js` is a boundary at `/` too and
+  // adding a second one there would put a second answer at a path the URL
+  // cannot choose between.
+  const atRoot = (boundaries) => boundaries.some((boundary) => boundary.path === "/");
+  if (!atRoot(notFound)) {
+    notFound.push({ path: "/", page: null, layouts: rootLayouts, mdx: false });
+  }
+  if (!atRoot(errors)) {
+    errors.push({ path: "/", module: null, layouts: rootLayouts });
+  }
+
   const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   routes.sort(byPath);
   handlers.sort(byPath);
@@ -287,27 +373,112 @@ function findModule(directory, stem, extensions) {
   return null;
 }
 
+/**
+ * What one directory name means to the route path.
+ *
+ * Mirrors `uf_router::classify_route_segment`, which is the same six answers
+ * in the same order. The order is load-bearing in one place: an interception
+ * marker is a `(…)` *prefix* with a route after it, and a `(group)` is a
+ * segment that ends in `)`, so the interception test has to come first or
+ * every group would be read as one.
+ *
+ * @param {string} segment one directory name
+ * @returns {{kind: "group"}
+ *   | {kind: "param", name: string}
+ *   | {kind: "catchAll", name: string}
+ *   | {kind: "literal", name: string}
+ *   | {kind: "slot", name: string}
+ *   | {kind: "interception", marker: string, route: string}}
+ */
+export function classifyRouteSegment(segment) {
+  if (segment.startsWith("@")) return { kind: "slot", name: segment.slice(1) };
+  const intercepted = interceptionMarker(segment);
+  if (intercepted != null) return { kind: "interception", ...intercepted };
+  if (segment.startsWith("(") && segment.endsWith(")")) return { kind: "group" };
+  if (segment.startsWith("[...") && segment.endsWith("]")) {
+    return { kind: "catchAll", name: segment.slice(4, -1) };
+  }
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    return { kind: "param", name: segment.slice(1, -1) };
+  }
+  return { kind: "literal", name: segment };
+}
+
+/**
+ * The `(.)`-style prefix of `segment` and the route after it, or `null`.
+ *
+ * One or more of `(.)`, `(..)` and `(...)` — every marker Next.js defines;
+ * `(..)(..)` is two of them rather than a fourth — followed by something for
+ * them to intercept. A marker with nothing after it names no route and is the
+ * `(group)` it has always been.
+ */
+function interceptionMarker(segment) {
+  let consumed = 0;
+  while (segment[consumed] === "(") {
+    const close = segment.indexOf(")", consumed);
+    if (close === -1) break;
+    const inner = segment.slice(consumed + 1, close);
+    if (inner.length === 0 || inner.length > 3 || /[^.]/.test(inner)) break;
+    consumed = close + 1;
+  }
+  if (consumed === 0 || consumed === segment.length) return null;
+  return { marker: segment.slice(0, consumed), route: segment.slice(consumed) };
+}
+
+/**
+ * Why uf refuses a directory named `segment`, or `null` when it serves it.
+ *
+ * The message is this router's own rather than `uf_router`'s, because the two
+ * are reached differently: the Rust one fails `uf build` and `uf dev` through
+ * the route manifest, and this one fails a project driving Vite itself. Both
+ * say the same two things — which feature the spelling belongs to, and that it
+ * is refused rather than served as a URL.
+ */
+export function unsupportedSegmentReason(segment) {
+  const classified = classifyRouteSegment(segment);
+  if (classified.kind === "slot") {
+    return (
+      `\`${segment}\` is a parallel-route slot, and uf does not have parallel routes — a route ` +
+      "here renders in one place, so there is nothing for a slot to render into. It is refused " +
+      `rather than served as the URL segment \`/${segment}\`, which is what it used to become. ` +
+      "Rename the directory; a URL segment that really starts with `@` has no spelling in this " +
+      "grammar, so capture it with a `[param]`. https://github.com/ubugeeei-prod/uf/issues/267"
+    );
+  }
+  if (classified.kind === "interception") {
+    return (
+      `\`${segment}\` is an intercepting route, and uf does not have interception — a navigation ` +
+      "carries where it is going and not where it came from, so nothing here could match " +
+      `\`${classified.route}\`. It is refused rather than served as the URL segment ` +
+      `\`/${segment}\`, which is what it used to become. Move the route to the path it belongs ` +
+      "at, or rename the directory. https://github.com/ubugeeei-prod/uf/issues/267"
+    );
+  }
+  return null;
+}
+
 /**
  * Turn directory segments into a route path and its parameters.
  *
  * `(group)` segments organise files without appearing in the URL, `[name]`
- * captures one segment, and `[...name]` captures the rest of the path.
+ * captures one segment, and `[...name]` captures the rest of the path. A slot
+ * or an interception never reaches here: {@link scanRoutes} refuses the
+ * directory before it walks into it.
  */
 export function routeFromSegments(segments) {
   const params = [];
   const out = [];
   for (const segment of segments) {
-    if (segment.startsWith("(") && segment.endsWith(")")) continue;
-    if (segment.startsWith("[...") && segment.endsWith("]")) {
-      const name = segment.slice(4, -1);
-      params.push({ name, catchAll: true });
-      out.push(`:${name}*`);
+    const classified = classifyRouteSegment(segment);
+    if (classified.kind === "group") continue;
+    if (classified.kind === "catchAll") {
+      params.push({ name: classified.name, catchAll: true });
+      out.push(`:${classified.name}*`);
       continue;
     }
-    if (segment.startsWith("[") && segment.endsWith("]")) {
-      const name = segment.slice(1, -1);
-      params.push({ name, catchAll: false });
-      out.push(`:${name}`);
+    if (classified.kind === "param") {
+      params.push({ name: classified.name, catchAll: false });
+      out.push(`:${classified.name}`);
       continue;
     }
     out.push(segment);
@@ -316,11 +487,21 @@ export function routeFromSegments(segments) {
   return { path: routePath, pattern: routePath.replace(/:(\w+)\*/g, "*$1"), params };
 }
 
-/** Virtual module ids the router plugin serves. */
+/**
+ * Virtual module ids the router plugin serves.
+ *
+ * `actions` is the one that does not come from this file's directory scan: it
+ * is generated from the RSC manifest by `internal/rsc.js`, because which
+ * `"use server"` exports are callable endpoints is an answer about the module
+ * graph and not about the filesystem. It is here because it is a virtual
+ * module id and this is where they are named, and because
+ * `serverModuleSource` below is the only thing that imports it.
+ */
 export const VIRTUAL = Object.freeze({
   routes: "virtual:uf/routes",
   client: "virtual:uf/client",
   server: "virtual:uf/server",
+  actions: "virtual:uf/actions",
 });
 
 /**
@@ -412,6 +593,23 @@ export function routesModuleSource(table, options = {}) {
     return id;
   };
 
+  // Templates are deduplicated for the reason layouts are — one
+  // `app/_uf.template.js` wraps every route under it — and are lazy for the
+  // reason layouts are too: a template is part of the route's own tree rather
+  // than a fallback React has to have in hand at the moment something goes
+  // wrong, so it is awaited with the layouts before the first render.
+  const templateIds = new Map();
+  const templateImports = [];
+  const templateId = (file) => {
+    let id = templateIds.get(file);
+    if (id === undefined) {
+      id = `template${templateIds.size}`;
+      templateIds.set(file, id);
+      templateImports.push(`const ${id} = () => import(${JSON.stringify(file)});`);
+    }
+    return id;
+  };
+
   const entries = table.routes.map((route) => {
     if (!shipsPage(route)) {
       return `  {
@@ -421,12 +619,16 @@ export function routesModuleSource(table, options = {}) {
     file: ${JSON.stringify(route.page)},
     layouts: [],
     loading: [],
+    templates: [],
   }`;
     }
     const layouts = route.layouts.map(layoutId);
     const loading = (route.loading ?? []).map(
       (boundary) => `{ above: ${boundary.above}, module: ${loadingId(boundary.module)} }`,
     );
+    const templates = (route.templates ?? []).map(
+      (entry) => `{ above: ${entry.above}, module: ${templateId(entry.module)} }`,
+    );
     return `  {
     path: ${JSON.stringify(route.path)},
     params: ${JSON.stringify(route.params)},
@@ -435,9 +637,19 @@ export function routesModuleSource(table, options = {}) {
     page: () => import(${JSON.stringify(route.page)}),
     layouts: [${layouts.join(", ")}],
     loading: [${loading.join(", ")}],
+    templates: [${templates.join(", ")}],
   }`;
   });
 
+  // A boundary the scan synthesised has no module to import — the framework's
+  // own page renders in its place — so it emits `null` where a declared one
+  // emits a loader, and a name for `file` rather than a path nothing wrote.
+  // See the note in `scanRoutes` and ubugeeei-prod/uf#351.
+  const SYNTHESISED = JSON.stringify("@uniflowed/router");
+  const boundaryModule = (file) =>
+    file == null ? "null" : `() => import(${JSON.stringify(file)})`;
+  const boundaryFile = (file) => (file == null ? SYNTHESISED : JSON.stringify(file));
+
   // A list, because a not-found is a segment file: every directory may declare
   // one and the router takes the nearest above the path. `layoutId` is the
   // same table the routes use, so a boundary that shares a layout with a page
@@ -446,8 +658,8 @@ export function routesModuleSource(table, options = {}) {
     (boundary) => `  {
     path: ${JSON.stringify(boundary.path)},
     mdx: ${boundary.mdx},
-    file: ${JSON.stringify(boundary.page)},
-    page: () => import(${JSON.stringify(boundary.page)}),
+    file: ${boundaryFile(boundary.page)},
+    page: ${boundaryModule(boundary.page)},
     layouts: [${boundary.layouts.map(layoutId).join(", ")}],
   }`,
   );
@@ -459,8 +671,8 @@ export function routesModuleSource(table, options = {}) {
   const errorEntries = (table.errors ?? []).map(
     (boundary) => `  {
     path: ${JSON.stringify(boundary.path)},
-    file: ${JSON.stringify(boundary.module)},
-    module: () => import(${JSON.stringify(boundary.module)}),
+    file: ${boundaryFile(boundary.module)},
+    module: ${boundaryModule(boundary.module)},
     layouts: [${boundary.layouts.map(layoutId).join(", ")}],
   }`,
   );
@@ -493,13 +705,18 @@ export function routesModuleSource(table, options = {}) {
   // Last, because it is defined by what everything above did *not* import: a
   // layout a kept route also uses is already in the graph as a lazy chunk, and
   // importing it here as well would pull it into the entry chunk instead.
-  const carried = new Set([...layoutIds.keys(), ...loadingIds.keys()]);
+  const carried = new Set([...layoutIds.keys(), ...loadingIds.keys(), ...templateIds.keys()]);
   const styleOnlyImports = [];
   for (const route of table.routes) {
     if (shipsPage(route)) {
       continue;
     }
-    const files = [route.page, ...route.layouts, ...(route.loading ?? []).map((it) => it.module)];
+    const files = [
+      route.page,
+      ...route.layouts,
+      ...(route.loading ?? []).map((it) => it.module),
+      ...(route.templates ?? []).map((it) => it.module),
+    ];
     for (const file of files) {
       if (carried.has(file)) {
         continue;
@@ -509,7 +726,7 @@ export function routesModuleSource(table, options = {}) {
     }
   }
 
-  return `${[...styleOnlyImports, ...layoutImports, ...loadingImports].join("\n")}
+  return `${[...styleOnlyImports, ...layoutImports, ...loadingImports, ...templateImports].join("\n")}
 export const routes = [
 ${entries.join(",\n")}
 ];
@@ -558,6 +775,16 @@ hydrate({ App, routes, notFound, errors });
  * request — one decides whether the router is reached at all, the others
  * decide what the router renders when it is.
  *
+ * `callAction` goes between the two, and its position is the same argument
+ * made twice. Below `runMiddleware`, because an action call is a request to a
+ * path and the guard on that path is owed the same say over it as over the
+ * page — which is why the call is a `POST` to the page's own URL rather than
+ * to a reserved one. Above `dispatch`, because a request that names an action
+ * has named it: letting it fall through to a route handler that happens to sit
+ * at the same path would answer somebody's action with somebody else's
+ * function. It declines every request that carries no action id, so a project
+ * with no actions pays one `headers.get` per request and nothing else.
+ *
  * `internal/serve.js` and `driver.js` call them in that order, and
  * `packages/vite/index.js` does the same for a project driving Vite itself.
  *
@@ -583,11 +810,13 @@ hydrate({ App, routes, notFound, errors });
  */
 export function serverModuleSource(appEntry) {
   return `import {
+  createActionDispatcher,
   createDispatcher,
   createMiddlewareRunner,
   createRenderer,
 } from "@uniflowed/router/server";
 import { routes, handlers, middleware, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
+import { actions } from ${JSON.stringify(VIRTUAL.actions)};
 import App from ${JSON.stringify(appEntry)};
 export { routes, handlers, middleware, notFound, errors };
 export { beginRequest } from "@uniflowed/router/server";
@@ -595,6 +824,7 @@ const renderer = createRenderer({ App, routes, notFound, errors });
 export const render = renderer.render;
 export const prerender = renderer.prerender;
 export const dispatch = createDispatcher({ handlers });
+export const callAction = createActionDispatcher({ actions });
 export const runMiddleware = createMiddlewareRunner({ middleware });
 `;
 }

package/internal/rsc.js

@@ -35,7 +35,7 @@
 // route uf has positively decided needs no browser — and a manifest that is
 // missing, unreadable, or written by an older uf removes nothing at all.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
 
 /** Environment variable naming the manifest, set by `uf build` and `uf dev`. */
@@ -140,12 +140,267 @@ export function clientRouteFilter(manifest, root, boundaries = {}) {
     if (needed(route.page)) return true;
     if (route.layouts.some(needed)) return true;
     if ((route.loading ?? []).some((entry) => needed(entry.module))) return true;
+    if ((route.templates ?? []).some((entry) => needed(entry.module))) return true;
+    // A boundary with no module of its own is the record the scan synthesises
+    // at the router root, and what renders there is the framework's own page —
+    // already in `@uniflowed/router`, reaching nothing this project wrote. It
+    // is skipped rather than left to `needed`, whose answer for a value that is
+    // not a file is "assume it is needed": that answer is right for a path the
+    // manifest has never heard of and wrong for the absence of a path, and
+    // taking it here would have kept every page of every project in the client
+    // bundle. See ubugeeei-prod/uf#351.
     for (const boundary of notFound) {
+      if (boundary.page == null) continue;
       if (covers(boundary.path, route.path) && needed(boundary.page)) return true;
     }
     for (const boundary of errors) {
+      if (boundary.module == null) continue;
       if (covers(boundary.path, route.path) && needed(boundary.module)) return true;
     }
     return false;
   };
 }
+
+// ---------------------------------------------------------------------------
+// Server actions
+//
+// The other half of the split, and the one the manifest was already carrying
+// an answer for. `serverActions` in the manifest is every action `uf_rsc`
+// decided is a *callable endpoint* — an action some module that can hand it
+// across a client boundary reaches — with the keyed id
+// `crates/uf_rsc/src/action.rs` derived for it. An action nothing exposes is
+// tracked in the registry and never written here, so a table built out of this
+// file cannot contain a row that was not meant to be dialable.
+//
+// Two tables come out of it, for the two graphs:
+//
+// * `serverActionModules` is the browser's. It says, for each `"use server"`
+//   file, which exports become `createServerReference` calls — and the plugin
+//   answers that source *instead of the file*, so the module's body never
+//   enters the client graph and neither does anything only it imported.
+// * `serverActionTable` is the server's. It is what `virtual:uf/actions`
+//   emits and what `createActionDispatcher` dials into.
+//
+// Both are keyed on the id and nothing else. No request-derived value ever
+// becomes a path, a specifier or an export name here or downstream; see the
+// header of `packages/router/internal/action-endpoint.js`.
+// ---------------------------------------------------------------------------
+
+/**
+ * The request header carrying an action id, lowercased as Node delivers it.
+ *
+ * A second spelling of `ACTION_HEADER` in
+ * `packages/router/internal/action-wire.js`, and it has to be one: this module
+ * is plain JavaScript the Vite host imports before any transform, and that one
+ * is Flow, which Node cannot import at all. `RSC_MANIFEST_ENV` above is the
+ * same situation with `crates/uf_rsc/src/manifest.rs`. What keeps a second
+ * spelling from becoming a second answer is
+ * `tests/library/server-actions.test.js`, which reads both and compares them.
+ */
+export const ACTION_HEADER = "uf-action";
+
+/** The id an action row must carry: 64 lowercase hexadecimal characters. */
+function isActionId(value) {
+  if (typeof value !== "string" || value.length !== 64) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    const digit = code >= 0x30 && code <= 0x39;
+    const lower = code >= 0x61 && code <= 0x66;
+    if (!digit && !lower) return false;
+  }
+  return true;
+}
+
+/**
+ * Whether a name can be written as `export const <name>`.
+ *
+ * The scanner only ever produces identifiers, so this refuses nothing a real
+ * project has. It is here because the alternative to refusing is emitting a
+ * module that does not parse, and a generated file that does not parse fails a
+ * build somewhere far from the module that caused it. `default` is handled by
+ * the caller, which writes `export default`.
+ */
+function isExportableName(name) {
+  if (typeof name !== "string" || name.length === 0) return false;
+  const first = name.charCodeAt(0);
+  const startish = (code) =>
+    (code >= 0x41 && code <= 0x5a) ||
+    (code >= 0x61 && code <= 0x7a) ||
+    code === 0x24 ||
+    code === 0x5f;
+  if (!startish(first)) return false;
+  for (let index = 1; index < name.length; index += 1) {
+    const code = name.charCodeAt(index);
+    if (!startish(code) && !(code >= 0x30 && code <= 0x39)) return false;
+  }
+  return true;
+}
+
+/** Every callable action of the manifest, in the manifest's own order. */
+function callableActions(manifest) {
+  if (manifest == null || !Array.isArray(manifest.serverActions)) return [];
+  return manifest.serverActions.filter(
+    (action) =>
+      action != null &&
+      isActionId(action.id) &&
+      typeof action.module === "string" &&
+      action.module !== "" &&
+      // An inline `"use server"` closure has no export name to import, so it
+      // has no reference in the client bundle and no row in the server's
+      // table. It is in the manifest, and reaching it needs the payload
+      // ubugeeei-prod/uf#252 is about.
+      action.kind === "module-export" &&
+      isExportableName(action.export === "default" ? "default_" : action.export),
+  );
+}
+
+/**
+ * The absolute path of a module the manifest names, or `null`.
+ *
+ * The manifest's paths are project-relative with forward slashes and were
+ * written by a walk that already refused anything outside the root; joined
+ * here and checked again, because a path that escapes the project is a path
+ * this plugin would otherwise hand to Rollup as a module to emit.
+ */
+function moduleFile(root, relative) {
+  const joined = path.resolve(root, relative);
+  const inside = path.relative(root, joined);
+  if (inside === "" || inside.startsWith("..") || path.isAbsolute(inside)) return null;
+  return joined;
+}
+
+/**
+ * Which exports of each `"use server"` file become references in the browser.
+ *
+ * Keyed by absolute path, because that is what Vite's `load` hook is given.
+ * A file with no callable action is absent rather than present-and-empty: the
+ * plugin substitutes a module only for a key it finds, and substituting an
+ * empty module for a file something imports would be a build error in place of
+ * a working import.
+ *
+ * @param {object | null} manifest from {@link readRscManifest}
+ * @param {string} root absolute project root
+ * @returns {Map<string, Array<{id: string, module: string, export: string}>>}
+ */
+export function serverActionModules(manifest, root) {
+  const modules = new Map();
+  for (const action of callableActions(manifest)) {
+    const file = moduleFile(root, action.module);
+    if (file == null) continue;
+    const rows = modules.get(file);
+    const row = { id: action.id, module: action.module, export: action.export };
+    if (rows === undefined) modules.set(file, [row]);
+    else rows.push(row);
+  }
+  return modules;
+}
+
+/**
+ * Every callable action, as the server's dispatcher table.
+ *
+ * @param {object | null} manifest from {@link readRscManifest}
+ * @param {string} root absolute project root
+ * @returns {Array<{id: string, module: string, export: string, file: string}>}
+ */
+export function serverActionTable(manifest, root) {
+  const rows = [];
+  for (const action of callableActions(manifest)) {
+    const file = moduleFile(root, action.module);
+    if (file == null) continue;
+    rows.push({ id: action.id, module: action.module, export: action.export, file });
+  }
+  return rows;
+}
+
+/**
+ * The client bundle's stand-in for one `"use server"` module.
+ *
+ * What the browser gets in place of the file: one `createServerReference` per
+ * callable export, an id each, and nothing the module itself imported. This is
+ * the whole of how a database handle reached only through an action stays on
+ * the server — `crates/uf_rsc/src/graph/build.rs` colours the module server for
+ * the same reason, so that the analysis and the bundle agree about it.
+ *
+ * @param {Array<{id: string, module: string, export: string}>} actions
+ */
+export function actionReferenceSource(actions) {
+  const lines = ['import { createServerReference } from "@uniflowed/router/action";', ""];
+  for (const action of actions) {
+    const reference = `createServerReference(${JSON.stringify(action.id)}, ${JSON.stringify(
+      `${action.module}#${action.export}`,
+    )})`;
+    lines.push(
+      action.export === "default"
+        ? `export default ${reference};`
+        : `export const ${action.export} = ${reference};`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The source of `virtual:uf/actions`: the table the endpoint dials into.
+ *
+ * One `import()` thunk per file rather than one per action, so a module with
+ * four actions is one chunk of the server bundle and not four. Lazy for the
+ * reason the handler table is: an action module is loaded when an action in it
+ * is called, and a project's actions are not something every request should
+ * pay to import.
+ *
+ * With no manifest the table is empty and every action call is a `404` — the
+ * same answer a project driving Vite itself gets for the route split, and for
+ * the same reason: uf will not guess at an analysis it was not given.
+ *
+ * @param {Array<{id: string, module: string, export: string, file: string}>} actions
+ */
+export function actionsModuleSource(actions) {
+  const loaders = new Map();
+  const declarations = [];
+  const loaderId = (file) => {
+    let id = loaders.get(file);
+    if (id === undefined) {
+      id = `load${loaders.size}`;
+      loaders.set(file, id);
+      declarations.push(`const ${id} = () => import(${JSON.stringify(file)});`);
+    }
+    return id;
+  };
+
+  const entries = actions.map(
+    (action) => `  {
+    id: ${JSON.stringify(action.id)},
+    module: ${JSON.stringify(action.module)},
+    export: ${JSON.stringify(action.export)},
+    load: ${loaderId(action.file)},
+  }`,
+  );
+
+  return `${declarations.join("\n")}
+export const actions = [
+${entries.join(",\n")}
+];
+export default actions;
+`;
+}
+
+/**
+ * A cheap identity for the manifest file, so a reader can tell it has changed.
+ *
+ * The plugin's `load` hook runs for every module in the graph and cannot parse
+ * the manifest each time. Size and modification time together are what
+ * `.uf/cache/transform` already keys on for the binary that wrote it, and the
+ * same reasoning applies: a file that differs in neither is the file that was
+ * read. `uf dev` also clears the cache outright when its watcher sees the
+ * manifest change, so this is the build's answer rather than the only one.
+ *
+ * @param {string | undefined} file
+ */
+export function rscManifestKey(file) {
+  if (file == null || file === "") return "";
+  try {
+    const stats = statSync(file);
+    return `${String(stats.size)}:${String(stats.mtimeMs)}`;
+  } catch {
+    return "";
+  }
+}

package/internal/serve.js

@@ -240,12 +240,26 @@ export function assetsFromManifest(manifest) {
  * naming rather than papering over, and it is the failure path of a request
  * that already went wrong — not the ordinary one this exists for.
  *
- * @param {{beginRequest: (request: Request) => {run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
  * @param {Request} request
  * @param {() => Promise<mixed>} body
  */
 export async function withRequest(entry, request, body) {
-  const { run, settle } = entry.beginRequest(request);
+  const lifecycle = entry.beginRequest(request);
+  const { run, settle } = lifecycle;
+  // What this host can do, put on the request the way `createFetchHandler`
+  // puts it on the one it owns. `uf dev` and `uf build --compile` reach a
+  // route handler without going through that function, and a handler that
+  // streams events or queues work has to get the same answer from all four
+  // front doors — a capability that is present under `uf start` and absent
+  // under `uf dev` is the difference this whole seam exists to remove.
+  //
+  // `nodeCapabilities`, because both of those *are* a Node process with a
+  // socket: a body reaches the client as it is written, and the process is
+  // still there afterwards. Neither passes an upgrader or a queue, because uf
+  // defines both and implements neither.
+  const { nodeCapabilities } = await deployment();
+  lifecycle.context.capabilities ??= nodeCapabilities();
   try {
     return await run(body);
   } finally {
@@ -274,11 +288,16 @@ export async function withRequest(entry, request, body) {
  * @param {{entry: object, assets: object, cache?: object}} build
  */
 export function createApplicationHandler({ entry, assets, cache }) {
-  const ready = deployment().then(({ createFetchHandler, createCacheStore }) =>
+  const ready = deployment().then(({ createFetchHandler, createCacheStore, nodeCapabilities }) =>
     createFetchHandler({
       app: entry,
       document: assets,
       cache: cacheFor(cache, createCacheStore),
+      // `uf preview` and `uf start` are a Node process with a socket, which is
+      // what a deployed `--adapter node` build is too — so a route handler
+      // that streams events answers the same way in the preview it is checked
+      // in and in the deployment it ends up as. See `withRequest` above.
+      capabilities: nodeCapabilities(),
     }),
   );
   return async function handle(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.11",
+  "version": "0.0.0-alpha.13",
   "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",
@@ -25,8 +25,8 @@
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.11",
-    "@uniflowed/server": "0.0.0-alpha.11",
+    "@uniflowed/host": "0.0.0-alpha.13",
+    "@uniflowed/server": "0.0.0-alpha.13",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",