@uniflowed/vite 0.0.0-alpha.20 → 0.0.0-alpha.21

package/driver.js

@@ -7,7 +7,7 @@
 //
 //   <host> driver.js dev     --root <dir> [--mode <m>] [--host <h>] [--port <n>] [--strict-port]
 //                            [--uf-env-file <file>]...
-//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>]
+//   <host> driver.js build   --root <dir> [--mode <m>] [--out-dir <dir>] [--target <target>]
 //                            [--prerender everything|possible|nothing]
 //                            [--static-build] [--because <sentence>]
 //   <host> driver.js library --root <dir> [--mode <m>] [--out-dir <dir>]
@@ -50,8 +50,9 @@ import { COMPILE_ASSETS_ID, compileAssetsPlugin } from "./internal/compile-asset
 import { emit, errorEvent, eventLogger } from "./internal/events.js";
 import { loadUfConfig, projectConfig } from "./internal/config.js";
 import { send, toRequest } from "./internal/http.js";
+import { createOpenApiDocument } from "./internal/openapi.js";
 import { withProjectConfig } from "./merge.js";
-import { VIRTUAL, scanRoutes } from "./internal/routes.js";
+import { VIRTUAL, resolveRouteTarget, scanRoutes } from "./internal/routes.js";
 import {
   BUILD_ID_FILE,
   assetsFromManifest,
@@ -161,6 +162,7 @@ async function viteConfig(config, mode) {
   const port = Number(argument("--port") ?? dev.port ?? 5173);
   const allowedHosts =
     Array.isArray(dev.allowedHosts) && dev.allowedHosts.length > 0 ? dev.allowedHosts : undefined;
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
 
   // What uf generates from the semantics it owns: where the project is, which
   // plugins make Flow compile, and the few settings uf enforces rather than
@@ -191,7 +193,7 @@ async function viteConfig(config, mode) {
     mode,
     clearScreen: false,
     customLogger: eventLogger(argument("--log-level") ?? "info"),
-    plugins: [uniflowed({ root, config })],
+    plugins: [uniflowed({ root, config, target: routeTarget })],
     server: {
       host,
       port,
@@ -255,6 +257,7 @@ async function viteConfig(config, mode) {
 async function dev() {
   const { createServer } = await import("vite");
   const config = await loadConfig();
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
   // The mode is uf's to decide, not this file's: `uf dev` resolves `--mode`,
   // the profile `uf env use` wrote and `env.active` before it starts anything,
   // and always passes the answer. The fallback is for a driver started by hand.
@@ -266,9 +269,9 @@ async function dev() {
   emit("listening", {
     local: urls.local,
     network: urls.network,
-    routes: scanRoutes(path.resolve(root, config.app?.router?.root ?? "app")).routes.map(
-      (route) => route.path,
-    ),
+    routes: scanRoutes(path.resolve(root, config.app?.router?.root ?? "app"), {
+      target: routeTarget,
+    }).routes.map((route) => route.path),
   });
   watchSources(server);
   watchEnvFiles(server);
@@ -390,6 +393,7 @@ function watchEnvFiles(server) {
 async function preview() {
   const { preview: startPreview } = await import("vite");
   const config = await loadConfig();
+  const routeTarget = resolveRouteTarget(config, argument("--target"));
   const inline = await viteConfig(config, argument("--mode") ?? "production");
   // A build that declared it emits no server has none to mount. `uf` refuses
   // `uf start` for such a project and lets this one through, because a preview
@@ -489,9 +493,9 @@ async function preview() {
     // be the report being wrong about the thing it exists to report.
     routes:
       build == null
-        ? scanRoutes(path.resolve(root, config.app?.router?.root ?? "app")).routes.map(
-            (route) => route.path,
-          )
+        ? scanRoutes(path.resolve(root, config.app?.router?.root ?? "app"), {
+            target: routeTarget,
+          }).routes.map((route) => route.path)
         : build.entry.routes.map((route) => route.path),
     handlers: build == null ? [] : build.entry.handlers.map((handler) => handler.path),
   });
@@ -632,6 +636,10 @@ async function build() {
   emit("phase", { name: "prerender" });
   const server = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
   const assets = assetsFromManifest(manifest);
+  const openapi = await createOpenApiDocument(server.handlers);
+  const openapiFile = path.join(root, ".uf", "build", "meta", "openapi.json");
+  mkdirSync(path.dirname(openapiFile), { recursive: true });
+  writeFileSync(openapiFile, `${JSON.stringify(openapi, null, 2)}\n`);
   const plan = await renderingPlan(server, prerender);
   emit("rendering", {
     prerender,
@@ -1070,9 +1078,9 @@ async function compile() {
  * of what an adapter is, and keeping the differences in one object is what
  * stops a second one from quietly becoming a second application.
  *
- * `bun`, `deno` and `static` are deliberately absent; `uf_config`'s
+ * `static` is deliberately absent; `uf_config`'s
  * `DeployAdapter::is_implemented` is the other half of that fact and
- * `docs/app/reference/cli/$page.mdx` says why for each of them.
+ * `docs/app/reference/cli/$page.mdx` says why.
  */
 const ADAPTERS = {
   node: {
@@ -1101,6 +1109,12 @@ const ADAPTERS = {
       server: bunEntrySource("./handler.js", schedules),
     }),
   },
+  deno: {
+    entries: (document, cache, build, schedules) => ({
+      handler: handlerEntrySource(document, cache, DENO_CAPABILITIES, build),
+      server: denoEntrySource("./handler.js", schedules),
+    }),
+  },
   // The same two files. What `--adapter container` adds is a `Dockerfile` and
   // a `.dockerignore`, and both are plain text that `uf` writes beside this
   // output rather than anything the bundler produces — see `uf_cli`'s
@@ -1155,6 +1169,7 @@ const ADAPTERS = {
  */
 const NODE_CAPABILITIES = { module: "@uniflowed/server/node", name: "nodeCapabilities" };
 const BUN_CAPABILITIES = { module: "@uniflowed/server/bun", name: "bunCapabilities" };
+const DENO_CAPABILITIES = { module: "@uniflowed/server/deno", name: "denoCapabilities" };
 const EDGE_CAPABILITIES = { module: "@uniflowed/server/edge", name: "edgeCapabilities" };
 const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lambdaCapabilities" };
 
@@ -1206,7 +1221,7 @@ const SERVERLESS_CAPABILITIES = { module: "@uniflowed/server/lambda", name: "lam
  * It is the one implemented target with no application to link: a static host
  * returns files, and `uf build` has already written them. So `uf` copies the
  * output directory itself and never spawns this driver for it, which is why
- * [`ADAPTERS`] has four rows and not five. What that target does instead of
+ * [`ADAPTERS`] has six rows and not seven. What that target does instead of
  * linking is refuse a project whose route handlers, middleware, unprerendered
  * routes or server actions a static host cannot answer — in Rust, because the
  * facts it needs are the route table and what the prerender reported.
@@ -1415,7 +1430,7 @@ const cache = { store: createCacheStore(${
 
 `
     : ""
-}// What this target can do, and it is not the same for all four: whether a
+}// What this target can do, and it is not the same for all six: 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
@@ -1590,6 +1605,52 @@ serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) =>
 `;
 }
 
+/**
+ * The source of `server.js`: the Deno socket around that handler.
+ *
+ * The same generated contract as Node and Bun, with `@uniflowed/server/deno`
+ * owning the host-specific pieces. The static directory is resolved with
+ * `import.meta.url` alone so the entry carries no `node:` imports.
+ */
+function denoEntrySource(handlerSpecifier, schedules) {
+  const cron = scheduleLines("@uniflowed/server/schedule", schedules);
+  return `// Generated by \`uf build --adapter deno\`. Not checked in, not edited.
+import { serve } from "@uniflowed/server/deno";
+${cron.imports}
+// \`beginRequest\` comes from the handler beside this file rather than from
+// \`@uniflowed/server/deno\` above, because the request has to be established in
+// the storage the *application* reads, which is the copy bundled into
+// \`handler.js\`. See ubugeeei-prod/uf#389.
+//
+// Deno has no Node globals, but dependency bundles may still carry a CommonJS
+// production branch that expects a few of them. Establish the small environment
+// shape before \`handler.js\` is evaluated, which requires a dynamic import here
+// rather than a static one.
+globalThis.process ??= { env: {} };
+globalThis.process.env ??= {};
+globalThis.process.env.NODE_ENV ??= "production";
+globalThis.Buffer ??= {
+  byteLength(value) {
+    return new TextEncoder().encode(String(value)).byteLength;
+  },
+};
+globalThis.setImmediate ??= (callback, ...args) => setTimeout(callback, 0, ...args);
+globalThis.clearImmediate ??= (handle) => clearTimeout(handle);
+const { beginRequest, fetch } = await import(${JSON.stringify(handlerSpecifier)});
+
+// Resolved from this file and not from the working directory: a process
+// manager and a person in a shell each start a server from wherever they
+// happen to be, and a directory that only served its own assets when it was
+// started from inside itself would be a deployment with a trap in it.
+const staticDir = decodeURIComponent(new URL("./static", import.meta.url).pathname);
+${cron.declarations}
+serve({ handle: fetch, staticDir, beginRequest${cron.option} }).catch((error) => {
+  console.error(\`uf: \${error?.message ?? String(error)}\`);
+  Deno.exit(1);
+});
+`;
+}
+
 /**
  * The source of `worker.js`: the Cloudflare Workers entry around that handler.
  *

package/index.js

@@ -80,6 +80,7 @@ import {
   RESERVED,
   VIRTUAL,
   clientModuleSource,
+  resolveRouteTarget,
   routesModuleSource,
   scanRoutes,
   serverModuleSource,
@@ -115,6 +116,7 @@ export function devUrlFor(id) {
  * @typedef {object} UniflowedOptions
  * @property {string} [root] absolute project root; Vite's root by default
  * @property {object} [config] the loaded `uf.config.js` object
+ * @property {"web" | "native" | "ios" | "android"} [target] app target
  * @property {string} [command] the `uf` binary to transform through
  */
 
@@ -126,6 +128,7 @@ export function devUrlFor(id) {
 export default function uniflowed(options = {}) {
   const ufConfig = options.config ?? {};
   const app = ufConfig.app ?? {};
+  const routeTarget = resolveRouteTarget(ufConfig, options.target);
   const routerRoot = app.router?.root ?? "app";
   const appEntry = app.router?.entry ?? ufConfig.build?.entries?.[0] ?? "app.js";
   const markdown = app.builtins?.markdown ?? {};
@@ -156,6 +159,7 @@ export default function uniflowed(options = {}) {
     flowPlugin({
       routerRoot,
       appEntry,
+      routeTarget,
       strictMode,
       navigation,
       mount,
@@ -176,6 +180,7 @@ export default function uniflowed(options = {}) {
 function flowPlugin({
   routerRoot,
   appEntry,
+  routeTarget,
   strictMode,
   navigation,
   mount,
@@ -260,10 +265,15 @@ function flowPlugin({
     // survives the build — so the browser's table was shipping the absolute
     // path of every page on the machine that built the site, to every visitor.
     // The server's table is read where those files are and keeps them.
-    return routesModuleSource(table, {
-      shipsPage: (route) => kept.has(route),
-      relativeTo: root,
-    });
+    // HTTP handlers are exclusively server capabilities. Even an unused
+    // dynamic import makes Vite traverse the handler's database/auth imports.
+    return routesModuleSource(
+      { ...table, handlers: [] },
+      {
+        shipsPage: (route) => kept.has(route),
+        relativeTo: root,
+      },
+    );
   };
 
   /**
@@ -373,7 +383,7 @@ function flowPlugin({
       if (id === RUNTIME_RESOLVED_ID) return refreshRuntimeSource();
       if (id === AUDIT_RESOLVED_ID) return auditRuntimeSource(accessibility?.axe);
       if (id === resolved(VIRTUAL.routes)) {
-        const table = scanRoutes(appRoot);
+        const table = scanRoutes(appRoot, { target: routeTarget });
         // The server renders every route, so the server's table is the whole
         // one and is generated with no filter at all. Only the browser's copy
         // is split.

package/internal/config.js

@@ -72,7 +72,7 @@ export async function loadUfConfig(root) {
   }
 
   const compiled = await compileConfig(source, file, root);
-  const module = await import(pathToFileURL(compiled).href);
+  const module = await importConfigModule(compiled);
   const config = module.default;
   if (config == null || typeof config !== "object") {
     throw new Error(
@@ -82,6 +82,20 @@ export async function loadUfConfig(root) {
   return { config, file };
 }
 
+async function importConfigModule(compiled) {
+  const previous = process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG;
+  process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG = "1";
+  try {
+    return await import(pathToFileURL(compiled).href);
+  } finally {
+    if (previous == null) {
+      delete process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG;
+    } else {
+      process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG = previous;
+    }
+  }
+}
+
 /**
  * Transform the config to JavaScript and write it where it can be imported.
  *
@@ -93,8 +107,14 @@ async function compileConfig(source, file, root) {
   const directory = path.join(root, COMPILED_DIR);
   const target = path.join(directory, `uf.config.${hash}.mjs`);
 
-  const out = await transformFlow(source, file, { root, sourceMap: false });
-  const code = rewriteRelativeImports(out?.code ?? source, path.dirname(file));
+  const out = await transformFlow(source, file, {
+    root,
+    sourceMap: false,
+    configBootstrap: true,
+  });
+  const code = rewriteConfigImports(
+    rewriteRelativeImports(out?.code ?? source, path.dirname(file)),
+  );
   // Atomically, because two `uf` commands in one project write this same path
   // at the same time — the hash is of the source, so they agree on the name —
   // and `writeFileSync` truncates before it writes. A reader that caught it
@@ -125,6 +145,13 @@ export function rewriteRelativeImports(code, baseDirectory) {
   );
 }
 
+function rewriteConfigImports(code) {
+  return code.replace(
+    /^\s*import\s*\{\s*defineConfig\s*\}\s*from\s*["']@uniflowed\/config["'];?\n?/gm,
+    "function defineConfig(config) {\n  return config;\n}\n",
+  );
+}
+
 /**
  * The JSON projection of a config object.
  *

package/internal/openapi.js

@@ -0,0 +1,218 @@
+// @noflow
+//
+// Route-handler OpenAPI output.
+//
+// The build driver imports this module before it registers the Node Flow
+// hooks, so it must stay plain JavaScript and must not statically import
+// Flow-authored packages. The schema and method vocabulary are loaded inside
+// `createOpenApiDocument`, after the driver has installed the hooks.
+
+const JSON = "application/json";
+const QUERY_EXTENSION = "x-uf-query";
+const STANDARD_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+
+export async function createOpenApiDocument(handlers, options = {}) {
+  const [{ HANDLER_METHODS }, { toJsonSchema }] = await Promise.all([
+    import("@uniflowed/router/handler"),
+    import("@uniflowed/validator/json-schema"),
+  ]);
+  const paths = {};
+  for (const record of handlers ?? []) {
+    const routePath = openApiPath(record.path);
+    const pathItem = paths[routePath] ?? {};
+    paths[routePath] = pathItem;
+    const module = await loadHandlerModule(record, pathItem);
+    if (module == null) continue;
+    for (const method of implementedMethods(module, HANDLER_METHODS)) {
+      const operation = createOperation(record, method, schemaFor(module, method), toJsonSchema);
+      if (STANDARD_METHODS.has(method)) {
+        pathItem[method.toLowerCase()] = operation;
+      } else if (method === "QUERY") {
+        pathItem[QUERY_EXTENSION] = operation;
+      }
+    }
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: options.title ?? "uf application",
+      version: options.version ?? "0.0.0",
+    },
+    paths,
+  };
+}
+
+async function loadHandlerModule(record, pathItem) {
+  try {
+    return await record.load();
+  } catch (error) {
+    if (record.file != null) pathItem["x-uf-source"] = record.file;
+    pathItem["x-uf-schema-unavailable"] = errorMessage(error);
+    return null;
+  }
+}
+
+function implementedMethods(module, methods) {
+  return methods.filter(
+    (method) =>
+      typeof module[method] === "function" ||
+      (method === "HEAD" && typeof module.GET === "function"),
+  );
+}
+
+function schemaFor(module, method) {
+  const table = module.schemas;
+  if (!isRecord(table)) return null;
+  const schema = table[method];
+  if (schema == null) return null;
+  if (!isRecord(schema)) {
+    throw new Error(`route handler schemas.${method} must be an object`);
+  }
+  return schema;
+}
+
+function createOperation(record, method, schema, toJsonSchema) {
+  const parameters = pathParameters(record);
+  const operation = {
+    operationId: operationId(record, method),
+    responses: untypedResponses(method),
+  };
+  if (record.file != null) operation["x-uf-source"] = record.file;
+  if (parameters.length > 0) operation.parameters = parameters;
+  if (schema == null) {
+    operation["x-uf-untyped"] = true;
+    return operation;
+  }
+
+  const unrepresentable = [];
+  if (schema.query != null) {
+    addQuerySchema(operation, exportSchema(toJsonSchema, schema.query, "query", unrepresentable));
+  }
+  if (schema.body != null) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        [JSON]: { schema: exportSchema(toJsonSchema, schema.body, "body", unrepresentable) },
+      },
+    };
+  }
+  if (schema.response != null) {
+    operation.responses = {
+      "200": {
+        description: method === "HEAD" ? "Typed response headers" : "Typed response",
+        content:
+          method === "HEAD"
+            ? undefined
+            : {
+                [JSON]: {
+                  schema: exportSchema(toJsonSchema, schema.response, "response", unrepresentable),
+                },
+              },
+      },
+    };
+    if (method === "HEAD") delete operation.responses["200"].content;
+  }
+  if (unrepresentable.length > 0) {
+    operation["x-uf-unrepresentable"] = unrepresentable;
+  }
+  return operation;
+}
+
+function untypedResponses(method) {
+  return {
+    "200": {
+      description: method === "HEAD" ? "Untyped response headers" : "Untyped response",
+    },
+  };
+}
+
+function exportSchema(toJsonSchema, schema, part, unrepresentable) {
+  const exported = toJsonSchema(schema);
+  for (const item of exported.unrepresentable) {
+    unrepresentable.push({ part, path: item.path, kind: item.kind });
+  }
+  return stripDialect(exported.schema);
+}
+
+function addQuerySchema(operation, schema) {
+  if (schema.type !== "object" || !isRecord(schema.properties) || hasOwn(schema, "$defs")) {
+    operation["x-uf-query-schema"] = schema;
+    return;
+  }
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const parameters = Object.keys(schema.properties).map((name) => ({
+    name,
+    in: "query",
+    required: required.has(name),
+    schema: schema.properties[name],
+  }));
+  operation.parameters = [...(operation.parameters ?? []), ...parameters];
+}
+
+function stripDialect(value) {
+  if (Array.isArray(value)) return value.map(stripDialect);
+  if (!isRecord(value)) return value;
+  const out = {};
+  for (const key of Object.keys(value)) {
+    if (key === "$schema") continue;
+    out[key] = stripDialect(value[key]);
+  }
+  return out;
+}
+
+function openApiPath(routePath) {
+  return routePath
+    .split("/")
+    .map((segment) => {
+      if (!segment.startsWith(":")) return segment;
+      return `{${segment.endsWith("*") ? segment.slice(1, -1) : segment.slice(1)}}`;
+    })
+    .join("/");
+}
+
+function pathParameters(record) {
+  const params = record.params ?? paramsFromPath(record.path);
+  return params.map((param) => {
+    const parameter = {
+      name: param.name,
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    };
+    if (param.catchAll) {
+      parameter.description = "Catch-all route segment, slash-separated in the URL.";
+    }
+    return parameter;
+  });
+}
+
+function paramsFromPath(routePath) {
+  return routePath
+    .split("/")
+    .filter((segment) => segment.startsWith(":"))
+    .map((segment) => ({
+      name: segment.endsWith("*") ? segment.slice(1, -1) : segment.slice(1),
+      catchAll: segment.endsWith("*"),
+    }));
+}
+
+function operationId(record, method) {
+  const name = `${method.toLowerCase()} ${record.path}`;
+  return name
+    .replaceAll(/[^a-zA-Z0-9]+/g, " ")
+    .trim()
+    .replaceAll(/ ([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+}
+
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function errorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}

package/internal/routes.js

@@ -78,6 +78,52 @@ export const LAYOUT_PROP_NAMES = Object.freeze(["children", "params"]);
 const PAGE_EXTENSIONS = [".js", ".jsx", ".mdx"];
 const MODULE_EXTENSIONS = [".js", ".jsx"];
 
+/** Application targets the route scanner knows how to select files for. */
+export const ROUTE_TARGETS = Object.freeze(["web", "native", "ios", "android"]);
+
+const TARGET_VARIANTS = Object.freeze({
+  web: ["web", null],
+  native: ["native", null],
+  ios: ["ios", "native", null],
+  android: ["android", "native", null],
+});
+
+/**
+ * The route target a loaded `uf.config.js` and an optional CLI flag describe.
+ *
+ * `react-native` is accepted as the config-shaped spelling of the same target
+ * `uf build --target native` selects. The default follows the framework
+ * preset rather than the target list: uf's default list names both web and
+ * React Native, so the list is a promise the project should keep satisfying,
+ * not the one build to run when none was requested.
+ */
+export function resolveRouteTarget(config = {}, requested = null) {
+  const app = config.app ?? {};
+  const named =
+    requested == null || requested === ""
+      ? app.framework === "react-native"
+        ? "native"
+        : "web"
+      : requested === "react-native"
+        ? "native"
+        : requested;
+  if (!ROUTE_TARGETS.includes(named)) {
+    throw new Error(
+      `uf: ${JSON.stringify(named)} is not an application target; choose web, native, ios or android`,
+    );
+  }
+  const declared = app.targets;
+  if (Array.isArray(declared)) {
+    const needs = named === "web" ? "web" : "react-native";
+    if (!declared.includes(needs)) {
+      throw new Error(
+        `uf: --target ${named} needs app.targets to include ${JSON.stringify(needs)}`,
+      );
+    }
+  }
+  return named;
+}
+
 /** Deepest directory nesting the scan will follow. */
 const MAX_DEPTH = 32;
 
@@ -254,6 +300,7 @@ const MAX_DEPTH = 32;
  * about.
  *
  * @param {string} appRoot absolute path of the router root (`app/`)
+ * @param {{target?: "web" | "native" | "ios" | "android"}} [options]
  * @returns {{
  *   routes: Route[],
  *   handlers: Handler[],
@@ -262,7 +309,8 @@ const MAX_DEPTH = 32;
  *   errors: ErrorBoundary[],
  * }}
  */
-export function scanRoutes(appRoot) {
+export function scanRoutes(appRoot, options = {}) {
+  const target = resolveRouteTarget({}, options.target ?? "web");
   const routes = [];
   const handlers = [];
   const middleware = [];
@@ -283,7 +331,7 @@ export function scanRoutes(appRoot) {
     // 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,
     // so one found here is a file nothing would ever open.
-    const strayDefault = findModule(directory, RESERVED.default, PAGE_EXTENSIONS);
+    const strayDefault = findModule(directory, RESERVED.default, PAGE_EXTENSIONS, target);
     if (strayDefault != null) {
       throw new Error(
         `${strayDefault}: \`$default.js\` is what a \`@slot\` renders when the URL says ` +
@@ -293,7 +341,7 @@ export function scanRoutes(appRoot) {
       );
     }
 
-    const ownLayout = findModule(directory, RESERVED.layout, MODULE_EXTENSIONS);
+    const ownLayout = findModule(directory, RESERVED.layout, MODULE_EXTENSIONS, target);
     const nextLayouts = ownLayout ? [...layouts, ownLayout] : layouts;
     if (depth === 0) {
       rootLayouts = nextLayouts;
@@ -305,7 +353,7 @@ export function scanRoutes(appRoot) {
     // `nextLayouts.length` is therefore the count taken after the own layout is
     // added, not before. A segment with a loading file and no layout of its own
     // still gets a boundary — it just shares its parent's frame.
-    const ownLoading = findModule(directory, RESERVED.loading, MODULE_EXTENSIONS);
+    const ownLoading = findModule(directory, RESERVED.loading, MODULE_EXTENSIONS, target);
     const nextLoading = ownLoading
       ? [...loading, { above: nextLayouts.length, module: ownLoading }]
       : loading;
@@ -316,7 +364,7 @@ export function scanRoutes(appRoot) {
     // 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 ownTemplate = findModule(directory, RESERVED.template, MODULE_EXTENSIONS, target);
     const nextTemplates = ownTemplate
       ? [...templates, { above: nextLayouts.length, module: ownTemplate }]
       : templates;
@@ -339,6 +387,7 @@ export function scanRoutes(appRoot) {
           segments,
           ownLayout,
           nextLayouts.length,
+          target,
           depth,
         ),
       ];
@@ -347,12 +396,12 @@ export function scanRoutes(appRoot) {
     // A middleware guards this directory and everything below it, whether or
     // not this directory is itself a route: `app/dashboard/$middleware.js`
     // with no `$page.js` beside it still guards `/dashboard/settings`.
-    const ownMiddleware = findModule(directory, RESERVED.middleware, MODULE_EXTENSIONS);
+    const ownMiddleware = findModule(directory, RESERVED.middleware, MODULE_EXTENSIONS, target);
     if (ownMiddleware) {
       middleware.push({ path: routeFromSegments(segments).path, module: ownMiddleware });
     }
 
-    const page = findModule(directory, RESERVED.page, PAGE_EXTENSIONS);
+    const page = findModule(directory, RESERVED.page, PAGE_EXTENSIONS, target);
     if (page) {
       const { path: routePath, pattern, params } = routeFromSegments(segments);
       routes.push({
@@ -370,7 +419,7 @@ export function scanRoutes(appRoot) {
     // A handler answers the request itself, so it takes no layouts and is not
     // MDX. It may sit beside a page: `/feed` can render for a browser and
     // `/feed.xml` answer for a reader, and both are the same directory tree.
-    const handler = findModule(directory, RESERVED.route, MODULE_EXTENSIONS);
+    const handler = findModule(directory, RESERVED.route, MODULE_EXTENSIONS, target);
     if (handler) {
       const { path: routePath, pattern, params } = routeFromSegments(segments);
       handlers.push({ path: routePath, pattern, params, module: handler });
@@ -380,7 +429,7 @@ export function scanRoutes(appRoot) {
     // `app/guide/$not-found.js` was never looked for and a reader who
     // followed a stale link into the manual was answered by the site's root
     // 404, outside the manual's own layout. See ubugeeei-prod/uf#263.
-    const ownNotFound = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS);
+    const ownNotFound = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS, target);
     if (ownNotFound) {
       notFound.push({
         path: routeFromSegments(segments).path,
@@ -392,7 +441,7 @@ export function scanRoutes(appRoot) {
 
     // `errors` is the boundaries a project declares, not failures that
     // happened: one entry per directory holding an `$error.js`.
-    const ownError = findModule(directory, RESERVED.error, MODULE_EXTENSIONS);
+    const ownError = findModule(directory, RESERVED.error, MODULE_EXTENSIONS, target);
     if (ownError) {
       errors.push({
         path: routeFromSegments(segments).path,
@@ -495,10 +544,11 @@ export function scanRoutes(appRoot) {
  * @param {ReadonlyArray<string>} segments the declaring segments, for the URL
  * @param {?string} ownLayout the declaring segment's own layout, or `null`
  * @param {number} above how many layouts are outside the slot
+ * @param {"web" | "native" | "ios" | "android"} target application target
  * @param {number} depth nesting depth, against `MAX_DEPTH`
  * @returns {Slot}
  */
-function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth) {
+function scanSlot(parent, directoryName, name, segments, ownLayout, above, target, depth) {
   const directory = path.join(parent, directoryName);
   if (LAYOUT_PROP_NAMES.includes(name)) {
     throw new Error(
@@ -525,7 +575,7 @@ function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth
   }
 
   const routes = [];
-  const defaultPage = findModule(directory, RESERVED.default, PAGE_EXTENSIONS);
+  const defaultPage = findModule(directory, RESERVED.default, PAGE_EXTENSIONS, target);
 
   const walkSlot = (current, currentSegments, layouts, atSlotRoot, currentDepth) => {
     if (currentDepth > MAX_DEPTH) return;
@@ -534,7 +584,8 @@ function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth
     // is left of parallel routes; see the issue.
     for (const role of [RESERVED.notFound, RESERVED.error, RESERVED.loading, RESERVED.template]) {
       const found =
-        findModule(current, role, MODULE_EXTENSIONS) ?? findModule(current, role, PAGE_EXTENSIONS);
+        findModule(current, role, MODULE_EXTENSIONS, target) ??
+        findModule(current, role, PAGE_EXTENSIONS, target);
       if (found != null) {
         throw new Error(
           `${found}: a \`@slot\` renders a page and the layouts inside the slot, and has no ` +
@@ -546,7 +597,7 @@ function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth
       }
     }
     for (const role of [RESERVED.route, RESERVED.middleware]) {
-      const found = findModule(current, role, MODULE_EXTENSIONS);
+      const found = findModule(current, role, MODULE_EXTENSIONS, target);
       if (found != null) {
         throw new Error(
           `${found}: a \`@slot\` renders inside the page at a URL and answers no request of its ` +
@@ -559,15 +610,16 @@ function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth
     // One default per slot, at the slot. A deeper one would be a second answer
     // to a question that is asked once — the URL either addressed this slot or
     // it did not.
-    if (!atSlotRoot && findModule(current, RESERVED.default, PAGE_EXTENSIONS) != null) {
+    const nestedDefault = findModule(current, RESERVED.default, PAGE_EXTENSIONS, target);
+    if (!atSlotRoot && nestedDefault != null) {
       throw new Error(
-        `${findModule(current, RESERVED.default, PAGE_EXTENSIONS)}: a \`@slot\` has one ` +
+        `${nestedDefault}: a \`@slot\` has one ` +
           `\`$default.js\`, directly inside \`${directoryName}\`, and this one is deeper, so ` +
           "nothing would ever render it.",
       );
     }
 
-    const layoutHere = findModule(current, RESERVED.layout, MODULE_EXTENSIONS);
+    const layoutHere = findModule(current, RESERVED.layout, MODULE_EXTENSIONS, target);
     const nextLayouts = layoutHere ? [...layouts, layoutHere] : layouts;
 
     const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) =>
@@ -589,12 +641,13 @@ function scanSlot(parent, directoryName, name, segments, ownLayout, above, depth
           currentSegments,
           layoutHere,
           nextLayouts.length,
+          target,
           currentDepth,
         ),
       ];
     }
 
-    const page = findModule(current, RESERVED.page, PAGE_EXTENSIONS);
+    const page = findModule(current, RESERVED.page, PAGE_EXTENSIONS, target);
     if (page) {
       const { path: routePath, params } = routeFromSegments(currentSegments);
       routes.push({
@@ -647,13 +700,16 @@ function isDirectory(candidate) {
   }
 }
 
-function findModule(directory, stem, extensions) {
-  for (const extension of extensions) {
-    const candidate = path.join(directory, stem + extension);
-    try {
-      if (statSync(candidate).isFile()) return candidate;
-    } catch {
-      // keep looking
+function findModule(directory, stem, extensions, target = "web") {
+  for (const variant of TARGET_VARIANTS[target] ?? TARGET_VARIANTS.web) {
+    for (const extension of extensions) {
+      const fileName = variant == null ? `${stem}${extension}` : `${stem}.${variant}${extension}`;
+      const candidate = path.join(directory, fileName);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // keep looking
+      }
     }
   }
   return null;

package/internal/rsc.js

@@ -47,13 +47,12 @@ export const RSC_MANIFEST_ENV = "UF_RSC_MANIFEST";
 /**
  * The manifest schema this understands.
  *
- * Version 1 published the client boundaries and nothing that said which
- * modules sat *above* one, so it cannot answer the question this module asks.
- * An older manifest is therefore refused rather than read optimistically: a
- * missing `proximity` would read as `undefined`, compare unequal to
- * `"reaches-boundary"`, and quietly drop every route from the client bundle.
+ * Version 3 lets client boundaries name package specifiers as well as project
+ * paths. An older manifest is therefore refused rather than read
+ * optimistically: it cannot know a route imports a package client module, and
+ * quietly dropping that route would be the worst possible answer.
  */
-const SUPPORTED_VERSION = 2;
+const SUPPORTED_VERSION = 3;
 
 /**
  * Read the RSC manifest, or `null` when there is nothing usable to read.

package/package.json

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